On this page

3D model viewer

ui::model_view from isolenui/kit/charts.h shows a glTF 2.0 model on an orbit camera, lit by a built in studio environment. It runs on corfu, the engine's model engine in corfu/src, and draws with Metal, Vulkan or the CPU backend.

3D Model Viewer, a gltf model on an orbit camera, drawn by isolen3D Model Viewer, a gltf model on an orbit camera, drawn by isolen
Not yet run interactively. The user will test it on the Mac and the RTX 2050.
A green toy car with flame decals on a red cloth draped over a stand, on a dark background, drawn by model_view

Showing a model

model_view_of(dev, path) fills a spec with the defaults below. model_view(u, label, spec, style) declares the view and returns a model_view_info. The style sizes the box, and its corners take the theme radius. The file is a .gltf or .glb.

car.cpp
#include "isolenui/app/app.h"
#include "isolenui/ui/ui.h"
#include "isolenui/kit/kit.h"

// the view renders only when something changed and loads the file on a worker
static ui::model_view_info car(ui::ctx* u, isolen_app* a, const char* path)
{
    ui::model_view_spec m = ui::model_view_of(isolen_device(a), path);
    m.zoom = 0.6f;
    m.auto_rotate = true;
    m.bg = ui::model_view_theme;
    m.tone = 1u;
    m.attribution = "Toy Car by Guido Odendahl and Eric Chadwick, CC0";
    return ui::model_view(u, "car", m, ui::row().width(lay_grow(1.0f)).height(420.0f));
}

model_view_spec

FieldDefaultMeaning
dev, pathThe device and the file. Views of one path share one loaded model.
yaw, pitch30, 15The start angle in degrees, and where a reset goes back to.
zoom1The start distance as a multiple of the distance that fits the whole model.
fov0.6The vertical field of view in radians.
auto_rotate, rotate_speedoff, 12Turns the model in degrees a second. It pauses while the camera is handled and waits 3 seconds after the last input.
bgmodel_view_clearClear draws only the model over what is behind. model_view_theme fills the box with the theme raised colour.
exposure, env_intensity1, 1Brightness of the image and of the environment light.
tone0The tone map: 0 neutral, 1 AgX, 2 ACES.
quality00 auto, 1 full, 2 fast. Auto renders fast on the CPU while the camera moves and refines once it settles.
memory00 auto, 1 retained, 2 minimal. Minimal drops what the next render can rebuild after a second idle. Auto is minimal on Vulkan and retained elsewhere.
min_zoom, max_zoom0.1, 4Zoom limits as multiples of the fit distance.
min_pitch, max_pitch-85, 85Pitch limits in degrees, clamped to 89 either way.
attributionnullA caption drawn under the view, for a model's licence.
set_cameranullNot null moves the camera there this frame.

model_view_info

FieldMeaning
cameraA model_view_camera: target, yaw and pitch in radians with yaw zero looking from plus z, distance and fov.
ready, failedThe model is loaded and drawing, or it could not load.
movingThe camera is being handled, coasting or turning, or settled less than a quarter second ago.
trisTriangles in the model.
render_msThe last render's time.
rendererThe backend name it draws with.
studio.cpp
#include "isolenui/app/app.h"
#include "isolenui/ui/ui.h"
#include "isolenui/kit/kit.h"

// a front view button moves the camera for one frame, the info reads it back
static void studio(ui::ctx* u, isolen_app* a, const char* path, ui::model_view_info* last)
{
    ui::model_view_spec m = ui::model_view_of(isolen_device(a), path);
    m.min_pitch = -10.0f;
    m.max_pitch = 60.0f;
    m.max_zoom = 2.0f;

    ui::model_view_camera front = last->camera;
    front.yaw = 0.0f;
    front.pitch = 0.0f;
    if (last->ready && ui::button(u, "front")) {
        m.set_camera = &front;
    }
    *last = ui::model_view(u, "studio", m, ui::row().width(lay_grow(1.0f)).height(360.0f));
    if (last->ready) {
        ui::textf(u, ui::caption(u), "%u triangles on %s, %.2f ms", last->tris, last->renderer,
                  double(last->render_ms));
    }
}

Controls

InputDoes
DragOrbits. A release keeps turning and slows to a stop.
Right drag, or Shift or Cmd with a dragPans.
WheelZooms toward the point under the pointer.
Trackpad pinchZooms the same way.
Sideways wheel or swipeTurns the model.
Double click, or HomeResets to the start camera.
ArrowsTurn 7.5 degrees. With Shift they pan.
Plus and minusZoom while it has focus.

The view keeps the wheel, so no view behind it scrolls, and claims the arrows and Home and End while it has focus. The right button and the pinch come from input::right_down and input::pinch. The viewer keeps a pinch that starts over it with ui::take_pinch, so the page does not zoom instead. See keyboard and input.

Loading and drawing

  • A path loads on a worker thread. Until it is ready the box shows a faint panel and checks again every 50 ms. Up to 16 models can be open at once.
  • A model that fails sets failed, logs one error and shows a caption saying it did not load.
  • It renders only when the camera, the options, the size, the model or the backend changed, at the box's physical pixel size, so an idle view costs nothing. See pixels and high DPI.
  • Metal on macOS and Vulkan on Windows each have their own renderer, and every other backend uses the CPU renderer. A backend switch rebuilds the renderer.

kit.conf and assets

Its line links the corfu library, which builds its Metal renderer on macOS and its Vulkan one elsewhere. On Windows corfu carries its compiled shaders inside the library, so an app ships no shader files for it.

kit.conf
model_view  libs corfu

isolenui carries one model, assets/models/toy_car.glb, the Toy Car by Guido Odendahl and Eric Chadwick from the Khronos glTF samples, under CC0. The gallery build copies it beside the executable, and the gallery's 3D Model Viewer page shows it with every option as a prop. See the gallery.

Last updated 6 October 2026