Class Material

The Material class represents a material definition for 3D rendering in the Rhodonite engine.

A material defines how a 3D object's surface appears when rendered, including:

  • Shader programs and their parameters
  • Texture bindings and sampling configurations
  • Blending and transparency settings
  • Rendering state configuration (culling, depth testing, etc.)

Key Features:

  • Shader Management: Automatically compiles and caches shader programs per primitive
  • Parameter Binding: Supports both static and animated shader parameters
  • Texture Handling: Manages texture bindings with customizable samplers
  • Blending Control: Fine-grained control over alpha blending operations
  • Multi-API Support: Compatible with both WebGL and WebGPU rendering backends
  • Performance Optimization: Fingerprint-based caching and state versioning

Material Types:

Materials are categorized by type (e.g., PBR, Phong, Custom) and can support:

  • Skinning animations for skeletal meshes
  • Morphing animations for vertex-based deformations
  • Lighting calculations with various models

Usage Examples:

// Set a basic parameter
material.setParameter('baseColorFactor', [1.0, 0.5, 0.0, 1.0]);

// Assign a texture with custom sampler
const sampler = new Sampler({ magFilter: TextureParameter.Linear });
material.setTextureParameter('baseColorTexture', texture, sampler);

// Configure blending for transparency
material.alphaMode = AlphaMode.Blend;
material.setBlendFuncFactor(Blend.SrcAlpha, Blend.OneMinusSrcAlpha);

State Management:

The material maintains internal state versioning for efficient change detection and shader program invalidation when parameters change.

See

Hierarchy (view full)

Constructors

constructor

Properties

__materialSid __materialTypeName __materialUid _allFieldVariables _allFieldsInfo _autoFieldVariablesOnly _autoTextureFieldVariablesOnly _autoUniformFieldVariablesOnly _materialContent _tags colorWriteMask cullFace cullFaceBack cullFrontFaceCCW isTranslucent zWriteWhenBlend InvalidObjectUID _soloDatumFields currentMaxObjectCount

Accessors

alphaMode alphaToCoverage blendEquationMode blendEquationModeAlpha blendFuncAlphaDstFactor blendFuncAlphaSrcFactor blendFuncDstFactor blendFuncSrcFactor fieldsInfoArray isLighting isMorphing isSkinning materialSID materialTID materialTypeName materialUID objectUID stateVersion uniqueName stateVersion

Methods

_addBelongPrimitive _copyFrom _createProgramByUpdatedSources _createProgramWebGL _createProgramWebGpu _getFingerPrint _getProperties _isAnimatedValue _setInternalSettingParametersToGpuWebGpu _setParametersToGpuWebGL _setParametersToGpuWebGLPerPrimitive _setParametersToGpuWebGLPerShaderProgram _setParametersToGpuWebGLWithOutInternalSetting _setUniformLocationsOfMaterialNodes _setupAdditionalUniformLocations _setupBasicUniformsLocations addShaderDefine calcFingerPrint getBelongPrimitives getParameter getShaderDefines getShaderProgramUid getTag getTagValue getTextureParameter hasTag isBlend isBlendOrTranslucent isMask isOpaque isShaderDefine isShaderProgramReady isTranslucentOpaque makeShadersInvalidate matchTag matchTags matchTagsAsFreeStrings removeShaderDefine removeTag setBlendEquationMode setBlendFuncFactor setBlendFuncSeparateFactor setParameter setTextureParameter setTextureParameterAsPromise tryToSetTag tryToSetUniqueName unregister validateTagString _reset getRnObject getRnObjectByName searchByTag

Constructors

constructor

  • new Material(materialTid, materialUid, materialSid, materialTypeName, materialNode): Material

  • Creates a new Material instance.

    Parameters

    • materialTid: number

      The material type ID

    • materialUid: number

      The unique material ID

    • materialSid: number

      The material serial ID within the material type

    • materialTypeName: string

      The name of the material type

    • materialNode: AbstractMaterialContent

      The abstract material content associated with this material

    Returns Material

Properties

__materialSid

__materialSid: number = -1

__materialTypeName

__materialTypeName: string

__materialUid

__materialUid: number = -1

_allFieldVariables

_allFieldVariables: Map<string, ShaderVariable> = ...

_allFieldsInfo

_allFieldsInfo: Map<string, ShaderSemanticsInfo> = ...

_autoFieldVariablesOnly

_autoFieldVariablesOnly: Map<string, ShaderVariable> = ...

_autoTextureFieldVariablesOnly

_autoTextureFieldVariablesOnly: Map<string, ShaderVariable> = ...

_autoUniformFieldVariablesOnly

