WIP: feat/txt-01 #203

Draft
OragonEfreet wants to merge 8 commits from feat/txt-01 into main
Owner

Add bitmap font support with a public text layout

Banjo can now load and use real font files.
This pull request adds bitmap font support, BMFont text and binary descriptors with BMP atlas pages, with a public text layout: a program can place, measure and draw glyphs itself.

It is the first delivery of the text plan.
The API is the product: it was written against the simplest font format, and later stories, TrueType, variable fonts and font fallback, plug into the same types without breaking them.

Pull request for the feat/txt-01 branch.
It closes the bitmap font and layout work: the typeface and font couple, the inspectable layout, and the one glyph-drawing call every text drawing goes through.

Added

inc/banjo/font.h

  • bj_typeface: the design read from a font file (glyphs, metrics, spacing); an index selects a face inside files that hold several.
  • bj_load_typeface, bj_destroy_typeface: load and release, with the path passed as a borrowed bj_str view, valid UTF-8 by contract.
  • bj_create_font, bj_destroy_font: derive one usable instance of a typeface at a pixel size; 0 asks for the size the file declares, and any other size fails on a bitmap font, which has the size it was exported at.
  • bj_font_typeface: the typeface a font derives from, as a borrowed pointer for inspection.
  • bj_load_font: the two calls composed, for a program that wants one file at one size; its documentation shows the equivalent code, which is its contract.

inc/banjo/text.h

  • bj_glyph_placement: one glyph of a laid-out text, carrying its glyph identifier, its pen position in bj_real, the byte offset of the character it came from, and the font it belongs to; a plain value a program can copy, keep and draw later.
  • bj_text_style: how to compose a text, its font chain as a borrowed array in priority order, its wrap width and its alignments; one style lays out many texts, the text itself is a parameter of each call.
  • bj_layout_text, bj_destroy_text_layout, bj_layout_glyph_count, bj_layout_glyph, bj_layout_bounds, bj_layout_line_count: lay a text out and read everything back, without drawing a pixel; measuring is reading the layout.
  • bj_draw_glyph: the one glyph-drawing function of the library.
  • bj_draw_text_layout: the convenience, lay out, draw every glyph, discard; a client of the layout, never a second engine, so a manual loop over the placements produces identical pixels.

src/font.c, src/text.c

  • BMFont, text and binary descriptors, atlas pages in BMP, kerning pairs and the character-to-glyph mapping; pages are normalized to 8bpp coverage masks at load, so no new image dependency.

assets/font/

  • The banjo-test fixtures, the descriptor in both encodings with defective variants, and their generator script.

Other

  • Examples: aligned text in a box in the three alignments; a manual loop over the placements drawing each glyph; per-glyph bouncing letters, an effect the public placements drive without any "animated text" function in the library.
  • Tests test/spec_font.c and test/spec_text.c, one case per example row of the specifications.
  • ADR 0009, the specifications font-001-typeface-and-font.md and text-001-glyph-layout.md, a capability line in the README, and a CHANGELOG entry.

Decisions

Per ADR 0009, the text API is a typeface and a font with a public layout.

The typeface is the design read from a font file, and the font is one instance of it at a size; a size is not always enough to describe a font, which is where variable fonts plug in.
A typeface counts its fonts: destroying a typeface handle only marks the typeface, its memory goes when its last font dies, and handles can be destroyed in any order.
Loading in one call is the two-call couple composed, never a second loader.
The layout refuses text that is not valid UTF-8, per ADR 0008.
One glyph-drawing function exists, and every text drawing, the convenience draw included, is that function or a loop over the same layout, so measure and draw cannot drift.
The style struct grows fields in later revisions, and its font chain is a borrowed array rather than a container object, so adding a public symbol waits for a real need.

Compatibility

The existing text engine, bj_draw_text, bj_blit_text, bj_measure_text and bj_draw_textf, is unchanged and keeps its names until its removal in 2.0.
The alignment values are the ones the old engine already uses, so both engines share the same enums while they coexist.
The built-in 8x8 font keeps working as before.

