---
url: /pawn/docs/guide/views.md
description: >-
  Views as camera rectangles of the canvas, views that follow DOM elements,
  picking.
---

# 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](../packages/react#views-in-page-layout) does this
for React. The [Views example](https://jakubprill.github.io/pawn/views.html)
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`](./input#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](../packages/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](../packages/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.
