Read Me

This is CFFI-SDL.

= Scope =

CFFI-SDL provides a CFFI-binding between Lisp and the Simple Directmedia Layer
(SDL). It is similar in scope to CL-SDL, but differs in two main ways:

* CFFI-SDL makes use of CFFI for defining the native bindings, rather than UFFI.
  Hence also its (otherwise uninspiring) name.
* CFFI-SDL leverages SWIG to generate most of this binding. That is, the actual
  CFFI code is generated by SWIG from the original SDL headers. This means that
  co-evolution with SDL does not require a lot of manual labour.

Not all of SDL is covered in the binding. Basically CFFI-SDL gives you enough
to get started doing OpenGL applications (which was my motivation for doing the
work). It has GL, GLU, and SDL basics for creating a rendering surface and
setting up the event loop.

= License =

CFFI-SDL is covered by a BSD license. See LICENSE.txt for details.

= Disclaimer =

The original code for CFFI-SDL was developed on a Mac OS X 10.5 system, making
use of SBCL as Lisp environment. It has not been tested with other Lisps or on
other operating systems. As such it may or may not work with other Lisps or
other OS's; but my guess is that you're going to need to do some work to get it
going. If you do get it going on another platform, however, contact me and I'll
try to integrate it so that others can enjoy it as well.

Also note that the original code was developed by someone who is not very well
versed in Lisp. By which I mean to say that I'm not a seasoned Lisp hacker, and
that this code may appear ugly to you if you do know more about Lisp than me.

= User documentation =

None yet. Please check the NeHe lessons (subfolder "nehe") for inspiration.

A note on naming though. Basically the function and constant names are generated
from the original names. The basic algorithm is to lose the initial "SDL_",
"GL_", "gl", "GLU_" or "glu", and then go from camelcase to dashed identifiers.
E.g. "SDL_SetVideoMode" becomes "set-video-mode".

= Developer notes =

The idea behind CFFI-SDL is to set up an SDL binding with minimal effort by
leveraging tools like SWIG. What we do is take the SDL header files and pass
them through SWIG. This then gives us CFFI code. We string this together, adding
package definitions and some support code, and then we have our final product.

The main advantage is that in this way CFFI-SDL can move along with SDL quickly
and easily. If a new version is released we can (in theory) just rerun the SWIG
tool on the new headers and enjoy the new features. Minimal work, maximum
flexibility.

This ideal is hampered, however, by some limitations in SWIG (or in my
understanding of how it works). SWIG ignores the contents of header files which
get included in other header files. This has the result that it doesn't know
about some typedefs and therefore mistranslates them to :pointer. In order to
remedy that I currently copy the headers, then hack the copied headers by adding
the relevant definitions. This solves the problem, but also means that on any
update of SDL there is some preparatory work to be done before you can do the
regeneration.

Also, due to SDL being licensed under the LGPLv2, I prefer not to add the modded
headers to the distribution. I do, however, include the final generated lisp
code, which should be enough if you just want to do some SDL programming.