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.
| Level | You write | The engine owns |
|---|---|---|
| 0 | A view callback for isolen_run | The loop, the window and every frame |
| 1 | The loop, with isolen_next_frame | The window and each frame's begin and end |
| 2 | Native passes on the live Vulkan or Metal objects | The 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.
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.
| Field | Meaning |
|---|---|
title, width, height | The window, in logical units. Width and height are ignored when full screen. See pixels and high DPI. |
monitor | A display index. Below zero lets the engine pick, and ISOLEN_MONITOR_SMALLEST picks the smallest display by area. --monitor N overrides it. |
chrome | Our 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_chrome | A borderless window where the kit draws its own window buttons even where the system has native ones. --drawn-chrome sets it. |
backdrop | An 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. |
transparent | The frame clears to alpha zero and the desktop shows through. --transparent sets it. |
shadow | An isolen_shadow: auto, the default, on or off. |
vsync | Presents on vblank. --vsync, --no-vsync and --uncapped override it. |
fullscreen | A frameless kiosk over the whole monitor. Width and height are ignored. |
start_fullscreen | Opens windowed, then goes full screen the way isolen_set_fullscreen does. --start-fullscreen sets it. |
background | Shows without taking the focus, for a panel another program spawns. |
srgb | The target encodes on write, so clear and your colours are given linear. |
continuous | A frame every display tick. Off by default, see below. |
fps_cap | A frames per second ceiling on top of vsync, on every backend. Zero, the default, leaves it to the display. --fps N overrides it. |
backend | The preferred gfx_backend_id. The command line can override it. |
font, log | The atlas and the log file, both resolved beside the executable. |
no_fallback, no_shaping | Skip loading the Hebrew, Arabic and Latin 1 fallback atlas, and leave Arabic unjoined. Both are off by default. See direction and bidi. |
clear | The clear colour, as four floats. |
theme | A ui::theme, copied when the app opens. Null means theme_hud. |
ime | The 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. |
lists | The 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_zoom | Turns the pinch page zoom off and hands every pinch to the ui as input::pinch. See pinch zoom. |
max_zoom | The deepest page zoom. Zero means five times. |
view, user | The level zero callback and the pointer it receives. |
#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 = truegives 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.
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 aui::themeand swaps it in live, then repaints. The looks are rebuilt from the new palette unless the theme setsown_looks. See states and looks.isolen_set_ime(a, mode)switches the Windows IME service live, with the same values as theimefield.isolen_vsyncandisolen_fps_capread back what was asked for.isolen_set_zoom,isolen_reset_zoomandisolen_zoom_getdrive the page zoom. See pinch zoom.isolen_set_transparent,isolen_set_backdrop,isolen_set_shadow,isolen_set_window_opacityand 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.
| Field | Meaning |
|---|---|
frame_ms | Time from the start of the frame to its present. |
waited | Seconds the app sat idle before this frame woke. |
frames | Frames presented so far. |
rects, glyphs, curves, art, runs | Records and runs the tree drew. |
flushes, grown, late, dropped | The 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.
| Flag | Effect |
|---|---|
--backend NAME | Parsed with gfx_backend_parse: vulkan, metal, d3d12, cpu or auto. |
--vulkan, --metal, --d3d12, --cpu | Pick that backend directly. |
--vsync, --no-vsync | Override vsync. |
--uncapped | Turns vsync off and clears fps_cap. |
--fps N | Sets fps_cap. |
--ime NAME | Sets ime: imm, tsf, anything else picks the default. |
--monitor N | Override monitor. |
--drawn-chrome | Sets drawn_chrome. |
--start-fullscreen | Sets start_fullscreen. |
--transparent | Sets transparent. |
--backdrop NAME | Sets backdrop: mica, acrylic or vibrancy. Any other name is none. |
--vk-validate | Turns on the Vulkan validation layer when it is installed. See troubleshooting. |
--chrome-test | Steps through maximize, restore, full screen and back on its own, logging each step. |