home *** CD-ROM | disk | FTP | other *** search
/ RISCWORLD 7 / RISCWORLD_VOL7.iso / Software / Issue4 / SDL / gcc346 / !SDL / doc / sdlgfx-2.0.13 / README < prev   
Encoding:
Text File  |  2004-12-21  |  10.0 KB  |  321 lines
  1.  
  2. SDL_gfx - SDL graphics drawing primitives and other support functions
  3. =============================================================================
  4.  
  5. Email aschiffler@appwares.ca to contact the author or better check
  6. author's homepage at http://www.ferzkopp.net for the most up-to-date
  7. contact information.
  8.  
  9. This library is licenced under the LGPL, see the file LICENSE for details. 
  10.  
  11.  
  12. Intro
  13. -----
  14.  
  15. The SDL_gfx library evolved out of the SDL_gfxPrimitives code which
  16. provided basic drawing routines such as lines, circles or polygons for 
  17. SDL Surfaces and adding a couple other useful functions for zooming 
  18. images for example and doing basic image processing on byte arrays.
  19.  
  20. The 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.  
  26. See ./Docs directory for a longer HTML version of this document.
  27.  
  28.  
  29. Supported Platforms
  30. -------------------
  31.  
  32. The library compiles and is tested for a Linux target (gcc compiler) and 
  33. a Win32 target (VisualC6/7, xmingw32 cross-compiler). MacOS X target is 
  34. reported to work (Project Builder). QNX is reported to build well (see diff).
  35.  
  36. When using the cross-compiler (available on the author's homepage), 
  37. the build process generates .DLLs. You can use the command line 'LIB.EXE' 
  38. tool to generate VC6 compatible .LIB files for linking purposes. 
  39.  
  40. Other platforms might work but have not been tested by the author.
  41.  
  42. See below for build instructions.
  43.  
  44.  
  45. Notes on Graphics Primitives
  46. ----------------------------
  47.  
  48. Care has been taken so that all routines are fully alpha-aware and can 
  49. blend any primitive onto the target surface if ALPHA<255. Surface depths 
  50. supported are 1,2,3 and 4 bytes per pixel. Surface locking is implemented
  51. in each routine and the library should work well with hardware 
  52. accelerated surfaces. 
  53.  
  54. Currently, The following Anti-Aliased drawing primitives are available:
  55. - AA-line
  56. - AA-polygon
  57. - AA-circle
  58. - AA-ellipse
  59.  
  60. [[[ Interface ]]]
  61.  
  62. See SDL_gfxPrimitives.h for all the drawing functions.
  63.  
  64.  
  65. Notes on Rotozoomer
  66. -------------------
  67.  
  68. The rotozoom code is not ASSEMBLY quality - but it should be fast enough 
  69. even for some realtime effects if the CPU is good or bitmaps small.
  70. With interpolation the routines are typically used for pre-rendering stuff 
  71. in higher quality (i.e. smoothing) - that's also a reason why the API differs 
  72. from SDL_BlitRect() and creates a new target surface each time rotozoom 
  73. is called. The final rendering speed is dependent on the target surface
  74. size as it is beeing xy-scanned when rendering the new surface.
  75.  
  76. Note also that the smoothing toggle is dependent on the input surface bit 
  77. depth. 8bit surfaces will never be smoothed - only 32bit surfaces will.
  78.  
  79. Note that surfaces of other bit depth then 8 and 32 will be converted 
  80. on the fly to a 32bit surface using a blit into a temporary surface. This 
  81. impacts performance somewhat.
  82.  
  83.  
  84. [[[ Interface ]]]
  85.  
  86. SDL_Surface * rotozoomSurface (SDL_Surface *src, double angle, double zoom, int smooth);
  87.  
  88.  Rotates and zoomes a 32bit or 8bit 'src' surface to newly created 'dst' surface.
  89.  'angle' is the rotation in degrees. 'zoom' a scaling factor. If 'smooth' is 1
  90.  then the destination 32bit surface is anti-aliased. If the surface is not 8bit
  91.  or 32bit RGBA/ABGR it will be converted into a 32bit RGBA format on the fly.
  92.  
  93.  
  94. SDL_Surface * rotozoomSurfaceXY (SDL_Surface *src, double angle, double zoomx, double zoomy, int smooth);
  95.  
  96.  Rotates and zoomes a 32bit or 8bit 'src' surface to newly created 'dst' surface.
  97.  'angle' is the rotation in degrees. 'zoomx' and 'zoomy' are scaling factors that
  98.  can also be negative. In this case the corresponding axis is flipped.  If 'smooth' 
  99.  is 1 then the destination 32bit surface is anti-aliased. If the surface is not 8bit
  100.  or 32bit RGBA/ABGR it will be converted into a 32bit RGBA format on the fly.
  101.  
  102.  Note: Flipping currently only works with antialiasing turned off.
  103.  
  104.  
  105. SDL_Surface * zoomSurface (SDL_Surface *src, double zoomx, double zoomy, int smooth);
  106.  
  107.  Zoomes a 32bit or 8bit 'src' surface to newly created 'dst' surface.
  108.  'zoomx' and 'zoomy' are scaling factors for width and height. If 'smooth' is 1
  109.  then the destination 32bit surface is anti-aliased. If the surface is not 8bit
  110.  or 32bit RGBA/ABGR it will be converted into a 32bit RGBA format on the fly.
  111.  
  112.  
  113. Smoothing (interpolation) flags work only on 32bit surfaces:
  114.  
  115.  #define SMOOTHING_OFF        0
  116.  #define SMOOTHING_ON        1
  117.  
  118.  
  119. Notes on framerate functions
  120. ----------------------------
  121.  
  122. The framerate functions are used to insert delays into the graphics loop
  123. to maintain a constant framerate.
  124.  
  125. The implementation is more sophisticated that the usual
  126.     SDL_Delay(1000/FPS); 
  127. call since these functions keep track of the desired game time per frame 
  128. for a linearly interpolated sequence of future timing points of each frame. 
  129. This is done to avoid rounding errors from the inherent instability in the 
  130. delay generation and application.
  131.  
  132. i.e. the 100th frame of a game running at 50Hz will be accurately
  133. 2.00sec after the 1st frame (if the machine can keep up with the drawing).
  134.  
  135.  
  136. [[[ Interface ]]]
  137.  
  138. The functions return 0 or 'value' for sucess and -1 for error. All functions
  139. use a pointer to a framerate-manager variable to operate.
  140.  
  141. void SDL_initFramerate(FPSmanager * manager);
  142.  
  143.  Initialize the framerate manager, set default framerate of 30Hz and
  144.  reset delay interpolation.
  145.  
  146.  
  147. int SDL_setFramerate(FPSmanager * manager, int rate);
  148.  
  149.  Set a new framerate for the manager and reset delay interpolation.
  150.  
  151.  
  152. int SDL_getFramerate(FPSmanager * manager);
  153.  
  154.  Get the currently set framerate of the manager.
  155.  
  156.  
  157. void SDL_framerateDelay(FPSmanager * manager);
  158.  
  159.  Generate a delay to accomodate currently set framerate. Call once in the
  160.  graphics/rendering loop. If the computer cannot keep up with the rate (i.e.
  161.  drawing too slow), the delay is zero and the delay interpolation is reset.
  162.  
  163.  
  164. Notes on imageFilter functions
  165. ------------------------------
  166.  
  167. The imagefilter functions are a collection of MMX optimized routines that
  168. operate on continuous buffers of bytes - typically greyscale images from 
  169. framegrabbers and such - performing functions such as image addition and 
  170. binarization. All functions (almost .. not the the convolution routines) 
  171. have a C implementation that is automatically used on systems without MMX 
  172. capabilities.
  173.  
  174.  
  175. [[[ Interface ]]]
  176.  
  177. See the extensive list of routines in SDL_imageFilters.h for info.
  178.  
  179.  
  180.  
  181. Installation and Test
  182. ---------------------
  183.  
  184. To compile the library your need the SDL 1.2 installed from source or 
  185. installed with the 'devel' RPM package. For example on Mandrake, run:
  186.     urpmi  libSDL1.2-devel
  187.  
  188. The run
  189.     ./autogen.sh    (optional)
  190.     ./configure
  191.     make
  192.     make install
  193.     ldconfig
  194.  
  195. to compile and install the library. The default location for the 
  196. installation is /usr/local/lib and /usr/local/include. The libary 
  197. path might need to be added to the file
  198.     /etc/ld.so.conf
  199.  
  200. Run the shell script 'nodebug.sh' before make, to patch the makefile 
  201. for optimized compilation:
  202.     ./autogen.sh    (optional)
  203.     ./configure
  204.     ./nodebug.sh
  205.     make
  206.     make install
  207.     ldconfig
  208.  
  209. To create a Windows DLL using VisualC:
  210.     unzip -a VisualC6.zip
  211.     vcvars32.bat
  212.     copy VisualC/makefile
  213.     nmake
  214. or
  215.     unzip -a VisualC7.zip
  216. and open the project file.
  217.  
  218.  
  219. To create a Windows DLL using the xmingw32 cross-compiler:
  220.     cross-configure
  221.     cross-make
  222.     cross-make install
  223.  
  224.  
  225. To build without MMX code enabled (i.e. PPC architecture):
  226.     ./configure --disable-mmx
  227.     make
  228.     make install
  229.  
  230.  
  231. To build on QNX6, patch first using:
  232.     patch -p0 <QNX.diff
  233.  
  234.  
  235. To build on MacOS X with Project Builder, follow these steps:
  236.     * Update your developer tools to the lastest version (December 2002 as
  237.     of this revision).
  238.     * Install the SDL Developers framework for Mac OS X.
  239.     * Download the latest SDL_gfx source distribution and extract the
  240.     archive in a convenient location.
  241.     * Extract the included OSX-PB.tgz archive into the
  242.     top directory of the SDL_gfx distribution (from step 3). This will create a
  243.     PB that contains the project files.
  244.     * The project has targets for the SDL_gfx framework and the four test
  245.     programs. All can be built using the 'deployment' or 'development' build
  246.     styles. 
  247.  
  248.  
  249.  
  250. Test Programs
  251. -------------
  252.  
  253. Change to the ./Test directory and run
  254.     ./configure
  255.     make
  256. to create several test programs for the libraries functions. This requires
  257. the library to be compiled and installed.
  258.  
  259.  
  260. See the source code .c files for sample code.
  261.  
  262.  
  263. Thanks
  264. ------
  265.  
  266. Thanks to 'AppWares Development Group' for supporting this project - please 
  267. visit http://www.appwares.com for more information.
  268.  
  269.  
  270. Contributors
  271. ------------
  272.  
  273. * Fix for filledbox by Ingo van Lil, inguin at gmx.de - thanks Ingo.
  274.  
  275. * Non-alpha line drawing code adapted from routine 
  276.   by Pete Shinners, pete at shinners.org - thanks Pete.
  277.  
  278. * More fixes by Karl Bartel, karlb at gmx.net - thanks Karl.
  279.  
  280. * Much testing and suggestions for fixes from Danny van Bruggen,
  281.   danny at froukepc.dhs.org - thanks Danny.
  282.  
  283. * Original AA-circle/-ellipse code idea from Stephane Magnenat, 
  284.   nct at wg0.ysagoon.com - thanks Stephane.
  285.  
  286. * Faster blending routines contributed by Anders Lindström,
  287.   cal at swipnet.se - thanks Anders.
  288.  
  289. * New AA-circle/-ellipse code based on ideas from Anders Lindström - 
  290.   thanks Anders.
  291.  
  292. * VisualC makefile contributed by Danny van Bruggen, 
  293.   danny at froukepc.dhs.org - thanks Danny.
  294.  
  295. * VisualC7 project file contributed by James Turk, 
  296.   jturk at conceptofzero.com - thanks James.
  297.  
  298. * Project Builder package contributed by Thomas Tongue, 
  299.   TTongue at imagiware.com - Thanks Thomas.
  300.  
  301. * Fix for filledPolygon contributed by Kentaro Fukuchi 
  302.   fukuchi at is.titech.ac.jp - Thanks Kentaro.
  303.  
  304. * QNX6 patch contributed by Mike Gorchak,
  305.   mike at malva.ua - Thanks Mike.
  306.  
  307. * Pie idea contributed by Eike Lange,
  308.   eike.lange at uni-essen.de - Thanks Eike.
  309.  
  310. * Dynamic font setup by Todor Prokopov,
  311.   koprok at dir.bg - Thanks Todor.
  312.  
  313. * Horizontal/Vertical flipping code by Victor (Haypo) 
  314.   Stinner, victor.stinner at haypocalc.com - Thanks Victor.
  315.  
  316. * OSX build fixes by Michael Wybrow, 
  317.   mjwybrow at cs.mu.oz.au - Thanks Michael.
  318.  
  319. * gcc3.4 build fixes by Dries Verachtert, 
  320.   dries at ulyssis.org - Thanks Dries.
  321.