vgpu/scene10 symbolsView source ↗

Symbols in this topic

groupfunctionmeshfunctionMeshNodetypeNodeOptionsoptionsNodeTransformValuestypeQuatLiketypescenefunctionSceneNodetypeSceneNodeKindtypeVec3Liketype

scene

Creates a root node for a scene tree. Any node can act as a root; scene() names the intent and tags the node with kind: "scene".

Import

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

Signature

TypeScript
1
declare function scene(options?: import("vgpu/scene").NodeOptions): import("vgpu/scene").SceneNode;

Examples

TypeScript
1
2
3
4
5
6
import { box, group, mesh, scene, unlitMaterial } from "vgpu/scene";
 
const root = scene();
const spinner = group({ label: "spinner" });
root.add(spinner);
spinner.add(mesh(box({ size: 1 }), unlitMaterial({ color: [0.2, 0.5, 1] })));

Notes

  • The tree is pure JS state — no GPU resources. Rendering binds a tree later (gpu.scene(), phase 2).
  • See also: group, mesh, SceneNode.

group

Creates a plain transform node used to group children.

Import

TypeScript
1
import { group } from "vgpu/scene";

Signature

TypeScript
1
declare function group(options?: import("vgpu/scene").NodeOptions): import("vgpu/scene").SceneNode;

Examples

TypeScript
1
2
3
4
import { group } from "vgpu/scene";
 
const rig = group({ position: [0, 2, 0], rotation: [0, Math.PI / 4, 0] });
rig.set({ rotation: [0, Math.PI / 2, 0] });

Notes

mesh

Creates a renderable node: a pure geometry descriptor paired with a material.

Import

TypeScript
1
import { mesh } from "vgpu/scene";

Signature

TypeScript
1
2
3
4
5
declare function mesh(
  geometry: import("vgpu/scene").SceneGeometry,
  material?: import("vgpu/scene").SceneMaterial,
  options?: import("vgpu/scene").NodeOptions,
): import("vgpu/scene").MeshNode;

Parameters

ParamTypeRequiredDefaultNotes
geometrySceneGeometry✔—Pure descriptor from box(), sphere(), plane(), …
materialSceneMaterial✖normalMaterial()Shading descriptor; swap by assigning node.material.
optionsNodeOptions✖{}Initial transform, label, visibility, children.

Returns: MeshNode with kind: "mesh". Throws: VGPU-SCENE-VALUE-INVALID for malformed transform options.

Examples

TypeScript
1
2
3
4
5
6
import { lambertMaterial, mesh, sphere } from "vgpu/scene";
 
const ball = mesh(sphere({ radius: 0.5 }), lambertMaterial({ color: [0.9, 0.4, 0.2] }), {
  position: [0, 0.5, 0],
});
ball.set({ rotation: [0, 1, 0] });

Notes

MeshNode

Class returned by mesh(). Extends SceneNode with geometry and material fields the renderer keys its caches by.

Import

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

Signature

TypeScript
1
2
3
4
declare class MeshNode {
  geometry: import("vgpu/scene").SceneGeometry;
  material: import("vgpu/scene").SceneMaterial;
}

Examples

TypeScript
1
2
3
4
import { box, mesh, unlitMaterial } from "vgpu/scene";
 
const node = mesh(box());
node.material = unlitMaterial({ color: [1, 0, 0] });

Notes

  • Both fields are swappable; identity changes re-key renderer caches (phase 2).
  • See also: mesh, SceneNode.

SceneNode

Base scene-tree node: a TRS transform with parent/children links. Mutation goes through set() so world matrices recompute lazily and only for dirty subtrees; exposed arrays keep a stable identity and are updated in place.

Import

TypeScript
1
import { SceneNode } from "vgpu/scene";

Signature

TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
declare class SceneNode {
  set(values: import("vgpu/scene").NodeTransformValues): this;
  lookAt(target: import("vgpu/scene").Vec3Like, up?: import("vgpu/scene").Vec3Like): this;
  add(...children: SceneNode[]): this;
  remove(...children: SceneNode[]): this;
  removeFromParent(): this;
  traverse(visit: (node: SceneNode) => void): void;
  readonly kind: import("vgpu/scene").SceneNodeKind;
  readonly parent: SceneNode | null;
  readonly children: readonly SceneNode[];
  readonly position: Float32Array;
  readonly quaternion: Float32Array;
  readonly scale: Float32Array;
  readonly localMatrix: Float32Array;
  readonly worldMatrix: Float32Array;
  readonly worldPosition: Float32Array;
  visible: boolean;
  label: string | undefined;
}

