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.
#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);
}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.
#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.