sge.gfx ¶

Contents

sge.gfx
- sge.gfx Classes

This module provides classes related to rendering graphics.

sge.gfx Classes ¶

sge.gfx.Color ¶

class sge.gfx.Color(value: Union[str, int, list, tuple])¶

This class stores color information.

Objects of this class support the following standard operations (where c is an object of this class):

iter(c) -- Return an iterable containing the object's red, green, blue, and alpha values, respectively.
int(c) -- Return an integer which can be interpreted as a hexadecimal representation in the form of 0xRRGGBB (where "RR" is red, "GG" is green, and "BB" is blue).
str(c) -- Return a string which indicates the English name of the color (in all lowercase) if possible, or hex_string otherwise.
c == c2 -- Equivalent to str(c) == str(c2).
c[i] -- Equivalent to tuple(c)[i].
c[i] = v -- Equivalent to converting c to list L, setting L[i] to v, and then setting the object's red, green, blue, and alpha values, respectively, to the values contained in L.

red¶: The red component of the color as an integer, where 0 indicates no red intensity and 255 indicates full red intensity.

green¶: The green component of the color as an integer, where 0 indicates no green intensity and 255 indicates full green intensity.

blue¶: The blue component of the color as an integer, where 0 indicates no blue intensity and 255 indicates full blue intensity.

alpha¶: The alpha transparency of the color as an integer, where 0 indicates full transparency and 255 indicates full opacity.

hex_string¶: An HTML hex string representation of the color. (Read-only)

Color.__init__(value: Union[str, int, list, tuple]) → None¶

Parameters:

value -- The value indicating the color represented by this object. Should be one of the following:
- One of the 16 HTML color names (case-insensitive).
- An HTML-style hex string containing 3, 4, 6, or 8 digits which indicate the red, green, blue, and alpha components of the color, respectively, as pairs of hexadecimal digits. If the string contains 3 or 4 digits, each digit is duplicated; for example, "#F80" is equivalent to "#FF8800".
- An integer which, when written as a hexadecimal number, specifies the components of the color in the same way as an HTML-style hex string containing 6 digits.
- A list or tuple indicating the red, green, and blue components, and optionally the alpha component, in that order.
If this is any type other than those specified above, TypeError is raised.

class sge.gfx.Sprite(name=None, directory='', *, width=None, height=None, transparent=True, origin_x=0, origin_y=0, fps=60, bbox_x=None, bbox_y=None, bbox_width=None, bbox_height=None)¶

This class stores images and information about how the SGE is to use those images.

What image formats are supported depends on the implementation of the SGE, but image formats that are generally a good choice are PNG and JPEG. See the implementation-specific information for a full list of supported formats.

width¶: The width of the sprite.

Note

Changing this attribute will cause the sprite to be scaled horizontally. This is a destructive transformation: it can result in loss of pixel information, especially if it is done repeatedly. Because of this, it is advised that you do not adjust this value for routine scaling. Use the image_xscale attribute of a sge.dsp.Object object instead.

height¶: The height of the sprite.

Note

Changing this attribute will cause the sprite to be scaled vertically. This is a destructive transformation: it can result in loss of pixel information, especially if it is done repeatedly. Because of this, it is advised that you do not adjust this value for routine scaling. Use the image_yscale attribute of a sge.dsp.Object object instead.

size¶: A two-part tuple containing the width and height, respectively, of the sprite. Each value in the tuple functions the same as width and height, but assigning to this value will set both to the desired size at the same time, scaling the image in one operation rather than two.

Note

Changing this attribute will cause the sprite to be scaled. This is a destructive transformation: it can result in loss of pixel information, especially if it is done repeatedly. Because of this, it is advised that you do not adjust this value for routine scaling. Use the image_xscale and image_yscale attributes of a sge.dsp.Object object instead.

transparent¶

Whether or not the image should be partially transparent, based on the image's alpha channel. If this is False, all pixels in the image will be treated as fully opaque regardless of what the image file says their opacity should be.

This can also be set to a sge.gfx.Color object, which will cause the indicated color to be used as a colorkey.

origin_x¶: The suggested horizontal location of the origin relative to the left edge of the images.

origin_y¶: The suggested vertical location of the origin relative to the top edge of the images.

fps¶: The suggested rate in frames per second to animate the image at. Can be negative, in which case animation will be reversed.

speed¶: The suggested rate to animate the image at as a factor of sge.game.fps. Can be negative, in which case animation will be reversed.

bbox_x¶: The horizontal location relative to the sprite of the suggested bounding box to use with it. If set to None, it will become equal to -origin_x (which is always the left edge of the image).

bbox_y¶: The vertical location relative to the sprite of the suggested bounding box to use with it. If set to None, it will become equal to -origin_y (which is always the top edge of the image).

bbox_width¶: The width of the suggested bounding box. If set to None, it will become equal to width - bbox_x (which is always everything on the image to the right of bbox_x).

bbox_height¶: The height of the suggested bounding box. If set to None, it will become equal to height - bbox_y (which is always everything on the image below bbox_y).

