Skip to content

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 }),
);
OptionDefaultMeaning
camera(required)Any three.js camera.
x, y0Top-left corner as fractions of the canvas (origin top-left).
width, height1Size as fractions of the canvas.
backgroundnullClear color of the view's area; null keeps what is underneath.
fit"height"How an orthographic camera fits the view's aspect ratio (below).
elementnullA 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:

fitWhat 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.

MemberMeaning
all, length, iterationEvery view, in draw order: for (const view of engine.views).
firstThe 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.