Viewport

A region of the canvas that renders a stack of layers through a camera.

Every viewport draws into the shared canvas through the area of its host element. The element must be unique across viewports.

Viewports also route input. Pointer and wheel events on the host element are enriched with clip and world coordinates and a picking ray, sent to each layer in order and passed to the camera controls unless a layer stops propagation.

const viewport = new Viewport({
  domElement: canvas,
  camera,
  layers: [imageLayer],
});
const idetik = new Idetik({ canvas, viewports: [viewport] });

viewport.addLayer(labelLayer);

Constructor

new Viewport(props): Viewport;

Parameter	Description
props: ViewportProps

Types

ViewportProps

Initialization properties for constructing a viewport.

Property	Description
id?: string	Unique id. Defaults to the element id or a generated id.
domElement: HTMLElement	Host element.
camera: Camera	The camera the viewport renders with.
layers?: Layer[]	Layers to render in order.
cameraControls?: CameraControls	Input controls driving the camera.

Properties

id

The viewport's unique identifier.

readonly id: string;

domElement

The host element defining the viewport's area.

readonly domElement: HTMLElement;

camera

The camera the viewport renders with.

readonly camera: Camera;

events

The pointer and wheel event dispatcher for the host element.

readonly events: EventDispatcher;

cameraControls?

Input controls driving the camera.

optional cameraControls?: CameraControls;

Accessors

layers readonly Layer[]

The layers rendered by this viewport in order. Layers with occludes set draw before non-occluding layers regardless of stack order.

get layers(): readonly Layer[];

Methods

addLayer() void

Adds a layer to the top of the stack. Throws if the viewport already contains the layer.

addLayer(layer): void;

Parameter	Description
layer: Layer	The layer to add.

removeLayer() void

Removes a previously added layer.

removeLayer(layer): void;

Parameter	Description
layer: Layer	The layer to remove.

removeAllLayers() void

Removes all layers from the viewport.

removeAllLayers(): void;

updateSize() void

Syncs the camera's aspect ratio to the host element's size. Called automatically when the host element resizes.

updateSize(): void;

getBoxRelativeTo() Box2

Computes the viewport's box relative to the given element in device pixels, with y flipped to match WebGL's bottom-left origin.

getBoxRelativeTo(element): Box2;

Parameter	Description
element: HTMLElement	The element to compute the box against, typically the canvas.

getBufferRect()

The viewport's size in device pixels. Measured relative to its own host element, so x and y are always 0.

getBufferRect(): {
  x: number;
  y: number;
  width: number;
  height: number;
};

clientToClip() vec3

Converts a client-space position to clip space. The y axis points down, matching the renderer's mirrored projection.

clientToClip(position, depth?): vec3;

Parameter	Description
position: vec2	The client-space position to convert.
depth: number	The clip-space z value. Defaults to 0.

clientToWorld() vec3

Converts a client-space position such as a pointer location to world space.

clientToWorld(position, depth?): vec3;

Parameter	Description
position: vec2	The client-space position to convert.
depth: number	The clip-space z value. Defaults to 0.