On this page

Choosing a backend

gfx_backend_id is an append only enum: gfx_backend_auto, vulkan, metal, d3d12 and cpu, then gfx_backend_count. A build only carries some of them, and a machine can only run some of the ones it carries.

Asking what is available

  • gfx_backend_list fills a gfx_backend_info for every id from Vulkan up, compiled in or not, with its name and whether it is compiled and available right now.
  • gfx_backend_check answers for one id, and returns gfx_ok only when it can be chosen on this machine now. The probe is cheap and needs no window.
  • gfx_backend_order lists the ids gfx_backend_auto walks on this platform. The first valid one wins. On Windows that is Vulkan, D3D12 and CPU, where D3D12 is not built yet and is skipped. On mac it is Metal then CPU, so the CPU backend is always the last resort.
  • gfx_backend_parse maps vulkan, metal, d3d12, cpu or auto to an id, and anything else to gfx_backend_count. gfx_backend_name goes the other way.
backends_choose.cpp
#include "isolenui/gfx/gfx.h"

#include <stdio.h>

// list every backend id and say what this build carries and what this
// machine can actually run right now
static void print_backends(void)
{
    gfx_backend_info info[gfx_backend_count];
    const uint32_t n = gfx_backend_list(info, gfx_backend_count);
    for (uint32_t i = 0; i < n; ++i) {
        const gfx_status status = gfx_backend_check(info[i].id);
        printf("%-8s compiled=%d available=%d check=%s\n", info[i].name,
               int(info[i].compiled), int(info[i].available),
               gfx_status_text(status));
    }
}

// the command line's --backend name funnels through gfx_backend_parse
// before it ever reaches gfx_desc::preferred or gfx_open
static gfx_backend_id backend_from_flag(const char* name)
{
    const gfx_backend_id id = gfx_backend_parse(name);
    if (id == gfx_backend_count) {
        // not a backend name at all, fall back to auto
        return gfx_backend_auto;
    }
    return id;
}

// the order gfx_backend_auto walks on this platform, first valid one wins,
// which is also the order gfx_open falls back along on a refused preference
static void print_fallback_order(void)
{
    gfx_backend_id order[gfx_backend_count];
    const uint32_t n = gfx_backend_order(order, gfx_backend_count);
    for (uint32_t i = 0; i < n; ++i) {
        printf("%u: %s\n", i, gfx_backend_name(order[i]));
    }
}

Status codes

Every status maps to a reason through gfx_status_text.

StatusTextMeaning
gfx_okokIt worked.
gfx_not_compilednot compiled into this buildThis build carries no such backend.
gfx_unavailablenot available on this machineIt is built in, but the probe found nothing here that can run it.
gfx_init_failedthe renderer did not startThe device came up and the renderer on it did not.
gfx_invalidnot a backendNot a backend id at all. A switch attempted inside a frame also returns this.
gfx_replay_failedan asset could not be rebuilt on the new rendererA switch started the new renderer, but an image, svg or font would not rebuild on it.

Opening with a preference

gfx_open takes a gfx_desc whose preferred id is only a preference. If that backend cannot run, the device falls back along the platform order with a warning. chosen reports what came up, and the call returns null with why set only when nothing on this machine can run. The app shell passes isolen_app_desc::backend through, after the command line flags have had their say.

Last updated 6 October 2026