_     _
          __ _ _ __ __ _ _ __ | |__ (_) ___ __ _
         / _` | '__/ _` | '_ \| '_ \| |/ __/ _` |
        | (_| | | | (_| | |_) | | | | | (_| (_| |
         \__, |_|  \__,_| .__/|_| |_|_|\___\__,_|
         |___/          |_|               Level 0

# Overview

Graphica is an extension of the ilo computer and a corresponding
vocabulary for Konilo. It adds a visual bitmap display and words
for drawing.

It is expected that development of Graphica will result in
several levels of increasing complexity. This document describes
Level 0, the core, minimal functionality.

# Concepts

Graphica provides a visual display consisting of a pixel grid.

Points are use to reference pixels on the display. These contain
a row (x) and column (y) pair and are packed into a single value
on the stack.

Points are created or unpacked using these functions:

  :g:point   (xy-p) [ #16 shift-left ] dip or ;
  :g:unpoint (p-xy) [ #16 shift-right ] [ #65535 and ] bi ;

The display memory is separate from the addressable ilo memory;
all access to it must done via the Graphica device.

# Limits

In Level 0, several limitations exist:

- 1 bit per pixel (black & white) only
- Display memory is fully separate from ilo's memory
- All display operations must run through the Graphica device

# The `g:` Vocabulary

Graphica's words are assigned to the `g:` namespace. You can
load this with either:

  * g

Or:

  '(graphica) needs

+----------------+--------+------------------------------------+
| Word           | Stack  | Description                        |
+================+========+====================================+
| g:query/level  |    -n  | Return the Graphica level          |
| g:query/colors |    -n  | Return the number of colors avail. |
| g:query/font   |    -hw | Return the font height/width       |
| g:query/screen |    -hw | Return the display height/width    |
| g:set-color    |   n-   | Set the current color for drawing  |
| g:point        |  xy-p  | Create a point                     |
| g:unpoint      |   p-xy | Unpack a point                     |
| g:pixel        |   p-   | Draw the pixel at point P          |
| g:get-pixel    |   p-n  | Get the color of the pixel at P    |
| g:hline        |  pw-   | Draw a horizontal line from P      |
| g:vline        |  ph-   | Draw a vertical line from P        |
| g:line         |  pp-   | Draw a line between the points     |
| g:rect         |  pp-   | Draw a rectangle between the points|
| g:circle       |  pr-   | Draw a circle around P             |
| g:triangle     | ppp-   | Draw a triangle between the points |
+----------------+--------+------------------------------------+

# Implementation

The Graphica extension is assigned to device id #12. Pass the
required parameters, operation id, and device number to the
`io` instruction.

Level 0 requires device 12 to support the following functions:

+------+-------+-----------+-----------------------------------+
| ID # | Level | Stack Use | Action                            |
+======+=======+===========+===================================+
| 0    | 0     |    -n     | return graphica level             |
| 1    | 0     |    -n     | return num of supported colors    |
| 2    | 0     |    -hw    | return font height, width         |
| 3    | 0     |    -hw    | return display height, width      |
| 4    | 0     |   n-      | set the pixel color for drawing   |
| 5    | 0     |   p-      | draw a pixel at p                 |
| 6    | 0     |   p-n     | return the color of pixel at p    |
+------+-------+-----------+-----------------------------------+

# Future

Level 1 will add device support for significantly faster drawing
operations. We expect to also provide a build of ilo with color
palette support with it as well. Beyond this, we have some plans
to explore adding sprites, scenes, and eventually some support
for 3D.

================================================================