_autoUniformFieldVariablesOnly: Map<string, ShaderVariable> = ...

_materialContent

_materialContent: AbstractMaterialContent

_tags

_tags: RnTags = {}

Collection of tags associated with this object

colorWriteMask

colorWriteMask: boolean[] = ...

cullFace

cullFace: boolean = true

cullFaceBack

cullFaceBack: boolean = true

cullFrontFaceCCW

cullFrontFaceCCW: boolean = true

isTranslucent

isTranslucent: boolean = false

zWriteWhenBlend

zWriteWhenBlend: boolean = false

Static ReadonlyInvalidObjectUID

InvalidObjectUID: -1 = -1

Invalid object UID constant

Static_soloDatumFields

_soloDatumFields: Map<string, Map<string, ShaderVariable>> = ...

StaticcurrentMaxObjectCount

currentMaxObjectCount: number = 0

Current maximum object count for UID generation

Accessors

alphaMode

alphaToCoverage

  • get alphaToCoverage(): boolean

  • Gets whether alpha-to-coverage is enabled for this material.

    Returns boolean

    True if alpha-to-coverage is enabled, false otherwise

  • set alphaToCoverage(alphaToCoverage): void

  • Sets whether alpha-to-coverage is enabled for this material. NOTE: To apply alpha-to-coverage, the output alpha value must not be fixed to a constant value. However, some shaders in Rhodonite fix the output alpha value to 1 by setAlphaIfNotInAlphaBlendMode. The shader needs to be improved to properly use alpha-to-coverage.

    Parameters

    • alphaToCoverage: boolean

      Whether to apply alpha-to-coverage to this material

    Returns void

blendEquationMode

blendEquationModeAlpha

blendFuncAlphaDstFactor

blendFuncAlphaSrcFactor

blendFuncDstFactor

blendFuncSrcFactor

fieldsInfoArray

isLighting

isMorphing

isSkinning

materialSID

materialTID

materialTypeName

materialUID

objectUID

  • get objectUID(): number

  • Gets the unique object identifier

    Returns number

    The object's UID

stateVersion

  • get stateVersion(): number

  • Gets the current state version of this material. This is incremented whenever the material's state changes.

    Returns number

    The state version number

uniqueName

  • get uniqueName(): string

  • Gets the unique name of this object

    Returns string

    The unique name string

StaticstateVersion

  • get stateVersion(): number

  • Gets the global state version for all materials. This is incremented whenever any material's state changes.

    Returns number

    The global state version number

Methods

_addBelongPrimitive

  • _addBelongPrimitive(primitive): void
  • Internal

    Adds a primitive to the list of primitives that belong to this material. Called from Primitive class only

    Parameters

    Returns void

_copyFrom

_createProgramByUpdatedSources

  • _createProgramByUpdatedSources(updatedShaderSources, primitive, onError?): [number, boolean]
  • Internal

    Creates a shader program using updated shader source code. Called from WebGLStrategyDataTexture and WebGLStrategyUniform

    Parameters

    • updatedShaderSources: ShaderSources

      The updated shader source code

    • primitive: Primitive

      The primitive to create the program for

    • OptionalonError: ((message: string) => void)

      Optional error callback function

        • (message): void

        • Parameters

          • message: string

          Returns void

    Returns [number, boolean]

    A tuple containing the program UID and whether it's a new program

_createProgramWebGL

  • _createProgramWebGL(vertexShaderMethodDefinitions_uniform, propertySetter, primitive, isWebGL2): [number, boolean]
  • Internal

    Creates a WebGL shader program for this material and the given primitive. Called from WebGLStrategyDataTexture and WebGLStrategyUniform

    Parameters

    • vertexShaderMethodDefinitions_uniform: string

      Vertex shader method definitions for uniforms

    • propertySetter: getShaderPropertyFunc

      Function to set shader properties

    • primitive: Primitive

      The primitive to create the program for

    • isWebGL2: boolean

      Whether to create a WebGL2 program

    Returns [number, boolean]

    A tuple containing the program UID and whether it's a new program

_createProgramWebGpu

  • _createProgramWebGpu(primitive, vertexShaderMethodDefinitions, propertySetter): void

  • Creates a WebGPU shader program for this material and the given primitive.

    Parameters

    • primitive: Primitive

      The primitive to create the program for

    • vertexShaderMethodDefinitions: string

      Vertex shader method definitions

    • propertySetter: getShaderPropertyFunc

      Function to set shader properties

    Returns void

_getFingerPrint

