Skip to content

Documentation / scene / MeshMaterial

Class: MeshMaterial

Defined in: libs/scene/src/material/meshmaterial.ts:126

Base class for mesh materials.

Key responsibilities:

  • Defines feature-based shader variants (alpha test, blending, alpha-to-coverage, TAA toggle, etc.).
  • Provides a material instancing mechanism (per-instance uniforms via a shared core material).
  • Implements the base shader scaffolding for multiple render passes (LIGHT, DEPTH, OBJECT_COLOR, SHADOWMAP).
  • Updates render states depending on pass and features (blending, depth, culling).
  • Submits material uniforms and cooperates with OIT/TAA/SSR/motion vectors.

Variant system:

  • Features are stored in _featureStates and hashed into _createHash().
  • Changing features calls useFeature(...) which triggers optionChanged(true) to rebuild programs.

Instancing:

  • defineInstanceUniform registers per-instance fields with packed layout.
  • createInstance() returns a lightweight instance that shares the core’s GPU programs and updates instance uniform buffer only. This improves batching/instancing support.

Shader hooks:

  • vertexShader(scope) and fragmentShader(scope) provide per-pass hook points to implement the material’s vertex/fragment logic. The base class wires up common I/O (skin, morph, instancing).
  • outputFragmentColor(...) centralizes final color output across passes, handling OIT and alpha ops.

Render states and queues:

  • updateRenderStates(...) sets depth/blend/cull states based on blending, alpha-to-coverage, depth equality optimizations, pass type, and optional OIT overrides.
  • getQueueType() chooses between opaque and transparent queues.

Extending:

  • Override vertexShader, fragmentShader, and optionally outputFragmentColor.
  • Override supportLighting, isTransparentPass, needFragmentColor, etc., as needed.
  • Use uniformChanged() when changing uniform-only values that do not alter shader variants.
  • Use useFeature() when toggling options that affect shader variants.

Extends

Extended by

Implements

  • Clonable<MeshMaterial>

Constructors

Constructor

new MeshMaterial(): MeshMaterial

Defined in: libs/scene/src/material/meshmaterial.ts:187

Create a MeshMaterial with default opaque settings.

Defaults:

  • blendMode = 'none'
  • cullMode = 'back'
  • opacity = 1
  • alphaCutoff = 0
  • taaStrength = 1 - 1/16

Returns

MeshMaterial

Overrides

Material.constructor

Accessors

disposed

Get Signature

get disposed(): boolean

Defined in: libs/base/dist/index.d.ts:6065

Returns

boolean

Inherited from

Material.disposed


changeTag

Get Signature

get changeTag(): number

Defined in: libs/scene/src/material/material.ts:164

Incremented when the material’s GPU-relevant state changes and render bundles may need to be rebuilt.

Returns

number

Inherited from

Material.changeTag


instanceId

Get Signature

get instanceId(): number

Defined in: libs/scene/src/material/material.ts:170

Runtime-unique numeric identifier for the material instance.

Returns

number

Inherited from

Material.instanceId


numPasses

Get Signature

get numPasses(): number

Defined in: libs/scene/src/material/material.ts:180

Number of rendering passes this material uses.

Increasing this will expand the per-pass hash cache; make sure to implement createHash(pass), _createProgram(pb, ctx, pass), and updateRenderStates(pass, ...) accordingly for each pass.

Returns

number

Set Signature

set numPasses(val): void

Defined in: libs/scene/src/material/material.ts:183

Parameters
val

number

Returns

void

Inherited from

Material.numPasses


coreMaterial

Get Signature

get coreMaterial(): this

Defined in: libs/scene/src/material/material.ts:264

Returns the core material that owns GPU state.

Instances may delegate to a shared core to reuse compiled programs and caches.

Returns

this

Inherited from

Material.coreMaterial


drawContext

Get Signature

get drawContext(): DrawContext

Defined in: libs/scene/src/material/meshmaterial.ts:508

Draw context captured during program creation, available inside shader hooks.

Returns

DrawContext

The last DrawContext used to build or apply this material.


