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_loaddecodes a file, andgfx_image_rgbacopies pixels you own. The copy is what a switch replays from.gfx_svg_loadregisters an svg document.gfx_font_binduploads a font's atlas. The metrics stay on the cpu for layout. A font whose pixels were released is refused.gfx_image_sizeandgfx_svg_sizeread 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.
0x00000004gfx_handle_slot gives 3GFX_NONE, is never produced because the low half stores slot plus one.#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.
| Flag | Effect |
|---|---|
gfx_image_no_mips | Level zero only. An update rebuilds no mip chain, and the image costs a quarter less memory. |
gfx_image_streamed | The 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.rgbapoints at its first pixel, and a zero stride readswtimes 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.
#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:
nativeis aVkImageViewin shader read layout. - Metal:
nativeis theMTLTexture. - CPU:
nativeis null andrgbapoints 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.