FastSpr is a module occupying about 5K, designed to offer high speed sprite plotting to the games writer. Typically it is at least twice as fast as OS routines, whilst providing full masking and a variable clipping window. The routines may be accessed via SWIs or direct calls.
Using FastSpr
=============
FastSpr uses a special sprite format, which provides high speed plotting. Sprite files are most easily produced using the application !FSPConv, with which instructions are provided.
The FastSpr files are usually about twice the size of the originating sprite file, but may be up to six times as large, or smaller, depending on the amount of transparent area of the sprites. !FSPConv usually treats colour 0 as transparent, and the more pixels which have colour 0, the smaller the FastSpr file.
Loading the Module
==================
You can load the module by either double clicking the application, or using the command *RMLoad FastSpr:FastSpr, or whatever you can engineer for yourself.
Loading your sprites
====================
The FastSpr file may be loaded in either of two ways:
(i) Into the RMA : Using *FastSprLoad or the SWI "FastSpr_Load"
(ii) Into user memory: For example, DIMming space from basic, loading the file into that space, and using SWI "FastSpr_SpritesAreAt" to tell FastSpr where they are.
Typical BASIC coding:
10 *FastSprLoad Filename
or
10 SYS "FastSpr_Load","Filename"
or
10 SYS "OS_File",&5,"Filename" TO ,,,,length - get the file length
20 DIM sprites length - make space for it
30 OSCLI "Load Filename "+STR$~(sprites) - load it in
Before any FastSpr operation, select the correct MODE for the sprites you are using. The SWI used to plot sprite is "FastSpr_Plot", number &47D00. Remeber that for speed, the SWIs should be referred to by number, not name.
Typical BASIC coding:
10 SYS &47D00,0,160,128 - Plots sprite 0 at coordinates 160,128.
Coordinates
===========
FastSpr uses memory coordinates. The top left of the screen is (0,0), and the bottom right is (x-1,y-1) where x is the number of bytes in one line, and y is the number of lines. For example, in MODE 13 (256 colour,320 by 256 pixels), (319,255) is the bottom right corner of the screen. The application !FSPConv produces sprites for which the middle of the sprite is plotted at the coordinates given. Negative coords and those off the screen are acceptable.
Clipping Window
===============
The sprites are clipped (ie parts outside of the window are not plotted) according to the window set by SWI "FastSpr_SetClipWindow".
Xmin and ymin are inclusive, whereas xmax and ymax are exclusive, so the correct window for the whole of a MODE 13 screen is 0,0,320,256.
The SWI "FastSpr_ClearWindow" fills the clip window with the current backdrop colour, set by SWI "FastSpr_SetBackdrop" or *FastSprBackdrop.
ScreenBanks
===========
FastSpr supports switching of screen banks to provide flicker free updates. SWI "FastSpr_Screenbank" does the job. A value of 1 supplied switches all subsequent operations to the shadow bank (the OS bank 2), any other value to the main bank (OS bank 1).
Typical BASIC coding:
10 b%=1
20 REPEAT loop starts
Do plotting, etc, here
30 WAIT
40 SYS &47D06,b% sets FastSpr's bank to one bank
50 SYS &6,&71,b% sets the displayed bank to the other (SWI is OS_Byte)
(55 SYS &6,&70,2-b%) only if you're using normal plotting routines as well
60 SYS &47D01 clears FastSpr's window
70 bank%=3-b% switches the banks for next time
80 UNTIL FALSE loop ends
Note : The most common problem with switching banks is neglecting to allocate enough screen memory. No errors are produced - it just doesn’t work.
Other Features
==============
For ultimate speed, you can call some routines directly to save time decoding the SWI issued. The SWI "FastSpr_GetAddress" returns the addresses of the useful routines.
Remember that these routines are in the RMA, so the desktop and RMTidy commands may move the module and your addresses will no longer be valid.
Speed Considerations
====================
The following guidelines should provide maximum speed.
(1) Use sprites with as many transparent pixels as possible. A sprite with twice as many solid pixels takes almost twice as long to plot.
(2) If you're using SWI FastSpr_ClearWindow, choose a clip window which (best) includes the whole width of the screen, or (next best) where xmin and xmax are multiples of 4.
(3) In BASIC refer to all SWIs by number if they need to be fast, or use direct calls from machine code.
(4) Avoid horizontal clipping if you can. Clipping the top or bottom of a sprite carries no time penalty, but clipping the sides may increase plotting time to up to twice. When clipping both sides, plotting time may be x3.
What it can't cope with
=======================
(1) Sprites bigger than 255 pixels along either axis.
(2) Screen modes wider than 640 pixels, or narrower than 4 (window clearing only).
(3) Commands such as MODE 128+13 will cause FastSpr to misread the start of screen memory. Use MODE 15 followed by MODE 13 to reserve two screenbanks.
To avoid problems, the following may be helpful.
(1) Make sure you are in the right mode for your sprite.
(2) Don't set clip windows and then change mode (which resets them).
(3) Don't chop up your machine with an axe.
(4) Don't forget that the module uses non-standard coordinates.
(5) Errors of the form 'Address exception at &18228F4' (or some similar number) are usually down to FastSpr trying to write outside the screen. Check that your sprite file is OK and you have enough screen memory etc.
Conditions
==========
This version of FastSpr may be freely used and distributed for commercial or non-commercial applications. If you can distribute the whole application and the application !FSPConv with your software then so much the better, but otherwise just include whatever you need. You must not remove my copyright notice from the module.
This software is supplied as is, and no liability will be accepted for loss or damage of any kind arising from its use or misuse.
