On this page

gfx_backend.h

What one backend implements. The device registry is the only caller.

#include "isolenui/gfx/gfx_backend.h". The guide starts at Writing a backend.

The backend table

Explained in Writing a backend.

gfx_backend_vtbl::set_presentgfx_backend_vtbl::set_transparentgfx_backend_vtblgfx_vulkan_backendgfx_metal_backendgfx_cpu_backend

Registry limits and handle bits

Explained in Assets and handles.

GFX_MAX_DEVICESGFX_MAX_IMAGESGFX_MAX_SVGSGFX_MAX_FONTSGFX_MAX_LISTENERSGFX_HANDLE_DEVICE_SHIFTGFX_HANDLE_REUSE_SHIFTgfx_handle_slot

Example

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
};

Last updated 23 October 2026