Anonymous avatar Anonymous committed a2d9a07

Minor define refactoring.
Documentation improvements.

Comments (0)

Files changed (46)

     1.4 Notes for Mac OS users
     1.5 Notes for Unix users
 2. Getting started
-3. Credits
-4. License
+3. License
 
 0. Description
 --------------
 the doc/ directory. A lot of examples demonstrating the abilities of
 Pygame2 are available in the examples/
 
-3. Credits
-----------
-TODO
-
-4. License
+3. License
 ----------
 This library is distributed under GNU LGPL version 2.1, which can be found in
-the file "doc/LGPL".
+the file "doc/LGPL". Parts might be licensed with less restrictions (e.g.
+BSD-style license or Public Domain code).
 
 This basically means you can use Pygame2 in any project you want, but if
 you make any changes or additions to pygame itself, those must be
 * Check display surface tracking for multiple calls to set_mode using
   different return variables.
 * Argument parsing must handle 64-bit conversions correctly.
-* Add palette color support to sdlext.transform (trunk rev. 2242).
 * Check trunk 1953 (blit blend operations).
 * Check trunk rev. 1937, 1947 (blit blend for self).
 * Mark methods, which are limited to certain bpp ranges.
-* Add doc notes about quit() behaviour of the various modules.
-* add pgcompat.h to *mod.h internal headers.
-* >8 bpp surfaces with palettes - it is supported (although it might be
-  pointless) by SDL and so should we.
 * math module changes in rev. 2777
-
-* freetype: render to buffer buffer support (like new bytearray, but
-  write to a buffer instead)
+* freetype: rendering size should use the bbox height for correct ascent/descent
+  values, not the real size
 * freetype: correct error messages (e.g. on trying to scale pcf fonts)
 * freetype: brush up docs and examples
-* freetype: description/markup language for rendering text (like e.g. pango
-   has)?
-
 * openal: check integrity and references for sources, buffers and listeners.
 
-Things to ADD:
-==============
-* (re)add tests
-* add examples
-* reorganise and add camera module
-* add movie module
-* subsurfaces via surface[x:y,a:b]? Brought up by ctgPi via IRC
-* Add prebuilt package for Win32 VC++ builds.
-* add OpenMP support where useful (looped operations, etc.)
-
 Things to FIX:
 ==============
 * Fix eval(repr(xyz)) for most types.
 * use copy.copy and copy.deepcopy for consistent object copies
-* Rewrite and fix up numpysurfarray and numpysndarray
 * recheck and redesign X11 implementation for pygame.sdlext.scrap
 * check all string/unicode conversions, esp. file I/O with !UTF-8 and !ASCII
 * respect surface->clip_rect where necessary!
   how not to do it)
 * SDL_gfx has to set the correct errors (SDL_SetError()). Fix that and
   merge it back to the SDL_gfx upstream
+* Brush up documentation for pygame2.midi.
+* Rewrite and fix up numpysurfarray and numpysndarray
+
+Things to ADD:
+==============
+* (re)add tests
+* add examples
+* reorganise and add camera module
+* add movie module
+* subsurfaces via surface[x:y,a:b]? Brought up by ctgPi via IRC
+* Add prebuilt package for Win32 VC++ builds.
+* add OpenMP support where useful (looped operations, etc.)
+* freetype: description/markup language for rendering text (like e.g. pango
+   has)?
+* freetype: render to buffer buffer support (like new bytearray, but
+  write to a buffer instead)
+* >8 bpp surfaces with palettes - it is supported (although it might be
+  pointless) by SDL and so should we.
+* Add palette color support to sdlext.transform (trunk rev. 2242).
 * Speed up blits using fast lookup tables for 8bpp to 8bpp.
-* Brush up documentation for pygame2.midi.
+* add pgcompat.h to *mod.h internal headers.
 
 Things to WRAP:
 ===============
 * SDL_Thread*
 * SDL_gfx image filter functions
 * characterXXX wrappers for sdlgdfx
-

config/clangccompiler.py

-"""A simple Intel C compiler class for Unix-based systems."""
+"""A simple LLVM C compiler class for Unix-based systems."""
 import os
+
 from distutils.unixccompiler import UnixCCompiler
 import distutils.sysconfig  as sysconfig
 
 C Modules
 ---------
 Create an new directory under src, using the name of the module you
-would like to create (see below, "Module naming"). All source files
+would like to create (see below, :ref:`cmodulenaming`). All source files
 related to your module should go into that directory (and stay there!).
 You should use the Python 2.5 and 3.1 API for programming. In order to
 support Python 2.4, include the "pgcompat.h" header file, where
 appropriate.
 
+.. _cmodulenaming:
+
 C Module Naming
 ---------------
 In case the module is a wrapper around an existing library, the module's
 install.
 DOCFILE.xml is the name of the documentation file to use, which is located
 under doc/src (see below, :ref:`documenting`).
-Each entry in the DEPENDENCYx list represents an external library reference
+Each entry in the DEPENDENCY list represents an external library reference
 which must be linked with the module. The names of these libraries can be
 found/modified in the config.config_modules file.
 
+.. note::
+
+   If the module is not fully implemented yet or in an unstable or untested
+   form, mark it as experimental, so that it will not be built and included
+   in default releases, but only in SCM-based builds.
+   To do this, simply add the ``experimental=True`` parameter to the ``Module``
+   constructor.
+
 Example: ::
 
   Module ("myownlib",[ "src/myownlib/myownlibmod.c", "src/myownlib/myclass.c" ],
   +-----------+----------------------------------------+
   | IS_MSYS   | (Win32) Msys build with GCC            |
   +-----------+----------------------------------------+
-  | IS_DARWIN | MacOS X and Darin-based platforms      |
+  | IS_DARWIN | MacOS X and Darwin-based platforms     |
   +-----------+----------------------------------------+
   | IS_UNIX   | Any other build platform that          |
   |           | successfully passes the preparations   |

doc/MODULE_FAQ.txt

 ============
 The C API contains numerous macros and functions that ease the
 developer's life. In order to have a similar behaviour without
-implementing the same things again and again, those will be listed here.
+implementing the same things again and again, the most important ones will be
+listed here.
+
+.. note::
+
+   For a full list of macros, utility functiona and C API interfaces, it is 
+   *strongly* recommended to read the :ref:`capi`.
 
 If it is necessary to rely on certain features specific to a particular
 environment, you can check for the build system flags, which are automatically
   +-----------+----------------------------------------+
   | IS_MSYS   | (Win32) Msys build with GCC            |
   +-----------+----------------------------------------+
-  | IS_DARWIN | MacOS X and Darin-based platforms      |
+  | IS_DARWIN | MacOS X and Darwin-based platforms     |
   +-----------+----------------------------------------+
   | IS_UNIX   | Any other build platform that          |
   |           | successfully passes the preparations   |
 ============
 Before a new release takes place, the following steps have to be made:
 
-* Increase version number (see `Postprocessing`) in ::
+* Increase version number (see :ref:`postprocessing`) in ::
   
     setup.py
     doc/conf.py
     
 * Update NEWS.txt with the changes since the last version (only for final
   releases - alpha and rc should contain the information, but not be tagged
-  explicitly). See `Editing News` for more information.
+  explicitly). See :ref:`editingnews` for more information.
 
 * Update README.txt and doc/BuildXXX.txt to point to the latest required
   dependency versions.
     make testall
     make testall2
 
+.. _editingnews:
+    
 Editing News
 ============
 The NEWS.txt file contains information about the changes between two
   
   Instructions for Mac OS X platforms*
 
+.. _postprocessing:
+
 Postprocessing
 ==============
 Right after a release has been made and the tree was tagged correctly, the
+.. _capi:
+
 ###################
 C API Documentation
 ###################

doc/capi/base.rst

 
 .. cvar:: PyObject* PyExc_PyGameError
 
-  The internally used :class:`pygame2.base.Error` exception class.
+  The internally used :class:`pygame2.Error` exception class.
 
 Functions
 ---------
       <desc>Gets or sets the bottom right corner position of the FRect.</desc>
     </attr>
     <method name="ceil">
-      <call>ceil () -> :class:`Rect`</call>
+      <call>ceil () -> Rect</call>
       <desc>
         Creates a :class:`Rect` from the specified FRect.
 
       </desc>
     </method>
     <method name="floor">
-      <call>floor () -> :class:`Rect`</call>
+      <call>floor () -> Rect</call>
       <desc>
         Creates a :class:`Rect` from the specified FRect.
 
       <desc>Gets or sets the right position of the FRect.</desc>
     </attr>
     <method name="round">
