sdl

Description

This is a Chicken extension for basic SDL support.

Author

Tony Garnock-Jones <tonyg@kcbbs.gen.nz>

Documentation

Naming conventions

I've tried to follow guile-sdl here. From the guile-sdl infopages:

> As with standard guile naming conventions, all names are converted to > lower-case, and underscores are replaced with hyphens. Functions that > modify one or more arguments have an exclamation point (`!') appended, > and functions which ask a question and return a boolean value have a > question mark (`?') appended.

Regarding flags, enums and constants: I differ from guile-sdl here - where guile-sdl exposes these as symbols, with functions for converting to and from numeric values, this library exposes a number of variables bound to numbers. To combine flags, use (+). For instance:

Note also that I differ from guile-sdl in the case of flag, enum and constant definitions. Since Chicken is now case-sensitive by default, I've made this extension retain the case of the C preprocessor definitions.

The reason I am recommending (+) over (bitwise-ior) here is that some of the flags do not fit in an immediate small integer, and must be represented as inexact numbers. Unfortunately, bitwise-ior only works properly when applied to immediate small integers, so there is a tradeoff to be made: use (bitwise-ior) where you are sure all the flags will fit in immediate integers, and use (+) otherwise, bearing in mind the fact that (bitwise-ior) gives an answer much more in the spirit of a bit set definition: if a flag is already set, (bitwise-ior) will not set it twice, where (+) will happily screw up the result completely.

Timers

It is problematic supporting SDL_AddTimer and SDL_RemoveTimer from chicken, since they a) are implemented using setitimer(2) and b) involve callbacks from C to Scheme. Each would be fine on its own, but taken together they interfere with the main Scheme thread.

As it happens, the SDL_WaitEvent function is implemented in terms of polling (!) for events, with a short delay if none present themselves - the usual pragmatic tradeoff for event-based systems on Unix-like machines - and so we will be doing no worse if we do a similar thing ourselves. Hence, I've written a Scheme-based timer library which integrates with SDL's event loop, calling SDL_Delay(10) when there's no work, just like SDL_WaitEvent.

SDL_Init / sdl-init on MacOS X

sdl-init does not work on MacOS X when called from a dynamically-loaded extension. Something internal to Quartz seems to get confused. (Chances are it's the redefinition of main() in SDL_main.h, which implies there will be problems on Windows as well.) You must call SDL_Initdirectly from your main program - if your main program is written in Scheme, you need to say something like

and then compile that part of the code, linking it against libSDL directly.

For convenience, this extension includes a program called sdl-csi which calls SDL_Init and then enters a version of the Chicken read-eval-print-loop, which can be used for interpreted/interactive use of the SDL bindings. The sdl-csi program is installed into the chicken program directory by chicken-setup.

Note that all this special handling of sdl-init is only required on MacOS X - other platforms (I've tried Debian linux on x86) have no difficulty with invoking sdl-init as a normal library procedure.

For more information

Consult the libsdl C library documentation for the precise usage of each function, structure, and variable. You can find the C library documentation here: