Commits

marcus  committed 13d1988

Added sdlgfx.primitive.filled_pie () method for the filledPieColor function.
Added mask.convolve() from trunk.
Added documentation for font, sdl.cursors, sdlext.font, sdlext.numericsurfarray, sdlext.numpysurfarray, sdlext.surfarray and sdlttf.sysfont modules.
Added C API documentation for sdl.joystick, sdl.mouse, sdl.video, sdl.rwops, sdlext, sdlgfx and sdlttf modules.
Added extending and module creation guide and FAQ to HTML documentation.
Added Unix build guide.
Added example support to XML documentation system.
Added zip packaging for documentation bundles.
Moved test_runner.py and run_tests.py into pygame2.test.
Renamed sdlext C API import to import_pygame2_sdlext_base().
sdlext.draw methods make use of PointFromObject() C API now.
sdlgfx.primitives methods make use of PointFromObject() C API now.
Fixed py2exe example.
Fixed incorporating libtiff in Win32 builds, if using the prebuilt version.
Fixed a VC++ string length bug.
Fixed pygame2.test module - tests can be run from python now.
Fixed sdl.video ColorFromObj() C API for NULL arguments.
Fixed sdl.rwops C APIs for NULL arguments.
Fixed base PyFrect_New() C API for negative sizes.

  • Participants
  • Parent commits 7f95d0c
  • Branches pgreloaded

Comments (0)

Files changed (108)

 release: dist
 	@$(PYTHON) config/bundle_docs.py
 
+runtest:
+	@$(PYTHON) test/run_tests.py
+
 # Do not run these in production environments! They are for testing
-# only!
+# purposes only!
 
 buildall: clean
 	@python2.4 setup.py build
 	@python2.6 setup.py install
 	@python3.0 setup.py install
 
+testall:
+	@python2.4 test/run_tests.py
+	@python2.5 test/run_tests.py
+	@python2.6 test/run_tests.py
+	@python3.0 test/run_tests.py
+
+testall2:
+	@python2.4 -c "import pygame2.test; pygame2.test.run ()"
+	@python2.5 -c "import pygame2.test; pygame2.test.run ()"
+	@python2.6 -c "import pygame2.test; pygame2.test.run ()"
+	@python3.0 -c "import pygame2.test; pygame2.test.run ()"
+
 purge_installs:
 	rm -rf /usr/local/include/python2.4/pygame2*
 	rm -rf /usr/local/include/python2.5/pygame2*
 Content:
 --------
 0. Description
-1. Installation
+1. Quick Installation
     1.1 Dependencies
     1.2 Notes on SVN usage
     1.3 Notes for Windows users
     1.4 Notes for Mac OS users
+    1.5 Notes for Unix users
 2. Getting started
 3. Credits
 4. License
 of the target application and environment. It can make use of different
 3rd party libraries, such as SDL, to provide enhanced functionality.
 
-1. Installation
----------------
+1. Quick Installation
+---------------------
 You can either use the python way of installing the package or the make
 command using the Makefile.
+
 Simply type
 
   python setup.py install 
 
     Build with JPEG format saving support for pygame2.sdl.
 
-
 1.1 Dependencies
 ----------------
