SGL Core Reference¶

SGL divided into two components–sgl.lib and sgl.core. sgl.core is the part of the library that provides the low-level drawing commands, similar to what you might find built into BlitzBasic or Processing. While ideally you should be able to spend most of your time in sgl.lib, it is essential to use sgl.core to make even the simplest SGL program.

To import sgl.core, currently this is all that is required:

import sgl

Then, to call any of the functions defined in sgl.core, simply prefix them with sgl., such as this:

sgl.init(640, 480)
graphic = sgl.load_image("smiley.png")

Warning

This may change in the future. I may make it so to import sgl.core, you must do it like this:

import sgl.core as sgl

The benefits of this approach:

It will make the internal structure of the library easier to maintain
It will make it more obvious that sgl.core is actually called sgl.core.

The detriments of this approach:

It is more typing for little benefit for the end-user.
The user must explicitly rename sgl.core to sgl to keep their command invocations short.

I still haven’t made up my mind which approach to take. Keep in mind you may have to change your import statements later. The command invocation will remain the same regardless, though–it is just the importing syntax that may change.

Concepts¶

Philosophy¶

Most of sgl.core is fairly simple–it is a non-object-oriented module with various functions. This may irritate people who like object-oriented programming, and does create some clumsiness. For example, to get the width of a drawing surface, you cannot do something like this:

graphic = sgl.load_image("smiley.png")
print(graphic.width)

You must instead do this:

graphic = sgl.load_image("smiley.png")
with sgl.with_buffer(graphic):
   print(sgl.get_width())

People coming to SGL from non-object-oriented languages, like BlitzBasic, may be used to this, but this will undoubtedly bother Python programmers. I assure you, however, this is an intentional choice. In SGL, you have the freedom to choose how you want to program your game–whether you want to use object-oriented programming or not, and even how you organize the objects and classes of your game. sgl.lib is but one approach of organizing classes to wrap the internals of SGL. You can easily make your own if you wish, and I encourage you to do so.

I feel like existing Python game development frameworks are a little too dogmatic in how they force a certain structure on your programs, and I want to avoid that at all costs, even if my approach is a bit excessive. If you can wrap your head around this philosophy, most of sgl.core should make sense to you.

Fake types¶

In the function reference, you may see references to types such as “SGL Surface” or “SGL Sound.” These are not real types, however–whenever a function claims to accept or return values of these types, in reality, they are dealing with classes of whatever the current backend is. So, if you’re using the Pygame backend, and you examine the type of an “SGL Surface”, you will find that it is, in reality, a pygame.Surface.

So, hypothetically, there’s nothing stopping you from calling pygame.Surface commands on an SGL surface, like this:

graphic = sgl.load_image("smiley.png")
graphic.set_at((3, 3), (255, 0, 0))

Please don’t do this, though. For one, this will obviously not work when different backends are introduced. And also, I may eventually actually wrap SGL Surfaces and such in classes like sglSurface or something, which will make your code broken on all backends.

Ideally, your code should be completely ignorant of what backend SGL is currently using. This’ll make your game/program more portable, which is one of the main points of SGL existing.

Color arguments¶

Color arguments in SGL are kind of ridiculously flexible, and take some influence from how Processing works.

Whenever you see an argument named *colors, it can accept the values in the following formats:

number - If you specify a single value as a color, it will specify shade of gray with that value used for the R, G, and B values of that color.
number, number - If you specify to values as a color, the first number will specify the shade of gray, as it would with a single number, but the second number will specify the transparency of that shade of gray.
number, number, number - If you specify three values, it will be interpreted as a normal RGB color.
number, number, number, number - If you specify for values, it will be interpreted as a normal RGBA color.
tuple/list - If you specify color as a tuple or list, it will be unpacked and interpreted as the arguments would.

In addition, for each number, the following rules apply:

If the number is an integer, it will be interpreted as a normal RGB value that ranges from 0 to 255.
If any numbers outside of this range, it will be clamped within that range.
If the number is a float, it will be interpreted as a percentage of 255. So, for example, 0.5 would be half of 255.

This is perhaps a little complicated, but allows you to do some very convenient things. For example, if you want to clear the screen with 50% gray, it is as simple as doing this:

sgl.clear(0.5)

If you want to make a surface that is black and 75% transparent, you can do this:

surface = sgl.make_surface(320, 32, 0.0, 0.75)

And, if you feel it is confusing that the color data is getting mixed in with the rest of their arguments, you can pass in tuples as well:

surface = sgl.make_surface(320, 32, (0.0, 0.75))

And, of course, you can use plain RGB values for everything:

sgl.clear(100, 175, 93)

Function reference¶

This is a reference of every single function in sgl.core. It is not complete yet, but all of the most essential functions have been documented in some detail. Hopefully this is helpful.

Base functions¶

These functions have to do with the base functioning of your program, and are essential for nearly everything you’d want to do with SGL.

sgl.init(width, height, scale=1, fullscreen=False, backend="pygame")¶

Must be called before any other SGL functions to initiate the drawing surface.

Parameters:	width, height (int) – Specifies the size of the display surface. scale (int) – Specifies the scaling factor. Width and height will be multiplied by this to form the actual window size. This is useful for working with small resolutions, such as 320x240. fullscreen (bool) – On desktop platforms, whether the display

should be windowed or fullscreen.

Parameters:	backend (str) – Which backend to use. Currently, the only supported option is “pygame”.

sgl.run(update=None, draw=None)¶

Starts an SGL program that automatically manages the event loop. SGL will call the specified callbacks every frame, and it is in these that you will specify your game logic.

Parameters:

update (function) – A function to call every frame to update your game’s state.
draw (function) – A function to call every frame to draw the current frame. Do not put any game logic in this function. No backends currently do this, but in the future, some might take advantage of the difference between update and draw to, for example, pause the game by calling update but not draw.

sgl.make_movie(file="", update=None, draw=None, duration=0, fps=24, realtime=False, display=True, **extra)¶

Similar to sgl.run(), but uses MoviePy to render each frame of your program to a video file or animated GIF.

Parameters:

file (str) – The filename of the movie you wish to output.
update, draw (function) – Works the same as with sgl.run().
duration (number) – The amount of your program’s execution you want to record, in seconds.
fps (number) – What the frame rate of the resulting video will be. make_movie will force your program’s frame rate to match with sgl.set_fps_limit().
realtime (boolean) – If the video renders faster than the frame rate you specify, this will slow down the speed of the video rendering to match. This is useful when you have “display” enabled and you want to, say, use your program while recording it. By default it is false.
display (boolean) – Whether to draw the current frame to the screen, in addition to rendering into the video file. Useful if you want to interact with your program as it is rendering to video.
extra (various) – Additional keyword arguments are passed to MoviePy’s write_videofile or write_gif functions. You can use this to specify additional settings about which codecs to use and such.

sgl.set_fps_limit(fps)¶

Sets the highest frame rate your program will allow. More specifically, it makes your program assume that the frame rate is always this value, as opposed to what it is in reality. This can make programming animation more convenient, but comes with some side effects–such as that, if the frame rate of your program drops, it will start running in slow motion.

Parameters:	fps (int) – The desired framerate. Set to 0 to disable framerate limiting.

sgl.get_fps_limit()¶

Gets the framerate limit. If there is no framerate limiting, will return 0.

Returns:	The framerate limit
Return type:	int

sgl.get_fps()¶

Gets the current framerate. This will return the actual frame rate, even if the limit has been set with sgl.set_fps_limit().

Returns:	The current framerate
Return type:	float

sgl.get_scale()¶

Gets the window’s scaling factor. SGL automatically takes into account the scaling factor when returning, say, mouse coordinates, so there shouldn’t be any reason to call this–it’s just for completeness sake.

Currently, is no setting the scaling factor–if you want to make a program in which the scaling factor appears to change, use surfaces and end the scaling abilities of sgl.blit() to simulate this. This functionality may be added in the future, though.

Returns:	The current scaling factor
Return type:	int

sgl.has(ability)¶

Returns whether the current backend has a given ability. The abilities are specified in the enum-like class sgl.abilities. There are currently only four abilities you can test for:

sgl.abilities.software: Whether the current backend is powered by software rendering, and thus will be slow at special effects such as rotating and scaling.
sgl.abilities.numpy: Whether the current backend supports exporting and importing surfaces to NumPy arrays.
sgl.abilities.save_buffer: Whether the current backend supports saving surfaces to image files.

The Pygame backend supports all of these.

Parameters:	ability (int) – The ability to test
Returns:	Whether the current backend supports this ability
Return type:	bool

sgl.set_title(title)¶

Sets the text in the title bar of the current window.

Parameters:	title (str) – The text to put in the title bar

sgl.get_title(title)¶

Gets the text currently in the title bar of the current window.

Returns:	The text in the title bar
Return type:	str

sgl.get_actual_screen_width()¶

Gets the width of the current window after applying the scaling factor. You should not need to get this. I should probably get rid of this function.

Returns:	The window width
Return type:	int

sgl.get_actual_screen_height()¶

Gets the height of the current window after applying the scaling factor. You should not need to get this. I should probably get rid of this function.

Returns:	The window height
Return type:	int

sgl.get_dt()¶

Gets delta time, or the time that has passed since the last frame is been rendered. If you do not have framerate limiting enabled for your program, you must multiply every animation value by this value if you expect your program to work consistently on different types of computers.

Unlike some other game libraries, this value is returned in seconds, not milliseconds.

Returns:	The time that has passed since the last frame in seconds
Return type:	float

sgl.is_running()¶

Returns whether your program is running. Useful for when you are manually managing the event loop, and you want your program to end under the same conditions an automatic SGL program would.

Returns:	Whether your program is running
Return type:	Bool

sgl.end()¶: Halts execution of the program, and closes the window.

Drawing commands¶

These commands have to do with drawing shapes.

sgl.set_smooth(smooth)¶

Sets whether lines for shapes should be anti-aliased or not. Currently no backend supports this.

Parameters:	smooth (bool) – Whether anti-aliasing should be enabled

sgl.get_smooth()¶

Returns whether anti-aliasing is enabled or not.

Returns:	Whether anti-aliasing is enabled
Return type:	bool

sgl.set_fill(*color)¶: Sets the color with which shapes are filled. Also affects what color fonts are rendered in.

sgl.get_fill()¶

Gets the current fill color.

Returns:	The current fill color, or `None` if fill is disabled
Return type:	tuple

sgl.set_stroke(*color)¶: Sets the color in which shapes are outlined.

sgl.get_stroke()¶

Gets the current stroke color.

Returns:	The current stroke color, or `None` if stroke is disabled
Return type:	tuple

sgl.set_stroke_weight(weight)¶: Sets how thick the lines outlining shapes will be. Setting this to 0 will disable stroke rendering.

sgl.get_stroke_weight()¶

Gets the current stroke weight.

Returns:	The current fill weight
Return type:	int

sgl.no_stroke()¶: Turns off stroke rendering.

sgl.no_fill()¶: Turns off fill rendering.

sgl.push()¶: Pushes the current graphics state to the stack. So, the next time you call sgl.pop, it will restore this state. You can use this to change the drawing colors and what current surface is, and reset them later.

sgl.pop()¶: Pops the current graphics state from the stack. This will make all the drawing settings return to what they were the last time sgl.push was called.

sgl.with_state()¶: A context manager that saves the current drawing state and restores it when the enclosed operations are finished. Useful to avoid manually having to call sgl.push and sgl.pop.

sgl.clear(*color)¶: Completely fills the current surface with the specified color.

sgl.draw_line(x1, y1, x2, y2)¶: Draw the line between the specified coordinates.

sgl.draw_rect(x, y, width, height)¶: Draws a rectangle in the specified area.

sgl.draw_ellipse(x, y, width, height, from_center=False)¶: Draws an ellipse in the specified area.

sgl.draw_circle(x, y, radius, from_center=True)¶: Draws a circle in the specified area.

Text commands¶

These commands have to do with rendering text.

sgl.set_font_smooth(smooth)¶: Specifies whether text is anti-aliased or not.

sgl.get_font_smooth()¶

Returns whether text is anti-aliased or not.

Returns:	Whether font antialiasing is enabled
Return type:	bool

sgl.load_font(file, size)¶

Loads a font from a font file in your program folder.

