--- title: unlitMaterial description: Creates a flat-color material descriptor; renders without lights. --- # unlitMaterial ## Import ```ts import { unlitMaterial } from "vgpu/scene"; ``` ## Signature ```ts declare function unlitMaterial(options?: import("vgpu/scene").ColorMaterialOptions): import("vgpu/scene").UnlitMaterial; ``` ## Examples ```ts 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 ```ts import { lambertMaterial } from "vgpu/scene"; ``` ## Signature ```ts declare function lambertMaterial(options?: import("vgpu/scene").ColorMaterialOptions): import("vgpu/scene").LambertMaterial; ``` ## Examples ```ts 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 ```ts import { normalMaterial } from "vgpu/scene"; ``` ## Signature ```ts declare function normalMaterial(): import("vgpu/scene").NormalMaterial; ``` ## Examples ```ts 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 ```ts import { shaderMaterial } from "vgpu/scene"; ``` ## Signature ```ts 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` | ✖ | `{}` | 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 ```ts 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 ```ts import { SceneMaterial } from "vgpu/scene"; ``` ## Signature ```ts declare abstract class SceneMaterial { abstract readonly kind: import("vgpu/scene").SceneMaterialKind; label: string | undefined; blend: import("vgpu/scene").MaterialBlend | undefined; } ``` ## Examples ```ts 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 ```ts import type { UnlitMaterial } from "vgpu/scene"; ``` ## Signature ```ts declare class UnlitMaterial { readonly kind: "unlit"; set(values: import("vgpu/scene").ColorMaterialValues): this; readonly color: Float32Array; readonly opacity: number; } ``` ## Examples ```ts 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 ```ts import type { LambertMaterial } from "vgpu/scene"; ``` ## Signature ```ts declare class LambertMaterial { readonly kind: "lambert"; set(values: import("vgpu/scene").ColorMaterialValues): this; readonly color: Float32Array; readonly opacity: number; } ``` ## Examples ```ts 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 ```ts import type { NormalMaterial } from "vgpu/scene"; ``` ## Signature ```ts declare class NormalMaterial { readonly kind: "normal"; } ``` ## Examples ```ts 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 ```ts import type { ShaderMaterial } from "vgpu/scene"; ``` ## Signature ```ts declare class ShaderMaterial { readonly kind: "shader"; readonly source: string; readonly values: Readonly>; set(values: Record): this; } ``` ## Examples ```ts 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 ```ts import type { ColorMaterialOptions } from "vgpu/scene"; ``` ## Signature ```ts 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 ```ts 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 ```ts import type { ColorMaterialValues } from "vgpu/scene"; ``` ## Signature ```ts interface ColorMaterialValues { readonly color?: import("vgpu/scene").Vec3Like; readonly opacity?: number; } ``` ## Examples ```ts 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 ```ts import type { MaterialBlend } from "vgpu/scene"; ``` ## Signature ```ts type MaterialBlend = "alpha" | "additive" | "premultiplied"; ``` ## Examples ```ts 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 ```ts import type { SceneMaterialKind } from "vgpu/scene"; ``` ## Signature ```ts type SceneMaterialKind = "unlit" | "normal" | "lambert" | "shader"; ``` ## Examples ```ts import { normalMaterial, type SceneMaterialKind } from "vgpu/scene"; const kind: SceneMaterialKind = normalMaterial().kind; void kind; ``` ## Notes * **See also:** `SceneMaterial`. *** # ShaderMaterialOptions Options accepted by `shaderMaterial()`. ## Import ```ts import type { ShaderMaterialOptions } from "vgpu/scene"; ``` ## Signature ```ts interface ShaderMaterialOptions { readonly set?: Record; readonly blend?: import("vgpu/scene").MaterialBlend; readonly label?: string; } ``` ## Examples ```ts import { shaderMaterial } from "vgpu/scene"; shaderMaterial("@fragment fn fs_main() {}", { label: "glow", blend: "additive" }); ``` ## Notes * **See also:** `shaderMaterial`, `ShaderMaterial`. --- For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md) For an index of all available documentation, see [/llms.txt](/llms.txt) For agent-facing discovery, including API and MCP surfaces, see [/agents.md](/agents.md)