Model previews & canvas views

make_model_thumbnail for offscreen pictures of a model, and CanvasView, the 2D-canvas primitive for HUD drawing.

Sometimes the UI has to show the world rather than a number: a picture of a model for an inventory slot or an asset library, or a small diagram drawn into a HUD. Neither needs a renderer of its own. A model thumbnail is a function that hands back pixels from the renderer that is already running, with no second device, no second context and no widget holding one open, and CanvasView draws with 2D canvas calls.

Model thumbnails

There is no drop-in model-preview widget under src/view/ - no drag-to-rotate, no clip playback. What there is instead is a function from a loaded model to pixels.

make_model_thumbnail(graphics, bundle, width, height, margin = 0) -> Promise<Sampler2D|null>
import { load_model_scene_bundle }
    from "@woosh/meep-engine/src/engine/asset/load_model_scene_bundle.js";
import { make_model_thumbnail }
    from "@woosh/meep-engine/src/engine/graphics3/preview/make_model_thumbnail.js";
import { sampler2d_to_html_canvas }
    from "@woosh/meep-engine/src/engine/graphics/texture/sampler/sampler2d_to_html_canvas.js";

const bundle = await load_model_scene_bundle(engine.assetManager, "models/sword.glb");
const sampler = await make_model_thumbnail(engine.graphics, bundle, 128, 128);

if (sampler !== null) {
    // the sampler is already 8-bit RGBA, so scale 1 and offset 0
    slot.appendChild(sampler2d_to_html_canvas(sampler, 1, 0));
}

make_model_thumbnail is only the order of four steps, each of which ships on its own under @woosh/meep-engine/src/engine/graphics3/preview/ (all named exports):

ExportModuleWhat it answers
model_preview_framing(result, bounds, fov, margin)model_preview_framing.jshow to frame the model
ModelPreviewFramingModelPreviewFraming.jsthe answer: scale, offset (Vector3), camera_distance
make_model_preview_scene(bundle, framing, aspect)make_model_preview_scene.js{scene, camera, drawn} - a scene of one model
MODEL_PREVIEW_FOVmake_model_preview_scene.js45° in radians, the FOV a preview is drawn with
make_model_thumbnail(...)make_model_thumbnail.jsthe four in order, plus the readback

Where the model is comes from shade_bundle_bounds (src/engine/graphics3/shade_bundle_bounds.js), which composes every node’s world from the bundle’s own locals - a bundle is a description of a model, with no transform state anyone has posed.

null is a normal result

A model with nothing to draw has no picture, and that is data rather than a fault. A glTF of empties has no bounds; a glTF whose every mesh is skinned has no drawable node, because a preview scene registers no skin and a skinned mesh therefore is not in it. Either way the answer is null, and a caller showing icons should show none for that asset rather than a blank square that reads as a broken renderer.

Framing

The scale is uniform and taken from the tightest of the three axes, so a model of any proportion lands inside the same unit box and every icon in a library is drawn at the same apparent size. A model’s own units mean nothing here. The box is then centred on the origin, and the camera distance is measured from the front face of the centred box.

margin is how much of the frame is left empty around the model, as a fraction of the frame’s height on each side: 0 fills it edge to edge, 0.25 leaves a quarter of the frame’s height clear above and below.

The camera stands at -camera_distance on Z looking at the origin - the renderer’s convention, applied by the scene builder rather than by the framing - with near = 0.01 and far = camera_distance * 4 + 4.

Lighting

A fixed three-light rig, all directional, none casting shadows: a key from over the viewer’s shoulder at intensity 3, a fill straight down the view axis at 1.5 so the side facing you is not read off the key alone, and a dim rim from behind and below at 0.6 so a silhouette does not close up into black.

There is no ambient term. The renderer takes ambient from the scene’s environment and a preview scene has none - no environment map, and its procedural sky is off: an icon of a model is a picture of the model, not of a place it would stand in.

It is a GPU readback, and it is tooling-only

The pixels come from GraphicsEngine.render_to_sampler(scene, camera, width, height), whose own documentation says tooling only - a readback is forbidden on any gameplay-affecting path. It draws with the renderer that is already running, so geometry and textures the frame needs are already resident, but it takes the renderer over for the call: pixel_ratio goes to 1, the renderer is resized to the picture, automatic exposure is turned off (a picture of one object against nothing has no scene to read an exposure from, and an adapting one would take the frames it adapts over), eight frames are drawn into an owned texture so the temporal effects have a history to converge from, and everything is restored afterwards. The resize drops the main view’s temporal history either way.

It throws when there is no device - before a successful graphics.start(), or after stop().

Cache the promise

A thumbnail is a whole model load plus a render plus a readback. Cache the promise, keyed by url and size, so a second asker awaits the first render rather than starting another one; that is what the editor’s own asset library does.

CanvasView

CanvasView (named, in src/view/elements/CanvasView.js) is a View wrapping an HTMLCanvasElement, exposing its 2D context as this.context2d and keeping the canvas dimensions in sync with View.size.

import { CanvasView } from "@woosh/meep-engine/src/view/elements/CanvasView.js";

const canvas = new CanvasView();
canvas.size.set(256, 64);

canvas.on.linked.add(() => {
    const ctx = canvas.context2d;
    ctx.fillStyle = "#3498db";
    ctx.fillRect(0, 0, 256, 64);
});

clear() wipes the whole canvas. It is the right choice for any HUD element that needs custom 2D drawing.

  • UI toolkit - View, GUIElement, GUIEngine, controls.
  • Widgets - radial menu, tooltips, currency, resource bars, drag-and-drop, modals, toasts.
  • Assets - AssetManager, GameAssetType, and loading a model as a SceneBundle.