On this page

The app shell

app.h wraps the window, the gfx device, the ui context and the frame loop. It offers three levels of the same app, and each level hands over more control.

LevelYou writeThe engine owns
0A view callback for isolen_runThe loop, the window and every frame
1The loop, with isolen_next_frameThe window and each frame's begin and end
2Native passes on the live Vulkan or Metal objectsThe device and the ui drawing under your pass

The shell tree

Before your view runs, the shell opens a root box the size of the window. With chrome on (see what chrome is), which is the default, the root is a column holding our title bar and a ui::view() body that takes the rest. With chrome off, and in full screen, the root is itself the view. Either way your code declares into a box that scrolls when the content is taller than the window. Neither box has padding, so opening your own padded column first is normal.

What the shell opens for youinteractive illustration
isolen_app_desc::chrome
window, logical units
ui::col().width(view_w).height(view_h)
ui::title_bar(title, status, ...)
ui::view().width(lay_pct(1)).height(lay_grow(1))
your view(isolen_frame*, void*)
With chrome on, the root is a column holding the title bar and a ui::view() body that takes the rest of the window. With chrome off, the root is itself the view. Your view callback always declares into the box that scrolls.

Describing an app

Start from isolen_app_defaults() and override fields rather than zeroing the struct, since a zeroed one has chrome and vsync off and no log file or clear colour. The defaults give a 1280 by 800 window on the primary monitor, chrome and vsync on, the automatic backend, the bundled atlas and theme_hud.

FieldMeaning
title, width, heightThe window, in logical units. Width and height are ignored when full screen. See pixels and high DPI.
monitorA display index. Below zero lets the engine pick, and ISOLEN_MONITOR_SMALLEST picks the smallest display by area. --monitor N overrides it.
chromeOur title bar in the system's title bar area, with the native frame, corners and window buttons. The view gets the rest. Off, the window is borderless with no bar. See window chrome.
drawn_chromeA borderless window where the kit draws its own window buttons even where the system has native ones. --drawn-chrome sets it.
backdropAn isolen_backdrop, none by default. Mica or Acrylic on Windows 11 and a vibrancy material on macOS, and it makes the window transparent. It used to be a bool. --backdrop NAME sets it. See transparent windows.
transparentThe frame clears to alpha zero and the desktop shows through. --transparent sets it.
shadowAn isolen_shadow: auto, the default, on or off.
vsyncPresents on vblank. --vsync, --no-vsync and --uncapped override it.
fullscreenA frameless kiosk over the whole monitor. Width and height are ignored.
start_fullscreenOpens windowed, then goes full screen the way isolen_set_fullscreen does. --start-fullscreen sets it.
backgroundShows without taking the focus, for a panel another program spawns.
srgbThe target encodes on write, so clear and your colours are given linear.
continuousA frame every display tick. Off by default, see below.
fps_capA frames per second ceiling on top of vsync, on every backend. Zero, the default, leaves it to the display. --fps N overrides it.
backendThe preferred gfx_backend_id. The command line can override it.
font, logThe atlas and the log file, both resolved beside the executable.
no_fallback, no_shapingSkip loading the Hebrew, Arabic and Latin 1 fallback atlas, and leave Arabic unjoined. Both are off by default. See direction and bidi.
clearThe clear colour, as four floats.
themeA ui::theme, copied when the app opens. Null means theme_hud.
imeThe Windows IME service: 0 is the default, TSF, which falls back to IMM on a multi threaded thread. 1 forces IMM and 2 TSF. Ignored on mac. See text editing and IME.
listsThe gfx_list_caps the tree list and the instance buffers start at. Zero means gfx_list_caps_default, and the frame list starts at a quarter of it. See the draw list.
no_zoomTurns the pinch page zoom off and hands every pinch to the ui as input::pinch. See pinch zoom.
max_zoomThe deepest page zoom. Zero means five times.
view, userThe level zero callback and the pointer it receives.
app_desc.cpp
#include "isolenui/app/app.h"
#include "isolenui/kit/kit.h"

// every field of the description, from a side panel another program spawns
// on the smallest display to a full screen show that renders every tick
static isolen_app_desc side_panel(isolen_view_fn view, void* user)
{
    isolen_app_desc d = isolen_app_defaults();
    d.title = "levels";
    d.width = 420;
    d.height = 900;
    d.monitor = ISOLEN_MONITOR_SMALLEST;
    // shows without taking the focus away from the program that spawned it
    d.background = true;
    // no title bar of ours, the root the view declares into is then a view
    d.chrome = false;
    d.view = view;
    d.user = user;
    return d;
}

static isolen_app_desc stage_show(isolen_view_fn view, const ui::theme* theme)
{
    isolen_app_desc d = isolen_app_defaults();
    d.title = "stage";
    d.fullscreen = true;
    // an animated backdrop wants a frame every display tick, the default
    // only runs a frame when something changed
    d.continuous = true;
    d.vsync = true;
    // the target encodes on write, so the clear colour is given linear
    d.srgb = true;
    d.clear[0] = 0.0f;
    d.clear[1] = 0.0f;
    d.clear[2] = 0.0f;
    d.clear[3] = 1.0f;
    d.theme = theme;
    d.font = "assets\\objectivity.atlas";
    d.log = "stage.log";
    d.view = view;
    return d;
}

