SDL_gfx - SDL graphics drawing primitives and other support functions ============================================================================= Email aschiffler@appwares.ca to contact the author or better check author's homepage at http://www.ferzkopp.net for the most up-to-date contact information. This library is licenced under the LGPL, see the file LICENSE for details. Intro ----- The SDL_gfx library evolved out of the SDL_gfxPrimitives code which provided basic drawing routines such as lines, circles or polygons for SDL Surfaces and adding a couple other useful functions for zooming images for example and doing basic image processing on byte arrays. The current components of the SDL_gfx library are: - Graphic Primitives (SDL_gfxPrimitves.h) - Rotozoomer (SDL_rotozoom.h) - Framerate control (SDL_framerate.h) - MMX image filters (SDL_imageFilter.h) See ./Docs directory for a longer HTML version of this document. Supported Platforms ------------------- The library compiles and is tested for a Linux target (gcc compiler) and a Win32 target (VisualC6/7, xmingw32 cross-compiler). MacOS X target is reported to work (Project Builder). When using the cross-compiler (available on the author's homepage), the build process generates .DLLs. You can use the command line 'LIB.EXE' tool to generate VC6 compatible .LIB files for linking purposes. Other platforms might work but have not been tested by the author. Notes on Graphics Primitives ---------------------------- Care has been taken so that all routines are fully alpha-aware and can blend any primitive onto the target surface if ALPHA<255. Surface depths supported are 1,2,3 and 4 bytes per pixel. Surface locking is implemented in each routine and the library should work well with hardware accelerated surfaces. Currently, The following Anti-Aliased drawing primitives are available: - AA-line - AA-polygon - AA-circle - AA-ellipse [[[ Interface ]]] See SDL_gfxPrimitives.h for all the drawing functions. Notes on Rotozoomer ------------------- The rotozoom code is not ASSEMBLY quality - but it should be fast enough even for some realtime effects if the CPU is good or bitmaps small. With interpolation the routines are typically used for pre-rendering stuff in higher quality (i.e. smoothing) - that's also a reason why the API differs from SDL_BlitRect() and creates a new target surface each time rotozoom is called. The final rendering speed is dependent on the target surface size as it is beeing xy-scanned when rendering the new surface. Note also that the smoothing toggle is dependent on the input surface bit depth. 8bit surfaces will never be smoothed - only 32bit surfaces will. Note that surfaces of other bit depth then 8 and 32 will be converted on the fly to a 32bit surface using a blit into a temporary surface. This impacts performance somewhat. [[[ Interface ]]] SDL_Surface * rotozoomSurface (SDL_Surface *src, double angle, double zoom, int smooth); Rotates and zoomes a 32bit or 8bit 'src' surface to newly created 'dst' surface. 'angle' is the rotation in degrees. 'zoom' a scaling factor. If 'smooth' is 1 then the destination 32bit surface is anti-aliased. If the surface is not 8bit or 32bit RGBA/ABGR it will be converted into a 32bit RGBA format on the fly. SDL_Surface * zoomSurface (SDL_Surface *src, double zoomx, double zoomy, int smooth); Zoomes a 32bit or 8bit 'src' surface to newly created 'dst' surface. 'zoomx' and 'zoomy' are scaling factors for width and height. If 'smooth' is 1 then the destination 32bit surface is anti-aliased. If the surface is not 8bit or 32bit RGBA/ABGR it will be converted into a 32bit RGBA format on the fly. Smoothing (interpolation) flags work only on 32bit surfaces: #define SMOOTHING_OFF 0 #define SMOOTHING_ON 1 Notes on framerate functions ---------------------------- The framerate functions are used to insert delays into the graphics loop to maintain a constant framerate. The implementation is more sophisticated that the usual SDL_Delay(1000/FPS); call since these functions keep track of the desired game time per frame for a linearly interpolated sequence of future timing points of each frame. This is done to avoid rounding errors from the inherent instability in the delay generation and application. i.e. the 100th frame of a game running at 50Hz will be accurately 2.00sec after the 1st frame (if the machine can keep up with the drawing). [[[ Interface ]]] The functions return 0 or 'value' for sucess and -1 for error. All functions use a pointer to a framerate-manager variable to operate. void SDL_initFramerate(FPSmanager * manager); Initialize the framerate manager, set default framerate of 30Hz and reset delay interpolation. int SDL_setFramerate(FPSmanager * manager, int rate); Set a new framerate for the manager and reset delay interpolation. int SDL_getFramerate(FPSmanager * manager); Get the currently set framerate of the manager. void SDL_framerateDelay(FPSmanager * manager); Generate a delay to accomodate currently set framerate. Call once in the graphics/rendering loop. If the computer cannot keep up with the rate (i.e. drawing too slow), the delay is zero and the delay interpolation is reset. Notes on imageFilter functions ------------------------------ The imagefilter functions are a collection of MMX optimized routines that operate on continuous buffers of bytes - typically greyscale images from framegrabbers and such - performing functions such as image addition and binarization. All functions (almost .. not the the convolution routines) have a C implementation that is automatically used on systems without MMX capabilities. [[[ Interface ]]] See the extensive list of routines in SDL_imageFilters.h for info. Installation and Test --------------------- To compile the library your need the SDL 1.2 installed from source or with the 'devel' RPM package. Run ./autogen.sh (optional) ./configure make make install ldconfig to compile and install the library. The default location for the installation is /usr/local/lib and /usr/local/include. Run the shell script 'nodebug.sh' before make, to patch the makefile for optimized compilation: ./autogen.sh (optional) ./configure ./nodebug.sh make make install ldconfig To create a Windows DLL using VisualC: unzip -a VisualC6.zip vcvars32.bat copy VisualC/makefile nmake or unzip -a VisualC7.zip and open the project file. To create a Windows DLL using the xmingw32 cross-compiler: cross-configure cross-make cross-make install To build without MMX code enabled (i.e. PPC architecture): ./configure --disable-mmx make make install To build on MacOS X with Project Builder, follow these steps: * Update your developer tools to the lastest version (December 2002 as of this revision). * Install the SDL Developers framework for Mac OS X. * Download the latest SDL_gfx source distribution and extract the archive in a convenient location. * Extract the included OSX-PB.tgz archive into the top directory of the SDL_gfx distribution (from step 3). This will create a PB that contains the project files. * The project has targets for the SDL_gfx framework and the four test programs. All can be built using the 'deployment' or 'development' build styles. Test Programs ------------- Change to the ./Test directory and run ./configure make to create several test programs for the libraries functions. This requires the library to be compiled and installed. See the source code .c files for sample code. Thanks ------ Thanks to 'AppWares Development Group' for supporting this project - please visit http://www.appwares.com for more information. Contributors ------------ * Non-alpha line drawing code adapted from routine by Pete Shinners, pete@shinners.org - thanks Pete. * More fixes by Karl Bartel, karlb@gmx.net - thanks Karl. * Much testing and suggestions for fixes from Danny van Bruggen, danny@froukepc.dhs.org - thanks Danny. * Original AA-circle/-ellipse code idea from Stephane Magnenat, nct@wg0.ysagoon.com - thanks Stephane. * Faster blending routines contributed by Anders Lindström, cal@swipnet.se - thanks Anders. * New AA-circle/-ellipse code based on ideas from Anders Lindström - thanks Anders. * VisualC makefile contributed by Danny van Bruggen, danny@froukepc.dhs.org - thanks Danny. * VisualC7 project file contributed by James Turk, jturk@conceptofzero.com - thanks James. * Project Builder package contributed by Thomas Tongue, TTongue@imagiware.com - Thanks Thomas.