ttf_words.c: TTF-TEXT entry point, hmtx advance widths (item 4.3.7e)

Punch list §25 item 4.3.7e complete. New src/word_source/ttf_words.c
registers TTF-TEXT ( c-addr u x y size color -- ): lazily loads the v1
default font capsule + raster cache once, decodes UTF-8 (C
reimplementation mirroring capsules/fabric.4th's DECODE-UTF8 exactly),
looks up each glyph's cached bitmap, blits via fb_put_pixel, advances
the pen by the glyph's real hmtx advance width scaled to pixels.

Necessary plumbing: ttf_parse() now also locates hhea/hmtx, and
ttf_glyph_advance_width() reads a glyph's advance width -- required for
this item's own "proportional spacing correct" acceptance clause, no
advance-width data existed anywhere else in the parser. Verified in
tools/ttftest.c: A/a/0/space all read advance_width=600, correctly
uniform since JetBrainsMono-Regular.ttf is monospace.

(x,y) is raster pixel space (top-left origin, Y-down), deliberately not
the stroke font TEXT's Cartesian Y-up convention -- recorded explicitly
in ttf_words.h, not conflated.

Verified live, amd64, screendump: injected
S" Hi 4.3.7e!" 200 200 28 16777215 TTF-TEXT over a serial socket after
boot, no error, captured a screendump showing the string rendered
legibly with correct mixed-case/digit/punctuation glyphs and even
spacing. TTF-TEXT is this item's permanent deliverable, not a
throwaway probe. Compile-checked clean on all three architectures.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
Robert Allan James
2026-08-10 23:11:40 -04:00
co-authored by Claude Sonnet 5
parent 2db4603d04
commit 715ebcc57e
8 changed files with 319 additions and 2 deletions
+39 -1
View File
@@ -4880,11 +4880,49 @@ document and committing that amendment as its own item.*
> nothing here is CANVAS-visual. Compile-checked clean (`-Wall -Werror -Wextra`) on all
> three architectures, with and without `-D__STARKERNEL__`.
- [ ] **4.3.7e — `TTF-TEXT` entry point.** `TTF-TEXT ( c-addr u x y size color -- )`,
- [x] **4.3.7e — `TTF-TEXT` entry point.** `TTF-TEXT ( c-addr u x y size color -- )`,
analogous to 4.3.6f's `TEXT` but TrueType-backed — becomes the primary text-rendering path
per the resolved relationship to the stroke font (§27.7); `TEXT`/the stroke system remain
available, not deprecated. *Done when:* a UTF-8 string renders correctly via `TTF-TEXT` in
one call, screendump-verified, proportional spacing correct. *Refs:* §27.7.
> **Done 2026-08-10.** New `src/word_source/ttf_words.c`/`ttf_words.h`, registered from
> `word_registry.c` as Module 30. `TTF-TEXT` lazily loads the v1 default font capsule
> (`fonts:JetBrainsMono-Regular.ttf`) and its raster cache once on first use, decodes the
> UTF-8 string byte-by-byte (a C reimplementation mirroring `capsules/fabric.4th`'s
> `DECODE-UTF8` exactly -- same lead-byte-length table, same U+FFFD fallback), looks up
> each codepoint's bitmap via `ttf_raster_cache_get()` (4.3.7d), blits it via
> `fb_put_pixel()`, and advances the pen by the glyph's real `hmtx` advance width (new --
> see below) scaled to pixels via the shared `q48_mul`/`q48_div` (safe here since advance
> widths and scale are always non-negative, unlike the rasterizer's signed cases).
>
> **Necessary plumbing added, not scope creep beyond this item's own "done when":**
> `ttf_parse()` now also locates `hhea` (for `numberOfHMetrics`) and `hmtx`, and
> `ttf_glyph_advance_width()` reads a glyph's advance width from it. Without this,
> "proportional spacing correct" (this item's own acceptance clause) would be unmet --
> there is no advance-width data anywhere else in the parser. Verified in
> `tools/ttftest.c`: `A`/`a`/`0`/space all read `advance_width=600`, correctly uniform
> since `JetBrainsMono-Regular.ttf` is monospace (a real structural property to check
> against, not an arbitrary assumption).
>
> **Coordinate convention, recorded explicitly, not conflated with the stroke font's:**
> `TTF-TEXT`'s `(x,y)` is raster pixel space (top-left origin, Y-down) -- the same space
> `PLOT`/`fb_put_pixel()` use -- NOT `capsules/fabric.4th`'s Cartesian Y-up space that the
> stroke font's `TEXT` (4.3.6f) uses via `CART-PLOT`. These are two deliberately different
> coordinate systems on two separate text paths; a caller mixing them up would get a
> vertically-flipped `y`. `(x,y)` is the first glyph's baseline-left origin.
>
> **Verified live, amd64, screendump.** Boot: same one-off script pattern as 4.3.7c
> (monitor socket + `socat` + HMP `screendump`, plus serial-socket command injection) --
> booted to `[Hera] ok>`, injected `S" Hi 4.3.7e!" 200 200 28 16777215 TTF-TEXT` over the
> serial socket, confirmed no error in the serial log (next prompt was a clean `ok>`), then
> captured a screendump. Result: `"Hi 4.3.7e!"` renders legibly at the expected position,
> mixed case + digits + punctuation all correct, glyphs evenly spaced left to right with no
> overlap -- `fb/amd64/ttf-text-hi437e-20260810-230926.png` (not committed; `fb/` is
> gitignored, matching every other screendump referenced in this document). Unlike
> 4.3.7c's `TTF-PROBE`, `TTF-TEXT` is the item's own permanent deliverable, not a
> throwaway -- nothing to revert.
>
> Compile-checked clean (`-Wall -Werror -Wextra`) on all three architectures.
- [ ] **4.3.7f — Checkpoint: TTF rendering, all three architectures.** Same posture as
4.3.6g. *Done when:* a single screendump per architecture shows a representative sample