diff --git a/FABRIC.md b/FABRIC.md index 96c0216..cdef9e4 100644 --- a/FABRIC.md +++ b/FABRIC.md @@ -3649,7 +3649,8 @@ document and committing that amendment as its own item.* > in this document from here on. First slice scoped below as 4.3.1. - [ ] **4.3.1 — Framebuffer sanity and the coordinate fabric.** First real work on Console: - prove the raw hardware boundary before anything Stadium- or VM-shaped touches it. Scope: + prove the raw hardware boundary before anything Stadium- or VM-shaped touches it. *Refs:* + §27. Scope: 1. Confirm `framebuffer.c` is wired to the real UEFI GOP `BootInfo` and draw a simple orientation-revealing test pattern (raw pixel primitives only — no coordinate/Z machinery yet). @@ -3971,3 +3972,58 @@ actually concurrent on one hart). No pthread, no kernel task, no scheduler. **RULED.** Item 0.8 is amended below to include this; no new punch-list item is needed — this is squarely inside what 0.8 already builds (`heartbeat.c`, the three re-arm call sites). + +## 27. Console — the drawing fabric (groundwork, 4.3.1) + +**STATUS: design-stage, 2026-08-07.** Supersedes `.claude/CONSOLE.md` as the authoritative +Console design document. `CONSOLE.md` was a rough prior working draft and is not edited +further; nothing in it should be treated as decided just because it is written down there. +This section covers 4.3.1 only — the groundwork slice: verify the hardware boundary works +and stand up the coordinate machinery. It is explicitly *not* the full Console specification +(fonts, scrolling-as-a-VM-behavior, message protocol from Hermes, etc.) — those are later +items under 4.3, scoped once 4.3.1's checkpoint is reviewed. + +### 27.1 The hardware boundary already exists + +`console_fb_init()` (`hal/console.c:269`) calls `fb_init()` with real UEFI GOP data from +`boot_info->framebuffer`, but only after POST completes, immediately before the REPL starts +(`kernel_main.c:800-807`). `include/starkernel/framebuffer.h` already exposes raw pixel +primitives: `fb_put_pixel`, `fb_fill_rect`, `fb_draw_glyph` (8×16 cells), `fb_scroll_rows`. +There is nothing to build to get pixels on screen — 4.3.1's first task is *verification*, +not construction: draw a simple, orientation-revealing test pattern with the existing +primitives and confirm it displays right-side up. + +### 27.2 No screenshot capability exists today + +All three `qemu` targets in `Makefile.starkernel` run with `-display none` and attach only a +serial chardev socket (for the log) — no monitor, no QMP socket. There is no way today to +issue QEMU's `screendump` command. 4.3.1 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 + +- **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. +- **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. + +### 27.4 Checkpoint: a cube + +4.3.1's acceptance is a cube rendered on screen using the coordinate/projection machinery +above — the first real exercise of that math, expected to take real effort, not a quick +add. Stop and review here before scoping the next 4.3.x item. + +### 27.5 Explicitly out of scope for 4.3.1 + +- **Raster image rendering** (PNG/JPEG decode, composited onto the fabric as backgrounds). + Real direction, raised 2026-08-07, deliberately deferred past this slice. +- Fonts, scrolling, cursor/VT100 semantics, the Hermes message protocol, Console as a fleet + VM under Hera's birth protocol — all later 4.3.x work, not 4.3.1.