1
2SDL_gfx - SDL graphics drawing primitives and other support functions
3=============================================================================
4
5Email aschiffler at ferzkopp.net to contact the author or better check
6author's homepage at http://www.ferzkopp.net for the most up-to-date
7contact information.
8
9This library is licenced under the LGPL, see the file LICENSE for details.
10
11
12Intro
13-----
14
15The SDL_gfx library evolved out of the SDL_gfxPrimitives code which
16provided basic drawing routines such as lines, circles or polygons for
17SDL Surfaces and adding a couple other useful functions for zooming
18images for example and doing basic image processing on byte arrays.
19
20The current components of the SDL_gfx library are:
21- Graphic Primitives (SDL_gfxPrimitves.h)
22- Rotozoomer (SDL_rotozoom.h)
23- Framerate control (SDL_framerate.h)
24- MMX image filters (SDL_imageFilter.h)
25- Custom Blit functions (SDL_gfxBlitFunc.h)
26
27See ./Docs directory for a longer HTML version of this document.
28
29
30Supported Platforms
31-------------------
32
33The library compiles and is tested for a Linux target (gcc compiler) and
34a Win32 target (VisualC6/7, mingw32, xmingw32 cross-compiler). MacOS X
35target is reported to work (10.3+ native and Project Builder).
36QNX is reported to build well (see .diff in "Other Builds").
37
38When using the cross-compiler (available on the author's homepage, slightly
39out of date), the build process generates .DLLs. You can use the command
40line 'LIB.EXE' tool to generate VC6 compatible .LIB files for linking
41purposes.
42
43Other platforms might work but have not been tested by the author.
44Please check the file "INSTALL" as well as the folder "Other Builds".
45
46See section "Installation and Test" below for more build instructions.
47
48
49Notes on Graphics Primitives
50----------------------------
51
52Care has been taken so that all routines are fully alpha-aware and can
53blend any primitive onto the target surface if ALPHA<255. Surface depths
54supported are 1,2,3 and 4 bytes per pixel. Surface locking is implemented
55in each routine and the library should work well with hardware
56accelerated surfaces.
57
58Currently, The following Anti-Aliased drawing primitives are available:
59- AA-line
60- AA-polygon
61- AA-circle
62- AA-ellipse
63
64[[[ Interface ]]]
65
66See SDL_gfxPrimitives.h for all the drawing functions.
67
68
69Notes on Rotozoomer
70-------------------
71
72The rotozoom code is not ASSEMBLY quality - but it should be fast enough
73even for some realtime effects if the CPU is good or bitmaps small.
74With interpolation the routines are typically used for pre-rendering stuff
75in higher quality (i.e. smoothing) - that's also a reason why the API differs
76from SDL_BlitRect() and creates a new target surface each time rotozoom
77is called. The final rendering speed is dependent on the target surface
78size as it is beeing xy-scanned when rendering the new surface.
79
80Note also that the smoothing toggle is dependent on the input surface bit
81depth. 8bit surfaces will never be smoothed - only 32bit surfaces will.
82
83Note that surfaces of other bit depth then 8 and 32 will be converted
84on the fly to a 32bit surface using a blit into a temporary surface. This
85impacts performance somewhat.
86
87
88[[[ Interface ]]]
89
90SDL_Surface * rotozoomSurface (SDL_Surface *src, double angle, double zoom, int smooth);
91
92 Rotates and zoomes a 32bit or 8bit 'src' surface to newly created 'dst' surface.
93 'angle' is the rotation in degrees. 'zoom' a scaling factor. If 'smooth' is 1
94 then the destination 32bit surface is anti-aliased. If the surface is not 8bit
95 or 32bit RGBA/ABGR it will be converted into a 32bit RGBA format on the fly.
96
97
98SDL_Surface * rotozoomSurfaceXY (SDL_Surface *src, double angle, double zoomx, double zoomy, int smooth);
99
100 Rotates and zoomes a 32bit or 8bit 'src' surface to newly created 'dst' surface.
101 'angle' is the rotation in degrees. 'zoomx' and 'zoomy' are scaling factors that
102 can also be negative. In this case the corresponding axis is flipped. If 'smooth'
103 is 1 then the destination 32bit surface is anti-aliased. If the surface is not 8bit
104 or 32bit RGBA/ABGR it will be converted into a 32bit RGBA format on the fly.
105
106 Note: Flipping currently only works with antialiasing turned off.
107
108
109SDL_Surface * zoomSurface (SDL_Surface *src, double zoomx, double zoomy, int smooth);
110
111 Zoomes a 32bit or 8bit 'src' surface to newly created 'dst' surface.
112 'zoomx' and 'zoomy' are scaling factors for width and height. If 'smooth' is 1
113 then the destination 32bit surface is anti-aliased. If the surface is not 8bit
114 or 32bit RGBA/ABGR it will be converted into a 32bit RGBA format on the fly.
115
116
117Smoothing (interpolation) flags work only on 32bit surfaces:
118
119 #define SMOOTHING_OFF 0
120 #define SMOOTHING_ON 1
121
122
123Notes on framerate functions
124----------------------------
125
126The framerate functions are used to insert delays into the graphics loop
127to maintain a constant framerate.
128
129The implementation is more sophisticated that the usual
130 SDL_Delay(1000/FPS);
131call since these functions keep track of the desired game time per frame
132for a linearly interpolated sequence of future timing points of each frame.
133This is done to avoid rounding errors from the inherent instability in the
134delay generation and application.
135
136i.e. the 100th frame of a game running at 50Hz will be accurately
1372.00sec after the 1st frame (if the machine can keep up with the drawing).
138
139
140[[[ Interface ]]]
141
142The functions return 0 or 'value' for sucess and -1 for error. All functions
143use a pointer to a framerate-manager variable to operate.
144
145void SDL_initFramerate(FPSmanager * manager);
146
147 Initialize the framerate manager, set default framerate of 30Hz and
148 reset delay interpolation.
149
150
151int SDL_setFramerate(FPSmanager * manager, int rate);
152
153 Set a new framerate for the manager and reset delay interpolation.
154
155
156int SDL_getFramerate(FPSmanager * manager);
157
158 Get the currently set framerate of the manager.
159
160
161void SDL_framerateDelay(FPSmanager * manager);
162
163 Generate a delay to accomodate currently set framerate. Call once in the
164 graphics/rendering loop. If the computer cannot keep up with the rate (i.e.
165 drawing too slow), the delay is zero and the delay interpolation is reset.
166
167
168Notes on imageFilter functions
169------------------------------
170
171The imagefilter functions are a collection of MMX optimized routines that
172operate on continuous buffers of bytes - typically greyscale images from
173framegrabbers and such - performing functions such as image addition and
174binarization. All functions (almost .. not the the convolution routines)
175have a C implementation that is automatically used on systems without MMX
176capabilities.
177
178
179[[[ Interface ]]]
180
181See the extensive list of routines in SDL_imageFilters.h for info.
182
183
184
185Installation and Test
186---------------------
187
188To compile the library your need the SDL 1.2 installed from source or
189installed with the 'devel' RPM package. For example on Mandrake, run:
190 urpmi libSDL1.2-devel
191
192The run
193 ./autogen.sh (optional)
194 ./configure
195 make
196 make install
197 ldconfig
198
199to compile and install the library. The default location for the
200installation is /usr/local/lib and /usr/local/include. The libary
201path might need to be added to the file
202 /etc/ld.so.conf
203
204Run the shell script 'nodebug.sh' before make, to patch the makefile
205for optimized compilation:
206 ./autogen.sh (optional)
207 ./configure
208 ./nodebug.sh
209 make
210 make install
211 ldconfig
212
213
214Other Builds
215------------
216
217Check the folder "Other Builds" for alternative makefiles.
218
219Windows
220-------
221
222To create a Windows DLL using VisualC:
223 unzip -a VisualC6.zip
224 vcvars32.bat
225 copy VisualC/makefile
226 nmake
227or
228 unzip -a VisualC7.zip
229and open the project file.
230
231To build using mingw32 on Win32, check the makefile contained in mingw.zip
232
233To create a Windows DLL using the xmingw32 cross-compiler:
234 cross-configure
235 cross-make
236 cross-make install
237
238Make sure the -DBUILD_DLL is used (and only then) when creating the DLLs.
239Make sure -DWIN32 is used when compiling the sources (creating or using
240the DLLs.
241
242Cross-Compilation
243-----------------
244
245The following sequence may be required to cross-compile a DLL:
246 rm -f acinclude.m4
247 sed -i -e 's/-version-info/-no-undefined -version-info/' Makefile.am
248 autoreconf --force --install
249
250No-MMX
251------
252
253To build without MMX code enabled (i.e. PPC or for AMD64 architecture
254which is missing pusha/popa):
255 ./configure --disable-mmx
256 make
257 make install
258i.e. to build on MacOSX 10.3+ use:
259 ./configure --disable-mmx && make
260
261
262QNX
263---
264
265To build on QNX6, patch first using:
266 patch -p0 <QNX.diff
267
268
269OSX
270---
271
272To build on MacOS X with Project Builder, follow these steps:
273 * Update your developer tools to the lastest version (December 2002 as
274 of this revision).
275 * Install the SDL Developers framework for Mac OS X.
276 * Download the latest SDL_gfx source distribution and extract the
277 archive in a convenient location.
278 * Extract the included OSX-PB.tgz archive into the
279 top directory of the SDL_gfx distribution (from step 3). This will create a
280 PB that contains the project files.
281 * The project has targets for the SDL_gfx framework and the four test
282 programs. All can be built using the 'deployment' or 'development' build
283 styles.
284
285A newer version for MaxOS X is included in the OSX-PB-XCode.zip archive. The
286updated version uses relative pathnames where appropriate, and pointers to
287the standard installation location of SDL. However, it may require XCode in
288order to be used.
289
290
291Test Programs
292-------------
293
294Change to the ./Test directory and run
295 ./configure
296 make
297to create several test programs for the libraries functions. This requires
298the library to be compiled and installed.
299
300
301See the source code .c files for some sample code and implementation hints.
302
303
304Contributors
305------------
306
307* Fix for filledbox by Ingo van Lil, inguin at gmx.de - thanks Ingo.
308
309* Non-alpha line drawing code adapted from routine
310 by Pete Shinners, pete at shinners.org - thanks Pete.
311
312* More fixes by Karl Bartel, karlb at gmx.net - thanks Karl.
313
314* Much testing and suggestions for fixes from Danny van Bruggen,
315 danny at froukepc.dhs.org - thanks Danny.
316
317* Original AA-circle/-ellipse code idea from Stephane Magnenat,
318 nct at wg0.ysagoon.com - thanks Stephane.
319
320* Faster blending routines contributed by Anders Lindstr�m,
321 cal at swipnet.se - thanks Anders.
322
323* New AA-circle/-ellipse code based on ideas from Anders Lindstr�m -
324 thanks Anders.
325
326* VisualC makefile contributed by Danny van Bruggen,
327 danny at froukepc.dhs.org - thanks Danny.
328
329* VisualC7 project file contributed by James Turk,
330 jturk at conceptofzero.com - thanks James.
331
332* Project Builder package contributed by Thomas Tongue,
333 TTongue at imagiware.com - Thanks Thomas.
334
335* Fix for filledPolygon contributed by Kentaro Fukuchi
336 fukuchi at is.titech.ac.jp - Thanks Kentaro.
337
338* QNX6 patch contributed by Mike Gorchak,
339 mike at malva.ua - Thanks Mike.
340
341* Pie idea contributed by Eike Lange,
342 eike.lange at uni-essen.de - Thanks Eike.
343
344* Dynamic font setup by Todor Prokopov,
345 koprok at dir.bg - Thanks Todor.
346
347* Horizontal/Vertical flipping code by Victor (Haypo)
348 Stinner, victor.stinner at haypocalc.com - Thanks Victor.
349
350* OSX build fixes by Michael Wybrow,
351 mjwybrow at cs.mu.oz.au - Thanks Michael.
352
353* gcc3.4 build fixes by Dries Verachtert,
354 dries at ulyssis.org - Thanks Dries.
355
356* Updated OSX build by Brian Rice,
357 water451 at gmail.com - Thanks Brian.
358
359* aaellipse issues pointed out by Marco Wertz,
360 marco.wertz at gmx.de - Thanks Marco.
361
362* texturedPolygon idea and code by Kees Jongenburger,
363 kees.jongenburger at gmail.com - Thanks Kees.
364
365* Several bugfixes contributed by Sigborn Skjaeret,
366 cisc at broadpark.no - Thanks CISC.
367
368* Syntax error for C++ found by Olivier Boudeville,
369 olivier.boudeville at online.fr - Thanks Olivier.
370
371* hline/vline clipping fixes found by Daniel Roggen,
372 droggen at gmail.com and Mikael Thieme,
373 mikael.thieme at his.se - Thanks Daniel+Mikael.
374
375* rotozoom fix for big-endian machines (i.e. PPC)
376 by Julian Mayer, julianmayer at mac.com - Thanks
377 Julian.
378
379* Cross-compilation notes contributed by Sylvain
380 Beucler, beuc at beuc.net - Thanks Sylvain.
381
382* Fix duplicate pixel renders in circleColor contributed
383 by David Raber, lotharstar at gmail.com - Thanks David.
384
385* New arcColor (and arcRGBA) routine contributed
386 by David Raber, lotharstar at gmail.com - Thanks David.
387
388* Idea for polygonColorMT and texturePolygonMT routines for
389 multithreaded operation contributed by "unknown" -
390 Thanks anyways.
391
392