Compatible with:
DOS Maximite CMM MM150 MM170 MM+ MMX Picromite ArmiteL4
Armite F4 ArmiteH7 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