starkernel: item 4.3.3 -- Cartesian coordinate machinery, found and fixed a VARIABLE alignment bug

Adds Module 28 (framebuffer_words.c/.h): PLOT ( x y color -- ), FB-WIDTH,
FB-HEIGHT -- raw hardware-boundary C primitives, kernel-only, no-op on
hosted builds, same pattern as every other module.

Adds capsules/fabric.4th (blocks 4900-4902, mkcapsule --lint clean):
COS45/Z->DELTA/PROJECT/CART-Y/CART-PLOT -- the 45-degree cavalier
orthographic projection and Y-flip, in FORTH per the compose-in-FORTH-first
rule (this is policy, not hardware access).

Found and fixed a second real bug while live-testing CART-PLOT over the
serial socket: defining_word_variable() (defining_words.c) captured
vm->here as a VARIABLE's address with no alignment call first, while
vm_load_cell/vm_store_cell require 8-byte-aligned addresses. This capsule's
VARIABLE ZD landed misaligned (945) purely by chance of what preceded it;
other capsules' variables happened to land aligned by luck, not guarantee.
Real deviation from FORTH-83/ANS, which specifies VARIABLE reserves an
aligned cell. Fixed with vm_align(vm) before capturing addr -- ALIGN
already existed as a word but VARIABLE wasn't calling it.

Verified end-to-end on amd64 via manual serial injection + QEMU screendump:
plotted 4 marker points (origin, +100 X, +100 Y, +50 Z) and confirmed all
landed at hand-calculated raster coordinates, including the diagonal
up-right shift for the Z-axis point -- the projection math is correct, not
just non-crashing. fb/fabric-test-cart-plot.png. 4.3.1's corner diagnostic
still renders correctly in the same shot, confirming no regression.

All three architectures (amd64/aarch64/riscv64) boot clean to ok> with the
DoE completing; dict_hash identical across all three
(0xc7f9adf885e306d2), confirming parity is unaffected.

FABRIC.md item 4.3.3 marked done with full acceptance evidence.
This commit is contained in:
Robert Allan James
2026-08-07 13:20:52 -04:00
parent fbf0625317
commit ef9806977a
9 changed files with 173 additions and 3 deletions
+6 -2
View File
@@ -1,5 +1,5 @@
# Capsule Block Manifest — Auto-generated
<!-- Generated by mkcapsule --manifest 2026-08-07T14:56:31Z -->
<!-- Generated by mkcapsule --manifest 2026-08-07T16:05:06Z -->
<!-- DO NOT EDIT — re-run mkcapsule --manifest to refresh. -->
<!-- Hand-written justifications and immutability notes live -->
<!-- in MANIFEST.md alongside this auto-generated index. -->
@@ -13,6 +13,7 @@
| `common:msg.4th` | 4055 | `0xa99c5bcd3877f80e` |
| `doe-campaign.4th` | 4060, 4061, 4062, 4063, 4064, 4065 | `0x3d4549142d91ec20` |
| `doe.4th` | 2100, 2101, 2102, 2103, 2104, 2105, 2106, 2107 | `0xb6ecf5374e8ee77c` |
| `fabric.4th` | 4900, 4901, 4902 | `0xb7db7380ec4a42a0` |
| `hermes:init.4th` | 4100, 4101, 4102, 4103, 4104, 4105, 4106, 4107, 4108, 4109, 4114, 4115, 4116, 4117, 4118, 4119, 4120, 4121, 4142, 4143, 4144, 4145, 4146, 4147, 4148, 4149, 4150, 4151, 4152, 4153, 4154, 4155, 4156, 4157, 4158, 4159, 4175, 4176 | `0x85c7b311d1e5bf97` |
| `init-0.4th` | 2200, 2201 | `0xd0a9550baf786bb3` |
| `init-1.4th` | 4406, 4415, 4425, 4435 | `0x63e251adb0a03613` |
@@ -224,10 +225,13 @@
| 4842 | `init-l8-transition.4th` | `0xbcc1a81976f0a4c9` | ok |
| 4851 | `artemis:init.4th` | `0xc9e92cd18f4c7b49` | ok |
| 4852 | `artemis:init.4th` | `0xc9e92cd18f4c7b49` | ok |
| 4900 | `fabric.4th` | `0xb7db7380ec4a42a0` | ok |
| 4901 | `fabric.4th` | `0xb7db7380ec4a42a0` | ok |
| 4902 | `fabric.4th` | `0xb7db7380ec4a42a0` | ok |
## Conflicts
None.
---
*26 capsule(s) scanned. Re-run `mkcapsule --manifest <dir>` to refresh.*
*27 capsule(s) scanned. Re-run `mkcapsule --manifest <dir>` to refresh.*
+32
View File
@@ -0,0 +1,32 @@
Block 4900
( fabric.4th -- Console drawing-fabric coordinate machinery )
( FABRIC.md item 4.3.3. 45-degree cavalier orthographic )
( projection. Z is depth-into-screen, not height. Q48.16 )
( throughout. Raw pixel write (PLOT/FB-WIDTH/FB-HEIGHT) is )
( C; this capsule is the FORTH-side policy on top of it. )
46341 CONSTANT COS45 ( Q48.16 cos(45)=sin(45) ~= 0.70710678 )
VARIABLE ZD
: Z->DELTA ( z -- delta )
Q.FROM-INT COS45 Q.* Q.TO-INT ;
Block 4901
( PROJECT: 3D Cartesian (x y z) -> 2D Cartesian (sx sy). )
( Cavalier projection: depth pushes diagonally up-right. )
: PROJECT ( x y z -- sx sy )
Z->DELTA ZD !
ZD @ +
SWAP ZD @ +
SWAP ;
( CART-Y: Cartesian Y (origin bottom, up positive) -> )
( raster Y (origin top, down positive). The Y-flip. )
: CART-Y ( cart-y -- raster-y )
FB-HEIGHT 1- SWAP - ;
Block 4902
( CART-PLOT: full pipeline -- 3D Cartesian point to screen. )
: CART-PLOT ( x y z color -- )
>R
PROJECT
CART-Y
R>
PLOT ;