_getProperties

  • _getProperties(propertySetter, isWebGL2): {
        pixelPropertiesStr: string;
        vertexPropertiesStr: string;
    }
  • Internal

    Gets shader property strings for vertex and pixel shaders.

    Parameters

    • propertySetter: getShaderPropertyFunc

      Function to set shader properties

    • isWebGL2: boolean

      Whether to generate WebGL2-compatible properties

    Returns {
        pixelPropertiesStr: string;
        vertexPropertiesStr: string;
    }

    Object containing vertex and pixel property strings

    • pixelPropertiesStr: string
    • vertexPropertiesStr: string

_isAnimatedValue

  • _isAnimatedValue(value): value is IAnimatedValue

  • Checks if a value is an animated value (implements IAnimatedValue).

    Parameters

    • value: any

      The value to check

    Returns value is IAnimatedValue

    True if the value is an animated value, false otherwise

_setInternalSettingParametersToGpuWebGpu

_setParametersToGpuWebGL

  • _setParametersToGpuWebGL(params): void
  • Internal

    Sets parameters to GPU for WebGL rendering per material. Called from WebGLStrategyDataTexture and WebGLStrategyUniform only

    Parameters

    • params: {
          args: RenderingArgWebGL;
          firstTime: boolean;
          material: Material;
          shaderProgram: WebGLProgram;
      }

      Object containing rendering parameters

    Returns void

_setParametersToGpuWebGLPerPrimitive

  • _setParametersToGpuWebGLPerPrimitive(params): void

  • Sets parameters to GPU for WebGL rendering per primitive.

    Parameters

    • params: {
          args: RenderingArgWebGL;
          firstTime: boolean;
          material: Material;
          shaderProgram: WebGLProgram;
      }

      Object containing rendering parameters

    Returns void

_setParametersToGpuWebGLPerShaderProgram

  • _setParametersToGpuWebGLPerShaderProgram(params): void

  • Sets parameters to GPU for WebGL rendering per shader program.

    Parameters

    • params: {
          args: RenderingArgWebGL;
          firstTime: boolean;
          material: Material;
          shaderProgram: WebGLProgram;
      }

      Object containing rendering parameters

    Returns void

_setParametersToGpuWebGLWithOutInternalSetting

  • _setParametersToGpuWebGLWithOutInternalSetting(params): void

  • Sets parameters to GPU for WebGL rendering without internal settings.

    Parameters

    • params: {
          firstTime: boolean;
          isUniformMode: boolean;
          shaderProgram: WebGLProgram;
      }

      Object containing rendering parameters

      • firstTime: boolean
      • isUniformMode: boolean
      • shaderProgram: WebGLProgram

    Returns void

_setUniformLocationsOfMaterialNodes

  • _setUniformLocationsOfMaterialNodes(isUniformOnlyMode, primitive): void
  • Internal

    Sets up uniform locations for material nodes in the shader program. Called from WebGLStrategyDataTexture and WebGLStrategyUniform only

    Parameters

    • isUniformOnlyMode: boolean

      Whether to operate in uniform-only mode

    • primitive: Primitive

      The primitive to set up uniforms for

    Returns void

_setupAdditionalUniformLocations

  • _setupAdditionalUniformLocations(shaderSemantics, isUniformOnlyMode, primitive): void
  • Internal

    Sets up additional uniform locations in the shader program. Called by WebGLStrategyDataTexture and WebGLStrategyUniform only

    Parameters

    • shaderSemantics: ShaderSemanticsInfo[]

      Array of shader semantics to set up

    • isUniformOnlyMode: boolean

      Whether to operate in uniform-only mode

    • primitive: Primitive

      The primitive to set up uniforms for

    Returns void

_setupBasicUniformsLocations

  • _setupBasicUniformsLocations(primitive): void
  • Internal

    Sets up basic uniform locations in the shader program. Called by WebGLStrategyDataTexture and WebGLStrategyUniform only

    Parameters

    • primitive: Primitive

      The primitive to set up uniforms for

    Returns void

addShaderDefine

  • addShaderDefine(define): void

  • Adds a shader define directive that will be included in shader compilation. This will invalidate existing shaders and require recompilation.

    Parameters

    • define: string

      The define directive to add (e.g., "USE_NORMAL_MAPPING")

    Returns void

calcFingerPrint

  • calcFingerPrint(): void
  • Internal

    Calculates and updates the material's fingerprint based on current state. The fingerprint is used for shader program caching and state comparison.

    Returns void

getBelongPrimitives

getParameter

  • getParameter(shaderSemantic): any

  • Gets the parameter value for the specified shader semantic.

    Parameters

    • shaderSemantic: string

      The shader semantic name to get the parameter for

    Returns any

    The parameter value or undefined if not found

getShaderDefines

