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
_featureStatesand hashed into_createHash(). - Changing features calls
useFeature(...)which triggersoptionChanged(true)to rebuild programs.
Instancing:
defineInstanceUniformregisters 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)andfragmentShader(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 optionallyoutputFragmentColor. - 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 = 1alphaCutoff = 0taaStrength = 1 - 1/16
Returns
MeshMaterial
Overrides
Accessors
disposed
Get Signature
get disposed():
boolean
Defined in: libs/base/dist/index.d.ts:6065
Returns
boolean
Inherited from
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
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
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
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
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
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
Set Signature
set blendMode(
val):void
Defined in: libs/scene/src/material/meshmaterial.ts:595
Parameters
val
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
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
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
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
dispose()
dispose():
void
Defined in: libs/base/dist/index.d.ts:6066
Returns
void
Inherited from
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
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
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
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
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
Draw context.
needUpdate
boolean
Whether uniforms need to be refreshed.
pass
number
Pass index.
Returns
void
Inherited from
clearCache()
clearCache():
void
Defined in: libs/scene/src/material/material.ts:440
Returns
void
Inherited from
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
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.numInstancesif available. - Else issues a non-instanced draw.
Parameters
pass
number
Pass number.
primitive
Primitive to draw.
ctx
Draw context.
numInstances
number
Explicit instance count (0 = auto).
Returns
void
Inherited from
onDispose()
protectedonDispose():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
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
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
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
Current draw context.
Returns
boolean
Whether material preparation succeeded.
Overrides
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()
staticdefineFeature():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()
staticdefineInstanceUniform(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
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
defineInstanceUniformwith getter/setter that read/write the packed buffer and notifyRenderBundleWrapper. - Delegates methods to the core material via prototype chain.
Returns
this
Overrides
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
getEffectiveBlendMode()
protectedgetEffectiveBlendMode(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?
Returns
getActiveAlphaCutoff()
protectedgetActiveAlphaCutoff(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?
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?
_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()
protectedusesAlphaCutoff(ctx?,pass?):boolean
Defined in: libs/scene/src/material/meshmaterial.ts:716
Whether this pass needs an alpha-cutoff uniform bound.
Parameters
ctx?
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?
Returns
boolean
updateRenderStates()
protectedupdateRenderStates(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
Current draw context.
Returns
void
void
Overrides
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
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
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?
Returns
boolean
True if the pass is transparent; otherwise false.
Overrides
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?
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