refactor(render): TextBackend owns its atlas, and staged glyphs carry a rotation basis

include/plot/render/bitmap_font.hpp

@@ -12,22 +12,22 @@ namespace plot::render {
 /// font file, FreeType or stb_truetype: `plot_core` stays dependency-free.
 ///
 /// Metrics are proportional, not fixed width: an advance is the glyph's ink
-/// width plus one pixel of spacing, floored at two pixels, computed once when
-/// the font is constructed from the same bitmaps the atlas uploads. Whitespace
-/// is a blank glyph with a nonzero advance, and every codepoint without a glyph
-/// draws a visible box, so a missing glyph is obvious rather than silently
-/// blank.
+/// width plus one pixel of spacing, floored at two pixels, derived from the
+/// same bitmaps the atlas uploads, so a second width table cannot drift from the
+/// artwork. Whitespace is a blank glyph with a nonzero advance, and every
+/// codepoint without a glyph draws a visible box, so a missing glyph is obvious
+/// rather than silently blank.
 ///
-/// Metrics are in unscaled font pixels, one per glyph texel. The text pipeline
-/// draws a cell `u_px_range` pixels across, so a run at another size measures
-/// `measure(utf8) * u_px_range.x / kGlyphPx`; `TextBatch::add_text` takes that
-/// cell size and applies the same scale to the pen it advances.
+/// Metrics are in unscaled font pixels, one per glyph texel, and the atlas is a
+/// grid of `kGlyphPx` cells: every glyph's rect is its own cell, so a run drawn
+/// at `s` pixels per font pixel measures `measure(utf8) * s` and sits in a cell
+/// of `s * kGlyphPx` pixels. `TextBatch::add_text` takes that factor and applies
+/// it to the pen it advances.
 class BitmapFont final : public TextBackend {
  public:
-  // Atlas geometry. It is part of the render pipeline's contract: the text
-  // vertex shader expands a glyph cell by `u_px_range` pixels and reads the cell
-  // at the instance's texel origin, so the atlas is a grid of 8x8 cells whose
-  // width must stay a whole number of cells.
+  // Atlas geometry: a grid of `kGlyphPx` cells whose width is a whole number of
+  // them. A glyph's rect is its own cell, normalised by these sizes, so the grid
+  // is all the text pipeline has to know about the atlas.
   static constexpr u32 kGlyphPx = 8;      ///< glyph cell edge, texels
   static constexpr u32 kFirstChar = 32;   ///< U+0020
   static constexpr u32 kAsciiGlyphs = 95; ///< U+0020..U+007E
@@ -42,17 +42,7 @@ class BitmapFont final : public TextBackend {
   static constexpr u32 kAtlasHeight = kAtlasRows * kGlyphPx;   ///< 56 texels
   static_assert(kAtlasCols * kAtlasRows >= kGlyphCount, "atlas too small for the glyph set");
 
-  /// Reported by `next_codepoint` for a byte sequence that is not valid UTF-8.
-  /// It is not a Unicode scalar value, so it can only map to the fallback box.
-  static constexpr u32 kInvalidCodepoint = 0xFFFFFFFFu;
-
-  /// Decodes one UTF-8 sequence from `p` and advances `p` past it — one byte
-  /// when the sequence is malformed, so a damaged label still terminates. The
-  /// text batch and `measure` share it, which is what keeps a staged run exactly
-  /// `measure`-wide.
-  static u32 next_codepoint(const char*& p) noexcept;
-
-  BitmapFont() noexcept;
+  BitmapFont() noexcept = default;
 
   /// Width of `utf8`, the sum of the glyph advances: zero for the empty string
   /// and for null. The ASCII path allocates nothing.
@@ -75,6 +65,21 @@ class BitmapFont final : public TextBackend {
   /// codepoints `format_si` emits map to real glyphs, and anything else maps to
   /// the visible missing-glyph box.
   static u32 glyph_index(u32 codepoint) noexcept;
+  /// The glyph for `codepoint`: its atlas cell as a normalised rect (see
+  /// `Glyph`), a zero bearing and its ink-derived advance. Never null -- a
+  /// codepoint with no artwork maps to the visible missing-glyph box, which is
+  /// what a label outside the coverage set should show.
+  const Glyph* glyph(u32 codepoint) const override;
+
+  /// The packed atlas, as `TextBackend` sees it: the bytes `atlas_image()`
+  /// returns, `kAtlasWidth` by `kAtlasHeight`, GL_R8-ready. Never null.
+  const u8* atlas_pixels() const override;
+  u32 atlas_width() const override;
+  u32 atlas_height() const override;
+
+  /// Always zero: the atlas is a compile-time constant, so it never changes and
+  /// the renderer uploads it once.
+  u32 revision() const override;
 
   /// Rows in a glyph bitmap, always `kGlyphPx`.
   u32 glyph_rows(char c) const noexcept;
@@ -90,12 +95,16 @@ class BitmapFont final : public TextBackend {
   /// (straight alpha, no dilation or gamma applied).
   static const u8* atlas_image() noexcept;
 
-  /// Texel origin of a glyph slot in the atlas; this is the per-instance `a_uv`
-  /// the text pipeline reads.
+  /// Texel origin of a glyph slot in the atlas, in texels; `glyph()` gives the
+  /// same rectangle normalised, which is what the text pipeline stages.
   static Vec2 atlas_origin(u32 slot) noexcept;
 
  private:
-  f32 advances_[kGlyphCount];
+  /// Every slot's rect, bearing and advance, derived from the bitmaps above at
+  /// compile time. This replaced a per-instance `advances_` array holding the
+  /// same numbers, so the advances the pen uses and the ones `glyph()` publishes
+  /// cannot drift apart.
+  static const Glyph* glyph_table() noexcept;
 };
 
 }  // namespace plot::render

include/plot/render/buffer.hpp

@@ -16,17 +16,37 @@ struct LineInstance {
   f32 y1;
 };
 
-/// Per-instance payload of the text pipeline: the glyph quad's top-left corner
-/// in Rect pixels plus the glyph's atlas texel origin.
+/// Per-instance payload of the text pipeline: one glyph cell.
+///
+/// - `(x, y)` is the cell's top-left corner in Rect pixels, top-left origin like
+///   `plot::Rect`. `TextBatch` already applied the glyph's bearing along the
+///   basis, so this is the corner the shader grows the cell from.
+/// - `(u, v)` is the glyph rect's **normalised top-left** in the atlas, with `v`
+///   increasing *downward* -- the convention `Glyph` states, so `(u, v)` is the
+///   rect's top-left texel and the cell spans `(u, v)..(u + w, v + h)`, where
+///   `(w, h)` is the glyph cell's normalised size (a per-draw uniform: every
+///   glyph a batch stages comes from one atlas and occupies a cell of one size).
+/// - `(ax, ay)` is the glyph's local +x axis -- the direction the run advances
+///   in -- as a **unit vector in pixels**. It is what rotates the cell: the
+///   shader builds it from `(ax, ay)` and its perpendicular, and maps the glyph's
+///   rect onto the two the same way round, so a cell is never mirrored. `(1, 0)`
+///   is unrotated text, and `(0, -1)` is a run advancing up the screen, i.e. a
+///   90 degree counter-clockwise label such as a y-axis title.
+///
+/// Six floats, so the whole text pipeline still fits one instanced draw call per
+/// frame with rotation free: a matrix per glyph would be three times the bytes
+/// for the same pixels.
 struct TextInstance {
   f32 x;
   f32 y;
   f32 u;
   f32 v;
+  f32 ax;
+  f32 ay;
 };
 
 static_assert(sizeof(LineInstance) == 4 * sizeof(f32), "line instance must stay 4 floats");
-static_assert(sizeof(TextInstance) == 4 * sizeof(f32), "text instance must stay 4 floats");
+static_assert(sizeof(TextInstance) == 6 * sizeof(f32), "text instance must stay 6 floats");
 
 /// How a store's staged instances reach the GPU. Semantics are identical either
 /// way -- only the transfer differs, and `Renderer::init()` picks one from

include/plot/render/primitives.hpp

@@ -1,7 +1,7 @@
 #pragma once
 #include <plot/core/types.hpp>
 #include <plot/math/vec2.hpp>
-#include <plot/render/bitmap_font.hpp>
+#include <plot/render/text.hpp>
 
 #include <vector>
 
@@ -55,41 +55,64 @@ class LineBatch {
 /// CPU-side staging for one instanced text draw call.
 ///
 /// Like `LineBatch` it keeps its capacity across frames. Each staged glyph is
-/// one instance: the glyph quad's top-left corner in pixels, top-left origin
-/// like `plot::Rect`, plus the glyph's atlas texel origin, interleaved as
-/// `x,y,u,v` — the layout the text shader declares (see buffer.hpp).
+/// one instance: the glyph cell's top-left corner in pixels, the glyph rect's
+/// normalised top-left in the atlas and the cell's rotation basis, interleaved as
+/// `x,y,u,v,ax,ay` — the layout the text shader declares (see `TextInstance` in
+/// buffer.hpp).
+///
+/// Every glyph a batch stages is read through one atlas rect of one size — its
+/// cell — so that size is recorded once (`glyph_cell_uv()`) and handed to the
+/// draw, rather than riding along with every instance.
 class TextBatch {
  public:
-  /// Starts a frame: empties the batch, keeps its capacity.
+  /// Starts a frame: empties the batch and the staged cell, keeps the capacity.
   void begin() noexcept;
   /// Same as `begin()`.
   void clear() noexcept;
 
-  /// Stages one glyph cell at `pos_px` (its top-left corner), reading the cell
-  /// from `slot` in the font atlas (see `BitmapFont::atlas_origin`). `slot`
-  /// indexes the atlas, not a codepoint.
-  void add_glyph(Vec2 pos_px, u32 slot);
-
-  /// Stages every codepoint of `utf8` and returns the pen past the last glyph,
-  /// so the run is exactly `font.measure(utf8) * px_per_cell /
-  /// BitmapFont::kGlyphPx` pixels wide — the width the draw covers when it is
-  /// told the same cell size as `u_px_range`.
+  /// Stages one glyph cell whose *pen* is `pen_px`: the cell's top-left corner is
+  /// the pen moved by the glyph's bearing (see `Glyph`), scaled and measured
+  /// along the run's own axes, so a glyph keeps its place inside a rotated run.
   ///
-  /// `px_per_cell` is the on-screen size of one glyph cell: pass
-  /// `BitmapFont::kGlyphPx` for 1:1 text, and anything else to scale the run.
-  /// The glyph quad itself is sized by the shader's `u_px_range`, which must be
-  /// the same value. A null or empty string stages nothing and returns `pen_px`.
-  Vec2 add_text(Vec2 pen_px, const char* utf8, const BitmapFont& font,
-                f32 px_per_cell = static_cast<f32>(BitmapFont::kGlyphPx));
+  /// `px` is the scale: on-screen pixels per font pixel, the factor `measure()`
+  /// is multiplied by — `1.0` draws the glyphs at the size the backend
+  /// rasterised them. `axis` is the direction the run advances in, in pixel
+  /// space; it rotates the cell (see `TextInstance`), and is normalised here, so
+  /// any non-zero direction works and a zero or non-finite one means "unrotated".
+  void add_glyph(Vec2 pen_px, const Glyph& glyph, f32 px = 1.0f,
+                 Vec2 axis = {1.0f, 0.0f});
+
+  /// Stages every codepoint of `utf8` from `pen_px` and returns the pen past the
+  /// last glyph, so the run is exactly `font.measure(utf8) * px` long measured
+  /// along `axis` — the length the plot layer reserved for the label, at the size
+  /// the text pipeline then draws it.
+  ///
+  /// The codepoints and the advances come from the backend itself, through
+  /// `next_codepoint()` and `glyph()`, so a run stages exactly what `measure()`
+  /// summed. A codepoint the backend has no glyph for stages nothing and moves
+  /// the pen nowhere — a run is never wider than the glyphs it can draw. A null
+  /// or empty string stages nothing and returns `pen_px`.
+  Vec2 add_text(const char* utf8, Vec2 pen_px, f32 px, const TextBackend& font,
+                Vec2 axis = {1.0f, 0.0f});
 
   /// Glyphs staged so far, one instance each.
-  u32 glyph_count() const noexcept { return static_cast<u32>(v_.size() / 4u); }
+  u32 glyph_count() const noexcept { return static_cast<u32>(v_.size() / 6u); }
 
-  /// Interleaved `x,y,u,v`, four floats per staged glyph.
+  /// Interleaved `x,y,u,v,ax,ay`, six floats per staged glyph.
   const std::vector<f32>& data() const noexcept { return v_; }
 
+  /// The staged glyphs' cell in the atlas, normalised: `(u1 - u0, v1 - v0)` of
+  /// the glyphs staged, which the draw passes as `u_glyph_uv` (see
+  /// `TextProgram::set_glyph_uv`). `(0, 0)` while nothing is staged.
+  Vec2 glyph_cell_uv() const noexcept { return cell_uv_; }
+
  private:
+  /// Stages one cell whose basis the caller has already normalised, so a run and
+  /// the pen it advances share one rounding of the axis.
+  void add_cell(Vec2 pen_px, const Glyph& glyph, f32 px, Vec2 unit_ux);
+
   std::vector<f32> v_;
+  Vec2 cell_uv_{};
 };
 
 }  // namespace plot::render

include/plot/render/program.hpp

@@ -48,8 +48,14 @@ class TextProgram {
 
   /// `u_viewport`: render target size in pixels.
   void set_viewport(Vec2 px) const noexcept;
-  /// `u_px_range`: pixels per glyph cell, i.e. the on-screen size of one glyph.
+  /// `u_px_range`: the glyph cell's size on screen, in pixels (width and
+  /// height -- a cell need not be square).
   void set_px_range(Vec2 px) const noexcept;
+  /// `u_glyph_uv`: the glyph cell's size in the atlas, normalised. It is the
+  /// rect every staged glyph is read through, so it is one size per draw: a
+  /// batch stages glyphs from one atlas, and `TextBatch::glyph_cell_uv()` is
+  /// where it comes from.
+  void set_glyph_uv(Vec2 uv) const noexcept;
   /// `u_tex_size`: atlas size in texels.
   void set_texture_size(Vec2 texels) const noexcept;
   /// `u_color`: tint colour, alpha included.

include/plot/render/renderer.hpp

@@ -6,7 +6,6 @@
 #include <plot/core/rect.hpp>
 #include <plot/core/status.hpp>
 #include <plot/core/types.hpp>
-#include <plot/gl/handle.hpp>
 #include <plot/math/vec2.hpp>
 #include <plot/plot/plot.hpp>
 #include <plot/render/bitmap_font.hpp>
@@ -14,6 +13,7 @@
 #include <plot/render/primitives.hpp>
 #include <plot/render/program.hpp>
 #include <plot/render/style.hpp>
+#include <plot/render/text_atlas.hpp>
 #include <plot/render/vertex_array.hpp>
 
 namespace plot {
@@ -70,7 +70,7 @@ class Renderer {
   Renderer(const Renderer&) = delete;
   Renderer& operator=(const Renderer&) = delete;
 
-  /// Compiles both programs, builds the glyph atlas and allocates the vertex
+  /// Compiles both programs, uploads the font's atlas and allocates the vertex
   /// buffers. The calling thread must have the context current and
   /// `plot::gl::load()` must have succeeded, otherwise the returned `Status` is
   /// `Unsupported`; anything the driver refuses is `GLFailure` plus its log.
@@ -114,13 +114,17 @@ class Renderer {
   /// vertex array 0, program 0, `GL_ARRAY_BUFFER` 0, texture unit 0 active and
   /// nothing bound to `GL_TEXTURE_2D` on it, blending off, scissoring off, and the
   /// viewport left at the frame's rect (the caller sets its own for the next pass).
-  /// Two pieces of global state the frame *changed* are handed back rather than
-  /// left where the frame wanted them: `GL_UNPACK_ALIGNMENT`, which `init()` set
-  /// to 1 for the glyph atlas' single-channel rows, and the clear colour, which is
+  /// The one piece of global state the frame *changed* is handed back rather than
+  /// left where the frame wanted it: the clear colour, which is
   /// `style().background` only for the duration of the frame. GL keeps no history
-  /// for the clear colour, so the host's value is queried on the first
-  /// `begin_frame()`; that first value is what comes back here, so a colour the
-  /// host changes after the first frame is restored over by it.
+  /// for it, so the host's value is queried on the first `begin_frame()`; that
+  /// first value is what comes back here, so a colour the host changes after the
+  /// first frame is restored over by it.
+  ///
+  /// `GL_UNPACK_ALIGNMENT` is deliberately not in that list any more: the atlas
+  /// upload needs it at 1 for single-channel rows, and `render::TextAtlas` saves
+  /// and restores it around every upload it performs, so no frame -- initial or
+  /// mid-run -- leaves it moved for the host's own uploads to inherit.
   /// The framebuffer binding is never touched -- it is the caller's, and so is the
   /// pixel-pack alignment if `dump_frame_ppm()` ran.
   void end_frame() noexcept;
@@ -176,19 +180,40 @@ class Renderer {
   /// by whole multiples of its cell only -- anything else lands a 1-bit glyph's
   /// strokes unevenly -- so `reset()` picks the multiple nearest the requested
   /// size.
+  ///
+  /// It is also the backend the renderer uploads the atlas from, so it forwards
+  /// the whole interface: the metrics and the glyph bearings and advances are
+  /// scaled, while the artwork itself -- the atlas bytes, its size and its
+  /// revision -- is the font's own and passes through untouched.
   class AxisFont final : public render::TextBackend {
    public:
     void reset(const render::BitmapFont& font, f32 requested_px) noexcept;
     f32 measure(const char* utf8) const override;
     f32 height() const override;
     f32 ascent() const override;
+    /// The font's glyph at this wrapper's scale: the atlas rect is unchanged (it
+    /// is scale-free) and the bearing and advance are multiplied by it, so one
+    /// `Glyph` describes the glyph this backend draws. The result lives in the
+    /// wrapper until the next call, which is enough for a caller measuring or
+    /// laying out one glyph at a time.
+    const render::Glyph* glyph(u32 codepoint) const override;
+    const u8* atlas_pixels() const override;
+    u32 atlas_width() const override;
+    u32 atlas_height() const override;
+    u32 revision() const override;
     /// On-screen size of one glyph cell, in pixels.
     f32 cell_px() const noexcept { return cell_px_; }
+    /// On-screen pixels per font pixel: the factor `measure()` and `glyph()` are
+    /// scaled by, and what `TextBatch::add_text` is handed as its size.
+    f32 scale() const noexcept { return scale_; }
 
    private:
     const render::BitmapFont* font_ = nullptr;
     f32 cell_px_ = 1.0f;
     f32 scale_ = 1.0f;
+    /// `glyph()`'s scaled result, returned by pointer because the interface is
+    /// `const Glyph*` and the scale is the one thing this wrapper adds.
+    mutable render::Glyph scaled_{};
   };
 
   /// One axis pair's data -> pixel mapping, already shifted so the viewport's
@@ -254,7 +279,7 @@ class Renderer {
   AxisFont font_backend_;
   render::Style style_;
 
-  gl::Texture atlas_;
+  render::TextAtlas atlas_;
   render::LineProgram line_program_;
   render::TextProgram text_program_;
   render::LineVertexArray line_vao_;
@@ -265,9 +290,6 @@ class Renderer {
   std::vector<f32> gather_;   ///< scratch for one gathered window, re-used
   mutable std::vector<u8> readback_;  ///< dump_frame_ppm's row buffer
 
-  /// The host's `GL_UNPACK_ALIGNMENT`, saved by `init()` before the atlas upload
-  /// set it to 1 and handed back by `end_frame()`. GL's default is 4.
-  gl::GLint host_unpack_alignment_ = 4;
   /// The host's `GL_COLOR_CLEAR_VALUE`, queried on the first `begin_frame()` (GL
   /// has no other way to recover it once the frame has set it) and handed back by
   /// `end_frame()`.

include/plot/render/shaders.hpp

@@ -30,16 +30,24 @@ extern const char* const kLineFS;
 
 /// GLSL source of the instanced text pipeline.
 ///
-/// One glyph cell per instance: `a_pos` at location 0 is the quad's top-left
-/// corner in Rect pixels and `a_uv` at location 1 is the glyph's atlas texel
-/// origin, both with a vertex attribute divisor of 1. The quad grows by
-/// `u_px_range` pixels per cell and the fragment shader samples the
+/// One glyph cell per instance, every attribute with a vertex attribute divisor
+/// of 1: `a_pos` at location 0 is the cell's top-left corner in Rect pixels,
+/// `a_uv` at location 1 is the glyph rect's normalised top-left in the atlas and
+/// `a_axis` at location 2 is the cell's local +x axis, a unit vector in pixels.
+///
+/// The vertex shader builds the cell from that basis and its perpendicular --
+/// the cell's own +v direction -- so `a_axis` of `(0, -1)` draws a run that
+/// advances up the screen, and it maps `a_uv` over the cell with the same
+/// handedness, so a glyph's top row stays its top row however the cell is
+/// turned. The fragment shader converts back to texels and samples the
 /// single-channel `GL_R8` atlas at the nearest texel centre, so `GL_NEAREST`
 /// never lands on a cell boundary. `u_color` tints the straight alpha.
 ///
-/// Uniforms: `u_viewport` (vec2, pixels), `u_px_range` (vec2, pixels per glyph
-/// cell), `u_tex_size` (vec2, atlas texels), `u_atlas` (sampler2D, unit 0),
-/// `u_color` (vec4).
+/// Uniforms: `u_viewport` (vec2, pixels), `u_px_range` (vec2, the glyph cell's
+/// size on screen in pixels), `u_glyph_uv` (vec2, the glyph cell's size in
+/// normalised atlas coordinates -- one size for the whole draw, since every
+/// glyph of a frame comes from one atlas), `u_tex_size` (vec2, atlas size in
+/// texels), `u_atlas` (sampler2D, unit 0), `u_color` (vec4).
 extern const char* const kTextVS;
 extern const char* const kTextFS;
 

include/plot/render/text.hpp

@@ -3,13 +3,70 @@
 
 namespace plot::render {
 
-/// Text metrics the plot layer lays axes and labels out with. It is a pure
-/// interface so the layout code never depends on the bitmap font, and so a
-/// caller can measure with a host toolkit's font instead.
+/// One glyph's atlas rectangle and metrics, in font pixels.
+///
+/// **The rectangle is normalised, v grows downward.** `(u0, v0)` is the glyph's
+/// top-left atlas texel and `(u1, v1)` its bottom-right, each divided by the
+/// atlas' size -- so the atlas is stored with its top row first, exactly the row
+/// order `atlas_pixels()` hands over, and a larger `v` is a row further down.
+/// Text is laid out with the same handedness: a glyph's own +y runs from `v0`
+/// toward `v1`, which on screen is downward when the glyph is unrotated. A
+/// backend that rasterised its atlas bottom row first would draw every glyph
+/// mirrored unless it divided `v` the other way, so the convention is stated
+/// once, here, and every consumer -- the text shader's UVs, the vertex shader's
+/// second cell axis, `TextBatch` -- uses it and nothing else.
+///
+/// `(xoff, yoff)` is the bearing from the pen to the glyph's top-left corner
+/// (top-left origin, font pixels) and `advance` is how far the pen moves along
+/// the baseline. Both are in font pixels, so a caller scaling a run multiplies
+/// them by the same factor it draws the atlas with.
+struct Glyph {
+  f32 u0 = 0.0f;
+  f32 v0 = 0.0f;
+  f32 u1 = 0.0f;
+  f32 v1 = 0.0f;
+  f32 xoff = 0.0f;
+  f32 yoff = 0.0f;
+  f32 advance = 0.0f;
+};
+
+/// A byte sequence that is not valid UTF-8, as reported by `next_codepoint`. It
+/// is deliberately not a Unicode scalar value, so it can only map to whatever a
+/// backend draws for "no glyph" rather than colliding with a real codepoint.
+inline constexpr u32 kInvalidCodepoint = 0xFFFFFFFFu;
+
+/// Decodes one UTF-8 sequence from `p` and advances `p` past it -- one byte when
+/// the sequence is malformed, so a damaged label still terminates.
+///
+/// It belongs to this interface rather than to a font because it is what keeps a
+/// backend's `measure()` and the glyphs the pipeline stages for the same string
+/// in step: both walk the string with this decoder, so neither can disagree with
+/// the other about where a codepoint starts.
+u32 next_codepoint(const char*& p) noexcept;
+
+/// The font a `Plot` measures with and the renderer draws with: metrics, plus the
+/// coverage atlas the text pipeline samples.
 ///
 /// Text is passed as UTF-8, not as a byte-per-character string: `plot::format_si`
 /// emits U+00B5, U+00B0 and U+03A9 for micro, degree and ohm, and an
 /// implementation that ignores that prints mojibake.
+///
+/// The atlas is the backend's own: it owns the pixels, the glyph table that
+/// describes them and the `revision()` that says when they changed. The renderer
+/// uploads whatever the backend exposes and re-uploads when the revision moves,
+/// so a backend can be swapped -- or re-baked at another size -- without the
+/// renderer knowing anything about fonts. `measure()`/`height()`/`ascent()` are
+/// in the atlas' font pixels: the pipeline scales them, never re-rasterises.
+///
+/// **One atlas, one cell size.** A staged glyph carries the *origin* of its rect
+/// and the draw carries the rect's size, once, for every instance in it (see
+/// `TextProgram::set_glyph_uv`) -- which is what keeps a glyph at six floats while
+/// still letting it be rotated. So every glyph a backend publishes must occupy a
+/// rect of the same size: its cell, with the ink inside it at `(xoff, yoff)`. A
+/// proportional face therefore bakes each glyph into a cell wide enough for the
+/// widest advance and spends the atlas area rather than the correctness; a
+/// backend whose rects differ in size would have its glyphs read through
+/// whichever rect was staged first.
 class TextBackend {
  public:
   TextBackend() noexcept = default;
@@ -17,8 +74,8 @@ class TextBackend {
   TextBackend& operator=(const TextBackend&) = default;
   virtual ~TextBackend() = default;
 
-  /// Width of `utf8` in the same units as `height()` (pixels for the bitmap
-  /// font). Zero for the empty string.
+  /// Width of `utf8` in the same units as `height()` (font pixels for a font
+  /// atlas). Zero for the empty string.
   virtual f32 measure(const char* utf8) const = 0;
 
   /// Line height: the cell a single line of text occupies.
@@ -27,6 +84,29 @@ class TextBackend {
   /// Distance from the top of the cell to the baseline, so a caller can align
   /// text bottoms instead of cell bottoms.
   virtual f32 ascent() const = 0;
+
+  /// The glyph for `codepoint`, or null when this backend has none -- the caller
+  /// then draws nothing for it (a backend that wants a visible missing-glyph box
+  /// publishes one as the glyph for the codepoints it cannot render). The
+  /// returned pointer stays valid for the backend's lifetime, so callers may hold
+  /// it across a frame.
+  virtual const Glyph* glyph(u32 codepoint) const = 0;
+
+  /// 8-bit single-channel coverage, row-major, `atlas_width() * atlas_height()`
+  /// bytes, top row first. Uploaded as GL_R8. Null is legal and means "no text".
+  virtual const u8* atlas_pixels() const = 0;
+
+  /// Atlas size in texels. Zero width or height means "no text", like a null
+  /// `atlas_pixels()`.
+  virtual u32 atlas_width() const = 0;
+  virtual u32 atlas_height() const = 0;
+
+  /// Bumped whenever `atlas_pixels()` content changes, so the renderer knows to
+  /// re-upload instead of trusting its cache. Must not change otherwise -- a
+  /// revision that moves on its own would re-upload the same bytes every frame --
+  /// and any change counts, so a backend may re-bake at a new size and keep
+  /// counting up.
+  virtual u32 revision() const = 0;
 };
 
 }  // namespace plot::render

include/plot/render/text_atlas.hpp

@@ -0,0 +1,80 @@
+#pragma once
+#include <plot/core/status.hpp>
+#include <plot/core/types.hpp>
+#include <plot/gl/handle.hpp>
+#include <plot/math/vec2.hpp>
+#include <plot/render/text.hpp>
+
+namespace plot::render {
+
+/// The GPU side of a `TextBackend`'s atlas.
+///
+/// The atlas belongs to the backend, so the renderer does not decide what it
+/// contains or how big it is: `sync()` uploads whatever `atlas_pixels()` points
+/// at, as a single-channel `GL_R8` image of `atlas_width()` by `atlas_height()`,
+/// and re-uploads exactly when the backend's `revision()` changes. Keying that
+/// cache on the revision rather than on a flag set once is what makes a font
+/// swap, or a re-bake at another size, visible -- a cached atlas left in place
+/// draws the previous font's glyphs and nothing in the pixels says why.
+///
+/// It is also where the atlas upload's `GL_UNPACK_ALIGNMENT` excursion is
+/// contained: `Texture::upload_r8` needs 1 for single-channel rows and leaves it
+/// there, so every upload here saves the caller's value and puts it back --
+/// whether it runs in `Renderer::init()` or in the middle of a frame, which is
+/// why the renderer's frame no longer has to carry that value around one.
+///
+/// Nearest filtering, always: the shader reads the texel centre of a glyph cell,
+/// and linear filtering would smear one cell into its neighbour.
+class TextAtlas {
+ public:
+  TextAtlas() noexcept = default;
+  TextAtlas(const TextAtlas&) = delete;
+  TextAtlas& operator=(const TextAtlas&) = delete;
+  TextAtlas(TextAtlas&&) noexcept = default;
+  TextAtlas& operator=(TextAtlas&&) noexcept = default;
+  ~TextAtlas() = default;
+
+  /// Brings the texture up to date with `backend`, and does nothing at all when
+  /// it already is: the same revision as the last successful upload means the
+  /// bytes on the GPU are the ones that revision describes. Any change counts,
+  /// including one that moves the revision backwards, so a backend that
+  /// re-bakes is never mistaken for one that did not.
+  ///
+  /// A null atlas, or one with a zero width or height, is legal and means "no
+  /// text": nothing is uploaded, `empty()` stays true and the resulting draw
+  /// stages nothing. The revision is recorded even then, so a backend whose
+  /// atlas never appears is not re-checked every frame -- the contract is that a
+  /// backend which *starts* providing one bumps its revision.
+  ///
+  /// False, with `st` filled in, when the driver refuses the texture; the last
+  /// successful upload is left in place and the next call retries.
+  bool sync(const TextBackend& backend, Status* st = nullptr) noexcept;
+
+  /// Binds to `unit` (texture unit 0 by default, which is where the text
+  /// program's sampler points).
+  void bind(gl::GLenum unit = gl::GL_TEXTURE0) const noexcept;
+
+  /// Atlas size in texels; `(0, 0)` while nothing has been uploaded.
+  Vec2 texel_size() const noexcept {
+    return Vec2{static_cast<f32>(width_), static_cast<f32>(height_)};
+  }
+
+  /// True while no atlas is on the GPU: there is no text to draw, and `bind()`
+  /// would bind nothing.
+  bool empty() const noexcept { return texture_.id() == 0; }
+
+  /// The revision of the atlas currently on the GPU. Meaningless before the
+  /// first `sync()`, which is the one call that always uploads.
+  u32 revision() const noexcept { return revision_; }
+
+ private:
+  gl::Texture texture_;
+  u32 revision_ = 0;
+  u32 width_ = 0;
+  u32 height_ = 0;
+  /// False until a revision has been recorded, so a backend whose `revision()`
+  /// is 0 is still uploaded once instead of being mistaken for "already there".
+  bool synced_ = false;
+};
+
+}  // namespace plot::render

include/plot/render/vertex_array.hpp

@@ -55,13 +55,16 @@ class LineVertexArray {
 };
 
 /// Vertex array plus instance buffer of the text pipeline: `a_pos` at location 0
-/// and the glyph's atlas texel origin `a_uv` at location 1, two floats each,
-/// advancing once per instance.
+/// (the cell's top-left corner in pixels), the glyph's atlas rect `a_uv` at
+/// location 1 and its rotation basis `a_axis` at location 2, two floats each,
+/// every one advancing once per instance. The layout is the one `TextInstance`
+/// declares and shaders.hpp consumes; a caller never writes a location, stride or
+/// offset, it stages a `TextBatch` and uploads its `data()`.
 class TextVertexArray {
  public:
   bool create(Status* st = nullptr, UploadMode mode = UploadMode::Orphan) noexcept;
 
-  /// Uploads `glyphs` instances from interleaved `x,y,u,v` floats.
+  /// Uploads `glyphs` instances from interleaved `x,y,u,v,ax,ay` floats.
   void upload(const f32* interleaved, u32 glyphs) noexcept;
 
   void bind() const noexcept { vao_.bind(); }