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 - [ ] **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 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 placeholder — not the final projection, no perspective/camera work yet. **Angle settled
45° cavalier vs. 2:1 pixel-art isometric; settle when this item is actually implemented. 2026-08-07: true 45° cavalier.** New C primitives `PLOT ( x y color -- )`, `FB-WIDTH`,
*Refs:* §27.3. `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/ - [ ] **4.3.3aQ48.16 trigonometry.** `Q.SIN`/`Q.COS` (radian input) added to `q48_16.c`,
projection machinery. Stop and review here before scoping the next 4.3.x item — not Taylor series after range-reducing into `[-π, π]` — same pattern as this file's existing
expected to be fast. *Refs:* §27.4. `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* *(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* *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 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. 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 - **Origin bottom-left**, `(0, 0)`. Traditional Cartesian, not raster/top-left-Y-down.
framebuffer's native memory layout is top-left origin, Y-down — the Y-flip transform must **Reinterpreted 2026-08-07:** §27.3 originally said the Y-flip "must live at the lowest
live at the lowest primitive layer so nothing built above it ever has to think about it. 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 - **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 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. 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: fixed orthographic, for now.** Explicitly a placeholder — not the final
projection, no perspective/camera work yet. **Open:** the exact angle — true 45° cavalier projection, no perspective/camera work yet. **Angle settled 2026-08-07: true 45° cavalier**
(both X and Z axes drawn at 45° off horizontal) vs. the 2:1 pixel-art isometric convention (both X and Z axes drawn at 45° off horizontal) `sx = x + z·cos45`, `sy = y + z·cos45`.
(~26.57°, the "2-across/1-up" slope most retro isometric engines use because it tiles Ruled out the 2:1 pixel-art isometric convention (~26.57°); no reason recorded beyond
cleanly on a pixel grid). Not settled; settle it when the projection math is actually preference.
written, not speculatively here. - **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) ### 27.4 Checkpoint: a cube (4.3.4)