Returns:	The loaded font
Return type:	SGL font object

sgl.load_system_font(font_name, size)¶

Loads a font from the user’s system via the font’s name.

Returns:	The loaded font
Return type:	SGL font object

sgl.set_font(font)¶: Sets what font is used for all future drawing operations.

sgl.draw_text(text, x, y)¶: Draws the specified text at the specified coordinates.

sgl.get_text_width(text)¶

Gets how wide the specified string will be when rendered in the current font.

Returns:	The width of the rendered text
Return type:	int

sgl.get_text_height(text="")¶

Gets how tall the specified string will be when rendered in the current font. Usually will just return the height of the current font.

Returns:	The height of the text
Return type:	int

Image commands¶

These commands have to do with loading images and stuff.

sgl.set_transparent_color(*color)¶: Sets what color will be considered transparent in images without an alpha channel. By default, this color is set to (255, 0, 255), or “magic magenta.”

sgl.load_image(file, use_transparent_color=True)¶

Loads an image without an alpha channel from the hard drive.

Returns:	A surface containing the image loaded
Return type:	SGL surface

sgl.load_alpha_image(file)¶

Loads an image with an alpha channel from the hard drive.

Returns:	A surface containing the image loaded
Return type:	SGL surface

Surface commands¶

These commands have to do with using surfaces and changing the current drawing buffer.

sgl.blit(thing, x, y, alpha=255, flip_v=False, flip_h=False, angle=0, width=None, height=None, scale=1, a_x=0, a_y=0, src_x=0, src_y=0, src_width=None, src_height=None, blend_mode=0, pretty=False)¶

Draws one surface to another. This function is kind of the motherlode of SGL, and provides most of the library’s drawing functionality.

Since this function takes so many arguments, it is recommended you use keyword arguments for everything beyond x and y. For example, a typical call to this function might look like this:

sgl.blit(self.player, 16, 16, flip_h=True, angle=45, a_x=0.5, a_y=0.5)

Parameters:

thing (SGL surface) –
The thing that should be drawn (or blitted) to the current surface.

Is an SGL surface value.
x, y (int/float) –
Specifies the coordinates on the current surface that thing should be drawn.

Currently, passing in floats will just result in them being rounded to integers.
alpha (int/float) –
A number specifying how transparent thing should be drawn.

If it is an integer, this should be a value between 0 and 255, with 0 being invisible and 255 being completely opaque.

If it is a float, this should be a value between 0.0 and 1.0, with zero being invisible and 1.0 being completely opaque.
flip_v, flip_h (bool) –
Specifies whether thing should be horizontally or vertically flipped.

Setting width or height to negative values will also flip a graphic.
angle (int) –
The angle to which thing should be rotated. The angle should be in degrees, and should be a value between 0 to 360 (although the code currently does not check this. It probably should).

Note that on software renderers, such as Pygame, rotation is fairly slow. You can rotate a few graphics, such as the player graphic, in real time, but it is recommended you cache rotated sprites if you plan to rotate many things at once.
width, height (int) –
Specifies the width and height to resize thing to.

If either of these values is not specified, it will be filled in with the original width/height of thing.

If either of these values is 0, thing will not be drawn.

If either is negative, thing will be drawn backwards in whatever direction resizing it takes.
scale (float) –
Enables you to scale thing by a ratio, keeping its aspect ratio. 1.0, the default, will draw thing at its normal size, 0.5 will draw it half as big, and so on.

This can be combined with width and height, and is applied after those values are calculated.
a_x, a_y (int/float) –
Specifies the anchor point of thing–the coordinates of the graphic that is considered (0, 0). Useful in conjunction with angle to rotate about different points of the graphic than the top left corner.

If these values are integers, they will be interpreted as exact coordinates on thing.

If these values are floats, they will be interpreted as a percentage of the size of thing. (As in, setting both anchor points to 0.5 will make the anchor point the center of the image.)
src_x, src_y, src_width, src_height (int) –
Makes the function apply to the specified rectangle of thing. This is applied before the other functions are. This is a convenience to avoid having to do sgl.get_chunk whatever you want to draw a small chunk of a larger image.

On hardware accelerated backends, this may be faster than using sgl.get_chunk.
blend_mode (int) –
Specifies the blending mode to use when drawing thing. Should be a constant from sgl.blend.

Currently, the only available blending values are:
- sgl.blend.add - Adds the colors of thing‘s pixels to the pixels behind it. So, black pixels will become transparent, white pixels will stay white, and everything in between will make the image behind slightly brighter.
- sgl.blend.subtract - Subtracts the colors of thing‘s pixels from the pixels behind it. So, black pixels will become transparent, and white pixels will invert the background to certain degree.
- sgl.blend.multiply - Multiply the colors of thing‘s pixels from the pixels behind it. So, white pixels will become transparent, black pixels will stay black, and everything else will be make the image behind slightly darker.
pretty (boolean) –
Specifies whether the results of scaling and/or rotating thing should be smoothed out or not.

This will slow down rendering in most cases.

sgl.blitf(thing, x, y)¶

A lightweight version of sgl.blit that does not perform any special effects on the surface being drawn. May be slightly faster.

Parameters:	thing (SGL surface) – The thing that should be drawn to the current surface. x, y (int) – Specifies the accordance on the current surface that `thing` should be drawn.

sgl.make_surface(width, height, *color)¶

Makes a new blank surface of the specified color. If no color specified, the new surface will be blank and transparent.

Returns:	The created surface
Return type:	SGL surface

sgl.get_chunk(x, y, width, height)¶

Takes a chunk out of the current surface and returns it as a new copy surface. Useful for separating out, say, individual frames from spritesheets.

Parameters:	x, y (int) – The coordinates to start extracting width, height (int) – The width and height of the rectangle to extract
Returns:	The extracted surface
Return type:	SGL surface

sgl.set_clip_rect(x, y, width, height)¶: Sets the clipping rectangle–makes it so all future rendering operations will only affect the specified rectangle of the current surface.

sgl.get_clip_rect()¶

Returns the size of the current clipping rectangle.

Returns:	A four element tuple, or None
Return type:	tuple

sgl.no_clip_rect()¶: Turns off rendering clipping.

sgl.set_buffer(surface)¶

Sets which surface is the drawing buffer–the surface on which all future drawing operations will take place. You can also think of this as the “current surface,” and many parts of the documentation refer to it like this).

Parameters:	surface (SGL surface) – The surface that will become the current surface

sgl.reset_buffer()¶: Sets the drawing buffer to refer to the screen buffer. If you manage the stack correctly, you shouldn’t need to use this, but this is here just in case.

sgl.with_buffer(buffer)¶

A context manager that makes all enclosed drawing operations apply to a given buffer. Useful to avoid manually dealing with the stack.

Parameters:	buffer (SGL buffer) – The buffer to draw on

sgl.get_width()¶

Gets the width of the current surface.

Returns:	The width of the current surface, in pixels
Return type:	int

sgl.get_height()¶

Gets the height of the current surface.

Returns:	The height of the current surface, in pixels
Return type:	int

sgl.save_image(file)¶

Saves the image in the current surface to the specified filename.

Parameters:	file (str) – The filename of the image to save to. The extension will determine the file type.

sgl.to_numpy()¶

Exports the current surface as a NumPy array. On some back ends, such as Pygame, this might return a “live” NumPy array that is linked the original surface–as in changing the array will instantly change the surface. This is much more efficient than the alternative, but can be unexpected.

Returns:	The pixel data of the current surface, in a three-dimensional array
Return type:	NumPy array

sgl.from_numpy(array)¶

Creates a new surface from a NumPy array.

Parameters:	array (NumPy array) – A three-dimensional array consisting of RGB values.
Returns:	The surface represented by the array
Return type:	SGL surface

Special Effect commands¶

These commands do cool special effects.

sgl.invert(surface=None)¶

Inverts the colors of either the current surface or whatever surface is passed in.

Returns:	A new surface, with the effect applied, or nothing
Return type:	SGL surface

sgl.grayscale(surface=None)¶

Turns to grayscale either the current surface or whatever surface is passed in.

Returns:	A new surface, with the effect applied, or nothing
Return type:	SGL surface

Audio functions¶

These functions have to do with playing music and sound effects.

