Add capsules/turtle.4th, a limited LOGO-style turtle graphics demo capsule

First entry in the "cookbook" track: a demo capsule plus HOWTO, per the
sequencing laid out after the POST-coverage sweep. Built entirely in FORTH
on top of existing primitives -- fabric.4th's LINE (raster Bresenham) and
Q.SIN/Q.COS (Q48.16 trig), plus PLOT/FB-WIDTH/FB-HEIGHT -- no new C words.

FORWARD/BACK/LEFT/RIGHT/PENUP/PENDOWN/HOME/SETXY/SETHEADING/SETCOLOR give
the classic turtle model; POLYGON and STAR compose FORWARD+turn into simple
demo shapes; TURTLE-DEMO is a one-call visual smoke test. Not wired into
init.4th -- REPL-invoked only, matching the original idea's own scope.

Verified: mkcapsule --lint clean, hosted-build logic trace shows zero VM
errors and correct stack balance through the whole vocabulary, zero build
warnings and capsule loads cleanly on all three kernel architectures.
Visual pixel-level confirmation not yet done (needs an interactive
gtk-display session or driving past the ~25-30 min DoE-before-REPL wall),
documented as an open item in the HOWTO.

HOWTO: docs/working/architecture/TURTLE-GRAPHICS-HOWTO-20260819.md

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
Robert Allan James
2026-08-19 01:50:54 -04:00
co-authored by Claude Sonnet 5
parent abb858a300
commit e40134da0d
6 changed files with 13242 additions and 2 deletions
+31
View File
@@ -1611,3 +1611,34 @@ independent, previously-undetected production bugs in `physics_freeze_words.c` t
this session entirely. Per the user's own sequencing ("code sweeps → HOL green → POST
coverage"), this closes that sequence; LOGO/turtle demo + HOWTOs + SDK beginnings are next,
pending explicit go-ahead.
**Cookbook, first entry — `capsules/turtle.4th`, a limited LOGO-style turtle graphics
capsule.** Started 2026-08-19 on explicit go-ahead, picking up the "cookbook" idea from the
user's own sequencing note above (demo capsule + DoE package/library, each with a HOWTO,
before SDK v1.9.0 scoping) and the older `project-stadium-logo-turtle-idea` memory (floated
2026-08-11, explicitly deferred until raised again). Composed entirely in FORTH on top of
existing primitives — `PLOT`/`FB-WIDTH`/`FB-HEIGHT` (`framebuffer_words.c`) and, more
significantly, `capsules/fabric.4th`'s already-implemented `LINE` (raster-space Bresenham) and
`Q.SIN`/`Q.COS` (Q48.16 trig, `q48_words.c`) — no new C words, matching this repo's "compose
in FORTH first" rule. `FORWARD`/`BACK` compute `dx`/`dy` from the turtle's heading (stored
directly in Q48.16 radians, not degrees, so no per-step conversion) and call `LINE` when the
pen is down; `LEFT`/`RIGHT`/`SETHEADING` do the degrees→radians conversion once, at the turn,
via a `DEG2RAD` constant. `POLYGON` and `STAR` compose `FORWARD`+turn in a loop (`STAR` uses a
144° turn, not `360/5=72°` — a regular pentagon doesn't self-intersect, the classic star shape
needs the overshoot). Block range `5100``5108`, clear of `fabric.4th`'s highest block
(`5002`). Not wired into `init.4th` — matches the memory's own note that this is REPL-invoked,
not part of Mama's boot sequence.
Verified: `mkcapsule --lint capsules/` clean. Logic verified on the hosted build by piping
`fabric.4th`'s core blocks (`4900``4909`) plus `turtle.4th` directly into the hosted binary —
zero VM errors, `--log-debug` trace confirms correct stack balance through `HOME`/`SETCOLOR`/
`POLYGON`/`STAR`/`FORWARD`/`LINE`. Baked cleanly into `capsule_generated.c` and built with zero
warnings on all three kernel architectures (amd64/aarch64/riscv64, only the two known
pre-existing linker warnings on aarch64 — RWX LOAD segment, `/align` — present as always).
amd64 boot verified clean through POST and into the DoE campaign with the capsule present.
**Not yet visually confirmed pixel-by-pixel in a live framebuffer** — driving the serial socket
interactively hits the same ~2530 minute DoE-before-REPL wall every kernel boot does, and
wasn't practical to sit through unattended for a demo capsule; the arithmetic and control flow
are verified, the actual rendered image is not. HOWTO:
`docs/working/architecture/TURTLE-GRAPHICS-HOWTO-20260819.md`. Second cookbook entry (DoE
package/library + its own HOWTO) is next.