pass

Get Signature

get pass(): number

Defined in: libs/scene/src/material/meshmaterial.ts:517

Current material pass index during program building. Typically used inside shader hooks to select per-pass logic.

Returns

number

The active pass index while building the program, or -1 when idle.


alphaCutoff

Get Signature

get alphaCutoff(): number

Defined in: libs/scene/src/material/meshmaterial.ts:526

Alpha test cutoff in [0, 1].

  • 0 disables alpha testing.
  • > 0 discards fragments with alpha < cutoff. Changing this marks uniforms dirty (no shader rebuild).
Returns

number

Set Signature

set alphaCutoff(val): void

Defined in: libs/scene/src/material/meshmaterial.ts:529

Parameters
val

number

Returns

void


alphaDither

Get Signature

get alphaDither(): boolean

Defined in: libs/scene/src/material/meshmaterial.ts:541

Whether alpha clipping uses frame-varying dither coverage.

  • Effective only when alpha cutoff is enabled.
  • Intended for masked materials (blendMode='none') to emulate soft transparency with TAA.
Returns

boolean

Set Signature

set alphaDither(val): void

Defined in: libs/scene/src/material/meshmaterial.ts:544

Parameters
val

boolean

Returns

void


TAADisabled

Get Signature

get TAADisabled(): boolean

Defined in: libs/scene/src/material/meshmaterial.ts:555

Whether TAA is disabled for this material.

  • When true, motion vectors encode a large sentinel to skip TAA accumulation.
  • Managed via an internal feature toggle.
Returns

boolean

Set Signature

set TAADisabled(val): void

Defined in: libs/scene/src/material/meshmaterial.ts:558

Parameters
val

boolean

Returns

void


TAAStrength

Get Signature

get TAAStrength(): number

Defined in: libs/scene/src/material/meshmaterial.ts:566

TAA strength in [0, 1].

  • Higher values generally imply stronger accumulation.
  • The value is mapped when writing motion-vector outputs during depth pass.
Returns

number

Set Signature

set TAAStrength(val): void

Defined in: libs/scene/src/material/meshmaterial.ts:569

Parameters
val

number

Returns

void


alphaToCoverage

Get Signature

get alphaToCoverage(): boolean

Defined in: libs/scene/src/material/meshmaterial.ts:581

Alpha-to-coverage toggle.

  • Useful to approximate transparency for MSAA targets.
  • Managed as a shader feature; toggling rebuilds variants.
Returns

boolean

Set Signature

set alphaToCoverage(val): void

Defined in: libs/scene/src/material/meshmaterial.ts:584

Parameters
val

boolean

Returns

void


blendMode

Get Signature

get blendMode(): BlendMode

Defined in: libs/scene/src/material/meshmaterial.ts:592

Blending mode of this material.

  • 'none' for opaque, 'blend' for standard alpha, 'additive' for emissive FX.
  • Changing the mode toggles an internal feature and rebuilds variants.
Returns

BlendMode

Set Signature

set blendMode(val): void

Defined in: libs/scene/src/material/meshmaterial.ts:595

Parameters
val

BlendMode

Returns

void


transparentShadowCaster

Get Signature

get transparentShadowCaster(): boolean

Defined in: libs/scene/src/material/meshmaterial.ts:606

Whether transparent visible materials cast shadow through a masked shadow-only path.

  • Visible rendering stays blended.
  • Shadow-map rendering is treated like a cutout material using shadowAlphaCutoff.
Returns

boolean

Set Signature

set transparentShadowCaster(val): void

Defined in: libs/scene/src/material/meshmaterial.ts:609

Parameters
val

boolean

Returns

void


shadowAlphaCutoff

Get Signature

get shadowAlphaCutoff(): number

Defined in: libs/scene/src/material/meshmaterial.ts:618

Alpha cutoff used by the shadow-only masked caster path.

Returns

number

Set Signature

set shadowAlphaCutoff(val): void

Defined in: libs/scene/src/material/meshmaterial.ts:621

Parameters
val

number

Returns

void


cullMode

