Save a rectangular region of the bitmap screen to RAM.

 

The image is a string variable in which to save a portion of the bitmap.  Attempting to omit image, or use a literal value (numeric or string),  will generate SYNTAX ERROR.  Attempting to use a numeric variable will generate a TYPE MISMATCH ERROR.  Because a BASIC string is limited to 255 bytes, the area of the bitmap you can save is limited.  To determine the number of bytes (length of string) that will be needed, use this formula:

 

Bytes needed = INT((Width + bits_per_pixel - 1) / 4 / bits_per_pixel) * Height + 4

 

where bits_per_pixel is 1 for high-resolution or 2 for multi-color bitmap mode.  You might (correctly) infer from that formula that only the bitmap pixels are saved, the color information is not!  Anyway, using the full screen width, the biggest image you can save is 6 rasters tall.  Using the full screen height, the biggest image you can save is 8 pixels wide (high-res bitmap) or 4 pixels wide (multi-color).

 

The area of the bitmap that is to be saved as an image is specified by two corners of a rectangle.  Each corner is specified by a point.  The first point (following the image variable) is required.  The second point is optional; it defaults to the pixel cursor (the last point calculated in the previous bitmap command).  Any specified points will be effected by SCALE if it is active.  The resulting points may be off-screen, but no error occurs as long as they are legal values as shown above.  These off-screen regions are saved in the image as 0 bits (representing the background color).

 

The region specified by the corner points is inclusive.  So for example, SSHAPE A$, 0,0, 7,7 will save an area 8 pixels wide and 8 pixels tall.

 

For numeric parameters (all but image), any floating-point numbers will first be converted to integers (see INT).  If any value is out-of-range (see above) an ILLEGAL QUANTITY ERROR is generated.  If no bitmap has been setup (see GRAPHIC), a NO GRAPHICS AREA is generated.

 

Once you haved saved an image, with SSHAPE (or SPRSAV), it is easy to make copies in memory with simple variable assignments (see LET) but there is seldom any reason to do this!

 

For experimenting, note the syntax of this command/statement is almost identical to BOX, so you can use the BOX with the same parameters except specify a colorSource instead of the image variable.  This will draw a rectangle around the region that would be saved.  Note the pixels under the BOX boundry would also be saved, not just the pixels inside.

 

Example of omitting optional "Corner B":

LOCATE 60,60: SSHAPE A$ ,100,100 : REM save region (60,60) to (100,100)

 

Example of relative rectangular and polar coordinate:

LOCATE 60,60: SSHAPE A$, +10,-10 : REM save region (60,60) to (70,50)

READY.
LOCATE 60,60: SSHAPE A$, 20; 30  : REM save region (60,60) to (70,43)

 

Typical example (both corners):

SSHAPE A$, ,, 10,10 :REM try omit Coordinate A

?SYNTAX ERROR
READY.                    :REM this works, but you could swap corners and omit last
SSHAPE A$, +0,+0, 10,10   :REM save pixel cursor + (0,0) to (10,10)

READY.
SSHAPE A$, 100,100, 60,60 :REM typical (absolute points) from (100,100) to (60,60)

 

BOX, BSAVE, LET, SPRSAV

 

GRAPHIC, GSHAPE, LOCATE, SCALE