On this page

A device without the ui

Code that never wants an element tree can open a device and drive frames itself.

  • gfx_desc_default gives an automatic preference, vsync on, no sRGB, an opaque black clear and gfx_list_caps_default in caps, the size the instance buffers start at. A frame that needs more grows them. gfx_open brings the device up on a window.
  • gfx_frame_begin runs once per tick. It returns false when there is nothing to draw into this tick, and the caller then skips it.
  • gfx_frame_draw submits a list at a scale in physical pixels per logical unit. Each call draws over the ones before, so a list can arrive as several chunks from its sink. gfx_frame_end presents.
  • gfx_resize, gfx_set_vsync, gfx_set_clear, gfx_wait_idle and gfx_close manage the rest of its life.

The window here is the platform handle defined under isolenui/src/platform/, outside the headers these docs cover. Never open a second device on a window an isolen_app already owns, and never begin a frame inside an isolen_next_frame loop, because that call already began one.

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

static gfx_list g_list;
static bool g_in_frame;

// a full list hands its lowest layers here mid frame, true lets it reuse the
// records, false outside a frame makes it grow instead
static bool draw_chunk(const gfx_list* chunk, void* user)
{
    if (!g_in_frame) {
        return false;
    }
    gfx_frame_draw(static_cast<gfx_device*>(user), chunk, 1.0f);
    return true;
}

// the device without the ui layer at all, for a host with no isolen_app in
// the picture. window is the platform handle isolen_app builds around,
// defined under src/platform/, outside the headers this site documents. never
// open a second device on a window isolen_app already owns, and never call
// gfx_frame_begin inside an isolen_next_frame loop, that call already began
// the frame
static void run_one_frame(window* w, gfx_device* dev, float view_w,
                           float view_h, float time)
{
    gfx_frame frame = {};
    if (!gfx_frame_begin(dev, &frame)) {
        return;
    }
    g_in_frame = true;
    gfx_list_begin(&g_list, view_w, view_h, time);
    gfx_fill(&g_list, 0.0f, 0.0f, view_w, view_h, 0xff141414u);
    // draws whatever the sink has not drawn yet
    gfx_frame_draw(dev, &g_list, 1.0f);
    g_in_frame = false;
    gfx_frame_end(dev);
    (void)w;
}

// opening a device directly, the way isolen_app does under the hood, on a
// window this host created and owns itself
static gfx_device* open_device(window* w)
{
    gfx_desc desc = gfx_desc_default();
    // the instance buffers start here and grow for a frame that needs more
    desc.caps.glyphs = 8192u;
    gfx_backend_id chosen = gfx_backend_auto;
    gfx_status why = gfx_ok;
    gfx_device* dev = gfx_open(w, &desc, &chosen, &why);
    if (dev && gfx_list_init(&g_list, &desc.caps)) {
        gfx_list_sink_set(&g_list, draw_chunk, dev);
    }
    return dev;
}

static void close_device(gfx_device* dev)
{
    gfx_list_free(&g_list);
    gfx_close(dev);
}

Drawing through a zoom

gfx_frame_draw_view(dev, list, scale, &view) draws a list magnified without recording it again. A gfx_view holds zoom, an origin x y and a clip, all in logical view units: a logical point p lands at p less x y, times zoom, and only clip is touched. A clip width below zero touches the whole target. The backend applies it as one transform to every record, so text, curves and vectors come out sharp at the zoomed size instead of scaled up pixels, and scissors and rounded clips follow it. A zoom of zero or below, or a null view, draws as gfx_frame_draw does. This is what the app's page zoom uses.

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

// the page list magnified around a point, the hud list drawn after it at
// identity so it stays the same size, both in one frame
static void draw_zoomed(gfx_device* dev, const gfx_list* page, const gfx_list* hud,
                        float scale, float zoom, float focus_x, float focus_y,
                        float view_w, float view_h)
{
    gfx_view v = {};
    v.zoom = zoom;
    // a logical point p lands at p less x y times zoom, so the focus sits mid view
    v.x = focus_x - view_w * 0.5f / zoom;
    v.y = focus_y - view_h * 0.5f / zoom;
    // the page box below a 40 unit bar, a width below zero would touch everything
    v.clip[0] = 0.0f;
    v.clip[1] = 40.0f;
    v.clip[2] = view_w;
    v.clip[3] = view_h - 40.0f;
    gfx_frame_draw_view(dev, page, scale, &v);
    gfx_frame_draw(dev, hud, scale);
}

A transparent surface

gfx_desc::transparent opens a device whose clear drops to alpha zero and whose surface hands its premultiplied alpha to the compositor, so what the frame leaves empty shows the desktop. Draw premultiplied with srgb off. gfx_set_transparent(dev, on) changes it between frames, and is refused with a warning inside one. gfx_transparent reads what was asked for. While it is on, gfx_set_clear keeps the colour for later but the clear stays at zero.

gfx_surface_alpha is true when the surface itself carries the alpha. When it is false the backend could not, and whether the desktop shows through is left to the window. Vulkan rebuilds its swapchain and asks the surface for premultiplied composite alpha, falling back to inherit, and an exclusive fullscreen swapchain stays opaque. Metal stops its layer claiming to be opaque. The CPU present clears its layers on mac and goes through the DWM frame on Windows. An app sets all of this through its own app description and window calls rather than here.

Present pacing

Two fields of gfx_desc say how frames reach the screen, and gfx_set_present(dev, hz, depth) changes them on a live device.

FieldMeaning
present_hzPresents are held to at most this rate. Zero presents on the display clock, every refresh the display offers.
present_depthHow many frames can queue ahead of the screen, 2 or 3 drawables. Two keeps input one refresh from the glass when a frame fits in it. Three absorbs a refresh when the compositor holds a drawable, where two would stall.
  • Unset. With both at zero the backend keeps its default: presents held to an even 60 on 3 drawables, so a frame that lands between two refreshes does not show for one and then two and judder. The show runs this way.
  • Apps. The app shell asks for the display clock with 3 drawables, so an app follows a 120 Hz display.
  • Environment. ISOLEN_FPS_CAP=N holds presents to N Hz whatever the code asked, and ISOLEN_FPS_CAP=0 forces the display clock. ISOLEN_DRAWABLES=2 or 3 sets the depth over the code.
  • Backends. Only Metal paces presents so far. The call is stored on every backend and the others keep their own cadence. It is the optional set_present entry of the backend table.

The Metal log says which pacing is in use at startup, then once a second what the display actually put up:

  • present on the display clock, 3 drawables, or present cadence held to 60 hz, 3 drawables, or present cadence held to N hz by the environment.
  • display put up N frames on WxH, gap LO to HI ms, mean M ms, begin to glass mean A max B ms, gpu mean C max D ms. Begin to glass runs from the moment the frame started, when its input is read, to the moment it was on screen, which is the latency the eye sees. The GPU numbers are the command buffer's own time on the GPU.

Last updated 6 October 2026