Andrew Kesterson
cdaefcc941
Some checks failed
akbasic CI Build / cmake_build (push) Successful in 3m0s
akbasic CI Build / sanitizers (push) Successful in 3m45s
akbasic CI Build / coverage (push) Failing after 3m22s
akbasic CI Build / akgl_build (push) Failing after 21s
akbasic CI Build / mutation_test (push) Successful in 11m26s
Organised the way the C128 Programmer's Reference Guide is: the language first, then each hardware area, then the reference sections. One markdown file per chapter. The verb and function references are generated from the interpreter's own dispatch table, with an assertion that every row is described, so they cannot drift out of step with what the program accepts. 98 verbs and 30 functions. Every example was run before it was written down, which caught three claims that were wrong: a whole FOR loop on one line prints nothing rather than looping once, MID and INSTR count from zero where a C128 counts from one, and a multi-line DEF returns a value the caller has to assign away. Chapter 13 is the list a BASIC 7.0 programmer needs -- roughly sixty documented differences, including the two known FOR defects and the fact that drawing does not survive a frame. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
119 lines
3.1 KiB
Markdown
119 lines
3.1 KiB
Markdown
# 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.
|