rgame 0.1.0

data/ext/rgame_core/text/font_atlas.c

@@ -0,0 +1,385 @@
+/*
+ * font_atlas.c — the one file in the text stack that touches GL.
+ *
+ * Everything interesting about text is elsewhere and pure: font.c knows what
+ * glyphs measure and look like, atlas.c knows where the next one goes on a
+ * page, glyph_cache.c knows which have been done already. This composes the
+ * three, owns the GL textures behind the pages, and reads the font file. That
+ * is layer 3 in CLAUDE.md's abstraction strategy, and it is kept this thin
+ * precisely so "we don't unit-test it directly" is honest rather than a gap —
+ * `spec_core/rgame/core/font_spec.rb` and the renderer's pixel checks exercise
+ * it end to end against a real GL context.
+ *
+ * ---------------------------------------------------------------------------
+ * Why the pages are GL_ALPHA
+ * ---------------------------------------------------------------------------
+ *
+ * A rasterised glyph is coverage: one byte per pixel saying how much ink is
+ * there. Uploading that as RGBA would cost four times the memory to say the
+ * same thing three redundant ways.
+ *
+ * An alpha texture under the fixed-function default (GL_MODULATE) gives
+ * `rgb = the vertex colour, a = vertex alpha * coverage`, which is exactly what
+ * coloured text is. No shader, no second code path in the backend — the glyph
+ * quads go through the same textured-quad call sprites do.
+ *
+ * Worth knowing for the day the project moves to core-profile GL: GL_ALPHA does
+ * not exist there. The equivalent is GL_RED plus a swizzle in a shader.
+ */
+
+#include "rgame/core.h"
+
+#include "app/app_gl.h"
+#include "text/atlas.h"
+#include "text/font.h"
+#include "text/font_internal.h"
+#include "text/glyph_cache.h"
+
+#include <SDL2/SDL_opengl.h>
+#include <stdio.h>
+#include <stdlib.h>
+
+/*
+ * Big enough that a Latin character set fits on one page — a few hundred glyphs
+ * at the sizes a game uses — and small enough that a font nobody draws much
+ * with has not cost a megabyte. 256 KB per page, one byte per pixel.
+ *
+ * A page that fills is not a problem: another one opens, and the only cost is
+ * that a string spanning both takes two draw calls instead of one.
+ */
+#define RGAME_FONT_PAGE_SIZE 512
+
+typedef struct {
+    unsigned int texture; /* GL name */
+    rgame_atlas atlas;
+} rgame_font_page;
+
+struct rgame_font {
+    rgame_app *app; /* retained, like an image's — see image.c */
+    rgame_typeface *typeface;
+    rgame_glyph_cache cache;
+
+    rgame_font_page *pages;
+    int page_count, page_capacity;
+
+    /* Reused for every rasterisation rather than malloc'd per glyph. Grown to
+     * the largest glyph seen and never shrunk; a font's biggest glyph is small
+     * and is met within the first few words. */
+    unsigned char *scratch;
+    size_t scratch_size;
+};
+
+/* See rgame_font_live_pages. Single-threaded, like the rest of the engine. */
+static long live_pages = 0;
+
+long rgame_font_live_pages(void) {
+    return live_pages;
+}
+
+/* ------------------------------------------------------------------------- *
+ * Pages
+ * ------------------------------------------------------------------------- */
+
+/*
+ * Allocates a blank page on the GPU. The caller must already have made the
+ * font's GL context current.
+ *
+ * The page is uploaded zeroed rather than left undefined: the gutters between
+ * glyphs are sampled by linear filtering at every glyph's edge, and undefined
+ * memory there is a fringe of noise around every letter.
+ */
+static int add_page(rgame_font *font) {
+    if (font->page_count == font->page_capacity) {
+        int capacity = font->page_capacity ? font->page_capacity * 2 : 2;
+        rgame_font_page *pages = realloc(font->pages, sizeof(rgame_font_page) * (size_t)capacity);
+        if (!pages) {
+            return 0;
+        }
+        font->pages = pages;
+        font->page_capacity = capacity;
+    }
+
+    unsigned char *blank = calloc(RGAME_FONT_PAGE_SIZE * RGAME_FONT_PAGE_SIZE, 1);
+    if (!blank) {
+        return 0;
+    }
+
+    unsigned int texture = 0;
+    glGenTextures(1, &texture);
+    if (texture == 0) {
+        free(blank);
+        return 0;
+    }
+
+    glBindTexture(GL_TEXTURE_2D, texture);
+    /* One byte per pixel and an arbitrary glyph width, so GL's default
+     * four-byte row alignment would shear every upload. */
+    glPixelStorei(GL_UNPACK_ALIGNMENT, 1);
+    /* Linear, unlike sprites: text is not pixel art, and stb hands us
+     * antialiased coverage that nearest sampling would throw away. */
+    glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MIN_FILTER, GL_LINEAR);
+    glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MAG_FILTER, GL_LINEAR);
+    glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_WRAP_S, GL_CLAMP_TO_EDGE);
+    glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_WRAP_T, GL_CLAMP_TO_EDGE);
+    glTexImage2D(GL_TEXTURE_2D, 0, GL_ALPHA, RGAME_FONT_PAGE_SIZE, RGAME_FONT_PAGE_SIZE, 0,
+                 GL_ALPHA, GL_UNSIGNED_BYTE, blank);
+    glBindTexture(GL_TEXTURE_2D, 0);
+
+    free(blank);
+
+    rgame_font_page *page = &font->pages[font->page_count++];
+    page->texture = texture;
+    rgame_atlas_init(&page->atlas, RGAME_FONT_PAGE_SIZE, RGAME_FONT_PAGE_SIZE);
+    live_pages++;
+    return 1;
+}
+
+/* ------------------------------------------------------------------------- *
+ * Loading
+ * ------------------------------------------------------------------------- */
+
+static void set_error(char *err, size_t err_size, const char *format, const char *detail) {
+    if (err && err_size > 0) {
+        snprintf(err, err_size, format, detail);
+    }
+}
+
+/* Same shape as image.c's reader: the engine decides how a missing file is
+ * reported, not the library that parses what is in it. */
+static unsigned char *read_whole_file(const char *path, long *out_size) {
+    FILE *file = fopen(path, "rb");
+    if (!file) {
+        return NULL;
+    }
+
+    if (fseek(file, 0, SEEK_END) != 0) {
+        fclose(file);
+        return NULL;
+    }
+    long size = ftell(file);
+    if (size <= 0) {
+        fclose(file);
+        return NULL;
+    }
+    rewind(file);
+
+    unsigned char *bytes = malloc((size_t)size);
+    if (!bytes) {
+        fclose(file);
+        return NULL;
+    }
+
+    size_t got = fread(bytes, 1, (size_t)size, file);
+    fclose(file);
+    if (got != (size_t)size) {
+        free(bytes);
+        return NULL;
+    }
+
+    *out_size = size;
+    return bytes;
+}
+
+rgame_font *rgame_font_load(rgame_app *app, const char *path, int pixel_height, char *err,
+                            size_t err_size) {
+    if (!app || !path) {
+        set_error(err, err_size, "%s", "no app or path given");
+        return NULL;
+    }
+    if (pixel_height <= 0) {
+        set_error(err, err_size, "%s", "a font size must be positive");
+        return NULL;
+    }
+
+    long size = 0;
+    unsigned char *bytes = read_whole_file(path, &size);
+    if (!bytes) {
+        set_error(err, err_size, "could not read %s", path);
+        return NULL;
+    }
+
+    rgame_font *font = calloc(1, sizeof(rgame_font));
+    if (!font) {
+        free(bytes);
+        set_error(err, err_size, "%s", "out of memory");
+        return NULL;
+    }
+
+    /* The face copies what it needs, so the file buffer goes straight back. */
+    font->typeface = rgame_typeface_open(bytes, (size_t)size, pixel_height);
+    free(bytes);
+    if (!font->typeface) {
+        free(font);
+        set_error(err, err_size, "could not read %s as a TrueType font", path);
+        return NULL;
+    }
+
+    rgame_glyph_cache_init(&font->cache);
+    rgame_app_gl_retain(app);
+    font->app = app;
+
+    /* No page yet. A font that is only ever measured — a layout pass that never
+     * draws — costs no video memory at all. */
+    return font;
+}
+
+void rgame_font_destroy(rgame_font *font) {
+    if (!font) {
+        return;
+    }
+
+    if (font->page_count > 0) {
+        /* Deleting a texture acts on whatever context is current, so say which
+         * and put back what was there — a collector picks this moment, quite
+         * possibly in the middle of another window's frame. If the app is
+         * already gone the pages went with its context, and there is nothing
+         * to delete. */
+        rgame_gl_context_save saved;
+        if (rgame_app_gl_make_current(font->app, &saved)) {
+            for (int i = 0; i < font->page_count; i++) {
+                glDeleteTextures(1, &font->pages[i].texture);
+            }
+        }
+        rgame_app_gl_restore(&saved);
+        live_pages -= font->page_count;
+    }
+
+    free(font->pages);
+    free(font->scratch);
+    rgame_glyph_cache_destroy(&font->cache);
+    rgame_typeface_close(font->typeface);
+    rgame_app_gl_release(font->app);
+    free(font);
+}
+
+/* ------------------------------------------------------------------------- *
+ * Queries
+ * ------------------------------------------------------------------------- */
+
+int rgame_font_height(const rgame_font *font) {
+    return font ? rgame_typeface_height(font->typeface) : 0;
+}
+
+float rgame_font_measure(const rgame_font *font, const char *text, size_t length) {
+    /* Measuring touches no GL and needs no page, so it works outside a frame —
+     * which matters, because laying out a menu happens in update, not draw. */
+    return font ? rgame_typeface_measure(font->typeface, text, length) : 0.0f;
+}
+
+const rgame_typeface *rgame_font_typeface(const rgame_font *font) {
+    return font ? font->typeface : NULL;
+}
+
+rgame_app *rgame_font_owner(const rgame_font *font) {
+    return font ? font->app : NULL;
+}
+
+/* ------------------------------------------------------------------------- *
+ * Rasterising on demand
+ * ------------------------------------------------------------------------- */
+
+/* Packs a glyph onto a page with room for it, opening a new one if the last is
+ * full. Returns the page index, or -1. */
+static int place_on_a_page(rgame_font *font, int width, int height, rgame_rect *out) {
+    if (font->page_count > 0 &&
+        rgame_atlas_place(&font->pages[font->page_count - 1].atlas, width, height, out)) {
+        return font->page_count - 1;
+    }
+
+    if (!add_page(font)) {
+        return -1;
+    }
+    if (!rgame_atlas_place(&font->pages[font->page_count - 1].atlas, width, height, out)) {
+        /* Bigger than a whole page. Nothing to be done for it, and a fresh page
+         * would refuse it too — so give up on this glyph rather than opening a
+         * page per attempt for the rest of the run. */
+        return -1;
+    }
+    return font->page_count - 1;
+}
+
+static int ensure_scratch(rgame_font *font, size_t needed) {
+    if (font->scratch_size >= needed) {
+        return 1;
+    }
+
+    unsigned char *scratch = realloc(font->scratch, needed);
+    if (!scratch) {
+        return 0;
+    }
+    font->scratch = scratch;
+    font->scratch_size = needed;
+    return 1;
+}
+
+int rgame_font_glyph(rgame_font *font, int codepoint, rgame_glyph *out, unsigned int *texture,
+                     int *page_width, int *page_height) {
+    if (!font || !out) {
+        return 0;
+    }
+
+    if (page_width) {
+        *page_width = RGAME_FONT_PAGE_SIZE;
+    }
+    if (page_height) {
+        *page_height = RGAME_FONT_PAGE_SIZE;
+    }
+
+    if (rgame_glyph_cache_find(&font->cache, codepoint, out)) {
+        if (texture) {
+            *texture = font->pages[out->page].texture;
+        }
+        return 1;
+    }
+
+    rgame_glyph glyph;
+    if (!rgame_typeface_glyph(font->typeface, codepoint, &glyph)) {
+        return 0;
+    }
+
+    /*
+     * A glyph with no ink — a space — is cached with an empty rectangle and
+     * never touches a page or the GPU. Its advance is the whole reason it is
+     * cached at all.
+     */
+    if (glyph.rect.w > 0 && glyph.rect.h > 0) {
+        rgame_gl_context_save saved;
+        if (!rgame_app_gl_make_current(font->app, &saved)) {
+            rgame_app_gl_restore(&saved);
+            return 0;
+        }
+
+        rgame_rect placed;
+        int page = place_on_a_page(font, glyph.rect.w, glyph.rect.h, &placed);
+        size_t pixels = (size_t)glyph.rect.w * (size_t)glyph.rect.h;
+
+        if (page < 0 || !ensure_scratch(font, pixels)) {
+            rgame_app_gl_restore(&saved);
+            return 0;
+        }
+
+        rgame_typeface_render(font->typeface, codepoint, font->scratch, glyph.rect.w,
+                              glyph.rect.w, glyph.rect.h);
+
+        glBindTexture(GL_TEXTURE_2D, font->pages[page].texture);
+        glPixelStorei(GL_UNPACK_ALIGNMENT, 1);
+        glTexSubImage2D(GL_TEXTURE_2D, 0, placed.x, placed.y, placed.w, placed.h, GL_ALPHA,
+                        GL_UNSIGNED_BYTE, font->scratch);
+        glBindTexture(GL_TEXTURE_2D, 0);
+
+        rgame_app_gl_restore(&saved);
+
+        glyph.page = page;
+        glyph.rect = placed;
+    }
+
+    /* A cache that could not grow is not fatal: the glyph is drawn from what
+     * was just rasterised and simply gets rasterised again next time. */
+    rgame_glyph_cache_insert(&font->cache, &glyph);
+
+    *out = glyph;
+    if (texture) {
+        *texture = glyph.rect.w > 0 ? font->pages[glyph.page].texture : 0;
+    }
+    return 1;
+}

