Source

pygame / doc / index.txt

Full commit
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) 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/products/pil/index.htm
.. _setuptools: http://peak.telecommunity.com/DevCenter/setuptools