API reference

Every public class, method, and event in @codexo/exojs. Generated from source.

classMaterial

@codexo/exojs / rendering / stable

Describes the look of a renderable - shader, uniforms, textures, blend mode, and sampling state - independent of its geometry. A `Material` can be shared across many drawables; renderers cache compiled programs/pipelines keyed on pipelineKey and reuse bindings keyed on bindKey. Subclasses fix the target drawable class. Call destroy when the material is no longer needed to release the GPU resources cached on every backend it was used on. Both keys are derived live from the current material state, so they stay stable across repeated reads and change exactly when the relevant state changes - even when uniforms, textures, blendMode, or sampler are mutated in place. # Typed and raw uniforms A shader source that declares a uniform schema gives its materials typed accessors: `material.uniforms.time.set(seconds)` for the implicit block, or `material.uniformBlocks.camera.uniforms.projection.set(matrix)` for named blocks. Writes go into the material's own std140 buffer and are uploaded only when a value changed, and setUniform is not available. A source without a schema keeps the untyped record: `material.uniforms` is a live map of the names declared at construction, and both languages' uniform declarations are the author's responsibility. Write a function that takes materials of either kind against AnyMaterial rather than the bare class, whose defaults describe the raw path.

props

methods

events

Import

import { Material } from '@codexo/exojs'

Describes the look of a renderable - shader, uniforms, textures, blend mode, and sampling state - independent of its geometry.

A `Material` can be shared across many drawables; renderers cache compiled programs/pipelines keyed on pipelineKey and reuse bindings keyed on bindKey. Subclasses fix the target drawable class. Call destroy when the material is no longer needed to release the GPU resources cached on every backend it was used on.

Both keys are derived live from the current material state, so they stay stable across repeated reads and change exactly when the relevant state changes - even when uniforms, textures, blendMode, or sampler are mutated in place.

# Typed and raw uniforms

A shader source that declares a uniform schema gives its materials typed accessors: `material.uniforms.time.set(seconds)` for the implicit block, or `material.uniformBlocks.camera.uniforms.projection.set(matrix)` for named blocks. Writes go into the material's own std140 buffer and are uploaded only when a value changed, and setUniform is not available.

A source without a schema keeps the untyped record: `material.uniforms` is a live map of the names declared at construction, and both languages' uniform declarations are the author's responsibility.

Write a function that takes materials of either kind against AnyMaterial rather than the bare class, whose defaults describe the raw path.

Constructors1

new(options: MaterialOptionsConstruction options shared by every Material. Only `shader` is required. What `uniforms` means follows from the shader source: on a source that declares a uni…<F, B>): Material<F, B>

Methods4

destroy(): void

Release GPU resources cached against this material on every backend that has compiled it. Safe to call multiple times. After destroy, the material can still be re-used - renderers recompile on next draw - but typical usage is to drop the reference.

onDispose(callback: () => void): void

Hook for renderers to register a per-material-instance cleanup callback (release compiled program, pipeline, or bind groups). The callback fires on destroy; renderers MUST also tolerate the material being garbage-collected without destroy ever being called. Part of the renderer SDK contract for extension renderers.

setTexture(name: string, texture: RenderTextureAn off-screen render target that can also be sampled as a texture. Combines RenderTarget (framebuffer attachment) with the sampler parameters of a Texture (sca… | TextureA static GPU texture sourced from an image, canvas, or video element. Holds the pixel source, its sampling state (ScaleModes, WrapModes) and its upload state (…): this

Replace the texture behind a declared slot, returning this for chaining.

setUniform(name: MaterialRawUniformNameA uniform name the raw path accepts; `never` once a schema is declared.<F, B>, value: UniformValueValue accepted by a material uniform on a shader source that declares no uniform schema. Scalars and small tuples auto-marshal to the appropriate `Float32Array…): this

Replace a declared uniform value, returning this for chaining. Unknown names and scalar↔texture kind changes are rejected. Only available on a material whose shader source declares no uniform schema; a typed material writes through uniforms instead.

Properties9

blendMode: BlendModesCompositing blend modes applied when drawing a Drawable over the current render target. Modes 0-4 are implemented as fixed-function GPU blend equations (no tex…

Compositing blend mode applied when drawing with this material.

sampler: SamplerOptionsGPU sampling state: how a texture is filtered and how UV coordinates outside `[0, 1]` are resolved. Sampling state is independent of a texture's pixel content,… | null

Filter/wrap override for the drawable's base texture, or null to inherit it.

shader: ShaderImmutable shader source pair shared by Material instances. `Shader` owns only the GLSL/WGSL text and its stable identity; it carries no uniform/texture state (…<F, B>

GLSL/WGSL source pair backing this material.

target: "mesh" | "particle" | "sprite"

Which drawable class this material can serve; renderers check compatibility.

bindKey: number

Stable bind key: identical ⇒ same bindings (textures unchanged). Derived from this material's identity, base-texture sampler override, and the identities of its bound textures. Changes when a texture is swapped or sampler state changes; drives bind-group/slot reuse.

pipelineKey: number

Stable pipeline key: identical ⇒ same GPU pipeline/program can be used. Derived from shader identity and blend mode, and is independent of the owning material instance so identically configured materials share a pipeline. Drives grouping and the pipeline cache.

textures: Record<string, RenderTextureAn off-screen render target that can also be sampled as a texture. Combines RenderTarget (framebuffer attachment) with the sampler parameters of a Texture (sca… | TextureA static GPU texture sourced from an image, canvas, or video element. Holds the pixel source, its sampling state (ScaleModes, WrapModes) and its upload state (…>

Live identities behind the fixed named texture slots.

uniformBlocks: MaterialUniformBlocksViewWhat Material.uniformBlocks exposes for a named-block schema.<B>

The declared named uniform blocks, each owning its own values.

uniforms: MaterialUniformsViewWhat Material.uniforms exposes: typed accessors when the shader source declares `uniforms`, the mutable value record when it declares no schema, and nothing wh…<F, B>

The typed accessors of the declared uniform block, or - on a source without a schema - the live user uniform values, where construction declares the fixed set of names and each name's scalar/texture kind: material.uniforms.u_time = performance.now() / 1000; material.uniforms.u_color = [1, 0.5, 0, 1];

Source

src/rendering/material/Material.ts