# Add bitmap font support with a public text layout Banjo can now load and use real font files. This pull request adds bitmap font support, BMFont text and binary descriptors with BMP atlas pages, with a public text layout: a program can place, measure and draw glyphs itself. It is the first delivery of the text plan. The API is the product: it was written against the simplest font format, and later stories, TrueType, variable fonts and font fallback, plug into the same types without breaking them. Pull request for the `feat/txt-01` branch. It closes the bitmap font and layout work: the typeface and font couple, the inspectable layout, and the one glyph-drawing call every text drawing goes through. ## Added `inc/banjo/font.h` - `bj_typeface`: the design read from a font file (glyphs, metrics, spacing); an index selects a face inside files that hold several. - `bj_load_typeface`, `bj_destroy_typeface`: load and release, with the path passed as a borrowed `bj_str` view, valid UTF-8 by contract. - `bj_create_font`, `bj_destroy_font`: derive one usable instance of a typeface at a pixel size; 0 asks for the size the file declares, and any other size fails on a bitmap font, which has the size it was exported at. - `bj_font_typeface`: the typeface a font derives from, as a borrowed pointer for inspection. - `bj_load_font`: the two calls composed, for a program that wants one file at one size; its documentation shows the equivalent code, which is its contract. `inc/banjo/text.h` - `bj_glyph_placement`: one glyph of a laid-out text, carrying its glyph identifier, its pen position in `bj_real`, the byte offset of the character it came from, and the font it belongs to; a plain value a program can copy, keep and draw later. - `bj_text_style`: how to compose a text, its font chain as a borrowed array in priority order, its wrap width and its alignments; one style lays out many texts, the text itself is a parameter of each call. - `bj_layout_text`, `bj_destroy_text_layout`, `bj_layout_glyph_count`, `bj_layout_glyph`, `bj_layout_bounds`, `bj_layout_line_count`: lay a text out and read everything back, without drawing a pixel; measuring is reading the layout. - `bj_draw_glyph`: the one glyph-drawing function of the library. - `bj_draw_text_layout`: the convenience, lay out, draw every glyph, discard; a client of the layout, never a second engine, so a manual loop over the placements produces identical pixels. `src/font.c`, `src/text.c` - BMFont, text and binary descriptors, atlas pages in BMP, kerning pairs and the character-to-glyph mapping; pages are normalized to 8bpp coverage masks at load, so no new image dependency. `assets/font/` - The `banjo-test` fixtures, the descriptor in both encodings with defective variants, and their generator script. Other - Examples: aligned text in a box in the three alignments; a manual loop over the placements drawing each glyph; per-glyph bouncing letters, an effect the public placements drive without any "animated text" function in the library. - Tests `test/spec_font.c` and `test/spec_text.c`, one case per example row of the specifications. - ADR 0009, the specifications `font-001-typeface-and-font.md` and `text-001-glyph-layout.md`, a capability line in the README, and a CHANGELOG entry. ## Decisions Per ADR 0009, the text API is a typeface and a font with a public layout. The typeface is the design read from a font file, and the font is one instance of it at a size; a size is not always enough to describe a font, which is where variable fonts plug in. A typeface counts its fonts: destroying a typeface handle only marks the typeface, its memory goes when its last font dies, and handles can be destroyed in any order. Loading in one call is the two-call couple composed, never a second loader. The layout refuses text that is not valid UTF-8, per ADR 0008. One glyph-drawing function exists, and every text drawing, the convenience draw included, is that function or a loop over the same layout, so measure and draw cannot drift. The style struct grows fields in later revisions, and its font chain is a borrowed array rather than a container object, so adding a public symbol waits for a real need. ## Compatibility The existing text engine, `bj_draw_text`, `bj_blit_text`, `bj_measure_text` and `bj_draw_textf`, is unchanged and keeps its names until its removal in 2.0. The alignment values are the ones the old engine already uses, so both engines share the same enums while they coexist. The built-in 8x8 font keeps working as before.
ADR 0009 fixes the shape of the text API before any code exists: a
typeface (the design read from a font file) and a font (one instance
of it at a size), with the one-call loader as their exact
composition, and a public layout of glyph placements. One
glyph-drawing function serves the convenience draw, the manual loop
and the measure, the style struct grows fields, its font chain is a
borrowed array, and loader paths are string views.
font.h and text.h declare the surface ADR 0009 shapes, before any implementation: the couple bj_typeface and bj_font, bj_load_font as the exact composition of the two calls, the borrowed bj_text_style with its font array, and the public layout of glyph placements, read back as placements, bounds and line count.
 bj_draw_glyph is the one glyph-drawing function, and bj_draw_text_layout is a client of the layout.
 src/font.c and src/text.c are placeholder translation units for the coming implementation, api.h grows the consumer typedefs, and the CMakeLists wires the new files in.
