This module provides classes related to rendering graphics.
-
class sge.gfx.Color(value)[source]
This class stores color information.
Objects of this class can be converted to iterables indicating the
object’s red, green, blue, and alpha
values, respectively; to integers which can be interpreted as a
hexadecimal representation of the color, excluding alpha
transparency; and to strings which indicate the English name of the
color (in all lowercase) if possible, and hex_string
otherwise.
-
red[source]
The red component of the color as an integer, where 0
indicates no red intensity and 255 indicates full red
intensity.
-
green[source]
The green component of the color as an integer, where 0
indicates no green intensity and 255 indicates full green
intensity.
-
blue[source]
The blue component of the color as an integer, where 0
indicates no blue intensity and 255 indicates full blue
intensity.
-
alpha[source]
The alpha transparency of the color as an integer, where 0
indicates full transparency and 255 indicates full opacity.
-
hex_string[source]
An HTML hex string representation of the color. (Read-only)
-
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)[source]
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[source]
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[source]
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.
-
transparent[source]
Whether or not the image should be partially transparent. If an
image does not have an alpha channel, a colorkey will be used,
with the transparent color being the color of the top-rightmost
pixel of the respective frame.
-
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[source]
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[source]
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[source]
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.
-
bbox_height
The height of the suggested bounding box.
-
name
The name of the sprite given when it was created. (Read-only)
-
frames[source]
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)[source]
Arguments:
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, IOError 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.
-
Sprite.append_frame()[source]
Append a new blank frame to the end of the sprite.
-
Sprite.insert_frame(frame)[source]
Insert a new blank frame into the sprite.
Arguments:
- frame – The frame of the sprite to insert the new frame
in front of, where 0 is the first frame.
-
Sprite.delete_frame(frame)[source]
Delete a frame from the sprite.
Arguments:
- frame – The frame of the sprite to delete, where 0 is
the first frame.
-
Sprite.draw_dot(x, y, color, frame=None)[source]
Draw a single-pixel dot on the sprite.
Arguments:
- 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.
-
Sprite.draw_line(x1, y1, x2, y2, color, thickness=1, anti_alias=False, frame=None)[source]
Draw a line segment on the sprite.
Arguments:
- 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.
- anti_alias – Whether or not anti-aliasing should be used.
- frame – The frame of the sprite to draw on, where 0
is the first frame; set to None to draw on all
frames.
-
Sprite.draw_rectangle(x, y, width, height, fill=None, outline=None, outline_thickness=1, frame=None)[source]
Draw a rectangle on the sprite.
Arguments:
- 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.
- 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.
- frame – The frame of the sprite to draw on, where 0
is the first frame; set to None to draw on all
frames.
-
Sprite.draw_ellipse(x, y, width, height, fill=None, outline=None, outline_thickness=1, anti_alias=False, frame=None)[source]
Draw an ellipse on the sprite.
Arguments:
- 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.
- 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.
- frame – The frame of the sprite to draw on, where 0
is the first frame; set to None to draw on all
frames.
-
Sprite.draw_circle(x, y, radius, fill=None, outline=None, outline_thickness=1, anti_alias=False, frame=None)[source]
Draw a circle on the sprite.
Arguments:
- 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.
- 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.
- frame – The frame of the sprite to draw on, where 0
is the first frame; set to None to draw on all
frames.
-
Sprite.draw_polygon(points, fill=None, outline=None, outline_thickness=1, anti_alias=False, frame=None)[source]
Draw a polygon on the sprite.
Arguments:
- 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.
- 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.
- frame – The frame of the sprite to draw on, where 0
is the first frame; set to None to draw on all
frames.
-
Sprite.draw_sprite(sprite, image, x, y, frame=None, blend_mode=None)[source]
Draw another sprite on the sprite.
Arguments:
sprite – The sprite 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', anti_alias=True, frame=None)[source]
Draw text on the sprite.
Arguments:
- 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.
- anti_alias – Whether or not anti-aliasing should be used.
- frame – The frame of the sprite to draw on, where 0
is the first frame; set to None to draw on all
frames.
-
Sprite.draw_erase(x, y, width, height, frame=None)[source]
Erase part of the sprite.
Arguments:
- 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)[source]
Erase everything from the sprite.
Arguments:
- frame – The frame of the sprite to clear, where 0 is
the first frame; set to None to clear all frames.
-
Sprite.draw_lock()[source]
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()[source]
Unlock the sprite.
Use this method to “unlock” the sprite after it has been
“locked” for continuous drawing by draw_lock().
-
Sprite.mirror()[source]
Mirror the sprite horizontally.
-
Sprite.flip()[source]
Flip the sprite vertically.
-
Sprite.rotate(x, adaptive_resize=True)[source]
Rotate the sprite about the center.
Arguments:
- 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 will also be adjusted so that the rotation
is about the center.
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.copy()[source]
Return a copy of the sprite.
-
Sprite.save(fname)[source]
Save the sprite to an image file.
Arguments:
- fname – The path of the file to save the sprite to. If
it is not a path that can be saved to, IOError 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_text(font, text, width=None, height=None, color=sge.gfx.Color("white"), halign='left', valign='top', anti_alias=True)[source]
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)[source]
Return a sprite based on the tiles in a tileset.
Arguments:
- 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)[source]
Return the current display on the screen as a sprite.
Arguments:
- 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")
-
class sge.gfx.Font(name=None, size=12, underline=False, bold=False, italic=False)[source]
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[source]
The height of the font in pixels.
-
underline[source]
Whether or not underlined rendering is enabled.
-
bold[source]
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[source]
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.
-
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)[source]
Arguments:
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. "Liberation Serif".
- 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.
-
Font.get_width(text, width=None, height=None)[source]
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)[source]
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)[source]
Return a font derived from a sprite.
Arguments:
- sprite – The sge.gfx.Sprite object to derive the
font from.
- chars – A list of characters to set the sprite’s frames
to. For example, ['A', 'B', 'C'] would assign the first
frame to the letter “A”, the second frame to the letter “B”,
and the third frame to the letter “C”. Any character not
listed here will be rendered as its differently-cased
counterpart if possible (e.g. “A” as “a”) or as a blank space
otherwise.
- 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.
-
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)[source]
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)[source]
Arguments set the respective initial attributes of the layer.
See the documentation for sge.gfx.BackgroundLayer for
more information.
-
class sge.gfx.Background(layers, color)[source]
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[source]
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)[source]
Arguments set the respective initial attributes of the
background. See the documentation for
sge.gfx.Background for more information.