akbasic/docs/06-graphics.md

# 6. Graphics

Everything in this chapter needs the SDL build and a graphics device. Without one each
verb refuses by name:

```
? 10 : RUNTIME ERROR DRAW needs a graphics device and this runtime has none
```

## The coordinate space

Drawing coordinates are **320 by 200**, with (0, 0) at the top left — BASIC 7.0's
hi-res screen. That is true whatever size the host's window is; stretching to fit is
the host's business, not the program's. `SCALE` maps a different range onto the same
screen.

## Colour

`COLOR` binds a *source* to a palette index, and the drawing verbs name the source
rather than the colour:

```
10 COLOR 1, 3
20 DRAW 1, 10, 20
```

Sources are numbered 0 to 6; palette indices are 1 to 16, as on a C128. That
indirection is BASIC 7.0's, and it is why every drawing verb's first argument is a
small number that is not a colour.

## The verbs

### GRAPHIC

`GRAPHIC mode` chooses a screen mode; `GRAPHIC CLR` clears it. Mode 0 is text and
refuses to draw.

### DRAW

```
10 DRAW 1, 10, 20
20 DRAW 1, 0, 0 TO 100, 100 TO 200, 0
```

One coordinate pair plots a point. Two or more, separated by `TO`, draw a polyline. A
bare `DRAW 1` plots wherever `LOCATE` left the pixel cursor.

### BOX

```
10 BOX 1, 10, 10, 40, 40
```

Corners, and an optional rotation angle. An unrotated `BOX` outlines rather than fills.

### CIRCLE

```
10 CIRCLE 1, 160, 100, 50, 30
```

Source, centre, then the two radii — so it draws ellipses. Further arguments give a
start angle, an end angle, a rotation and the degree increment, which is what makes it
an arc or a polygon.

### PAINT

```
10 PAINT 1, 160, 100
```

Flood-fills the region containing a point. If the region is too large for the fill's
own working space it stops and reports rather than leaving a half-painted screen with
no explanation.

### LOCATE

Moves the pixel cursor, which is where a bare `DRAW` plots and where a `BOX` with two
coordinates finishes.

### SCALE

```
10 SCALE 1, 1023, 1023
```

Turns on user coordinates and gives their maxima. With it on, your coordinates are
mapped onto the 320 by 200 screen. `SCALE 0` turns it off.

### WIDTH

`WIDTH 1` or `WIDTH 2` sets how thick a drawn line is. A thick line is drawn as
parallel passes; see Chapter 13.

## Saving and stamping regions

`SSHAPE` copies a rectangle off the screen and `GSHAPE` stamps it back:

```
10 BOX 1, 0, 0, 20, 20
20 SSHAPE A$, 0, 0, 20, 20
30 GSHAPE A$, 100, 100
```

**`A$` holds a handle, not the pixels.** On a C128 the string holds the bitmap, so a
program could save it to disk or take its `LEN`. Here a string is a fixed 255 bytes and
the region is a device surface, so what goes in the string is a reference to it —
`SHAPE:0`. You can pass it to `GSHAPE` and to `SPRSAV`, which is everything BASIC ever
does with one, but you cannot store it or measure it.

## What is not here

`FILTER` parses and then refuses: there is no filter stage to configure. See Chapter 7.

The graphics verbs draw straight to the renderer rather than into a display list, so
anything drawn is overwritten by the text layer on the next frame. A program that wants
its drawing to persist has to redraw it. This is recorded as a defect rather than a
design; see Chapter 13.