Skip to content

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.

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).

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.

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.

The viewport size is never fetched through an API. When it changes, the host sends it as a Message to update.