# SPRITE

Compatible with:
DOS Maximite CMM MM150 MM170 MM+ MMX Picromite ArmiteL4 Armite F4 ArmiteH7 Picomite CMM2

Syntax:
SPRITE parameter

Description:
SPRITE
The SPRITE commands are used to manipulate small graphic images on the VGA screen. These are useful when writing games.
The maximum size of a sprite is MM.HRES-1 and MM.VRES-1

SPRITE CLOSE [#]n
Closes sprite “n” and releases its memory resources allowing the sprite number to be re-used.
The command will give an error if other sprites are copied from this one unless they are closed first.

SPRITE CLOSE ALL
Closes all sprites and releases all sprite memory. The screen is not changed.

SPRITE COPY [#]n, [#]m, nbr
Makes a copy of sprite “n” to “nbr” of new sprites starting a number “m”.
Copied sprites share the same loaded image as the original to save memory

SPRITE HIDE [#]n
SPRITE HIDE ALL
SPRITE HIDE SAFE [#]n
Removes sprite n from the display and replaces the stored background.
To restore a screen to a previous state sprites should be hidden in the opposite order to which they were written "LIFO"
Hides all the sprites allowing the background to be manipulated.

The following commands cannot be used when all sprites are hidden:
SPRITE SHOW (SAFE)
SPRITE HIDE (SAFE, ALL)
SPRITE SWAP
SPRITE MOVE
SPRITE SCROLLR
SPRITE SCROLL
Removes sprite n from the display and replaces the stored background.
Automatically hides all more recent sprites as well as the requested one and then replaces them afterwards.
This ensures that sprites that are covered by other sprites can be removed without the user tracking the write order.
Of course this version is less efficent than the simple version and should only be used it there is a risk of the sprite being partially covered.

SPRITE INTERRUPT sub
Specifies the name of the subroutine that will be called when a sprite collision occurs.
See Appendix E of the CMM2 manual for how to use the function SPRITE to interrogate details of what has collided

SPRITE LOAD fname$ [,start_sprite_number]
Loads the file ‘fname$’ which must be formatted as an original Colour Maximite sprite file.
See the original Colour Maximite MMBasic Language Manual for the file format. Multiple sprite files can be loaded by specifying a different ‘start_sprite_number’ for each file.
The programmer is responsible for making sure that the sprites do not overlap.

SPRITE LOADARRAY [#]n, w, h, array%()
Creates the sprite 'n' with width 'w' and height 'h' by reading w*h RGB888 values from 'array%()'. The RGB888 values must be stored in order of columns across and then rows down starting at the top left.
This allows the programmer to create simple sprites in a program without needing to load them from disk or read them from the display.
The firmware will generate an error if 'array%()' is not big enough to hold the number of values required.

SPRITE LOADPNG [#]n, fname$ [, transparency_cut_off]
Loads the PNG image ‘fname$’ as sprite number ‘n’.
If the PNG file is in ARGB8888 format the ‘transparency_cut_off’ parameter is used to determine whether the pixel should be solid or missing/transparent.
Valid values are 1 to 15, default is 8. MMBasic compares the 4 most significant bits of the transparency data in the file with the cut off value and assigns a transparency of 0 or 15 depending on the comparison.
This allows RGB(0,0,0) to be a valid solid colour. If the file is in RGB888 format then an RGB level of 0,0,0 is used to determine transparency as there is no other information to use.

SPRITE MOVE
Actions a single atomic transaction that re-locates all sprites which have previously had a location change set up using the SPRITE NEXT command.
Collisions are detected once all sprites are moved and reported in the same way as from a scroll

SPRITE NEXT [#]n, x, y
Sets the X and Y coordinate of the sprite to be used when the screen is next scrolled or the SPRITE MOVE command is executed.
Using SPRITE NEXT rather than SPRITE SHOW allows multiple sprites to be moved as part of the same atomic transaction.

SPRITE NOINTERRUPT
Disables collision interrupts

SPRITE RESTORE
Restores all the sprites. NB that any position changes previously requested using SPRITE NEXT will be actioned by the RESTORE and collision detection will be run.

SPRITE READ [#]n, x , y, w, h [,pagenumber]
Reads the display area specified by coordinates ‘x’ and ‘y’, width ‘w’ and height ‘h’ into buffer number ‘n’.
If the buffer is already in use and the width and height of the new area are the same as the original then the new command will overwrite the stored area.
The optional parameter page number specifies which page is to be read to create the sprite. The default is the current write page.
Set the page to FRAMEBUFFER to read from the framebuffer – see the FRAMEBUFFER command.

SPRITE SCROLL x, y [,col]
Scrolls the background and any sprites on layer 0 'x' pixels to the right and 'y' pixels up.
'x' can be any number between -MM.HRES-1 and MM.HRES-1,
'y' can be any number between -MM.VRES-1 and MM.VRES-1.
Sprites on any layer other than zero will remain fixed in position on the screen. By default the scroll wraps the image round.
If 'col' is specified the colour will replace the area behind the scrolled image. If 'col' is set to -1 the scrolled area will be left untouched.

SPRITE SCROLLR x, y, w, h, delta_x, delta_y [,col]
Scrolls the region of the screen defined by top-right coordinates ‘x’ and ‘y’ and width and height ‘w’ and ‘h’ by ‘delta_x’ pixels to the right and ‘delta_y’ pixels up.
By default the scroll wraps the background round. If ‘col’ is specified the colour will replace the area behind the scrolled image.
Sprites on any layer other than zero will remain fixed in position on the screen. Sprites in layer zero where the centre of the sprite (x+ w/2, y+ h/2) falls within the scrolled region will move with the scroll and wrap round if the centre moves outside one of the boundaries of the scrolled region.

SPRITE SHOW [#]n, x,y, layer, [orientation]
Displays sprite ‘n’ on the screen with the top left at coordinates ‘x’, ‘y’.
Sprites will only collide with other sprites on the same layer, layer zero, or with the screen edge. If a sprite is already displayed on the screen then the SPRITE SHOW command acts to move the sprite to the new location. The display background is stored as part of the command and will be replaced when the sprite is hidden or moved further.
‘orientation’ is optional and can be:
0 - normal display (default if omitted)
1 - mirrored left to right
2 - mirrored top to bottom
3 - rotated 180 degrees (= 1+2)

SPRITE SHOW SAFE [#]n, x,y, layer [,orientation] [,ontop]
SPRITE SWAP [#]n1, [#]n2 [,orientation]
Shows a sprite and automatically compensates for any other sprites that overlap it.
If the sprite is not already being displayed the command acts exactly the same as SPRITE SHOW.
If the sprite is already shown it is moved and remains in its position relative to other sprites based on the original order of writing. i.e. if sprite 1 was written before sprite 2 and it is moved to overlap sprite 2 it will display under sprite 2.
If the optional "ontop" parameter is set to 1 then the sprite moved will become the newest sprite and will sit on top of any other sprite it overlaps.
Refer to SPRITE SHOW for details of the orientation parameter. Replaces the sprite ‘n1’ with the sprite ‘n2’. The sprites must have the same width and height and ‘n1’ must be displayed or an error will be generated. The replacement sprite inherits the background from the original as well as its position in the list of order drawn.

SPRITE TRANSPARENCY [#]n, transparency
Transparency can be between 1 and 15 and changes all pixels with a nonzero transparency in the stored sprite to the new level.

SPRITE WRITE [#]n, x y [,orientation]
Overwrites the display with the contents of sprite buffer ‘n’ with the top left at coordinates ‘x’, ‘y’.
SPRITE WRITE overwrites the complete area of the display. The background that is overwritten is not stored so SPRITE WRITE is inherently higher performing than SPRITE SHOW but with greater functional
limitations.
The optional 'orientation' parameter defaults to 4 and specifies how the stored image data is changed as it is written out.
It is the bitwise AND of the following values:
&B001 = mirrored left to right
&B010 = mirrored top to bottom
&B100 = don't copy transparent pixels

SPRITE()

The SPRITE functions return information regarding sprites which are small graphic images on the VGA screen. These are useful when writing games.

SPRITE(C, [#]n )
Returns the number of currently active collisions for sprite n. If n=0 then returns the number of sprites that have a currently active collision following a SPRITE SCROLL command

SPRITE(C, [#]n, m)
Returns the number of the sprite which caused the “m”th collision of sprite
n. If n=0 then returns the sprite number of “m”th sprite that has a currently active collision following a SPRITE SCROLL command.
If the collision was with the edge of the screen then the return value will be:
&HF1 collision with left of screen
&HF2 collision with top of screen
&HF4 collision with right of screen
&HF8 collision with bottom of screen

SPRITE(D,spriteno1, spriteno2)
Returns the distance between the centres of spriteno1 and spriteno2. (returns -1 if either sprite is not active)

SPRITE(E, [#]n)
Returns a bitmap indicating any edges of the screen the sprite is in contact with: 1 =left of screen, 2=top of screen, 4=right of screen, 8=bottom of screen

SPRITE(H,[#]n)
Returns the height of sprite n. This function is active whether or not the sprite is currently displayed (active).
If sprite(E,spriteno) AND 1 Then
'collision with left of screen
Else If sprite(E,spriteno) AND 2 Then
'collision with top of screen
Else If sprite(E,spriteno) AND 4 Then
'collision with right of screen
Else If sprite(E,spriteno) AND 8 Then
'collision with bottom of screen

SPRITE(L, [#]n)
Returns the layer number of active sprites number n

SPRITE(N)
Returns the number of displayed (active) sprites

SPRITE(N,n)
Returns the number of displayed (active) sprites on layer n

SPRITE(S)
Returns the number of the sprite which last caused a collision.
NB if the number returned is Zero then the collision is the result of a SPRITE SCROLL command and the SPRITE(C…) function should be used to find how many and which sprites collided.

SPRITE(T,spriteno)
Returns a bitmap showing all the sprites currently in collision with the requested sprite.
Bits 0-63 in the returned integer represent a current collision with sprites 1 to 64 respectively

SPRITE(V,spriteno1,spriteno2)
Returns the vector from 'spriteno1' to 'spriteno2' in radians.
The angle is based on the clock so if 'spriteno2' is above 'spriteno1' on the screen then the answer will be zero. This can be used on any pair of sprites that are visible.
If either sprite is not visible the function will return -1. This is particularly useful after a collision if the programmer wants to make some differential decision based on where the collision occurred.
The angle is calculated between the centre of each of the sprites which may of course be different sizes.

SPRITE(W, [#]n)
Returns the width of sprite n. This function is active whether or not the sprite is currently displayed (active).

SPRITE(X, [#]n)
Returns the X-coordinate of sprite n. This function is only active when the sprite is currently displayed (active). Returns 10000 otherwise.

SPRITE(Y, [#]n)
Returns the Y-coordinate of sprite n. This function is only active when the sprite is currently displayed (active). Returns 10000 otherwise.

Last edited: 15 December, 2020