pysdl2-cffi
===========

The pysdl2-cffi package is a wrapper for libSDL2 (http://www.libsdl.org/)
and its related libraries SDL_image, SDL_mixer, and SDL_ttf, built
using cffi. This package wraps each function in automatically
generated helper functions by following some simple rules, exposing
them under the ``sdl`` namespace without the ``SDL_`` etc.  prefixes.

The Binding Rules
-----------------

- Functions and constants are exposed under the ``sdl``,
  ``sdl.image``, ``sdl.mixer``, and ``sdl.ttf`` namespaces.
- Functions are renamed by removing the ``SDL_`` prefix and lower casing the
  first letter of the function. ``SDL_CreateWindow`` becomes
  ``sdl.createWindow``, ``IMG_LoadTexture`` becomes ``sdl.image.loadTexture``.
- Constants (or anything that has two capital letters after the prefix) are
  renamed by removing the prefix only.  ``SDL_INIT_VIDEO`` becomes
  ``sdl.INIT_VIDEO``, ``MIX_INIT_MP3`` becomes ``sdl.mixer.INIT_MP3``.
- (The original names are available in the ``lib`` submodule of each of the
  ``_sdl``, ``_sdl_image``, ``_sdl_mixer``, ``_sdl_ttf`` modules)
- Functions with primitive-typed out parameters return a tuple of the return
  value (if any) and the value of each out parameter.

    C::

        uint32_t SDL_GetMouseState(int *, int *);

    pysdl2-cffi::

        buttons, x, y = sdl.getMouseState()

        # It is also possible to pass the correct C type to the function:
        x_pointer = sdl.ffi.new('int *')
        y_pointer = sdl.ffi.new('int *')
        buttons, x, y = sdl.getMouseState(x_pointer, y_pointer)
        x[0] == x and y[0] == y

- Structs are exposed as classes that can automatically allocate non-opaque
  structures. For example, SDL_Rect can be allocated by pysdl2-cffi,
  but SDL_Window can only be allocated by calling ``sdl.createWindow()``.
  Structs are exposed without their prefix in the same way as other
  declarations::

    rect = sdl.Rect()
    rect.x = 4
    rect.y = 3
    rect.w = 42
    rect.h = 64

- Structs can accept any valid ffi initializer as their arguments. This also
  works when a function would otherwise require a struct::

    rect = sdl.Rect((4, 3, 42, 64))
    rect2 = sdl.Rect(dict(x=4, y=3, w=42, h=64))

    intersection = sdl.Rect()   # we need to be able to see the result
    intersects = sdl.intersectRect((4,3,42,64), (40,60,10,10), intersection)

- Any function that takes a particular struct as its first argument is also
  a method on the relevant helper class::

    intersects = rect.intersectRect((40,60,10,10), intersection)

- The binding does not try to hook resource management to garbage collection.
  Users should release textures, windows, and so on using the appropriate SDL
  functions or risk leaking resources.

Error Handling
--------------

Most functions in the ``sdl``, ``sdl.image``, and ``sdl.ttf`` libraries check their return
value for errors. If there was an error then an exception ``sdl.SDLError()`` is
thrown. The exception's ``.message`` property holds SDL's own error message as
reported by ``sdl.getError()``::

    >>> sdl.image.load('/tmp/i_dont_exist.png')
    SDLError: Couldn't open /tmp/i_dont_exist.png

The ``sdl.mixer`` library does not currently convert errors to exceptions.

Bugs
----

- Some functions that are probably useless in Python, like string manipulation
  or logging functions, are wrapped anyway. They may be removed later.