// runtime control from inside a view, all of it takes effect at the frame
// boundary so nothing changes under the frame that is being declared
static void settings(isolen_frame* f, void* user)
{
    (void)user;
    ui::ctx* u = f->ui;

    // an idle app sleeps, a clock that only changes once a second asks for
    // exactly one frame a second rather than setting continuous
    ui::textf(u, ui::mono(u), "up %.0f s", f->time);
    isolen_redraw_after(f->app, 1.0f);

    bool vsync = isolen_vsync(f->app);
    if (ui::toggle(u, "vsync", &vsync)) {
        isolen_set_vsync(f->app, vsync);
        isolen_status(f->app, "vsync %s", vsync ? "on" : "off");
    }
    if (ui::button(u, "quit")) {
        isolen_quit(f->app);
    }
}

int main(int argc, char** argv)
{
    const isolen_app_desc d = side_panel(settings, nullptr);
    return isolen_run(&d, argc, argv);
}

Frames on demand

By default a frame only runs when something could have changed on screen. That covers input, a resize, a pending backend or vsync change, the first two frames, a widget that is still easing (ui::busy), or an explicit request. An idle app submits nothing, so the driver can hand its memory back.

  • isolen_redraw(app) asks for one more frame after this one. Anything that animates outside the ui calls it every frame.
  • isolen_redraw_after(app, seconds) asks for a frame once that much time has passed, even if nothing else asks. The earliest request wins.
  • isolen_wake(app) runs a frame soon and is safe from any thread, such as an audio or loader thread that changed state.
  • continuous = true gives up all of this and renders every display tick, for a show with a live backdrop.

Frames keep coming while the user drags a window edge, through the same gate. See live resize. After each frame the shell also sets the pointer shape the frame asked for. See cursors.

A native pass or a canvas that animates by itself must call isolen_redraw each frame. Otherwise it freezes as soon as the mouse stops moving.

Runtime control

isolen_set_vsync, isolen_set_backend and the window controls in window chrome all wait for the frame boundary, so nothing changes under the frame being declared. isolen_status sets the status line on our title bar, and isolen_quit makes the next isolen_next_frame return false. isolen_device, isolen_window and isolen_font reach the objects the shell owns. See switching live for the backend.

  • isolen_set_theme(a, t) copies a ui::theme and swaps it in live, then repaints. The looks are rebuilt from the new palette unless the theme sets own_looks. See states and looks.
  • isolen_set_ime(a, mode) switches the Windows IME service live, with the same values as the ime field.
  • isolen_vsync and isolen_fps_cap read back what was asked for.
  • isolen_set_zoom, isolen_reset_zoom and isolen_zoom_get drive the page zoom. See pinch zoom.
  • isolen_set_transparent, isolen_set_backdrop, isolen_set_shadow, isolen_set_window_opacity and the mouse calls change the window live. See transparent windows.

Frame rate cap

isolen_set_fps_cap(a, fps) takes effect on the next frame, and zero or below lifts the cap. It works on top of vsync and on every backend. Deadlines step by the period, so a late wake is paid back and the average holds at the cap. A stall longer than one period starts the schedule again. The wait still wakes on input, and on Windows it uses a high resolution waitable timer so the deadline is not rounded up to the scheduler tick. A cap only limits frames that are wanted anyway. An idle app still runs none, and a frame asked for early waits for its slot instead of being dropped.

Below the cap, an app presents on the display clock with 3 drawables, so it follows a 120 Hz display rather than an even 60. That pacing is on Metal only so far. See present pacing for the fields, the ISOLEN_FPS_CAP and ISOLEN_DRAWABLES overrides and the log line that reports what reached the screen.

Frame stats

isolen_stats_get(a, &s) copies the stats of the last presented frame into an isolen_stats. The counts are summed over every chunk of the tree the sink handed over, and do not include what you paint into isolen_frame::list.

FieldMeaning
frame_msTime from the start of the frame to its present.
waitedSeconds the app sat idle before this frame woke.
framesFrames presented so far.
rects, glyphs, curves, art, runsRecords and runs the tree drew.
flushes, grown, late, droppedThe tree list's sink and growth counters. See the draw list.

The command line

isolen_run and isolen_open take argc and argv and consume the standard flags. isolen_args hands back the positional arguments the engine did not take.

FlagEffect
--backend NAMEParsed with gfx_backend_parse: vulkan, metal, d3d12, cpu or auto.
--vulkan, --metal, --d3d12, --cpuPick that backend directly.
--vsync, --no-vsyncOverride vsync.
--uncappedTurns vsync off and clears fps_cap.
--fps NSets fps_cap.
--ime NAMESets ime: imm, tsf, anything else picks the default.
--monitor NOverride monitor.
--drawn-chromeSets drawn_chrome.
--start-fullscreenSets start_fullscreen.
--transparentSets transparent.
--backdrop NAMESets backdrop: mica, acrylic or vibrancy. Any other name is none.
--vk-validateTurns on the Vulkan validation layer when it is installed. See troubleshooting.
--chrome-testSteps through maximize, restore, full screen and back on its own, logging each step.

Last updated 6 October 2026