getShaderProgramUid

  • getShaderProgramUid(primitive): number

  • Gets the shader program UID for the given primitive.

    Parameters

    • primitive: Primitive

      The primitive to get the shader program UID for

    Returns number

    The shader program UID or -1 if not found

getTag

  • getTag(tagName): Tag

  • Retrieves a complete tag object (name and value) for the specified tag name

    Parameters

    • tagName: string

      The name of the tag to retrieve

    Returns Tag

    A Tag object containing the name and value

getTagValue

  • getTagValue(tagName): any

  • Retrieves the value associated with a specific tag name

    Parameters

    • tagName: string

      The name of the tag whose value to retrieve

    Returns any

    The tag value, or undefined if the tag doesn't exist

getTextureParameter

  • getTextureParameter(shaderSemantic): any

  • Gets the texture parameter for the specified shader semantic.

    Parameters

    • shaderSemantic: string

      The shader semantic name to get the texture for

    Returns any

    The texture parameter array or undefined if not found

hasTag

  • hasTag(tagName): boolean

  • Checks whether this object has a tag with the specified name

    Parameters

    • tagName: string

      The name of the tag to check for

    Returns boolean

    True if the tag exists (value is not null/undefined), false otherwise

isBlend

isBlendOrTranslucent

  • isBlendOrTranslucent(): boolean

  • Checks if the material is either in blend mode or translucent.

    Returns boolean

    True if in blend mode or translucent, false otherwise

isMask

isOpaque

isShaderDefine

  • isShaderDefine(define): boolean

  • Checks if a specific shader define directive is set on this material.

    Parameters

    • define: string

      The define directive to check for

    Returns boolean

    True if the define is set, false otherwise

isShaderProgramReady

  • isShaderProgramReady(primitive): boolean

  • Checks if the shader program is ready for the given primitive.

    Parameters

    • primitive: Primitive

      The primitive to check shader readiness for

    Returns boolean

    True if the shader program is ready, false otherwise

isTranslucentOpaque

  • isTranslucentOpaque(): boolean

  • Checks if the material is translucent but not in blend mode.

    Returns boolean

    True if alpha mode is Opaque or Mask and the material is translucent

makeShadersInvalidate

  • makeShadersInvalidate(): void

  • Invalidates all shader programs associated with this material. This forces shader recompilation on the next render.

    Returns void

matchTag

  • matchTag(tagName, tagValue): boolean

  • Checks if this object has a tag with the specified name and value

    Parameters

    • tagName: string

      The tag name to match

    • tagValue: string

      The tag value to match

    Returns boolean

    True if the object has a matching tag, false otherwise

matchTags

  • matchTags(tags): boolean

  • Checks if this object has all the specified tags with exactly matching values

    Parameters

    • tags: RnTags

      Object containing tag names as keys and expected values

    Returns boolean

    True if all specified tags exist with matching values, false otherwise

matchTagsAsFreeStrings

  • matchTagsAsFreeStrings(stringArray): boolean

  • Checks if the object's combined tag string contains all the provided search strings. This allows for flexible searching within tag names and values.

    Parameters

    • stringArray: string[]

      Array of strings that must all be present in the combined tag string

    Returns boolean

    True if all strings are found in the combined tag string, false otherwise

removeShaderDefine

  • removeShaderDefine(define): void

  • Removes a shader define directive from the material. This will invalidate existing shaders and require recompilation.

    Parameters

    • define: string

      The define directive to remove

    Returns void

removeTag

setBlendEquationMode

  • setBlendEquationMode(blendEquationMode, blendEquationModeAlpha?): void

  • Sets the blend equation mode for blending operations. This method only works if the alpha mode is set to blend.

    Parameters

    • blendEquationMode: BlendEnum

      The blend equation mode (e.g., gl.FUNC_ADD)

    • OptionalblendEquationModeAlpha: BlendEnum

      Optional separate blend equation mode for alpha channel

    Returns void

setBlendFuncFactor

  • setBlendFuncFactor(blendFuncSrcFactor, blendFuncDstFactor): void

  • Sets blend function factors for both RGB and alpha channels. This method only works if the alpha mode is set to blend.

    Parameters

    • blendFuncSrcFactor: BlendEnum

      Source blend factor

    • blendFuncDstFactor: BlendEnum

      Destination blend factor

    Returns void