-      <call>round () -> :class`Rect`</call>
+      <call>round () -> Rect</call>
       <desc>
         Creates a :class:`Rect` from the specified FRect.
 
       <desc>Gets or sets the top right corner position of the FRect.</desc>
     </attr>
     <method name="trunc">
-      <call>trunc () -> :class:`Rect`</call>
+      <call>trunc () -> Rect</call>
       <desc>
         Creates a :class:`Rect` from the specified FRect.
 
       filetype argument to request specific font file types, such as bdf or ttf
       fonts.
 
-      All found fonts are returned as list
+      All found fonts are returned as list.
     </desc>
     <example></example>
   </func>
     </desc>
     <example></example>
   </func>
-  <func name="get_fonts">
-    <call>get_fonts () -> [str, str, ...]</call>
+  <func name="get_families">
+    <call>get_families () -> [str, str, ...]</call>
     <desc>
       Gets the list of available font families.
     </desc>

doc/src/mathbase.xml

   </desc>
   <func name="vector_from_polar">
     <call>vector_from_polar (p1, p2) -> Vector2</call>
-    <desc></desc>
+    <desc>
+      Creates a 2D vector from the passed polar coordinates.
+    </desc>
   </func>
   <func name="vector_from_spherical">
     <call>vector_from_spherical (p1, p2, p3) -> Vector2</call>
-    <desc></desc>
+    <desc>
+      Creates a 3D vector from the passed spherical coordinates.
+    </desc>
   </func>
 
   <class name="Vector">
-    <constructor>Vector () -> Vector</constructor>
-    <desc>Creates a new Vector.
+    <constructor>Vector (elements) -> Vector</constructor>
+    <desc>Creates a new Vector with the specified elements or dimension.
+    
+      Creates a new n-dimensional Vector. *elements* can be either a sequence of
+      numbers representing the values for each dimension or a positive integer
+      to create an empty vector with *elements* dimensions.
     </desc>
+    <example>
+      from pygame2.math import Vector
+      
+      # Create a 3D vector with x=1, y=2 and z=3
+      v1 = Vector ([1, 2, 3])
+      
+      # Create a vector with 15 dimensions, where each component is set to 0.
+      v2 = Vector (15)
+    </example>
     <attr name="dimension">
       <desc>Gets the dimensions of the :class:`Vector`.</desc>
     </attr>
     </attr>
     <method name="normalize">
       <call>normalize () -> Vector</call>
-      <desc></desc>
+      <desc>Creates a normalized representation of this Vector.</desc>
     </method>
     <method name="normalize_ip">
       <call>normalize_ip () -> None</call>
-      <desc></desc>
+      <desc>Normalizes the Vector in place.</desc>
     </method>
     <method name="slerp">
       <call>slerp () -> Vector</call>
       <desc></desc>
     </method>
     <method name="dot">
-      <call>dot () -> float</call>
-      <desc></desc>
+      <call>dot (v) -> float</call>
+      <desc>Calculates the dot product of the Vector and the passed argument.
+      </desc>
     </method>
     <method name="scale_to">
-      <call>scale_to (v) -> Vector</call>
-      <desc></desc>
+      <call>scale_to (length) -> Vector</call>
+      <desc>Scales the Vector to match the passed length.</desc>
     </method>
     <method name="reflect">
       <call>reflect () -> Vector</call>
-      <desc></desc>
+      <desc>Creates a reflected representation of the Vector.</desc>
     </method>
     <method name="reflect_ip">
       <call>reflect_ip () -> None</call>
-      <desc></desc>
+      <desc>Reflects the Vector in place.</desc>
     </method>
     <method name="distance">
-      <call>distance () -> None</call>
-      <desc></desc>
+      <call>distance (v) -> float</call>
+      <desc>Calculates the distance between two vectors.</desc>
     </method>
     <method name="distance_squared">
       <call>distance_squared () -> None</call>
-      <desc></desc>
+      <desc>Calculates the squared distance between two vectors.</desc>
     </method>
   </class>
   
       <desc>Gets or sets second element of the :class:`Vector2`.</desc>
     </attr>
     <method name="rotate">
-      <call>rotate () -> Vector2</call>
-      <desc></desc>
+      <call>rotate (angle) -> Vector2</call>
+      <desc>Rotates the Vector2 by the passed degrees.</desc>
     </method>
     <method name="rotate_ip">
-      <call>rotate_ip () -> Vector2</call>
-      <desc></desc>
+      <call>rotate_ip (angle) -> Vector2</call>
+      <desc>Rotates the Vector2 by the passed degrees in place.</desc>
     </method>
     <method name="as_polar">
       <call>as_polar () -> float, float</call>
-      <desc></desc>
+      <desc>Gets the polar coordinate representation of the Vector2.</desc>
     </method>
     <method name="angle_to">
       <call>angle_to (v) -> float</call>
-      <desc></desc>
+      <desc>Calculates the angle (in degrees) between two Vector2 objects.</desc>
     </method>
     <method name="cross">
       <call>cross (v) -> Vector2</call>
-      <desc></desc>
+      <desc>Creates the cross product of the two Vector2 objects.</desc>
     </method>
   </class>
 
       <desc>Gets or sets third element of the :class:`Vector3`.</desc>
     </attr>
     <method name="rotate_x">
-      <call>rotate_x () -> Vector3</call>
-      <desc></desc>
+      <call>rotate_x (angle) -> Vector3</call>
+      <desc>Rotates the Vector3 by the passed degrees around the x-axis.</desc>
     </method>
     <method name="rotate_x_ip">
-      <call>rotate_x_ip () -> None</call>
-      <desc></desc>
+      <call>rotate_x_ip (angle) -> None</call>
+      <desc>Rotates the Vector3 by the passed degrees in place around the x-axis.
+      </desc>
     </method>
     <method name="rotate_y">
-      <call>rotate_y () -> Vector3</call>
-      <desc></desc>
+      <call>rotate_y (angle) -> Vector3</call>
+      <desc>Rotates the Vector3 by the passed degrees around the y-axis.</desc>
     </method>
     <method name="rotate_y_ip">
-      <call>rotate_y_ip () -> None</call>
-      <desc></desc>
+      <call>rotate_y_ip (angle) -> None</call>
+      <desc>Rotates the Vector3 by the passed degrees in place around the y-axis.</desc>
     </method>
     <method name="rotate_z">
-      <call>rotate_z () -> Vector3</call>
-      <desc></desc>
+      <call>rotate_z (angle) -> Vector3</call>
+      <desc>Rotates the Vector3 by the passed degrees around the z-axis.</desc>
     </method>
     <method name="rotate_z_ip">
-      <call>rotate_z_ip () -> None</call>
-      <desc></desc>
+      <call>rotate_z_ip (angle) -> None</call>
+      <desc>Rotates the Vector3 by the passed degrees in place around the z-axis.</desc>
     </method>
     <method name="rotate">
-      <call>rotate () -> Vector3</call>
-      <desc></desc>
+      <call>rotate (angle, axis) -> Vector3</call>
+      <desc>Rotates the Vector3 by the passed degrees around the passed axis vector.
+      </desc>
     </method>
     <method name="rotate_ip">
-      <call>rotate_ip () -> Vector3</call>
-      <desc></desc>
+      <call>rotate_ip (angle, axis) -> Vector3</call>
+      <desc>Rotates the Vector3 by the passed degrees in place around the passed axis vector.
+      </desc>
     </method>
     <method name="angle_to">
       <call>angle_to (v) -> float</call>
-      <desc></desc>
+      <desc>Calculates the angle between two vectors in degrees</desc>
     </method>
     <method name="cross">
       <call>cross (v) -> Vector3</call>
-      <desc></desc>
+      <desc>Calculates the cross product between the two Vector3 instances.</desc>
     </method>
     <method name="as_spherical">
       <call>as_spherical () -> float, float, float</call>
-      <desc></desc>
+      <desc>Gets the sperhical coordinate representation of the Vector3.</desc>
     </method>
   </class>
 

doc/src/modules.rst

    pygame2_sdlimage_constants.rst
    pygame2_sdlmixer.rst
    pygame2_sdlmixer_channel.rst
+   pygame2_sdlmixer_constants.rst
    pygame2_sdlmixer_music.rst
    pygame2_sdlmixer_numericsndarray.rst
    pygame2_sdlttf.rst

doc/src/openalbase.xml

       <call>buffer_data (bufnum, format, data, samplerate)</call>
       <desc>
         Buffers a chunk of *data* into one of the created buffers.
-
-        
       </desc>
       <example></example>
     </method>
       <call>get_prop (bufnum, prop, type) -> value or (value, ...) </call>
       <desc>
         Retrieves the value(s) of an OpenAL property for the Buffers.
-      
-        
       </desc>
       <example></example>
     </method>
     <method name="set_prop">
-      <call></call>
+      <call>set_prop (</call>
       <desc></desc>
       <example></example>
     </method>
   </class>
 
   <class name="CaptureDevice">
-    <constructor>TODO</constructor>
+    <constructor>CaptureDevice ()</constructor>
     <desc>None</desc>
     <example></example>
     <attr name="format">
       <example></example>
     </attr>
     <method name="get_samples">
-      <call></call>
+      <call>get_samples ()</call>
       <desc></desc>
       <example></example>
     </method>
       <example></example>
     </attr>
     <method name="start">
-      <call></call>
+      <call>start ()</call>
       <desc></desc>
       <example></example>
     </method>
     <method name="stop">
-      <call></call>
+      <call>stop ()</call>
       <desc></desc>
       <example></example>
     </method>
   </class>
 
   <class name="Context">
-    <constructor>TODO</constructor>
+    <constructor>Context ()</constructor>
     <desc>None</desc>
     <example></example>
     <method name="create_buffers">
-      <call></call>
+      <call>create_buffers ()</call>
       <desc></desc>
       <example></example>
     </method>
     <method name="create_sources">
-      <call></call>
+      <call>create_sources ()</call>
       <desc></desc>
       <example></example>
     </method>
       <example></example>
     </attr>
     <method name="disable">
-      <call></call>
+      <call>disable ()</call>
       <desc></desc>
       <example></example>
     </method>
       <example></example>
     </attr>
     <method name="enable">
-      <call></call>
+      <call>enable ()</call>
       <desc></desc>
       <example></example>
     </method>
       <example></example>
     </attr>
     <method name="is_enabled">
-      <call></call>
+      <call>is_enabled ()</call>
       <desc></desc>
       <example></example>
     </method>
       <example></example>
     </attr>
     <method name="make_current">
-      <call></call>
+      <call>make_current ()</call>
       <desc></desc>
       <example></example>
     </method>
     <method name="process">
-      <call></call>
+      <call>process ()</call>
       <desc></desc>
       <example></example>
     </method>
       <example></example>
     </attr>
     <method name="suspend">
-      <call></call>
+      <call>suspend ()</call>
       <desc></desc>
       <example></example>
     </method>
   </class>
 
   <class name="Device">
-    <constructor>TODO</constructor>
+    <constructor>Device ()</constructor>
     <desc>None</desc>
     <example></example>
     <attr name="extensions">
       <example></example>
     </attr>
     <method name="get_enum_value">
-      <call></call>
+      <call>get_enum_value ()</call>
       <desc></desc>
       <example></example>
     </method>
     <method name="get_error">
-      <call></call>
+      <call>get_error ()</call>
       <desc></desc>
       <example></example>
     </method>
     <method name="has_extension">
-      <call></call>
+      <call>has_extension</call>
       <desc></desc>
       <example></example>
     </method>
   </class>
 
   <class name="Listener">
-    <constructor>TODO</constructor>
+    <constructor>Listener</constructor>
     <desc>None</desc>
     <example></example>
     <method name="get_prop">
-      <call></call>
+      <call>get_prop ()</call>
       <desc></desc>
       <example></example>
     </method>
     <method name="set_prop">
-      <call></call>
+      <call>set_prop ()</call>
       <desc></desc>
       <example></example>
     </method>
   </class>
 
   <class name="Sources">
-    <constructor>TODO</constructor>
+    <constructor>Sources</constructor>
     <desc>None</desc>
     <example></example>
     <attr name="count">
       <example></example>
     </attr>
     <method name="get_prop">
-      <call></call>
+      <call>get_prop ()</call>
       <desc></desc>
       <example></example>
     </method>
     <method name="pause">
-      <call></call>
+      <call>pause ()</call>
       <desc></desc>
       <example></example>
     </method>
     <method name="play">
-      <call></call>
+      <call>play ()</call>
       <desc></desc>
       <example></example>
     </method>
     <method name="queue_buffers">
-      <call></call>
+      <call>queue_buffers ()</call>
       <desc></desc>
       <example></example>
     </method>
     <method name="rewind">
-      <call></call>
+      <call>rewind ()</call>
       <desc></desc>
       <example></example>
     </method>
     <method name="set_prop">
-      <call></call>
+      <call>set_prop ()</call>
       <desc></desc>
       <example></example>
     </method>
       <example></example>
     </attr>
     <method name="stop">
-      <call></call>
+      <call>stop ()</call>
       <desc></desc>
       <example></example>
     </method>
     <method name="unqueue_buffers">
-      <call></call>
+      <call>unqueue_buffers ()</call>
       <desc></desc>
       <example></example>
     </method>
   </class>
 
   <func name="al_get_string">
-    <call></call>
+    <call>al_get_string ()</call>
     <desc></desc>
     <example></example>
   </func>
   <func name="get_default_capture_device_name">
-    <call></call>
+    <call>get_default_capture_device_name ()</call>
     <desc></desc>
     <example></example>
   </func>
   <func name="get_default_output_device_name">
-    <call></call>
+    <call>get_default_output_device_name ()</call>
     <desc></desc>
     <example></example>
   </func>
   <func name="get_enum_value">
-    <call></call>
+    <call>get_enum_value ()</call>
     <desc></desc>
     <example></example>
   </func>
   <func name="get_error">
-    <call></call>
+    <call>get_error ()</call>
     <desc></desc>
     <example></example>
   </func>
   <func name="init">
-    <call></call>
+    <call>init ()</call>
     <desc></desc>
     <example></example>
   </func>
   <func name="is_extension_present">
-    <call></call>
+    <call>is_extension_present ()</call>
     <desc></desc>
     <example></example>
   </func>
   <func name="list_capture_devices">
-    <call></call>
+    <call>list_capture_devices ()</call>
     <desc></desc>
     <example></example>
   </func>
   <func name="list_output_devices">
-    <call></call>
+    <call>list_output_devices</call>
     <desc></desc>
     <example></example>
   </func>
   <func name="quit">
-    <call></call>
+    <call>quit ()</call>
     <desc></desc>
     <example></example>
   </func>
   <func name="set_current_context">
-    <call></call>
+    <call>set_current_context ()</call>
     <desc></desc>
     <example></example>
   </func>

doc/src/resources.xml

 
       Opens and reads a certain file from a TAR archive. The result is returned
       as StringIO stream. *filename* can be a relative or absolute path within
-      the ZIP archive. The optional *dir* argument can be used to supply a
+      the TAR archive. The optional *dir* argument can be used to supply a
       relative directory path, under which *filename* will be tried to retrieved.
 
       *type* is used to supply additional compression information, in case the

doc/src/sdl_constants.rst

 .. 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.
+   the both RGB values will be used for the result.
 
 .. data:: BLEND_RGB_SUB
 

doc/src/sdlevent.xml

     </desc>
   </func>
   <func name="get">
-    <call>get ([events]) -> [:class:`Event`, :class:`Event`, ... ]</call>
+    <call>get ([events]) -> [Event, Event, ... ]</call>
     <desc>
       Gets events from the event queue.
 
     </desc>
   </func>
   <func name="poll">
-    <call>poll () -> :class:`Event`</call>
+    <call>poll () -> Event</call>
     <desc>
       Gets a single event from the event queue.
 
     </desc>
   </func>
   <func name="wait">
-    <call>wait () -> :class:`Event`</call>
+    <call>wait () -> Event</call>
     <desc>
       Waits indefinitely for the next available event.
 

doc/src/sdlextbase.xml

       While it is possible to assign both, integer color values and RGB(A)
       color tuples, the PixelArray will only use integers for the
       color representation. Thus, checking for certain colors has to be done
-      using the :meth:`pygame2.sdl.video.Surface.map_rgb` method of the surface,
+      using the :meth:`pygame2.sdl.video.PixelFormat.map_rgba` method of the
+      surface's :attr:`pygame2.sdl.video.Surface.format`,
       the PixelArray was created for. ::
 
         pxarray = pygame.PixelArray (surface)
         # Check, if the first pixel at the topleft corner is blue
-        if pxarray[0][0] == surface.map_rgb ((0, 0, 255)):
+        if pxarray[0][0] == surface.format.map_rgba ((0, 0, 255)):
             ...
       
       If you operate on a slice, you also can use arbitrary sequences or

doc/src/sdlextdraw.xml

    </desc>
 
   <func name="aaline">
-    <call>aaline (surface, color, x1, y1, x2, y2[, blend]) -> :class:`pygame2.Rect`
-    aaline (surface, color, point1, point2[, blend]) -> :class:`pygame2.Rect`</call>
+    <call>aaline (surface, color, x1, y1, x2, y2[, blend]) -> Rect
+    aaline (surface, color, point1, point2[, blend]) -> Rect</call>
     <desc>Draws a fine anti-aliased line.
       
       Draws an anti-aliased line on a *surface*. If *blend* is True, the
     </desc>
   </func>
   <func name="aalines">
-    <call>aalines (surface, color, (point1, point2, ...) [, blend]) -> :class:`pygame2.Rect`
+    <call>aalines (surface, color, (point1, point2, ...) [, blend]) -> Rect
     </call>
     <desc>Draws multiple contiguous anti-aliased line segments on a surface.
     
     </desc>
   </func>
   <func name="aapolygon">
-    <call>aapolygon (surface, color, (point1, point2, ...) [, blend]) -> :class:`pygame2.Rect`
+    <call>aapolygon (surface, color, (point1, point2, ...) [, blend]) -> Rect
     </call>
     <desc>Draws an anti-aliased polygonal shape on a surface.
     
     </desc>
   </func>
   <func name="arc">
-    <call>arc (surface, color, rect, startangle, stopangle[, width]) -> :class:`pygame2.Rect`
+    <call>arc (surface, color, rect, startangle, stopangle[, width]) -> Rect
     </call>
     <desc>Draws an elliptical arc on a surface.
     
     </desc>
   </func>
   <func name="circle">
-    <call>circle (surface, color, x, y, radius[, width]) -> :class:`pygame2.Rect`
-    circle (surface, color, point, radius[, width]) -> :class:`pygame2.Rect`</call>
+    <call>circle (surface, color, x, y, radius[, width]) -> Rect
+    circle (surface, color, point, radius[, width]) -> Rect</call>
     <desc>Draws a circular shape on a surface.
     
       Draws a circular shape on a *surface* with an optionally specified
     </desc>
   </func>
   <func name="ellipse">
-    <call>ellipse (surface, color, rect[, width]) -> :class:`pygame2.Rect`</call>
+    <call>ellipse (surface, color, rect[, width]) -> Rect</call>
     <desc>Draws an elliptical shape on a surface.
     
       Draws an elliptical shape on a *surface* with an optionally
     </desc>
   </func>
   <func name="line">
-    <call>line (surface, color, x1, y1, x2, y2[, width]) -> :class:`pygame2.Rect`
-    line (surface, color, point1, point2[, width]) -> :class:`pygame2.Rect`</call>
+    <call>line (surface, color, x1, y1, x2, y2[, width]) -> Rect
+    line (surface, color, point1, point2[, width]) -> Rect</call>
     <desc>Draws a straight line segment on a surface.
 
       Draws a straight line segment on a *surface* with an optionally
     </desc>
   </func>
   <func name="lines">
-    <call>lines (surface, color, (point1, point2, ...) [, width]) -> :class:`pygame2.Rect`</call>
+    <call>lines (surface, color, (point1, point2, ...) [, width]) -> Rect</call>
     <desc>Draws multiple contiguous line segments on a surface.
     
       Draws a sequence of lines on a *surface* with an optionally
     </desc>
   </func>
   <func name="polygon">
-    <call>polygon (surface, color, (point1, point2), ...) [, width]) -> :class:`pygame2.Rect`
+    <call>polygon (surface, color, (point1, point2), ...) [, width]) -> Rect
     </call>
     <desc>Draws a polygonal shape on a surface.
     
     </desc>
   </func>
   <func name="rect">
