Draw into the whole window, not its top-left 320x200

The graphics verbs documented a coordinate transform that did not exist. With
SCALE off a coordinate went straight to akgl_draw_* as a pixel address, so an
800x600 window drew a C128 listing into its corner and left the rest unused --
while the chapter said coordinates were 320x200 and stretching to fit was the
host's business.

akbasic_GraphicsBackend gains a size entry point, require_graphics() asks it
before every verb that draws so a resized window is honoured between two
statements, and 320x200 becomes the fallback for a backend that leaves it NULL.
It is the record's one optional member, so a host written against the old header
keeps the behaviour it had.

SCALE now maps onto the device, and RGR(1)/RGR(2) report the drawing surface so
a program can use a window whose size it did not choose. RGR(0) is BASIC 7.0's
own field, the GRAPHIC mode.

SCALE also mapped xmax onto the width rather than onto the last pixel, so
SCALE 1, 319, 199 followed by DRAW 1, 319, 199 drew nothing at all -- one pixel
past the surface. Fixed in the same line, because it is what makes "SCALE gives
a C128 listing the whole window" true rather than nearly true.

The akgl test renders against a 128x128 target, deliberately smaller than the
old constants: a SCALE still dividing by them misses it entirely rather than
landing somewhere plausible.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

docs/06-graphics.md

@@ -14,10 +14,35 @@ verb refuses by name:
 
 ## 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.
+**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:
+
+```basic requires=akgl
+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:
+
+```basic requires=akgl
+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
 
@@ -90,7 +115,18 @@ coordinates finishes.
 ```
 
 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.
+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. All three
+refuse when there is no graphics device, except `RGR(0)`, which is a mode this
+interpreter recorded rather than a screen it has to go and measure.
 
 ### WIDTH
 

docs/08-sprites.md

@@ -84,8 +84,10 @@ the continuous form, which is a trap worth remembering.
 The continuous form does not move anything on the statement itself. The sprite moves as
 the program runs, paced by the host's clock. Speed 0 stops it.
 
-Coordinates are the same 320 by 200 space the drawing verbs use, not the VIC-II's
-raster coordinates.
+Coordinates are the same window pixels the drawing verbs use, not the VIC-II's raster
+coordinates — see Chapter 6, and `RGR(1)` and `RGR(2)` for how big the window is.
+`SCALE` does not apply to them: a sprite is positioned in device pixels whatever the
+drawing verbs are doing.
 
 ## Collision
 

docs/12-function-reference.md

@@ -25,6 +25,7 @@ so a call with the wrong number is a syntax error rather than a surprise.
 | `POINTER` | 1 | `POINTER(V)` | The address of a variable's value. |
 | `POINTERVAR` | 1 | `POINTERVAR(V)` | The address of the variable structure itself, metadata included. |
 | `RAD` | 1 | `RAD(n)` | Degrees converted to radians. |
+| `RGR` | 1 | `RGR(f)` | The `GRAPHIC` mode (0), or the drawing surface's width (1) or height (2) in pixels. |
 | `RIGHT` | 2 | `RIGHT(A$, n)` | The rightmost `n` characters. Clamped. |
 | `RSPCOLOR` | 1 | `RSPCOLOR(n)` | One of `SPRCOLOR`'s two shared registers, 1 or 2. |
 | `RSPPOS` | 2 | `RSPPOS(n, f)` | A sprite's x (0), y (1) or speed (2). |

docs/13-differences.md

@@ -89,7 +89,10 @@ interpreter's error code, which bears no relation to a Commodore error number. P
 
 ## Graphics
 
-- **Coordinates are always 320 by 200**, whatever the window size.
+- **A coordinate is a window pixel, not one of 320 by 200.** A C128 listing therefore
+  draws in the top-left corner of a larger window; `SCALE 1, 319, 199` gives it the
+  whole window back. `RGR(1)` and `RGR(2)` report the size, and are ours rather than
+  7.0's — where 7.0's `RGR` takes only field 0, the `GRAPHIC` mode.
 - **`SSHAPE` puts a handle in the string, not the pixels.** You can pass it to `GSHAPE`
   and `SPRSAV`; you cannot save it or take its `LEN`.
 - **`WIDTH` is emulated** by drawing parallel passes.
@@ -107,7 +110,8 @@ interpreter's error code, which bears no relation to a Commodore error number. P
 
 ## Sprites
 
-- **Coordinates are the 320 by 200 drawing space**, not the VIC-II's raster space.
+- **Coordinates are window pixels**, not the VIC-II's raster space, and `SCALE` does
+  not apply to them.
 - **`SPRSAV` takes an integer array**, not a string, for the data form — a string here
   cannot hold a zero byte. It also takes an **image file path**, which a C128 cannot.
 - **A sprite loaded from a file keeps the image's own size**, not 24 by 21.