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) <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
--------

The latest source release is:

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

In the future SDL-ctypes may also be released separately from Pygame.
In the meantime you can extract it from the same source download; there
are no dependencies of SDL-ctypes on Pygame-ctypes.

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.  

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.08``.  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.08:$PYTHONPATH; export PYTHONPATH

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

    python mygame.py

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

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

    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``.

Documentation
-------------

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

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

.. _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