Two specifications follow ADR 0009, before any code: font-001 the
couple (either descriptor encoding loads and lays out identically,
the native size or zero loads and any other size fails, destroying a
typeface handle marks it while living fonts keep working, the sugar
is the two calls), text-001 the layout (one placement per character,
the pen advancing by the declared metrics, clusters as byte offsets
of multi-byte characters, wrapping at spaces, alignment anchors, and
the convenience draw pixel-identical to a manual loop over the
placements). Example values follow from the banjo-test descriptor
declared in the scopes, which the fixture generator will implement
and the tests will check.
test(font): RED typeface_binary_matches_text_layout
Some checks failed
C++ Compatibility / C++ Compatibility Check (pull_request) Successful in 21s
Documentation / build-docs (pull_request) Successful in 22s
Build and Test / linux-linux-gcc / shared (pull_request) Has been cancelled
Build and Test / linux-linux-gcc / static (pull_request) Has been cancelled
Build and Test / linux-windows-mingw (build only) / shared (pull_request) Has been cancelled
Build and Test / linux-windows-mingw (build only) / static (pull_request) Has been cancelled
QA / cert (pull_request) Has been cancelled
967aafa659
OragonEfreet force-pushed feat/txt-01 from 967aafa659
Some checks failed
C++ Compatibility / C++ Compatibility Check (pull_request) Successful in 21s
Documentation / build-docs (pull_request) Successful in 22s
Build and Test / linux-linux-gcc / shared (pull_request) Has been cancelled
Build and Test / linux-linux-gcc / static (pull_request) Has been cancelled
Build and Test / linux-windows-mingw (build only) / shared (pull_request) Has been cancelled
Build and Test / linux-windows-mingw (build only) / static (pull_request) Has been cancelled
QA / cert (pull_request) Has been cancelled
to a6e6db0209
Some checks failed
C++ Compatibility / C++ Compatibility Check (pull_request) Successful in 22s
Documentation / build-docs (pull_request) Successful in 24s
QA / cert (pull_request) Successful in 48s
Build and Test / linux-linux-gcc / shared (pull_request) Failing after 1m0s
Build and Test / linux-linux-gcc / static (pull_request) Failing after 1m0s
Build and Test / linux-windows-mingw (build only) / shared (pull_request) Successful in 56s
Build and Test / linux-windows-mingw (build only) / static (pull_request) Successful in 56s
2026-11-15 23:49:05 +01:00
Compare
OragonEfreet force-pushed feat/txt-01 from a6e6db0209
Some checks failed
C++ Compatibility / C++ Compatibility Check (pull_request) Successful in 22s
Documentation / build-docs (pull_request) Successful in 24s
QA / cert (pull_request) Successful in 48s
Build and Test / linux-linux-gcc / shared (pull_request) Failing after 1m0s
Build and Test / linux-linux-gcc / static (pull_request) Failing after 1m0s
Build and Test / linux-windows-mingw (build only) / shared (pull_request) Successful in 56s
Build and Test / linux-windows-mingw (build only) / static (pull_request) Successful in 56s
to 389a20938a
Some checks failed
C++ Compatibility / C++ Compatibility Check (pull_request) Successful in 21s
Documentation / build-docs (pull_request) Successful in 20s
QA / cert (pull_request) Successful in 41s
Build and Test / linux-linux-gcc / shared (pull_request) Failing after 57s
Build and Test / linux-linux-gcc / static (pull_request) Failing after 59s
Build and Test / linux-windows-mingw (build only) / shared (pull_request) Successful in 57s
Build and Test / linux-windows-mingw (build only) / static (pull_request) Successful in 1m0s
2026-11-16 14:37:19 +01:00
Compare
OragonEfreet force-pushed feat/txt-01 from 389a20938a
Some checks failed
C++ Compatibility / C++ Compatibility Check (pull_request) Successful in 21s
Documentation / build-docs (pull_request) Successful in 20s
QA / cert (pull_request) Successful in 41s
Build and Test / linux-linux-gcc / shared (pull_request) Failing after 57s
Build and Test / linux-linux-gcc / static (pull_request) Failing after 59s
Build and Test / linux-windows-mingw (build only) / shared (pull_request) Successful in 57s
Build and Test / linux-windows-mingw (build only) / static (pull_request) Successful in 1m0s
to 9c33e051b6
Some checks failed
C++ Compatibility / C++ Compatibility Check (pull_request) Successful in 22s
Documentation / build-docs (pull_request) Successful in 24s
QA / cert (pull_request) Successful in 50s
Build and Test / linux-linux-gcc / shared (pull_request) Failing after 1m1s
Build and Test / linux-linux-gcc / static (pull_request) Failing after 1m2s
Build and Test / linux-windows-mingw (build only) / shared (pull_request) Successful in 57s
Build and Test / linux-windows-mingw (build only) / static (pull_request) Successful in 57s
2026-11-16 14:44:02 +01:00
Compare
Seven spec suites each carried their own allocator that fails one
allocation of a chosen number. They now share the one of mock_memory.h:
mock_count_allocations, mock_fail_allocation, mock_allocation_count and
mock_stop_counting.