sgl.load_sound(file)¶

Loads a sound file from the hard drive.

Returns:	An object representing the loaded sound
Return type:	SGL sound

sgl.play_sound(sound, volume=1.0, loops=0)¶

Plays a previously loaded sound.

Parameters:

sound (SGL sound) – The sound object to play
volume (float) – The volume to play the sound at, specified as a float. (So, 1.0 would be full volume, 0.5 would be half volume, and so on.)
loops (int) – How many times to loop playback of the sound. If this is 0, the default, the sound will only play once. If it is -1, it will play forever, until sgl.stop_sound is called on it.

sgl.stop_sound(sound)¶

Stops the specified sound.

Parameters:	sound (SGL sound) – The sound object to stop

sgl.stop_all_sounds()¶: Stops all currently playing sounds.

sgl.is_sound_playing(sound)¶

Determines whether the specified sound is currently playing.

Parameters:	sound (SGL sound) – The sound object to query
Returns:	Whether the sound is playing
Return type:	bool

sgl.play_music(file, volume=1.0, loops=-1)¶

Plays, by default, infinitely looping background music. Music, unlike sounds, do not need to be loaded in advance. They are loaded when you call this function. Because of this, only one music track can be playing at once.

Parameters:	file (str) – The filename of the music to play volume (float) – The volume to play the music at, specified as a float. (So, 1.0 would be full volume, 0.5 would be half volume, and so on.) loops (int) – How many times to loop playback of the music. By default, this is -1, which will look the music forever, until `sgl.stop_music()` is called.

sgl.pause_music()¶: Pauses the currently playing piece of music. This is different from sgl.stop_music() in that you can later call sgl.resume_music() to resume the song from the exact point at which you paused it. With stopping, you have no choice but to restart the song.

sgl.resume_music()¶: Resumes a piece of music that has been paused with sgl.pause_music().

sgl.set_music_volume(volume)¶

Sets the volume of the currently playing music.

Parameters:	volume (float) – The volume to play the music at, specified as a float. (So, 1.0 would be full volume, 0.5 would be half volume, and so on.)

sgl.stop_music()¶: Stops the currently playing music. This music will not be able to be resumed with sgl.pause_music().

sgl.is_music_playing()¶

Returns whether any music is currently playing.

Returns:	Whether any music is playing
Return type:	bool

Input commands¶

These commands have to do with getting input.

sgl.add_input(type)¶

Initializes support for a specified type of input.

Parameters:	type (int) – The type of input to add. Should be a constant from `sgl.input`.

sgl.supports_input(type)¶

Returns whether the backend supports the specified input type. Might be integrated into sgl.has() later.

Parameters:	type (int) – The type of input to test. Should be a constant from `sgl.input`.
Returns:	Whether the specified type of input is supported by this backend
Return type:	bool

sgl.remove_input(type)¶

Removes support for a specified type of input. It does not matter whether this input is real or fake–it will remove it regardless.

Parameters:	type (int) – The type of input to remove. Should be a constant from `sgl.input`.

sgl.has_input(type)¶

Returns whether a specified input type is handled or not. Intentionally does not distinguish between real and fake inputs.

Parameters:	type (int) – The type of input to test. Should be a constant from `sgl.input`.
Returns:	Whether the specified type of input is currently handled
Return type:	bool

sgl.on_key_down(key)¶

Briefly returns True on the frame a keyboard key is pressed down.

Parameters:	key (int) – The key code of the key to test. Should be a constant from `sgl.key`.
Returns:	Whether a key has just been pressed down
Return type:	bool

sgl.on_key_up(key)¶

Briefly returns True on the frame a keyboard key is released.

Parameters:	key (int) – The key code of the key to test. Should be a constant from `sgl.key`.
Returns:	Whether a key has just been released
Return type:	bool

sgl.is_key_pressed(key)¶

Returns True if the specified keyboard key is currently pressed.

Parameters:	key (int) – The key code of the key to test. Should be a constant from `sgl.key`.
Returns:	Whether a key is currently down
Return type:	bool

sgl.get_keys_pressed()¶

Returns a list of all the keyboard keys currently pressed.

