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.


In the gallery3D Model Viewermodel_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.
#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
| Field | Default | Meaning |
|---|---|---|
dev, path | The device and the file. Views of one path share one loaded model. | |
yaw, pitch | 30, 15 | The start angle in degrees, and where a reset goes back to. |
zoom | 1 | The start distance as a multiple of the distance that fits the whole model. |
fov | 0.6 | The vertical field of view in radians. |
auto_rotate, rotate_speed | off, 12 | Turns the model in degrees a second. It pauses while the camera is handled and waits 3 seconds after the last input. |
bg | model_view_clear | Clear draws only the model over what is behind. model_view_theme fills the box with the theme raised colour. |
exposure, env_intensity | 1, 1 | Brightness of the image and of the environment light. |
tone | 0 | The tone map: 0 neutral, 1 AgX, 2 ACES. |
quality | 0 | 0 auto, 1 full, 2 fast. Auto renders fast on the CPU while the camera moves and refines once it settles. |
memory | 0 | 0 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_zoom | 0.1, 4 | Zoom limits as multiples of the fit distance. |
min_pitch, max_pitch | -85, 85 | Pitch limits in degrees, clamped to 89 either way. |
attribution | null | A caption drawn under the view, for a model's licence. |
set_camera | null | Not null moves the camera there this frame. |
model_view_info
| Field | Meaning |
|---|---|
camera | A model_view_camera: target, yaw and pitch in radians with yaw zero looking from plus z, distance and fov. |
ready, failed | The model is loaded and drawing, or it could not load. |
moving | The camera is being handled, coasting or turning, or settled less than a quarter second ago. |
tris | Triangles in the model. |
render_ms | The last render's time. |
renderer | The backend name it draws with. |
#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
| Input | Does |
|---|---|
| Drag | Orbits. A release keeps turning and slows to a stop. |
| Right drag, or Shift or Cmd with a drag | Pans. |
| Wheel | Zooms toward the point under the pointer. |
| Trackpad pinch | Zooms the same way. |
| Sideways wheel or swipe | Turns the model. |
| Double click, or Home | Resets to the start camera. |
| Arrows | Turn 7.5 degrees. With Shift they pan. |
| Plus and minus | Zoom 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.
model_view libs corfuisolenui 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.