The copy of spec_textwrapper.c handed a null user data to the mock, so the
allocations of its out-of-memory cases escaped the leak accounting. They
are counted now, and all of them are freed. spec_window.c failed the next
malloc only; it now fails call number 0, which is that same malloc.

AI-Generated: yes
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QyvSwnqf7RLGEVjGgWyTdU
chore(test): add 'should fail' tests
All checks were successful
C++ Compatibility / C++ Compatibility Check (pull_request) Successful in 21s
Documentation / build-docs (pull_request) Successful in 19s
QA / cert (pull_request) Successful in 38s
Build and Test / linux-linux-gcc / shared (pull_request) Successful in 1m0s
Build and Test / linux-linux-gcc / static (pull_request) Successful in 1m4s
Build and Test / linux-windows-mingw (build only) / shared (pull_request) Successful in 55s
Build and Test / linux-windows-mingw (build only) / static (pull_request) Successful in 56s
6ea4615ee4
With `bj_cli::extra` set, the first positional value beyond the
positional descriptors ends the parsing: it and every argument after it,
options and `--` included, are handed back as a `struct bj_cli_extra`, an
argc/argv view into argv, on success only. The usage line ends with
`[...]`, and bj_validate_cli refuses an argument that stores into the
extra destination.

Two crashes are fixed on the way: a negative argument count, which
bj_parse_cli accepts with a NULL argv, no longer reads past it, and a
NULL argument among the counted ones fails the parse.

cli-001 gains Rules 13 and 14 and rows in Rules 6, 7, 8 and 11, and
examples/cli.c shows the extra arguments.

AI-Generated: yes
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QyvSwnqf7RLGEVjGgWyTdU
test.h reads its flags through bj_parse_cli: --stop-at-error,
--show-output, which lets the cases write to standard output, -h/--help,
and the names of the cases to run. With names, main runs a collecting
pass first, and an unknown name exits with status 2 before any case
runs.

After each case, the runner puts back the allocators the program runs
on, the mock by default, so a case stopped with the failing allocator
armed cannot pass it on; spec_mem declares that it runs on the C
library's. The mock's realloc of NULL now allocates, as realloc does.

The framework's portable cases move to unit_test_framework_portable.c,
which Windows builds too.