data/ext/rgame_core/text/font_internal.h

@@ -0,0 +1,47 @@
+#ifndef RGAME_FONT_INTERNAL_H
+#define RGAME_FONT_INTERNAL_H
+
+#include "text/font.h"
+#include "rgame/core.h"
+
+/*
+ * What the drawing path needs from inside an `rgame_font`.
+ *
+ * `rgame_font` is opaque in the public header and stays that way — a caller
+ * outside this extension has no business knowing what an atlas page is. But
+ * app.c has to walk a string and place its glyphs, so the accessors live here,
+ * in a header that is not under include/ and therefore cannot leave
+ * ext/rgame_core/. Same arrangement as image_internal.h.
+ */
+
+/* The face behind the font, for measuring and walking a string. */
+const rgame_typeface *rgame_font_typeface(const rgame_font *font);
+
+/* The app whose GL context the atlas pages live in, or NULL. Compared against
+ * the app being drawn into, for the same reason images are — a texture from
+ * another context samples nothing and paints white. */
+rgame_app *rgame_font_owner(const rgame_font *font);
+
+/*
+ * A glyph ready to draw: cached if it has been seen, and otherwise rasterised,
+ * packed onto a page and uploaded on the spot.
+ *
+ * Also reports which GL texture to bind and how big it is, since the caller
+ * needs both to turn the glyph's page rectangle into texture coordinates.
+ *
+ * Returns 1 on success, 0 if the glyph could not be made — out of memory, or an
+ * atlas page that refused a glyph bigger than a whole page. A caller should
+ * skip that glyph and carry on drawing the rest of the string.
+ *
+ * Uploading mid-frame is fine: uploads happen immediately while drawing is
+ * deferred, so the page is complete long before the frame is submitted.
+ */
+int rgame_font_glyph(rgame_font *font, int codepoint, rgame_glyph *out, unsigned int *texture,
+                     int *page_width, int *page_height);
+
+/* How many atlas pages exist across all live fonts — for tests, the way
+ * rgame_texture_live_sheets is for images. A leaked page is invisible
+ * otherwise. */
+long rgame_font_live_pages(void);
+
+#endif /* RGAME_FONT_INTERNAL_H */

