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_listfills agfx_backend_infofor every id from Vulkan up, compiled in or not, with its name and whether it is compiled and available right now.gfx_backend_checkanswers for one id, and returnsgfx_okonly when it can be chosen on this machine now. The probe is cheap and needs no window.gfx_backend_orderlists the idsgfx_backend_autowalks 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_parsemaps vulkan, metal, d3d12, cpu or auto to an id, and anything else togfx_backend_count.gfx_backend_namegoes 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.
| Status | Text | Meaning |
|---|---|---|
gfx_ok | ok | It worked. |
gfx_not_compiled | not compiled into this build | This build carries no such backend. |
gfx_unavailable | not available on this machine | It is built in, but the probe found nothing here that can run it. |
gfx_init_failed | the renderer did not start | The device came up and the renderer on it did not. |
gfx_invalid | not a backend | Not a backend id at all. A switch attempted inside a frame also returns this. |
gfx_replay_failed | an asset could not be rebuilt on the new renderer | A 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.