AI-Generated: yes
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QyvSwnqf7RLGEVjGgWyTdU
.
All checks were successful
C++ Compatibility / C++ Compatibility Check (pull_request) Successful in 21s
Documentation / build-docs (pull_request) Successful in 19s
QA / cert (pull_request) Successful in 39s
Build and Test / linux-linux-gcc / shared (pull_request) Successful in 1m0s
Build and Test / linux-linux-gcc / static (pull_request) Successful in 1m5s
Build and Test / linux-windows-mingw (build only) / shared (pull_request) Successful in 55s
Build and Test / linux-windows-mingw (build only) / static (pull_request) Successful in 58s
2984a2bd59
OragonEfreet force-pushed feat/txt-01 from 2984a2bd59
All checks were successful
C++ Compatibility / C++ Compatibility Check (pull_request) Successful in 21s
Documentation / build-docs (pull_request) Successful in 19s
QA / cert (pull_request) Successful in 39s
Build and Test / linux-linux-gcc / shared (pull_request) Successful in 1m0s
Build and Test / linux-linux-gcc / static (pull_request) Successful in 1m5s
Build and Test / linux-windows-mingw (build only) / shared (pull_request) Successful in 55s
Build and Test / linux-windows-mingw (build only) / static (pull_request) Successful in 58s
to ee8d691ac0
Some checks failed
C++ Compatibility / C++ Compatibility Check (pull_request) Successful in 21s
Documentation / build-docs (pull_request) Successful in 20s
QA / cert (pull_request) Successful in 38s
Build and Test / linux-linux-gcc / static (pull_request) Has been cancelled
Build and Test / linux-windows-mingw (build only) / shared (pull_request) Has been cancelled
Build and Test / linux-windows-mingw (build only) / static (pull_request) Has been cancelled
Build and Test / linux-linux-gcc / shared (pull_request) Has been cancelled
2026-11-16 22:57:18 +01:00
Compare
OragonEfreet force-pushed feat/txt-01 from ee8d691ac0
Some checks failed
C++ Compatibility / C++ Compatibility Check (pull_request) Successful in 21s
Documentation / build-docs (pull_request) Successful in 20s
QA / cert (pull_request) Successful in 38s
Build and Test / linux-linux-gcc / static (pull_request) Has been cancelled
Build and Test / linux-windows-mingw (build only) / shared (pull_request) Has been cancelled
Build and Test / linux-windows-mingw (build only) / static (pull_request) Has been cancelled
Build and Test / linux-linux-gcc / shared (pull_request) Has been cancelled
to eda828195c
All checks were successful
C++ Compatibility / C++ Compatibility Check (pull_request) Successful in 21s
Documentation / build-docs (pull_request) Successful in 24s
QA / cert (pull_request) Successful in 48s
Build and Test / linux-linux-gcc / shared (pull_request) Successful in 1m3s
Build and Test / linux-linux-gcc / static (pull_request) Successful in 1m4s
Build and Test / linux-windows-mingw (build only) / shared (pull_request) Successful in 55s
Build and Test / linux-windows-mingw (build only) / static (pull_request) Successful in 57s
2026-11-16 22:58:57 +01:00
Compare
OragonEfreet force-pushed feat/txt-01 from eda828195c
All checks were successful
C++ Compatibility / C++ Compatibility Check (pull_request) Successful in 21s
Documentation / build-docs (pull_request) Successful in 24s
QA / cert (pull_request) Successful in 48s
Build and Test / linux-linux-gcc / shared (pull_request) Successful in 1m3s
Build and Test / linux-linux-gcc / static (pull_request) Successful in 1m4s
Build and Test / linux-windows-mingw (build only) / shared (pull_request) Successful in 55s
Build and Test / linux-windows-mingw (build only) / static (pull_request) Successful in 57s
to 08b5aa3d6a
All checks were successful
C++ Compatibility / C++ Compatibility Check (pull_request) Successful in 21s
Documentation / build-docs (pull_request) Successful in 15s
QA / cert (pull_request) Successful in 37s
Build and Test / linux-linux-gcc / shared (pull_request) Successful in 1m2s
Build and Test / linux-linux-gcc / static (pull_request) Successful in 1m4s
Build and Test / linux-windows-mingw (build only) / shared (pull_request) Successful in 55s
Build and Test / linux-windows-mingw (build only) / static (pull_request) Successful in 57s
2026-11-16 23:24:55 +01:00
Compare
OragonEfreet force-pushed feat/txt-01 from 08b5aa3d6a
All checks were successful
C++ Compatibility / C++ Compatibility Check (pull_request) Successful in 21s
Documentation / build-docs (pull_request) Successful in 15s
QA / cert (pull_request) Successful in 37s
Build and Test / linux-linux-gcc / shared (pull_request) Successful in 1m2s
Build and Test / linux-linux-gcc / static (pull_request) Successful in 1m4s
Build and Test / linux-windows-mingw (build only) / shared (pull_request) Successful in 55s
Build and Test / linux-windows-mingw (build only) / static (pull_request) Successful in 57s
to 055b42008f
All checks were successful
C++ Compatibility / C++ Compatibility Check (pull_request) Successful in 21s
Documentation / build-docs (pull_request) Successful in 16s
QA / cert (pull_request) Successful in 38s
Build and Test / linux-linux-gcc / shared (pull_request) Successful in 1m3s
Build and Test / linux-linux-gcc / static (pull_request) Successful in 1m5s
Build and Test / linux-windows-mingw (build only) / shared (pull_request) Successful in 55s
Build and Test / linux-windows-mingw (build only) / static (pull_request) Successful in 56s
2026-11-17 23:35:15 +01:00
Compare
.
All checks were successful
C++ Compatibility / C++ Compatibility Check (pull_request) Successful in 19s
Documentation / build-docs (pull_request) Successful in 14s
QA / cert (pull_request) Successful in 40s
Build and Test / linux-linux-gcc / shared (pull_request) Successful in 50s
Build and Test / linux-linux-gcc / static (pull_request) Successful in 58s
Build and Test / linux-windows-mingw (build only) / shared (pull_request) Successful in 46s
Build and Test / linux-windows-mingw (build only) / static (pull_request) Successful in 41s
42c6a82fbd
chore: update .gitignore
All checks were successful
C++ Compatibility / C++ Compatibility Check (pull_request) Successful in 21s
Documentation / build-docs (pull_request) Successful in 20s
QA / cert (pull_request) Successful in 47s
Build and Test / linux-linux-gcc / shared (pull_request) Successful in 1m3s
Build and Test / linux-linux-gcc / static (pull_request) Successful in 39s
Build and Test / linux-windows-mingw (build only) / shared (pull_request) Successful in 55s
Build and Test / linux-windows-mingw (build only) / static (pull_request) Successful in 55s
95d01e272a
All checks were successful
C++ Compatibility / C++ Compatibility Check (pull_request) Successful in 21s
Documentation / build-docs (pull_request) Successful in 20s
QA / cert (pull_request) Successful in 47s
Build and Test / linux-linux-gcc / shared (pull_request) Successful in 1m3s
Build and Test / linux-linux-gcc / static (pull_request) Successful in 39s
Build and Test / linux-windows-mingw (build only) / shared (pull_request) Successful in 55s
Build and Test / linux-windows-mingw (build only) / static (pull_request) Successful in 55s
This pull request is marked as a work in progress.
View command line instructions

Checkout

From your project repository, check out a new branch and test the changes.
git fetch -u origin feat/txt-01:feat/txt-01
git switch feat/txt-01

Merge

Merge the changes and update on Forgejo.

Warning: The "Autodetect manual merge" setting is not enabled for this repository, you will have to mark this pull request as manually merged afterwards.

git switch main
git merge --no-ff feat/txt-01
git switch feat/txt-01
git rebase main
git switch main
git merge --ff-only feat/txt-01
git switch feat/txt-01
git rebase main
git switch main
git merge --no-ff feat/txt-01
git switch main
git merge --squash feat/txt-01
git switch main
git merge --ff-only feat/txt-01
git switch main
git merge feat/txt-01
git push origin main
Sign in to join this conversation.
No reviewers
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
OragonEfreet/banjo!203
No description provided.