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

GSHAPE

Keyword
Abbreviation Token (hex) Version(s) Classification
GSHAPE G{Shift+S} E3 3.5, 7.0 Command and Statement
RESUME RES{Shift+U}  E3  4.7  Command and Statement

Syntax  
GSHAPE image [ , { [ + | - ] xVal [ , [ + | - ] yVal ] distance ; angle } [ , renderMode ] ]
 
Parameters Type Legal Value(s) Default Value Note(s)
image String
0 to 255 characters
Should be a variable created with SSHAPE or SPRSAV
xVal Integer*  -32768 to +32767  pixel cursor X  rectangular X ordinate or offset for a point
yVal  Integer*  -32768 to +32767  pixel cursor Y rectangular Y ordinate or offset for a point 
distance Integer*  -32768 to +32767  polar distance for a point
angle Unsigned Integer  0 to 65535  undefined polar angle for a point
renderMode Integer
  1. Store
  2. Invert bits and Store
  3. OR bits
  4. AND bits
  5. XOR bits
0
Modes 0 and 1 overwrite exisiting bitmap pixels
Modes 2 to 3 merge image with existing bitmap pixels
*Due to a bug in the original C128 ROMs (start-up message says (c)1985), only positive/unsigned values of 0 to 65535 may be used.
 
 
Purpose  
Render a saved image on the bitmap screen.

 
 
Remarks  
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.
 
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).
 
Note in order to specify a renderMode, you must specify a point (otherwise the point is optional).  To use the default point anyway, just specify a relative offset of +0 for both xVal and yVal (see example).
 
Unfortunately there is no way to clip or scale the image or reverse the horizontal or vertical direction (i.e., "no mirror X nor mirror Y").  Note if SCALE is in effect, it only affects the (specified, non-default) starting point, but not the size of the rendered image.
 
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.
 
I believe GSHAPE is short for "Graph Shape", although I have seen no offical definition.
 
Example of optional 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
 
Compare With  
 
See Also  

© H2Obsession, 2014
Comments