On this page

Writing a backend

A backend implements every function pointer in gfx_backend_vtbl and exposes one extern const instance, the same shape as gfx_vulkan_backend, gfx_metal_backend and gfx_cpu_backend. The device registry is the only caller.

The table

  • probe is cheap, repeatable and needs no window. It returns true when this machine can run the backend.
  • open returns the backend's own opaque state, which owns every native object. A null return is a failed open, whatever why says.
  • resize, set_vsync, set_clear and wait_idle follow the device calls of the same names.
  • set_transparent(state, on) makes the surface carry premultiplied alpha to the compositor, or stop. It returns true only when the surface now really does, which is what gfx_surface_alpha reports. A backend that cannot returns false and the frame stays opaque.
  • frame_begin fills the gfx_frame, including the native encoder and target that level two code reads. frame_draw(state, list, scale, view) copies a list into the backend's buffers, and frame_end presents. A null view draws at identity, and the device already turns an identity gfx_view into null.
  • The asset calls upload and free images, svgs and fonts. resident_bytes feeds gfx_stats.
  • set_present(state, hz, depth) is optional and may be null. A backend without it presents on its own cadence. See present pacing.

The Vulkan and Metal backends draw a list through one shared replay in isolenui/gfx/gfx_replay.h. gfx_replay_draw pushes every run of a list into a gfx_passes and flushes the layers in order, and gfx_replay_rewind keeps the records already encoded this frame and starts the runs over. A host with a renderer of its own fills gfx_passes the same way, so a list draws alike through either. A new backend with different native passes does not need it.

gfx_replay_draw takes a last, optional const pass_view* zoom. With one, a zoomed draw renders into a target zoom times larger, shifted by the view, so every pass keeps its own mapping and only the scissor, the rounded mask and the curve joints have to learn the shift. The curve pass carries it as an off pair in its push constants, which are 32 bytes on both backends. The CPU backend takes the other route and rewrites each record on the way in.

Rounded clip masks

Every gfx_run and gfx_art carries a gfx_mask, a rounded box its records are cut to on top of the scissor. gfx_mask_on says whether there is one, and gfx_mask_px(m, sx, sy, out) turns it into target pixels as x0 y0 x1 y1 and then the four radii, top left, top right, bottom right, bottom left, the layout every fragment stage in the engine reads. The engine's passes carry it in their push constants and multiply each fragment's alpha by its coverage of the rounded box. Records the list found clear of every corner are stored with no mask at all. A backend that ignores the mask draws rounded clips square. See the draw list.

Shadows in the rect pass

gfx_shadow records an ordinary gfx_rect whose border is minus the blur's sigma, with the box already grown by the spread and three sigma. A rect pass must treat a negative border as a blurred rounded box of that sigma, as the Vulkan, Metal and CPU backends do, or shadows draw as solid rects. See shadows and elevation.

Handles, not slots

Every asset call takes the full handle. The backend keeps one native object per slot, found with gfx_handle_slot(handle, cap). It stores the handle beside the object, and draws a record only when the record's handle matches the stored one. A stale handle from a freed asset therefore draws nothing, even after its slot is reused. See assets and handles for the bit layout.

backends_vtbl.cpp
#include "isolenui/gfx/gfx_backend.h"

