FastSpr uses a bit more memory for its sprites than RISC OS, and reaps the benefit with higher plotting speed and built in masking.
The Plotting Code
=================
FastSpr data is stored as one 32 bit word per pixel; the 8 LSBs are the colour, and the 24 MSBs are the offset in bytes of this pixel from the top left of the sprite.
3 bytes 1 byte
/-----------------------\ /------\
offset colour
The data can be lifted from memory and written to the screen using the followng code:
LDMIA R10!,{R0-R9}
STRB R0,[R11,R0,LSR #8]
STRB R1,[R11,R1,LSR #8]
STRB R2,[R11,R2,LSR #8]
etc etc....
Here the data is at address R10, and the screen address of the top left of the sprite is R11. In this way, data is transferred for one-and-a-bit instructions per pixel, and masking is automatic.
File Format
===========
The file format is as follows:
[word] the string "FSP1" - Identifies this as FastSpr type 1
[word] zero
[word] zero
[word] number of sprites
[word] offset to sprite 0 from the start of the file
[word] offset to sprite 1
[words] ....
[word] offset to last sprite
Sprite block
[byte] x size
[byte] y size
[byte] x offset - which will be subtracted from the given x coord
[byte] y offset - same, from the y coord
[word] offset to start of first line of sprite data
- offsets here are from the start of the sprite block
[word] offset to start of second line of sprite data
- which is directly after the end of the first line
[words] ....
[word] offset to end of last line of sprite data
words sprite data
End of sprite block
Naturally, each sprite has its own sprite block, pointed to by its own offset. The offsets in the sprite block are used for fast vertical clipping. It's definitely best to produce FastSpr files using the application !FSPConv or similar, and edit the program if you need anything different from the standard conversion.
FastSpr's Variables
======================
All of these are 32 bit words, stored at the address returned in R4 by SWI "FastSpr_GetAddress".
R4+0 Start of screen memory
R4+4 Amount of screen memory
R4+8 Vertical pixel resolution
R4+12 Number of bytes in one line
= horizontal pixel resolution if a 256 colour mode
R4+16 Size of the current mode in bytes
R4+20 The start of the screen bank FastSpr is using at the moment
R4+24 Address of sprite data
R4+28 Clip window : minimum x } Inclusive
R4+32 Minimum y }
R4+36 Maximum x } Exclusive
R4+40 Maximum y }
R4+44 Backdrop colour, repeated four times ie &CFCFCFCF for colour &CF.
The mode-dependant variables are updated upon a mode changed, as is the clip window. The clip window, screen bank and datastart may be written, to provide faster versions of the relavent SWIs. Setting dodgy clip windows, which would otherwise be screened out by the SWI, may lead to address exceptions or worse.
SWI Documentation
=================
SWI "FastSpr_Plot" : Takes the sprite number in R0, and the coords in R1 & R2. Returns promptly if the sprite is fully off the screen.
SWI "FastSpr_ClearWindow" : Fills the current clip window, on the current screen bank, with the backdrop colour. Is unlikely to produce a correctly filled window less than 4 pixels wide.
SWI "FastSpr_SetClipWindow" : R0 = min x, R1 = min y, R2 = max x, R3 = max y. Bad clip windows are trapped. Clip windows are reset to full screen after a mode change.
SWI "FastSpr_Load" : R0 must point to a valid filename. File is loaded into the RMA if there’s room, otherwise an error is returned.
SWI "FastSpr_GetAddress" : Returns addresses of routines which may need to be accessed quickly. When used in this way, the routines preserve only R10-R13. The SWI returns the following:
R0 Address to call for plot.
R1 Address to call for clearwindow.
R2 Address to call for screenbank changes.
R4 Address of the variables.
Most of the other module functions can be emulated by writing to the variable block pointed to by R4. All code can be executed in user or supervisor mode.
Incidentally, to branch-link to a register, use:
MOV R14,PC
MOV PC,R0 - for a branch to R0
...code continues
SWI "FastSpr_SetBackdrop" : Sets the backdrop colour used by "FastSpr_ClearWindow". R0 should contain the colour number 0-255 when the SWI is issued.
SWI "FastSpr_ScreenBank" : Subsequently, FastSpr will use the normal screenbank if R0<>1, or the shadow bank if R0=1. The normal bank is selected after a mode change. Note that FastSpr will not check if screen memory is actually there before trying to write to it, so it’s best to make sure first.
SWI "FastSpr_SpritesAreAt" : Sets FastSpr’s address of sprite data (vars+24) to a value passed in R0. The file validity is checked when a plot command is issued.
All of these SWIs should preserve all registers excluding R0. The module supports the command *Help FastSprSWIs which provides a handy list of the SWIs.
