On this page

Level 2, native handles

isolen_frame::native is a gfx_frame, which is backend neutral. A backend header turns it back into typed api objects, so a native pass can draw over the tree with the device's own command buffer or encoder.

Ordering with the tree

The tree normally draws at the end of the frame. isolen_flush_ui draws it immediately, so a native pass recorded after the call lands on top of what the tree painted. A pass that animates by itself must also call isolen_redraw, or it stops when the app goes idle.

Page zoom

A pinch can magnify the page without laying it out again, and the tree is then drawn through a gfx_view. A native pass is not. isolen_frame::zoom is the magnification this frame is drawn at, 1 when not zoomed. A pass that draws in page coordinates maps them the same way, using isolen_zoom_get, or the app sets no_zoom. See pinch zoom.

From a device to its window

The native device calls below take a window. Code that only holds a gfx_device*, such as a kit component, reaches it with gfx_window_of(dev) from isolenui/gfx/gfx.h. It returns null for a null device or one that is not open, so check it before passing it on. An app can also use isolen_window.

Vulkan on Windows

gfx_vulkan.h gives gfx_vulkan_frame_of, which fills the recording command buffer, the target image and view, the extent, the format, the swapchain image index and the frame in flight slot. It returns false outside a Vulkan frame. gfx_vulkan_cmd and gfx_vulkan_view are inline shortcuts that return VK_NULL_HANDLE on another backend. gfx_vulkan_device_of returns the instance, device, queue, pipeline cache and the engine's own gpu_context for a window.

main.cppverified by reading, needs the vulkan sdk
#include "isolenui/app/app.h"
#include "isolenui/gfx/gfx_vulkan.h"

// level two on windows, a native pass recorded after isolen_flush_ui lands
// on top of whatever the tree already painted this frame
static void draw(isolen_frame* f, void* user)
{
    (void)user;
    ui::ctx* u = f->ui;
    ui_box(u, ui::col().grow().pad(24.0f))
    {
        ui::text(u, "native pass draws over this", ui::body(u));
    }

    isolen_flush_ui(f->app);

    gfx_vulkan_frame vk = {};
    if (!gfx_vulkan_frame_of(&f->native, &vk)) {
        return;
    }
    // vk.cmd is already recording into vk.image, the same buffer
    // gfx_vulkan_cmd(&f->native) returns, a native pass goes here
    const VkCommandBuffer cmd = gfx_vulkan_cmd(&f->native);
    (void)cmd;

    // the pass animates on its own, so it asks for the next frame too
    isolen_redraw(f->app);
}

int main(int argc, char** argv)
{
    isolen_app_desc d = isolen_app_defaults();
    d.title = "isolen ui, level two";
    d.backend = gfx_backend_vulkan;
    d.view = draw;
    return isolen_run(&d, argc, argv);
}
This header includes isolenui/gpu/vk_common.h and therefore volk and the Vulkan SDK, so this example only builds on Windows. It was checked by reading against the header, and against a stub volk.h that declares only the handle types.

Metal on macOS

gfx_metal.h only declares anything under Objective-C++. A plain .cpp that includes it sees an empty header and stays neutral, so the native pass goes in a .mm file. gfx_metal_frame_of fills the command buffer, the open render encoder, the target texture, its format and size, and the frame in flight slot. gfx_metal_encoder, gfx_metal_target and gfx_metal_format are inline shortcuts that return nil or MTLPixelFormatInvalid on another backend.

main.mm
#include "isolenui/app/app.h"
#include "isolenui/gfx/gfx_metal.h"

// level two on macos, this file is objective c++ so gfx_metal.h declares its
// types, a plain .cpp that includes the same header sees nothing at all
static void draw(isolen_frame* f, void* user)
{
    (void)user;
    ui::ctx* u = f->ui;
    ui_box(u, ui::col().grow().pad(24.0f))
    {
        ui::text(u, "metal pass draws over this", ui::body(u));
    }

    isolen_flush_ui(f->app);

    gfx_metal_frame mf = {};
    if (!gfx_metal_frame_of(&f->native, &mf)) {
        return;
    }
    // the encoder is open on the frame target, a native pass sets its own
    // pipeline and draws here, slot indexes a per frame in flight ring
    id<MTLRenderCommandEncoder> enc = gfx_metal_encoder(&f->native);
    const MTLPixelFormat format = gfx_metal_format(&f->native);
    [enc pushDebugGroup:@"native pass"];
    [enc popDebugGroup];
    (void)format;
    (void)mf.slot;

    isolen_redraw(f->app);
}

int main(int argc, char** argv)
{
    isolen_app_desc d = isolen_app_defaults();
    d.title = "isolen ui, level two on metal";
    d.backend = gfx_backend_metal;
    d.view = draw;
    return isolen_run(&d, argc, argv);
}

Every Metal device in the process shares one MTLDevice and one queue. The references in gfx_metal_device and gfx_metal_frame are borrowed and never outlive gfx_close, so do not retain them past the frame.

Last updated 6 October 2026