vgpu/scene5 symbolsView source ↗

Symbols in this topic

orbitControlsfunctionOrbitControlstypeOrbitControlsElementtypeOrbitControlsOptionsoptionsOrbitControlsValuestype

orbitControls

Creates shared drag-orbit + wheel-zoom controls that drive a camera (or any node) around a target point. Input adjusts goal values; update(deltaTime) eases the current state toward them and writes the node's transform, so it composes with frameLoop() and on-demand rendering alike.

Import

TypeScript
1
import { orbitControls, type OrbitControlsOptions } from "vgpu/scene";

Signature

TypeScript
1
2
3
4
declare function orbitControls(
  node: import("vgpu/scene").SceneNode,
  options?: import("vgpu/scene").OrbitControlsOptions,
): import("vgpu/scene").OrbitControls;

Parameters

ParamTypeRequiredDefaultNotes
nodeSceneNode✔—Usually a camera; any node with set()/lookAt() works.
options.elementOrbitControlsElement✖—Pointer/wheel source (usually the canvas). Omit for programmatic-only control.
options.targetVec3Like✖[0, 0, 0]World-space orbit/look-at point.
options.dampingnumber✖0.1Easing time constant in seconds (~63% convergence). 0 applies input immediately.
options.rotateSpeednumber✖0.005Drag sensitivity in radians per pixel.
options.zoomSpeednumber✖1Wheel zoom sensitivity multiplier.
options.distance{ min?, max? }✖—Zoom clamp range.
options.pitch{ min?, max? }✖±(π/2 − 0.01)Pitch limits in radians; defaults keep the camera off the poles.

Returns: OrbitControls with update(), set(), dispose(), and yaw/pitch/distance/target state. Throws: VGPU-SCENE-VALUE-INVALID for malformed target vectors.

Examples

TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
import { clock, init, frameLoop } from "vgpu";
import { orbitControls, perspectiveCamera } from "vgpu/scene";
 
declare const canvas: HTMLCanvasElement;
 
const gpu = await init();
const camera = perspectiveCamera({ fov: 45, position: [2, 2, 3], target: [0, 0, 0] });
const controls = orbitControls(camera, { element: canvas, damping: 0.1 });
 
frameLoop(gpu, () => {
  controls.update(clock(gpu).deltaTime); // explicit update, no hidden rAF
});

Notes

  • The initial yaw/pitch/distance pose is derived from the node's current position relative to target.
  • update() returns true only when the node moved — use it to skip re-rendering static frames.
  • Replaces the per-example installOrbitInput/installDragOrbit copies; one shared implementation.
  • See also: OrbitControls, OrbitControlsOptions, perspectiveCamera.

OrbitControls

Class returned by orbitControls().

Import

TypeScript
1
import type { OrbitControls } from "vgpu/scene";

Signature

TypeScript
1
2
3
4
5
6
7
8
9
declare class OrbitControls {
  update(deltaTime?: number): boolean;
  set(values: import("vgpu/scene").OrbitControlsValues): this;
  dispose(): void;
  readonly yaw: number;
  readonly pitch: number;
  readonly distance: number;
  readonly target: Float32Array;
}

Examples

TypeScript
1
2
3
4
5
6
7
import { orbitControls, perspectiveCamera } from "vgpu/scene";
 
const camera = perspectiveCamera({ fov: 45, position: [0, 0, 5], target: [0, 0, 0] });
const controls = orbitControls(camera, { damping: 0 });
controls.set({ yaw: Math.PI / 2, distance: 8 });
controls.update();
controls.dispose();

Notes

  • set() jumps immediately (state and goal); pointer/wheel input eases through damping.
  • dispose() removes DOM listeners; the node keeps its last transform.
  • See also: orbitControls, OrbitControlsValues.

OrbitControlsElement

Structural event-target contract so controls work with an HTMLCanvasElement without requiring DOM types, and with mocks in Node tests.

Import

TypeScript
1
import type { OrbitControlsElement } from "vgpu/scene";

Signature

TypeScript
1
2
3
4
5
6
7
8
9
interface OrbitControlsElement {
  addEventListener(type: string, listener: (event: never) => void, options?: { passive?: boolean } | boolean): void;
  removeEventListener(type: string, listener: (event: never) => void): void;
  setPointerCapture?(pointerId: number): void;
  releasePointerCapture?(pointerId: number): void;
}
 
// (listener parameters are typed loosely in the real declaration so the DOM's
// overloaded addEventListener stays assignable)

Examples

TypeScript
1
2
3
4
5
import type { OrbitControlsElement } from "vgpu/scene";
 
declare const canvas: HTMLCanvasElement;
const element: OrbitControlsElement = canvas;
void element;

Notes

  • Listened events: pointerdown, pointermove, pointerup, pointercancel, wheel (non-passive).
  • See also: orbitControls.

OrbitControlsOptions

Options accepted by orbitControls().

Import

TypeScript
1
import type { OrbitControlsOptions } from "vgpu/scene";

Signature

TypeScript
1
2
3
4
5
6
7
8
9
10
interface OrbitControlsOptions {
  readonly element?: import("vgpu/scene").OrbitControlsElement;
  readonly target?: import("vgpu/scene").Vec3Like;
  readonly damping?: number;
  readonly rotateSpeed?: number;
  readonly zoomSpeed?: number;
  readonly distance?: { readonly min?: number; readonly max?: number };
  readonly pitch?: { readonly min?: number; readonly max?: number };
  readonly label?: string;
}

Examples

TypeScript
1
2
3
4
5
6
7
import { orbitControls, perspectiveCamera } from "vgpu/scene";
 
orbitControls(perspectiveCamera({ fov: 45, position: [0, 0, 5] }), {
  target: [0, 0.5, 0],
  distance: { min: 1, max: 20 },
  pitch: { min: -1.2, max: 1.2 },
});

Notes

OrbitControlsValues

Values accepted by OrbitControls.set(); applied immediately to both state and goal.

Import

TypeScript
1
import type { OrbitControlsValues } from "vgpu/scene";

Signature

TypeScript
1
2
3
4
5
6
interface OrbitControlsValues {
  readonly yaw?: number;
  readonly pitch?: number;
  readonly distance?: number;
  readonly target?: import("vgpu/scene").Vec3Like;
}

Examples

TypeScript
1
2
3
4
import { orbitControls, perspectiveCamera } from "vgpu/scene";
 
const controls = orbitControls(perspectiveCamera({ fov: 45, position: [0, 0, 5] }));
controls.set({ pitch: 0.4, distance: 6 });

Notes

  • pitch and distance are clamped to the configured limits.
  • See also: OrbitControls.