Index of /~tonyg/Darcs/chicken-sdl/_darcs/current

Name	Last modified	Size

Parent Directory		-
COPYING	2005-10-30 09:21	26K
Makefile	2005-10-30 09:21	911
heap.scm	2005-10-30 09:21	1.6K
sdl.setup	2005-10-30 09:21	100
test-heap.scm	2005-10-30 09:21	305
test-net.scm	2005-10-30 09:21	497
test-sdl-body.scm	2005-10-30 09:21	2.1K
test-sdl.scm	2005-10-30 09:21	179
timer.scm	2005-10-30 09:21	903
unknown2-scale8.jpg	2005-10-30 09:21	5.4K
sdl-csi.scm	2005-11-17 12:29	504
README.html	2005-11-17 12:42	6.2K
sdl.scm	2005-12-15 19:37	32K

Eggs Unlimited - sdl

back

sdl

Description:

This is a Chicken extension for basic SDL support.

Author:

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

Version:

v0.4.51117.0

Download:

sdl.egg

Requirements:

You will need:

SDL installed on your system, with 'sdl-config' on your path
SDL_ttf installed on your system
SDL_image installed on your system
SDL_gfx installed on your system
SDL_net installed on your system

Usage:

  (require-extension sdl)

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

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

Warning!

NOTE:
	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!

License:

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

back