name¶: The name of the sprite given when it was created. (Read-only)

frames¶: The number of animation frames in the sprite. (Read-only)

rd¶: Reserved dictionary for internal use by the SGE. (Read-only)

Sprite.__init__(name=None, directory='', *, width=None, height=None, transparent=True, origin_x=0, origin_y=0, fps=60, bbox_x=None, bbox_y=None, bbox_width=None, bbox_height=None)¶

Parameters:

name -- The base name of the image files, used to find all individual image files that make up the sprite's animation`. One of the following rules will be used to find the images:
- The base name plus a valid image extension. If this rule is used, the image will be loaded as a single-frame sprite.
- The base name and an integer separated by either a hyphen (-) or an underscore (_) and followed by a valid image extension. If this rule is used, all images with names like this are loaded and treated as an animation, with the lower-numbered images being earlier frames.
- The base name and an integer separated by either -strip or _strip and followed by a valid image extension. If this rule is used, the image will be treated as an animation read as a horizontal reel from left to right, split into the number of frames indicated by the integer.
- If the base name is None, the sprite will be a fully transparent rectangle at the specified size (with both width and height defaulting to 32 if they are set to None). The SGE decides what to assign to the sprite's name attribute in this case, but it will always be a string.
If none of the above rules can be used, FileNotFoundError is raised.
directory -- The directory to search for image files in.

All other arguments set the respective initial attributes of the sprite. See the documentation for Sprite for more information.

sge.gfx.Sprite Methods ¶

Sprite.append_frame()¶: Append a new blank frame to the end of the sprite.

Sprite.insert_frame(frame)¶

Insert a new blank frame into the sprite.

Parameters:

frame -- The frame of the sprite to insert the new frame in front of, where 0 is the first frame.

Sprite.extend(sprite)¶

Extend this sprite with the frames of another sprite.

If the size of the frames added is different from the size of this sprite, they are scaled to this sprite's size.

Parameters:

sprite -- The sprite to add the frames of to this sprite.

Sprite.delete_frame(frame)¶

Delete a frame from the sprite.

Parameters:

frame -- The frame of the sprite to delete, where 0 is the first frame.

Sprite.get_pixel(x, y, frame=0)¶

Return a sge.gfx.Color object indicating the color of a particular pixel on the sprite.

Parameters:

x -- The horizontal location relative to the sprite of the pixel to check.
y -- The vertical location relative to the sprite of the pixel to check.
frame -- The frame of the sprite to check, where 0 is the first frame.

Sprite.get_pixels(frame=0)¶

Return a two-dimensional list of :class`sge.gfx.Color` objects indicating the colors of a particular frame's pixels.

A returned list given the name pixels is indexed as pixels[x][y], where x is the horizontal location of the pixel and y is the vertical location of the pixel.

Parameters:

frame -- The frame of the sprite to check, where 0 is the first frame.

Sprite.draw_dot(x, y, color, frame=None, *, blend_mode=None)¶

Draw a single-pixel dot on the sprite.

Parameters:

x -- The horizontal location relative to the sprite to draw the dot.
y -- The vertical location relative to the sprite to draw the dot.
color -- A sge.gfx.Color object representing the color of the dot.
frame -- The frame of the sprite to draw on, where 0 is the first frame; set to None to draw on all frames.
blend_mode -- The blend mode to use. Possible blend modes are:
- sge.BLEND_NORMAL
- sge.BLEND_RGBA_ADD
- sge.BLEND_RGBA_SUBTRACT
- sge.BLEND_RGBA_MULTIPLY
- sge.BLEND_RGBA_SCREEN
- sge.BLEND_RGBA_MINIMUM
- sge.BLEND_RGBA_MAXIMUM
- sge.BLEND_RGB_ADD
- sge.BLEND_RGB_SUBTRACT
- sge.BLEND_RGB_MULTIPLY
- sge.BLEND_RGB_SCREEN
- sge.BLEND_RGB_MINIMUM
- sge.BLEND_RGB_MAXIMUM
None is treated as sge.BLEND_NORMAL.

Sprite.draw_line(x1, y1, x2, y2, color, thickness=1, frame=None, *, anti_alias=False, blend_mode=None)¶

Draw a line segment on the sprite.

Parameters:

x1 -- The horizontal location relative to the sprite of the first end point of the line segment.
y1 -- The vertical location relative to the sprite of the first end point of the line segment.
x2 -- The horizontal location relative to the sprite of the second end point of the line segment.
y2 -- The vertical location relative to the sprite of the second end point of the line segment.
color -- A sge.gfx.Color object representing the color of the line segment.
thickness -- The thickness of the line segment.
frame -- The frame of the sprite to draw on, where 0 is the first frame; set to None to draw on all frames.
anti_alias -- Whether or not anti-aliasing should be used.
blend_mode -- The blend mode to use. Possible blend modes are:
- sge.BLEND_NORMAL
- sge.BLEND_RGBA_ADD
- sge.BLEND_RGBA_SUBTRACT
- sge.BLEND_RGBA_MULTIPLY
- sge.BLEND_RGBA_SCREEN
- sge.BLEND_RGBA_MINIMUM
- sge.BLEND_RGBA_MAXIMUM
- sge.BLEND_RGB_ADD
- sge.BLEND_RGB_SUBTRACT
- sge.BLEND_RGB_MULTIPLY
- sge.BLEND_RGB_SCREEN
- sge.BLEND_RGB_MINIMUM
- sge.BLEND_RGB_MAXIMUM
None is treated as sge.BLEND_NORMAL.

Changed in version 2.0: Repositioned the frame parameter to where the anti_alias parameter used to be.

Sprite.draw_rectangle(x, y, width, height, frame=None, *, fill=None, outline=None, outline_thickness=1, blend_mode=None)¶

Draw a rectangle on the sprite.

Parameters:

x -- The horizontal location relative to the sprite to draw the rectangle.
y -- The vertical location relative to the sprite to draw the rectangle.
width -- The width of the rectangle.
height -- The height of the rectangle.
frame -- The frame of the sprite to draw on, where 0 is the first frame; set to None to draw on all frames.
fill -- A sge.gfx.Color object representing the color of the fill of the rectangle.
outline -- A sge.gfx.Color object representing the color of the outline of the rectangle.
outline_thickness -- The thickness of the outline of the rectangle.
blend_mode -- The blend mode to use. Possible blend modes are:
- sge.BLEND_NORMAL
- sge.BLEND_RGBA_ADD
- sge.BLEND_RGBA_SUBTRACT
- sge.BLEND_RGBA_MULTIPLY
- sge.BLEND_RGBA_SCREEN
- sge.BLEND_RGBA_MINIMUM
- sge.BLEND_RGBA_MAXIMUM
- sge.BLEND_RGB_ADD
- sge.BLEND_RGB_SUBTRACT
- sge.BLEND_RGB_MULTIPLY
- sge.BLEND_RGB_SCREEN
- sge.BLEND_RGB_MINIMUM
- sge.BLEND_RGB_MAXIMUM
None is treated as sge.BLEND_NORMAL.

Changed in version 2.0: Repositioned the frame parameter to where the fill parameter used to be.

Sprite.draw_ellipse(x, y, width, height, frame=None, *, fill=None, outline=None, outline_thickness=1, anti_alias=False, blend_mode=None)¶

Draw an ellipse on the sprite.

Parameters:

x -- The horizontal location relative to the sprite to position the imaginary rectangle containing the ellipse.
y -- The vertical location relative to the sprite to position the imaginary rectangle containing the ellipse.
width -- The width of the ellipse.
height -- The height of the ellipse.
frame -- The frame of the sprite to draw on, where 0 is the first frame; set to None to draw on all frames.
fill -- A sge.gfx.Color object representing the color of the fill of the ellipse.
outline -- A sge.gfx.Color object representing the color of the outline of the ellipse.
outline_thickness -- The thickness of the outline of the ellipse.
anti_alias -- Whether or not anti-aliasing should be used.
blend_mode -- The blend mode to use. Possible blend modes are:
- sge.BLEND_NORMAL
- sge.BLEND_RGBA_ADD
- sge.BLEND_RGBA_SUBTRACT
- sge.BLEND_RGBA_MULTIPLY
- sge.BLEND_RGBA_SCREEN
- sge.BLEND_RGBA_MINIMUM
- sge.BLEND_RGBA_MAXIMUM
- sge.BLEND_RGB_ADD
- sge.BLEND_RGB_SUBTRACT
- sge.BLEND_RGB_MULTIPLY
- sge.BLEND_RGB_SCREEN
- sge.BLEND_RGB_MINIMUM
- sge.BLEND_RGB_MAXIMUM
None is treated as sge.BLEND_NORMAL.

Changed in version 2.0: Repositioned the frame parameter to where the fill parameter used to be.

Sprite.draw_circle(x, y, radius, frame=None, *, fill=None, outline=None, outline_thickness=1, anti_alias=False, blend_mode=None)¶

Draw a circle on the sprite.

Parameters:

x -- The horizontal location relative to the sprite to position the center of the circle.
y -- The vertical location relative to the sprite to position the center of the circle.
radius -- The radius of the circle.
frame -- The frame of the sprite to draw on, where 0 is the first frame; set to None to draw on all frames.
fill -- A sge.gfx.Color object representing the color of the fill of the circle.
outline -- A sge.gfx.Color object representing the color of the outline of the circle.
outline_thickness -- The thickness of the outline of the circle.
anti_alias -- Whether or not anti-aliasing should be used.
blend_mode -- The blend mode to use. Possible blend modes are:
- sge.BLEND_NORMAL
- sge.BLEND_RGBA_ADD
- sge.BLEND_RGBA_SUBTRACT
- sge.BLEND_RGBA_MULTIPLY
- sge.BLEND_RGBA_SCREEN
- sge.BLEND_RGBA_MINIMUM
- sge.BLEND_RGBA_MAXIMUM
- sge.BLEND_RGB_ADD
- sge.BLEND_RGB_SUBTRACT
- sge.BLEND_RGB_MULTIPLY
- sge.BLEND_RGB_SCREEN
- sge.BLEND_RGB_MINIMUM
- sge.BLEND_RGB_MAXIMUM
None is treated as sge.BLEND_NORMAL.