// a d3d12 backend would define one of these the same way
// gfx_vulkan_backend, gfx_metal_backend and gfx_cpu_backend do, and an extern next to theirs
// is what lets the registry's per platform table point a slot at it
namespace {

struct d3d12_image {
    uint32_t handle;
    uint32_t width;
    uint32_t height;
};

struct d3d12_state {
    uint64_t frame;
    d3d12_image images[GFX_MAX_IMAGES];
};

d3d12_state g_d3d12_state;

bool d3d12_probe(void)
{
    return true;
}

// a null return is a failed open whatever why says, so a real open hands
// back a real state pointer
void* d3d12_open(window* w, const gfx_desc* d, gfx_status* why)
{
    (void)w;
    (void)d;
    g_d3d12_state = {};
    *why = gfx_ok;
    return &g_d3d12_state;
}

void d3d12_close(void* state) { (void)state; }
bool d3d12_resize(void* state, uint32_t width, uint32_t height)
{
    (void)state;
    (void)width;
    (void)height;
    return true;
}
void d3d12_set_vsync(void* state, bool on) { (void)state; (void)on; }
void d3d12_set_clear(void* state, const float rgba[4]) { (void)state; (void)rgba; }
// true only when the surface really hands premultiplied alpha to the compositor
bool d3d12_set_transparent(void* state, bool on)
{
    (void)state;
    return !on;
}
void d3d12_wait_idle(void* state) { (void)state; }
bool d3d12_frame_begin(void* state, gfx_frame* out)
{
    d3d12_state* s = static_cast<d3d12_state*>(state);
    out->index = s->frame++;
    out->backend = gfx_backend_d3d12;
    out->native_encoder = nullptr;
    out->native_target = nullptr;
    return true;
}

// a record draws only when the handle it carries matches the one stored in
// its slot, so a stale handle from a freed image draws nothing, a null view
// draws at identity
void d3d12_frame_draw(void* state, const gfx_list* list, float scale, const gfx_view* view)
{
    const d3d12_state* s = static_cast<const d3d12_state*>(state);
    for (uint32_t i = 0; i < list->art_count; ++i) {
        const gfx_art& a = list->art[i];
        if (a.kind != gfx_art_image) {
            continue;
        }
        const uint32_t slot = gfx_handle_slot(a.asset, GFX_MAX_IMAGES);
        if (slot == 0xffffffffu || s->images[slot].handle != a.asset) {
            continue;
        }
        // blit s->images[slot] at a.quad times scale here
    }
    (void)scale;
    (void)view;
}
void d3d12_frame_end(void* state) { (void)state; }

// every asset call takes the full handle, the slot comes out of its low bits
bool d3d12_image_upload(void* state, uint32_t handle, const uint8_t* rgba,
                        uint32_t width, uint32_t height, uint32_t flags)
{
    // flags carries gfx_image_no_mips, one level and no rebuild on update
    (void)flags;
    d3d12_state* s = static_cast<d3d12_state*>(state);
    const uint32_t slot = gfx_handle_slot(handle, GFX_MAX_IMAGES);
    if (slot == 0xffffffffu || !rgba) {
        return false;
    }
    s->images[slot] = { handle, width, height };
    return true;
}
// a rect of new pixels, copied before the call returns
bool d3d12_image_update(void* state, uint32_t handle, const uint8_t* rgba, uint32_t stride,
                        uint32_t x, uint32_t y, uint32_t w, uint32_t h)
{
    (void)state;
    (void)handle;
    (void)rgba;
    (void)stride;
    (void)x;
    (void)y;
    (void)w;
    (void)h;
    return false;
}
// a texture the app made itself, refused here
bool d3d12_image_external(void* state, uint32_t handle, const gfx_external_image* d)
{
    (void)state;
    (void)handle;
    (void)d;
    return false;
}
void d3d12_image_free(void* state, uint32_t handle)
{
    d3d12_state* s = static_cast<d3d12_state*>(state);
    const uint32_t slot = gfx_handle_slot(handle, GFX_MAX_IMAGES);
    if (slot != 0xffffffffu && s->images[slot].handle == handle) {
        s->images[slot] = {};
    }
}
bool d3d12_svg_upload(void* state, uint32_t handle, const char* path, float* width,
                    float* height)
{
    (void)state;
    (void)handle;
    (void)path;
    *width = 0.0f;
    *height = 0.0f;
    return false;
}
void d3d12_svg_free(void* state, uint32_t handle) { (void)state; (void)handle; }
bool d3d12_font_upload(void* state, uint32_t handle, const text_font* font)
{
    (void)state;
    (void)handle;
    (void)font;
    return true;
}
void d3d12_font_free(void* state, uint32_t handle) { (void)state; (void)handle; }
uint64_t d3d12_resident_bytes(void* state) { (void)state; return 0u; }

} // namespace

// extern gives the const external linkage so the registry can see it
extern const gfx_backend_vtbl gfx_d3d12_backend = {
    gfx_backend_d3d12,
    "d3d12",
    d3d12_probe,
    d3d12_open,
    d3d12_close,
    d3d12_resize,
    d3d12_set_vsync,
    d3d12_set_clear,
    d3d12_set_transparent,
    d3d12_wait_idle,
    d3d12_frame_begin,
    d3d12_frame_draw,
    d3d12_frame_end,
    d3d12_image_upload,
    d3d12_image_update,
    d3d12_image_external,
    d3d12_image_free,
    d3d12_svg_upload,
    d3d12_svg_free,
    d3d12_font_upload,
    d3d12_font_free,
    d3d12_resident_bytes,
    nullptr, // set_present is optional
};

The registry keeps a per platform table of backends. Adding one means declaring its extern next to the others and pointing that table's slot at it. The example is shaped as the d3d12 backend, whose id is reserved and not yet built. The CPU backend is a full one to read.

Last updated 6 October 2026