-Pygame2 is designed to run in as many environments as possible. As such, the
-only absolutely necessary dependency is a working Python installation.
-Additionally other libraries are needed, if you want to enable certain features
-of Pygame2.
+Pygame2 is designed to run in as many environments as possible. As such,
+the only absolutely necessary dependency is a working Python
+installation. Additionally other libraries are needed, if you want to
+enable certain features of Pygame2.
 
 * Python 2.4, 2.5, 2.6, 3.0 supported   (http://www.python.org)
 
 * SDL_mixer >= 1.2.8        (http://www.libsdl.org/projects/SDL_mixer/)
 * SDL_ttf >= 2.0.9          (http://www.libsdl.org/projects/SDL_ttf/)
 * SDL_image >= 1.2.6        (http://www.libsdl.org/projects/SDL_image/)
-* SDL_gfx >= 2.0.17         (http://www.ferzkopp.net/Software/SDL_gfx-2.0/)
+* SDL_gfx >= 2.0.18         (http://www.ferzkopp.net/Software/SDL_gfx-2.0/)
 * libpng >= 1.2.24          (http://www.libpng.org)
 * libjpeg >= 6b             (http://www.ijg.org/)
 
 --------------------------
 TODO
 
+1.5 Notes for Unix users
+------------------------
+Building Pygame2 from its source code usually happens as described above
+in 'Quick Installation'. You might want to take a look at the
+doc/BuildUnix.txt document for more details about it, though.
+
 2. Getting started
 ------------------
-To gain ground quickly, you can find many examples, the reference and tutorials
-within the doc/ directory.
+To gain ground quickly, you can find the reference and tutorials within
+the doc/ directory. A lot of examples demonstrating the abilities of
+Pygame2 are available in the examples/
 
 3. Credits
 ----------
 * merge transform/scale asm changes in rev. 1657:1669
 * complete physics collision and contacts and merge it back to the branch
 * make LayeredGroups class independent from sdl surfaces, where possible
-* check all BuildValue and ParseTuple calls for the correct value range
 * check anything for possible integer/float overflows
 * use copy.copy and copy.deepcopy for consistent object copies
-* make use of PointFromObject and SizeFromObject where necessary
 * Merge transform smooth scale changes in rev. 1715:1717
-* Merge convolve from rev. 1796
 * Rewrite and fix up numpysurfarray and numpysndarray
 
 Things to ADD:
 * add examples
 * reorganise and add camera module
 * add portmidi wrapper.
-* Subsurfaces via surface[x:y,a:b]? Brought up by ctgPi via IRC
-* add filledPieColor wrapper for sdlgfx.primitives
-* add characterXXX wrappers for sdlgdfx
+* subsurfaces via surface[x:y,a:b]? Brought up by ctgPi via IRC
 
 Things to FIX:
 ==============
   merge it back to the SDL_gfx upstream
 * all methods taking or returning angles as arguments should use degrees, not
   radians - an implicit conversion (DEG2RAD/RAD2DEG) will be done
-* fix installed pygame2.test suite
 
 Things to WRAP:
 ===============
 * SDL_Audio*
 * SDL_Thread*
 * SDL_gfx image filter functions
+* characterXXX wrappers for sdlgdfx

File config/bundle_docs.py

 """
 
 import os, sys
-import tarfile
+import tarfile, zipfile
 import re
 
 sys.path.append (os.path.pardir)
 excludes = [ "create_cref.py", "create_rstref.py", "create_doc.py",
              "conf.py", "Makefile" ]
 
-def add_files (bundle, root, alias, file_names):
+def add_files (bundle, root, alias, file_names, iszip):
     for file_name in file_names:
         file_alias = os.path.join (alias, file_name)
-        print ("  %s --> %s" % (file_name, file_alias))
-        bundle.add (os.path.join (root, file_name), file_alias)
+        print ("%s --> %s" % (file_name, file_alias))
+        if iszip:
+            bundle.write (os.path.join (root, file_name), file_alias)
+        else:
+            bundle.add (os.path.join (root, file_name), file_alias)
 
-def add_directory (bundle, root, alias):
+def add_directory (bundle, root, alias, iszip):
     reject_dirs = re.compile (r'(sphinx)|(src)|(.svn)$')
 
     # Since it is the file extension that is of interest the reversed
                     if reject_files_reversed.match(f[-1::-1]) is None and \
                     f not in excludes]
         sub_alias = os.path.join (alias, sub_root[len (root)+1:])
-        add_files (bundle, sub_root, sub_alias, files)
+        add_files (bundle, sub_root, sub_alias, files, iszip)
 
 def main():
     bundle_name_elements = ['pygame', 'docs']
     else:
         version = '-%s' % match.group(1)
 
-    bundle_name = "dist/pygame2%s-docs-and-examples.tar.gz" % version
+    bundle_name = os.path.join ("dist",
+                                "pygame2%s-docs-and-examples.tar.gz" % version)
+    zip_name = os.path.join ("dist",
+                             "pygame2%s-docs-and-examples.zip" % version)
     print ("Creating bundle %s" % bundle_name)
 
     if not os.path.exists ("dist"):
         os.mkdir ("dist")
-        
+    
     bundle = tarfile.open (bundle_name, "w:gz")
+    zipbundle = zipfile.ZipFile (zip_name, "w", zipfile.ZIP_DEFLATED)
+    
     try:
         root = os.path.abspath (".")
         alias = "pygame2"
-        add_files (bundle, root, alias, ['README.txt', ])
+        add_files (bundle, root, alias, ['README.txt', ], False)
+        add_files (zipbundle, root, alias, ['README.txt', ], True)
         add_directory (bundle, os.path.join(root, 'doc'),
-                       os.path.join(alias, 'doc'))
+                       os.path.join(alias, 'doc'), False)
+        add_directory (zipbundle, os.path.join(root, 'doc'),
+                       os.path.join(alias, 'doc'), True)
         add_directory (bundle, os.path.join(root, 'examples'),
-                       os.path.join(alias, 'examples'))
-        print ("\nFinished: %s" % bundle_name)
+                       os.path.join(alias, 'examples'), False)
+        add_directory (zipbundle, os.path.join(root, 'examples'),
+                       os.path.join(alias, 'examples'), True)
+        print ("\nFinished: %s\n          %s\n" % (bundle_name, zip_name))
     finally:
         bundle.close()
+        zipbundle.close()
 
 if __name__ == '__main__':
     main()

File config/config_msys.py

     
     if cfg.WITH_SDL:
         libraries.update (_hunt_libs ("SDL", dirs))
-        libraries.update (_hunt_libs ("SDL", dirs))
     if cfg.WITH_SDL_MIXER:
         libraries.update (_hunt_libs ("SDL_mixer", dirs))
     if cfg.WITH_SDL_IMAGE:

File config/dll.py

     ('vorbis', r'(lib){0,1}vorbis(-0){0,1}\.dll$', ['ogg']),
     ('ogg', r'(lib){0,1}ogg(-0){0,1}\.dll$', []),
     ('smpeg', r'(lib){0,1}smpeg\.dll$', ['SDL']),
-    ('tiff', r'(lib){0,1}tiff\.dll$',  ['jpeg', 'z']),
+    ('tiff', r'(lib){0,1}tiff(-3){0,1}\.dll$',  ['jpeg', 'z']),
     ('jpeg', r'(lib){0,1}jpeg\.dll$', []),
     ('png', r'(lib){0,1}png(1[23])(-0){0,1}\.dll$', ['z']),
     ('z', r'zlib1\.dll$', []),

File doc/BuildMinGW.txt

 ============================
 Building Pygame2 using MinGW
 ============================
-Using MinGW on Win32 platforms is probably the most comfortable way to build
-and install Pygame2, thanks to a handy script, that will do most of the work
-for you.
+Using MinGW on Win32 platforms is probably the most comfortable way to
+build and install Pygame2 on Windows, thanks to a handy script, that
+will do most of the work for you.
 
-    NOTE: At http://pygame.org/wiki/MingW you can find more information and
+.. note::
+
+    At http://pygame.org/wiki/MingW you can find more information and
     details about the build and installation process.
 
 Setting up MSYS and MinGW
 
 Building the dependencies
 -------------------------
-    NOTE: The following list of dependencies might not be the most actual one.
+.. note::
+
+    The following list of dependencies might not be the most actual one.
     Please check the README.txt file in the top source directory for the
     most actual dependency list!
 
 * SDL_mixer >= 1.2.8         (http://www.libsdl.org/projects/SDL_mixer/)
 * SDL_ttf >= 2.0.9           (http://www.libsdl.org/projects/SDL_ttf/)
 * SDL_image >= 1.2.6         (http://www.libsdl.org/projects/SDL_image/)
-* SDL_gfx >= 2.0.17          (http://www.ferzkopp.net/Software/SDL_gfx-2.0/)
+* SDL_gfx >= 2.0.18          (http://www.ferzkopp.net/Software/SDL_gfx-2.0/)
 * libpng >= 1.2.24           (http://www.libpng.org)
 * libjpeg >= 6b              (http://www.ijg.org/)
 
 common directory, where the msys_build_deps.py script can find them.
 The script will search the directory where it resides, the parent directory of
 it and a directory named 'deps' for the unpacked sources.
-  
-    NOTE: At this point, we strongly recommend a directory named 'deps' that is
-    created under the Pygame2 source directory.
+
+.. note::
+
+    At this point, we strongly recommend a directory named 'deps' that
+    is created under the Pygame2 source directory.
  
 Once anything's unpacked, move the Pygame2 source directory to your MSYS home
 directory (in a default installation this would be C:\\msys\\1.0\\home\\%USERNAME%).
-Start the Msys shell and change to the Pygame2 source directory:
+Start the Msys shell and change to the Pygame2 source directory: ::
 
     cd pgreloaded
 
-Now start the msys_build_deps.py script:
+Now start the msys_build_deps.py script: ::
 
     python msys_build_deps.py --all
 
 Building Pygame2
 ----------------
 Now that all dependencies are built and installed, you can proceed to build
-and install Pygame2 itself. Simply type:
+and install Pygame2 itself. Simply type: ::
 
     python setup.py build --compiler=mingw32 install
 

File doc/BuildUnix.txt

+========================
+Building Pygame2 on Unix
+========================
+Building Pygame2 on Unix compatible platforms, such as Linux or BSD, is
+probably the easiest way of having a fully featured multimedia framework
+
+Setting the environment
+-----------------------
+You will need a mostly C99 compatible compiler such as the GNU C
+Compiler and (optionally) a make utility such as GNU make or pmake.
+
+Building the dependencies
+-------------------------
+.. note::
+
+    The following list of dependencies might not be the most actual one.
+    Please check the README.txt file in the top source directory for the
+    most actual dependency list!
+
+Make sure, you have at least one of the following Python versions installed:
+
+* Python 2.4, 2.5, 2.6, 3.0 (http://www.python.org)
+
+To build anything, you will have to download the following additional source
+packages:
+
+* SDL >= 1.2.10              (http://www.libsdl.org)
+* SDL_mixer >= 1.2.8         (http://www.libsdl.org/projects/SDL_mixer/)
+* SDL_ttf >= 2.0.9           (http://www.libsdl.org/projects/SDL_ttf/)
+* SDL_image >= 1.2.6         (http://www.libsdl.org/projects/SDL_image/)
+* SDL_gfx >= 2.0.18          (http://www.ferzkopp.net/Software/SDL_gfx-2.0/)
+* libpng >= 1.2.24           (http://www.libpng.org)
+* libjpeg >= 6b              (http://www.ijg.org/)
+
+And you will need the dependency packages for the packages above:
+
+* zlib >= 1.2.3              (http://www.zlib.net)
+* tiff >= 3.8.2              (http://libtiff.org)
+* libvorbis >= 1.2.0         (http://www.xiph.org/vorbis/)
+* libogg >= 1.1.3            (http://www.xiph.org/ogg/)
+* freetype >= 2.3.5          (http://www.freetype.org)
+* FLAC >= 1.2.1              (http://flac.sourceforge.net)
+
+The next step would be to build and install those dependencies in the
+correct order as required by your specific operating system. Once done
+with it, you can go on to build Pygame2.
+
+Building Pygame2
+----------------
+Now that all dependencies are built and installed, you can proceed to
+build and install Pygame2 itself. You can either use the python way of
+installing the package or the make command using the Makefile.
+
+Simply type ::
+
+  python setup.py install 
+
+for the traditional python way or ::
+
+  make install
+
+for using the Makefile. This will try to perform a default installation
+with as many features as possible.

File doc/BuildVC.txt

 For later Python releases, Visual Studio.NET 2008 or Visual C++ 2008 Express
 are required. 
 
+.. note::
+
     NOTE: If you are going to use the VC Toolkit 2003, make sure, you have some
     proper registry keys set. Otherwise Python's distutils will not be able to
     detect the settings. Within the util/ directory you can find an example
 
 Setting up the dependencies
 ---------------------------
+
+.. note::
+
     NOTE: The following list of dependencies might not be the most actual
     one. Please check the README.txt file in the top source directory
     for the most actual dependency list!
 * SDL_mixer >= 1.2.8         (http://www.libsdl.org/projects/SDL_mixer/)
 * SDL_ttf >= 2.0.9           (http://www.libsdl.org/projects/SDL_ttf/)
 * SDL_image >= 1.2.6         (http://www.libsdl.org/projects/SDL_image/)
-* SDL_gfx >= 2.0.17          (http://www.ferzkopp.net/Software/SDL_gfx-2.0/)
+* SDL_gfx >= 2.0.18          (http://www.ferzkopp.net/Software/SDL_gfx-2.0/)
 * libpng >= 1.2.24           (http://www.libpng.org)
 * libjpeg >= 6b              (http://www.ijg.org/)
 
 _searchdirs entry within the config/config_win.py script to include the
 directories.
 
-    NOTE: At this point, we strongly recommend a directory named 'prebuilt'
+.. note::
+
+    At this point, we strongly recommend a directory named 'prebuilt'
     that is created under the Pygame2 source directory.
 
-    NOTE: You can find a set of prebuilt dependencies at
-    http://www3.telus.net/len_l/pygame/
-    Simply download the matching Win32 prebuilt package and unpack it within the
-    source directory of pgreloaded.
+.. note::
 
-    NOTE: The 'prebuilt' directory should have the following layout:
-    prebuilt\include    -> Contains all header files and header subdirectories
+    You can find a set of prebuilt dependencies at
+    http://www3.telus.net/len_l/pygame/. Simply download the matching
+    Win32 prebuilt package and unpack it within the source directory of
+    pgreloaded.
+
+.. note::
+
+    The 'prebuilt' directory should have the following layout:
+
+    prebuilt\\include    -> Contains all header files and header subdirectories
     as installed by the dependencies.
-    prebuilt\lib        -> Contains all library files (both, .dll and .lib)
+
+    prebuilt\\lib        -> Contains all library files (both, .dll and .lib)
     as installed by the dependencies.
 
 Building Pygame2
 ----------------
-If anything you can proceed to build and install Pygame2 itself. Simply type:
+If anything you can proceed to build and install Pygame2 itself. Simply
+type: ::
 
     python setup.py build install
 
 
 You also can use the small build.bat batch script, which optionally can
 set up the VC++ include and library paths. Change it to your needs and
-then execute it using
+then execute it using ::
 
     build.bat
 

File doc/MODULES.txt

+============================
+Creating modules for Pygame2
+============================
+
 Creating a new module is a piece of cake. In order to maintain a similar
 layout for all modules, you should respect some minor rules.
 
 support Python 2.4, include the "pgcompat.h" header file, where
 appropriate.
 
-C module naming
+C Module Naming
 ---------------
 In case the module is a wrapper around an existing library, the module's
 should be similar to that of the library. The module name should be all
 lowercase and do not have any other characters besides a-z in its name.
 
-Example:
+Example: ::
+
   SDL_gfx  -> sdlgfx
   SDL      -> sdl
   MyOwnLib -> myownlib
   ...
 
 The module (or modules) source files should match the following naming
-conventions:
+conventions: ::
 
-Module C source:  MODULENAMEmod.c
-C API header:     pgMODULENAME.h
-Classes:          CLASSNAME.c
+  Module C source:  MODULENAMEmod.c
+  C API header:     pgMODULENAME.h
+  Classes:          CLASSNAME.c
 
 The file names are all lowercase, MODULENAME has to be replaced with the
 name of the module (see above), CLASSNAME is the name of the class to
 be easy to determine the module header, module code and class code files
 on a first glance, without looking at the contents of the files.
 
-Example:
-   Module C source: sdlimage -> sdlimagemod.c, imagemod.c, ...
-   C API header:    sdlimage -> pgsdlimage.h, pgimage.h, ...
-   Classes:         Surface  -> surface.c
-                    Mask     -> mask.c
+Example: ::
+
+  Module C source: sdlimage -> sdlimagemod.c, imagemod.c, ...
+  C API header:    sdlimage -> pgsdlimage.h, pgimage.h, ...
+  Classes:         Surface -> surface.c,
+                   Mask -> mask.c
 
 Make sure, the C API header does not conflict with another header to be
 installed. Headers used on the module scope only (internally used
 replaced with the name of the module and SUBMODULE with an existing
 submodule.
 
-Example:
-  pygame2.sdl.video -> import_pygame2_sdl_video()
-  pygame2.sdlttf    -> import_pygame2_sdlttf()
-  ...
+  +-------------------+----------------------------+
+  | pygame2.sdl.video | import_pygame2_sdl_video() |
+  +-------------------+----------------------------+
+  | pygame2.sdlttf    | import_pygame2_sdlttf()    |
+  +-------------------+----------------------------+
+  | ...               | ...                        |
+  +-------------------+----------------------------+  
 
 The rest of the C API should follow the Python naming conventions. You
 can take a look at the existing headers for examples on how to do it.
 If you have plain C functions you would like to become an own C library,
-use the pyg_ prefix to indicate it. Those functions must not have any reference
+use the pyg\_ prefix to indicate it. Those functions must not have any reference
 to the Python API and should be seperated from the rest of the code so that
 merging them into an own library is as easy as possible.
 
-Example (see src/sdlext, draw.c and draw.h):
+Example (see src/sdlext, draw.c and draw.h): ::
+
     int pyg_draw_aaline (...);
     int pyg_draw_line (...);
     ...
   
-C module build system
+C Module Build System
 ---------------------
 Add your newly created module to the modules list in modules.py. Doing
 that is pretty straight forward and should not be too complex. A new
-entry looks like this:
+entry looks like this: ::
 
-        Module ("MODULENAME", [ "SOURCEFILE.c", "SOURCEFILE.c", ... ],
-                [ "pgCAPIHEADER.h", "pgCAPIHEADER.h", ...], "DOCFILE.xml")
+  Module ("MODULENAME", [ "SOURCEFILE.c", "SOURCEFILE.c", ... ],
+          [ "pgCAPIHEADER.h", "pgCAPIHEADER.h", ...], "DOCFILE.xml")
 
 In case you have submodules, you would split anything according to your
 needs. You can see how submodules are added by looking at the various
 DOCFILE.xml is the name of the documentation file to use, which is located
 under doc/src (see below, "Documenting").
 
-Example:
+Example: ::
+
   Module ("myownlib",[ "src/myownlib/myownlibmod.c", "src/myownlib/myclass.c" ],
                      [ "src/myownlib/pgmyownlib.h" ], "myownlib.xml")
 
 If the module has external dependencies, which cannot be guaranteed to
-be available on each platform, add a
+be available on each platform, add a ::
 
-    WITH_MOD = istrue (os.getenv ("WITH_MOD", True))
+  WITH_MOD = istrue (os.getenv ("WITH_MOD", True))
 
 to the cfg.py configuration file so that users can enable/disable the
 module on demand using the build and environment settings.
 within cfg.py, it MUST check for WITH_MOD and has to be enabled or disabled
 according to that entry.
 
-Example:
+Example: ::
+  
   if WITH_MYOWNLIB:
       # Module should be build. MyOwnLib is available according to the
       # user.
       # Disable the module.
       mod.canbuild = False
 
-C Module dependencies
+C Module Dependencies
 ---------------------
 If you have inter-module dependencies (e.g. parts of pygame.myownlib can make
 use of pygame.sdl.video), you have to check, whether the specific module is
 available. In your C code, you can test for certain defines, which ease this
 process. Each module creates a HAVE_PYGAME_MODULENAME define to test for.
-To check for e.g. pygame.sdl.video, you can use
+To check for e.g. pygame.sdl.video, you can use::
 
-#ifdef HAVE_PYGAME_SDL_VIDEO
-  /* Code that relies upon pygame.sdl.video */
-#endif
+  #ifdef HAVE_PYGAME_SDL_VIDEO
+    /* Code that relies upon pygame.sdl.video */
+  #endif
 
 Make sure, you load the correct modules within the module initialization
 function. Take a look at the src/mask/maskmod.c module file for an example.
 
-Build environment dependencies
+Build Environment Dependencies
 ------------------------------
 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
 added at compile time. Currently, the following flags are available:
 
-  IS_WIN32      - Win32 build with Visual C++
-  IS_MSYS       - (Win32) Msys build with GCC
-  IS_UNIX       - Any other build plattform that successfully passes the
-                  preparations
+  IS_WIN32 - Win32 build with Visual C++
+  IS_MSYS  - (Win32) Msys build with GCC
+  IS_UNIX  - Any other build plattform that successfully passes the preparations
 
 You can easily check for those flags in the C code using the usualy preprocessor
-magic:
+magic: ::
 
-#ifdef IS_WIN32 
-  /* Visual C++ specific Win32 instructions */
-#elif defined(IS_MSYS)
-  /* GCC/Msys specific Win32 instructions */
-#elif defined(IS_UNIX)
- /* Unix specific instructions */
-#endif
+  #ifdef IS_WIN32 
+    /* Visual C++ specific Win32 instructions */
+  #elif defined(IS_MSYS)
+    /* GCC/Msys specific Win32 instructions */
+  #elif defined(IS_UNIX)
+   /* Unix specific instructions */
+  #endif
 
-Python modules
+Python Modules
 --------------
 Python modules have no special restriction, but should follow the
 typical python conventions. The files should be named all lowercase and
 in doc/src/. They are all XML files and must have a ".xml" suffix in order to
 be recognized by the documentation build system.
 
-*** Python Modules ***
+Python Modules
+^^^^^^^^^^^^^^
 Once you have written your module, you can create a documentation template for
-it using the create_doc.py script. Simply type 
+it using the create_doc.py script. Simply type ::
 
   python create_doc.py pygame2.myownlib myownlib.xml
   
 If you documented your python code properly, there won't be any empty sections
 within the documentation ;-).
 
-*** C Modules *** 
-
+C Modules 
+^^^^^^^^^
 C Modules require the documentation to be available at compile time,
 which involves two steps to set up the initial documentation. The
 documentation system creates C header files from the XML files
 documentation as you develop the C code. See below for the C constants to use.
 
 If you have an already written module, integrate it first (as described above),
-then run the create_doc.py script on it:
+then run the create_doc.py script on it: ::
  
   python create_doc.py pygame2.myownlib myownlib.xml
 
 Include the "DOCFILE_doc.h" header file, then use the proper constants for all
 things to document.
 
-*** C documentation constants ***
-
+C Documentation Constants
+^^^^^^^^^^^^^^^^^^^^^^^^^
 The C constants are generated using the DOC_MODULENAME_CLASSNAME_NAME scheme.
 The following constants are used:
 
-DOC_MODULENAME             - The documentation for the module.
-DOC_MODULENAME_FUNCNAME    - The documentation for a module function.
-DOC_MODULENAME_CLASSNAME   - The documentation for a class.
-DOC_MODULENAME_CLASSNAME_X - The documentation for a class method or attribute.
+  +---------------------------+-------------------------------------------+
+  | DOC_MODULENAME            | The documentation for the module.         |
+  +---------------------------+-------------------------------------------+
+  | DOC_MODULENAME_FUNCNAME   | The documentation for a module function.  |
+  +---------------------------+-------------------------------------------+
+  | DOC_MODULENAME_CLASSNAME  | The documentation for a class.            |
+  +---------------------------+-------------------------------------------+
+  |DOC_MODULENAME_CLASSNAME_X | The documentation for a class method or   |
+  |                           | attribute.                                |
+  +---------------------------+-------------------------------------------+
 
 Take a look at the src/base code to learn more about it.

File doc/MODULE_FAQ.txt

-C API
------
+============
+C Module FAQ
+============
 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.
 environment, you can check for the build system flags, which are automatically
 added at compile time. Currently, the following flags and macros are available:
 
-  IS_WIN32      - Win32 build with Visual C++
-  IS_MSYS       - (Win32) Msys build with GCC
-  IS_UNIX       - Any other build platform that successfully passes the
-                  preparations
+  +-----------+----------------------------------------+
+  |  IS_WIN32 | Win32 build with Visual C++            |
+  +-----------+----------------------------------------+
+  | IS_MSYS   | (Win32) Msys build with GCC            |
+  +-----------+----------------------------------------+
+  | IS_UNIX   | Any other build platform that          |
+  |           | successfully passes the preparations   |
+  +-----------+----------------------------------------+
 
 base/pgdefines.h contains some useful numeric macros:
 
-  MIN(x,y)       - returns the minimum of two values
-  MAX(x,y)       - returns the maximum of two values
-  ABS(x)         - returns the absolute value
-  trunc(x)       - truncates a number
-  round(x)       - rounds a number
-  DEG2RAD(x)     - converts degrees to radians
-  DEG2RAD(x)     - converts radians to degrees
-  ADD_LIMIT(x,y) - variable addition using overflow limits
-  SUB_LIMIT(x,y) - variable subtraction using overflow limits
+  +----------------+--------------------------------------------+
+  | MIN(x,y)       | Returns the minimum of two values          |
+  +----------------+--------------------------------------------+
+  | MAX(x,y)       | Returns the maximum of two values          |
+  +----------------+--------------------------------------------+
+  | ABS(x)         | Returns the absolute value                 |
+  +----------------+--------------------------------------------+
+  | trunc(x)       | Truncates a number                         |
+  +----------------+--------------------------------------------+
+  | round(x)       | Rounds a number                            |
+  +----------------+--------------------------------------------+
+  | DEG2RAD(x)     | Converts degrees to radians                |
+  +----------------+--------------------------------------------+
+  | DEG2RAD(x)     | Converts radians to degrees                |    
+  +----------------+--------------------------------------------+
+  | ADD_LIMIT(x,y) | Variable addition using overflow limits    |
+  +----------------+--------------------------------------------+
+  |SUB_LIMIT(x,y)  | variable subtraction using overflow limits |
+  +----------------+--------------------------------------------+
 
 Besides that it contains various ready-to-use macros for signed/unsigned
 integer and double additions and subtractions with overflow checking.
 or floating point value from a PyObject. Those however require other
 modules to import the base module.
 
-* Text handling *
-
+Text Handling
+-------------
 For text guaranteed to be UTF-8 or ASCII, use the related Text_***() macros
 instead of the specific PyUnicode/PyString APIs. The Text_***() macros assure
 that for each Python version the current API is used.
 For other objects that contain text (but not necessarily UTF-8 or ASCII), use 
 the UTF8FromObject() and ASCIIFromObject() conversion functions.
 
-* Sizes and points *
-
+Sizes And Points
+----------------
 Whereever typical two-value tuples for denoting points or sizes are necessary
 or used, use the [F]PointFromObject() and [F]SizeFromObject() functions from 
 base/pgbase.h. Those guarantee interoperability with rectangular arguments,
 tuples, lists and any other sequence and take care of the most basic value
 checks.
 
-* SDL Rectangles *
-
+SDL Rectangles
+--------------
 sdl/pgsdl.h defines some handy routines to quickly get a SDL_Rect from
 the base.Rect and base.FRect classes, SDLRect_FromRect(). Use it
 wherever methods require a rectangular object. IsValidRect() checks only,
 whether the passed argument is a base.Rect or base.FRect.
 
-* SDL surface pixel manipulation *
-
+SDL Surface Pixel Manipulation
+------------------------------
 sdl/surface.h contains tons of macros to manipulate surface pixels. It
 should be your first address to look for a matching operation whenever
 you need it.
 
-* SDL color handling *
-
+SDL Color Handling
+------------------
 The Color class uses an ARGB layout for PyColor_AsNumber(). In order to
 prepare this value for color operations within the SDL functions or
 pixel manipulations, use the RGB2FORMAT() and ARGB2FORMAT() macros,
 defined in sdl/surface.h.
 
-* SDL subsystems *
-
+SDL Subsystems
+--------------
 Whenever you require a certain subsystem to be available, use the
 corresponding ASSERT_***_INIT() macro from sdl/pgsdl.h.

File doc/Makefile

 
 .PHONY: rst help clean html web pickle htmlhelp latex changes linkcheck
 
+all: help
+
 rst: clean
 	@$(PYTHON) create_rstref.py
 	-cp -f BuildMinGW.txt buildmingw.rst
 	-cp -f BuildVC.txt buildvc.rst
+	-cp -f BuildUnix.txt buildunix.rst
+	-cp -f MODULES.txt newmodules.rst
+	-cp -f MODULE_FAQ.txt module_faq.rst
 
 help:
 	@echo "Please use \`make <target>' where <target> is one of"
 
 clean:
 	-rm -rf sphinx/build *~ *.pyc ref html
-	-rm -f buildmingw.rst buildvc.rst 
+	-rm -f buildmingw.rst buildunix.rst buildvc.rst
+	-rm -f newmodules.rst module_faq.rst
 
 html: rst
 	mkdir -p sphinx/build/html sphinx/build/doctrees

File doc/api_template.xml

 <?xml version="1.0" encoding="utf-8" ?>
-
-<!DOCTYPE module [
-<!ELEMENT module (short, desc, (func | class)*)>
-<!ATTLIST module name CDATA #REQUIRED>
-
-<!ELEMENT desc (#PCDATA)>
-<!ELEMENT short (#PCDATA)>
-<!ELEMENT call (#PCDATA)>
-
-<!ELEMENT func (call, desc)>
-<!ATTLIST func name CDATA #REQUIRED>
-
-<!ELEMENT class (constructor, desc, (attr | method)*)>
-<!ATTLIST class name CDATA #REQUIRED>
-<!ELEMENT constructor (#PCDATA)>
-<!ELEMENT attr (#PCDATA)>
-<!ATTLIST attr name CDATA #REQUIRED>
-<!ELEMENT method (call, desc)>
-<!ATTLIST method name CDATA #REQUIRED>
-
-]>
+<!DOCTYPE module SYSTEM "api.dtd">
 
 <!-- 
-     Pygame C API template for generating the C code doc strings and 
+     Pygame2 C API template for generating the C code doc strings and 
      RST/HTML documentation.
 -->
+
 <module name="NAME">
   <short>SHORT DESC (single line)</short>
   <desc>DESCRIPTION</desc>
+  <example>EXAMPLE CODE</example>
   
-    <func name="METHODNAME">
-      <call>FUNC()</call>
+  <func name="METHODNAME">
+    <call>FUNC()</call>
+    <desc>DESCRIPTION</desc>
+    <example>EXAMPLE CODE</example>
+  </func>
+  
+  <class name="CLASSNAME">
+    <cosntructor>CLASS()</cosntructor>
+    <desc>DESCRIPTION</desc>
+    <example>EXAMPLE CODE</example>
+    <attr name="NAME">
       <desc>DESCRIPTION</desc>
-    </func>
-    
-    <class name="CLASSNAME">
-      <cosntructor>CLASS()</cosntructor>
+      <example>EXAMPLE CODE</example>
+    </attr>
+    <method name="METHODNAME">
+      <call>METHOD()</call>
       <desc>DESCRIPTION</desc>
-      <attr name="NAME">DESCRIPTION</attr>
-      <method name="METHODNAME">
-        <call>METHOD()</call>
-        <desc>DESCRIPTION</desc>
-      </method>
+      <example>EXAMPLE CODE</example>
+    </method>
     </class>
   </module>

File doc/building.rst

 Building Pygame2 on your platform
 #################################
 
-Building pygame2 XXX
+These section provide an overview and guidance for building and
+installing pygame2 on various target platforms. Currently building
+instructions for Unix compatible operating system and Microsoft Windows
+exist.
 
 Contents:
 
 
    buildmingw.rst
    buildvc.rst
+   buildunix.rst
+
+Besides those build instructions, pygame2's build process can be tweaked
+for all target platforms as described below.
+
+Environment Settings
+====================
+You can use certain environment settings to influence the build. Those
+are evaluated in the "cfg.py" file in the top source directory and can
+be tweaked directly within that file, too.
+
+By default, the build system will test for certain environment variables
+being set to control the build of various features. If they are *not*
+available, the build system assumes that you want to have as many
+features as possible and thus will enable them.
+
+Currently the following environment variables are controlling, which
+components of pgreloaded should be build: ::
+
+  WITH_SDL=[yes|no|1|True]                Example: make -DWITH_SDL=yes
+
+Build and install the :mod:`pygame2.sdl` module. This wraps the SDL
+library and is required for any other SDL related module in
+pygame2. ::
+
+  WITH_SDL_MIXER=[yes|no|1|True]          Example: make -DWITH_SDL_MIXER=no
+
+Build and install the :mod:`pygame2.sdlmixer` module. This wraps the
+SDL_mixer library. ::
+
+  WITH_SDL_IMAGE=[yes|no|1|True]          Example: make -DWITH_SDL_IMAGE=True
+
+Build and install the :mod:`pygame2.sdlimage` module. This wraps the
+SDL_image library. ::
+
+  WITH_SDL_TTF=[yes|no|1|True]            Example: make -DWITH_SDL_TTF=True
+
+Build and install the :mod:`pygame2.sdlttf` module. This wraps the
+SDL_ttf library. ::
+
+  WITH_SDL_GFX=[yes|no|1|True]            Example: make -DWITH_SDL_GFX=1
+
+Build and install the :mod:`pygame2.sdlgfx` module. This wraps the
+SDL_gfx library. ::
+
+  WITH_PNG=[yes|no|1|True]                Example: make -DWITH_PNG=True
+
+Build with PNG format saving support for
+:meth:`pygame2.sdl.video.Surface.save`. ::
+
+  WITH_JPEG=[yes|no|1|True]               Example: make -DWITH_JPEG=False
+
+Build with JPEG format saving support for
+:meth:`pygame2.sdl.video.Surface.save`.
+

File doc/capi.rst

 Pygame2 C API
 #############
 
-Pygame2's C API 
+The following sections cover the internal C API of Pygame2. The C API is useful
+for implementing your own C extension or if you require some Python to C
+interoperatibility.
 
-C API:
+Notes on Reading
+================
+All methods and functions covered by this C API usually check their arguments
+for the correct value range, types and so on. If they fail due to wrong
+arguments or an internal error, they will either set an exception using::
+
+  PyErr_SetString (EXC_TYPE, MESSAGE)
+
+or escalate the exception, if it was set in another place.
+
+Those methods, which do not set an exception on failure or do not check their
+arguments, are clearly marked as such.
+
+API Reference
+=============
 
 .. toctree::
 
   capi/sdlbase.rst
   capi/sdlcdrom.rst
   capi/sdlevent.rst
+  capi/sdljoystick.rst
+  capi/sdlmouse.rst
+  capi/sdlvideo.rst
+  capi/sdlrwops.rst
+  capi/sdlext.rst
+  capi/sdlgfx.rst
+  capi/sdlttf.rst
+

File doc/capi/base.rst

 
   .. cmember:: pgint16 CRect.x
 
-    The topleft x coordinate of the CRect.
+    The topleft x coordinate of the :ctype:`CRect`.
 
   .. cmember:: pgint16 CRect.y
 
-    The topleft y coordinate of the CRect.
+    The topleft y coordinate of the :ctype:`CRect`.
 
   .. cmember:: pguint16 CRect.w
 
-    The width of the CRect.
+    The width of the :ctype:`CRect`.
 
   .. cmember:: pguint16 CRect.h
 
-    The height of the CRect.
+    The height of the :ctype:`CRect`.
 
 Macros
 ------
                INT16_SUB_LIMIT(x,y)
 
    Adds and subtracts two integer values, but guarantees that the result will
-   not be smaller or larger than the INT_MIN and INT_MAX limits.
+   not be smaller or larger than the *INT_MIN* and *INT_MAX* limits.
 
 .. cfunction:: UINT_ADD_LIMIT(x,y)
                UINT_SUB_LIMIT(x,y)
                UINT16_SUB_LIMIT(x,y)
 
    Adds and subtracts two unsigned integer values, but guarantees that the
-   result will not be smaller or larger than zero and UINT_MAX.
+   result will not be smaller or larger than zero and *UINT_MAX*.
 
 .. cfunction:: LONG_ADD_LIMIT(x,y)
                LONG_SUB_LIMIT(x,y)
                INT32_SUB_LIMIT(x,y)
 
    Adds and subtracts two long integer values, but guarantees that the result
-   will not be smaller or larger than the LONG_MIN and LONG_MAX limits.
+   will not be smaller or larger than the *LONG_MIN* and *LONG_MAX* limits.
 
 .. cfunction:: ULONG_ADD_LIMIT(x,y)
                ULONG_SUB_LIMIT(x,y)
                UINT32_SUB_LIMIT(x,y)
 
    Adds and subtracts two unsigned long integer values, but guarantees that the
-   result will not be smaller or larger than zero and ULONG_MAX.
+   result will not be smaller or larger than zero and *ULONG_MAX*.
 
 .. cfunction:: DBL_ADD_LIMIT(x,y)
                DBL_SUB_LIMIT(x,y)
 
    Adds and subtracts two floating point values, but guarantees that the result
-   will not be smaller or larger than the DBL_MIN and DBL_MAX limits.
+   will not be smaller or larger than the *DBL_MIN* and *DBL_MAX* limits.
 
 .. cfunction:: INT_ADD_UINT_LIMIT(x,y,z)
                INT_SUB_UINT_LIMIT(x,y,z)
                INT16_SUB_UINT16_LIMIT(x,y,z)
 
     Adds and subtracts an unsigned integer *y* to an integer *x* and stores the
-    result in the integer *z*. If the operation will exceed the INT_MIN and
-    INT_MAX limits, *z* will be set to INT_MIN or INT_MAX.
+    result in the integer *z*. If the operation will exceed the *INT_MIN* and
+    *INT_MAX* limits, *z* will be set to *INT_MIN or *INT_MAX*.
 
 Errors
 ------
 .. cfunction:: int DoubleFromObj (PyObject* obj, double *val)
 
   Tries to convert the PyObject to a double and stores the result in *val*, if
-  successful. If it does not succeed, 0 will be returned and an exception be
-  set, otherwise it will return 1.
+  successful. This returns 1 on success and 0 on failure.
+
+  This will not check the arguments for being *NULL*.
 
 .. cfunction:: int IntFromObj (PyObject* obj, int *val)
 
   Tries to convert the PyObject to an int and stores the result in *val*, if
-  successful. If it does not succeed, 0 will be returned and an exception be
-  set, otherwise it will return 1.
+  successful. This returns 1 on success and 0 on failure.
+
+  This will not check the arguments for being *NULL*.
 
 .. cfunction:: int UintFromObj (PyObject* obj, unsigned int *val)
 
   Tries to convert the PyObject to an unsigned int and stores the result in
-  *val*, if successful. If it does not succeed, 0 will be returned and an
-  exception be set, otherwise it will return 1.
+  *val*, if successful. This returns 1 on success and 0 on failure.
+
+  This will not check the arguments for being *NULL*.
 
 .. cfunction:: int DoubleFromSeqIndex (PyObject *seq, Py_ssize_t index, double *val)
 
   Tries to get the item at the desired *index* from the passed sequence object
-  and converts it to a double, which will be stored in *val*. If it does not
-  succeed, 0 will be returned and an exception be set, otherwise it will return
-  1.
+  and converts it to a double, which will be stored in *val*. This returns 1 on
+  success and 0 on failure.
+
+  This will not check the arguments for being *NULL*.
 
 .. cfunction:: int IntFromSeqIndex (PyObject *seq, Py_ssize_t index, int *val)
 
   Tries to get the item at the desired *index* from the passed sequence object
-  and converts it to an int, which will be stored in *val*. If it does not
-  succeed, 0 will be returned and an exception be set, otherwise it will return
-  1.
+  and converts it to an int, which will be stored in *val*. This returns 1 on
+  success and 0 on failure.
+
+  This will not check the arguments for being *NULL*.
 
 .. cfunction:: int UintFromSeqIndex (PyObject *seq, Py_ssize_t index, unsigned int *val)
 
   Tries to get the item at the desired *index* from the passed sequence object
-  and converts it to an unsigned int, which will be stored in *val*. If it does
-  not succeed, 0 will be returned and an exception be set, otherwise it will
-  return 1.
+  and converts it to an unsigned int, which will be stored in *val*. This
+  returns 1 on success and 0 on failure.
+
+  This will not check the arguments for being *NULL*.
 
 .. cfunction:: int PointFromObject (PyObject *obj, int *x, int *y)
 
   Tries to get two int values from the passed object. If the object is a
   :ctype:`PyRect` or :ctype:`PyFRect`, the topleft x and y values are taken,
-  if the object is a sequence type, the first two items are used.  If it does
-  not succeed, 0 will be returned and an exception be set, otherwise it will
-  return 1.
+  if the object is a sequence type, the first two items are used. This returns
+  1 on success and 0 on failure.
+
+  This will not check the arguments for being *NULL*.
 
 .. cfunction:: int SizeFromObject (PyObject *obj, pgint32 *x, pgint32 *y)
 
   Tries to get two pgint32 values from the passed object. If the object is a
   :ctype:`PyRect` or :ctype:`PyFRect`, the width and height values are taken,
-  if the object is a sequence type, the first two items are used. If it does
-  not succeed, 0 will be returned and an exception be set, otherwise it will
-  return 1.
+  if the object is a sequence type, the first two items are used. This returns
+  1 on success and 0 on failure.
+
+  This will not check the arguments for being *NULL*.
 
 .. cfunction:: int FPointFromObject (PyObject *obj, double *x, double *y)
 
   Tries to get two double values from the passed object. If the object is a
   :ctype:`PyRect` or :ctype:`PyFRect`, the topleft x and y values are taken,
-  if the object is a sequence type, the first two items are used.  If it does
-  not succeed, 0 will be returned and an exception be set, otherwise it will
-  return 1.
+  if the object is a sequence type, the first two items are used. This returns
+  1 on success and 0 on failure.
+
+  This will not check the arguments for being *NULL*.
 
 .. cfunction:: int FSizeFromObject (PyObject *obj, double *x, double *y)
 
   Tries to get two double values from the passed object. If the object is a
   :ctype:`PyRect` or :ctype:`PyFRect`, the width and height values are taken,
-  if the object is a sequence type, the first two items are used. If it does
-  not succeed, 0 will be returned and an exception be set, otherwise it will
-  return 1.
+  if the object is a sequence type, the first two items are used. This returns
+  1 on success and 0 on failure.
+
+  This will not check the arguments for being *NULL*.
 
 .. cfunction:: int ASCIIFromObject (PyObject *obj, char** text, PyObject **convobj)
 
   Tries to get ASCII text from the passed object and stores the result in
   *text*. If the object has to be converted, the conversion result will be
   stored in *convobj* and needs to be freed by the caller, once *text* is not
-  required anymore.
+  required anymore. This returns 1 on success and 0 on failure.
+
+  This will not check the arguments for being *NULL*.
 
 .. cfunction:: int UTF8FromObject (PyObject *obj, char** text, PyObject **convobj)
 
   Tries to get UTF-8 encoded text from the passed object and stores the result
   in *text*. If the object has to be converted, the conversion result will be
   stored in *convobj* and needs to be freed by the caller, once *text* is not
-  required anymore.
+  required anymore. This returns 1 on success and 0 on failure.
+
+  This will not check the arguments for being *NULL*.
 
 PyColor
 -------
   Returns true, if the argument is a :ctype:`PyColor` or a subclass of
   :ctype:`PyColor`.
 
-.. cfunction:: PyObject* PyColor_New (pgbyte[] rgba)
+.. cfunction:: PyObject* PyColor_New (pgbyte rgba[])
 
   Creates a new :ctype:`PyColor` object from the passed 4-value RGBA array. On
   failure, this returns NULL.
 .. cfunction:: pguint32 PyColor_AsNumber (PyObject *color)
 
   Returns the 32-bit ARGB integer representation of the :ctype:`PyColor` object.
-  If the passed *color* is not a :ctype:`PyColor` object, 0 will be returned
-  and a :exc:`TypeError` set.
+  On failure, this returns 0. As 0 might be a valid color, you should check
+  for an error explicitly using :cfunc:`PyErr_Occured`.
 
 PyRect
 ------
 .. cmember:: void* PyBufferProxy.buffer
 
   A pointer to the underlying C buffer contents.
-  
+
 .. cmember:: Py_ssize_t PyBufferProxy.length
 
   The length of the buffer in bytes
-  
+
 .. cmember:: bufferunlock_func PyBufferProxy.unlock_func
 
   The unlock function callback hook. bufferunlock_func is defined as::
-  
+
     int (*bufferunlock_func)(PyObject* object, PyObject* buffer)
-  
+
 Functions
 ^^^^^^^^^
 .. cfunction:: int PyBufferProxy_Check (PyObject *obj)
   :ctype:`PyBufferProxy`.
 
 .. cfunction:: void* PyBufferProxy_AsBuffer (PyObject *obj)
+
+  Macro for accessing the *buffer* member of the :ctype:`PyBufferProxy`.
   
-  Macro for accessing the *buffer* member of the :ctype:`PyBufferProxy`.
-  This does not perform any type checks.
+  This does not perform any type or argument checks.
 
 .. cfunction:: PyObject* PyBufferProxy_New (PyObject *object, void *buffer, Py_ssize_t length, bufferunlock_func func)
 
   Gets the size of the :ctype:`PySurface` instance. *self* is the
   :ctype:`PySurface` itself, the *closure* argument is the same as for the
   Python C API getter definition.
-  
+
 .. cfunction:: PyObject* (*get_pixels) (PyObject *self, void *closure)
 
   Gets the raw pixels of the :ctype:`PySurface` instance. *self* is the
   :ctype:`PySurface` itself, the *closure* argument is the same as for the
   Python C API getter definition.
-  
+
 .. cfunction:: PyObject* (*blit)(PyObject *self, PyObject *args, PyObject *kwds)
 
   Blits the :ctype:`PySurface` onto some other :ctype:`PySurface` or whatever
   is appropriate for the concrete implementation. *self* is the
   :ctype:`PySurface` itself, the *args* and *kwds* arguments are the same as for
   the Python C API method definition.
-  
+
 .. cfunction:: PyObject* (*copy)(PyObject *self)
 
   Creates an exact copy of the :ctype:`PySurface`. *self* is the
   :ctype:`PySurface` itself.
-  
+
 Functions
 ^^^^^^^^^
 .. cfunction:: int PySurface_Check (PyObject *obj)

File doc/capi/mask.rst

 
 .. cfunction:: bitmask_t* PyMask_AsBitmask (PyObject *obj)
 
-  Macro for accessing the *mask* member of the :ctype:`PyMask`. This
-  does not perform any type checks.
+  Macro for accessing the *mask* member of the :ctype:`PyMask`.
+
+  This does not perform any type or argument checks.
 
 .. cfunction:: PyObject* PyMask_New (int width, int height)
 

File doc/capi/sdlbase.rst

 and related modules. They are used to check whether certain parts of the
 SDL subsystems are properly set and initialised.
 
-.. cfunction:: ASSERT_JOYSTICK_INIT (retval)
-
-  Checks, whether the joystick subsystem was properly initialised. If
-  not, this will set a :exc:`PyExc_PyGameError` and return *retval*.
-
-.. cfunction:: ASSERT_JOYSTICK_OPEN (obj, retval)
-
-  Checks, whether the passed :ctype:`PyJoystick` is open for access. If
-  not, this will set a :exc:`PyExc_PyGameError` and return *retval*.
-
 .. cfunction:: ASSERT_TIME_INIT (retval)
 
   Checks, whether the time subsystem was properly initialised. If not,
   this will set a :exc:`PyExc_PyGameError` and return *retval*.
 
-.. cfunction:: ASSERT_VIDEO_INIT (retval)
-
-  Checks, whether the video subsystem was properly initialised. If not,
-  this will set a :exc:`PyExc_PyGameError` and return *retval*.
-
-.. cfunction:: ASSERT_VIDEO_SURFACE_SET (retval)
-
-  Checks, whether a display surface was created already using
-  :func:`pygame2.sdl.video.set_mode`. If not, this will set a
-  :exc:`PyExc_PyGameError` and return *retval*.
-
 Functions
 ---------
 
   
     void (*quit_func)(void)
 
+  This will not check the argument for being *NULL*.
+
 .. cfunction:: int Uint8FromObj (PyObject *obj, Uint8 *val)
 
   Tries to convert the PyObject to a Uint8 and stores the result in
-  *val*, if successful. If it does not succeed, 0 will be returned and
-  an exception be set, otherwise it will return 1.
+  *val*, if successful. This returns 1 on success and 0 on failure.
+  
+  This will not check the arguments for being *NULL*.
 
 .. cfunction:: int Uint16FromObj (PyObject *obj, Uint16 *val)
 
   Tries to convert the PyObject to a Uint16 and stores the result in
-  *val*, if successful. If it does not succeed, 0 will be returned and
-  an exception be set, otherwise it will return 1.
+  *val*, if successful. This returns 1 on success and 0 on failure.
+
+  This will not check the arguments for being *NULL*.
 
 .. cfunction:: int Sint16FromObj (PyObject *obj, Sint16 *val)
 
   Tries to convert the PyObject to a Sint16 and stores the result in
-  *val*, if successful. If it does not succeed, 0 will be returned and
-  an exception be set, otherwise it will return 1.
+  *val*, if successful. This returns 1 on success and 0 on failure.
+
+  This will not check the arguments for being *NULL*.
 
 .. cfunction:: int Uint32FromObj (PyObject *obj, Uint32 *val)
 
   Tries to convert the PyObject to a Uint32 and stores the result in
-  *val*, if successful. If it does not succeed, 0 will be returned and
-  an exception be set, otherwise it will return 1.
+  *val*, if successful. This returns 1 on success and 0 on failure.
+
+  This will not check the arguments for being *NULL*.
 
 .. cfunction:: int Uint8FromSeqIndex (PyObject *obj, Py_ssize_t index, Uint8 *val)
 
   Tries to get the item at the desired *index* from the passed sequence
-  object and converts it to a Uint8, which will be stored in *val*. If
-  it does not succeed, 0 will be returned and an exception be set,
-  otherwise it will return 1.
+  object and converts it to a Uint8, which will be stored in *val*. This
+  returns 1 on success and 0 on failure.
+
+  This will not check the arguments for being *NULL*.
 
 .. cfunction:: int Uint16FromSeqIndex (PyObject *obj, Py_ssize_t index, Uint16 *val)
 
   Tries to get the item at the desired *index* from the passed sequence
-  object and converts it to a Uint16, which will be stored in *val*. If
-  it does not succeed, 0 will be returned and an exception be set,
-  otherwise it will return 1.
+  object and converts it to a Uint16, which will be stored in *val*. This
+  returns 1 on success and 0 on failure.
+
+  This will not check the arguments for being *NULL*.
 
 .. cfunction:: int Sint16FromSeqIndex (PyObject *obj, Py_ssize_t index, Sint16 *val)
 
   Tries to get the item at the desired *index* from the passed sequence
-  object and converts it to a Sint16, which will be stored in *val*. If
-  it does not succeed, 0 will be returned and an exception be set,
-  otherwise it will return 1.
+  object and converts it to a Sint16, which will be stored in *val*. This
+  returns 1 on success and 0 on failure.
+
+  This will not check the arguments for being *NULL*.
 
 .. cfunction:: int Uint32FromSeqIndex (PyObject *obj, Py_ssize_t index, Uint32 *val)
 
   Tries to get the item at the desired *index* from the passed sequence
-  object and converts it to a Uint32, which will be stored in *val*. If
-  it does not succeed, 0 will be returned and an exception be set,
-  otherwise it will return 1.
+  object and converts it to a Uint32, which will be stored in *val*. This
+  returns 1 on success and 0 on failure.
+
+  This will not check the arguments for being *NULL*.
 
 .. cfunction:: int IsValidRect (PyObject *obj)
 
   case if, the object is either a :ctype::`PyRect` or :ctype::`PyFRect`
   instance or a 4-value sequence that carries two Sint16-compatible
   values two Uint16-compatible values in the order (Sint16, Sint16,
-  Uint16, Uint16). If the object is a valid rectangle object, 1 will be
-  returned, otherwise 0 and a :exc:`TypeError` be set.
+  Uint16, Uint16). This returns 1 on success and 0 on failure.
 
 .. cfunction:: int SDLRect_FromRect (PyObject *obj, SDL_Rect *rect)
 
    Tries to convert the passed object to a :ctype:`SDL_Rect` and stores
-   the result in the passed *rect*'s members. If the object is a valid
-   rectangle object (as for :cfunc:`IsValidRect`), 1 will be returned,
-   otherwise 0 and a :exc:`TypeError` be set.
+   the result in the passed *rect*'s members. The object must be a valid
+   rectangle object (as for :cfunc:`IsValidRect`). This returns 1 on success
+   and 0 on failure.

File doc/capi/sdlcdrom.rst

 .. cfunction:: SDL_CD* PyCD_AsCD (PyObject *obj)
 
   Macro for accessing the *cd* member of the :ctype:`PyCD`. This does
-  not perform any type checks.
+  not perform any type or argument checks.
 
 PyCDTrack
 ---------
 .. cfunction:: SDL_CDtrack* PyCDTrack_AsCDTrack (PyObject *obj)
 
   Macro for accessing the *track* member of the :ctype:`PyCDTrack`. This
-  does not perform any type checks.
+  does not perform any type or argument checks.

File doc/capi/sdlevent.rst

 The :mod:`pygame2.sdl.event` C API contains objects and functions for
 accessing and manipulating the SDL event system queue.
 
-TODO: describe user event encapsulation!
+.. todo::
+   
+   Describe user event encapsulation!
 
 Import
 ------
 
 Macros
 ------
-.. cmacro:: PYGAME_USEREVENT
+.. data:: PYGAME_USEREVENT
 
   Constant for SDL user event types. This is usually placed into the
   :cmember:`SDL_Event.data1` field for :cmacro:`SDL_USEREVENT` events.
 
-.. cmacro:: PYGAME_USEREVENT_CODE
+.. data:: PYGAME_USEREVENT_CODE
 
   Constant for SDL user event types. This is usually placed into the
   :cmember:`SDL_Event.code` field for :cmacro:`SDL_USEREVENT` events.
 .. cfunction:: int PyEvent_SDLEventFromEvent (PyObject *obj, SDL_Event *event)
 
   Fills the passed :ctype:`SDL_Event` *event* with the information of
-  the :ctype:`PyEvent`. On success, this will return 1. If the passed
-  *event* is NULL, 0 will be returned and a :exc:`ValueError` be set, if
-  the passed *obj* is not a :ctype:`PyEvent` a :exc:`TypeError` be set.
-  On any other error an exception will be raised and 0 returned.
+  the :ctype:`PyEvent`. This returns 1 on success and 0 on failure.

File doc/capi/sdlext.rst

+=========================
+pygame2.sdlext.base C API
+=========================
+
+The :mod:`pygame2.sdlext.base` C API contains objects and functions for
+accessing and manipulating :mod:`pygame2.sdl` objects in a specialised
+manner.
+
+Import
+------
+Include headers::
+
+  pygame2/pgsdlext.h
+
+.. cfunction:: int import_pygame2_sdlext_base (void)
+
+  Imports the :mod:`pygame2.sdlext.base` module. This returns 0 on
+  success and -1 on failure.
+
+PyPixelArray
+------------
+.. ctype:: PyPixelArray
+.. ctype:: PyPixelArray_Type
+
+The PyPixelArray object is used manipulating the design of the visible
+mouse cursor.
+
+Members
+^^^^^^^
+.. cmember:: PyObject* PyPixelArray.surface
+
+  The :ctype:`PySDLSurface` referenced by the :ctype:`PyPixelArray`.
+
+.. cmember:: PyObject* PyPixelArray.parent
+
+  The parent :ctype:`PyPixelArray`, if any.
+
+.. cmember:: Uint32 PyPixelArray.xstart
+
+  The X start offset for a subarray. For an initial :ctype:`PyPixelArray` this
+  will be 0.
+
+.. cmember:: Uint32 PyPixelArray.ystart
+
+  The Y start offset for a subarray. For an initial :ctype:`PyPixelArray` this
+  will be 0.
+
+.. cmember:: Uint32 PyPixelArray.xlen
+
+  The X segment length in pixels. For an initial :ctype:`PixelArray` this will
+  be the width of the :ctype:`PySDLSurface`.
+
+.. cmember:: Uint32 PyPixelArray.ylen
+
+  The Y segment length in pixels. For an initial :ctype:`PixelArray` this will
+  be the height of the :ctype:`PySDLSurface`.
+
+.. cmember:: Sint32 PyPixelArray.xstep
+
+  The step width in the X direction to reach the next accessible pixel. For an
+  initial :ctype:`PixelArray` this will be 1.
+  
+.. cmember:: Sint32 PyPixelArray.xstep
+
+  The step width in the Y direction to reach the next accessible row. For an
+  initial :ctype:`PixelArray` this will be 1.
+
+.. cmember:: Uint32 PyPixelArray.padding
+
+  The overall padding in X direction to reach the next row. As the pixel buffer
+  of the :ctype:`PySDLSurface` is a 1D array, the :cmember:`padding` denotes
+  the overall length in bytes to reach the next row of pixels. This is usually
+  the same as the pitch of the :ctype:`PySDLSurface`.
+
+Functions
+^^^^^^^^^^
+.. cfunction:: int PyPixelArray_Check (PyObject *obj)
+
+  Returns true, if the argument is a :ctype:`PyPixelArray` or a subclass of
+  :ctype:`PyPixelArray`.
+
+.. cfunction:: PyObject* PyPixelArray_New (PyObject *obj)
+
+  Creates a new :ctype:`PyPixelArray` object from the passed
+  :ctype:`PySDLSurface`. On failure, this returns NULL.

File doc/capi/sdlgfx.rst

+=========================
+pygame2.sdlgfx.base C API
+=========================
+
+The :mod:`pygame2.sdlgfx.base` C API contains objects for managing
+constant frame rates and update steps for SDL based screen surfaces.
+
+Import
+------
+Include headers::
+
+  pygame2/pgsdlgfx.h
+
+.. cfunction:: int import_pygame2_sdlgfx_base (void)
+
+  Imports the :mod:`pygame2.sdlgfx.base` module. This returns 0 on
+  success and -1 on failure.
+
+PyFPSManager
+------------
+.. ctype:: PyFPSManager
+.. ctype:: PyFPSManager_Type
+
+The PyFPSManager object features a high resolution timer support for
+accurate and fixed frame rate support using SDL.
+
+Members
+^^^^^^^
+.. cmember:: FPSmanager* PyFPSManager.fps
+
+  The FPSmanager pointer to access the underlying fps management object.
+
+Functions
+^^^^^^^^^^
+.. cfunction:: int PyFPSManager_Check (PyObject *obj)
+
+  Returns true, if the argument is a :ctype:`PyFPSManager` or a subclass of
+  :ctype:`PyFPSManager`.
+
+.. cfunction:: PyObject* PyFPSManager_New (void)
+
+  Creates a new :ctype:`PyFPSManager` object. On failure, this returns
+  NULL.
+
+.. cfunction:: FPSmanager* PyFPSManager_AsFPSmanager (PyObject *obj)
+
+  Macro for accessing the *fps* member of the :ctype:`PyFPSManager`. This
+  does not perform any type or argument checks.

File doc/capi/sdljoystick.rst

+==========================
+pygame2.sdl.joystick C API
+==========================
+
+The :mod:`pygame2.sdl.joystick` C API contains objects and functions for
+accessing the physical joystick input devices of the computer.
+
+Import
+------
+Include headers::
+
+  pygame2/pgsdl.h
+
+.. cfunction:: int import_pygame2_sdl_joystick (void)
+
+  Imports the :mod:`pygame2.sdl.joystick` module. This returns 0 on success
+  and -1 on failure.
+
+Macros
+------
+.. cfunction:: ASSERT_JOYSTICK_INIT (retval)
+
+  Checks, whether the joystick subsystem was properly initialised. If
+  not, this will set a :exc:`PyExc_PyGameError` and return *retval*.
+
+.. cfunction:: ASSERT_JOYSTICK_OPEN (obj, retval)
+
+  Checks, whether the passed :ctype:`PyJoystick` is open for access. If
+  not, this will set a :exc:`PyExc_PyGameError` and return *retval*.
+
+PyJoystick
+----------
+.. ctype:: PyJoystick
+.. ctype:: PyJoystick_Type
+
+The PyJoystick object is used for gaining access to and retrieving information
+from joystick input devices using SDL.
+
+Members
+^^^^^^^
+.. cmember:: Uint8 PyJoystick.index
+
+  The joystick device index as reported by the SDL library.
+
+.. cmember:: SDL_Joystick* PyJoystick.joystick
+
+  The SDL_Joystick pointer to access the joystick device.
+
+Functions
+^^^^^^^^^^
+.. cfunction:: int PyJoystick_Check (PyObject *obj)
+
+  Returns true, if the argument is a :ctype:`PyJoystick` or a subclass of
+  :ctype:`PyJoystick`.
+
+.. cfunction:: PyObject* PyJoystick_New (int index)
+
+  Creates a new :ctype:`PyJoystick` object from the passed joystick device
+  index. On failure, this returns NULL.
+
+.. cfunction:: SDL_Joystick* PyJoystick_AsJoystick (PyObject *obj)
+
+  Macro for accessing the *joystick* member of the :ctype:`PyJoystick`. This
+  does not perform any type or argument checks.

File doc/capi/sdlmouse.rst

+=======================
+pygame2.sdl.mouse C API
+=======================
+
+The :mod:`pygame2.sdl.mouse` C API contains objects and functions for
+accessing and manipulating the mouse input device and cursor design.
+
+Import
+------
+Include headers::
+
+  pygame2/pgsdl.h
+
+.. cfunction:: int import_pygame2_sdl_mouse (void)
+
+  Imports the :mod:`pygame2.sdl.mouse` module. This returns 0 on success
+  and -1 on failure.
+
+PyCursor
+--------
+.. ctype:: PyCursor
+.. ctype:: PyCursor_Type
+
+The PyCursor object is used manipulating the design of the visible mouse cursor.
+
+Members
+^^^^^^^
+.. cmember:: SDL_Cursor* PyCursor.cursor
+
+  The SDL_Cursor pointer to access the mouse cursor design.
+
+Functions
+^^^^^^^^^^
+.. cfunction:: int PyCursor_Check (PyObject *obj)
+
+  Returns true, if the argument is a :ctype:`PyCursor` or a subclass of
+  :ctype:`PyCursor`.
+
+.. cfunction:: SDL_Cursor* PyCursor_AsCursor (PyObject *obj)
+
+  Macro for accessing the *cursor* member of the :ctype:`PyCursor`. This does
+  not perform any type or argument checks.

File doc/capi/sdlrwops.rst

+=======================
+pygame2.sdl.rwops C API
+=======================
+
+The :mod:`pygame2.sdl.rwops` C API contains objects for
+accessing :ctype:`SDL_RWops` from Python objects.
+
+Import
+------
+Include headers::
+
+  pygame2/pgsdl.h
+
+.. cfunction:: int import_pygame2_sdl_rwops (void)
+
+  Imports the :mod:`pygame2.sdl.rwops` module. This returns 0 on success
+  and -1 on failure.
+
+Functions
+---------
+.. cfunction:: SDL_RWops* RWopsFromPython (PyObject *obj)
+
+  Creates a :ctype:`SDL_RWops` object from the passed Python object.
+  *obj* must be some file-like or buffer-like object supporting the binary read,
+  write, seek, tell and close methods to be fully usable as :ctype:`SDL_RWops`.
+  On failure, this returns NULL.
+
+.. cfunction:: int RWopsCheckPython (SDL_RWops *rw)
+
+  Checks, whether the passed :ctype:`SDL_RWops` was created from a Python
+  object. This returns 1 for a Python object, 0 if it is not a Python object and
+  -1 on failure.
+
+.. cfunction:: SDL_RWops* RWopsFromPythonThreaded (PyObject *obj)
+  
+  Creates a :ctype:`SDL_RWops` object with threading support from the passed
+  Python object. *obj* must be some file-like or buffer-like object supporting
+  the binary read, write, seek, tell and close methods to be fully usable as
+  :ctype:`SDL_RWops`. On failure, this returns NULL.
+
+.. cfunction:: int RWopsCheckPythonThreaded (SDL_RWops *rw)
+
+  Checks, whether the passed :ctype:`SDL_RWops` was created from a Python
+  object. This returns 1 for a Python object, 0 if it is not a Python object and
+  -1 on failure.

File doc/capi/sdlttf.rst

+=========================
+pygame2.sdlttf.base C API
+=========================
+
+The :mod:`pygame2.sdlttf.base` C API contains objects and functions for
+accessing TrueType font rendering on SDL surfaces.
+
+Import
+------
+Include headers::
+
+  pygame2/pgsdlttf.h
+
+.. cfunction:: int import_pygame2_sdlttf_base (void)
+
+  Imports the :mod:`pygame2.sdlttf.base` module. This returns 0 on
+  success and -1 on failure.
+
+Macros
+------
+.. cfunction:: ASSERT_TTF_INIT (retval)
+
+  Checks, whether the ttf subsystem was properly initialised. If
+  not, this will set a :exc:`PyExc_PyGameError` and return *retval*.
+
+
+PyFont
+------
+.. ctype:: PyFont
+.. ctype:: PyFont_Type
+
+The PyFont object is used for rendering text to a :ctype:`PySDLSurface`.
+
+Members
+^^^^^^^
+.. cmember:: TTF_Font* PyFont.font
+
+  The TTF_Font pointer to access the underlying font.
+
+Functions
+^^^^^^^^^^
+.. cfunction:: int PyFont_Check (PyObject *obj)
+
+  Returns true, if the argument is a :ctype:`PyFont` or a subclass of
+  :ctype:`PyFont`.
+
+.. cfunction:: PyObject* PyFont_New (char *filename, int ptsize)
+
+  Creates a new :ctype:`PyFont` object from the passed TrueType font
+  file. *ptsize* specifies the font size (height) in points. On failure,
+  this returns NULL.
+
+.. cfunction:: TTF_Font* PyFont_AsFont (PyObject *obj)
+
+  Macro for accessing the *font* member of the :ctype:`PyFont`. This
+  does not perform any type or argument checks.

File doc/capi/sdlvideo.rst

+=======================
+pygame2.sdl.video C API
+=======================
+
+The :mod:`pygame2.sdl.video` C API contains fundamental objects and functions
+for accessing and manipulating the screen display, image surface objects and
+overlay graphics.
+
+Import
+------
+Include headers::
+
+  pygame2/pgsdl.h
+
+.. cfunction:: int import_pygame2_sdl_video (void)
+
+  Imports the :mod:`pygame2.sdl.video` module. This returns 0 on success
+  and -1 on failure.
+
+Basic Types
+-----------
+.. ctype:: SDLSurfaceLock
+
+  Internally used lock tracking object. It is used in conjunction with
+  the :cfunc:`PySDLSurface_AcquireLockObj` function to keep track of the 
+  external locking objects for a :ctype:`PySDLSurface`.
+  
+  .. cmember:: PyObject* SDLSurfaceLock.surface
+  
+  The :ctype:`PySDLSurface` object that is locked.
+  
+  .. cmember:: PyObject* SDLSurfaceLock.lockobj
+  
+  The :ctype:`PyObject` that causes the lock on the :ctype:`PySDLSurface`.
+
+Macros
+------
+.. cfunction:: ASSERT_VIDEO_INIT (retval)
+
+  Checks, whether the video subsystem was properly initialised. If not,
+  this will set a :exc:`PyExc_PyGameError` and return *retval*.
+
+.. cfunction:: ASSERT_VIDEO_SURFACE_SET (retval)
+
+  Checks, whether a display surface was created already using
+  :func:`pygame2.sdl.video.set_mode`. If not, this will set a
+  :exc:`PyExc_PyGameError` and return *retval*.
+
+Functions
+---------
+.. cfunction:: int ColorFromObj (PyObject *obj, SDL_PixelFormat *format, Uint32 *val)
+
+  Converts the passed object to a 32-bit integer color value and stores the
+  result in *val*. This returns 1 on success and 0 on failure.
+
+PyPixelFormat
+-------------
+.. ctype:: PyPixelFormat
+.. ctype:: PyPixelFormat_Type
+
+The :ctype:`PyPixelFormat` object is a wrapper around the
+:ctype:`SDL_PixelFormat` type, which contains format information about surfaces,
+such as the bit depth, color mask, etc.
+
+Members
+^^^^^^^
+.. cmember:: SDL_PixelFormat* PyPixelFormat.format
+  
+  The SDL_PixelFormat pointer to access the pixel format information.
+
+.. cmember:: int PyPixelFormat.readonly
+
+  A read-only flag that indicates whether the informat