www.riscos.com Technical Support: BBC BASIC Reference Manual

Sprites

A sprite is just a graphic shape made up of an array of pixels. You can create and manipulate sprites using Paint. This is a general-purpose painting program whose output happens to be stored in a sprite. It is fully described in the RISC OS 3 Applications Guide.

Having created one or more sprites in a spritefile (using Paint), you can then:

• load this file;
• manipulate and plot one or more sprites from it.

For a full description of how to load, manipulate and plot sprites see the Sprites chapter of the Programmer's Reference Manual.

Loading a user sprite

In the program fragment below the function FNload_sprites takes the name of a sprite file as a parameter and loads sprites from this file into a user sprite area:

 60 DEF FNload_sprites(sprite_file$)
 70   LOCAL length%, area_ptr%
 
 80   REM Find size of sprite file
 90   SYS "OS_File",13,sprite_file$ TO ,,,,length%

100   REM Reserve memory for user sprite area
110   REM Size of area should be size of file + 4 bytes for length
120   DIM area_ptr% length%+4-1

130   REM Initialise area with size...
140   area_ptr%!0 = length%+4
150   REM ...and with offset to first sprite
160   area_ptr%!4 = 16
170   REM Finish initialising with this sprite op
180   SYS "OS_SpriteOp",9+256,area_ptr%

190   REM Load sprites
200   SYS "OS_SpriteOp",10+256,area_ptr%,sprite_file$

210   REM Return pointer to user sprite area
220 = area_ptr%

The function FNload_sprites (defined above) calls OS_SpriteOp to initialise a sprite user area and load the specified sprite file into it. OS_SpriteOp is the SWI which controls the sprite system (SWI stands for SoftWare Interrupt, and is one of the ARM's built-in instructions). The first parameter this SWI takes is a number between 1 and 62 specifying the particular action to be taken. Adding 256 to this number indicates that it is a user sprite. These actions include:

OS_SpriteOp	9 + 256	initialise a sprite area
OS_SpriteOp	10 + 256	load sprite definitions from a spritefile into a sprite area
OS_SpriteOp	34 + 256	plot a sprite at the coordinates supplied

Plotting a user sprite

The following program calls the function FNload_sprites to load a spritefile and return a pointer to the control block of the user sprite area. It then calls OS_SpriteOp 34+256 (i.e. 290) to plot a sprite from this spritefile on the screen at coordinates (200,300), using a plot action of 0:

 10 REM Load spritefile from RISC OS "Applications 1" disc
 20 sprite_area% = FNload_sprites("adfs::App1.$.!System.!Sprites")
 30 REM plot sprite to screen at (200,300)
 40 SYS "OS_SpriteOp",34+256,sprite_area%,"!system",200,300,0
 50 END

The parameters that OS_SpriteOp 290 takes are:

pointer to control block of sprite area
sprite name
x coordinate
y coordinate
plot action:
	Value	Action
	0	Overwrite colour on screen
	1	OR with colour on screen
	2	AND with colour on screen
	3	exclusive OR with colour on screen
	4	Invert colour on screen
	5	Leave colour on screen unchanged
	6	AND with colour on screen with NOT of sprite pixel colour
	7	OR with colour on screen with NOT of sprite pixel colour
	&08	If set, then use the mask, otherwise don't
	&10	ECF pattern 1
	&20	ECF pattern 2
	&30	ECF pattern 3
	&40	ECF pattern 4
	&50	Giant ECF pattern (patterns 1 - 4 placed side by side)