vgpu/scene14 symbolsView source ↗

Symbols in this topic

ColorMaterialOptionsoptions ColorMaterialValuestype lambertMaterialfunction LambertMaterialtype MaterialBlendtype normalMaterialfunction NormalMaterialtype SceneMaterialtype SceneMaterialKindtype shaderMaterialfunction ShaderMaterialtype ShaderMaterialOptionsoptions unlitMaterialfunction UnlitMaterialtype

unlitMaterial

Creates a flat-color material descriptor; renders without lights.

Import

TypeScript

import { unlitMaterial } from "vgpu/scene";

Signature

TypeScript

declare function unlitMaterial(options?: import("vgpu/scene").ColorMaterialOptions): import("vgpu/scene").UnlitMaterial;

Examples

TypeScript

import { srgb, unlitMaterial } from "vgpu/scene";
 
const material = unlitMaterial({ color: srgb("#3b82f6") });
material.set({ opacity: 0.5 });

Notes

Materials are pure descriptors — no GPU resources; pipelines compile when a tree is bound with the scene renderer.
See also: lambertMaterial, normalMaterial, shaderMaterial, ColorMaterialOptions.

lambertMaterial

Creates an N·L diffuse material descriptor lit by scene lights (uses @vgpu/wgsl-std/light lambert).

Import

TypeScript

import { lambertMaterial } from "vgpu/scene";

Signature

TypeScript

declare function lambertMaterial(options?: import("vgpu/scene").ColorMaterialOptions): import("vgpu/scene").LambertMaterial;

Examples

TypeScript

import { directionalLight, lambertMaterial, mesh, scene, sphere } from "vgpu/scene";
 
const root = scene({
  children: [
    mesh(sphere({ radius: 0.5 }), lambertMaterial({ color: [0.4, 0.6, 1] })),
    directionalLight({ direction: [-1, -2, -1], intensity: 1.2 }),
  ],
});
void root;

Notes

Pair with directionalLight() / ambientLight() nodes in the tree.
See also: unlitMaterial, directionalLight, ambientLight.

normalMaterial

Creates a debug material that shades world-space normals; needs no lights or parameters. It is the default material of mesh().

Import

TypeScript

import { normalMaterial } from "vgpu/scene";

Signature

TypeScript

declare function normalMaterial(): import("vgpu/scene").NormalMaterial;

Examples

TypeScript

import { mesh, normalMaterial, torus } from "vgpu/scene";
 
const donut = mesh(torus(), normalMaterial());
void donut;

Notes

See also: mesh, unlitMaterial.

shaderMaterial

Creates a custom material from a WGSL fragment stage compiled against the scene renderer's vertex contract. Scene globals live in @group(0) (renderer-owned); material bindings start at @group(1).

Import

TypeScript

import { shaderMaterial } from "vgpu/scene";

Signature

TypeScript

declare function shaderMaterial(
  source: string,
  options?: import("vgpu/scene").ShaderMaterialOptions,
): import("vgpu/scene").ShaderMaterial;

Parameters

Param	Type	Required	Default	Notes
source	`string`	✔	—	WGSL fragment stage. May import from `@vgpu/wgsl-std/*`.
options.set	`Record<string, unknown>`	✖	`{}`	Initial binding values keyed by WGSL variable name, like `draw.set()`.
options.blend	`MaterialBlend`	✖	—	`"alpha"`, `"additive"`, or `"premultiplied"`.
options.label	`string`	✖	—	Used in error `where` strings.

Returns: ShaderMaterial descriptor with source, values, and set(). Throws: None at construction; WGSL errors surface when the renderer compiles the material.

Examples

TypeScript

import { shaderMaterial } from "vgpu/scene";
 
const glow = shaderMaterial(GLOW_WGSL, { set: { params: { color: [0.2, 0.5, 1], intensity: 2 } } });
glow.set({ params: { intensity: 4 } }); // merges per binding, like draw.set()
 
declare const GLOW_WGSL: string;

Notes

The renderer owns the vertex stage and @group(0) by default; write fragment-only WGSL with params in @group(1)+.
See also: ShaderMaterialOptions, ShaderMaterial, unlitMaterial.

SceneMaterial

Abstract base of every material descriptor. Discriminate concrete materials by kind.

Import

TypeScript

import { SceneMaterial } from "vgpu/scene";

Signature

TypeScript

declare abstract class SceneMaterial {
  abstract readonly kind: import("vgpu/scene").SceneMaterialKind;
  label: string | undefined;
  blend: import("vgpu/scene").MaterialBlend | undefined;
}

Examples

TypeScript

import { UnlitMaterial, unlitMaterial, type SceneMaterial } from "vgpu/scene";
 
const material: SceneMaterial = unlitMaterial();
if (material instanceof UnlitMaterial) void material.color;

Notes

See also: SceneMaterialKind, unlitMaterial, shaderMaterial.

UnlitMaterial

Class returned by unlitMaterial(). kind: "unlit" with color, opacity, and set().

Import

TypeScript

import type { UnlitMaterial } from "vgpu/scene";

Signature

TypeScript

declare class UnlitMaterial {
  readonly kind: "unlit";
  set(values: import("vgpu/scene").ColorMaterialValues): this;
  readonly color: Float32Array;
  readonly opacity: number;
}

Examples

TypeScript

import { unlitMaterial } from "vgpu/scene";
 
