API reference

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

classLitMaterial

@codexo/exojs-lighting / lighting / stable

Makes a sprite respond to the lights of a Lighting system. ```ts crate.material = new LitMaterial({ lighting }); hero.material = new LitMaterial({ lighting, normals: new NormalMap(heroNormalMap) }); ``` The shaded result is `albedo * (ambient + sum over lights)`, each light falling off quadratically to nothing at its radius and, for a cone light, fading across its edge. # One normal source per material Normals are a material binding, not a per-sprite one, so every sprite drawn with a given material shares them - in practice one material per atlas. Sprites from a second atlas need a second material, which breaks the batch at the material boundary. Both shade against the same system. # Ownership The material owns neither the lighting system nor the textures. `destroy()` releases only the GPU resources cached against this material.

props

methods

events

Import

import { LitMaterial } from '@codexo/exojs-lighting'

Makes a sprite respond to the lights of a Lighting system.

```ts crate.material = new LitMaterial({ lighting }); hero.material = new LitMaterial({ lighting, normals: new NormalMap(heroNormalMap) }); ```

The shaded result is `albedo * (ambient + sum over lights)`, each light falling off quadratically to nothing at its radius and, for a cone light, fading across its edge.

# One normal source per material

Normals are a material binding, not a per-sprite one, so every sprite drawn with a given material shares them - in practice one material per atlas. Sprites from a second atlas need a second material, which breaks the batch at the material boundary. Both shade against the same system.

# Ownership

The material owns neither the lighting system nor the textures. `destroy()` releases only the GPU resources cached against this material.

Constructors1

new(options: LitMaterialOptionsConstruction options for LitMaterial.): LitMaterial

Methods6

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: never, 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.

from(source: 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>, options?: Omit<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>, "shader">): SpriteMaterialMaterial specialization for Sprite drawables. The base texture stays on the sprite and is sampled through the engine's `sampleBase(slot, uv)` helper, which pre…<F, B>

Build a SpriteMaterial from an existing Shader. Equivalent to new SpriteMaterial({ shader, ...options }).

from(glslVertex: string, glslFragment: string, options?: { 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…; 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; uniforms?: Record<string, 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…>; wgsl?: string }): SpriteMaterialMaterial specialization for Sprite drawables. The base texture stays on the sprite and is sampled through the engine's `sampleBase(slot, uv)` helper, which pre…

Build a SpriteMaterial from raw GLSL vertex and fragment source strings. Wraps them in a new Shader; pass options.wgsl to also cover the WebGPU backend.

Properties12

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.

lighting: LightingWhat a lighting system does with lights, materials and occluders, whichever renderer turns them into pixels. ```ts const lighting = new LightmapLighting(app, {…

The system this material shades against.

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 (…<Readonly<{ emissive: Float; normalY: Float }>, undefined>

GLSL/WGSL source pair backing this material.

target: "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.

emissive: number

How much light the surface emits of its own. See LitMaterialOptions.emissive.

normals: NormalSourceWhere a LitMaterial takes its surface normals from. An object rather than a name, so a source carries its own parameters and a user can add one: anything that…

The bound normal source. Assigning a replacement takes effect on the next draw and carries its own channel convention with it.

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

packages/exojs-lighting/src/LitMaterial.ts