On this page

Assets and handles

Images, svgs and fonts are owned by the device registry. It keeps each asset's source, so a backend switch can rebuild every one of them.

Loading and freeing

  • gfx_image_load decodes a file, and gfx_image_rgba copies pixels you own. The copy is what a switch replays from.
  • gfx_svg_load registers an svg document.
  • gfx_font_bind uploads a font's atlas. The metrics stay on the cpu for layout. A font whose pixels were released is refused.
  • gfx_image_size and gfx_svg_size read natural sizes back, and each kind has a matching _free.

The registry holds up to 256 images, 64 svgs and 4 fonts per device. A load past that returns GFX_NONE, which is zero and never a valid handle.

Handle bits

A handle packs three fields. The low 16 bits hold the slot plus one, which is why zero is never valid. Bits 16 and 17 hold the device index, since up to four devices can be open. Bits 18 to 31 hold a reuse count that moves on each time a slot is freed. GFX_HANDLE_DEVICE_SHIFT and GFX_HANDLE_REUSE_SHIFT name the boundaries, and gfx_handle_slot extracts the slot, or returns 0xffffffff for a value out of range.

Stale and foreign handles are rejected. A handle kept after its asset was freed carries an old reuse count, and a handle from another device carries another index, so neither matches a live asset. Drawing or freeing with one logs a warning and does nothing. The reuse count is 14 bits, so a stale handle only matches again after 16,384 frees of the same slot.

Handle bitsinteractive illustration
00000000000000000000000000000100
bits 18 to 31, reuse 0bits 16 and 17, device 0bits 0 to 15, slot plus one 4
handle 0x00000004gfx_handle_slot gives 3
no copy kept yet
Keep a copy of the handle, then free and reload the slot. The reuse count moves on, so the copy no longer matches what the slot holds and every draw or free that carries it is rejected. Zero, GFX_NONE, is never produced because the low half stores slot plus one.
gfx_assets.cpp
#include "isolenui/gfx/gfx.h"
#include "isolenui/gfx/gfx_backend.h"

#include <stdio.h>

// the registry keeps each asset's source, a path or a copy of the pixels, so
// a backend switch can rebuild every one of them on the new renderer
struct deck_assets {
    gfx_image logo = GFX_NONE;
    gfx_image noise = GFX_NONE;
    gfx_svg gear = GFX_NONE;
    gfx_font font = GFX_NONE;
};

static bool load_assets(gfx_device* dev, const text_font* font, deck_assets* out)
{
    out->logo = gfx_image_load(dev, "assets/logo.png");

    static uint8_t pixels[64 * 64 * 4];
    for (uint32_t i = 0; i < 64u * 64u; ++i) {
        const uint8_t v = uint8_t((i * 2654435761u) >> 24);
        pixels[i * 4 + 0] = v;
        pixels[i * 4 + 1] = v;
        pixels[i * 4 + 2] = v;
        pixels[i * 4 + 3] = 255u;
    }
    out->noise = gfx_image_rgba(dev, pixels, 64u, 64u);
    out->gear = gfx_svg_load(dev, "assets/gear.svg");

    // refused, and GFX_NONE, when the font already released its pixels
    out->font = gfx_font_bind(dev, font);

    uint32_t w = 0;
    uint32_t h = 0;
    gfx_image_size(dev, out->logo, &w, &h);
    float sw = 0.0f;
    float sh = 0.0f;
    gfx_svg_size(dev, out->gear, &sw, &sh);
    printf("logo %ux%u, gear %.0fx%.0f\n", w, h, sw, sh);

    return out->logo != GFX_NONE && out->font != GFX_NONE;
}

// slot plus one in the low 16 bits, the device in bits 16 and 17 and a
// reuse count above, so a freed handle or another device's never matches
static void describe_handle(gfx_image h)
{
    const uint32_t slot = gfx_handle_slot(h, GFX_MAX_IMAGES);
    const uint32_t device_bits = GFX_HANDLE_REUSE_SHIFT - GFX_HANDLE_DEVICE_SHIFT;
    const uint32_t device = (h >> GFX_HANDLE_DEVICE_SHIFT) & ((1u << device_bits) - 1u);
    const uint32_t reuse = h >> GFX_HANDLE_REUSE_SHIFT;
    printf("handle %08x, slot %u, device %u, reuse %u\n", h, slot, device, reuse);
}