unlitMaterial().set({ color: [1, 0, 0] });

Notes

color keeps a stable array identity; mutate via set().
See also: unlitMaterial, ColorMaterialValues.

LambertMaterial

Class returned by lambertMaterial(). kind: "lambert" with color, opacity, and set().

Import

TypeScript

import type { LambertMaterial } from "vgpu/scene";

Signature

TypeScript

declare class LambertMaterial {
  readonly kind: "lambert";
  set(values: import("vgpu/scene").ColorMaterialValues): this;
  readonly color: Float32Array;
  readonly opacity: number;
}

Examples

TypeScript

import { lambertMaterial } from "vgpu/scene";
 
lambertMaterial({ color: [0.4, 0.6, 1] }).set({ opacity: 0.8 });

Notes

See also: lambertMaterial, ColorMaterialValues.

NormalMaterial

Class returned by normalMaterial(). kind: "normal", no parameters.

Import

TypeScript

import type { NormalMaterial } from "vgpu/scene";

Signature

TypeScript

declare class NormalMaterial {
  readonly kind: "normal";
}

Examples

TypeScript

import { normalMaterial, type NormalMaterial } from "vgpu/scene";
 
const material: NormalMaterial = normalMaterial();
void material;

Notes

See also: normalMaterial.

ShaderMaterial

Class returned by shaderMaterial(). Holds the WGSL source plus binding values merged by set().

Import

TypeScript

import type { ShaderMaterial } from "vgpu/scene";

Signature

TypeScript

declare class ShaderMaterial {
  readonly kind: "shader";
  readonly source: string;
  readonly values: Readonly<Record<string, unknown>>;
  set(values: Record<string, unknown>): this;
}

Examples

TypeScript

import { shaderMaterial } from "vgpu/scene";
 
const material = shaderMaterial("@fragment fn fs_main() {}", { set: { params: { t: 0 } } });
material.set({ params: { t: 1 } });

Notes

set() merges plain-object values per top-level key and replaces everything else, mirroring draw.set() semantics.
See also: shaderMaterial, ShaderMaterialOptions.

ColorMaterialOptions

Options shared by unlitMaterial() and lambertMaterial().

Import

TypeScript

import type { ColorMaterialOptions } from "vgpu/scene";

Signature

TypeScript

interface ColorMaterialOptions {
  readonly color?: import("vgpu/scene").Vec3Like;
  readonly opacity?: number;
  readonly blend?: import("vgpu/scene").MaterialBlend;
  readonly label?: string;
}

Parameters

Field	Type	Required	Default	Notes
color	`Vec3Like`	✖	`[1, 1, 1]`	Linear RGB; pass `srgb("#…")` for hex input.
opacity	`number`	✖	`1`	In `[0, 1]`. Values below 1 need a `blend` mode to show.
blend	`MaterialBlend`	✖	—	Blend preset shared with `DrawOptions.blend`.
label	`string`	✖	—	Used in error `where` strings.

Examples

TypeScript

import { srgb, unlitMaterial } from "vgpu/scene";
 
unlitMaterial({ color: srgb("#ff8800"), opacity: 0.75, blend: "alpha" });

Notes

See also: ColorMaterialValues, unlitMaterial, lambertMaterial.

ColorMaterialValues

Values accepted by set() on color materials.

Import

TypeScript

import type { ColorMaterialValues } from "vgpu/scene";

Signature

TypeScript

interface ColorMaterialValues {
  readonly color?: import("vgpu/scene").Vec3Like;
  readonly opacity?: number;
}

Examples

TypeScript

import { unlitMaterial } from "vgpu/scene";
 
unlitMaterial().set({ color: [0, 1, 0], opacity: 0.9 });

Notes

See also: ColorMaterialOptions.

MaterialBlend

Blend preset accepted by materials; the same presets as DrawOptions.blend.

Import

TypeScript

import type { MaterialBlend } from "vgpu/scene";

Signature

TypeScript

type MaterialBlend = "alpha" | "additive" | "premultiplied";

Examples

TypeScript

import { unlitMaterial, type MaterialBlend } from "vgpu/scene";
 
const blend: MaterialBlend = "additive";
unlitMaterial({ blend });

Notes

Materials with a blend mode render after opaque ones.
See also: ColorMaterialOptions, ShaderMaterialOptions.

SceneMaterialKind

Discriminator for material descriptors.

Import

TypeScript

import type { SceneMaterialKind } from "vgpu/scene";

Signature

TypeScript

type SceneMaterialKind = "unlit" | "normal" | "lambert" | "shader";

Examples

TypeScript

import { normalMaterial, type SceneMaterialKind } from "vgpu/scene";
 
const kind: SceneMaterialKind = normalMaterial().kind;
void kind;

Notes

See also: SceneMaterial.

ShaderMaterialOptions

Options accepted by shaderMaterial().

Import

TypeScript

import type { ShaderMaterialOptions } from "vgpu/scene";

Signature

TypeScript

interface ShaderMaterialOptions {
  readonly set?: Record<string, unknown>;
  readonly blend?: import("vgpu/scene").MaterialBlend;
  readonly label?: string;
}

Examples

TypeScript

import { shaderMaterial } from "vgpu/scene";
 
shaderMaterial("@fragment fn fs_main() {}", { label: "glow", blend: "additive" });

Notes

See also: shaderMaterial, ShaderMaterial.