Changed in version 2.0: Repositioned the frame parameter to where the fill parameter used to be.

Sprite.draw_polyline(points, color, thickness=1, frame=None, *, anti_alias=False, blend_mode=None)¶

Draw a sequence of contiguous straight lines on the sprite.

Parameters:

points -- A list of points relative to the sprite to position each of the polyline's angles. Each point should be a tuple in the form (x, y), where x is the horizontal location and y is the vertical location.
color -- A sge.gfx.Color object representing the color of the line segment.
thickness -- The thickness of the line segment.
frame -- The frame of the sprite to draw on, where 0 is the first frame; set to None to draw on all frames.
anti_alias -- Whether or not anti-aliasing should be used.
blend_mode -- The blend mode to use. Possible blend modes are:
- sge.BLEND_NORMAL
- sge.BLEND_RGBA_ADD
- sge.BLEND_RGBA_SUBTRACT
- sge.BLEND_RGBA_MULTIPLY
- sge.BLEND_RGBA_SCREEN
- sge.BLEND_RGBA_MINIMUM
- sge.BLEND_RGBA_MAXIMUM
- sge.BLEND_RGB_ADD
- sge.BLEND_RGB_SUBTRACT
- sge.BLEND_RGB_MULTIPLY
- sge.BLEND_RGB_SCREEN
- sge.BLEND_RGB_MINIMUM
- sge.BLEND_RGB_MAXIMUM
None is treated as sge.BLEND_NORMAL.

Sprite.draw_polygon(points, frame=None, *, fill=None, outline=None, outline_thickness=1, anti_alias=False, blend_mode=None)¶

Draw a polygon on the sprite.

Parameters:

points -- A list of points relative to the sprite to position each of the polygon's angles. Each point should be a tuple in the form (x, y), where x is the horizontal location and y is the vertical location.
frame -- The frame of the sprite to draw on, where 0 is the first frame; set to None to draw on all frames.
fill -- A sge.gfx.Color object representing the color of the fill of the polygon.
outline -- A sge.gfx.Color object representing the color of the outline of the polygon.
outline_thickness -- The thickness of the outline of the polygon.
anti_alias -- Whether or not anti-aliasing should be used.
blend_mode -- The blend mode to use. Possible blend modes are:
- sge.BLEND_NORMAL
- sge.BLEND_RGBA_ADD
- sge.BLEND_RGBA_SUBTRACT
- sge.BLEND_RGBA_MULTIPLY
- sge.BLEND_RGBA_SCREEN
- sge.BLEND_RGBA_MINIMUM
- sge.BLEND_RGBA_MAXIMUM
- sge.BLEND_RGB_ADD
- sge.BLEND_RGB_SUBTRACT
- sge.BLEND_RGB_MULTIPLY
- sge.BLEND_RGB_SCREEN
- sge.BLEND_RGB_MINIMUM
- sge.BLEND_RGB_MAXIMUM
None is treated as sge.BLEND_NORMAL.

Sprite.draw_sprite(sprite, image, x, y, frame=None, *, blend_mode=None)¶

Draw another sprite on the sprite.

Parameters:

sprite -- The sge.gfx.Sprite or sge.gfx.TileGrid object to draw with.
image -- The frame of sprite to draw with, where 0 is the first frame.
x -- The horizontal location relative to self to position the origin of sprite.
y -- The vertical location relative to self to position the origin of sprite.
frame -- The frame of the sprite to draw on, where 0 is the first frame; set to None to draw on all frames.
blend_mode -- The blend mode to use. Possible blend modes are:
- sge.BLEND_NORMAL
- sge.BLEND_RGBA_ADD
- sge.BLEND_RGBA_SUBTRACT
- sge.BLEND_RGBA_MULTIPLY
- sge.BLEND_RGBA_SCREEN
- sge.BLEND_RGBA_MINIMUM
- sge.BLEND_RGBA_MAXIMUM
- sge.BLEND_RGB_ADD
- sge.BLEND_RGB_SUBTRACT
- sge.BLEND_RGB_MULTIPLY
- sge.BLEND_RGB_SCREEN
- sge.BLEND_RGB_MINIMUM
- sge.BLEND_RGB_MAXIMUM
None is treated as sge.BLEND_NORMAL.

Sprite.draw_text(font, text, x, y, width=None, height=None, color=sge.gfx.Color('white'), halign='left', valign='top', frame=None, *, anti_alias=True, blend_mode=None, outline=None, outline_thickness=0)¶

Draw text on the sprite.

Parameters:

font -- The font to use to draw the text.
text -- The text (as a string) to draw.
x -- The horizontal location relative to the sprite to draw the text.
y -- The vertical location relative to the sprite to draw the text.
width -- The width of the imaginary rectangle the text is drawn in; set to None to make the rectangle as wide as needed to contain the text without additional line breaks. If set to something other than None, a line which does not fit will be automatically split into multiple lines that do fit.
height -- The height of the imaginary rectangle the text is drawn in; set to None to make the rectangle as tall as needed to contain the text.
color -- A sge.gfx.Color object representing the color of the text.
halign -- The horizontal alignment of the text and the horizontal location of the origin of the imaginary rectangle the text is drawn in. Can be set to one of the following:
- "left" -- Align the text to the left of the imaginary rectangle the text is drawn in. Set the origin of the imaginary rectangle to its left edge.
- "center" -- Align the text to the center of the imaginary rectangle the text is drawn in. Set the origin of the imaginary rectangle to its center.
- "right" -- Align the text to the right of the imaginary rectangle the text is drawn in. Set the origin of the imaginary rectangle to its right edge.
valign -- The vertical alignment of the text and the vertical location of the origin of the imaginary rectangle the text is drawn in. Can be set to one of the following:
- "top" -- Align the text to the top of the imaginary rectangle the text is drawn in. Set the origin of the imaginary rectangle to its top edge. If the imaginary rectangle is not tall enough to contain all of the text, cut text off from the bottom.
- "middle" -- Align the the text to the middle of the imaginary rectangle the text is drawn in. Set the origin of the imaginary rectangle to its middle. If the imaginary rectangle is not tall enough to contain all of the text, cut text off equally from the top and bottom.
- "bottom" -- Align the text to the bottom of the imaginary rectangle the text is drawn in. Set the origin of the imaginary rectangle to its top edge. If the imaginary rectangle is not tall enough to contain all of the text, cut text off from the top.
frame -- The frame of the sprite to draw on, where 0 is the first frame; set to None to draw on all frames.
anti_alias -- Whether or not anti-aliasing should be used.
blend_mode -- The blend mode to use. Possible blend modes are:
- sge.BLEND_NORMAL
- sge.BLEND_RGBA_ADD
- sge.BLEND_RGBA_SUBTRACT
- sge.BLEND_RGBA_MULTIPLY
- sge.BLEND_RGBA_SCREEN
- sge.BLEND_RGBA_MINIMUM
- sge.BLEND_RGBA_MAXIMUM
- sge.BLEND_RGB_ADD
- sge.BLEND_RGB_SUBTRACT
- sge.BLEND_RGB_MULTIPLY
- sge.BLEND_RGB_SCREEN
- sge.BLEND_RGB_MINIMUM
- sge.BLEND_RGB_MAXIMUM
None is treated as sge.BLEND_NORMAL.
outline -- A sge.gfx.Color object representing the color of the text's outline. Set to None for no outline.
outline_thickness -- The thickness of the outline in pixels. A value of 0 means no outline will be drawn.

Changed in version 2.0: Repositioned the frame parameter to where the anti_alias parameter used to be.

Sprite.draw_shader(x, y, width, height, shader, frame=None)¶

Apply a pixel shader to the sprite.

Parameters:

x -- The horizontal location relative to the sprite of the area to apply the shader to.
y -- The vertical location relative to the sprite of the area to apply the shader to.
width -- The width of the area to apply the shader to.
height -- The height of the area to apply the shader to.
shader -- A callback function for the shader (see below).
frame -- The frame of the sprite to apply the shader to, where 0 is the first frame; set to None to erase from all frames.

The shader argument is a callback function which must contain the following Parameters:

x -- The horizontal location of the pixel relative to the area the shader is being applied to.
y -- The vertical location of the pixel relative to the area the shader is being applied to.
red -- The red component of the initial color as an integer, where 0 indicates no red intensity and 255 indicates full red intensity.
green -- The green component of the initial color as an integer, where 0 indicates no green intensity and 255 indicates full red intensity.
blue -- The blue component of the initial color as an integer, where 0 indicates no blue intensity and 255 indicates full red intensity.
alpha -- The alpha component of the initial color as an integer, where 0 indicates fully transparent and 255 indicates fully opaque.

The callback function must return the new color components of the respective pixel containing the modified red, green, blue, and alpha values, respectively.

For example, the following function would serve as a shader that inverts all colors:

def shader(x, y, red, green, blue, alpha):
    return (255 - red, 255 - green, 255 - blue, alpha)

Note

Due to use of the CPU, applying these shaders is highly inefficient. To compensate, it is important to apply shaders to sprites as infrequently as possible, preferably just once at the start, and reuse the sprites they were applied to.

Sprite.draw_erase(x, y, width, height, frame=None)¶

Erase part of the sprite.

Parameters:

x -- The horizontal location relative to the sprite of the area to erase.
y -- The vertical location relative to the sprite of the area to erase.
width -- The width of the area to erase.
height -- The height of the area to erase.
frame -- The frame of the sprite to erase from, where 0 is the first frame; set to None to erase from all frames.

