Render a saved image on the bitmap screen.

 

The image is typically generated by either SSHAPE or SPRSAV, and is thus typically a string variable.  However BASIC will accept any string.  If seems to do nothing if the string is less than 5 characters.  As you might expect, if the string wasn't generated properly, you get a bunch of garbage on the screen!  All I can say is the string consists of raw pixel data, no color data, and is terminated by a "footer" that specifies the width and height of the image.  If image is not a string, a TYPE MISMATCH ERROR is generated.

 

Following the image is an optional point of the bitmap to begin rendering the image (starting at the top-left pixel).  The default point is the pixel cursor.  A specified point will be effected by SCALE if it is active.  The resulting value may be off-screen, but is acceptable as long as it is legal as shown above.

 

A point specified as a polar coordinate will always be relative to the pixel cursor.  A point specified in rectangular form will normally be an absolute coordinate (independ of the pixel cursor), but using a + or - in front of the xVal or yVal will make that ordinate relative to the pixel cursor.  The x and y ordinates are processed independantly; either, neither, or both ordinates of the rectangular coordinate may be in relative form (whichever use a leading + or -).  Note these must be literal + and - characters in the command/statement.  So if you have a variable X with a negative value (like -10) then it will be used an absolute coordinate unless you preced it with + or - sign.  You normally wouldn't put a - sign unless you want to reverse the direction of the variable.  So, for this example, use +X for a relative ordinate.  As opposed to a variable, if you want to enter a literal negative value (for an absolute ordinate), you must enclose it in parentheses; otherwise it would interpreted as a relative ordinate.  Sorry if that is confusing!  If so, you need to play with relative and absolute coordinates to see clearly what I mean.

 

The image may be drawn either partially or completely off-screen.  Going off-screen does not generate an error.  Portions of the image that are rendered on-screen will done according to the renderMode which defaults to zero.  The zero mode simply stores the pixels saved in the string back to bitmap; this completely over-writes any pixels currently on the bitmap.  A renderMode of 1 does essentially the same thing, but each pixel read from the image is inverted before being rendered on the bitmap.  Note the bit-values of the pixel are inverted; not the actual color of the pixel.

 

The renderModes 2 to 4 operate differently (than 0 and 1).  These modes combine the bits of the image's pixel with the current bitmap's pixel by using a bit-wise boolean operator: OR for mode 2, AND for mode 3, and XOR for 4.  Using GSHAPE twice, both times with the XOR mode and at the same point, you can both draw and erase the same image on the bitmap, so you could use it for slow animation.  The OR mode will act similar to a transparency; anywhere the image has a background color, the original bitmap's pixels will show through.  The AND mode is kind of like an inverted transparency; anywhere the image has a non-background color, the original bitmap's pixels will show through (and image pixels that are background will output render the background color).

 

Perhaps worse, the image only contains bitmap pixels.  The colors those pixels had when the image was saved are nowhere to be found.  When using GSHAPE, the values currently assigned to the various colorSources are used instead (see COLOR).

 

Any floating-point numbers will first be converted to integers (see INT).  If any numeric 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.

 

 

Example of optional point:

LOCATE 60,60 : REM set pixel cursor at 60,60

READY.
GSHAPE A$    : REM render image A$ with its top-left pixel at 60,60

 

Example of relative rectangular and polar coordinate:

LOCATE 60,60: GSHAPE A$, +10,-10 : REM render top-left at 70,50 = 60+10, 60-10

READY.
GSHAPE A$, (+10),(-10) : REM render top-left at 10,-10

READY.
LOCATE 60,60: GSHAPE A$, 20; 30 : REM render at 70,43 = 60+20*SIN(30), 60-20*COS(30)

 

Example of renderModes:

GSHAPE A$, ,, 1     : REM try to use default (pixel cursor) in reverse mode
?SYNTAX ERROR

READY.
GSHAPE A$, +0,+0, 1 : REM render at pixel cursor in reverse mode

READY.
GSHAPE A$, 20,20, 4   : REM render top-left at 20,20 using XOR mode

 

BOX, CHAR, PAINT 

 

COLOR, GRAPHIC, LOCATE, SCALE, SSHAPE