Returns: Not directly constructed in user code; use scene(), group(), mesh(), cameras, or lights. Throws: VGPU-SCENE-CYCLE when add() would create a cycle; VGPU-SCENE-VALUE-INVALID for malformed vectors.

Examples

TypeScript
1
2
3
4
5
6
7
8
9
import { group } from "vgpu/scene";
 
const parent = group({ position: [1, 0, 0] });
const child = group({ position: [0, 1, 0] });
parent.add(child);
 
const world = child.worldMatrix; // stable identity
parent.set({ position: [2, 0, 0] });
void world; // same array, refreshed on next read

Notes

  • position/quaternion/scale/worldMatrix return the internal arrays: safe to bind, but mutate only via set() so dirty tracking stays exact.
  • lookAt() orients the node's -Z axis at a world-space target and compensates for parent transforms.
  • add() reparents nodes that already have a parent.
  • See also: group, mesh, NodeTransformValues, SceneCamera.

NodeOptions

Options accepted by node factories: all of NodeTransformValues plus initial children.

Import

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

Signature

TypeScript
1
2
3
4
5
6
7
8
9
interface NodeOptions {
  readonly position?: import("vgpu/scene").Vec3Like;
  readonly rotation?: import("vgpu/scene").Vec3Like;
  readonly quaternion?: import("vgpu/scene").QuatLike;
  readonly scale?: number | import("vgpu/scene").Vec3Like;
  readonly visible?: boolean;
  readonly label?: string;
  readonly children?: readonly import("vgpu/scene").SceneNode[];
}

Examples

TypeScript
1
2
3
4
import { group, mesh, box } from "vgpu/scene";
 
const rig = group({ label: "rig", children: [mesh(box())] });
void rig;

Notes

NodeTransformValues

Transform and flag values accepted by node.set().

Import

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

Signature

TypeScript
1
2
3
4
5
6
7
8
interface NodeTransformValues {
  readonly position?: import("vgpu/scene").Vec3Like;
  readonly rotation?: import("vgpu/scene").Vec3Like;
  readonly quaternion?: import("vgpu/scene").QuatLike;
  readonly scale?: number | import("vgpu/scene").Vec3Like;
  readonly visible?: boolean;
  readonly label?: string;
}

Parameters

FieldTypeRequiredDefaultNotes
positionVec3Like✖[0, 0, 0]Local position.
rotationVec3Like✖—Intrinsic XYZ Euler angles in radians. Ignored when quaternion is given.
quaternionQuatLike✖identityLocal rotation (x, y, z, w).
scalenumber | Vec3Like✖1Uniform number or per-axis vector.
visibleboolean✖trueInvisible nodes (and their subtrees) are skipped by the renderer.
labelstring✖—Used in error where strings and debugging.

Examples

TypeScript
1
2
3
import { group } from "vgpu/scene";
 
group().set({ position: [0, 1, 0], rotation: [0, Math.PI, 0], scale: 2 });

Notes

Vec3Like

Three-component vector input accepted by scene-tree setters: tuples, plain arrays, or typed arrays.

Import

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

Signature

TypeScript
1
type Vec3Like = readonly [number, number, number] | readonly number[] | Float32Array;

Examples

TypeScript
1
2
3
import type { Vec3Like } from "vgpu/scene";
 
const up: Vec3Like = [0, 1, 0];

Notes

QuatLike

Quaternion input (x, y, z, w) accepted by scene-tree setters.

Import

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

Signature

TypeScript
1
type QuatLike = readonly [number, number, number, number] | readonly number[] | Float32Array;

Examples

TypeScript
1
2
3
import type { QuatLike } from "vgpu/scene";
 
const identity: QuatLike = [0, 0, 0, 1];

Notes

SceneNodeKind

Discriminator for scene-tree node types, used by renderers and traversal code.

Import

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

Signature

TypeScript
1
2
3
4
5
6
7
8
type SceneNodeKind =
  | "scene"
  | "group"
  | "mesh"
  | "perspective-camera"
  | "orthographic-camera"
  | "directional-light"
  | "ambient-light";

Examples

TypeScript
1
2
3
4
5
6
7
import { scene, mesh, box, type SceneNode } from "vgpu/scene";
 
const root = scene({ children: [mesh(box())] });
const meshes: SceneNode[] = [];
root.traverse((node) => {
  if (node.kind === "mesh") meshes.push(node);
});

Notes