1/*! 2 3 4\mainpage SDL_gfx - SDL-1.2 graphics drawing primitives, rotozoom and other supporting functions 5 6 7\section contact_sec Contact and License 8 9Email aschiffler at ferzkopp dot net to contact the author or better check 10author's homepage at http://www.ferzkopp.net for the most up-to-date 11contact information. 12 13This library is licenced under the zlib License, see the file LICENSE for details. 14 15 16\section intro_sec Introduction 17 18The SDL_gfx library evolved out of the SDL_gfxPrimitives code which 19provided basic drawing routines such as lines, circles or polygons for 20SDL Surfaces and adding a couple other useful functions for zooming 21images for example and doing basic image processing on byte arrays. 22 23Note that SDL_gfx is compatible with SDL version 1.2 (not SDL2). 24A contributed patch to enable compilation of SDL_gfx against SDL2 25with CMake is provided in the "Other Builds" folder. 26 27The current components of the SDL_gfx library are: 28- Graphic Primitives (SDL_gfxPrimitives.h, SDL_gfxPrimitives.c) 29- Rotozoomer (SDL_rotozoom.h, SDL_rotozoom.c) 30- Framerate control (SDL_framerate.h, SDL_framerate.c) 31- MMX image filters (SDL_imageFilter.h, SDL_imageFilter.c) 32- Custom Blit functions (SDL_gfxBlitFunc.h, SDL_gfxBlitFunc.c) 33- Build-in 8x8 Font (SDL_gfxPrimitives_font.h) 34 35 36 37\subsection notes_gfx Notes on Graphics Primitives 38 39Care has been taken so that all routines are fully alpha-aware and can 40blend any primitive onto the target surface if ALPHA<255. Surface depths 41supported are 1,2,3 and 4 bytes per pixel. Surface locking is implemented 42in each routine and the library should work well with hardware 43accelerated surfaces. 44 45\htmlonly 46<a href="../Screenshots/SDL_gfxPrimitives.jpg" target="_blank" title="SDL_gfxPrimitives Screenshot"><img src="../Screenshots/SDL_gfxPrimitives-thumb.jpg" border="0" hspace="5"></a><br /> 47\endhtmlonly 48 49Currently, The following Anti-Aliased drawing primitives are available: 50- AA-line 51- AA-polygon 52- AA-circle 53- AA-ellipse 54 55Note: All ___Color routines expect the color to be in the format 0xRRGGBBAA. 56 57\subsection notes_roto Notes on Rotozoomer 58 59The rotozoom code is not ASM-speed quality, but it should be fast enough 60even for some realtime effects if the CPU is good or bitmaps small. 61With interpolation the routines are typically used for pre-rendering stuff 62in higher quality (i.e. smoothing) - that's also the reason why the API differs 63from SDL_BlitRect() - as they create a new target surface each time rotozoom 64is called. The final rendering speed is dependent on the target surface 65size as it is beeing xy-scanned when rendering the new surface. 66 67\htmlonly 68<a href="../Screenshots/SDL_rotozoom.jpg" target="_blank" title="SDL_rotozoom Screenshot"><img src="../Screenshots/SDL_rotozoom-thumb.jpg" border="0" hspace="5"></a><br /> 69\endhtmlonly 70 71Note also that the smoothing toggle is dependent on the input surface bit 72depth. 8bit surfaces will \b never be smoothed - only 32bit surfaces will. 73 74Note that surfaces of other bit depth then 8 and 32 will be converted 75on the fly to a 32bit surface using a blit into a temporary surface. This 76impacts performance somewhat. 77 78Smoothing (interpolation) flags work only on 32bit surfaces: 79\verbatim 80 #define SMOOTHING_OFF 0 81 #define SMOOTHING_ON 1 82\endverbatim 83 84\subsection notes_rate Notes on Framerate Manager 85 86The framerate functions are used to insert delays into the graphics loop 87to maintain a constant framerate. 88 89The implementation is more sophisticated that the usual 90\verbatim 91 SDL_Delay(1000/FPS); 92\endverbatim 93call since these functions keep track of the desired game time per frame 94for a linearly interpolated sequence of future timing points of each frame. 95This is done to avoid rounding errors from the inherent instability in the 96delay generation and application. 97 98\htmlonly 99<a href="../framerate.png" target="_blank" title="Framerate Diagram"><img src="../framerate-thumb.png" border="0"></a><br /> 100\endhtmlonly 101 102i.e. the 100th frame of a game running at 50Hz will be accurately 1032.00sec after the 1st frame (if the machine can keep up with the drawing). 104 105The functions return 0 or 'value' for sucess and -1 for error. All functions 106use a pointer to a framerate-manager variable to operate. 107 108 109\subsection notes_filter Notes on ImageFilters 110 111The imagefilter functions are a collection of MMX optimized routines that 112operate on continuous buffers of bytes - typically greyscale images from 113framegrabbers and such - performing functions such as image addition and 114binarization. All functions (almost ... not the the convolution routines) 115have a C implementation that is automatically used on systems without MMX 116capabilities. 117 118The compiler flag -DUSE_MMX toggles the conditional compile of MMX assembly. 119An assembler must be installed (i.e. "nasm"). 120 121 122\subsection notes_blitters Notes on Custom Blitters 123 124The custom blitter functions provide (limited) support for surface 125compositing - that is surfaces can be blitted together, and then 126still blitted to the screen with transparency intact. 127 128\subsection platforms Supported Platforms 129 130\subsubsection platformlinux Unix/Linux 131 132The library compiles and is tested for a Linux target (gcc compiler) via the 133the usual configure;make;make install sequence. 134 135\subsubsection platformwindows Windows 136 137A Win32 target is available (VisualC, mingw32, xmingw32 cross-compiler). 138 139VS2015 SP3 140 141- Download SDL sources for Windows from https://www.libsdl.org/download-1.2.php 142- Place files into directory along the SDL_gfx source folder as SDL-1.2.15 143- Recompile SDL with VS2015 144- Open SDL_gfx_VS2015.sln 145 146Older solution versions (VS2010, VS2008) are also still included 147and should work with those versions, including express versions, after path 148compiler and linker path adjustments. 149 150See "Other Builds" for additional makefiles (likely out of date, since not maintained). 151 152When using the cross-compiler (available on the author's homepage, very 153out of date), the build process generates .DLLs. You can use the command 154line 'LIB.EXE' tool to generate VC6 compatible .LIB files for linking 155purposes. 156 157\subsubsection platformosx Mac OSX 158 159The usual autotools build chain should be used. MacPorts or fink may 160be required (that's what the author uses). 161 162Xcode is supported via templates. See "Other Builds" folder Xcode3+.zip - 163this template only supports SDL_gfx and not the tests. For this template, the 164Deployment Target (the lowest version to run on) is set to 10.5 and expects 165the SDL.framework preinstalled in some default location 166(either /Library/Frameworks, or ~/Library/Frameworks). 167 168Older targets are also reported to work (10.3+ native and Project Builder). 169 170\subsubsection platformqnx QNX 171 172QNX was reported to build (see .diff in "Other Builds"). 173 174\subsubsection platformzune Zune 175 176ZuneHD (WinCE 6 ARM) is reported to build (see OpenZDK in "Other Builds"). 177Note that between rendering on the Zune's ARM CPU and constantly uploading 178textures to the GPU, SDL_gfx is going to be slow. Also, the libc math 179functions all use software FP emulation even when VFP floating point 180support is turned on in the compiler, so there's extra overhead due to that 181as well. 182 183\subsubsection platformothers Others 184 185Other platforms might work but have not been tested by the author. 186Please check the file "INSTALL" as well as the folder "Other Builds". 187 188See also section "Installation" below for more build instructions. 189 190\section install_sec Installation 191 192\subsection unix Unix/Linux 193 194To compile the library your need the SDL 1.2 installed from source or 195installed with the 'devel' RPM package. For example on Mandriva, run: 196\verbatim 197 urpmi libSDL1.2-devel 198\endverbatim 199 200Then run 201\verbatim 202 ./autogen.sh # (optional, recommended) 203 ./configure 204 make 205 make install 206 ldconfig 207\endverbatim 208 209to compile and install the library. The default location for the 210installation is /usr/local/lib and /usr/local/include. The libary 211path might need to be added to the file: 212 /etc/ld.so.conf 213 214Run the shell script 'nodebug.sh' before make, to patch the makefile 215for optimized compilation: 216\verbatim 217 ./autogen.sh # (optional, recommended) 218 ./configure 219 ./nodebug.sh 220 make 221 make install 222 ldconfig 223\endverbatim 224 225Check the folder "Other Builds" for alternative makefiles. 226 227\subsection prep Build Prep 228 229Run autogen.sh or manually: 230\verbatim 231 aclocal --force 232 libtoolize --force --copy 233 autoreconf -fvi 234\endverbatim 235 236\subsection nommx No-MMX 237 238To build without MMX code enabled (i.e. PPC or for AMD64 architecture 239which is missing pusha/popa): 240\verbatim 241 ./configure --disable-mmx 242 make 243 make install 244\endverbatim 245i.e. to build on MacOSX 10.3+ use: 246\verbatim 247 ./configure --disable-mmx && make 248\endverbatim 249 250\subsection vs9 Windows (VC9, VS2010) 251 252Open SDL_gfx_VS2010.sln solution file and review README. 253 254\subsection vs8 Windows (VC8, VS2008) 255 256Open SDL_gfx_VS2008.sln solution file and review README. 257 258 259\subsection vc6 Windows (VC6/7) 260 261See folder Other Builds. 262 263To create a Windows DLL using VisualC6: 264\verbatim 265 unzip -a VisualC6.zip 266 vcvars32.bat 267 copy VisualC/makefile 268 nmake 269\endverbatim 270or 271\verbatim 272 unzip -a VisualC7.zip 273\endverbatim 274and open the project file. 275 276 277\subsection wince WindowsCE 278 279See folder Other Builds. 280 281May need workaround for missing lrint. 282 283 284\subsection cross Cross-Compilation 285 286To build using mingw32 on Win32, check the makefile contained in mingw.zip 287 288To create a Windows DLL using the xmingw32 cross-compiler: 289\verbatim 290 cross-configure 291 cross-make 292 cross-make install 293\endverbatim 294 295Make sure the -DBUILD_DLL is used (and only then) when creating the DLLs. 296Make sure -DWIN32 is used when compiling the sources (creating or using 297the DLLs. 298 299Specify the path to your cross-compiled 'sdl-config', and invoke 300'./configure' with the '--host' and '--build' arguments. For example, 301to cross-compile a .DLL from GNU/Linux: 302\verbatim 303 SDL_CONFIG=/usr/local/cross-tools/i386-mingw32msvc/bin/sdl-config \ 304 ./configure --host=i586-mingw32msvc --build=i686-pc-linux-gnu 305 make 306 make install 307\endverbatim 308 309\subsection qnx QNX 310 311To build on QNX6, patch first using: 312\verbatim 313 patch -p0 <QNX.diff 314\endverbatim 315 316\subsection osx OSX 317 318Use standard unix build sequence. 319 320To build on MacOS X with Project Builder, follow these steps: 321- Update your developer tools to the lastest version. 322- Install the SDL Developers framework for Mac OS X. 323- Download the latest SDL_gfx source distribution and extract the 324 archive in a convenient location. 325- Extract the included OSX-PB.tgz archive into the 326 top directory of the SDL_gfx distribution (from step 3). This will create a 327 PB that contains the project files. 328- The project has targets for the SDL_gfx framework and the four test 329 programs. All can be built using the 'deployment' or 'development' build 330 styles. 331 332A newer version for MaxOS X is included in the OSX-PB-XCode.zip archive. The 333updated version uses relative pathnames where appropriate, and pointers to 334the standard installation location of SDL. However, it may require XCode in 335order to be used. 336 337\section interfaces_sec Language Interfaces 338 339SDL_gfx has been integrated with the following language interfaces: 340- Pascal: http://www.freepascal-meets-sdl.net 341- Perl: http://sdl.perl.org 342- Python: http://www.pygame.org 343- C#: http://cs-sdl.sourceforge.net 344- Lua: http://www.egsl.retrogamecoding.org/ 345- Oberon: http://sourceforge.net/projects/sdl-for-oberon/ 346 347\section test_sec Test Programs 348 349Change to the ./Test directory and run 350\verbatim 351 ./autogen.sh 352 ./configure 353 make 354\endverbatim 355to create several test programs for the libraries functions. This requires 356the library to be previously compiled and installed. 357 358 359See the source code .c files for some sample code and implementation hints. 360 361 362\section contrib_sec Contributors 363 364- Fix for filledbox by Ingo van Lil, inguin at gmx.de - thanks Ingo. 365 366- Non-alpha line drawing code adapted from routine 367 by Pete Shinners, pete at shinners.org - thanks Pete. 368 369- More fixes by Karl Bartel, karlb at gmx.net - thanks Karl. 370 371- Much testing and suggestions for fixes from Danny van Bruggen, 372 danny at froukepc.dhs.org - thanks Danny. 373 374- Original AA-circle/-ellipse code idea from Stephane Magnenat, 375 nct at wg0.ysagoon.com - thanks Stephane. 376 377- Faster blending routines contributed by Anders Lindstroem, 378 cal at swipnet.se - thanks Anders. 379 380- New AA-circle/-ellipse code based on ideas from Anders Lindstroem - 381 thanks Anders. 382 383- VisualC makefile contributed by Danny van Bruggen, 384 danny at froukepc.dhs.org - thanks Danny. 385 386- VisualC7 project file contributed by James Turk, 387 jturk at conceptofzero.com - thanks James. 388 389- Project Builder package contributed by Thomas Tongue, 390 TTongue at imagiware.com - Thanks Thomas. 391 392- Fix for filledPolygon contributed by Kentaro Fukuchi 393 fukuchi at is.titech.ac.jp - Thanks Kentaro. 394 395- QNX6 patch contributed by Mike Gorchak, 396 mike at malva.ua - Thanks Mike. 397 398- Pie idea contributed by Eike Lange, 399 eike.lange at uni-essen.de - Thanks Eike. 400 401- Dynamic font setup by Todor Prokopov, 402 koprok at dir.bg - Thanks Todor. 403 404- Horizontal/Vertical flipping code by Victor (Haypo) 405 Stinner, victor.stinner at haypocalc.com - Thanks Victor. 406 407- OSX build fixes by Michael Wybrow, 408 mjwybrow at cs.mu.oz.au - Thanks Michael. 409 410- gcc3.4 build fixes by Dries Verachtert, 411 dries at ulyssis.org - Thanks Dries. 412 413- Updated OSX build by Brian Rice, 414 water451 at gmail.com - Thanks Brian. 415 416- aaellipse issues pointed out by Marco Wertz, 417 marco.wertz at gmx.de - Thanks Marco. 418 419- texturedPolygon idea and code by Kees Jongenburger, 420 kees.jongenburger at gmail.com - Thanks Kees. 421 422- Several bugfixes contributed by Sigborn Skjaeret, 423 cisc at broadpark.no - Thanks CISC. 424 425- Syntax error for C++ found by Olivier Boudeville, 426 olivier.boudeville at online.fr - Thanks Olivier. 427 428- hline/vline clipping fixes found by Daniel Roggen, 429 droggen at gmail.com and Mikael Thieme, 430 mikael.thieme at his.se - Thanks Daniel+Mikael. 431 432- rotozoom fix for big-endian machines (i.e. PPC) 433 by Julian Mayer, julianmayer at mac.com - Thanks 434 Julian. 435 436- Cross-compilation notes contributed by Sylvain 437 Beucler, beuc at beuc.net - Thanks Sylvain. 438 439- Fix duplicate pixel renders in circleColor contributed 440 by David Raber, lotharstar at gmail.com - Thanks David. 441 442- New arcColor (and arcRGBA) routine contributed 443 by David Raber, lotharstar at gmail.com - Thanks David. 444 445- Idea for polygonColorMT and texturePolygonMT routines for 446 multithreaded operation contributed by "unknown" - 447 Thank you. 448 449- Multiple patches applied and repackaged version 2.0.18 450 by Paul, sweetlilmre at gmail.com - Thanks Paul and 451 other contributors of patches. 452 453- Change to avoid gcc4 compiler warnings contributed by Thien-Thi 454 nguyen, ttn at gnuvola.org - thanks Thi. 455 456- hline 1bpp off-by-one patch contributed by Manuel Lausch 457 mail at manuellausch.de - Thanks Manuel. 458 459- pkg-config support contributed by Luca Bigliardi, shammash 460 at artha.org - thanks Luca. 461 462- Updated mingw Makefile contributed by Jan Leike, jan dot leike 463 at gmx dot net - thanks Jan. 464 465- Rotozoom debugging help by Jeff Wilges, heff at ifup dot us - 466 thanks Jeff. 467 468- Build updates provided by Barry deFreese, bdefreese at debian 469 dot org - thanks Barry. 470 471- Fix for 1-pixel postponement with 8bit scaling by Sylvain Beucler, 472 beuc at beuc dot net - thanks Sylvain. 473 474- Updates to headers and configure to allow for cross-compiling 475 to DLL (not just static .a) and fixes for compiling on Windows 476 using autotools by Sylvain Beucler, beuc at beuc dot net - thanks Sylvain. 477 478- Added Visual CE Project to Builds. Contributed by vrichomme at smartmobili 479 dot com - thanks. 480 481- Added Symbian and Windows 64bit fix with lrint function by Rene 482 Dudfield, renesd at gmail dot com - thanks Rene. 483 484- Fixes for Rotate90 0-degree case by Chris Allport, chris dot allport 485 at gmail dot com - thanks Chris. 486 487- Fixed for Win32 build support defines by tigerfishdaisy (SF) - thanks 488 Tiger Tiger. 489 490- Patch for OpenSDK contributed by itsnotabigtruck at ovi dot com - thanks 491 IsNotABigTruck. 492 493- OSX Xcode 3+ template ZIP contributed by marabus at meta dot ua - thanks 494 Vasyl. 495 496- Memory leak/error check patch for zoomSurface contributed by 497 RodolfoRG - thanks Rodolfo. 498 499- Zoom scaling factor rounding bugfix patch contributed by WanderWander 500 Lairson Costa - thanks Wander. 501 502- Suggestions for speed improvements contributed by inkyankes - thanks. 503 504- Pixel blend routine patches contributed by mitja at lxnav dot com - 505 thanks Mitja. 506 507- ImageFilter patches contributed by beuc at beuc dot net - thanks Sylvain. 508 509- Bug reports contributed by Yannick dot Guesnet at univ-rouen dot fr - 510- thanks Yannick. 511 512\section changelog_sec Change Log 513 514\verbinclude ChangeLog 515 516*/