Sprite.draw_clear(frame=None)¶

Erase everything from the sprite.

Parameters:

frame -- The frame of the sprite to clear, where 0 is the first frame; set to None to clear all frames.

Sprite.draw_lock()¶

Lock the sprite for continuous drawing.

Use this method to "lock" the sprite for being drawn on several times in a row. What exactly this does depends on the implementation and it may even do nothing at all, but calling this method before doing several draw actions on the sprite in a row gives the SGE a chance to make the drawing more efficient.

After you are done with continuous drawing, call draw_unlock() to let the SGE know that you are done drawing.

Warning

Do not cause a sprite to be used while it's locked. For example, don't leave it locked for the duration of a frame, and don't draw it or project it on anything. The effect of using a locked sprite could be as minor as graphical errors and as severe as crashing the program, depending on the SGE implementation. Always call draw_unlock() immediately after you're done drawing for a while.

Sprite.draw_unlock()¶

Unlock the sprite.

Use this method to "unlock" the sprite after it has been "locked" for continuous drawing by draw_lock().

Sprite.mirror(frame=None)¶

Mirror the sprite horizontally.

Parameters:

frame -- The frame of the sprite to mirror, where 0 is the first frame; set to None to mirror all frames.

Sprite.flip(frame=None)¶

Flip the sprite vertically.

Parameters:

frame -- The frame of the sprite to flip, where 0 is the first frame; set to None to flip all frames.

Sprite.resize_canvas(width, height)¶

Resize the sprite by adding empty space instead of scaling.

After resizing the canvas:

The horizontal location of the origin is multiplied by the new width divided by the old width.
The vertical location of the origin is multiplied by the new height divided by the old height.
All frames are repositioned within the sprite such that their position relative to the origin is the same as before.

Parameters:

width -- The width to set the sprite to.
height -- The height to set the sprite to.

Sprite.scale(xscale=1, yscale=1, frame=None)¶

Scale the sprite to a different size.

Unlike changing width and height, this function does not result in the actual size of the sprite changing. Instead, any scaled frames are repositioned so that the pixel which was at the origin before scaling remains at the origin.

Parameters:

xscale -- The horizontal scale factor.
yscale -- The vertical scale factor.
frame -- The frame of the sprite to scale, where 0 is the first frame; set to None to scale all frames.

Note

This is a destructive transformation: it can result in loss of pixel information, especially if it is done repeatedly. Because of this, it is advised that you do not adjust this value for routine scaling. Use the image_xscale and image_yscale attributes of a sge.dsp.Object object instead.

Note

Because this function does not alter the actual size of the sprite, scaling up may result in some parts of the image being cropped off.

Sprite.rotate(x, adaptive_resize=True, frame=None)¶

Rotate the sprite about the center.

Parameters:

x -- The rotation amount in degrees, with rotation in a positive direction being clockwise.
adaptive_resize -- Whether or not the sprite should be resized to accomodate rotation. If this is True, rotation amounts other than multiples of 180 will result in the size of the sprite being adapted to fit the whole rotated image. The origin and any frames which have not been rotated will also be moved so that their location relative to the rotated image(s) is the same.
frame -- The frame of the sprite to rotate, where 0 is the first frame; set to None to rotate all frames.

Note

This is a destructive transformation: it can result in loss of pixel information, especially if it is done repeatedly. Because of this, it is advised that you do not adjust this value for routine rotation. Use the image_rotation attribute of a sge.dsp.Object object instead.

Sprite.swap_color(old_color, new_color, frame=None)¶

Change all pixels of one color to another color.

Parameters:

old_color -- A sge.gfx.Color object indicating the color of pixels to change.
new_color -- A sge.gfx.Color object indicating the color to change the pixels to.
frame -- The frame of the sprite to modify, where 0 is the first frame; set to None to modify all frames.

Note

If you have to swap multiple colors, use of Sprite.draw_shader() will probably be more efficient.

Sprite.copy()¶: Return a copy of the sprite.

Sprite.get_spritelist()¶

Return a list of sprites based on this one.

The list returns one sprite for each of this sprite's frames, containing only said frame. This effectively splits an animated sprite into several stillframe sprites.

Sprite.save(fname)¶

Save the sprite to an image file.

Parameters:

fname -- The path of the file to save the sprite to. If it is not a path that can be saved to, OSError is raised.

If the sprite has multiple frames, the image file saved will be a horizontal reel of each of the frames from left to right with no space in between the frames.

classmethod Sprite.from_tween(sprite, frames, fps=None, *, xscale=None, yscale=None, rotation=None, blend=None, bbox_x=None, bbox_y=None, bbox_width=None, bbox_height=None, blend_mode=None)¶

Create a sprite based on tweening an existing sprite.

"Tweening" refers to creating an animation from gradual transformations to an image. For example, this can be used to generate an animation of an object growing to a particular size. The animation generated is called a "tween".