data/ext/rgame_core/text/glyph_cache.c

@@ -0,0 +1,142 @@
+/*
+ * glyph_cache.c — an open-addressed table of rasterised glyphs.
+ * See glyph_cache.h for why it caches per glyph and why nothing is ever evicted.
+ */
+
+#include "text/glyph_cache.h"
+
+#include <stdlib.h>
+
+/* Small enough that a font drawing only digits wastes nothing, big enough that
+ * plain ASCII text never rehashes. */
+#define RGAME_GLYPH_CACHE_MIN_CAPACITY 64
+
+/* Grow at 3/4 full. Linear probing degrades sharply as a table approaches
+ * full — the probe walk turns into a scan — so the table is kept loose. */
+#define RGAME_GLYPH_CACHE_LOAD_NUMERATOR 3
+#define RGAME_GLYPH_CACHE_LOAD_DENOMINATOR 4
+
+void rgame_glyph_cache_init(rgame_glyph_cache *cache) {
+    cache->entries = NULL;
+    cache->capacity = 0;
+    cache->count = 0;
+}
+
+void rgame_glyph_cache_destroy(rgame_glyph_cache *cache) {
+    if (!cache) {
+        return;
+    }
+
+    free(cache->entries);
+    /* Left in the state init would produce, so a second destroy is a no-op and
+     * a find afterwards is an ordinary miss rather than a use-after-free. */
+    rgame_glyph_cache_init(cache);
+}
+
+/*
+ * Knuth's multiplicative hash, masked to the table size.
+ *
+ * Note what this is *not*: a correctness requirement. Replacing it with the
+ * identity function leaves every test passing, and rightly so — linear probing
+ * resolves collisions whatever the hash does, so a worse one is slower, not
+ * wrong. That mutation survives the suite deliberately.
+ *
+ * It stays because the cost is one multiply and the alternative is a bet on the
+ * key distribution. Identity happens to spread the codepoints a Latin game
+ * draws almost perfectly, since they arrive in contiguous runs (ASCII 32..126,
+ * Latin-1 accents, a handful of punctuation). The bet is on the next game:
+ * masking the low bits of a table this small means an emoji range, or CJK, or
+ * any set whose members share their low bits, lands in a few buckets and turns
+ * every lookup into a walk. Not worth finding out.
+ */
+static unsigned int slot_for(int codepoint, unsigned int capacity) {
+    return ((unsigned int)codepoint * 2654435761u) & (capacity - 1);
+}
+
+/*
+ * The slot a codepoint occupies, or the first free one after where it would be.
+ *
+ * One walk answers both "is it here?" and "where does it go?", which is what
+ * lets insert find an existing entry and replace it rather than adding a
+ * second. Nothing is ever deleted, so there are no tombstones to skip and the
+ * walk stops at the first empty slot.
+ *
+ * Terminates because the table is never allowed to fill.
+ */
+static rgame_glyph *probe(rgame_glyph *entries, unsigned int capacity, int codepoint) {
+    unsigned int slot = slot_for(codepoint, capacity);
+
+    for (;;) {
+        rgame_glyph *entry = &entries[slot];
+        if (entry->codepoint == 0 || entry->codepoint == codepoint) {
+            return entry;
+        }
+        slot = (slot + 1) & (capacity - 1);
+    }
+}
+
+/* Reallocates into a bigger table and re-probes every entry — slots depend on
+ * the capacity, so the old positions mean nothing in the new table. */
+static int grow(rgame_glyph_cache *cache) {
+    unsigned int capacity = cache->capacity ? cache->capacity * 2
+                                            : RGAME_GLYPH_CACHE_MIN_CAPACITY;
+
+    rgame_glyph *entries = calloc(capacity, sizeof(rgame_glyph));
+    if (!entries) {
+        return 0;
+    }
+
+    for (unsigned int i = 0; i < cache->capacity; i++) {
+        if (cache->entries[i].codepoint != 0) {
+            *probe(entries, capacity, cache->entries[i].codepoint) = cache->entries[i];
+        }
+    }
+
+    free(cache->entries);
+    cache->entries = entries;
+    cache->capacity = capacity;
+    return 1;
+}
+
+int rgame_glyph_cache_find(const rgame_glyph_cache *cache, int codepoint, rgame_glyph *out) {
+    if (!cache || !out || !cache->entries || codepoint == 0) {
+        return 0;
+    }
+
+    const rgame_glyph *entry = probe(cache->entries, cache->capacity, codepoint);
+    if (entry->codepoint != codepoint) {
+        return 0;
+    }
+
+    *out = *entry;
+    return 1;
+}
+
+int rgame_glyph_cache_insert(rgame_glyph_cache *cache, const rgame_glyph *glyph) {
+    if (!cache || !glyph || glyph->codepoint == 0) {
+        return 0; /* 0 is the empty marker; storing it would hide the entry */
+    }
+
+    /* Grown *before* the insert, not after, so the table can never be full at
+     * the moment probe() walks it — that walk has no exit condition other than
+     * finding a free slot. */
+    if ((cache->count + 1) * RGAME_GLYPH_CACHE_LOAD_DENOMINATOR >=
+        cache->capacity * RGAME_GLYPH_CACHE_LOAD_NUMERATOR) {
+        if (!grow(cache)) {
+            return 0;
+        }
+    }
+
+    rgame_glyph *entry = probe(cache->entries, cache->capacity, glyph->codepoint);
+    /* An existing entry is overwritten in place, so the count only moves when
+     * the codepoint is genuinely new. */
+    if (entry->codepoint == 0) {
+        cache->count++;
+    }
+    *entry = *glyph;
+    return 1;
+}
+
+unsigned int rgame_glyph_cache_count(const rgame_glyph_cache *cache) {
+    return cache ? cache->count : 0;
+}