Get Signature

get cullMode(): FaceMode

Defined in: libs/scene/src/material/meshmaterial.ts:632

Face culling mode: 'none' | 'front' | 'back'.

  • Does not force shader rebuild; affects rasterizer state.
Returns

FaceMode

Set Signature

set cullMode(val): void

Defined in: libs/scene/src/material/meshmaterial.ts:635

Parameters
val

FaceMode

Returns

void


opacity

Get Signature

get opacity(): number

Defined in: libs/scene/src/material/meshmaterial.ts:645

Material opacity in [0, 1].

  • Used in transparent passes. Changing marks uniforms dirty only.
Returns

number

Set Signature

set opacity(val): void

Defined in: libs/scene/src/material/meshmaterial.ts:648

Parameters
val

number

Returns

void


objectColor

Get Signature

get objectColor(): Immutable<Vector4>

Defined in: libs/scene/src/material/meshmaterial.ts:659

Per-object color used for GPU picking/object-ID pass.

  • Changing marks uniforms dirty only.
Returns

Immutable<Vector4>

Set Signature

set objectColor(val): void

Defined in: libs/scene/src/material/meshmaterial.ts:662

Parameters
val

Immutable<Vector4>

Returns

void

Methods

on()

on<K>(type, listener, context?): void

Defined in: libs/base/dist/index.d.ts:594

IEventTarget.on

Type Parameters

K

K extends "dispose"

Parameters

type

K

listener

EventListener<{ dispose: []; }, K>

context?

unknown

Returns

void

Inherited from

Material.on


once()

once<K>(type, listener, context?): void

Defined in: libs/base/dist/index.d.ts:598

IEventTarget.once

Type Parameters

K

K extends "dispose"

Parameters

type

K

listener

EventListener<{ dispose: []; }, K>

context?

unknown

Returns

void

Inherited from

Material.once


off()

off<K>(type, listener?, context?): void

Defined in: libs/base/dist/index.d.ts:602

IEventTarget.off

Type Parameters

K

K extends "dispose"

Parameters

type

K

listener?

EventListener<{ dispose: []; }>

context?

unknown

Returns

void

Inherited from

Material.off


dispatchEvent()

dispatchEvent<K>(type, ...args): void

Defined in: libs/base/dist/index.d.ts:606

IEventTarget.dispatchEvent

Type Parameters

K

K extends "dispose"

Parameters

type

K

args

...object[K]

Returns

void

Inherited from

Material.dispatchEvent


dispose()

dispose(): void

Defined in: libs/base/dist/index.d.ts:6066

Returns

void

Inherited from

Material.dispose


supportInstancing()

supportInstancing(): boolean

Defined in: libs/scene/src/material/material.ts:230

Whether this material supports hardware instancing.

Override and return false if per-instance data is not supported in the shader.

Returns

boolean

Inherited from

Material.supportInstancing


isBatchable()

isBatchable(): boolean

Defined in: libs/scene/src/material/material.ts:234

Returns true if this is a instance of material

Returns

boolean

Inherited from

Material.isBatchable


needSceneColor()

needSceneColor(): boolean

Defined in: libs/scene/src/material/material.ts:241

Whether this material requires the scene color texture (e.g., for refraction).

Returns

boolean

Inherited from

Material.needSceneColor


needSceneDepth()

needSceneDepth(): boolean

Defined in: libs/scene/src/material/material.ts:247

Whether this material requires the linear scene depth texture (e.g., for depth-aware effects).

Returns

boolean

Inherited from

Material.needSceneDepth


applyUniforms()

applyUniforms(bindGroup, ctx, needUpdate, pass): void

Defined in: libs/scene/src/material/material.ts:415

Conditionally update uniforms/resources into the material bind group.

Delegates to _applyUniforms() when needUpdate is true (based on _optionTag check).

Parameters

bindGroup

BindGroup

Material bind group at index 2 (may be null if program has no layout).

ctx

DrawContext

Draw context.

needUpdate

boolean

Whether uniforms need to be refreshed.

pass

number

Pass index.

Returns