-    <call>rect (surface, color, rect [, width]) -> :class:`pygame2.Rect`</call>
+    <call>rect (surface, color, rect [, width]) -> Rect</call>
     <desc>Draws a rectangular shape on a surface.
     
       Draws a rectangular shape on a *surface* with an optionally

doc/src/sdlextfastevent.xml

   </class>
 
   <func name="get">
-    <call>get () -> [:class:`Event`, :class:`Event`, ...]</call>
+    <call>get () -> [Event, Event, ...]</call>
     <desc>
       Gets events from the event queue.
 
     </desc>
   </func>
   <func name="poll">
-    <call>poll () -> :class:`Event`</call>
+    <call>poll () -> Event</call>
     <desc>
       Gets a single event from the event queue.
 
     </desc>
   </func>
   <func name="wait">
-    <call>wait () -> :class:`Event`</call>
+    <call>wait () -> Event</call>
     <desc>
       Waits indefinitely for the next available event.
 

doc/src/sdlextfont.xml

       <example></example>
     </method>
     <method name="render_on">
-      <call>render_on (surface, text, offset=(0, 0)) -> :class:`pygame2.Rect`</call>
+      <call>render_on (surface, text, offset=(0, 0)) -> Rect</call>
       <desc>
         Renders a text on the passed surface, starting at offset.
 
       <example></example>
     </method>
     <method name="render">
-      <call>render (text) -> :class:`pygame2.sdl.video.Surface`</call>
+      <call>render (text) -> Surface</call>
       <desc>
         Renders the passed *text* on a new
         :class:`pygame2.sdl.video.Surface` and returns it.

doc/src/sdlexttransform.xml

   </desc>
 
   <func name="average_color">
-    <call>average_color (surface[, rect]) -> :class:`pygame2.Color`</call>
+    <call>average_color (surface[, rect]) -> Color</call>
     <desc>
       Finds the average color of a surface.
       
     </desc>
   </func>
   <func name="average_surfaces">
-    <call>average_surfaces ((surface1, surface2, ...)[, destsurface]) -> :class:`pygame2.sdl.video.Surface`</call>
+    <call>average_surfaces ((surface1, surface2, ...)[, destsurface]) -> Surface</call>
     <desc>
       Creates a new surface with the average colors from a list of surfaces.
       
     </desc>
   </func>
   <func name="chop">
-    <call>chop (surface, rect) -> :class:`pygame2.sdl.video.Surface`</call>
+    <call>chop (surface, rect) -> Surface</call>
     <desc>
       Extracts a portion of a surface.
 
     </desc>
   </func>
   <func name="flip">
-    <call>flip (surface, flipx, flipy) -> :class:`pygame2.sdl.video.Surface`</call>
+    <call>flip (surface, flipx, flipy) -> Surface</call>
     <desc>
       Flips a surface horizontically, vertically or over both axes.
       
     </desc>
   </func>
   <func name="laplacian">
-    <call>laplacian (surface[, destsurface]) -> :class:`pygame2.sdl.video.Surface`</call>
+    <call>laplacian (surface[, destsurface]) -> Surface</call>
     <desc>
       Finds the edges in a surface using the laplacian algorithm.
       
     </desc>
   </func>
   <func name="rotate">
-    <call>rotate (surface, angle) -> :class:`pygame2.sdl.video.Surface`</call>
+    <call>rotate (surface, angle) -> Surface</call>
     <desc>
       Rotates a surface.
       
     </desc>
   </func>
   <func name="scale">
-    <call>scale (surface, width, height[, destsurface]) -> :class:`pygame2.sdl.video.Surface`
-      scale (surface, size[, destsurface]) -> :class:`pygame2.sdl.video.Surface`
+    <call>scale (surface, width, height[, destsurface]) -> Surface
+      scale (surface, size[, destsurface]) -> Surface
     </call>
     <desc>
        Resizes the surface to a new resolution.
     </desc>
   </func>
   <func name="scale2x">
-    <call>scale (surface[, destsurface]) -> :class:`pygame2.sdl.video.Surface`</call>
+    <call>scale (surface[, destsurface]) -> Surface</call>
     <desc>
       Scales a surface to the double of its original size.
       
     </desc>
   </func>
   <func name="smoothscale">
-    <call>smoothscale (surface, width, height[, destsurface]) -> :class:`pygame2.sdl.video.Surface`
-      smoothscale (surface, size[, destsurface]) -> :class:`pygame2.sdl.video.Surface`
+    <call>smoothscale (surface, width, height[, destsurface]) -> Surface
+      smoothscale (surface, size[, destsurface]) -> Surface
     </call>
     <desc>
       Resizes the surface to a new resolution using smoothing algorithms.
     </desc>
   </func>
   <func name="threshold">
