
sge.gfx
*******


Contents
^^^^^^^^

* 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.BackgroundLayer Methods

    * sge.gfx.Background

      * sge.gfx.Background Methods

This module provides classes related to rendering graphics.


sge.gfx Classes
===============


sge.gfx.Color
-------------

class sge.gfx.Color(value)

   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

      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)


sge.gfx.Sprite
--------------

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.

   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)


sge.gfx.Sprite Methods
~~~~~~~~~~~~~~~~~~~~~~

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)

   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, "OSError" 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()

   Append a new blank frame to the end of the sprite.

Sprite.insert_frame(frame)

   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.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.

   Arguments:

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

Sprite.delete_frame(frame)

   Delete a frame from the sprite.

   Arguments:

   * "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.

   Arguments:

   * "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.

   Arguments:

   * "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.

   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.

   * "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, anti_alias=False, frame=None, blend_mode=None)

   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.

   * "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_rectangle(x, y, width, height, fill=None, outline=None, outline_thickness=1, frame=None, blend_mode=None)

   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.

   * "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_ellipse(x, y, width, height, fill=None, outline=None, outline_thickness=1, anti_alias=False, frame=None, blend_mode=None)

   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.

   * "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_circle(x, y, radius, fill=None, outline=None, outline_thickness=1, anti_alias=False, frame=None, blend_mode=None)

   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.

   * "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, fill=None, outline=None, outline_thickness=1, anti_alias=False, frame=None, blend_mode=None)

   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.

   * "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.

   Arguments:

   * "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', anti_alias=True, frame=None, blend_mode=None)

   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.

   * "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_erase(x, y, width, height, frame=None)

   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)

   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()

   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.

   Arguments:

   * "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.

   Arguments:

   * "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:

   1. The horizontal location of the origin is multiplied by the
      new width divided by the old width.

   2. The vertical location of the origin is multiplied by the new
      height divided by the old height.

   3. All frames are repositioned within the sprite such that their
      position relative to the origin is the same as before.

   Arguments:

   * "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.

   Arguments:

   * "xscale" -- The horizontal scale factor.

   * "yscale" -- The vertical scale factor.

   * "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 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.

   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 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.

   Arguments:

   * "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 rotate, where "0" is the
     first frame; set to "None" to rotate all frames.

   Note: While this method can be used on any image, it is likely to
     be most efficient when used on images based on palettes (such as
     8-bit images).  The SGE cannot implicitly convert high bit depth
     images to low bit depths, so if you plan on using this method
     frequently, you should ensure that you save your images in a low
     bit depth.

Sprite.copy()

   Return a copy of the sprite.

Sprite.save(fname)

   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, "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".

   Arguments:

   * "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)

   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.

   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)

   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")


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.

   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)


sge.gfx.Font Methods
~~~~~~~~~~~~~~~~~~~~

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

   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)

   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)

   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.

   Arguments:

   * "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)


sge.gfx.BackgroundLayer Methods
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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)


sge.gfx.Background Methods
~~~~~~~~~~~~~~~~~~~~~~~~~~

Background.__init__(layers, color)

   Arguments set the respective initial attributes of the background.
   See the documentation for "sge.gfx.Background" for more
   information.