void

Inherited from

Material.applyUniforms


clearCache()

clearCache(): void

Defined in: libs/scene/src/material/material.ts:440

Returns

void

Inherited from

Material.clearCache


passToHash()

passToHash(pass): string

Defined in: libs/scene/src/material/material.ts:456

Convert a pass index to a hash seed string.

Subclasses may override to encode per-pass role (e.g., "depth", "forward", "shadow").

Parameters

pass

number

Pass number.

Returns

string

String used when building full hash.

Inherited from

Material.passToHash


drawPrimitive()

drawPrimitive(pass, primitive, ctx, numInstances): void

Defined in: libs/scene/src/material/material.ts:484

Issue the actual draw call for a pass.

Override for custom per-pass draw behavior if necessary. The default implementation:

  • Draws instanced if numInstances > 0.
  • Else uses ctx.instanceData.numInstances if available.
  • Else issues a non-instanced draw.

Parameters

pass

number

Pass number.

primitive

Primitive

Primitive to draw.

ctx

DrawContext

Draw context.

numInstances

number

Explicit instance count (0 = auto).

Returns

void

Inherited from

Material.drawPrimitive


onDispose()

protected onDispose(): void

Defined in: libs/scene/src/material/material.ts:499

Dispose the material and release GPU-side resource references.

  • Unregisters from the global registry.
  • Disposes the per-material bind groups kept in _states.

Returns

void

Inherited from

Material.onDispose


clone()

clone(): MeshMaterial

Defined in: libs/scene/src/material/meshmaterial.ts:209

Create a shallow clone of this material. Subclasses should override to copy custom fields.

Returns

MeshMaterial

Implementation of

Clonable.clone

Overrides

Material.clone


copyFrom()

copyFrom(other): void

Defined in: libs/scene/src/material/meshmaterial.ts:220

Copy common MeshMaterial properties from another material. Call super.copyFrom(other) first when overriding in subclasses.

Parameters

other

this

Source material.

Returns

void

Overrides

Material.copyFrom


apply()

apply(ctx): boolean

Defined in: libs/scene/src/material/meshmaterial.ts:241

Capture the active draw context for both cached and freshly-built program paths.

The shader-building hooks access this.drawContext, but uniform application may also consult it on subsequent frames when the GPU program is reused from cache. Updating it here keeps material mixins in sync even when createProgram() is skipped.

Parameters

ctx

DrawContext

Current draw context.

Returns

boolean

Whether material preparation succeeded.

Overrides

Material.apply


uniformChanged()

uniformChanged(): void

Defined in: libs/scene/src/material/meshmaterial.ts:250

Mark uniform-only changes so uniforms are re-uploaded on next apply, without rebuilding shader programs.

Returns

void


defineFeature()

static defineFeature(): number

Defined in: libs/scene/src/material/meshmaterial.ts:257

Define a new feature bit/index for shader variants. Subclasses may use this to add their own switches.

Returns

number


defineInstanceUniform()

static defineInstanceUniform(prop, type, name?): number

Defined in: libs/scene/src/material/meshmaterial.ts:290

Define a per-instance uniform for this class.

Returns a compact index encoding the vector index and component offset, which can be used in shader code via getInstancedUniform(...).

Parameters

prop

string

Property name exposed on instances.

type

InstanceUniformType

Uniform data type.

name?

string = ''

Returns

number

Encoded index for use in getInstancedUniform.

Throws

If the property is already defined or type is invalid.


getInstancedUniform()

getInstancedUniform(scope, uniformIndex): PBShaderExp

Defined in: libs/scene/src/material/meshmaterial.ts:331

Read an encoded per-instance uniform in shader code.

Encoded index packs: vector index, component offset, and component count.

Parameters

scope

PBInsideFunctionScope

Inside-function shader scope.

uniformIndex

number

Encoded index from defineInstanceUniform.

Returns

PBShaderExp

The shader expression reading the selected components.


getInstancedUniforms()

getInstancedUniforms(): object[]

Defined in: libs/scene/src/material/meshmaterial.ts:353