Parameters:

sprite -- The sprite to base the tween on. If the sprite includes multiple frames, all frames will be used in sequence until the end of the tween.

The tween's origin is derived from this sprite's origin, adjusted appropriately to accomodate any size changes made. Whether or not the tween is transparent is also determined by whether or not this sprite is transparent.
frames -- The number of frames the to make the tween take up.
fps -- The suggested rate of animation for the tween in frames per second. If set to None, the suggested animation rate of the base sprite is used.
xscale -- The horizontal scale factor at the end of the tween. If set to None, horizontal scaling will not be included in the tweening process.
yscale -- The vertical scale factor at the end of the tween. If set to None, vertical scaling will not be included in the tweening process.
rotation -- The total clockwise rotation amount in degrees at the end of the tween. Can be negative to indicate counter-clockwise rotation instead. If set to None, rotation will not be included in the tweening process.
blend -- A sge.gfx.Color object representing the color to blend with the sprite at the end of the tween. If set to None, color blending will not be included in the tweening process.
blend_mode -- The blend mode to use with blend. Possible blend modes are:
- sge.BLEND_NORMAL
- sge.BLEND_RGBA_ADD
- sge.BLEND_RGBA_SUBTRACT
- sge.BLEND_RGBA_MULTIPLY
- sge.BLEND_RGBA_SCREEN
- sge.BLEND_RGBA_MINIMUM
- sge.BLEND_RGBA_MAXIMUM
- sge.BLEND_RGB_ADD
- sge.BLEND_RGB_SUBTRACT
- sge.BLEND_RGB_MULTIPLY
- sge.BLEND_RGB_SCREEN
- sge.BLEND_RGB_MINIMUM
- sge.BLEND_RGB_MAXIMUM
None is treated as sge.BLEND_RGBA_MULTIPLY.

All other arguments set the respective initial attributes of the tween. See the documentation for sge.gfx.Sprite for more information.

classmethod Sprite.from_text(font, text, width=None, height=None, color=sge.gfx.Color('white'), halign='left', valign='top', *, anti_alias=True, outline=None, outline_thickness=0)¶

Create a sprite, draw the given text on it, and return the sprite. See the documentation for sge.gfx.Sprite.draw_text() for more information.

The sprite's origin is set based on halign and valign.

classmethod Sprite.from_tileset(fname, x=0, y=0, columns=1, rows=1, xsep=0, ysep=0, width=1, height=1, origin_x=0, origin_y=0, transparent=True, fps=0, bbox_x=None, bbox_y=None, bbox_width=None, bbox_height=None)¶

Return a sprite based on the tiles in a tileset.

Parameters:

fname -- The path to the image file containing the tileset.
x -- The horizontal location relative to the image of the top-leftmost tile in the tileset.
y -- The vertical location relative to the image of the top-leftmost tile in the tileset.
columns -- The number of columns in the tileset.
rows -- The number of rows in the tileset.
xsep -- The spacing between columns in the tileset.
ysep -- The spacing between rows in the tileset.
width -- The width of the tiles.
height -- The height of the tiles.

For all other arguments, see the documentation for Sprite.__init__().

Each tile in the tileset becomes a subimage of the returned sprite, ordered first from left to right and then from top to bottom.

classmethod Sprite.from_screenshot(x=0, y=0, width=None, height=None)¶

Return the current display on the screen as a sprite.

Parameters:

x -- The horizontal location of the rectangular area to take a screenshot of.
y -- The vertical location of the rectangular area to take a screenshot of.
width -- The width of the area to take a screenshot of; set to None for all of the area to the right of x to be included.
height -- The height of the area to take a screenshot of; set to None for all of the area below y to be included.

If you only wish to save a screenshot (of the entire screen) to a file, the easiest way to do that is:

sge.gfx.Sprite.from_screenshot().save("foo.png")

sge.gfx.Font ¶

class sge.gfx.Font(name=None, size=12, *, underline=False, bold=False, italic=False)¶

This class stores a font for use by text drawing methods.

Note that bold and italic rendering could be ugly. It is better to choose a bold or italic font rather than enabling bold or italic rendering, if possible.

size¶: The height of the font in pixels.

underline¶: Whether or not underlined rendering is enabled.

bold¶: Whether or not bold rendering is enabled.

Note

Using this option can be ugly. It is better to choose a bold font rather than enabling bold rendering, if possible.

italic¶: Whether or not italic rendering is enabled.

Note

Using this option can be ugly. It is better to choose an italic font rather than enabling italic rendering, if possible.

linesize¶: The size of a line of text, i.e. the distance between the top of one line and the top of the line that follows it. (Read-only)

name¶: The name of the font as specified when it was created. (Read-only)

rd¶: Reserved dictionary for internal use by the SGE. (Read-only)

Font.__init__(name=None, size=12, *, underline=False, bold=False, italic=False)¶

Parameters:

name -- The name of the font. Can be one of the following:
- A string indicating the path to the font file.
- A string indicating the case-insensitive name of a system font, e.g. "Roboto".
- A list or tuple of strings indicating either a font file or a system font to choose from in order of preference.
If none of the above methods return a valid font, the SGE will choose the font.

All other arguments set the respective initial attributes of the font. See the documentation for sge.gfx.Font for more information.

Note

It is generally not a good practice to rely on system fonts. There are no standard fonts; a font which you have on your system is probably not on everyone's system. Rather than relying on system fonts, choose a font which is under a libre license (such as the GNU General Public License or the SIL Open Font License) and distribute it with your game; this will ensure that everyone sees text rendered the same way you do.

sge.gfx.Font Methods ¶

Font.get_width(text, width=None, height=None, *, outline_thickness=0)¶

Return the width of a certain string of text when rendered.

See the documentation for sge.gfx.Sprite.draw_text() for more information.

Font.get_height(text, width=None, height=None, *, outline_thickness=0)¶

Return the height of a certain string of text when rendered.

See the documentation for sge.gfx.Sprite.draw_text() for more information.

classmethod Font.from_sprite(sprite, chars, hsep=0, vsep=0, size=12, *, underline=False, bold=False, italic=False)¶

Return a font derived from a sprite.

Parameters:

sprite -- The sge.gfx.Sprite object to derive the font from.
chars -- A dictionary mapping each supported text character to the corresponding frame of the sprite. For example, {'A': 0, 'B': 1, 'C': 2} would assign the letter "A' to the first frame, the letter "B" to the second frame, and the letter "C" to the third frame.

Alternatively, this can be given as a list of characters to assign to the frames corresponding to the characters' indexes within the list. For example, ['A', 'B', 'C'] would assign the letter "A" to the first frame, the letter "B" to the second frame, and the letter "C" to the third frame.

Any character not explicitly mapped to a frame will be rendered as its differently-cased counterpart if possible (e.g. "A" as "a"). Otherwise, it will be rendered using the frame mapped to None. If None has not been explicitly mapped to a frame, it is implied to be a blank space.
hsep -- The amount of horizontal space to place between characters when text is rendered.
vsep -- The amount of vertical space to place between lines when text is rendered.

All other arguments set the respective initial attributes of the font. See the documentation for sge.gfx.Font for more information.

The font's name attribute will be set to the name of the sprite the font is derived from.

The font's size attribute will indicate the height of the characters in pixels. The width of the characters will be adjusted proportionally.

sge.gfx.BackgroundLayer ¶

class sge.gfx.BackgroundLayer(sprite, x, y, z=0, *, xscroll_rate=1, yscroll_rate=1, repeat_left=False, repeat_right=False, repeat_up=False, repeat_down=False)¶

This class stores a sprite and certain information for a layer of a background. In particular, it stores the location of the layer, whether the layer tiles horizontally, vertically, or both, and the rate at which it scrolls.

sprite¶: The sprite used for this layer. It will be animated normally if it contains multiple frames.

x¶: The horizontal location of the layer relative to the background.

y¶: The vertical location of the layer relative to the background.

z¶: The Z-axis position of the layer in the room.

xscroll_rate¶: The horizontal rate that the layer scrolls as a factor of the additive inverse of the horizontal movement of the view.

yscroll_rate¶: The vertical rate that the layer scrolls as a factor of the additive inverse of the vertical movement of the view.

repeat_left¶: Whether or not the layer should be repeated (tiled) to the left.

repeat_right¶: Whether or not the layer should be repeated (tiled) to the right.

repeat_up¶: Whether or not the layer should be repeated (tiled) upwards.

repeat_down¶: Whether or not the layer should be repeated (tiled) downwards.

rd¶: Reserved dictionary for internal use by the SGE. (Read-only)

BackgroundLayer.__init__(sprite, x, y, z=0, *, xscroll_rate=1, yscroll_rate=1, repeat_left=False, repeat_right=False, repeat_up=False, repeat_down=False)¶: Arguments set the respective initial attributes of the layer. See the documentation for sge.gfx.BackgroundLayer for more information.

sge.gfx.Background ¶

class sge.gfx.Background(layers, color)¶

This class stores the layers that make up the background (which contain the information about what images to use and where) as well as the color to use where no image is shown.

layers¶: A list containing all sge.gfx.BackgroundLayer objects used in this background. (Read-only)

color¶: A sge.gfx.Color object representing the color used in parts of the background where no layer is shown.

rd¶: Reserved dictionary for internal use by the SGE. (Read-only)

Background.__init__(layers, color)¶: Arguments set the respective initial attributes of the background. See the documentation for sge.gfx.Background for more information.

sge.gfx ¶

sge.gfx Classes ¶

sge.gfx.Color ¶

sge.gfx.Sprite ¶

sge.gfx.Sprite Methods ¶

sge.gfx.Font ¶

sge.gfx.Font Methods ¶

sge.gfx.BackgroundLayer ¶

sge.gfx.Background ¶

Seclusion Game Engine

Navigation

Related Topics