Source

pygame / doc / index.txt

Full commit
aholkner d9b4216 

aholkner 508d3e5 
aholkner d9b4216 



aholkner 508d3e5 



aholkner d9b4216 



aholkner 508d3e5 
aholkner d9b4216 






aholkner 508d3e5 
aholkner d9b4216 






aholkner 508d3e5 
aholkner 781e6c2 





























aholkner 508d3e5 


aholkner d1cbb8c 

aholkner 508d3e5 
aholkner d1cbb8c 




































aholkner d9b4216 

aholkner d1cbb8c 

aholkner 508d3e5 




aholkner d1cbb8c 
aholkner 90a137d 




aholkner d1cbb8c 

aholkner 90a137d 

aholkner d1cbb8c 
aholkner 90a137d 



aholkner d1cbb8c 
aholkner 90a137d 

aholkner d1cbb8c 
aholkner 90a137d 



aholkner d1cbb8c 
aholkner 90a137d 

aholkner d1cbb8c 
aholkner 90a137d 







aholkner 508d3e5 





aholkner d9b4216 
aholkner d1cbb8c 
Pygame-ctypes
=============

Pygame-ctypes is a reimplementation of Pygame_ using ctypes_.  Internally,
it uses SDL-ctypes, a wrapper around SDL_ using ctypes.  Both Pygame-ctypes
and SDL-ctypes are maintained by `Alex Holkner`_ and supported by
`Google Summer of Code 2006`_.

What's it for?
--------------

Pygame is a Python package which provides a simplified interface to
the graphics, audio and input functionalities of SDL.  Until now
Pygame was written as a C Python extension.  This reimplementation
is written purely in Python, giving benefits such as:

* Direct access to all SDL functions and structures, including those
  not provided by Pygame.
* Development and extension of Pygame is greatly simplified.
* Other implementations of Python, such as PyPy, Jython and IronPython
  may in future be able to make use of Pygame-ctypes (support for ctypes
  in each of these implementation is currently under development
  or experimental).

As far as possible Pygame-ctypes has been made API compatible with
Pygame.  However, several new features have already been introduced
that are not available in standard Pygame:

* Support for NumPy and numarray in addition to Pygame's Numeric routines.
* Closer integration with the `Python Imaging Library`_ (PIL) allowing
  more image formats to be loaded and saved.

Requirements
------------

* Python 2.3 or later.
* Requires `ctypes 1.0.0 <http://starship.python.net/crew/theller/ctypes/>`_.
  This is included in Python 2.5, or can be installed as an extension
  for older versions.
* `SDL 1.2.1 <http://www.libsdl.org>`_ or later.

The following libraries are optional but are required for some of Pygame's
functionality:

* `Python Imaging Library (PIL) <http://www.pythonware.com/library/pil>`_
  is required for some ``pygame.transform`` functions, for saving and
  loading images other than BMP, and speeds up other image functions.
* `SDL_image <http://www.libsdl.org/projects/SDL_image>`_ can be used
  in place of PIL for loading some image types.
* `SDL_ttf <http://www.libsdl.org/projects/SDL_ttf>`_ is required for all
  ``pygame.font`` functions.
* `SDL_mixer <http://www.libsdl.org/projects/SDL_ttf>`_ is required for
  all ``pygame.mixer`` functions.

Any of the following array modules can be used for the ``pygame.surfarray``
and ``pygame.sndarray`` functions, and for speeding up some image
operations:

* `NumPy <http://numpy.scipy.org/>`_ (recommended)
* `Numeric <http://numpy.scipy.org/>`_ 
* `numarray <http://www.stsci.edu/resources/software_hardware/numarray>`_

Download
--------

Documentation
^^^^^^^^^^^^^

Documentation is included in the source distribution under the ``doc``
directory.  It is also browseable online:

* `Pygame-ctypes manual <pygame-manual/index.html>`_
* `Pygame-ctypes API reference <pygame-api/index.html>`_
* `SDL-ctypes manual <sdl-manual/index.html>`_
* `SDL-ctypes API reference <sdl-api/index.html>`_

Runtime eggs
^^^^^^^^^^^^

Download and install `setuptools`_, then add the following to your source
to use the eggs::
    
    from pkg_resources import require
    require('Pygame-ctypes>=0.09')

There's no need to install these eggs, just make sure they are either in
the working directory or a directory that's in ``sys.path``.

+------------+----------------------------------------------------------------+
|Python 2.3  || `Pygame_ctypes-0.09-py2.3.egg <Pygame_ctypes-0.09-py2.3.egg>`_|
|            || `SDL_ctypes-0.09-py2.3.egg <SDL_ctypes-0.09-py2.3.egg>`_      |
+------------+----------------------------------------------------------------+
|Python 2.4  || `Pygame_ctypes-0.09-py2.4.egg <Pygame_ctypes-0.09-py2.4.egg>`_|
|            || `SDL_ctypes-0.09-py2.4.egg <SDL_ctypes-0.09-py2.4.egg>`_      |
+------------+----------------------------------------------------------------+
|Python 2.5  || `Pygame_ctypes-0.09-py2.5.egg <Pygame_ctypes-0.09-py2.5.egg>`_|
|            || `SDL_ctypes-0.09-py2.5.egg <SDL_ctypes-0.09-py2.5.egg>`_      |
+------------+----------------------------------------------------------------+

Source release
^^^^^^^^^^^^^^

The latest source release for both Pygame-ctypes and SDL-ctypes is:

* `pygame-ctypes-0.09.tar.gz <pygame-ctypes-0.09.tar.gz>`_, includes the
  latest snapshot of SDL-ctypes.

SVN Repository
^^^^^^^^^^^^^^

You can also access the SVN repository directly::

    svn co svn://pygame.org/svn/pygame/branches/ctypes-soc


Installation
------------

You should generally **not** install Pygame-ctypes, as it will replace the
standard Pygame package.  Because Pygame-ctypes doesn't need to compile
anything, it can run straight from its own directory (or from an egg, see
above).  

For example, on Linux, Mac OS X or Cygwin, let's say you've downloaded and
extracted the source release to ``/home/joe/pygame-ctypes-0.09``.  Now you can
run your existing Pygame games by including this path near the start of your
``PYTHONPATH``::

    # Using bash:
    PYTHONPATH=/home/joe/pygame-ctypes-0.09:$PYTHONPATH; export PYTHONPATH

    # Using csh:
    setenv PYTHONPATH /home/joe/pygame-ctypes-0.09:$PYTHONPATH

    python mygame.py

On Windows, assuming you downloaded and extracted the source release to
``c:\pygame-ctypes-0.09``::

    # At the command prompt:
    set PYTHONPATH=c:\pygame-ctypes-0.09

    python mygame.py

Remember to set the ``PYTHONPATH`` environment variable each time you
open a terminal or command prompt, or add it to your startup file.

**Mac OS X users**: you should use ``pythonw``, not ``python``.


.. _SDL: http://www.libsdl.org
.. _ctypes: http://starship.python.net/crew/theller/ctypes
.. _Alex Holkner: mailto:aholkner@cs.rmit.edu.au
.. _Google Summer of Code 2006: http://code.google.com/soc
.. _Pygame: http://www.pygame.org
.. _Python Imaging Library: http://www.pythonware.com/library/pil
.. _setuptools: http://peak.telecommunity.com/DevCenter/setuptools