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