-    <call>threshold (surface, color, threscolor[, destsurface]) -> :class:`pygame2.sdl.video.Surface`
-      threshold (surface, colorsurface, threscolor[, destsurface]) -> :class:`pygame2.sdl.video.Surface`
+    <call>threshold (surface, color, threscolor[, destsurface]) -> Surface
+      threshold (surface, colorsurface, threscolor[, destsurface]) -> Surface
     </call>
     <desc>TODO</desc>
   </func>

doc/src/sdlgfxbase.xml

       delays the execution to keep the required frame rate.
 
       The desired frame rate must be within the range of
-      :const:`FPS_LOWER_LIMIT` and const:`FPS_UPPER_LIMIT`. If the
+      :const:`FPS_LOWER_LIMIT` and :const:`FPS_UPPER_LIMIT`. If the
       *framerate* argument is omitted, :const:`FPS_DEFAULT` is assumed
       for it.
     </desc>

doc/src/sdlgfxrotozoom.xml

   <desc>SDL_gfx rotozoom wrapper module</desc>
 
   <func name="rotate_90">
-    <call>rotate_90 (surface, times) -> :class:`pygame2.sdl.video.Surface`
+    <call>rotate_90 (surface, times) -> Surface
     </call>
     <desc>Rotates a surface clockwise by 90 degrees.
       
     </desc>
   </func>
   <func name="rotozoom">
-    <call>rotozoom (surface, angle, zoom[, smooth]) -> :class:`pygame2.sdl.video.Surface`</call>
+    <call>rotozoom (surface, angle, zoom[, smooth]) -> Surface</call>
     <desc>Rotates and zooms a surface.
     
       Rotates and zooms a *surface* at the same time and returns a new
     </desc>
   </func>
   <func name="rotozoom_xy">
-    <call>rotozoom_xy (surface, angle, zoomx, zoomy[, smooth]) -> :class:`pygame2.sdl.video.Surface`</call>
+    <call>rotozoom_xy (surface, angle, zoomx, zoomy[, smooth]) -> Surface</call>
     <desc>Rotates and zooms a surface with different scaling factors for the x- and y- axes.
     
       Rotates and zooms a *surface* at the same time and returns a new
     </desc>
   </func>
   <func name="shrink">
-    <call>zoom (surface, shrinkx, shrinky) -> :class:`pygame2.sdl.video.Surface`
+    <call>zoom (surface, shrinkx, shrinky) -> Surface
     </call>
     <desc>Shrinks a surface.
       
     </desc>
   </func>
   <func name="zoom">
-    <call>zoom (surface, zoomx, zoomy[, smooth]) -> :class:`pygame2.sdl.video.Surface`</call>
+    <call>zoom (surface, zoomx, zoomy[, smooth]) -> Surface</call>
     <desc>Zooms a surface.
     
       Zooms a *surface* and returns a new

doc/src/sdlimage.xml

   <desc>SDL image I/O wrapper module</desc>
 
   <func name="load_bmp">
-    <call>load_bmp (file) -> :class:`pygame2.sdl.video.Surface`</call>
+    <call>load_bmp (file) -> Surface</call>
     <desc>
       Loads a BMP file and creates a :class:`pygame2.sdl.video.Surface` from it.
     

doc/src/sdlimagebase.xml

     </desc>
   </func>
   <func name="get_error">
-    <call>get_error () -> :exc:`pygame2.Error`</call>
+    <call>get_error () -> str</call>
     <desc>
-      Gets the last :exc:`pygame2.Error` occured.
+      Gets the last SDL error message occured.
 
-      SDL_image maintains an internal error message. This message will
-      usually be given to you when a :exc:`pygame2.Error` is
-      raised.
+      SDL_image maintains an internal error message. This message will usually
+      be given to you when a :exc:`pygame2.Error` is raised.
 
       You will rarely need to call this function.
     </desc>
   </func>
   <func name="load">
-    <call>load (file[, type]) -> :class:`pygame2.sdl.video.Surface`</call>
+    <call>load (file[, type]) -> Surface</call>
     <desc>
       Loads an image file and creates a :class:`pygame2.sdl.video.Surface` from
       it.
     </desc>
   </func>
   <func name="read_xpm_from_array">
-    <call>read_xpm_from_array (buffer) -> :class:`pygame2.sdl.video.Surface`</call>
+    <call>read_xpm_from_array (buffer) -> Surface</call>
     <desc>Creates a :class:`pygame2.sdl.video.Surface` from a XPM buffer.
     
       Creates a :class:`pygame2.sdl.video.Surface` from a XPM

doc/src/sdlmixer_constants.rst

+:mod:`pygame2.sdlmixer.constants` -- Constants for SDL_mixer
+============================================================
+
+This module contains the constants used throughout the
+:mod:`pygame2.sdlmixer` modules.
+
+.. module:: pygame2.sdlmixer.constants
+   :synopsis: Constants used throughout the :mod:`pygame2.sdlmixer` modules.
+
+Initialisation Constants
+------------------------
+
+Those constants are used by the :func:`pygame2.sdlmixer.init` function.
+
+.. data:: INIT_FLAC
+
+   Initialises the FLAC library bindings.
+
+.. data:: INIT_MOD
+
+   Initialises the timidity library bindings.
+
+.. data:: INIT_MP3
+
+   Initialises the smpeg/mad library bindings.
+    
+.. data:: INIT_OGG
+
+   Initialises the ogg/vorbis library bindings.
+
+Format constants
+----------------
+
+Those constants are used by the :func:`pygame2.sdlmixer.open_audio` and
+:func:`pygame2.sdlmixer.query_spec` functions.
+
+.. data:: AUDIO_U8
+
+   Unsigned 8-bit data in system byte order.
+
+.. data:: AUDIO_S8
+
+   Signed 8-bit data in system byte order.
+
+.. data:: AUDIO_U16LSB
+
+   Unsigned 16-bit data in little-endian byte order.
+   
+.. data:: AUDIO_S16LSB
+
+   Signed 16-bit data in little-endian byte order.
+    
+.. data:: AUDIO_U16MSB
+
+   Unsigned 16-bit data in big-endian byte order.
+
+.. data:: AUDIO_S16MSB
+   
+   Signed 16-bit data in big-endian byte order.
+
+.. data:: AUDIO_U16
+
+   Unsigned 16-bit data in system byte order.
+
+.. data:: AUDIO_S16
+   
+   Signed 16-bit data in system byte order.
+
+.. data:: AUDIO_U16SYS
+
+   Unsigned 16-bit data in system byte order.
+
+.. data:: AUDIO_S16SYS
+   
+   Signed 16-bit data in system byte order.
+
+.. todo::
+
+   Complete the constants
+

doc/src/sdlmixerbase.xml

   </class>
 
   <func name="close_audio">
-    <call></call>
-    <desc></desc>
+    <call>close_audio () -> None</call>
+    <desc>
+      Closes an opened instance of the audio hardware.
+
+      Use :func:`query_spec` to detect how often :func:`close_audio` has
+      to be called.
+
+      After calling this function (often enough), you should not invoke
+      any SDL_mixer related class, method or function as they are likely
+      to fail or might give unpredictable results.
+    </desc>
   </func>
   <func name="get_compiled_version">
-    <call></call>
-    <desc></desc>
+    <call>get_compiled_version () -> (int, int, int)</call>
+    <desc>
+      Gets the SDL_mixer version pygame2 was compiled against as three-value tuple.
+
+      This version is built at compile time. It can be used to detect
+      which features may not be available through Pygame, if it is used
+      as precompiled package using a different version of the SDL_mixer
+      library.
+    </desc>
   </func>
   <func name="get_error">
-    <call></call>
-    <desc></desc>
+    <call>get_error () -> str</call>
+    <desc>
+      Gets the last SDL_mixer error message occured.
+
+      SDL_mixer maintains an internal error message. This message will
+      usually be given to you when a :exc:`pygame2.Error` is raised.
+
+      You will rarely need to call this function.
+    </desc>
   </func>
   <func name="get_version">
-    <call></call>
-    <desc></desc>
+    <call>get_version () -> (int, int, int)</call>
+    <desc>
+      Gets the SDL_mixer version pygame2 currently uses as three-value tuple.
+
+      This version is detected at runtime. It can be used to detect
+      which features may not be available through Pygame, if it is used
+      as precompiled package using a different version of the SDL_mixer
+      library.
+    </desc>
   </func>
   <func name="init">
