GRAPHICS
========

Multiple vocabularies are available to present graphics in different
forms and resolutions.

A selection of examples are given in the DEMO-GRAPHICS.FS file, to
view their results execute

    INCLUDE DEMO-GRAPHICS.FS
    DEMO


Common Definitions
------------------

The base GRAPHICS vocabulary defines words that can be used
independently or by any of the other vocabularies. To use them
directly first execute

    INCLUDE GRAPHICS.FS


Definitions
-----------

The following constants can be used wherever col8 or col16 is given
below

    BLACK
    WHITE
    RED
    CYAN
    PURPLE
    GREEN
    BLUE
    YELLOW

The following constants can be used wherever col16 is given below

    ORANGE
    LT-ORANGE
    PINK
    LT-CYAN
    LT-PURPLE
    LT-GREEN
    LT-BLUE
    LT-YELLOW


BORDER   ( col8 -- )

    Set the border colour.

BACKGROUND   ( col16 -- )

    Set the background colour.

AUX   ( col16 -- )

    Set the auxiliary colour.

FOREGROUND   ( col8 -- )

    Set the foreground colour.

INVERT   ( tf -- )

    Set the global reverse video flag.

SCREENBASE@   ( -- addr )

    Get the start address of the screen.

CHARBASE@   ( -- addr )

    Get the start address of the character generator.

COLOURBASE@   ( -- addr )

    Get the start address of the colour attributes.

CELLH@   ( -- cellh )

    Get the height of each screen cell in pixels (8 or 16).

XMAX@   ( -- maxx )

    Get the number of horizontal screen cells.

YMAX@   ( -- maxy )

    Get the number of vertical screen cells.

XPOS@   ( -- posx )

    Get the horizontal offset of the left side of the screen.

YPOS@   ( -- posy )

    Get the vertical offset of the top of the screen.

SCREENBASE!   ( addr -- )

    Set the start address of the screen.

CHARBASE!   ( addr -- )

    Set the start address of the character generator.

CELLH!   ( cellh -- )

    Set the height of each screen cell in pixels (8 or 16).

XMAX!   ( maxx -- )

    Set the number of horizontal screen cells.

YMAX!   ( maxy -- )

    Set the number of vertical screen cells.

XPOS!   ( posx -- )

    Set the horizontal offset of the left side of the screen.

YPOS!   ( posy -- )

    Set the vertical offset of the top of the screen.

RESET-SCREEN   ( -- )

    Restore VIC register values to defaults.


User-defined Graphics
---------------------

The GRAPHICS USR vocabulary can be used to redefine one or more
characters to contain a user-selected bit pattern.

The vocabulary is made available by first executing

    INCLUDE GFX-USR.FS


Definitions
-----------

REDEFSET   ( addr -- )

    Copy a character set from ROM to memory so it may be
    modified. Constants are defined for the set with capital letters
    and graphics (CHARSET1) and the set with upper and lower case
    letters (CHARSET2).

REDEF   ( addr ch count -- )

    Copy the bit patterns starting at addr to the location that
    defines character ch. count is the number of characters to
    redefine. Each character requires 8 bytes.

REDEFSET2   ( addr -- )

    Copy a character set from ROM to memory so it may be
    modified, converting it to double height.

REDEF2   ( addr ch count -- )

    Copy the bit patterns starting at addr to the location that
    defines character ch. count is the number of characters to
    redefine. Each character requires 16 bytes.

CLEAR   ( -- )

    Clear the screen.


Low-resolution Graphics
-----------------------

The GRAPHICS LORES vocabulary provides words that allow plotting
points on a 44 x 46 pixel screen.

The vocabulary is made available by first executing

    INCLUDE GFX-LORES.FS


Definitions
-----------

PLOT   ( x y -- )

    Set the point at the co-ordinates X, Y to the foreground colour.

UNPLOT   ( x y -- )

    Set the point at the co-ordinates X, Y to the background colour.

XPLOT   ( x y -- )

    Set the point at the co-ordinates X, Y to the opposite of
    foreground or background colour according to its present value.

FGSET   ( col8 x y -- )

    Set the foreground colour of the cell holding the point at the
    co-ordinates X, Y.

CLEAR   ( -- )

    Clear the screen and set the foreground colour of all cells.

SSAVE   ( addr count -- )

    Save the contents of the screen and colour attributes to a file
    on the default device.

SLOAD   ( addr count -- )

    Load the contents of the screen and colour attributes from a file
    on the default device.


High-resolution Graphics
------------------------

The GRAPHICS HIRES vocabulary provides words that allow plotting
points on a 160 x 192 pixel screen.

The vocabulary is made available by first executing

    INCLUDE GFX-HIRES.FS


Definitions
-----------

INIT   ( -- )

    Set VIC registers for graphics.

PLOT   ( x y -- )

    Set the point at the co-ordinates X, Y to the foreground colour.

UNPLOT   ( x y -- )

    Set the point at the co-ordinates X, Y to the background colour.

XPLOT   ( x y -- )

    Set the point at the co-ordinates X, Y to the opposite of
    foreground or background colour according to its present value.

FGSET   ( col8 x y -- )

    Set the foreground colour of the cell holding the point at the
    co-ordinates X, Y.

CLEAR   ( -- )

    Clear the screen and set the foreground colour of all cells.

MGLOAD   ( addr count -- )
    Load a MICROGRAFIK image from the default device.


Multi-colour Graphics
---------------------

The GRAPHICS MULTICOL vocabulary provides words that allow plotting
multicolour points on a 80 x 192 pixel screen.

The vocabulary is made available by first executing

    INCLUDE GFX-MULTICOL.FS


Definitions
-----------

INIT   ( -- )

    Set VIC registers for graphics.

PLOT   ( x y -- )

    Set the point at the co-ordinates X, Y to the foreground colour.

BRDPLOT   ( x y -- )

    Set the point at the co-ordinates X, Y to the border colour.

AUXPLOT   ( x y -- )

    Set the point at the co-ordinates X, Y to the auxiliary colour.

BGPLOT   ( x y -- )

    Set the point at the co-ordinates X, Y to the background colour.

FGSET   ( col8 x y -- )

    Set the foreground colour of the cell holding the point at the
    co-ordinates X, Y.

CLEAR   ( -- )

    Clear the screen and set the foreground colour of all cells.
