Renderer ABI
Compiled view code doesn’t build a UI tree. It makes a linear series of calls into the
runtime (kura_rt_begin_frame, kura_rt_fill_rect, kura_rt_draw_text,
kura_rt_end_frame, and so on), which forward to a renderer.
A renderer implements one table of function pointers, KuraRendererOps, defined in
Sources/renderer/renderer_abi.h. Nothing outside that header is needed to write one.
Operations
Section titled “Operations”| Operation | Purpose |
|---|---|
begin_frame(self, width, height) |
Start a frame |
end_frame(self) |
Finish and present the frame |
push_clip(self, rect) / pop_clip(self) |
Clip rectangle stack |
fill_rect(self, rect, color) |
Filled rectangle |
stroke_rect(self, rect, color) |
Rectangle outline |
draw_line(self, from, to, color) |
Line |
draw_text(self, pos, utf8, length, style, color) |
Text |
measure_text(self, utf8, length, style, out) |
Text metrics, used by layout |
Points, sizes and rectangles are KuraVec2, KuraVec3 and KuraRect: plain structs of 32-bit floats (x, y;
x, y, z; x, y, width, height), with y growing downward. They are the same floats, in the same order, as the
compiler’s own Vec2, Vec3 and Rect types (see Types), so a rectangle
needs no conversion on its way to a renderer.
Every operation returns a KuraRendererStatus. In debug builds the generated code checks that
status after each draw call (kura_rt_check_renderer).
Compatibility
Section titled “Compatibility”KuraRendererOps starts with a struct_size field. A renderer sets it to
sizeof(KuraRendererOps) as it was built. New operations are only ever added at the end, so a
host reads struct_size to learn which operations an older renderer has.
draw_text and measure_text take a KuraTextStyle: a font size in pixels and a family,
the UTF-8 bytes of a font-family value (not NUL-terminated, with family_length). It is a name or a
comma-separated list in order of preference (Inter, sans-serif), and NULL or a zero length means
the default font. The renderer decides how to keep what it needs per family. The OpenGL renderer keeps a glyph atlas per
font. A family that can’t be found is drawn in the system’s default font, never as an error.
Layout measures text with measure_text before anything is drawn, so a renderer has to measure the way it
draws: the same text, style and renderer always give the same metrics. ascent is the distance from the top
of the box to the baseline of the first line, and draw_text puts the top-left of that box at pos.
The shared text/ library does the shaping (HarfBuzz) and the rasterizing (FreeType), and finds the font for
a family on the system (fontconfig, with a few well-known paths when there is none). A renderer that wants
real text uses it, and one that doesn’t can keep the fixed-width model the headless renderer defaults to.
KURA_RENDERER_ABI_VERSION is 2: version 2 added family to KuraTextStyle.
Renderers in the tree
Section titled “Renderers in the tree”| Renderer | Purpose |
|---|---|
| Headless | Implements the ABI without drawing. Used for unit tests (with GTest). Text is a fixed-width model, or real fonts with shaped_text. |
| Image | Encodes the headless renderer’s framebuffer as PNG/JPEG, for visual regression tests. |
| OpenGL | Draws text with HarfBuzz and a glyph atlas per font. |
| Vulkan | Planned. |
The headless renderer defines the ABI every other renderer follows, and runs without a GPU so that tests are simple.
Viewport
Section titled “Viewport”The viewport size is never fetched through an API. When it changes, the host sends it as a
Message to update.