-    <call></call>
-    <desc></desc>
+    <call>init ([flags]) -> int</call>
+    <desc>
+      Initializes the underlying SDL_mixer library.
+
+      Initializes the underlying SDL_mixer library using the passed
+      mixer flags. The flags indicate, which music library (FLAC, OGG,
+      ...) SDL_mixer should initialize and can be a bitwise
+      combination of the initialization constants of the
+      :mod:`pygame2.sdlmixer.constants` module.
+
+      In case an error occured, an exception will be raised.
+    </desc>
   </func>
   <func name="open_audio">
-    <call></call>
-    <desc></desc>
+    <call>open_audio (frequency, format, channels, chunksize) -> None</call>
+    <desc>
+      Initializes the mixer API and prepares the audio hardware for access.
+
+      This must be called before using any other method or class for
+      audio output. It initializes the API with a certain *frequency*
+      (e.g. 44100 for 44.1 KHz).
+
+      *format* is the sample format that will be used in the
+      :class:`Chunk` and :class:`Music` objects and can be one of the
+      :data:`AUDIO_XXX` constants.
+
+      *channels* denotes the number of output channels, not the number
+      of :class:`Channel` instances and can be 1 for mono or 2 for
+      stereo sound.
+
+      *chunksize* is the size of bytes used per output sample to
+      stream. The larger the value, the more often the output hooks will
+      be called. A good value for chunksize is between 1024 and 4096 on
+      most computers (1kB - 4 kB).
+
+      .. note::
+      
+        You can call this method multiple times with different
+        values. In turn, you have to call :func:`close_audio` as often
+        as you called :func:`open_audio` to shut anything down.
+    </desc>
+    <example>
+      import pygame2.sdlmixer as mixer
+      import pygame2.sdlmixer.constants as mixconst
+      ...
+      
+      mixer.open_audio (22050, mixconst.AUDIO_U16SYS, 2, 2048)
+    </example>
   </func>
   <func name="query_spec">
-    <call></call>
-    <desc></desc>
+    <call>query_spec () -> (int, int, int, int)</call>
+    <desc>
+      Queries the actual settings used by the audio device.
+
+      Queries the actual settings used by the audio device and returns
+      the setting in the following order:
+
+        * number of times :func:`open_audio` was called
+        * current frequency
+        * current format
+        * current channel setting (stereo or mono)
+
+     See :func:`open_audio` for the typical meaning and values of the
+     returned tuple.
+    </desc>
   </func>
   <func name="quit">
-    <call></call>
-    <desc></desc>
+    <call>quit () -> None</call>
+    <desc>
+      Shuts down the underlying SDL_mixer library.
+
+      After calling this function, you should not invoke any SDL_mixer
+      related class, method or function as they are likely to fail or
+      might give unpredictable results.
+    </desc>
   </func>
   <func name="was_init">
-    <call></call>
-    <desc></desc>
+    <call>was_init () -> bool</call>
+    <desc>
+      Gets, whether the SDL_mixer library was initialized or not.
+
+      .. note::
+
+         This only checks, whether the **SDL** flag :data:`INIT_AUDIO`
+         was set.
+    </desc>
   </func>
 </module>
 

doc/src/sdltime.xml

       *interval*. *callable* can be any callable objet, method or function.
       On invocation, the optional *data* will be passed to the callable. If
       *data* is a sequence, each item of it will be passed as single argument
-      to tha callable.
+      to the callable.
             
       This will return an CObject that acts as unique id for the timer callback.
 

doc/src/sdlttf_constants.rst

 ----------------
 
 The following constants are used for rendering text for a certain font using
-:meth:`pygam2.sdlttf.Font.render`.
+:meth:`pygame2.sdlttf.Font.render`.
 
 .. data:: RENDER_SOLID
    

doc/src/sdlttfbase.xml

       <desc>Gets the line skip of the Font.</desc>
     </attr>
     <method name="render">
-      <call>render (text, fgcolor[, bgcolor, renderflag]) -> :class:`pygame2.sdl.video.Surface`</call>
+      <call>render (text, fgcolor[, bgcolor, renderflag]) -> Surface</call>
       <desc>
         Renders a text to a :class:`pygame2.sdl.video.Surface`.
         
     </desc>
   </func>
   <func name="get_error">
-    <call>get_error () -> :exc:`pygame2.Error`</call>
+    <call>get_error () -> str</call>
     <desc>
-      Gets the last :exc:`pygame2.Error` occured.
+      Gets the last SDL_ttf error message occured.
 
       SDL_ttf maintains an internal error message. This message will usually
-      be given to you when a :exc:`pygame2.Error` is raised. You will
-      rarely need to call this function.
+      be given to you when a :exc:`pygame2.Error` is raised.
+
+      You will rarely need to call this function.
     </desc>
   </func>
   <func name="get_version">

doc/src/sdlttfsysfont.xml

   <short>SDL_ttf system font loader module</short>
   <desc>SDL_ttf system font loader module</desc>
   <func name="get_sys_font">
-    <call>get_sys_font (name, size, style=STYLE_NORMAL) -> :class:`pyggame2.sdlttf.Font`</call>
+    <call>get_sys_font (name, size, style=STYLE_NORMAL) -> Font</call>
     <desc>
-      Create a :class:`pyggame2.sdlttf.Font` from system font resources
+      Create a :class:`pygame2.sdlttf.Font` from system font resources
 
       This will search the system fonts for the given font *name*. You can
       also enable bold or italic styles, and the appropriate system font

doc/src/sdlwm.xml

     </desc>
   </func>
   <func name="toggle_fullscreen">
-    <call>toggle_fullscren (bool) -> bool</call>
+    <call>toggle_fullscreen (bool) -> bool</call>
     <desc>
       Tries to toggle the fullscreen mode for the SDL window and
       returns, whether the operation was successful or not.

doc/tutorial/index.rst

 .. toctree::
   :maxdepth: 2
 
+  pygame
+
 Indices and tables
 ==================
 

doc/tutorial/pygame.rst

