This file has been dedicated to the public domain, to the extent
possible under applicable law, via CC0. See
http://creativecommons.org/publicdomain/zero/1.0/ for more
information. This file is offered as-is, without any warranty.

========================================================================

This file details specifics of the Pygame SGE implementation which
may be useful to know.


FORMATS SUPPORT

sge.gfx.Sprite supports the following image formats if Pygame is built
with full image support:

- PNG
- JPEG
- Non-animated GIF
- BMP
- PCX
- Uncompressed Truevision TGA
- TIFF
- ILBM
- Netpbm
- X Pixmap

If Pygame is built without full image support, sge.gfx.Sprite will only
be able to load uncompressed BMP images.

sge.snd.Sound supports the following audio formats:

- Uncompressed WAV
- Ogg Vorbis

sge.snd.Music supports the following audio formats:

- Ogg Vorbis
- MOD
- XM
- MIDI

MP3 is also supported on some systems, but not all, due to software idea
patents which restrict use of this format.  On some systems, attempting
to load an unsupported format can crash the game.  Since MP3 support is
not available on all systems, it is best to avoid using it; consider
using Ogg Vorbis instead.

For starting position in MOD files, the pattern order number is used
instead of the number of milliseconds.

The pygame.mixer module, which is used for all audio playback, is
optional and depends on SDL_mixer; if pygame.mixer is unavailable,
sounds and music will not play.


MISSING FEATURES

sge.gfx.Sprite.draw_line, sge.dsp.Room.project_line, and
sge.dsp.Game.project_line support anti-aliasing for lines with a
thickness of 1 only.  sge.gfx.Sprite.draw_polygon,
sge.dsp.Room.project_polygon, and sge.dsp.Game.project_polygon support
anti-aliasing for outlines of polygons with a thickness of 1 only.
sge.gfx.Sprite.draw_text, sge.dsp.Room.project_text, and
sge.dsp.Game.project_text support anti-aliasing in all cases.  No other
drawing or projecting methods support anti-aliasing.  If anti-aliasing
is unsupported for a particular case, the Pygame SGE will ignore the
request for anti-aliasing.


KEYBOARD LOCK-UP

There is a bug in either Pygame or SDL, most likely SDL, which sometimes
causes keyboard input to stop working.  In Pygame programs such as this
one, this occurs when pygame.display.set_mode is called multiple times,
which in the Pygame SGE occurs any time either the size of the window or
the video mode (windowed or fullscreen) changes.  See this post from the
SGE blog for more information:

https://savannah.nongnu.org/forum/forum.php?forum_id=8113

You may also be interested in this report on the Pygame issue tracker:

https://bitbucket.org/pygame/pygame/issue/212/

As mentioned in the post on the SGE blog, this is a particularly serious
problem for anyone using the X Window System (e.g. pretty much any
GNU/Linux user), or any other window system that gives complete control
to fullscreen SDL applications.  On these systems, if the game requires
keyboard input to either leave fullscreen or exit, the system will
become unresponsive to everything that isn't sent directly to the kernel
(such as the magic SysRq key in Linux systems).

Luckily, the bug doesn't seem to affect mouse input, so if you allow the
player to enter fullscreen mode in-game, it is highly recommended for
you to provide some method of either exiting the game or exiting
fullscreen with the mouse.  This can be a button somewhere on the screen
if the game uses the mouse cursor, or it can be a simple mouse button
click otherwise.


DISCOLORED PNG IMAGES

Some versions of Pygame have problems saving color information of PNG
images correctly.  As a result, depending on your exact version of
Pygame, images saves with sge.gfx.Sprite.save may be discolored.  The
best workaround is to choose a different format, such as BMP, GIF, or
JPEG.
