Several words are available to use the "map" area of the screen as a graphics area. This is fixed in size to 256x64 pixels, and is only available on expanded Z88s. Use the EXP? word to check for a suitable Z88 before using these words; they will just be ignored on unexpanded machines.

The graphics area must be initialised before use, using OPENMAP, which requires a window number on the stack. Additionally, you should make sure that any text windows you are using are defined so that they do not overlap this area, which is situated at the right of the display. For example, use the following phrases:

    1 0 48 8  1 OPENWINDOW

Note that if you are using graphics, OPENMAP must be used every time a RC_DRAW error occurs (and, of course, you should redraw the graphics present in the area).

Basic facilities

The coordinate system used runs from x=0 at the left side to x=255 at the right side, and from y=0 at the bottom to y=63 at the top.

In all the graphics words it is perfectly acceptable to give coordinates outside these limits. By default, pixels out of range are simply ignored. This means, for example, that a circle drawn with a centre of (0,0) will just appear as a quarter circle in the bottom left corner of the map.

An alternative treatment available is to force all out-of-range pixels to the nearest "edge" of the map and plot them there. In the circle example, this would be drawn like a piece of cake, with the left and bottom sides drawn as lines at the edge of the screen.

The most basic graphics facilities generally work with a single point at a time, and are listed here:

GBOUND ( flag -- )
If flag is true, this switches the graphics system to force all out-of-range pixels to the edge of the map area. If flag is false, out-of-range pixels are ignored (the default).
GPAGE ( -- )
Clear the graphics area.
GSET ( x y -- )
Set the point with coordinates (x,y).
GCLR ( x y -- )
Clear the point with coordinates (x,y).
GINV ( x y -- )
Invert the point with coordinates (x,y).
GSET? ( x y -- flag )
Give a true flag if the point with coordinates (x,y) is set.
GMOVE ( x y -- )
Change the "last point" coordinates to (x,y), without affecting the point.
GPOS? ( -- x y )
Get the coordinates of the last point referred to by any other graphics word.

Drawing facilities

These words offer further facilities for creating graphics:

GLINE ( dx dy -- )
Draw a straight line from the last point, across dx pixels to the right, and up dy pixels. Either dx or dy can be negative, producing lines going left and down.
GLINETO ( x y -- )
An alternative to GLINE, with this word you specify the destination coordinates of the line, which is drawn to there from the last point.
GBOX ( dx dy -- )
Draw a rectangle or square, with one corner at the last point, and the other corner at a point dx pixels to the right, and dy pixels up. Again, dx or dy may be negative.
GELLIPSE ( x y w h -- )
Draws an ellipse with a centre at (x,y) and horizontal radius w, vertical radius h.
GCIRCLE ( x y r -- )
Draws a circle with a centre at (x,y) and a radius of r.

Filling areas with textures

A fill/shade feature is available, which allows you to shade any area with your own design or one of the two supplied shading patterns. Each of these routines take a point within the area to be shaded.

The algorithm used is very simple, so it is fast but will not fill complicated shapes in a single go. The best position to specify for the point is where the shape is tallest.

GFILL ( x y -- )
Fills an area in solid black.
GSHADE ( x y -- )
Fills an area in grey.
GPATTERN ( x y c-addr -- )
Fills an area using a user-defined pattern held at c-addr.

You can specify your own shades by CREATEing a word and compiling 8 bytes of shade data after it; each byte represents one line of the shade pattern (the first byte is for the top line). For example, an interesting shade is:

    CREATE MYSHADE 204 C, 0 C, 51 C, 0 C, 170 C, 85 C, 170 C, 0 C,

More about CamelForth

Back to the Z88 home page