source: project/wiki/eggref/4/sdl @ 26075

Last change on this file since 26075 was 26075, checked in by Christian Kellermann, 10 years ago

updated sdl version history

File size: 5.4 KB
Line 
1[[tags: egg]]
2
3== sdl
4
5[[toc:]]
6
7=== Description
8
9This is a Chicken extension for basic SDL support.
10
11=== Author
12
13Tony Garnock-Jones <tonyg@kcbbs.gen.nz>
14
15=== Documentation
16
17==== Naming conventions
18
19I've tried to follow guile-sdl here. From the guile-sdl infopages:
20
21  As with standard guile naming conventions, all names are converted to
22  lower-case, and underscores are replaced with hyphens.  Functions that
23  modify one or more arguments have an exclamation point (`!') appended,
24  and functions which ask a question and return a boolean value have a
25  question mark (`?') appended.
26
27Regarding flags, enums and constants: I differ from guile-sdl here -
28where guile-sdl exposes these as symbols, with functions for
29converting to and from numeric values, this library exposes a number
30of variables bound to numbers. To combine flags, use {{(+)}}. For
31instance:
32
33<enscript highlight=scheme>
34  (define s (sdl-set-video-mode 640 480 0 (+ SDL_HWSURFACE
35                                             SDL_HWPALETTE
36                                             SDL_DOUBLEBUF)))
37</enscript>
38
39Note also that I differ from guile-sdl in the case of flag, enum and
40constant definitions. Since Chicken is now case-sensitive by default,
41I've made this extension retain the case of the C preprocessor
42definitions.
43
44The reason I am recommending {{(+)}} over {{(bitwise-ior)}} here is
45that some of the flags do not fit in an immediate small integer, and
46must be represented as inexact numbers. Unfortunately, {{bitwise-ior}}
47only works properly when applied to immediate small integers, so there
48is a tradeoff to be made: use {{(bitwise-ior)}} where you are ''sure''
49all the flags will fit in immediate integers, and use {{(+)}}
50otherwise, bearing in mind the fact that {{(bitwise-ior)}} gives an
51answer much more in the spirit of a bit set definition: if a flag is
52already set, {{(bitwise-ior)}} will not set it twice, where {{(+)}}
53will happily screw up the result completely.
54
55==== Garbage Collection
56
57Currently, some datastructures ({{SDL_Surface}} and {{TTF_Font}})
58require manual deallocation. Use {{(sdl-free-surface)}} and
59{{(ttf-close-font)}}, respectively. Future versions of this library
60may implement automatic reclamation of unused {{SDL_Surface}} and/or
61{{TTF_Font}} structures.
62
63==== Timers
64
65It is problematic supporting {{SDL_AddTimer}} and {{SDL_RemoveTimer}}
66from chicken, since they a) are implemented using {{setitimer}}(2) and
67b) involve callbacks from C to Scheme. Each would be fine on its own,
68but taken together they interfere with the main Scheme thread.
69
70As it happens, the {{SDL_WaitEvent}} function is implemented in terms
71of polling (!) for events, with a short delay if none present
72themselves - the usual pragmatic tradeoff for event-based systems on
73Unix-like machines - and so we will be doing no worse if we do a
74similar thing ourselves. Hence, I've written a Scheme-based timer
75library which integrates with SDL's event loop, calling
76{{SDL_Delay(10)}} when there's no work, just like {{SDL_WaitEvent}}.
77
78==== SDL_Init / sdl-init on MacOS X
79
80{{sdl-init}} does not work on MacOS X when called from a
81dynamically-loaded extension. Something internal to Quartz seems to
82get confused. (Chances are it's the redefinition of {{main()}} in
83{{SDL_main.h}}, which implies there will be problems on Windows as
84well.) You must call {{SDL_Init}} ''directly'' from your main program
85- if your main program is written in Scheme, you need to say something
86like
87
88<enscript highlight=scheme>
89  (declare (foreign-declare "#include <SDL.h>\n"))
90  (foreign-code "SDL_Init(SDL_INIT_EVERYTHING);")
91</enscript>
92
93and then compile that part of the code, linking it against {{libSDL}}
94directly.
95
96For convenience, this extension includes a program called {{sdl-csi}}
97which calls {{SDL_Init}} and then enters a version of the Chicken
98read-eval-print-loop, which can be used for interpreted/interactive
99use of the SDL bindings. The {{sdl-csi}} program is installed into the
100chicken program directory by {{chicken-setup}}.
101
102Note that all this special handling of {{sdl-init}} is only required
103on MacOS X - other platforms (I've tried Debian linux on x86) have no
104difficulty with invoking {{sdl-init}} as a normal library procedure.
105
106==== For more information
107
108Consult the [[http://www.libsdl.org/|libsdl C library]]
109documentation for the precise usage of each function, structure, and
110variable. You can find the C library documentation here:
111
112[[http://www.libsdl.org/intro/toc.html]]
113
114
115=== Warning
116
117  THIS IS ALPHA CODE.
118
119  Only some of the features have been tested.
120  The interfaces are likely to change in the future.
121  Not all of SDL is supported.
122
123  BE WARNED!
124
125  See especially the lack of warranty in the LGPL!
126
127=== Changelog
128* 0.5.5: more FFI fixes, keyboard codes have been added, .setup script fixes (Christian Kellermann)
129* 0.5.4: fixed wrong pointer type in sdl-color? procedure (Christian Kellermann)
130* 0.5.3: fixed setup script for OpenBSD (Christian Kellermann)
131* 0.5.2: ???
132* 0.5.1: fixed use of removed {{pointer}} type
133* v0.4.51117.6 Added {{sdl-gl-swap-buffers}}, {{sdl-gl-set-attribute}} and {{sdl-gl-get-attribute}}, suggested by Koen Weddepohl
134* v0.4.51117.5 Another attempt at mingw porting
135* v0.4.51117.4 Modified sdl.scm to include proper headers for windows [reported by Jong-Hyouk Yun]
136* v0.4.51117.3 Added a few missing functions
137* v0.4.51117.2 A few missing functions added for joystick support
138* v0.4.51117.1 Joystick-support by Achernar Alpha Eridani
139* v0.4.51117.0
140
141=== License
142
143  This library is licensed under the LGPL, the same license as SDL
144  itself. See the file "COPYING" in the provided archive.
Note: See TracBrowser for help on using the repository browser.