Get the list of per-instance uniforms for this material class.

Returns

object[]


createInstance()

createInstance(): this

Defined in: libs/scene/src/material/meshmaterial.ts:368

Create a material instance (preferred for GPU instancing).

  • On WebGL1 (or when instancing unsupported), falls back to cloning.
  • Otherwise, returns a proxy instance that shares GPU programs and stores per-instance uniforms in a compact Float32Array.

The returned instance:

  • Exposes properties defined by defineInstanceUniform with getter/setter that read/write the packed buffer and notify RenderBundleWrapper.
  • Delegates methods to the core material via prototype chain.

Returns

this

Overrides

Material.createInstance


supportLighting()

supportLighting(): boolean

Defined in: libs/scene/src/material/meshmaterial.ts:674

Whether this material responds to scene lighting. Override to return false for unlit materials.

Returns

boolean

True if lighting affects this material; otherwise false.

Overrides

Material.supportLighting


getEffectiveBlendMode()

protected getEffectiveBlendMode(pass, ctx?): BlendMode

Defined in: libs/scene/src/material/meshmaterial.ts:681

Returns the effective blend mode for the current pass. Transparent-shadow-caster materials stay blended in visible passes, but become masked in shadow passes.

Parameters

pass

number

ctx?

DrawContext

Returns

BlendMode


getActiveAlphaCutoff()

protected getActiveAlphaCutoff(ctx?, pass?): number

Defined in: libs/scene/src/material/meshmaterial.ts:694

Returns the alpha cutoff that should be used for the current pass.

Parameters

ctx?

DrawContext

pass?

number = ...

Returns

number


useTransparentShadowCaster()

useTransparentShadowCaster(ctx?, _pass?): boolean

Defined in: libs/scene/src/material/meshmaterial.ts:700

Whether the current pass should use the shadow-only masked caster path.

Parameters

ctx?

DrawContext

_pass?

number = ...

Returns

boolean


useTransparentShadowCasterForPass()

useTransparentShadowCasterForPass(renderPassType?): boolean

Defined in: libs/scene/src/material/meshmaterial.ts:706

Whether the specified render pass type should reinterpret this transparent material as a masked shadow caster.

Parameters

renderPassType?

number

Returns

boolean


usesAlphaCutoff()

protected usesAlphaCutoff(ctx?, pass?): boolean

Defined in: libs/scene/src/material/meshmaterial.ts:716

Whether this pass needs an alpha-cutoff uniform bound.

Parameters

ctx?

DrawContext

pass?

number = ...

Returns

boolean


needFragmentColorInput()

needFragmentColorInput(ctx?): boolean

Defined in: libs/scene/src/material/meshmaterial.ts:724

Whether this pass needs fragment color inputs. This stays aligned with the historical meaning of needFragmentColor, but also allows shadow-only transparent casters to fetch alpha sources.

Parameters

ctx?

DrawContext

Returns

boolean


updateRenderStates()

protected updateRenderStates(pass, stateSet, ctx): void

Defined in: libs/scene/src/material/meshmaterial.ts:737

Update render states per pass and draw context. Sets blending, alpha-to-coverage, depth test/write, cull mode, color mask, and cooperates with OIT.

Parameters

pass

number

Current material pass index.

stateSet

RenderStateSet

Render state set to update.

ctx

DrawContext

Current draw context.

Returns

void

void

Overrides

Material.updateRenderStates


applyUniformValues()

applyUniformValues(bindGroup, ctx, pass): void

Defined in: libs/scene/src/material/meshmaterial.ts:806

Submit material uniforms/resources to the material bind group (set 2). Handles alpha cutoff, opacity (non-instanced transparent), OIT, object color, and TAA strength.

Parameters

bindGroup

BindGroup

The material bind group to write into.

ctx

DrawContext

Current draw context.

pass

number

Current material pass index.

Returns

void

void


getQueueType()

getQueueType(): number

Defined in: libs/scene/src/material/meshmaterial.ts:830

Determine the render queue for this material. Transparent materials are queued as QUEUE_TRANSPARENT, otherwise QUEUE_OPAQUE.

