Andrew Kesterson
5709dc160c
A drawing lasted exactly one frame. The verbs are immediate, they went to the back buffer, SDL double-buffers and the frontend never clears -- so the only way to keep a picture was to capture it with `SSHAPE` and install it as a sprite, which is what `examples/breakout/sprites/breakout.bas` spends two of its eight sprites doing. That was TODO.md section 9 item 9. The drawing verbs now render into a layer texture the frame composites under the text and the sprites. Draw once; it is there on every frame after. **Bracketed around the step phase, not around each verb.** One pair of `SDL_SetRenderTarget` calls a frame instead of one per `DRAW`, and it is also what makes `SSHAPE` read back what the program has just drawn rather than whatever the last frame left. **The layer is transparent where nothing was drawn.** It covers the whole window and composites underneath, so an opaque one would black out the frame the moment a program issued a single `DRAW`. And a fresh SDL target texture's contents are undefined, so it is cleared on creation -- skipping that puts uninitialised memory under the first frame's text and looks like a driver bug rather than a missing memset. **The line editor forced a wrinkle worth naming.** `akbasic_frontend_akgl_pump()` is called from two places with different answers to "is a render target current": the frame loop calls it between steps, and the sink's editor calls it from *inside* a step, borrowing a frame while it waits for a typed line. SDL refuses to present while a target is current, so the pump ends the layer, presents, and puts it back only if it was the one that ended it. `akgl_frontend` caught this -- it drives a REPL session, and it failed with "You can't present on a render target" the first time the brackets went in. This does not make a drawing *visible* on its own. The text layer still repaints every row it owns, opaque, every frame, and by default it owns the whole window; `WINDOW` shrinks it and that half was already fixed. The two together are what a picture needed, and the tests assert both -- a pixel still there a frame later with nothing redrawn, and a pixel below a shrunk text area surviving the text repaint. The second assertion wipes to a non-black colour first, because against black it could not tell a transparent layer from an opaque one. The tests found two of their own bugs on the way: `stop_runtime()` was not tearing the graphics backend down, so re-initialising it dropped a live texture on the floor; and a first draft called `begin()` before `start_runtime()`, which re-inits the backend, so the assertion read back off an orphaned render target and passed while proving nothing. Chapters 6 and 13 stop saying a drawing has to be redrawn every frame, because it does not. The batch-boundary tear stays documented -- it bites an `SSHAPE` capture, which matters much less now that capturing is not the only way to keep a picture. Both games still run clean. 111 with akgl, 110 without. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EwxGB6TdoVvZ11KQQME9cL
8.7 KiB
6. Graphics
Everything in this chapter needs the SDL build and a graphics device. Without one each verb refuses by name:
10 DRAW 1, 0, 0 TO 100, 100
? 10 : RUNTIME ERROR DRAW needs a graphics device and this runtime has none
The coordinate space
A drawing coordinate is a pixel of the host's window, with (0, 0) at the top left.
On the standalone interpreter's 800 by 600 window, DRAW 1, 799, 599 lands on the
bottom-right pixel and everything in between is reachable. A game embedding the
interpreter gets whatever size its own renderer is.
RGR is how a program finds out:
10 PRINT "THE SCREEN IS"
20 PRINT RGR(1)
30 PRINT "BY"
40 PRINT RGR(2)
50 DRAW 1, 0, 0 TO RGR(1) - 1, RGR(2) - 1
Subtracting one is not a wart, it is the last pixel: a window RGR(1) wide has
columns 0 through RGR(1) - 1.
A C128 listing assumes 320 by 200 and will draw in the top-left corner. Give it the whole window by naming the space it was written for:
10 SCALE 1, 319, 199
20 BOX 1, 0, 0, 319, 199
That box is now the border of the window whatever size the window is. When no device answers the size question at all, 320 by 200 is what the interpreter assumes — the space a C128 listing was written for is the right thing to fall back to.
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.
Every picture in this chapter is generated by running the listing above it; see
MAINTENANCE.md if you are editing one.
DRAW
10 COLOR 1, 8
20 DRAW 1, 20, 180 TO 90, 40 TO 160, 150 TO 230, 20 TO 300, 120
30 COLOR 2, 6
40 DRAW 2, 20, 190 TO 300, 190
50 LOCATE 160, 100
60 COLOR 3, 3
70 DRAW 3
One coordinate pair plots a point. Two or more, separated by TO, draw a polyline. A
bare DRAW 3 — the last line above, and the single red pixel in the middle of the
picture — plots wherever LOCATE left the pixel cursor.
BOX
10 COLOR 1, 8
20 BOX 1, 20, 30, 130, 140
30 COLOR 2, 6
40 BOX 2, 180, 30, 290, 140, 30
50 COLOR 3, 3
60 LOCATE 300, 190
70 BOX 3, 20, 160
Corners, and an optional rotation angle — the green box is the same box turned 30 degrees about its own centre. Two coordinates instead of four take the other corner from the pixel cursor, which is the red box.
BOX always outlines; it cannot fill. BASIC 7.0 selects fill with a seventh
argument and that is not implemented here — see Chapter 13. PAINT is the fill you
have.
CIRCLE
10 COLOR 1, 8
20 CIRCLE 1, 80, 70, 60, 60
30 COLOR 2, 6
40 CIRCLE 2, 230, 70, 75, 45
50 COLOR 3, 3
60 CIRCLE 3, 160, 140, 130, 50, 90, 270
Source, centre, then the two radii — equal radii give a circle and unequal ones an
ellipse. Two further arguments are a start and an end angle, which is what makes the
red arc: 90 to 270 is the bottom half, because angles here are degrees clockwise from
straight up, the same convention MOVSPR uses. Beyond those come a rotation and the
degree increment, and a large increment is what turns a circle into a polygon.
PAINT
10 COLOR 1, 8
20 CIRCLE 1, 100, 100, 70, 70
30 BOX 1, 180, 50, 290, 150
40 COLOR 2, 6
50 PAINT 2, 100, 100
60 COLOR 3, 3
70 PAINT 3, 230, 100
Flood-fills the region containing a point, stopping at whatever is already drawn — so the outline you fill inside can come from any verb. 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 COLOR 1, 3
20 BOX 1, 0, 0, 319, 199
30 SCALE 1, 319, 199
40 COLOR 2, 6
50 BOX 2, 0, 0, 319, 199
60 DRAW 2, 0, 0 TO 319, 199
That picture is 640 by 400, and both boxes name the same four numbers. The red one is
drawn with SCALE off, so its coordinates are pixels and it covers exactly the
top-left 320 by 200 of the window — which is what a C128 listing does here. The green
one is drawn after SCALE 1, 319, 199 and fills the window, and the diagonal confirms
that 319, 199 reaches the last pixel rather than stopping one short of it.
Turns on user coordinates and gives their maxima. With it on, your coordinates are
mapped onto the drawing surface: 0 is the first pixel and the maximum you gave is the
last one, so DRAW 1, 1023, 1023 above reaches the bottom-right corner rather than
missing it by a pixel. SCALE 1 on its own uses 7.0's 1023 by 1023. SCALE 0 turns
it off and coordinates go back to being window pixels.
RGR
RGR(0) is the current GRAPHIC mode. RGR(1) and RGR(2) are the drawing
surface's width and height in pixels — those two are ours rather than 7.0's, and they
are what a program needs to use a window whose size it did not choose. They
refuse when there is no graphics device, unlike RGR(0), which is a mode this
interpreter recorded rather than a screen it has to go and measure.
RGR(3) and RGR(4) are a character cell's width and height, also ours. They come
from the text device rather than the graphics one — a character grid belongs to the
sink — so they refuse by naming that instead. Between them and
RWINDOW, which gives the current text window in columns
and rows, a program can place a character and a sprite at the same spot without
hardcoding a number measured against whatever font the host loaded:
10 CW# = RGR(3)
20 CH# = RGR(4)
30 COL# = 12
40 ROW# = 3
50 CHAR 1, COL#, ROW#, "X"
60 MOVSPR 1, COL# * CW#, ROW# * CH#
RWINDOW follows a WINDOW call, because it reports the window. RGR(3) and RGR(4)
do not, because windowing does not change how big a character is.
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 COLOR 1, 8
20 CIRCLE 1, 40, 40, 30, 30
30 COLOR 2, 6
40 PAINT 2, 40, 40
50 SSHAPE A$, 8, 8, 72, 72
60 GSHAPE A$, 120, 20
70 GSHAPE A$, 200, 60
80 GSHAPE A$, 120, 120
One disc drawn, captured, and stamped three times.
A string array works: SSHAPE SH$(2), ... writes into element 2 and GSHAPE SH$(2)
stamps what element 2 names, so a program can keep a set of shapes in one array.
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.
A drawing stays. The verbs render into a layer the frame composites underneath the text and the sprites, so a program draws its picture once and it is there on every frame after. It does not have to redraw it, and it does not have to capture it into a sprite.
What covers it is the text layer, which repaints every row it owns — opaque, every frame,
for a reason akbasic_sink_akgl_render() explains — and by default it owns the whole
window. WINDOW shrinks it:
10 WINDOW 0, 0, 39, 1
20 GRAPHIC 1, 1
30 COLOR 1, 3
40 BOX 1, 20, 40, 300, 180
Two rows of text at the top, the rest of the window for drawing, and the box is still there a thousand frames later.
A redraw also has to fit inside one batch. The host runs a fixed number of source
lines and then presents, and presenting throws the drawing buffer away — so a run of
drawing verbs longer than one batch is torn rather than merely transient, and an
SSHAPE at the end of it captures only the part issued since the present. Watching
TI# change is how a program finds the boundary; Chapter 13 has the measured numbers and
Chapter 18 has a
routine that uses them.