Commodore‎ > ‎BASIC‎ > ‎Keywords‎ > ‎

SPRSAV

Keyword
Abbreviation Token (hex) Version(s) Classification
SPRSAV SPR{Shift+S} FE 16 7.0 Command and Statement

Syntax  
SPRSAV { { sourceSprite , { saveSprite image2 } } | { image1 , { saveSprite | image2 } } }
 
Parameters Type Legal Value(s) Default Value Note(s)
sourceSprite Unsigned Byte
1 to 8
 
saveSprite Unsigned Byte 1 to 8  
image1 String  67 bytes*   *should be with SPRSAV or SSHAPE
image2 String variable      Must be a variable, not a literal or expression 
 
 
Purpose  
Data initialization / State management; Copy a sprite definition to a string or another sprite, or initialize a sprite definition from a string.
 
 
Remarks  
SPRSAV provides three ways to read/write (load/store) a SPRITE's image definition:
  1. SPRSAV sourceSprite, saveSprite will copy the image of sourceSprite into saveSprite
  2. SPRSAV sourceSprite, image2 will copy a SPRITE's image into a string (compatible with GSHAPE)
  3. SPRSAV image1, saveSprite will copy an image string (presumably made with SPRSAV or SSHAPE) into a SPRITE
SPRSAV also allows a fourth form: SPRSAV image1, image2.  However, this form does not (neccessarily) copy sprite data; it is equivalant to LET.
 
The third form is often used in a program to initialize the image of a sprite (an alternative is to BLOAD sprite image(s)).  The second form may occassionaly be used to create a "stamp" that may be drawn repeatedly on a bitmap.  The first form is rarely used, except in direct mode (program design).  The fourth form is just silly.
 
The first form works flawlessly assuming the Syntax is correct and the sourceSprite and saveSprite are both the same "color type" (both high-resolution or both multi-color).
 
The second form creates (or replaces) a string which holds an image of the sprite.  This may be used in subsequent SPRSAV statements, or with GSHAPE to "stamp" the bitmap with the image.  The resulting image string will be 67 bytes which consists of 63 bytes for the sprite image itself, plus a 4-byte "footer" used by GSHAPE (describes the dimensions of the image).
 
For the third form, image1 is a string which should have been created with SPRSAV or SSHAPE.  If not, strange images will result (but there will be no error if the Syntax is correct).  An image created with SSHAPE should always be 21 pixels tall and either 24 or 12 pixels wide, depending if you want a high-resolution or multi-color SPRITE, respectively.  The SSHAPE image should have come from high-resolution or multi-color bitmap respectively.  If not, the SPRITE will receive a strange image.
 
In forms 2 and 4, image2 must be a string variable (not a literal or expression), otherwise SYNTAX ERROR will occur.
 
If a parameter is omitted or is invalid, or if any extra parameter(s) are given, then SYNTAX ERROR is generated.  If image1 or image2 (when present) is not a string, or sourceSprite or saveSprite (when present) is not numeric, then TYPE MISMATCH ERROR occurs.  The values for sourceSprite and/or saveSprite may be manually converted from string to numeric with VAL.  Floating-point values of sourceSprite and/or saveSprite are automatically converted with INT.  If any parameter is not a Legal Value (see above) an ILLEGAL QUANTITY ERROR is generated.
 
Note that a SPRITE has more properties that define it besides its image (see SPRITE).  SPRSAV does not copy any sprite characteristics other than the image pixels.  In particular, no color information is copied.
 
Once you haved saved an image, it is easy to make copies in memory with simple variable assignments (see LET), although there is seldom any reason to do this.
 
Examples:
SPRSAV 1,2    :REM copy image of SPRITE 1 to SPRITE 2

READY.
SPRSAV 1,A$   :REM copy image of SPRITE 1 to string A$

READY.
SPRSAV 1,"?"  :REM copy image of SPRITE 1 to string "?"

?SYNTAX ERROR
READY.
SPRSAV "!",2  :REM copy 'image' "!" to SPRITE 2 (results in garbage)

READY.
SPRSAV A$,2   :REM copy image A$ (saved SPRITE 1) to SPRITE 2

READY.
SPRSAV A$,B$  :REM same as LET B$ = A$

READY.
SPRSAV "!",C$ :REM same as LET C$ = "!"

READY.
PRINT C$      :REM proof
!

READY.
If you try those examples, then afterwards you can use GSHAPE A$,x,y to stamp the bitmap with an image of sprite 1.
 
Compare With  
 
See Also  

© H2Obsession, 2014
Comments