Returns:	A list of all pressed keys
Return type:	list of ints

sgl.get_letters_pressed()¶

Returns a string containing all the characters typed in the last frame. Handles capitalizing letters and changing characters when shift is pressed.

Returns:	The text typed in the last frame
Return type:	str

sgl.show_mouse()¶: Shows the system mouse cursor.

sgl.hide_mouse()¶: Hides the system mouse cursor.

sgl.get_mouse_x()¶

Returns what the mouse cursor’s x position on the current frame.

Returns:	The mouse’s x coordinates
Return type:	int

sgl.get_mouse_y()¶

Returns what the mouse cursor’s y position on the current frame.

Returns:	The mouse’s y coordinates
Return type:	int

sgl.get_prev_mouse_x()¶

Returns what the mouse cursor’s x position was on the previous frame. Exists for convenience and because when managing the event loop automatically, it is impossible for your program to retrieve this value manually.

Returns:	The mouse’s x coordinates on the previous frame
Return type:	int

sgl.get_prev_mouse_y()¶

Returns what the mouse cursor’s y position was on the previous frame.

Returns:	The mouse’s y coordinates on the previous frame
Return type:	int

sgl.on_mouse_down(button=1)¶

Briefly returns True on the frame the specified mouse button is pressed down. By default, it tests for the left mouse button–button #1. Does not intelligently determine what the left mouse button is if the user has used their system settings to swap the functions of the mouse buttons.

Parameters:	button (int) – The number of the mouse button to test. Is 1 by default.
Returns:	Whether a mouse button has just been pressed down
Return type:	bool

sgl.is_mouse_pressed(button=1)¶

Returns True if the specified mouse button is currently pressed down.

Parameters:	button (int) – The number of the mouse button to test. Is 1 by default.
Returns:	Whether a mouse button is pressed
Return type:	bool

sgl.get_mouse_buttons_pressed()¶

Returns a list of all the currently pressed mouse buttons.

Returns:	A list of all the pressed mouse buttons
Return type:	list of ints

sgl.on_joy_down(button)¶

Briefly returns True on the frame the specified joystick button is pressed down.

Parameters:	button (int) – The number of the joystick button to test
Returns:	Whether a joystick button has just been pressed down
Return type:	bool

sgl.on_joy_up(button)¶

Briefly returns True on the frame the specified joystick button is released.

Parameters:	button (int) – The number of the joystick button to test
Returns:	Whether a joystick button has just been pressed released
Return type:	bool

sgl.is_joy_pressed(button)¶

Returns True if the specified joystick button is currently pressed down.

Parameters:	button (int) – The number of the joystick button to test
Returns:	Whether a joystick button is pressed
Return type:	bool

sgl.get_joy_axis(axis)¶

Returns the value of a joystick’s given “axis”. There is usually a separate axis for each direction of each stick. For example, there might be an axis for the horizontal motion of the left stick, the vertical motion of the left stick, and axes for both on right stick. Some joysticks, however, use axes for other things as well, such as pressure sensitive buttons. Experiment to figure out which is which.

Parameters:	axis (int) – The axis to get the value from
Returns:	The value reported by the current axis
Return type:	float

sgl.get_joy_num_axes()¶

Returns the amount of axes this joystick reports having.

Returns:	The number of axes on this joystick
Return type:	int

Fake input commands¶

These commands have to do the fake input system, in which on platforms without certain types of input, such as smart phones, you can simulate unavailable input devices with the ones that are available.

Warning

I don’t think this API actually makes any sense. I might remove or change it later.

sgl.add_fake_input(type)¶: Adds a fake input. There must not be an equivalent real input defined.

sgl.got_key_down(key)¶: Simulates a key on the keyboard being pressed down.

sgl.got_key_up(key)¶: Simulates a key on the keyboard being released. If you do not call this function, SGL will think the key has been pressed down forever.

sgl.got_mouse_move(x, y)¶: Simulates the mouse moving to a new point.

sgl.got_mouse_down(button=1)¶: Simulates a mouse button being pressed.

sgl.got_mouse_up(button=1)¶: Simulates a mouse button being released. Similarly to sgl.got_key_up(), this is necessary for SGL to ever consider a mouse button released.