FABRIC.md: item 4.3.3 -- settle 45deg cavalier, split off 4.3.3a/4.3.3b

Scoping discussion for 4.3.3 (Cartesian coordinate machinery) surfaced a
larger ask: a full geometry drawing wordset (circles, arcs, ellipses,
radian-based trig), which doesn't exist anywhere in this codebase yet.
Split per the one-task-per-checkbox rule rather than overloading 4.3.3:

- 4.3.3 stays scoped to single-point plumbing: PLOT/FB-WIDTH/FB-HEIGHT (C,
  raw hardware boundary) plus PROJECT/CART-Y/CART-PLOT (FORTH, capsules/
  fabric.4th, blocks 4900+), per compose-in-FORTH-first.
- 4.3.3a (new): Q.SIN/Q.COS in q48_16.c, Taylor series, same pattern as the
  file's existing Q.LOG/Q.EXP/Q.SQRT.
- 4.3.3b (new): LINE/CIRCLE/ARC/ELLIPSE in FORTH, built on 4.3.3 + 4.3.3a.

Also settled: projection angle is true 45 degree cavalier (not 2:1
isometric); "1080p" is a sizing sanity check only, not a hardcoded
constraint (Q48.16's 48 integer bits comfortably cover it).
This commit is contained in:
Robert Allan James
2026-08-07 11:48:50 -04:00
parent ab96ac0970
commit fbf0625317
+41 -15
View File
@@ -3694,13 +3694,25 @@ document and committing that amendment as its own item.*
- [ ] **4.3.3 — Cartesian coordinate machinery.** Origin bottom-left `(0, 0)`, Y-up, plus a
new Z axis (depth-into-screen, not height) and a fixed orthographic projection as a
placeholder — not the final projection, no perspective/camera work yet. Angle open: true
45° cavalier vs. 2:1 pixel-art isometric; settle when this item is actually implemented.
*Refs:* §27.3.
placeholder — not the final projection, no perspective/camera work yet. **Angle settled
2026-08-07: true 45° cavalier.** New C primitives `PLOT ( x y color -- )`, `FB-WIDTH`,
`FB-HEIGHT` (raw hardware boundary, no Cartesian awareness); new FORTH capsule
`capsules/fabric.4th` (blocks 4900+) for `PROJECT`/`CART-Y`/`CART-PLOT`, per the
compose-in-FORTH-first rule — the transform is policy, not hardware access. *Refs:* §27.3.
- [ ] **4.3.4Checkpoint: draw a cube.** First real exercise of the 4.3.3 coordinate/
projection machinery. Stop and review here before scoping the next 4.3.x item — not
expected to be fast. *Refs:* §27.4.
- [ ] **4.3.3aQ48.16 trigonometry.** `Q.SIN`/`Q.COS` (radian input) added to `q48_16.c`,
Taylor series after range-reducing into `[-π, π]` — same pattern as this file's existing
`Q.LOG`/`Q.EXP`/`Q.SQRT`, not a new precedent. Raised 2026-08-07 while scoping 4.3.3: needed
by 4.3.3b, does not exist anywhere in this codebase today (checked). *Refs:* §27.3.
- [ ] **4.3.3b — Geometry drawing primitive wordset.** `LINE`, `CIRCLE`, `ARC`, `ELLIPSE` in
`capsules/fabric.4th`, built on 4.3.3's `PLOT`/`CART-PLOT` and 4.3.3a's `Q.SIN`/`Q.COS`.
Raised 2026-08-07. Q48.16 throughout; resolution-agnostic (48 integer bits comfortably
covers 1080p and well beyond — no hardcoded viewport assumptions). *Refs:* §27.3.
- [ ] **4.3.4 — Checkpoint: draw a cube.** First real exercise of the 4.3.3/4.3.3a/4.3.3b
coordinate/projection/geometry machinery — cube edges use `LINE`. Stop and review here
before scoping the next 4.3.x item — not expected to be fast. *Refs:* §27.4.
*(4.3.x is open-ended — more items get appended here as Console work is scoped item by*
*item, developed on the fly per §25.0. 4.4 below is unaffected by anything added above*
@@ -4038,20 +4050,34 @@ serial chardev socket (for the log) — no monitor, no QMP socket. There is no w
issue QEMU's `screendump` command. 4.3.2 adds a monitor/QMP socket (mirroring the existing
serial-socket pattern) so the framebuffer can actually be inspected as a `.ppm` after a run.
### 27.3 Coordinate system (4.3.3)
### 27.3 Coordinate system (4.3.3, 4.3.3a, 4.3.3b)
- **Origin bottom-left**, `(0, 0)`. Traditional Cartesian, not raster/top-left-Y-down. The
framebuffer's native memory layout is top-left origin, Y-down — the Y-flip transform must
live at the lowest primitive layer so nothing built above it ever has to think about it.
- **Origin bottom-left**, `(0, 0)`. Traditional Cartesian, not raster/top-left-Y-down.
**Reinterpreted 2026-08-07:** §27.3 originally said the Y-flip "must live at the lowest
primitive layer," written before the language split (below) was decided. `PLOT` is the true
hardware boundary and is deliberately raster-native with no Cartesian awareness at all —
same posture as `BLOCK`/`UPDATE` staying dumb about policy. `CART-Y`, in FORTH, is the
lowest *Cartesian-aware* layer, which satisfies the original intent (nothing above it ever
thinks about the flip) even though the flip itself lives one level up from the raw pixel
write.
- **Z axis, depth-into-screen** (not height-off-ground). Confirmed 2026-08-07: this is
heading toward real 3D animation over time, not a single static scene — Z is being added
now because retrofitting it later is more expensive than building it in from the start.
- **Projection: fixed orthographic, for now.** Explicitly a placeholder — not the final
projection, no perspective/camera work yet. **Open:** the exact angle — true 45° cavalier
(both X and Z axes drawn at 45° off horizontal) vs. the 2:1 pixel-art isometric convention
(~26.57°, the "2-across/1-up" slope most retro isometric engines use because it tiles
cleanly on a pixel grid). Not settled; settle it when the projection math is actually
written, not speculatively here.
projection, no perspective/camera work yet. **Angle settled 2026-08-07: true 45° cavalier**
(both X and Z axes drawn at 45° off horizontal) `sx = x + z·cos45`, `sy = y + z·cos45`.
Ruled out the 2:1 pixel-art isometric convention (~26.57°); no reason recorded beyond
preference.
- **Language: FORTH for the transform, C only for the raw pixel write.** Per the project's
compose-in-FORTH-first rule — `PROJECT`/`CART-Y`/`CART-PLOT` are policy, not hardware
access, so they belong in `capsules/fabric.4th`, not in C. Only `PLOT`/`FB-WIDTH`/
`FB-HEIGHT` are C primitives.
- **Trigonometry (4.3.3a) and geometry primitives (4.3.3b), raised 2026-08-07 while scoping
this item.** `Q.SIN`/`Q.COS` (Taylor series, radian input) extend `q48_16.c` the same way
`Q.LOG`/`Q.EXP`/`Q.SQRT` already do — not a new precedent, just more of the same module.
`LINE`/`CIRCLE`/`ARC`/`ELLIPSE` build on those plus `PLOT`/`CART-PLOT`, entirely in FORTH,
Q48.16 throughout. Resolution-agnostic by design — 48 integer bits is vastly more range
than 1920×1080 needs, checked as a sizing sanity check only, not a hardcoded constraint.
### 27.4 Checkpoint: a cube (4.3.4)