data/ext/rgame_core/text/glyph_cache.h

@@ -0,0 +1,89 @@
+#ifndef RGAME_GLYPH_CACHE_H
+#define RGAME_GLYPH_CACHE_H
+
+#include "graphics/clip.h"
+
+/*
+ * What has already been rasterised, and where it went. Pure — no font, no
+ * atlas, no GL; this module knows only that a codepoint maps to a rectangle
+ * and some numbers.
+ *
+ * ---------------------------------------------------------------------------
+ * Per glyph, never per string
+ * ---------------------------------------------------------------------------
+ *
+ * A game draws a lot of short-lived, always-changing strings: a score, a timer,
+ * a coordinate readout. Caching those *as strings* would grow one entry per
+ * distinct string ever displayed, which for a timer is one per frame, forever.
+ * Caching per glyph bounds the whole thing by the character set instead — a few
+ * hundred entries for a Latin game, and it stops growing the moment the player
+ * has seen every digit.
+ *
+ * That is also why there is **no eviction**. There is nothing to evict: the
+ * cache cannot outgrow the glyph set the game actually draws, and dropping a
+ * glyph would only mean rasterising it again next frame. A cache with no
+ * eviction has no tombstones, no ages and no policy to get wrong, which is most
+ * of why this file is short.
+ *
+ * ---------------------------------------------------------------------------
+ * Open addressing
+ * ---------------------------------------------------------------------------
+ *
+ * One flat array, probed linearly, keyed by codepoint. No node per glyph, so
+ * lookup is a hash and a walk over adjacent memory — which matters because this
+ * is on the per-character path of every string drawn.
+ *
+ * Codepoint 0 marks an empty slot. That costs nothing: 0 is NUL, which is never
+ * a glyph anyone draws, and inserting it is refused rather than quietly
+ * corrupting the table.
+ */
+
+/* One cached glyph: where its pixels are, and how to place them. */
+typedef struct {
+    int codepoint;
+    int page; /* which atlas page holds it */
+    /* Where on that page, in pixels. Empty for a glyph with no ink, such as a
+     * space — which is still cached, because its advance is worth keeping. */
+    rgame_rect rect;
+
+    /* How far the pen moves after drawing it, in pixels at the font's size. */
+    float advance;
+    /* Where the pixels sit relative to the pen: x from the pen position, y from
+     * the *top of the line box* rather than the baseline, because that is the
+     * corner a caller passes to `text`. Converting once, here, keeps the
+     * baseline out of every drawing calculation downstream. */
+    float bearing_x, bearing_y;
+} rgame_glyph;
+
+typedef struct {
+    rgame_glyph *entries; /* NULL until the first insert */
+    unsigned int capacity; /* always a power of two, or 0 */
+    unsigned int count;
+} rgame_glyph_cache;
+
+/* An empty cache that has allocated nothing. A font that never draws text
+ * therefore costs nothing beyond this struct. */
+void rgame_glyph_cache_init(rgame_glyph_cache *cache);
+
+/* Frees the table. Safe on an empty cache, and safe to call twice. */
+void rgame_glyph_cache_destroy(rgame_glyph_cache *cache);
+
+/* Writes the cached glyph and returns 1, or returns 0 and leaves `out`
+ * untouched. */
+int rgame_glyph_cache_find(const rgame_glyph_cache *cache, int codepoint, rgame_glyph *out);
+
+/*
+ * Stores a glyph, replacing any entry for the same codepoint. Returns 1 on
+ * success and 0 if the codepoint is 0 or the table could not grow.
+ *
+ * A failed insert is not fatal to the caller: the glyph simply is not cached,
+ * and gets rasterised again next time. Slow, but correct — which is the right
+ * failure mode for a cache.
+ */
+int rgame_glyph_cache_insert(rgame_glyph_cache *cache, const rgame_glyph *glyph);
+
+/* How many distinct codepoints are cached. Bounded by the character set the
+ * game draws, which is the property the whole design rests on. */
+unsigned int rgame_glyph_cache_count(const rgame_glyph_cache *cache);
+
+#endif /* RGAME_GLYPH_CACHE_H */