// freeing bumps the slot's reuse count, the old value stays dead until that
// 14 bit count wraps after 16384 reuses of the slot, so a draw or free that
// still carries it is rejected with a warning
static void reload_logo(gfx_device* dev, deck_assets* a)
{
    const gfx_image old = a->logo;
    gfx_image_free(dev, a->logo);
    a->logo = gfx_image_load(dev, "assets/logo_v2.png");
    describe_handle(old);
    describe_handle(a->logo);
}

// resident bytes and dropped records are the numbers to watch on a 4 gb card
static void log_gpu_stats(const gfx_device* dev)
{
    gfx_stats s = {};
    gfx_stats_get(dev, &s);
    printf("frame %llu images %u svgs %u fonts %u resident %llu bytes dropped %u\n",
           (unsigned long long)s.frames, s.images, s.svgs, s.fonts,
           (unsigned long long)s.resident_bytes, s.dropped);
}

static void unload_assets(gfx_device* dev, deck_assets* a)
{
    gfx_image_free(dev, a->logo);
    gfx_image_free(dev, a->noise);
    gfx_svg_free(dev, a->gear);
    gfx_font_free(dev, a->font);
    *a = {};
}

Images you update

gfx_image_create takes a gfx_image_desc: width, height, flags, optional rgba with a stride in bytes, and an optional refill with its user. A null rgba starts the image clear, and a zero stride reads width times four.

FlagEffect
gfx_image_no_mipsLevel zero only. An update rebuilds no mip chain, and the image costs a quarter less memory.
gfx_image_streamedThe registry keeps no copy of the pixels. On a backend switch it calls refill for the whole image, and without one the image replays clear with a warning.
  • gfx_image_update(dev, image, rgba, width, height) replaces every pixel. The size must match the image, or it is refused with a warning.
  • gfx_image_update_rect(dev, image, rgba, stride, x, y, w, h) replaces a rectangle. rgba points at its first pixel, and a zero stride reads w times four. A rectangle past the edge is refused.
  • Both take straight RGBA8 like gfx_image_rgba, copy it before they return, and are seen by every draw of the frame they land in. Call them on the render thread.
  • An image that is not streamed keeps its copy in step, so a switch replays the latest pixels. A file image takes a copy of its file on its first update for the same reason.
scope.cpp
#include "isolenui/gfx/gfx.h"

#include <string.h>

// a waveform strip the app redraws itself, one column at a time
struct scope {
    gfx_image img;
    uint8_t column[4u * 256u];
    uint32_t x;
};

// a switch asks for the whole image again, the app knows what it shows
static bool scope_refill(gfx_image image, uint8_t* rgba, uint32_t stride, void* user)
{
    (void)image;
    (void)user;
    for (uint32_t y = 0; y < 256u; ++y) {
        memset(rgba + size_t(y) * stride, 0, 512u * 4u);
    }
    return true;
}

static bool scope_open(gfx_device* dev, scope* s)
{
    gfx_image_desc d = {};
    d.width = 512u;
    d.height = 256u;
    // one level and no copy kept, updates are cheap and the refill replays it
    d.flags = gfx_image_no_mips | gfx_image_streamed;
    d.refill = scope_refill;
    d.user = s;
    s->img = gfx_image_create(dev, &d);
    s->x = 0;
    return s->img != GFX_NONE;
}

// one new column, stride is one pixel since the rect is one wide
static void scope_push(gfx_device* dev, scope* s, float level)
{
    const uint32_t top = 255u - uint32_t(level * 255.0f);
    for (uint32_t y = 0; y < 256u; ++y) {
        const uint32_t on = y >= top ? 0xff38c172u : 0xff101010u;
        memcpy(s->column + y * 4u, &on, 4u);
    }
    gfx_image_update_rect(dev, s->img, s->column, 4u, s->x, 0u, 1u, 256u);
    s->x = (s->x + 1u) % 512u;
}

Textures the app owns

gfx_image_external(dev, &desc) wraps a texture the app rendered itself, so the tree can draw it. The gfx_external_image names its backend, which must be the one the device runs, and its size.

  • Vulkan: native is a VkImageView in shader read layout.
  • Metal: native is the MTLTexture.
  • CPU: native is null and rgba points at pixels sampled in place, with a stride of width times four.

The app still owns the texture after gfx_image_free, until a wait idle, or on Vulkan until the frames in flight plus one have passed. An external image cannot be updated through the registry. A backend switch drops it with a warning, and the app wraps its new texture again. The kit's texture3d shows one in the tree.

Stats

gfx_stats_get fills a gfx_stats with the frame count, the live image, svg and font counts, the resident bytes the backend reports, and the records the last list refused because memory ran out. On the 4 GB event GPU, resident bytes is the number to watch.

Last updated 6 October 2026