Appearance
Views and picking
A View is a camera drawn into a rectangle of the engine's canvas. All views share one scene and are drawn in the order they were added, so later views draw on top.
ts
import { View } from "@pawnjs/core";
import { OrthographicCamera } from "three";
// Full canvas.
engine.views.add(new View({ camera: main, background: 0x09090b }));
// A minimap in the top-right corner, drawn on top.
const top = new OrthographicCamera(-6, 6, 6, -6, 0.1, 100);
top.position.set(0, 20, 0);
top.lookAt(0, 0, 0);
engine.views.add(
new View({ camera: top, x: 0.72, y: 0.04, width: 0.24, height: 0.24, background: 0x27272a }),
);| Option | Default | Meaning |
|---|---|---|
camera | (required) | Any three.js camera. |
x, y | 0 | Top-left corner as fractions of the canvas (origin top-left). |
width, height | 1 | Size as fractions of the canvas. |
background | null | Clear color of the view's area; null keeps what is underneath. |
fit | "height" | How an orthographic camera fits the view's aspect ratio (below). |
element | null | A DOM element whose on-screen box the view follows. |
name | "" | A label. |
The engine keeps each camera's aspect ratio in sync with its view: a PerspectiveCamera gets a new aspect, and an OrthographicCamera follows the view's fit:
fit | What stays |
|---|---|
"height" | The vertical extent; the camera widens or narrows horizontally. |
"width" | The horizontal extent; the camera grows or shrinks vertically. |
"contain" | Both extents in sight: taller on a narrow view, wider on a wide one. |
Each fit starts from the camera's own extents: the ones it was made with, or the ones you last set on it. "contain" keeps a scene in frame from a wide desktop window to a phone. The vertical extent scales about the camera's axis (or its nearest edge, when the axis lies outside it), so a camera whose bottom is 0 keeps the bottom edge of the view on the same line:
ts
// 12 wide and 4 tall from the camera's height up, wherever the view is.
const camera = new OrthographicCamera(-6, 6, 4, 0, 0.1, 100);
camera.position.set(0, 0, 20);
engine.views.add(new View({ camera, fit: "contain" }));engine.views.add(view) returns a function that removes the view; so does engine.views.remove(view). Set view.enabled = false to skip a view in both drawing and picking.
The views of an engine
engine.views holds the views in draw order and answers where they are. Drawing, picking, labels and the camera rig all ask it, so they agree on which views are drawn: enabled ones, and views following an element whose element is on screen.
| Member | Meaning |
|---|---|
all, length, iteration | Every view, in draw order: for (const view of engine.views). |
first | The first view drawn now, or null. CameraRig and Labels use it by default. |
drawn(), isDrawn(view) | Views drawn now, and whether one is. |
sizeOf(view) | Size of a drawn view in CSS pixels, or null. |
rayAt(u, v, raycaster), ray(view, u, v, raycaster) | Point a raycaster through a canvas position, in the topmost drawn view there or in a given view. |
project(point, view?) | Client coordinates of a world point and whether it is visible. |
canvasRect() | The canvas box in client pixels, or null without a canvas in a page. |
During a frame each element's box is read once and kept until the frame ends, so asking often costs no extra layout.
Views in page layout
A view with an element follows that element's box every frame, as the page lays out and scrolls; hidden or scrolled-out elements are skipped. With a transparent canvas fixed over the whole page, one canvas can draw 3D into any number of elements:
ts
const engine = new Engine({ canvas, enableTransparency: true });
// canvas CSS: position: fixed; inset: 0; pointer-events: none;
for (const card of document.querySelectorAll<HTMLElement>(".card")) {
engine.views.add(new View({ camera: makeCamera(), element: card }));
}<PawnView> in @pawnjs/react does this for React. The Views example shows it live.
Picking
engine.pick(clientX, clientY) raycasts in the topmost enabled view under a point given in client (viewport) coordinates, for example from a pointer event. It returns hits sorted by distance:
ts
canvas.addEventListener("click", (event) => {
const [hit] = engine.pick(event.clientX, event.clientY);
if (!hit?.entity) return;
hit.entity.set(Position, { x: 0, y: 1, z: 0 });
});Each hit is { view, entity, intersection }: the view it happened in, the entity that owns the hit object (or undefined for objects you added to the scene yourself), and the raw three.js Intersection. Hits on a child mesh of a Visual resolve to the entity, and hits on an instance resolve to the instance's entity.
engine.pickAt(u, v) does the same for a canvas position given as fractions (0 to 1, origin top-left).
Pointer picks under the pointer for you: every frame for target and hits, and once for each press and click.
A view points a picking ray with view.updateRay(raycaster, ndc); a view with its own projection overrides it, as MapView from @pawnjs/maps does.
Post-processing
A view's render function draws it in place of a plain renderer.render(scene, camera), so one view can go through three's EffectComposer (bloom, outlines, color grading) while the others stay plain. It gets the renderer with its viewport and scissor already set to the view's area (and its clear color to the view's background, which the composer's first pass clears to), the scene, the view, its rect in canvas CSS pixels, and the engine's elapsed and delta seconds for effects that move. Size the composer to the rect; a composer that renders to the screen draws into the view's area.
ts
const camera = new PerspectiveCamera(60, 1, 0.1, 500);
let composer: EffectComposer | null = null;
let width = 0;
let height = 0;
engine.views.add(
new View({
camera,
render({ renderer, scene, view, rect }) {
if (!composer) {
composer = new EffectComposer(renderer);
composer.addPass(new RenderPass(scene, view.camera));
// Strength, radius, and the brightness that starts to glow.
composer.addPass(new UnrealBloomPass(new Vector2(), 0.8, 0.4, 0.9));
composer.addPass(new OutputPass());
}
if (rect.width !== width || rect.height !== height) {
({ width, height } = rect);
composer.setSize(width, height);
}
composer.render();
},
}),
);OutputPass applies the engine's tone mapping and color space to the whole image, so keep it last; through a composer, a material's toneMapped: false no longer opts out of tone mapping. Bloom picks what is brighter than its threshold before tone mapping, so brightly lit surfaces glow along with emissive ones. The composer's render targets are yours to free with composer.dispose() when the view goes.
Drawing the scene into a texture
drawToTarget(data, target, camera?) draws the scene into a render target the size of the view's area in device pixels, then points the renderer back at the view's area on screen. A view can then show the scene through a shader of its own, such as a reflection in water: the view below draws the scene upside down and rippling.
ts
const camera = new PerspectiveCamera(50, 1, 0.1, 100);
const target = new WebGLRenderTarget(1, 1);
const ripple = new ShaderMaterial({
uniforms: { image: { value: target.texture }, time: { value: 0 } },
vertexShader: `varying vec2 vUv;
void main() { vUv = uv; gl_Position = vec4(position.xy, 0.0, 1.0); }`,
fragmentShader: `uniform sampler2D image; uniform float time; varying vec2 vUv;
void main() {
vec2 uv = vec2(vUv.x + 0.005 * sin(vUv.y * 80.0 - time), 1.0 - vUv.y);
gl_FragColor = texture2D(image, uv);
#include <tonemapping_fragment>
#include <colorspace_fragment>
}`,
});
const quad = new Scene().add(new Mesh(new PlaneGeometry(2, 2), ripple));
const screen = new OrthographicCamera(-1, 1, 1, -1, 0, 1);
engine.views.add(
new View({
camera,
element: water,
render(data) {
drawToTarget(data, target);
ripple.uniforms.time.value = data.elapsed;
data.renderer.render(quad, screen);
},
}),
);The target is yours: free it with target.dispose() when the view goes.
Headless and external renderers
Without canvas and renderer the engine runs headless: systems tick, nothing is drawn. engine.setRenderer(renderer) sets or swaps the renderer later, for hosts that hand over a WebGL context after the engine exists (as @pawnjs/maps does). The engine clears the canvas each frame only when renderer.autoClear is on; turn it off to draw over a host's content.