From fbf062531793cb29bc66726aa222ad8c1c09a062 Mon Sep 17 00:00:00 2001 From: Robert Allan James Date: Fri, 7 Aug 2026 11:48:50 -0400 Subject: [PATCH] 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). --- FABRIC.md | 56 ++++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 41 insertions(+), 15 deletions(-) diff --git a/FABRIC.md b/FABRIC.md index c80ed30..1c29c4a 100644 --- a/FABRIC.md +++ b/FABRIC.md @@ -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.4 — Checkpoint: 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.3a — Q48.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)