home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 3 / PDCD_3.iso / games / gamesuite / !FastSpr / FSprHelp / Manual < prev    next >
Text File  |  1995-01-29  |  6KB  |  190 lines
  1. FastSpr Documentation - version 3.00
  2. =====================
  3.  
  4.   FastSpr is a module occupying about 8K, designed to offer high speed sprite
  5. plotting to the games writer.  Typically it is at least twice as fast as OS
  6. routines, whilst providing full masking and a variable clipping window.  The
  7. routines may be accessed via SWIs or direct calls.
  8.  
  9. Using FastSpr
  10. =============
  11.  
  12.   FastSpr uses a special sprite format, which provides high speed plotting. 
  13. Sprite files are most easily produced using the application FSPConv, with
  14. which instructions are provided.  Basically, you need to do the following:
  15.  
  16.   o  Make a SpriteFile (using !Paint) with sprites called 0,1,2,3,4...etc
  17.  
  18.   o  Drag this to the FSPConv icon
  19.  
  20.   o  Click convert.
  21.  
  22.   The FastSpr files are usually about twice the size of the originating
  23. sprite file, but may be up to six times as large, or smaller, depending on
  24. the amount of transparent area of the sprites.  See the help files with
  25. FSPConv for full details.
  26.  
  27. Loading the Module
  28. ==================
  29.  
  30.   You can load the module by either double clicking the application, or using
  31. the command *RMLoad FastSpr:FastSpr, or whatever you can engineer for
  32. yourself.
  33.  
  34. Loading your sprites
  35. ====================
  36.  
  37.   The FastSpr file may be loaded in either of two ways:
  38.  
  39. (i)  Into the RMA    : Using *FastSprLoad or the SWI "FastSpr_Load"
  40. (ii) Into user memory.  There is a simple way to load the file into an
  41. Amnesia area.  See the entry on FastSpr_GetPointer in the SWIDocs file.
  42.  
  43. Typical BASIC coding:
  44.  
  45. 10 *FastSprLoad 1 Filename
  46.  
  47. or
  48.  
  49. 10 SYS "FastSpr_Load","Filename",1
  50.  
  51. Plotting
  52. ========
  53.  
  54.   Before any FastSpr operation, select the correct MODE for the sprites you
  55. are using.  The SWI used to plot sprite is "FastSpr_Plot", number &47D00. 
  56. Remeber that for speed, the SWIs should be referred to by number, not name.
  57.  
  58. Typical BASIC coding:
  59.  
  60. 10 SYS &47D00,&02000003,160,128  - Plots sprite 3 from pool 2 at coordinates
  61. 160,128.
  62.  
  63. Coordinates
  64. ===========
  65.  
  66.   FastSpr uses memory coordinates.  The top left of the screen is (0,0), and
  67. the bottom right is (x-1,y-1) where x is the number of bytes in one line, and
  68. y is the number of lines.  For example, in MODE 13 (256 colour,320 by 256
  69. pixels), (319,255) is the bottom right corner of the screen.  The application
  70. !FSPConv produces sprites for which the middle of the sprite is plotted at
  71. the coordinates given.  Negative coords and those off the screen are
  72. acceptable.
  73.  
  74. Clipping Window
  75. ===============
  76.  
  77.   The sprites are clipped (ie parts outside of the window are not plotted)
  78. according to the window set by SWI "FastSpr_SetClipWindow".
  79.  
  80. Typical BASIC coding:
  81.  
  82. 10 SYS "FastSpr_SetClipWindow",xmin,ymin,xmax,ymax
  83.  
  84. Xmin and ymin are inclusive, whereas xmax and ymax are exclusive, so the
  85. correct window for the whole of a MODE 13 screen is 0,0,320,256.
  86.  
  87.   The SWI "FastSpr_ClearWindow" fills the clip window with the current
  88. backdrop colour, set by SWI "FastSpr_SetBackdrop" or *FastSprBackdrop.
  89.  
  90.  
  91. ScreenBanks
  92. ===========
  93.  
  94.   FastSpr supports switching of screen banks to provide flicker free updates.
  95. SWI "FastSpr_Screenbank" does the job.  A value of 1 supplied switches all
  96. subsequent operations to the shadow bank (the OS bank 2), any other value to
  97. the main bank (OS bank 1).
  98.  
  99. Typical BASIC coding:
  100.  
  101. 10 b%=1
  102. 20 REPEAT               loop starts
  103.  
  104. Do plotting, etc, here
  105.  
  106. 30 WAIT
  107. 40 SYS &47D06,b%     sets FastSpr's bank to one bank
  108. 50 SYS &6,&71,b%     sets the displayed bank to the other (SWI is OS_Byte)
  109. (55 SYS &6,&70,2-b%) only if you're using normal plotting routines as well
  110. 60 SYS &47D01        clears FastSpr's window
  111. 70 bank%=3-b%        switches the banks for next time 
  112.  
  113. 80 UNTIL FALSE          loop ends
  114.  
  115.   Note : The most common problem with switching banks is neglecting to
  116. allocate enough screen memory.  No errors are produced - it just doesn’t
  117. work.
  118.  
  119. Other Features
  120. ==============
  121.  
  122.   For ultimate speed, you can call some routines directly to save time
  123. decoding the SWI issued.  The SWI "FastSpr_GetAddress" returns the addresses
  124. of the useful routines.
  125.  
  126. Typical BASIC coding:
  127.  
  128. 10 SYS "FastSpr_GetAddress",plotadr,clearadr,bankadr
  129. ...
  130. 20 A%=0
  131. 30 B%=160
  132. 40 C%=128
  133. 50 CALL plotadr
  134.  
  135. is equivalent to
  136.  
  137. 10 SYS "FastSpr_Plot",0,160,128
  138.  
  139.   Remember that these routines are in the RMA, so the desktop and RMTidy
  140. commands may move the module and your addresses will no longer be valid.
  141.  
  142. Speed Considerations
  143. ====================
  144.  
  145.   The following guidelines should provide maximum speed.
  146.  
  147. (1)  Use sprites with as many transparent pixels as possible.  A sprite with
  148. twice as many solid pixels takes almost twice as long to plot in most cases.
  149.  
  150. (2)  If you're using SWI FastSpr_ClearWindow, choose a clip window which
  151. (best) includes the whole width of the screen, or (next best) where xmin and
  152. xmax are multiples of 4.
  153.  
  154. (3)  In BASIC refer to all SWIs by number if they need to be fast. 
  155.  
  156. (4)  Avoid horizontal clipping if you can.  Clipping the top or bottom of a
  157. sprite carries no time penalty, but clipping the sides may increase plotting
  158. time to up to twice.  When clipping both sides, plotting time may be x3.
  159.  
  160. What it can't cope with
  161. =======================
  162.  
  163. (1)  Sprites bigger than 255 pixels along either axis in FSP1 format.
  164.  
  165. (2)  Screen modes wider than 640 pixels, or narrower than 4 (window clearing
  166. only).
  167.  
  168.   To avoid problems, the following may be helpful.
  169.  
  170. (1)  Make sure you are in the right mode for your sprite.
  171.  
  172. (2)  Don't set clip windows and then change mode (which resets them).
  173.  
  174. (3)  Don't chop up your machine with an axe.
  175.  
  176. (4)  Don't forget that the module uses non-standard coordinates.
  177.  
  178. Conditions
  179. ==========
  180.  
  181.   This version of FastSpr may be freely used and distributed for commercial
  182. or non-commercial applications.  If you can distribute the whole application
  183. and the application !FSPConv with your software then so much the better, but
  184. otherwise just include whatever you need.  You must not remove my copyright
  185. notice from the module.
  186.   This software is supplied as is, and no liability will be accepted for loss
  187. or damage of any kind arising from its use or misuse.
  188.  
  189. Andy Southgate, 5th Nov 1993. Updated 16th October 1994.
  190.