+####################
+Pygame2 for Pygamers
+####################
+
+This section is about migrating from Pygame to Pygame2 and explains the
+smaller and bigger changes, which you will encounter, if you are already
+used to Pygame.
+
+Module Names and Packages
+=========================
+
+In Pygame2, the whole module and package layout changed. While Pygame
+used a 'get all from module `pygame`' approach, Pygame2 forces you to
+explicitly import the required bits and pieces.
+
+While in Pygame, you simply do a ::
+
+  import pygame # Import anything
+
+in Pygame2 you have to ::
+
+  import pygame2           # Import the Pygame2 core
+  import pygame2.sdl       # Import the SDL core wrapper
+  import pygame2.sdl.video # Import the SDL video system
+  import pygame2.sdlmixer  # Import the SDL_mixer wrapper
+  ...
+
+Each Pygame2 package and module forces you to explicitly import
+it. While this sounds like a lot of typing work all over the place, it
+also lets you easily choose and deploy only the minimum of the required
+dependencies for your application and keeps your imports free of
+superfluous stuff.
+
+Initialization and Shutdown
+===========================
+
+Similar to the explicit imports, you also have to explicitly initialize
+the modules, where necessary. In Pygame, a ::
+
+  pygame.init ()
+  ...
+  pygame.quit ()
+
+is enough to initialize nearly all parts and shut them down at the end
+of the program. In Pygame2, you have to explicitly initialize the
+modules (not all of them, of course. Only the majority of the
+SDL-related ones and :mod:`pygame2.freetype`). ::
+
+  pygame2.sdl.video.init ()
+  pygame2.sdl.audio.init ()
+  pygame2.sdlmixer.init ()
+  ...
+  pygame2.sdl.video.quit ()
+  pygame2.sdl.audio.quit ()
+  pygame2.sdlmixer.quit ()
+
+.. note::
+ 
+  The :mod:`pygame2.sdl` modules can also be initialized using
+  :func:`pygame2.sdl.init()` and the appropriate flags.
+
+Some modules might contain an :func:`init` and :func:`quit` method,
+which do not use anything (such as e.g. :mod:`pygame2.openal`). Those
+are mostly for future usage and might be required to be invoked in later
+version of Pygame2.
+
+Detail Changes (or: where to find what)
+=======================================
+
+The following subsections will provide you a comparision of which Pygame
+module, class, method or function can be found where in Pygame2 now.
+
+pygame
+------
+
+pygame.init
+  There is no similar function or attribute in Pygame2. Use the
+  corresponding :func:`init` functions of the modules and packages.
+
+pygame.quit
+  There is no similar function or attribute in Pygame2. Use the
+  corresponding :func:`quit` functions of the modules and packages.
+
+pygame.error
+  :class:`pygame2.Error`
+
+pygame.get_error
+  :func:`pygame2.sdl.get_error`, :func:`pygame2.sdlmixer.get_error`, ...
+
+pygame.set_error
+  There is no similar function or attribute in Pygame2. 
+
+pygame.get_sdl_version
+  :func:`pygame2.sdl.get_version` and :func:`pygame2.sdl.get_compiled_version` 
+
+pygame.get_sdl_byteorder
+  :const:`pygame2.sdl.constants.BYTEORDER`
+
+pygame.register_quit
+  There is no similar function or attribute in Pygame2. 
+
+pygame.version
+  :attr:`pygame2.version_info` and :attr:`pygame2.__version__`
+
+pygame.camera
+-------------
+
+The module is not (yet) ported to Pygame2.
+
+pygame.cdrom
+------------
+
+pygame.cdrom
+  :mod:`pygame2.sdl.cdrom`
+
+pygame.cdrom.init
+  :func:`pygame2.sdl.cdrom.init`
+
+pygame.cdrom.quit
+  :func:`pygame2.sdl.cdrom.quit`
+
+pygame.cdrom.get_init
+  :func:`pygame2.sdl.cdrom.was_init`
+
+pygame.cdrom.get_count
+  :func:`pygame2.sdl.cdrom.num_drives`
+
+pygame.cdrom
+  :mod:`pygame2.sdl.cdrom`
+
+pygame.cdrom.CD
+  :class:`pygame2.sdl.cdrom.CD`
+
+pygame.cdrom.CD.init
+  :meth:`pygame2.sdl.cdrom.CD.open`
+
+pygame.cdrom.CD.quit
+  :meth:`pygame2.sdl.cdrom.CD.close`
+
+pygame.cdrom.CD.get_init
+   There is no similar function or attribute in Pygame2.
+
+pygame.cdrom.CD.play
+  :meth:`pygame2.sdl.cdrom.CD.play` and
+  :meth:`pygame2.sdl.cdrom.CD.play_tracks`
+
+pygame.cdrom.CD.stop
+  :meth:`pygame2.sdl.cdrom.CD.stop`
+
+pygame.cdrom.CD.pause
+  :meth:`pygame2.sdl.cdrom.CD.pause`
+
+pygame.cdrom.CD.resume
+  :meth:`pygame2.sdl.cdrom.CD.resume`
+
+pygame.cdrom.CD.eject
+  :meth:`pygame2.sdl.cdrom.CD.eject`
+
+pygame.cdrom.CD.get_id
+  :attr:`pygame2.sdl.cdrom.CD.index`
+
+pygame.cdrom.CD.get_name
+  :attr:`pygame2.sdl.cdrom.CD.name`
+
+pygame.cdrom.CD.get_busy
+  :attr:`pygame2.sdl.cdrom.CD.status` == :const:`pygame2.sdl.constants.CD_PLAYING`
+
+pygame.cdrom.CD.get_paused
+  :attr:`pygame2.sdl.cdrom.CD.status` == :const:`pygame2.sdl.constants.CD_PAUSED`
+
+pygame.cdrom.CD.get_current
+  :attr:`pygame2.sdl.cdrom.CD.cur_track` and
+  :attr:`pygame2.sdl.cdrom.CD.cur_frame`
+
+  :attr:`pygame2.sdl.cdrom.CD.cur_track` will return a
+  :class:`pygame2.sdl.cdrom.CDTrack` object with additional information
+  about the track length, type, etc.
+
+pygame.cdrom.CD.get_empty
+  :attr:`pygame2.sdl.cdrom.CD.status` == :const:`pygame2.sdl.constants.CD_TRAYEMPTY`
+
+pygame.cdrom.CD.get_numtracks
+  :attr:`pygame2.sdl.cdrom.CD.num_tracks`
+
+pygame.cdrom.CD.get_track_audio
+  :attr:`pygame2.sdl.cdrom.CDTrack.type` == :const:`pygame2.sdl.constants.AUDIO_TRACK`
+
+pygame.cdrom.CD.get_all
+  :attr:`pygame2.sdl.cdrom.CD.tracks`
+
+  :attr:`pygame2.sdl.cdrom.CD.tracks` returns a list of
+  :attr:`pygame2.sdl.cdrom.CDTrack` object, which provide additional
+  information about the tracks.
+
+pygame.cdrom.CD.get_track_start
+  :attr:`pygame2.sdl.cdrom.CDTrack.offset`
+
+  :attr:`pygame2.sdl.cdrom.CDTrack.offset` will return the track offset
+  in frames.
+
+pygame.cdrom.CD.get_track_length
+  :attr:`pygame2.sdl.cdrom.CDTrack.length`
+
+pygame.Color
+------------
+
+No notable changes apply here, except that there is no replacement for
+:meth:`pygame.Color.set_length`.
+
+pygame.cursors
+--------------
+
+pygame.cursors can be found under :mod:`pygame2.sdl.cursors`.
+
+pygame.display
+--------------
+
+pygame.display
+  There is no 1:1 replacement for :mod:`pygame.display`.
+
+  Instead you have to use a mixture of :mod:`pygame2.sdl.video`,
+  :mod:`pygame2.sdl.wm` and :mod:`pygame2.sdl.gl`
+
+pygame.display.init
+  :func:`pygame2.sdl.video.init`
+
+pygame.display.quit
+  :func:`pygame2.sdl.video.quit`
+
+pygame.display.get_init
+  :func:`pygame2.sdl.video.was_init`
+
+pygame.display.set_mode
+  :func:`pygame2.sdl.video.set_mode`
+
+pygame.display.get_surface
+  :func:`pygame2.sdl.video.get_videosurface`
+
+pygame.display.flip
+  Use :meth:`pygame2.sdl.video.Surface.flip` of the video surface.
+
+pygame.display.update
+  Use :meth:`pygame2.sdl.video.Surface.update` of the video surface.
+
+pygame.display.get_driver
+  :func:`pygame2.sdl.video.get_drivername`
+
+pygame.display.Info
+  :func:`pygame2.sdl.video.get_info`
+
+pygame.display.get_wm_info
+  :func:`pygame2.sdl.wm.get_info`
+
+pygame.display.list_modes
+  :func:`pygame2.sdl.video.list_modes`
+
+pygame.display.mode_ok
+  :func:`pygame2.sdl.video.is_mode_ok`
+
+pygame.display.gl_get_attribute
+  :func:`pygame2.sdl.gl.get_attribute`
+
+pygame.display.gl_set_attribute
+  :func:`pygame2.sdl.gl.set_attribute`
+
+pygame.display.get_active
+  :func:`pygame2.sdl.event.get_app_state` ::
+
+    (pygame2.sdl.event.get_app_state () & pygame2.sdl.constants.APPACTIVE) == pygame2.sdl.constants.APPACTIVE
+
+pygame.display.iconify
+  :func:`pygame2.sdl.wm.iconify_window`
+
+pygame.display.toggle_fullscreen
+  :func:`pygame2.sdl.wm.toggle_fullscreen`
+
+pygame.display.set_gamma
+  :func:`pygame2.sdl.video.set_gamma`
+
+pygame.display.set_icon
+  :func:`pygame2.sdl.wm.set_icon`
+
+pygame.display.set_caption
+  :func:`pygame2.sdl.wm.set_caption`
+
+pygame.display.get_caption
+  :func:`pygame2.sdl.wm.get_caption`
+
+pygame.display.set_palette
+  Use :meth:`pygame2.sdl.video.Surface.set_palette` of the video surface.
+
+pygame.draw
+-----------
+
+pygame.draw can be found under :mod:`pygame2.sdlext.draw`.
+
+pygame.event
+------------
+
+pygame.event
+  :mod:`pygame2.sdl.event`
+
+pygame.event.pump
+  :func:`pygame2.sdl.event.pump`
+
+pygame.event.get
+  :func:`pygame2.sdl.event.get`
+
+pygame.event.poll
+  :func:`pygame2.sdl.event.poll`
+
+pygame.event.wait
+  :func:`pygame2.sdl.event.wait`
+
+pygame.event.peek
+  :func:`pygame2.sdl.event.peek`
+
+pygame.event.clear
+  :func:`pygame2.sdl.event.clear`
+
+pygame.event.event_name
+  :attr:`pygame2.sdl.event.Event.name`
+
+pygame.event.set_blocked
+  :func:`pygame2.sdl.event.set_blocked`
+
+pygame.event.set_allowed
+  Use :func:`pygame2.sdl.event.state` with :attr:`pygame2.sdl.constants.ENABLE`
+
+pygame.event.get_blocked
+  :func:`pygame2.sdl.event.get_blocked`
+
+pygame.event.set_grab
+  :func:`pygame2.sdl.wm.grab_input`
+
+pygame.event.get_grab
+  :func:`pygame2.sdl.event.get_app_state` ::
+
+    (pygame2.sdl.event.get_app_state () & (pygame2.sdl.constants.APPMOUSEFOCUS | pygame2.sdl.constants.APPINPUTFOCUS) == 
+      (pygame2.sdl.constants.APPMOUSEFOCUS | pygame2.sdl.constants.APPINPUTFOCUS) 
+
+pygame.event.post
+  :func:`pygame2.sdl.event.push`
+
+pygame.event.Event
+  :class:`pygame2.sdl.event.Event`
+
+pygame.font
+-----------
+
+:mod:`pygame.font` separates into two different modules in Pygame2,
+:mod:`pygame2.font` for font-file related tasks and
+:mod:`pygame2.sdlttf` for the SDL_ttf wrapper.
+
+pygame.font.init
+  :func:`pygame2.sdlttf.init`
+
+pygame.font.quit
+  :func:`pygame2.sdlttf.quit`
+
+pygame.font.get_init
+  :func:`pygame2.sdlttf.was_init`
+
+pygame.font.init
+  :func:`pygame2.sdlttf.init`
+
+pygame.font.get_default_font
+  There is no similar function or attribute in Pygame2.
+
+pygame.font.get_fonts
+  There is no similar function or attribute in Pygame2.
+
+pygame.font.match_font
+  :func:`pygame2.font.find_font`
+
+pygame.font.SysFont
+  :func:`pygame2.sdlttf.sysfont.get_sys_font`
+
+pygame.font.Font
+  :class:`pygame2.sdlttf.Font`
+
+pygame.font.Font.render
+  :meth:`pygame2.sdlttf.Font.render`
+
+pygame.font.Font.size
+  :meth:`pygame2.sdlttf.Font.get_size`
+
+pygame.font.Font.set_underline
+  :attr:`pygame2.sdlttf.Font.style` \|= :attr:`pygame2.sdlttf.constants.STYLE_UNDERLINE` 
+
+pygame.font.Font.get_underline
+  :attr:`pygame2.sdlttf.Font.style` ::
+
+    (pygame2.sdlttf.Font.style & pygame2.sdlttf.constants.STYLE_UNDERLINE) ==
+       pygame2.sdlttf.constants.STYLE_UNDERLINE
+
+pygame.font.Font.set_bold
+  :attr:`pygame2.sdlttf.Font.style` \|= :attr:`pygame2.sdlttf.constants.STYLE_BOLD` 
+pygame.font.Font.get_bold
+  :attr:`pygame2.sdlttf.Font.style` ::
+
+    (pygame2.sdlttf.Font.style & pygame2.sdlttf.constants.STYLE_BOLD) ==
+       pygame2.sdlttf.constants.STYLE_BOLD`
+
+pygame.font.Font.set_italic
+  :attr:`pygame2.sdlttf.Font.style` \|= :attr:`pygame2.sdlttf.constants.STYLE_ITALIC` 
+
+pygame.font.Font.get_italic
+  :attr:`pygame2.sdlttf.Font.style` ::
+  
+    (pygame2.sdlttf.Font.style & pygame2.sdlttf.constants.STYLE_ITALIC) ==
+       pygame2.sdlttf.constants.STYLE_ITALIC
+
+pygame.font.Font.metrics
+  :meth:`pygame2.sdlttf.Font.get_glyph_metrics`
+
+pygame.font.Font.get_linesize
+  :attr:`pygame2.sdlttf.Font.line_skip`
+
+pygame.font.Font.get_height
+  :attr:`pygame2.sdlttf.Font.height`
+
+pygame.font.Font.get_ascent
+  :attr:`pygame2.sdlttf.Font.ascent`
+
+pygame.font.Font.get_descent
+  :attr:`pygame2.sdlttf.Font.descent`
+
+pygame.gfxdraw
+--------------
+
+pygame.gfxdraw can be found under :mod:`pygame2.sdlgfx`.
+
+pygame.image
+------------
+
+:mod:`pygame.image` separates into two different modules in Pygame2,
+:mod:`pygame2.sdl.image` for BMP loading and :mod:`pygame2.sdlimage` for
+the SDL_image wrapper.
+
+pygame.image.load
+  :func:`pygame2.sdl.image.load_bmp` and :func:`pygame2.sdlimage.load`
+
+pygame.image.save
+  :func:`pygame2.sdl.image.save_bmp` and :meth:`pygame2.sdl.video.Surface.save`
+
+pygame.image.get_extended
+  There is no similar function or attribute in Pygame2. If the
+  :mod:`pygame2.sdlimage` module is available and
+  :mod:`pygame2.sdl.video` is built with PNG and JPEG support, you can
+  assume to have extended format support for loading and saving images.
+  
+pygame.image.tostring
+  Use the :attr:`pygame2.sdl.video.Surface.pixels` attribute.
+
+pygame.image.fromstring
+  There is no similar function or attribute in Pygame2. Use the
+  :attr:`pygame2.sdl.video.Surface.pixels` attribute to access the raw
+  buffer.
+
+pygame.image.frombuffer
+  There is no similar function or attribute in Pygame2. Use the
+  :attr:`pygame2.sdl.video.Surface.pixels` attribute to access the raw
+  buffer.
+
+pygame.joystick
+---------------
+
+pygame.joystick
+  :mod:`pygame2.sdl.joystick`
+
+pygame.joystick.init
+  :func:`pygame2.sdl.joystick.init`
+
+pygame.joystick.quit
+  :func:`pygame2.sdl.joystick.quit`
+
+pygame.joystick.get_init
+  :func:`pygame2.sdl.joystick.was_init`
+
+pygame.joystick.get_count
+  :func:`pygame2.sdl.joystick.num_joysticks`
+
+pygame.joystick.Joystick
+  :class:`pygame2.sdl.joystick.Joystick`
+
+pygame.joystick.Joystick.init
+  :meth:`pygame2.sdl.joystick.Joystick.open`
+
+pygame.joystick.Joystick.quit
+  :meth:`pygame2.sdl.joystick.Joystick.close`
+
+pygame.joystick.Joystick.get_init
+  :attr:`pygame2.sdl.joystick.Joystick.opened`
+
+pygame.joystick.Joystick.get_id
+  :attr:`pygame2.sdl.joystick.Joystick.index`
+
+pygame.joystick.Joystick.get_name
+  :attr:`pygame2.sdl.joystick.Joystick.name`
+
+pygame.joystick.Joystick.get_numaxes
+  :attr:`pygame2.sdl.joystick.Joystick.num_axes`
+
+pygame.joystick.Joystick.get_axis
+  :attr:`pygame2.sdl.joystick.Joystick.get_axis`
+
+pygame.joystick.Joystick.get_numballs
+  :attr:`pygame2.sdl.joystick.Joystick.num_balls`
+
+pygame.joystick.Joystick.get_ball
+  :meth:`pygame2.sdl.joystick.Joystick.get_ball`
+
+pygame.joystick.Joystick.get_numbuttons
+  :attr:`pygame2.sdl.joystick.Joystick.num_buttons`
+
+pygame.joystick.Joystick.get_button
+  :meth:`pygame2.sdl.joystick.Joystick.get_button`
+
+pygame.joystick.Joystick.get_numhats
+  :attr:`pygame2.sdl.joystick.Joystick.num_hats`
+
+pygame.joystick.Joystick.get_hat
+  :meth:`pygame2.sdl.joystick.Joystick.get_hat`
+
+pygame.key
+----------
+
+pygame.key
+  :mod:`pygame2.sdl.keyboard`
+
+pygame.key.get_focused
+  :func:`pygame2.sdl.event.get_app_state` ::
+
+    (pygame2.sdl.event.get_app_state () & (pygame2.sdl.constants.APPINPUTFOCUS) == pygame2.sdl.constants.APPINPUTFOCUS
+
+pygame.key.get_pressed
+  :meth:`pygame2.sdl.keyboard.get_state`
+
+pygame.key.get_mods
+  :meth:`pygame2.sdl.keyboard.get_mod_state`
+
+pygame.key.set_mods
+  :meth:`pygame2.sdl.keyboard.set_mod_state`
+
+pygame.key.set_repeat
+  :meth:`pygame2.sdl.keyboard.enable_repeat`
+
+pygame.key.get_repeat
+  :meth:`pygame2.sdl.keyboard.get_repeat`
<