setBlendFuncSeparateFactor

  • setBlendFuncSeparateFactor(blendFuncSrcFactor, blendFuncDstFactor, blendFuncAlphaSrcFactor, blendFuncAlphaDstFactor): void

  • Sets separate blend function factors for RGB and alpha channels. This method only works if the alpha mode is set to blend.

    Parameters

    • blendFuncSrcFactor: BlendEnum

      Source blend factor for RGB

    • blendFuncDstFactor: BlendEnum

      Destination blend factor for RGB

    • blendFuncAlphaSrcFactor: BlendEnum

      Source blend factor for alpha

    • blendFuncAlphaDstFactor: BlendEnum

      Destination blend factor for alpha

    Returns void

setParameter

  • setParameter(shaderSemanticName, value): void

  • Sets a parameter value for the specified shader semantic. The parameter can be a static value or an animated value.

    Parameters

    • shaderSemanticName: string

      The shader semantic name to set the parameter for

    • value: any

      The value to set (can be static or animated)

    Returns void

setTextureParameter

  • setTextureParameter(shaderSemantic, texture, sampler?): void

  • Sets a texture parameter for the specified shader semantic. If the texture has transparency, the material's alpha mode may be automatically set to Blend.

    Parameters

    • shaderSemantic: string

      The shader semantic name for the texture

    • texture: AbstractTexture

      The texture to assign

    • Optionalsampler: Sampler

      Optional sampler to use with the texture. If not provided, uses default sampler

    Returns void

setTextureParameterAsPromise

  • setTextureParameterAsPromise(shaderSemantic, promise): void

  • Sets a texture parameter from a Promise that resolves to a texture. This is useful for asynchronous texture loading.

    Parameters

    • shaderSemantic: string

      The shader semantic name for the texture

    • promise: Promise<AbstractTexture>

      A Promise that resolves to the texture

    Returns void

tryToSetTag

  • tryToSetTag(tag): boolean

  • Attempts to set a tag on this object. If the tag already exists, it will be replaced.

    Parameters

    • tag: Tag

      The tag object containing the name and value to set

    Returns boolean

    True if the tag was successfully set, false if the tag name contains invalid characters

tryToSetUniqueName

  • tryToSetUniqueName(name, toAddNameIfConflict): boolean

  • Attempts to set a unique name for this object

    Parameters

    • name: string

      The desired unique name

    • toAddNameIfConflict: boolean

      If true, appends UID to make name unique when conflicts occur; if false, fails on conflict

    Returns boolean

    True if the name was successfully set, false if there was a conflict and toAddNameIfConflict was false

unregister

validateTagString

  • validateTagString(val): boolean

  • Validates that a tag string contains only allowed characters (alphanumeric and underscore)

    Parameters

    • val: string

      The string to validate

    Returns boolean

    True if the string contains only valid characters, false if it contains invalid characters

Static_reset

StaticgetRnObject

  • getRnObject(objectUid): undefined | RnObject

  • Retrieves an RnObject instance by its unique identifier

    Parameters

    • objectUid: number

      The unique identifier of the object to retrieve

    Returns undefined | RnObject

    The RnObject instance or undefined if not found or garbage collected

StaticgetRnObjectByName

StaticsearchByTag

  • searchByTag(tag, value): undefined | WeakRef<RnObject>

  • Searches for the first object that has a specific tag with the given value

    Parameters

    • tag: string

      The tag name to search for

    • value: string

      The tag value to match

    Returns undefined | WeakRef<RnObject>

    WeakRef to the first matching object, or undefined if not found

Settings

Member Visibility

On This Page

Key Features:Material Types:Usage Examples:State Management:
Constructors
Properties
Accessors
Methods
_addBelongPrimitive_copyFrom_createProgramByUpdatedSources_createProgramWebGL_createProgramWebGpu_getFingerPrint_getProperties_isAnimatedValue_setInternalSettingParametersToGpuWebGpu_setParametersToGpuWebGL_setParametersToGpuWebGLPerPrimitive_setParametersToGpuWebGLPerShaderProgram_setParametersToGpuWebGLWithOutInternalSetting_setUniformLocationsOfMaterialNodes_setupAdditionalUniformLocations_setupBasicUniformsLocationsaddShaderDefinecalcFingerPrintgetBelongPrimitivesgetParametergetShaderDefinesgetShaderProgramUidgetTaggetTagValuegetTextureParameterhasTagisBlendisBlendOrTranslucentisMaskisOpaqueisShaderDefineisShaderProgramReadyisTranslucentOpaquemakeShadersInvalidatematchTagmatchTagsmatchTagsAsFreeStringsremoveShaderDefineremoveTagsetBlendEquationModesetBlendFuncFactorsetBlendFuncSeparateFactorsetParametersetTextureParametersetTextureParameterAsPromisetryToSetTagtryToSetUniqueNameunregistervalidateTagString_resetgetRnObjectgetRnObjectByNamesearchByTag