Commits

Anonymous committed 3c6134a

Minor documentation reorganisation.
Fixed lots of minor documentation fixes.
Added pygame2.font.find_fonts() method, which returns all matching fonts.

Comments (0)

Files changed (35)

config/libconfig.py

             output = p.communicate()[0]
             retcode = p.returncode
         if helpers.getversion()[0] >= 3:
-            output = str (output, "ascii")
+            output = str (output, "utf-8")
         return retcode, output
     except OSError:
         return -1, None

config/pkgconfig.py

             output = p.communicate()[0]
             retcode = p.returncode
         if helpers.getversion()[0] >= 3:
-            output = str (output, "ascii")
+            output = str (output, "utf-8")
         return retcode, output
     except OSError:
         return -1, None
 	@echo "  linkcheck to check all external links for integrity"
 
 docclean:
-	@rm -rf sphinx/build *~ *.pyc *.orig ref/pygame2_*
-	@rm -f ref/pygame2.rst ref/*~ ref/*.pyc ref/*.orig
-	@rm -f builddarwin.rst buildmingw.rst buildunix.rst buildvc.rst
-	@rm -f newmodules.rst module_faq.rst news.rst release.rst
+	@rm -rf sphinx/build *~ *.pyc *.orig ref
+	@rm -rf builddarwin.rst buildmingw.rst buildvc.rst buildunix.rst
+	@rm -rf newmodules.rst module_faq.rst release.rst news.rst
 
 clean: docclean
 	@rm -rf html
 * Make sure, all tests for all supported Python versions work on all
   platforms. ::
 
-  make clean
-  make purge_installs
-  make installall
-  make testall
-  make testall2
+    make clean
+    make purge_installs
+    make installall
+    make testall
+    make testall2
 
 Editing News
 ============
 
 # List of directories, relative to source directory, that shouldn't be searched
 # for source files.
-exclude_trees = ['sphinx/build']
+exclude_trees = ['sphinx/build', 'src']
 
 # The reST default role (used for this markup: `text`) to use for all documents.
 #default_role = None

doc/create_rstref.py

 from xml.dom.minidom import parse
-import os, glob, sys
+import os, glob, sys, shutil
 
 RST_HEADER = """"""
 
         print ("Now writing RST for %s...." % doc.modulename)
         doc.create_rst ()
 
-def get_doc_files ():
+def get_xml_files ():
     docs = []
     files = glob.glob (os.path.join ("src", "*.xml"))
     for fname in files:
         docs.append (Doc (fname))
     return docs
 
+def get_rst_files ():
+    return glob.glob (os.path.join ("src", "*.rst"))
+
 if __name__ == "__main__":
-    docs = get_doc_files ()
+    docs = get_xml_files ()
     for doc in docs:
         print ("Parsing file %s..." % doc.filename)
         doc.parse_content ()
     create_rst (docs)
+
+    # Simply copy all other rst files
+    docs = get_rst_files ()
+    if not os.path.exists ("ref"):
+        os.mkdir ("ref")
+    for doc in docs:
+        fname = os.path.basename (doc)
+        shutil.copyfile (doc, os.path.join ("ref", "pygame2_%s" % fname))
    news.rst
    building.rst
    tutorial/index.rst
-   modules.rst
+   ref/pygame2_modules.rst
    capi.rst
    extending.rst
    release.rst

doc/modules.rst

-####################
-Module Documentation
-####################
-
-This is the core documentation of the various modules, classes and
-functions, pygame2 offers. If you want a quick module overview, use the
-:ref:`modindex`. If you just want to look up a specific class, attribute
-method or function, use the :ref:`genindex` or :ref:`search`.
-
-General Notes for Reading
-=========================
-
-.. note::
-
-  Whenever the API documentation refers to file-like objects, those
-  *must* support binary read and write access. This is especially
-  important for Python 3.x users and the new :mod:`io` module.
-
-Modules
-=======
-
-.. toctree::
-   :maxdepth: 2
-
-   ref/pygame2.rst
-   ref/pygame2_colorpalettes.rst
-   ref/examples.rst
-   ref/pygame2_font.rst
-   ref/pygame2_freetype_base.rst
-   ref/pygame2_mask.rst
-   ref/pygame2_physics.rst
-   ref/pygame2_sdl.rst
-   ref/pygame2_sdl_audio.rst
-   ref/pygame2_sdl_cdrom.rst
-   ref/sdlconstants.rst
-   ref/pygame2_sdl_cursors.rst
-   ref/pygame2_sdl_event.rst
-   ref/pygame2_sdl_gl.rst
-   ref/pygame2_sdl_image.rst
-   ref/pygame2_sdl_joystick.rst
-   ref/pygame2_sdl_keyboard.rst
-   ref/pygame2_sdl_mouse.rst
-   ref/pygame2_sdl_rwops.rst
-   ref/pygame2_sdl_time.rst
-   ref/pygame2_sdl_video.rst
-   ref/pygame2_sdl_wm.rst
-   ref/pygame2_sdlext.rst
-   ref/pygame2_sdlext_draw.rst
-   ref/pygame2_sdlext_fastevent.rst
-   ref/pygame2_sdlext_font.rst
-   ref/pygame2_sdlext_numericsurfarray.rst
-   ref/pygame2_sdlext_numpysurfarray.rst
-   ref/pygame2_sdlext_scrap.rst
-   ref/pygame2_sdlext_surfarray.rst
-   ref/pygame2_sdlext_transform.rst
-   ref/pygame2_sdlgfx.rst
-   ref/pygame2_sdlgfx_primitives.rst
-   ref/pygame2_sdlgfx_rotozoom.rst
-   ref/pygame2_sdlimage.rst
-   ref/pygame2_sdlmixer.rst
-   ref/pygame2_sdlmixer_channel.rst
-   ref/pygame2_sdlmixer_music.rst
-   ref/pygame2_sdlmixer_numericsndarray.rst
-   ref/pygame2_sdlttf.rst
-   ref/pygame2_sdlttf_sysfont.rst
-   ref/tests.rst

doc/ref/examples.rst

-:mod:`pygame2.examples` -- examples for Pygame2
-===============================================
-
-Examples package for Pygame2.
-
-This package contains code snippets demonstrating the aspects of the
-various Pygame2 modules. Each example is an module of its own and can be
-easily executed using ::
-
-    python -m pygame2.examples.<module>.<example>
-
-To run the drawing pygame2.sdlext example, you would type ::
-
-    python -m pygame2.examples.sdlext.draw
-
-Currently the following examples exists:
-
-+------------------------------------+----------------------------------------+
-| Example                            | Description                            |
-+====================================+========================================+
-| pygame2.examples.import            | Simple import example for all Pygame2  |
-|                                    | modules.                               |
-+------------------------------------+----------------------------------------+
-| pygame2.examples.py2exe_setup      | Win32 standalone executable creation   |
-|                                    | example using Pygame2.                 |
-+------------------------------------+----------------------------------------+
-| pygame2.examples.physics.simple    | Simple physics example                 |
-+------------------------------------+----------------------------------------+
-| pygame2.examples.sdl.cdrom         | Demonstrates the features of the       |
-|                                    | :mod:`pygame2.sdl.cdrom` module.       |
-+------------------------------------+----------------------------------------+
-| pygame2.examples.sdl.hello_world   | The almighty "Hello World" example     |
-|                                    | using the :mod:`pygame2.sdl` module.   |
-+------------------------------------+----------------------------------------+
-| pygame2.examples.sdl.keyboard      | Demonstrates keyboard input and event  |
-|                                    | handling for the                       |
-|                                    | :mod:`pygame2.sdl.keyboard` module.    |
-+------------------------------------+----------------------------------------+
-| pygame2.examples.sdl.mouse         | Demonstrates mouse input and event     |
-|                                    | handling for the                       |
-|                                    | :mod:`pygame2.sdl.mouse` module.       |
-+------------------------------------+----------------------------------------+
-| pygame2.examples.sdl.surface_blit  | Demonstrates supported blitting        |
-|                                    | operations for                         |
-|                                    | :class:`pygame2.sdl.video.Surface`     |
-|                                    | objects.                               |
-+------------------------------------+----------------------------------------+
-| pygame2.examples.sdl.surface_fill  | Demonstrates supported filling         |
-|                                    | operations for                         |
-|                                    | :class:`pygame2.sdl.video.Surface`     |
-|                                    | objects.                               |
-+------------------------------------+----------------------------------------+
-| pygame2.examples.sdlext.draw       | Demonstrates the features of the       |
-|                                    | :mod:`pygame2.sdlext.draw` module.     |
-+------------------------------------+----------------------------------------+
-| pygame2.examples.sdlext.pixelarray | Demonstrates the features of the       |
-|                                    | :class:`pygame2.sdlext.PixelArray`     |
-|                                    | class.                                 |
-+------------------------------------+----------------------------------------+

doc/ref/sdlconstants.rst

-:mod:`pygame2.sdl.constants` -- Constants for SDL
-=================================================
-
-This module contains the constants used throughout the :mod:`pygame2.sdl`
-modules.
-
-.. module:: pygame2.sdl.constants
-   :synopsis: Constants used throughout the :mod:`pygame2.sdl` modules.
-
-Initialisation Constants
-------------------------
-
-Those constants are used by the :func:`pygame2.sdl.init`,
-:func:`pygame2.sdl.init_subsystem` and :func:`pygame2.sdl.quit_subsystem`
-functions.
-
-.. data:: INIT_AUDIO
-
-   Initialises the SDL audio subsystem.
-
-.. data:: INIT_CDROM
-
-   Initialises the SDL cdrom subsystem.
-
-.. data:: INIT_TIMER
-
-   Initialises the SDL timer subsystem.
-
-.. data:: INIT_JOYSTICK
-
-   Initialises the SDL joystick subsystem.
-
-.. data:: INIT_VIDEO
-
-   Initialises the SDL video subsystem.
-
-.. data:: INIT_EVERYTHING
-
-   Initialises all parts of the SDL subsystems.
-
-.. data:: INIT_NOPARACHUTE
-
-   Initialises the SDL subsystems without a segmentation fault parachute.
-
-.. data:: INIT_EVENTTHREAD
-
-   Initialises the SDL event subsystem with threading support.
-
-Blending Constants
-------------------
-
-Those constants are used by the :meth:`pygame2.sdl.video.Surface.blit`
-and :meth:`pygame2.sdl.video.Surface.fill` methods.
-
-.. data:: BLEND_RGB_ADD
-
-   Used for an additive blend, ignoring the per-pixel alpha value.
-
-.. data:: BLEND_RGB_SUB
-
-   Used for an subtractive blend, ignoring the per-pixel alpha value.
-
-.. data:: BLEND_RGB_MULT
-
-   Used for an multiply blend, ignoring the per-pixel alpha value.
-
-.. data:: BLEND_RGB_AND
-
-   Used for a binary AND'd blend, ignoring the per-pixel alpha value.
-
-.. data:: BLEND_RGB_OR
-
-   Used for a binary OR'd  blend, ignoring the per-pixel alpha value.
-
-.. data:: BLEND_RGB_XOR
-
-   Used for a binary XOR'd blend, ignoring the per-pixel alpha value.
-
-.. data:: BLEND_RGB_MIN
-
-   Used for a minimum blend, ignoring the per-pixel alpha value.
-
-.. data:: BLEND_RGB_MAX
-
-   Used for a maximum blend, ignoring the per-pixel alpha value.
-
-.. data:: BLEND_RGB_AVG
-
-   Used for an average blend, ignoring the per-pixel alpha value.
-
-.. data:: BLEND_RGB_DIFF
-
-   Used for a difference blend, ignoring the per-pixel alpha value.
-
-.. data:: BLEND_RGB_SCREEN
-
-   Used for a screen blend, ignoring the per-pixel alpha value.
-
-.. data:: BLEND_RGBA_ADD
-
-   Used for an additive blend, with the per-pixel alpha value.
-
-.. data:: BLEND_RGBA_SUB
-
-   Used for an subtractive blend, with the per-pixel alpha value.
-
-.. data:: BLEND_RGBA_MULT
-
-   Used for an multiply blend, with the per-pixel alpha value.
-
-.. data:: BLEND_RGBA_AND
-
-   Used for a binary AND'd blend, with the per-pixel alpha value.
-
-.. data:: BLEND_RGBA_OR
-
-   Used for a binary OR'd  blend, with the per-pixel alpha value.
-
-.. data:: BLEND_RGBA_XOR
-
-   Used for a binary XOR'd blend, with the per-pixel alpha value.
-
-.. data:: BLEND_RGBA_MIN
-
-   Used for a minimum blend, with the per-pixel alpha value.
-
-.. data:: BLEND_RGBA_MAX
-
-   Used for a maximum blend, with the per-pixel alpha value.
-
-.. data:: BLEND_RGBA_AVG
-
-   Used for an average blend, with the per-pixel alpha value.
-
-.. data:: BLEND_RGBA_DIFF
-
-   Used for a difference blend, with the per-pixel alpha value.
-
-.. data:: BLEND_RGBA_SCREEN
-
-   Used for a screen blend, with the per-pixel alpha value.
-
-CD-ROM Constants
-----------------
-
-The following constants are used by the :mod:`pygame2.sdl.cdrom` module.
-
-.. data:: MAX_TRACKS
-
-   The maximum amount of tracks to manage on a CD-ROM.
-
-The following constants are used by the :attr:`pygame2.sdl.cdrom.CDTrack.type`
-attribute.
-
-.. data:: AUDIO_TRACK
-
-   Indicates an audio track.
-
-.. data:: DATA_TRACK
-
-   Indicates a data track.
-
-The following constants are used by the :attr:`pygame2.sdl.cdrom.CD.status`
-attribute:
-
-.. data:: CD_TRAYEMPTY
-
-   Indicates that no CD-ROM is in the tray.
-
-.. data:: CD_STOPPED
-
-   Indicates that the CD playback has been stopped.
-
-.. data:: CD_PLAYING
-
-   Indicates that the CD is currently playing a track.
-
-.. data:: CD_PAUSED
-
-   Indicates that the CD playback has been paused.
-
-.. data:: CD_ERROR
-
-   Indicates an error on accessing the CD.
-
-Event Constants
----------------
-
-Those constants are used by the :mod:`pygame2.sdl.event` module
-functions.
-
-.. data:: NOEVENT
-
-   Indicates no event.
-
-.. data:: NUMEVENTS
-
-   The maximum amount of event types allowed to be used.
-
-.. data:: ACTIVEEVENT
-
-   Raised, when the SDL application state changes.
-
-.. data:: KEYDOWN
-
-   Raised, when a key is pressed down.
-
-.. data:: KEYUP
-
-   Raised, when a key is released.
-
-.. data:: MOUSEMOTION
-
-   Raised, when the mouse moves.
-
-.. data:: MOUSEBUTTONDOWN
-
-   Raised, when a mouse button is pressed down.
-
-.. data:: MOUSEBUTTONUP
-
-   Raised, when a mouse button is released.
-
-.. data:: JOYAXISMOTION
-
-   Raised, when a joystick axis moves.
-
-.. data:: JOYBALLMOTION
-
-   Raised, when a trackball on a joystick moves.
-
-.. data:: JOYHATMOTION
-
-   Raised, when a hat on a joystick moves.
-
-.. data:: JOYBUTTONDOWN
-
-   Raised, when a joystick button is pressed down.
-
-.. data:: JOYBUTTONUP
-
-   Raised, when a joystick button is released.
-
-.. data:: QUIT
-
-   Raised, when the SDL application window shall be closed.
-
-.. data:: SYSWMEVENT
-
-   Raised, when an unknown, window manager specific event occurs.
-
-.. data:: VIDEORESIZE
-
-   Raised, when the SDL application window shall be resized.
-
-.. data:: VIDEOEXPOSE
-
-   Raised, when the screen has been modified outside of the SDL
-   application and the SDL application window needs to be redrawn.
-
-.. data:: USEREVENT
-
-   Raised, when a user-specific event occurs.
-
-Application Constants
----------------------
-
-Those constants are used by the :data:`ACTIVEEVENT` event and the
-:func:`pygame2.sdl.event.get_app_state` method.
-
-.. data:: APPACTIVE
-
-   Indicates that that the SDL application is currently active.
-
-.. data:: APPINPUTFOCUS
-
-   Indicates that the SDL application has the keyboard input focus.
-
-.. data:: APPMOUSEFOCUS
-
-   Indicates that the SDL application has the mouse input focus.
-
-Keyboard Constants
-------------------
-
-The following constants are used by the :func:`pygame2.sdl.keyboard.set_repeat`
-function:
-
-.. data:: DEFAULT_REPEAT_DELAY
-
-   The default delay before starting to repeat raising :data:`KEYDOWN` event
-   on pressing a key down.
-
-.. data:: DEFAULT_REPEAT_INTERVAL
-
-   The default interval for raising :data:`KEYDOWN` events on pressing a key
-   down.
-
-The following constants are used by the :func:`pygame2.sdl.keyboard.get_state`
-and :func:`pygame2.sdl.keyboard.get_key_name` functions and the :data:`KEYDOWN`
-and :data:`KEYUP` events.
-
-+-------------------+-------------------------------------------------------+
-| Constant          | Meaning and Value                                     |
-+===================+=======================================================+
-| K_UNKNOWN         | An unknown key.                                       |
-+-------------------+-------------------------------------------------------+
-| K_a - K_z         | Alphabetical keys ranging from a to z. There is no    |
-|                   | captalised version of them. Instead the keyboard      |
-|                   | modifier state can be checked for :data:`KMOD_SHIFT`  |
-|                   | being set.                                            |
-+-------------------+-------------------------------------------------------+
-| K_0 - K_9         | Numerical keys ranging from 0 to 9. Those differ from |
-|                   | the numerical keys on the keypad.                     |
-+-------------------+-------------------------------------------------------+
-| K_TAB, K_SPACE,   | Tabulator, Space, Exclamation Mark, Hash, Double      |
-| K_EXCLAIM, K_HASH,| Quote, Dollar sign, Single Quote, Ampersand, Left     |
-| K_QUOTEDBL,       | and Right Parenthesis, Asterisk, Plus and Minus,      |
-| K_DOLLAR, K_QUOTE,| Comma, Period, Slash and Backslash, Colon and         |
-| K_AMPERSAND,      | Semicolon, Question Mark, At sign, Left and Right     |
-| K_LEFTPAREN,      | Bracket, Caret, Underscore and Backquote keys.        |
-| K_RIGHTPAREN,     |                                                       |
-| K_ASTERISK,       |                                                       |
-| K_PLUS, K_MINUS,  |                                                       |
-| K_COMMA, K_PERIOD,|                                                       |
-| K_SLASH,          |                                                       |
-| K_BACKSLASH,      |                                                       |
-| K_COLON,          |                                                       |
-| K_SEMICOLON,      |                                                       |
-| K_QUESTION, K_AT, |                                                       |
-| K_LEFTBRACKET,    |                                                       |
-| K_RIGHTBRACKET,   |                                                       |
-| K_CARET,          |                                                       |
-| K_UNDERSCORE,     |                                                       |
-| K_BACKQUOTE       |                                                       |
-+-------------------+-------------------------------------------------------+
-| K_LESS, K_GREATER,| Less, Greater and Equality sign keys.                 |
-| K_EQUALS          |                                                       |
-+-------------------+-------------------------------------------------------+
-| K_F1 - K_F15      | Function keys from F1 to F15.                         |
-+-------------------+-------------------------------------------------------+
-| K_HOME, K_END,    | Home and End, Insert and Delete, PageUp and PageDown  |
-| K_INSERT,         | and Backspace keys.                                   |
-| K_DELETE,         |                                                       |
-| K_PAGEUP,         |                                                       |
-| K_PAGEDOWN,       |                                                       |
-| K_BACKSPACE       |                                                       |
-+-------------------+-------------------------------------------------------+
-| K_LEFT, K_RIGHT,  | Cursor keys.                                          |
-| K_DOWN, K_UP      |                                                       |
-+-------------------+-------------------------------------------------------+
-| K_KP0 - K_KP9     | Numerical keys on the keypad, ranging from 0 to 9.    |
-+-------------------+-------------------------------------------------------+
-| K_KP_PERIOD,      | Period, Divide, Multiply, Plus, Minus, Equal sign and |
-| K_KP_DIVIDE,      | the Enter key on the keypad.                          |
-| K_KP_MULTIPLY,    |                                                       |
-| K_KP_MINUS,       |                                                       |
-| K_KP_PLUS,        |                                                       |
-| K_KP_EQUALS,      |                                                       |
-| K_KP_ENTER        |                                                       |
-+-------------------+-------------------------------------------------------+
-| K_HELP, K_PRINT,  | Help, Print, SysReq, Break, Menu, Power, Euro sign,   |
-| K_SYSREQ, K_BREAK,| First and Last keys.                                  |
-| K_MENU, K_POWER,  |                                                       |
-| K_EURO, K_FIRST,  |                                                       |
-| K_LAST            |                                                       |
-+-------------------+-------------------------------------------------------+
-| K_ESCAPE, K_PAUSE,| Escape, Pause and Clear keys.                         |
-| K_CLEAR           |                                                       |
-+-------------------+-------------------------------------------------------+
-| K_NUMLOCK,        | NumLock, CapsLock and ScrolLock keys.                 |
-| K_CAPSLOCK,       |                                                       |
-| K_SCROLLOCK       |                                                       |
-+-------------------+-------------------------------------------------------+
-| K_RSHIFT,         | Right and Left Shift, Right and Left Control, Right   |
-| K_LSHIFT, K_RCTRL,| and Left Alternative, Right and Left Meta, Right and  |
-| K_LCTRL, K_RALT,  | Left Super and Mode keys.                             |
-| K_LALT, K_RMETA,  |                                                       |
-| K_LMETA, K_LSUPER,|                                                       |
-| K_RSUPER, K_MODE  |                                                       |
-+-------------------+-------------------------------------------------------+
-
-The following constants are keyboard modifer states, used as bitwise
-combinations to check, whether they were hold down on keyboard
-input. They are used by the :func:`pygame2.sdl.keyboard.get_mod_state` and
-:func:`pygame2.sdl.keyboard.set_mod_state` functions.
-
-+-------------------+-------------------------------------------------------+
-| Constant          | Meaning and Value                                     |
-+===================+=======================================================+
-| KMOD_NONE         | No modifier key was pressed.                          |
-+-------------------+-------------------------------------------------------+
-| KMOD_LSHIFT,      | Left Shift, Right Shift or one of both was pressed.   |
-| KMOD_RSHIFT,      |                                                       |
-| KMOD_SHIFT        |                                                       |
-+-------------------+-------------------------------------------------------+
-| KMOD_LCTRL,       | Left Control, Right Contro or one of both was pressed.|
-| KMOD_RCTRL,       |                                                       |
-| KMOD_CTRL         |                                                       |
-+-------------------+-------------------------------------------------------+
-| KMOD_LALT,        | Left Alternative, Right Alternative or one of both    |
-| KMOD_RALT,        | was pressed.                                          |
-| KMOD_ALT          |                                                       |
-+-------------------+-------------------------------------------------------+
-| KMOD_LMETA,       | Left Meta, Right Met or one of both was pressed.      |
-| KMOD_RMETA,       |                                                       |
-| KMOD_META         |                                                       |
-+-------------------+-------------------------------------------------------+
-| KMOD_NUM,         | NumLock, CapsLock or Mode was pressed.                |
-| KMOD_CAPS,        |                                                       |
-| KMOD_MODE         |                                                       |
-+-------------------+-------------------------------------------------------+
-
-Various Constants
------------------
-
-.. data:: BYTEORDER
-
-   The byteorder, SDL and pygame2.sdl were compiled with. It is set to either
-   :data:`LIL_ENDIAN` or :data:`BIG_ENDIAN`.
-
-.. data:: LIL_ENDIAN
-
-   Indicates a little endian byte order.
-
-.. data:: BIG_ENDIAN
-    
-   Indicates a big endian byte order.

doc/ref/tests.rst

-:mod:`pygame2.test` -- unit tests for Pygame2
-=============================================
-
-This package contains the unit tests for Pygame2. You can execute the
-unit tests using ::
-
-    python -m pygame2.test
       <desc>
         Writes raw data to the :class:`BufferProxy`.
 
-        Writes the raw data from buffer to the :class:`BufferProxy` object,
-        starting at the specified offset within the :class:`BufferProxy`. If
-        the length of the passed buffer exceeds the length of the
-        :class:`BufferProxy` (reduced by the offset), an :exc:`IndexError` will
+        Writes the raw data from *buffer* to the :class:`BufferProxy` object,
+        starting at the specified *offset* within the :class:`BufferProxy`. If
+        the length of the passed *buffer* exceeds the length of the
+        :class:`BufferProxy` (reduced by *offset*), an :exc:`IndexError` will
         be raised.
       </desc>
     </method>
       values to differ slightly from what you might expect.</desc>
     </attr>
     <method name="normalize">
-      <call>normalize() -> tuple</call>
+      <call>normalize() -> (float, float, float, float)</call>
       <desc>
         Returns the normalized RGBA values of the :class:`Color`.
 
   <class name="Error">
     <constructor>Error (...) -> Error</constructor>
     <desc>
-      A specialized exception class that indicates a misbehaviour within the
+      A specialized exception class that indicates a misbehavior within the
       pygame2 modules.
     </desc>
   </class>
       :class:`FRect`.</desc>
     </attr>
     <method name="clamp">
-      <call>clamp (FRect) -> FRect</call>
+      <call>clamp (frect) -> FRect</call>
       <desc>
         Moves the rectangle inside another.
 
       </desc>
     </method>
     <method name="clamp_ip">
-      <call>clamp_ip (FRect) -> None</call>
+      <call>clamp_ip (frect) -> None</call>
       <desc>
         Moves the rectangle inside another, in place.
 
-        Same as FRect.clamp(FRect), but operates in place.
+        Same as :meth:`clamp`, but operates in place.
       </desc>
     </method>
     <method name="clip">
-      <call>clip (FRect) -> FRect</call>
+      <call>clip (frect) -> FRect</call>
       <desc>
         Crops a rectangle inside another.
 
       <desc>
         Test if one rectangle in a dictionary intersects.
 
-        Returns the key and value of the first dictionary value that
+        Returns the key and value of the first dictionary entry that
         collides with the :class:`FRect`. If no collisions are found,
         None is returned. Depending on the *checkvals* argument either the
-        keys or values of the dict must be :class:`FRect` objects. By
-        default, the keys are checked.
+        keys or values of *dict* must be :class:`FRect` objects. By default,
+        the keys are checked.
 
         You can provide your own comparision function as *key*
-        argument. The comparision function will take two args, the
-        :class:`FRect` itself and an key or value from the passed
+        argument. The comparision function will take two arguments, the
+        :class:`FRect` itself and a key or value from the passed
         dictionary. It must return True or False ::
         
           def cmpfunc (rect1, rect2):
         default, the keys are checked.
 
         You can provide your own comparision function as *key*
-        argument. The comparision function will take two args, the
-        :class:`FRect` itself and an key or value from the passed
+        argument. The comparision function will take two arguments, the
+        :class:`FRect` itself and a key or value from the passed
         dictionary. It must return True or False ::
 
           def cmpfunc (rect1, rect2):
       </desc>
     </method>
     <method name="collidelist">
-      <call>collidelist (rects[, key]) -> index</call>
+      <call>collidelist (rects[, key]) -> int</call>
       <desc>
         Test if one rectangle in a list intersects.
 
         returned. If no collisions are found an index of -1 is returned.
 
         You can provide your own comparision function as *key*
-        argument. The comparision function will take two args, the
-        :class:`FRect` itself and an key or value from the passed
+        argument. The comparision function will take two arguments, the
+        :class:`FRect` itself and a key or value from the passed
         dictionary. It must return True or False ::
 
           def cmpfunc (rect1, rect2):
       </desc>
     </method>
     <method name="collidelistall">
-      <call>collidelistall (rects[, key]) -> [index, ...]</call>
+      <call>collidelistall (rects[, key]) -> [int, ...]</call>
       <desc>
         Test if all rectangles in a list intersect.
 
         are found, an empty list is returned.
 
         You can provide your own comparision function as *key*
-        argument. The comparision function will take two args, the
-        :class:`FRect` itself and an key or value from the passed
+        argument. The comparision function will take two arguments, the
+        :class:`FRect` itself and a key or value from the passed
         dictionary. It must return True or False ::
 
           def cmpfunc (rect1, rect2):
       </desc>
     </method>
     <method name="collidepoint">
-      <call>collidepoint (x, y) -> bool</call>
+      <call>collidepoint (x, y) -> bool
+        collidepoint (point) -> bool</call>
       <desc>
         Test if a point is inside a rectangle.
 
-        Returns true if the given point is inside the rectangle. A point
+        Returns True if the given *point* is inside the rectangle. A point
         along the right or bottom edge is not considered to be inside
         the rectangle.
       </desc>
     </method>
     <method name="colliderect">
-      <call>colliderect (FRect) -> bool</call>
+      <call>colliderect (frect) -> bool</call>
       <desc>
         Test if two rectangles overlap.
 
-        Returns true if any portion of either rectangle overlap (except
+        Returns True if any portion of either rectangle overlap (except
         the top+bottom or left+right edges).
       </desc>
     </method>
     <method name="contains">
-      <call>contains (FRect) -> bool</call>
+      <call>contains (frect) -> bool</call>
       <desc>
         Test if one rectangle is inside another.
 
-        Returns true when the argument rectangle is completely inside
+        Returns True when the argument rectangle is completely inside
         the :class:`FRect`.
       </desc>
     </method>
       </desc>
     </method>
     <method name="fit">
-      <call>fit (FRect) -> FRect</call>
+      <call>fit (frect) -> FRect</call>
       <desc>
         Resize and move a rectangle with aspect ratio.
 
       <desc>Gets or sets the height of the :class:`FRect`.</desc>
     </attr>
     <method name="inflate">
-      <call>inflate (x, y) -> FRect</call>
+      <call>inflate (x, y) -> FRect
+        inflate (size) -> FRect</call>
       <desc>
         Grow or shrink the rectangle size.
 
       </desc>
     </method>
     <method name="inflate_ip">
-      <call>inflate_ip (x, y) -> None</call>
+      <call>inflate_ip (x, y) -> None
+        inflate_ip (size) -> None</call>
       <desc>
         Grow or shrink the rectangle size, in place.
 
-        Same as FRect.inflate(x, y), but operates in place.
+        Same as :meth:`inflate`, but operates in place.
       </desc>
     </method>
     <attr name="left">
       <desc>Gets or sets the mid top edge position of the :class:`FRect`.</desc>
     </attr>
     <method name="move">
-      <call>move (x, y) -> FRect</call>
+      <call>move (x, y) -> FRect
+        move (point) -> FRect</call>
       <desc>
         Moves the rectangle.
 
-        Returns a new rectangle that is moved by the given offset. The x
-        and y arguments can be any integer value, positive or negative.
+        Returns a new rectangle that is moved by the given offset. The *x*
+        and *y* arguments can be any float or integer value, positive or
+        negative.
       </desc>
     </method>
     <method name="move_ip">
-      <call>move_ip (x, y) -> None</call>
+      <call>move_ip (x, y) -> None
+        move_ip (point) -> FRect</call>
       <desc>
         Moves the rectangle, in place.
 
-        Same as FRect.move (x, y), but operates in place.
+        Same as :meth:`move`, but operates in place.
       </desc>
     </method>
     <attr name="right">
       </desc>
     </method>
     <method name="union">
-      <call>union (FRect) -> FRect</call>
+      <call>union (frect) -> FRect</call>
       <desc>
         Joins two rectangles into one.
 
       </desc>
     </method>
     <method name="union_ip">
-      <call>union_ip (FRect) -> FRect</call>
+      <call>union_ip (frect) -> FRect</call>
       <desc>
         Joins two rectangles into one, in place.
 
-        Same as FRect.union(FRect), but operates in place.
+        Same as :meth:`union`, but operates in place.
       </desc>
     </method>
     <attr name="w">
     <constructor>Rect (...) -> Rect</constructor>
     <desc>A class for storing rectangular coordinates.
 
-    A :class:`Rect` is used to store and manipulate rectangular
-    coordinates.
+      A :class:`Rect` is used to store and manipulate rectangular coordinates.
     </desc>
     <attr name="bottom">
       <desc>Gets or sets the bottom edge position of the :class:`Rect`.</desc>
       :class:`Rect`.</desc>
     </attr>
     <method name="clamp">
-      <call>clamp (Rect) -> Rect</call>
+      <call>clamp (rect) -> Rect</call>
       <desc>
         Moves the rectangle inside another.
 
       </desc>
     </method>
     <method name="clamp_ip">
-      <call>clamp_ip (Rect) -> None</call>
+      <call>clamp_ip (rect) -> None</call>
       <desc>
         Moves the rectangle inside another, in place.
 
-        Same as Rect.clamp(Rect), but operates in place.
+        Same as :meth:`clamp`, but operates in place.
       </desc>
     </method>
     <method name="clip">
-      <call>clip (Rect) -> Rect</call>
+      <call>clip (rect) -> Rect</call>
       <desc>
         Crops a rectangle inside another.
 
       <desc>
         Test if one rectangle in a dictionary intersects.
 
-        Returns the key and value of the first dictionary value that
+        Returns the key and value of the first dictionary entry that
         collides with the :class:`Rect`. If no collisions are found,
         None is returned. Depending on the *checkvals* argument either the
-        keys or values of the dict must be :class:`Rect` objects. By
+        keys or values of the *dict* must be :class:`Rect` objects. By
         default, the keys are checked.
 
         You can provide your own comparision function as *key*
-        argument. The comparision function will take two args, the
-        :class:`FRect` itself and an key or value from the passed
+        argument. The comparision function will take two arguments, the
+        :class:`Rect` itself and a key or value from the passed
         dictionary. It must return True or False ::
 
           def cmpfunc (rect1, rect2):
         Returns a list of all the key and value pairs that intersect
         with the :class:`Rect`. If no collisions are found an empty list
         is returned. Depending on the *checkvals* argument either the keys
-        or values of the dict must be :class:`Rect` objects. By default,
+        or values of the *dict* must be :class:`Rect` objects. By default,
         the keys are checked.
 
         You can provide your own comparision function as *key*
-        argument. The comparision function will take two args, the
-        :class:`FRect` itself and an key or value from the passed
+        argument. The comparision function will take two arguments, the
+        :class:`Rect` itself and an key or value from the passed
         dictionary. It must return True or False ::
 
           def cmpfunc (rect1, rect2):
       </desc>
     </method>
     <method name="collidelist">
-      <call>collidelist (list[, key]) -> index</call>
+      <call>collidelist (list[, key]) -> int</call>
       <desc>
         Test if one rectangle in a list intersects.
 
         returned. If no collisions are found an index of -1 is returned.
 
         You can provide your own comparision function as *key*
-        argument. The comparision function will take two args, the
-        :class:`FRect` itself and an key or value from the passed
+        argument. The comparision function will take two arguments, the
+        :class:`Rect` itself and an key or value from the passed
         dictionary. It must return True or False ::
 
           def cmpfunc (rect1, rect2):
       </desc>
     </method>
     <method name="collidelistall">
-      <call>collidelistall (list[, key]) -> [index, ...]</call>
+      <call>collidelistall (list[, key]) -> [int, ...]</call>
       <desc>
         Test if all rectangles in a list intersect.
 
         an empty list is returned.
 
         You can provide your own comparision function as *key*
-        argument. The comparision function will take two args, the
-        :class:`FRect` itself and an key or value from the passed
+        argument. The comparision function will take two arguments, the
+        :class:`Rect` itself and an key or value from the passed
         dictionary. It must return True or False ::
 
           def cmpfunc (rect1, rect2):
       </desc>
     </method>
     <method name="collidepoint">
-      <call>collidepoint (x, y) -> bool</call>
+      <call>collidepoint (x, y) -> bool
+        collidepoint (point) -> bool</call>
       <desc>
         Test if a point is inside a rectangle.
 
-        Returns true if the given point is inside the rectangle. A point
+        Returns True if the given point is inside the rectangle. A point
         along the right or bottom edge is not considered to be inside
         the rectangle.
       </desc>
     </method>
     <method name="colliderect">
-      <call>colliderect (Rect) -> bool</call>
+      <call>colliderect (rect) -> bool</call>
       <desc>
         Test if two rectangles overlap.
 
-        Returns true if any portion of either rectangle overlap (except
+        Returns True if any portion of either rectangle overlap (except
         the top+bottom or left+right edges).
       </desc>
     </method>
     <method name="contains">
-      <call>contains (Rect) -> bool</call>
+      <call>contains (rect) -> bool</call>
       <desc>
         Test if one rectangle is inside another.
 
-        Returns true when the argument rectangle is completely inside
+        Returns True when the argument rectangle is completely inside
         the :class:`Rect`.
       </desc>
     </method>
       </desc>
     </method>
     <method name="fit">
-      <call>fit (Rect) -> Rect</call>
+      <call>fit (rect) -> Rect</call>
       <desc>
         Resize and move a rectangle with aspect ratio.
 
       <desc>Gets or sets the height of the :class:`Rect`.</desc>
     </attr>
     <method name="inflate">
-      <call>inflate (x, y) -> Rect</call>
+      <call>inflate (x, y) -> Rect
+        inflate (size) -> Rect</call>
       <desc>
         Grow or shrink the rectangle size.
 
       </desc>
     </method>
     <method name="inflate_ip">
-      <call>inflate_ip (x, y) -> None</call>
+      <call>inflate_ip (x, y) -> None
+        inflate_ip (size) -> Rect</call>
       <desc>
         Grow or shrink the rectangle size, in place.
 
-        Same as Rect.inflate(x, y), but operates in place.
+        Same as :meth:`inflate`, but operates in place.
       </desc>
     </method>
     <attr name="left">
       :class:`Rect`.</desc>
     </attr>
     <method name="move">
-      <call>move (x, y) -> Rect</call>
+      <call>move (x, y) -> Rect
+        move (point) -> Rect</call>
       <desc>
         Moves the rectangle.
 
-        Returns a new rectangle that is moved by the given offset. The x
-        and y arguments can be any integer value, positive or negative.
+        Returns a new rectangle that is moved by the given offset. The *x*
+        and *y* arguments can be any integer value, positive or negative.
       </desc>
     </method>
     <method name="move_ip">
-      <call>move_ip (x, y) -> None</call>
+      <call>move_ip (x, y) -> None
+        move_ip (point) -> None</call>
       <desc>
         Moves the rectangle, in place.
 
-        Same as Rect.move (x, y), but operates in place.
+        Same as :meth:`move`, but operates in place.
       </desc>
     </method>
     <attr name="right">
       :class:`Rect`.</desc>
     </attr>
     <method name="union">
-      <call>union (Rect) -> Rect</call>
+      <call>union (rect) -> Rect</call>
       <desc>
         Joins two rectangles into one.
 
       </desc>
     </method>
     <method name="union_ip">
-      <call>union_ip (Rect) -> Rect</call>
+      <call>union_ip (rect) -> Rect</call>
       <desc>
         Joins two rectangles into one, in place.
 
-        Same as Rect.union(Rect), but operates in place.
+        Same as :meth:`union`, but operates in place.
       </desc>
     </method>
     <attr name="w">
       <desc>
         Performs a blit operation on the :class:`Surface`.
 
-        The behaviour, arguments and return value depend on the concrete
+        The behavior, arguments and return value depend on the concrete
         :class:`Surface` implementation.
       </desc>
     </method>

doc/src/colorpalettes.xml

   <alias>pygame2.colorpalettes</alias>
   <short>Various, indexed color palettes</short>
   <desc>
-    Indexed color palettes. The following palettes are currently
-    available:
+    Indexed color palettes. Each palette is a tuple of :class:`pygame2.Color`.
+    The following palettes are currently available:
 
     +--------------------+---------------------------------------------------+
     | MONOPALETTE        | 1-bit monochrome palette (black and white).       |

doc/src/examples.rst

+:mod:`pygame2.examples` -- examples for Pygame2
+===============================================
+
+Examples package for Pygame2.
+
+This package contains code snippets demonstrating the aspects of the
+various Pygame2 modules. Each example is a module of its own and can be
+easily executed using ::
+
+    python -m pygame2.examples.<module>.<example>
+
+To run the drawing pygame2.sdlext example, you would type ::
+
+    python -m pygame2.examples.sdlext.draw
+
+Currently the following examples exists:
+
++------------------------------------+----------------------------------------+
+| Example                            | Description                            |
++====================================+========================================+
+| pygame2.examples.import            | Simple import example for all Pygame2  |
+|                                    | modules.                               |
++------------------------------------+----------------------------------------+
+| pygame2.examples.py2exe_setup      | Win32 standalone executable creation   |
+|                                    | example using Pygame2.                 |
++------------------------------------+----------------------------------------+
+| pygame2.examples.physics.simple    | Simple physics example                 |
++------------------------------------+----------------------------------------+
+| pygame2.examples.sdl.cdrom         | Demonstrates the features of the       |
+|                                    | :mod:`pygame2.sdl.cdrom` module.       |
++------------------------------------+----------------------------------------+
+| pygame2.examples.sdl.hello_world   | The almighty "Hello World" example     |
+|                                    | using the :mod:`pygame2.sdl` module.   |
++------------------------------------+----------------------------------------+
+| pygame2.examples.sdl.keyboard      | Demonstrates keyboard input and event  |
+|                                    | handling for the                       |
+|                                    | :mod:`pygame2.sdl.keyboard` module.    |
++------------------------------------+----------------------------------------+
+| pygame2.examples.sdl.mouse         | Demonstrates mouse input and event     |
+|                                    | handling for the                       |
+|                                    | :mod:`pygame2.sdl.mouse` module.       |
++------------------------------------+----------------------------------------+
+| pygame2.examples.sdl.surface_blit  | Demonstrates supported blitting        |
+|                                    | operations for                         |
+|                                    | :class:`pygame2.sdl.video.Surface`     |
+|                                    | objects.                               |
++------------------------------------+----------------------------------------+
+| pygame2.examples.sdl.surface_fill  | Demonstrates supported filling         |
+|                                    | operations for                         |
+|                                    | :class:`pygame2.sdl.video.Surface`     |
+|                                    | objects.                               |
++------------------------------------+----------------------------------------+
+| pygame2.examples.sdlext.draw       | Demonstrates the features of the       |
+|                                    | :mod:`pygame2.sdlext.draw` module.     |
++------------------------------------+----------------------------------------+
+| pygame2.examples.sdlext.pixelarray | Demonstrates the features of the       |
+|                                    | :class:`pygame2.sdlext.PixelArray`     |
+|                                    | class.                                 |
++------------------------------------+----------------------------------------+
     <desc>
       Finds a font matching a certain family or font filename.
 
-      Tries to find a font that matches the passed requirements
-      best. The *name* argument denotes a specific font or font family
-      name. If multiple fonts match that name, the *bold* and *italic*
-      arguments are used to find a font that matches the requirements
-      best. *ftype* is an optional font filetype argument to request
-      specific font file types, such as bdf or ttf fonts.
+      Tries to find a font that matches the passed requirements best. The
+      *name* argument denotes a specific font or font family name. If multiple
+      fonts match that name, the *bold* and *italic* arguments are used to find
+      a font that matches the requirements best. *ftype* is an optional font
+      filetype argument to request specific font file types, such as bdf or ttf
+      fonts.
     </desc>
     <example></example>
   </func>
   <class name="Mask">
     <constructor>Mask (width, height) -> Mask
     Mask (size) -> Mask</constructor>
-    <desc>Creates a new :class:`Mask` object with the specified width
-    and height
+    <desc>
+      Creates a new :class:`Mask` object with the specified width and height.
     </desc>
     <attr name="angle">
       <desc>Gets the orientation of the pixels. Finds the approximate
       of pixels. It will return 0.0 on an empty :class:`Mask`.</desc>
     </attr>
     <attr name="centroid">
-      <desc>Gets the centroid, the center of pixel mass, of the pixels
-      in a :class:`Mask`.  Returns a coordinate tuple for the centroid
-      of the :class:`Mask`. if the :class:`Mask` is empty, it will
-      return (0,0).</desc>
+      <desc>
+        Gets the centroid, the center of pixel mass, of the pixels
+        in a :class:`Mask`. Returns a coordinate tuple for the centroid
+        of the :class:`Mask`. If the :class:`Mask` is empty, it will return
+        (0, 0).
+      </desc>
     </attr>
     <method name="clear">
       <call>clear () -> None</call>
 
         Returns a :class:`Mask` with the [x-offset[0], y-offset[1]] bit
         set if shifting *mask* so that it's lower right corner pixel is
-        at (x, y) would cause it to overlap with self.
+        at (*x*, *y*) would cause it to overlap with self.
 
         If an *outputmask* is specified, the output is drawn onto
         *outputmask* and *outputmask* is returned. Otherwise a mask of
         Draws the passed :class:`Mask` onto the :class:`Mask`.
         
         This performs a bitwise OR operation upon the calling
-        :class:`Mask`. The passed mask's start offset for the draw
-        operation will be the x and y offset passed to the method.
+        :class:`Mask`. The passed *mask*'s start offset for the draw
+        operation will be the *x* and *y* offset passed to the method.
       </desc>
     </method>
     <method name="erase">
         Erases the passed :class:`Mask` from the :class:`Mask`.
 
         This performs a bitwise NAND operation upon the calling
-        :class:`Mask`. The passed mask's start offset for the erase
-        operation will be the x and y offset passed to the method.
+        :class:`Mask`. The passed *mask*'s start offset for the erase
+        operation will be the *x* and *y* offset passed to the method.
       </desc>
     </method>
     <method name="fill">
         Gets the points outlining an object on the mask.
         
         Returns a list of points of the outline of the first object it
-        comes across in the :class:`Mask`.  For this to be useful, there
+        comes across in the :class:`Mask`. For this to be useful, there
         should probably only be one connected component of pixels in the
         :class:`Mask`. The *skip* option allows you to skip pixels in
         the outline. For example, setting it to 10 would return a list
       <desc>
         Returns the number of overlapping bits of two Masks.
 
-        This returns how many pixels overlap with the other mask given. It
+        This returns how many pixels overlap with the other *mask* given. It
         can be used to see in which direction things collide, or to see how
         much the two masks collide.
       </desc>
       <call>overlap_mask (mask, x, y) -> Mask
       overlap_mask (mask, point) -> Mask</call>
       <desc>
-        Returns a mask with the overlap of two other masks. A bitwise AND.
+        Returns a :class:`Mask` with the overlap of two other masks. A bitwise
+        AND.
       </desc>
     </method>
     <method name="scale">
       <call>scale (width, height) -> Mask
       scale (size) -> Mask</call>
       <desc>
-        Creates a new scaled :class:`Mask` with the given width and height.
+        Creates a new scaled :class:`Mask` with the given *width* and *height*.
 
         The quality of the scaling may not be perfect for all circumstances,
-        but it should be reasonable. If either w or h is 0 a clear 1x1 mask is
-        returned.
+        but it should be reasonable. If either *width* or *height* is 0 a clear
+        1x1 mask is returned.
       </desc>
     </method>
     <method name="set_at">
   <func name="from_surface">
     <call>from_surface (surface, threshold) -> Mask</call>
     <desc>
-      Returns a :class:`Mask` from the given pygame2.sdl.video.Surface.
+      Returns a :class:`Mask` from the given :class:`pygame2.sdl.video.Surface`.
 
-      Makes the transparent parts of the Surface not set, and the opaque parts
-      set. The alpha of each pixel is checked to see if it is greater than the
-      given threshold. If the Surface is color keyed, then threshold is not
+      Makes the transparent parts of the :class:`pygame2.sdl.video.Surface` not
+      set, and the opaque parts set. The alpha of each pixel is checked to see
+      if it is greater than the given *threshold*. If the
+      :class:`pygame2.sdl.video.Surface` is color keyed, then *threshold* is not
       used.
 
       This requires pygame2 to be built with SDL support enabled.
   <func name="from_threshold">
     <call>from_threshold (surface, color[, threshold, thressurface]) -> Mask</call>
     <desc>
-      Creates a mask by thresholding surfaces.
-
+      Creates a :class:`Mask` by thresholding surfaces.
 
       This is a more featureful method of getting a :class:`Mask` from a
-      Surface.  If supplied with only one Surface, all pixels within the
-      threshold of the supplied *color* are set in the Mask. If given
-      the optional *thressurface*, all pixels in *surface* that are
-      within the *threshold* of the corresponding pixel in
-      *thressurface* are set in the :class:`Mask`.
+      :class:`pygame2.sdl.video.Surface`. If supplied with only one
+      :class:`pygame2.sdl.video.Surface`, all pixels within the *threshold* of
+      the supplied *color* are set in the :class`Mask`. If given
+      the optional *thressurface*, all pixels in *surface* that are within the
+      *threshold* of the corresponding pixel in *thressurface* are set in the
+      :class:`Mask`.
     </desc>
   </func>
 </module>
-

doc/src/modules.rst

+####################
+Module Documentation
+####################
+
+This is the core documentation of the various modules, classes and
+functions, pygame2 offers. If you want a quick module overview, use the
+:ref:`modindex`. If you just want to look up a specific class, attribute
+method or function, use the :ref:`genindex` or :ref:`search`.
+
+General Notes for Reading
+=========================
+
+.. note::
+
+  Whenever the API documentation refers to file-like objects, those
+  *must* support binary read and write access. This is especially
+  important for Python 3.x users and the new :mod:`io` module.
+
+Modules
+=======
+
+.. toctree::
+   :maxdepth: 2
+
+   pygame2.rst
+   pygame2_colorpalettes.rst
+   pygame2_examples.rst
+   pygame2_font.rst
+   pygame2_freetype_base.rst
+   pygame2_mask.rst
+   pygame2_physics.rst
+   pygame2_sdl.rst
+   pygame2_sdl_audio.rst
+   pygame2_sdl_cdrom.rst
+   pygame2_sdl_constants.rst
+   pygame2_sdl_cursors.rst
+   pygame2_sdl_event.rst
+   pygame2_sdl_gl.rst
+   pygame2_sdl_image.rst
+   pygame2_sdl_joystick.rst
+   pygame2_sdl_keyboard.rst
+   pygame2_sdl_mouse.rst
+   pygame2_sdl_rwops.rst
+   pygame2_sdl_time.rst
+   pygame2_sdl_video.rst
+   pygame2_sdl_wm.rst
+   pygame2_sdlext.rst
+   pygame2_sdlext_draw.rst
+   pygame2_sdlext_fastevent.rst
+   pygame2_sdlext_font.rst
+   pygame2_sdlext_numericsurfarray.rst
+   pygame2_sdlext_numpysurfarray.rst
+   pygame2_sdlext_scrap.rst
+   pygame2_sdlext_surfarray.rst
+   pygame2_sdlext_transform.rst
+   pygame2_sdlgfx.rst
+   pygame2_sdlgfx_primitives.rst
+   pygame2_sdlgfx_rotozoom.rst
+   pygame2_sdlimage.rst
+   pygame2_sdlmixer.rst
+   pygame2_sdlmixer_channel.rst
+   pygame2_sdlmixer_music.rst
+   pygame2_sdlmixer_numericsndarray.rst
+   pygame2_sdlttf.rst
+   pygame2_sdlttf_constants.rst
+   pygame2_sdlttf_sysfont.rst
+   pygame2_tests.rst

doc/src/sdl_constants.rst

+:mod:`pygame2.sdl.constants` -- Constants for SDL
+=================================================
+
+This module contains the constants used throughout the :mod:`pygame2.sdl`
+modules.
+
+.. module:: pygame2.sdl.constants
+   :synopsis: Constants used throughout the :mod:`pygame2.sdl` modules.
+
+Initialisation Constants
+------------------------
+
+Those constants are used by the :func:`pygame2.sdl.init`,
+:func:`pygame2.sdl.init_subsystem` and :func:`pygame2.sdl.quit_subsystem`
+functions.
+
+.. data:: INIT_AUDIO
+
+   Initialises the SDL audio subsystem.
+
+.. data:: INIT_CDROM
+
+   Initialises the SDL cdrom subsystem.
+
+.. data:: INIT_TIMER
+
+   Initialises the SDL timer subsystem.
+
+.. data:: INIT_JOYSTICK
+
+   Initialises the SDL joystick subsystem.
+
+.. data:: INIT_VIDEO
+
+   Initialises the SDL video subsystem.
+
+.. data:: INIT_EVERYTHING
+
+   Initialises all parts of the SDL subsystems.
+
+.. data:: INIT_NOPARACHUTE
+
+   Initialises the SDL subsystems without a segmentation fault parachute.
+
+.. data:: INIT_EVENTTHREAD
+
+   Initialises the SDL event subsystem with threading support.
+
+Blending Constants
+------------------
+
+Those constants are used by the :meth:`pygame2.sdl.video.Surface.blit`
+and :meth:`pygame2.sdl.video.Surface.fill` methods.
+
+If not stated otherwise, each of the modes will work on a per-channel basis,
+so that the described operation is performed on each RGB(A) color component.
+This means that e.g. BLEND_RGB_ADD performs some operation similar to
+(R1 + R1, G1 + G2, B1 + B2).
+
+.. data:: BLEND_RGB_ADD
+
+   Used for an additive blend, ignoring the per-pixel alpha value. The sum of
+   the both RGB values will used for the result.
+
+.. data:: BLEND_RGB_SUB
+
+   Used for an subtractive blend, ignoring the per-pixel alpha value. The
+   difference of both RGB values will be used for the result. If the difference
+   is smaller than 0, it will be set to 0.
+
+.. data:: BLEND_RGB_MULT
+
+   Used for an multiply blend, ignoring the per-pixel alpha value. The
+   both RGB values will be multiplied with each other, causing the result
+   to be darker.
+
+.. data:: BLEND_RGB_AND
+
+   Used for a binary AND'd blend, ignoring the per-pixel alpha value.
+   The bitwise AND combination of both RGB values will be used for the result.
+
+.. data:: BLEND_RGB_OR
+
+   Used for a binary OR'd  blend, ignoring the per-pixel alpha value.
+   The bitwise OR combination of both RGB values will be used for the result.
+
+.. data:: BLEND_RGB_XOR
+
+   Used for a binary XOR'd blend, ignoring the per-pixel alpha value.
+   The bitwise XOR combination of both RGB values will be used for the result.
+   
+.. data:: BLEND_RGB_MIN
+
+   Used for a minimum blend, ignoring the per-pixel alpha value. The minimum
+   of both RGB values will be used for the result.
+
+.. data:: BLEND_RGB_MAX
+
+   Used for a maximum blend, ignoring the per-pixel alpha value. The maximum
+   of both RGB values will be used for the result.
+
+.. data:: BLEND_RGB_AVG
+
+   Used for an average blend, ignoring the per-pixel alpha value. The average
+   of an addition of both RGB values will be used for the result.
+
+.. data:: BLEND_RGB_DIFF
+
+   Used for a difference blend, ignoring the per-pixel alpha value. The real
+   difference of both RGB values will be used for the result.
+
+.. data:: BLEND_RGB_SCREEN
+
+   Used for a screen blend, ignoring the per-pixel alpha value. The
+   inverted multiplication result of the inverted RGB values will be used,
+   causing the result to be brighter.
+
+.. data:: BLEND_RGBA_ADD
+
+   Used for an additive blend, with the per-pixel alpha value. The sum of
+   the both RGBA values will used for the result.
+
+.. data:: BLEND_RGBA_SUB
+
+   Used for an subtractive blend, with the per-pixel alpha value. The
+   difference of both RGBA values will be used for the result. If the difference
+   is smaller than 0, it will be set to 0.
+
+.. data:: BLEND_RGBA_MULT
+
+   Used for an multiply blend, with the per-pixel alpha value. The
+   both RGBA values will be multiplied with each other, causing the result
+   to be darker.
+
+.. data:: BLEND_RGBA_AND
+
+   Used for a binary AND'd blend, with the per-pixel alpha value.
+   The bitwise AND combination of both RGBA values will be used for the result.
+
+.. data:: BLEND_RGBA_OR
+
+   Used for a binary OR'd  blend, with the per-pixel alpha value.
+   The bitwise OR combination of both RGBA values will be used for the result.
+
+.. data:: BLEND_RGBA_XOR
+
+   Used for a binary XOR'd blend, with the per-pixel alpha value.
+   The bitwise XOR combination of both RGBA values will be used for the result.
+
+.. data:: BLEND_RGBA_MIN
+
+   Used for a minimum blend, with the per-pixel alpha value. The minimum
+   of both RGBA values will be used for the result.
+
+.. data:: BLEND_RGBA_MAX
+
+   Used for a maximum blend, with the per-pixel alpha value. The maximum
+   of both RGBA values will be used for the result.
+
+.. data:: BLEND_RGBA_AVG
+
+   Used for an average blend, with the per-pixel alpha value. The average
+   of an addition of both RGBA values will be used for the result.
+
+.. data:: BLEND_RGBA_DIFF
+
+   Used for a difference blend, with the per-pixel alpha value. The real
+   difference of both RGBA values will be used for the result.
+
+.. data:: BLEND_RGBA_SCREEN
+
+   Used for a screen blend, with the per-pixel alpha value. The
+   inverted multiplication result of the inverted RGBA values will be used,
+   causing the result to be brighter.
+
+CD-ROM Constants
+----------------
+
+The following constants are used by the :mod:`pygame2.sdl.cdrom` module.
+
+.. data:: MAX_TRACKS
+
+   The maximum amount of tracks to manage on a CD-ROM.
+
+The following constants are used by the :attr:`pygame2.sdl.cdrom.CDTrack.type`
+attribute.
+
+.. data:: AUDIO_TRACK
+
+   Indicates an audio track.
+
+.. data:: DATA_TRACK
+
+   Indicates a data track.
+
+The following constants are used by the :attr:`pygame2.sdl.cdrom.CD.status`
+attribute:
+
+.. data:: CD_TRAYEMPTY
+
+   Indicates that no CD-ROM is in the tray.
+
+.. data:: CD_STOPPED
+
+   Indicates that the CD playback has been stopped.
+
+.. data:: CD_PLAYING
+
+   Indicates that the CD is currently playing a track.
+
+.. data:: CD_PAUSED
+
+   Indicates that the CD playback has been paused.
+
+.. data:: CD_ERROR
+
+   Indicates an error on accessing the CD.
+
+Event Constants
+---------------
+
+Those constants are used by the :mod:`pygame2.sdl.event` module
+functions.
+
+.. data:: NOEVENT
+
+   Indicates no event.
+
+.. data:: NUMEVENTS
+
+   The maximum amount of event types allowed to be used.
+
+.. data:: ACTIVEEVENT
+
+   Raised, when the SDL application state changes.
+
+.. data:: KEYDOWN
+
+   Raised, when a key is pressed down.
+
+.. data:: KEYUP
+
+   Raised, when a key is released.
+
+.. data:: MOUSEMOTION
+
+   Raised, when the mouse moves.
+
+.. data:: MOUSEBUTTONDOWN
+
+   Raised, when a mouse button is pressed down.
+
+.. data:: MOUSEBUTTONUP
+
+   Raised, when a mouse button is released.
+
+.. data:: JOYAXISMOTION
+
+   Raised, when a joystick axis moves.
+
+.. data:: JOYBALLMOTION
+
+   Raised, when a trackball on a joystick moves.
+
+.. data:: JOYHATMOTION
+
+   Raised, when a hat on a joystick moves.
+
+.. data:: JOYBUTTONDOWN
+
+   Raised, when a joystick button is pressed down.
+
+.. data:: JOYBUTTONUP
+
+   Raised, when a joystick button is released.
+
+.. data:: QUIT
+
+   Raised, when the SDL application window shall be closed.
+
+.. data:: SYSWMEVENT
+
+   Raised, when an unknown, window manager specific event occurs.
+
+.. data:: VIDEORESIZE
+
+   Raised, when the SDL application window shall be resized.
+
+.. data:: VIDEOEXPOSE
+
+   Raised, when the screen has been modified outside of the SDL
+   application and the SDL application window needs to be redrawn.
+
+.. data:: USEREVENT
+
+   Raised, when a user-specific event occurs.
+
+Application Constants
+---------------------
+
+Those constants are used by the :data:`ACTIVEEVENT` event and the
+:func:`pygame2.sdl.event.get_app_state` method.
+
+.. data:: APPACTIVE
+
+   Indicates that that the SDL application is currently active.
+
+.. data:: APPINPUTFOCUS
+
+   Indicates that the SDL application has the keyboard input focus.
+
+.. data:: APPMOUSEFOCUS
+
+   Indicates that the SDL application has the mouse input focus.
+
+Keyboard Constants
+------------------
+
+The following constants are used by the :func:`pygame2.sdl.keyboard.set_repeat`
+function:
+
+.. data:: DEFAULT_REPEAT_DELAY
+
+   The default delay before starting to repeat raising :data:`KEYDOWN` event
+   on pressing a key down.
+
+.. data:: DEFAULT_REPEAT_INTERVAL
+
+   The default interval for raising :data:`KEYDOWN` events on pressing a key
+   down.
+
+The following constants are used by the :func:`pygame2.sdl.keyboard.get_state`
+and :func:`pygame2.sdl.keyboard.get_key_name` functions and the :data:`KEYDOWN`
+and :data:`KEYUP` events.
+
++-------------------+-------------------------------------------------------+
+| Constant          | Meaning and Value                                     |
++===================+=======================================================+
+| K_UNKNOWN         | An unknown key.                                       |
++-------------------+-------------------------------------------------------+
+| K_a - K_z         | Alphabetical keys ranging from a to z. There is no    |
+|                   | captalised version of them. Instead the keyboard      |
+|                   | modifier state can be checked for :data:`KMOD_SHIFT`  |
+|                   | being set.                                            |
++-------------------+-------------------------------------------------------+
+| K_0 - K_9         | Numerical keys ranging from 0 to 9. Those differ from |
+|                   | the numerical keys on the keypad.                     |
++-------------------+-------------------------------------------------------+
+| K_TAB, K_SPACE,   | Tabulator, Space, Exclamation Mark, Hash, Double      |
+| K_EXCLAIM, K_HASH,| Quote, Dollar sign, Single Quote, Ampersand, Left     |
+| K_QUOTEDBL,       | and Right Parenthesis, Asterisk, Plus and Minus,      |
+| K_DOLLAR, K_QUOTE,| Comma, Period, Slash and Backslash, Colon and         |
+| K_AMPERSAND,      | Semicolon, Question Mark, At sign, Left and Right     |
+| K_LEFTPAREN,      | Bracket, Caret, Underscore and Backquote keys.        |
+| K_RIGHTPAREN,     |                                                       |
+| K_ASTERISK,       |                                                       |
+| K_PLUS, K_MINUS,  |                                                       |
+| K_COMMA, K_PERIOD,|                                                       |
+| K_SLASH,          |                                                       |
+| K_BACKSLASH,      |                                                       |
+| K_COLON,          |                                                       |
+| K_SEMICOLON,      |                                                       |
+| K_QUESTION, K_AT, |                                                       |
+| K_LEFTBRACKET,    |                                                       |
+| K_RIGHTBRACKET,   |                                                       |
+| K_CARET,          |                                                       |
+| K_UNDERSCORE,     |                                                       |
+| K_BACKQUOTE       |                                                       |
++-------------------+-------------------------------------------------------+
+| K_LESS, K_GREATER,| Less, Greater and Equality sign keys.                 |
+| K_EQUALS          |                                                       |
++-------------------+-------------------------------------------------------+
+| K_F1 - K_F15      | Function keys from F1 to F15.                         |
++-------------------+-------------------------------------------------------+
+| K_HOME, K_END,    | Home and End, Insert and Delete, PageUp and PageDown  |
+| K_INSERT,         | and Backspace keys.                                   |
+| K_DELETE,         |                                                       |
+| K_PAGEUP,         |                                                       |
+| K_PAGEDOWN,       |                                                       |
+| K_BACKSPACE       |                                                       |
++-------------------+-------------------------------------------------------+
+| K_LEFT, K_RIGHT,  | Cursor keys.                                          |
+| K_DOWN, K_UP      |                                                       |
++-------------------+-------------------------------------------------------+
+| K_KP0 - K_KP9     | Numerical keys on the keypad, ranging from 0 to 9.    |
++-------------------+-------------------------------------------------------+
+| K_KP_PERIOD,      | Period, Divide, Multiply, Plus, Minus, Equal sign and |
+| K_KP_DIVIDE,      | the Enter key on the keypad.                          |
+| K_KP_MULTIPLY,    |                                                       |
+| K_KP_MINUS,       |                                                       |
+| K_KP_PLUS,        |                                                       |
+| K_KP_EQUALS,      |                                                       |
+| K_KP_ENTER        |                                                       |
++-------------------+-------------------------------------------------------+
+| K_HELP, K_PRINT,  | Help, Print, SysReq, Break, Menu, Power, Euro sign,   |
+| K_SYSREQ, K_BREAK,| First and Last keys.                                  |
+| K_MENU, K_POWER,  |                                                       |
+| K_EURO, K_FIRST,  |                                                       |
+| K_LAST            |                                                       |
++-------------------+-------------------------------------------------------+
+| K_ESCAPE, K_PAUSE,| Escape, Pause and Clear keys.                         |
+| K_CLEAR           |                                                       |
++-------------------+-------------------------------------------------------+
+| K_NUMLOCK,        | NumLock, CapsLock and ScrolLock keys.                 |
+| K_CAPSLOCK,       |                                                       |
+| K_SCROLLOCK       |                                                       |
++-------------------+-------------------------------------------------------+
+| K_RSHIFT,         | Right and Left Shift, Right and Left Control, Right   |
+| K_LSHIFT, K_RCTRL,| and Left Alternative, Right and Left Meta, Right and  |
+| K_LCTRL, K_RALT,  | Left Super and Mode keys.                             |
+| K_LALT, K_RMETA,  |                                                       |
+| K_LMETA, K_LSUPER,|                                                       |
+| K_RSUPER, K_MODE  |                                                       |
++-------------------+-------------------------------------------------------+
+
+The following constants are keyboard modifer states, used as bitwise
+combinations to check, whether they were hold down on keyboard
+input. They are used by the :func:`pygame2.sdl.keyboard.get_mod_state` and
+:func:`pygame2.sdl.keyboard.set_mod_state` functions.
+
++-------------------+-------------------------------------------------------+
+| Constant          | Meaning and Value                                     |
++===================+=======================================================+
+| KMOD_NONE         | No modifier key was pressed.                          |
++-------------------+-------------------------------------------------------+
+| KMOD_LSHIFT,      | Left Shift, Right Shift or one of both was pressed.   |
+| KMOD_RSHIFT,      |                                                       |
+| KMOD_SHIFT        |                                                       |
++-------------------+-------------------------------------------------------+
+| KMOD_LCTRL,       | Left Control, Right Contro or one of both was pressed.|
+| KMOD_RCTRL,       |                                                       |
+| KMOD_CTRL         |                                                       |
++-------------------+-------------------------------------------------------+
+| KMOD_LALT,        | Left Alternative, Right Alternative or one of both    |
+| KMOD_RALT,        | was pressed.                                          |
+| KMOD_ALT          |                                                       |
++-------------------+-------------------------------------------------------+
+| KMOD_LMETA,       | Left Meta, Right Met or one of both was pressed.      |
+| KMOD_RMETA,       |                                                       |
+| KMOD_META         |                                                       |
++-------------------+-------------------------------------------------------+
+| KMOD_NUM,         | NumLock, CapsLock or Mode was pressed.                |
+| KMOD_CAPS,        |                                                       |
+| KMOD_MODE         |                                                       |
++-------------------+-------------------------------------------------------+
+
+Surface Flags
+-------------
+
+The flags explained below are used by the :class:`pygame2.sdl.video.Surface`
+class and various :mod:`pygame2.sdl.video` functions. Not all of them are
+however used or applicable to both, the module functions and the class itself.
+Using them, although not supported by the one or other, will not result in an
+error, instead the inappropriate flags are silently ignored.
+
+.. data:: SWSURFACE
+
+   The surface is held in system memory. 
+
+.. data:: HWSURFACE
+
+   The surface is held in video memory.
+
+.. data:: PREALLOC
+
+   The surface uses preallocated memory.
+
+.. data:: SRCCOLORKEY
+
+   This flag turns on colorkeying for blits from this surface. If
+   :data:`HWSURFACE` is also specified and colorkeyed blits are
+   hardware-accelerated, then SDL will attempt to place the surface in video
+   memory. Use :meth:`pygame2.sdl.video.Surface.set_colorkey` to set or clear
+   this flag after surface creation.
+
+.. data:: SRCALPHA
+
+   This flag turns on alpha-blending for blits from this surface. If
+   :data:`HWSURFACE` is also specified and alpha-blending blits are
+   hardware-accelerated, then the surface will be placed in video memory if
+   possible. Use :meth:`pygame2.sdl.video.Surface.set_alpha` to set or clear
+   this flag after surface creation.
+
+.. data:: ASYNCBLIT
+  
+   Enables the use of asynchronous updates of the surface. This will usually
+   slow down blitting on single CPU machines, but may provide a speedincrease
+   on SMP systems.
+   
+   This is only available for the :mod:`pygame2.sdl.video` functions and the
+   display surface set by :meth:`pygame2.sdl.video.set_mode`.
+
+.. data:: ANYFORMAT
+
+   Normally, if a video surface of the requested bits-per-pixel (bpp) is not
+   available, SDL will emulate one with a shadow surface. Passing ANYFORMAT
+   prevents this and causes SDL to use the video surface, regardless of its
+   pixel depth.
+
+   This is only available for the :mod:`pygame2.sdl.video` functions and the
+   display surface set by :meth:`pygame2.sdl.video.set_mode`.
+
+.. data:: HWPALETTE 
+
+   Give SDL exclusive palette access. Without this flag you may not always get
+   the colors you request with :meth:`pygame2.sdl.video.Surface.set_colors` or 
+   :meth:`pygame2.sdl.video.Surface.set_palette`.
+
+.. data:: DOUBLEBUF
+
+   Enable hardware double buffering; only valid with HWSURFACE. Calling
+   :meth:`pygame2.sdl.video.Surface.flip` will flip the buffers and update
+   the screen. All drawing will take place on the surface that is not displayed
+   at the moment. If double buffering could not be enabled then
+   :meth:`pygame2.sdl.video.Surface.flip` will just perform a
+   :meth:`pygame2.sdl.video.Surface.update` on the entire screen.
+
+   This is only available for the :mod:`pygame2.sdl.video` functions and the
+   display surface set by :meth:`pygame2.sdl.video.set_mode`.
+
+.. data:: FULLSCREEN
+
+   SDL will attempt to use a fullscreen mode. If a hardware resolution change
+   is not possible (for whatever reason), the next higher resolution will be
+   used and the display window centered on a black background.
+
+   This is only available for the :mod:`pygame2.sdl.video` functions and the
+   display surface set by :meth:`pygame2.sdl.video.set_mode`.
+
+.. data:: OPENGL
+
+   Create an OpenGL rendering context. You should have previously set OpenGL
+   video attributes with :meth:`pygame2.sdl.gl.set_attribute`.
+
+   This is only available for the :mod:`pygame2.sdl.video` functions and the
+   display surface set by :meth:`pygame2.sdl.video.set_mode`.
+
+.. data:: OPENGLBLIT
+
+   Create an OpenGL rendering context, like above, but allow normal blitting
+   operations. The screen (2D) surface may have an alpha channel, and
+   :meth:`pygame2.sdl.video.Surface.update` must be used for updating changes
+   to the screen surface.
+
+   .. note::
+      
+      This option is kept for compatibility only, and is not recommended for
+      new code.
+
+   This is only available for the :mod:`pygame2.sdl.video` functions and the
+   display surface set by :meth:`pygame2.sdl.video.set_mode`.
+
+.. data:: HWACCEL
+
+   Surface blits uses hardware acceleration.
+
+.. data:: RLEACCEL
+
+   Colorkey blitting is accelerated with RLE.
+
+.. data:: RESIZABLE
+
+   Create a resizable window. When the window is resized by the user a
+   :data:`VIDEORESIZE` event is generated and :meth:`pygame2.sdl.video.set_mode`
+   can be called again with the new size.
+
+   This is only available for the :mod:`pygame2.sdl.video` functions and the
+   display surface set by :meth:`pygame2.sdl.video.set_mode`.
+
+.. data:: NOFRAME
+
+   If possible, NOFRAME causes SDL to create a window with no title bar or
+   frame decoration. Fullscreen modes automatically have this flag set.
+