chickadee » sdl

Outdated egg!

This is an egg for CHICKEN 4, the unsupported old release. You're almost certainly looking for the CHICKEN 5 version of this egg, if it exists.

If it does not exist, there may be equivalent functionality provided by another egg; have a look at the egg index. Otherwise, please consider porting this egg to the current version of CHICKEN.

sdl

Description

This is a Chicken extension for basic SDL support.

If you are writing new software, consider using sdl-base, sdl-ttf and sdl-mixer eggs instead. They allow to link your program only with the libraries you need.

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:

  (define s (sdl-set-video-mode 640 480 0 (+ SDL_HWSURFACE
					     SDL_HWPALETTE
					     SDL_DOUBLEBUF)))

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.

Garbage Collection

Currently, some datastructures (SDL_Surface and TTF_Font) require manual deallocation. Use (sdl-free-surface) and (ttf-close-font), respectively. Future versions of this library may implement automatic reclamation of unused SDL_Surface and/or TTF_Font structures.

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 (and, probably, Windows)

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. See the I get "Undefined reference to 'SDL_main'" ... in the Windows FAQ on SDL Wiki for more information.) You must call SDL_Init directly from your main program - if your main program is written in Scheme, you need to say something like

  (declare (foreign-declare "#include <SDL.h>\n"))
  (foreign-code "SDL_Init(SDL_INIT_EVERYTHING);")

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:

http://www.libsdl.org/intro/toc.html

External dependencies

This egg depends on the sdl library and headers being present on your system. Please see the list below on instructions on how to resolve the dependencies on your system.

Ubuntu 12.04 (Precise)

  sudo apt-get install libsdl-ttf2.0-dev libsdl1.2-dev libsdl-image1.2-dev libsdl-gfx1.2-dev libsdl-net1.2-dev

Warning

 THIS IS ALPHA CODE.
 Only some of the features have been tested.
 The interfaces are likely to change in the future.
 Not all of SDL is supported.
 BE WARNED!
 See especially the lack of warranty in the LGPL!

Changelog

License

 This library is licensed under the LGPL, the same license as SDL
 itself. See the file "COPYING" in the provided archive.