A device without the ui
Code that never wants an element tree can open a device and drive frames itself.
gfx_desc_defaultgives an automatic preference, vsync on, no sRGB, an opaque black clear andgfx_list_caps_defaultincaps, the size the instance buffers start at. A frame that needs more grows them.gfx_openbrings the device up on a window.gfx_frame_beginruns once per tick. It returns false when there is nothing to draw into this tick, and the caller then skips it.gfx_frame_drawsubmits 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_endpresents.gfx_resize,gfx_set_vsync,gfx_set_clear,gfx_wait_idleandgfx_closemanage 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.
#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.
#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.
| Field | Meaning |
|---|---|
present_hz | Presents are held to at most this rate. Zero presents on the display clock, every refresh the display offers. |
present_depth | How 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=Nholds presents to N Hz whatever the code asked, andISOLEN_FPS_CAP=0forces the display clock.ISOLEN_DRAWABLES=2or3sets 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_presententry 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, orpresent cadence held to 60 hz, 3 drawables, orpresent 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.