Returns

number

The queue type constant.

Overrides

Material.getQueueType


isTransparentPass()

isTransparentPass(pass, ctx?): boolean

Defined in: libs/scene/src/material/meshmaterial.ts:840

Whether the given pass is transparent. Default returns true when blendMode !== 'none'.

Parameters

pass

number

Material pass index.

ctx?

DrawContext

Returns

boolean

True if the pass is transparent; otherwise false.

Overrides

Material.isTransparentPass


featureUsed()

featureUsed<T>(feature): T

Defined in: libs/scene/src/material/meshmaterial.ts:867

Query a feature flag’s current value.

Type Parameters

T

T = unknown

Expected value type.

Parameters

feature

number

The feature index.

Returns

T

The current value for the feature, typed as T.


useFeature()

useFeature(feature, use): void

Defined in: libs/scene/src/material/meshmaterial.ts:878

Enable or disable a feature and trigger variant rebuild when changed. Calls optionChanged(true) internally on change.

Parameters

feature

number

The feature index to set.

use

unknown

The new feature value (typed by convention).

Returns

void

void


needFragmentColor()

needFragmentColor(ctx?): boolean

Defined in: libs/scene/src/material/meshmaterial.ts:917

Whether the fragment shader needs to compute color. Returns true for LIGHT pass, or when alpha test or alpha-to-coverage is enabled. Override if the material writes color in other passes.

Parameters

ctx?

DrawContext

Optional draw context; defaults to the last captured drawContext.

Returns

boolean

True if fragment color computation is needed; otherwise false.


vertexShader()

vertexShader(scope): void

Defined in: libs/scene/src/material/meshmaterial.ts:934

Vertex shader hook. Prepares common inputs (skin/morph/instancing), varyings, and pass-dependent outputs. Override to implement per-vertex logic; use ShaderHelper as needed.

Parameters

scope

PBFunctionScope

Vertex shader function scope.

Returns

void

void


fragmentShader()

fragmentShader(scope): void

Defined in: libs/scene/src/material/meshmaterial.ts:969

Fragment shader hook. Declares pass-dependent uniforms (e.g., opacity, objectColor, alphaCutoff). Override to implement per-fragment logic, and call outputFragmentColor to finalize writes.

Parameters

scope

PBFunctionScope

Fragment shader function scope.

Returns

void

void


outputFragmentColor()

outputFragmentColor(scope, worldPos, color, ssrRoughness?, ssrNormal?, sssProfile?, sssParams?, sssDiffuse?, sssTransmission?, sssProfileEnabled?, skinSSS?): void

Defined in: libs/scene/src/material/meshmaterial.ts:1069

Centralized final color write and per-pass output composition.

Behavior by pass:

  • LIGHT: clipping, alpha handling, optional OIT integration, fog application, color output encoding.
  • DEPTH: encoded depth; optional motion vectors (TAA enabled/disabled handling).
  • OBJECT_COLOR: object color and distance output (linear depth or world-pos + distance).
  • SHADOWMAP: writes shadow depth via light’s shadow implementation.

Also writes SSR roughness/normal buffers when requested via material flags.

Parameters

scope

PBInsideFunctionScope

Inside-function shader scope.

worldPos

PBShaderExp

Fragment world-space position expression.

color

PBShaderExp

Lit fragment color expression; may be undefined for depth-only paths.

ssrRoughness?

PBShaderExp

Optional SSR roughness output expression.

ssrNormal?

PBShaderExp

Optional SSR normal output expression.

sssProfile?

PBShaderExp

Optional SSS profile output expression.

sssParams?

PBShaderExp

Optional SSS packed params output expression.

sssDiffuse?

PBShaderExp

Optional diffuse-only lighting color for SSS composition.

sssTransmission?

PBShaderExp

Optional thin-shell transmission lighting color for SSS composition.

sssProfileEnabled?

boolean = false

True only when this material should write SSS profile data.

skinSSS?

PBShaderExp

Returns

void

void

Released under the MIT License.