On this page

Switching live

gfx_switch, and isolen_set_backend above it, move a running device to another backend without losing a single asset.

How a switch works

  1. The target is checked. gfx_backend_auto resolves to the first valid backend in the platform order.
  2. The old renderer is drained until it is idle, and every switch listener is told gfx_switch_leaving while the old device is still open.
  3. The new renderer is opened beside the old one and sized to the current surface.
  4. Every registered image, svg and font is replayed into the new renderer from the source the registry kept: the file path, or a copy of the pixels.
  5. Only once all of that succeeds is the old renderer closed. Listeners are then told gfx_switch_entered.

Because the new renderer takes every asset before the old one lets go, a failure costs only the new state. A refused switch leaves the device on the backend it was already running, so reading gfx_backend or isolen_backend afterwards always tells the truth. Handles stay valid across a switch.

backends_switch.cpp
#include "isolenui/app/app.h"

#include <stdio.h>

// a refused switch keeps the backend that was already running, so reading
// isolen_backend back afterwards always tells the truth
static void try_switch(isolen_app* app, gfx_backend_id want)
{
    const gfx_status status = isolen_set_backend(app, want);
    switch (status) {
    case gfx_ok:
        isolen_status(app, "now running on %s",
                      gfx_backend_name(isolen_backend(app)));
        break;
    case gfx_replay_failed:
        // the new renderer came up but an image, svg or font would not
        // rebuild on it, so it was torn down and nothing was lost
        isolen_status(app, "%s could not take every asset, staying on %s",
                      gfx_backend_name(want), gfx_backend_name(isolen_backend(app)));
        break;
    default:
        isolen_status(app, "backend switch to %s refused: %s",
                      gfx_backend_name(want), gfx_status_text(status));
        break;
    }
}

// the same switch on a device opened without isolen_app, a switch between
// gfx_frame_begin and gfx_frame_end is refused with gfx_invalid, so it runs
// between frames and reads back what is really live afterwards
static gfx_backend_id try_switch_raw(gfx_device* dev, gfx_backend_id want)
{
    const gfx_status status = gfx_switch(dev, want);
    if (status != gfx_ok) {
        printf("switch to %s refused: %s\n", gfx_backend_name(want),
               gfx_status_text(status));
    }
    return gfx_backend(dev);
}

Code that holds native GPU objects

Assets registered through gfx replay on their own. Code that makes native GPU objects of its own beside gfx, such as a renderer that talks to Vulkan or Metal directly, has to let go of them before the device they were made on closes. A Vulkan handle used after its device is gone faults inside the driver. A switch listener is told when to let go and when to rebuild.

CallDoes
bool gfx_switch_listen(gfx_device* dev, gfx_switch_fn fn, void* user)Adds a listener. Adding the same fn and user again does nothing and returns true. A device holds up to GFX_MAX_LISTENERS, 32, and one more returns false with an error in the log.
void gfx_switch_unlisten(gfx_device* dev, gfx_switch_fn fn, void* user)Removes it. Call it before the object that user points at goes away.

gfx_switch_fn is void fn(gfx_device* dev, gfx_switch_step step, gfx_backend_id from, gfx_backend_id to, void* user).

StepWhenWhat to do
gfx_switch_leavingThe old backend is idle and still open, before the new one opens. gfx_close sends it too, with to set to gfx_backend_count.Destroy every native object made on from.
gfx_switch_enteredThe live backend has every gfx asset back. After a refused switch it still comes, with to equal to from, because the old backend stayed.Rebuild on the backend now live, gfx_backend(dev).

A switch refused before it starts, because the target is not available or the call came inside a frame, tells nobody anything. The 3D model viewer is a listener: it lets go of its GPU renderer on leaving and makes one for the new backend on entered, which is what keeps a Vulkan to CPU switch from crashing in the driver.

overlay_pass.cpp
#include "isolenui/gfx/gfx.h"

struct my_renderer;
my_renderer* my_renderer_open(gfx_device* dev);
void my_renderer_close(my_renderer* r);

struct overlay_pass {
    gfx_device* dev;
    my_renderer* r;
};

// native gpu objects made outside gfx go while the old device is still open
static void on_switch(gfx_device* dev, gfx_switch_step step, gfx_backend_id from,
                      gfx_backend_id to, void* user)
{
    overlay_pass* p = static_cast<overlay_pass*>(user);
    if (step == gfx_switch_leaving) {
        my_renderer_close(p->r);
        p->r = nullptr;
        return;
    }
    // entered, on the new backend or back on the old one when the switch was refused
    (void)from;
    (void)to;
    p->r = my_renderer_open(dev);
}

void overlay_open(overlay_pass* p, gfx_device* dev)
{
    p->dev = dev;
    p->r = my_renderer_open(dev);
    gfx_switch_listen(dev, on_switch, p);
}

void overlay_close(overlay_pass* p)
{
    gfx_switch_unlisten(p->dev, on_switch, p);
    my_renderer_close(p->r);
    p->r = nullptr;
}

When a switch is refused

  • The target is not compiled in or not available: the status from gfx_backend_check.
  • The new renderer did not start: gfx_init_failed or what its open reported.
  • An asset would not rebuild: gfx_replay_failed. An image whose file changed size on disk still replays and the registry follows the new size. An image whose source file is gone replays blank at its old size, with a warning.
  • The call came between gfx_frame_begin and gfx_frame_end: gfx_invalid.
isolen_set_backend waits for the frame boundary, so it is safe to call from a view. A font whose pixels were released cannot be replayed, which is why gfx_font_bind refuses one.

In the log

Every step of a switch is logged, so a switch that hangs or crashes shows where it stopped:

  • gfx switch from vulkan to cpu, waiting for vulkan to go idle, then gfx switch vulkan idle.
  • gfx switch told N owners to let go of vulkan, and later to rebuild on cpu, when there are listeners.
  • gfx switch opening cpu, gfx switch opened cpu, replaying assets, gfx switch replayed into cpu, closing vulkan and gfx switch closed vulkan.
  • On Vulkan, the teardown logs each of its own steps too. See troubleshooting.

Last updated 6 October 2026