rhodonite
    Preparing search index...

    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.)
    • 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

    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
    // 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);

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

    Hierarchy (View Summary)

    Index

    Constructors

    constructor

    Properties

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

    Accessors

    alphaMode alphaToCoverage baseMaterialName blendEquationMode blendEquationModeAlpha blendFuncAlphaDstFactor blendFuncAlphaSrcFactor blendFuncDstFactor blendFuncSrcFactor fieldsInfoArray isLighting isMorphing isNodeBasedMaterial isSkinning materialSID materialTID materialTypeName materialUID materialVariationIdentifier objectUID shaderNodeFileName shaderNodeJson shaderNodeUniforms stateVersion uniqueName

    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 updateStateVersion validateTagString _reset getRnObject getRnObjectByName searchByTag

    Constructors

    Properties

    __materialSid

    __materialSid: number = -1

    __materialTypeName

    __materialTypeName: string

    __materialUid

    __materialUid: number = -1

    _allFieldsInfo

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

    _allFieldVariables

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

    _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: boolean[] = ...
    cullFace: boolean = true
    cullFaceBack: boolean = true
    cullFrontFaceCCW: boolean = true
    isTranslucent: boolean = false
    zWriteWhenBlend: boolean = false
    currentMaxObjectCount: number = 0

    Current maximum object count for UID generation

    InvalidObjectUID: -1

    Invalid object UID constant

    Accessors

    • 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: boolean): 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

    • get baseMaterialName(): string

      Gets the base material name without variation identifier. This is the human-readable material type name (e.g., "PbrUber", "ClassicUber").

      Returns string

      The base material name

    • get isNodeBasedMaterial(): boolean

      Checks if this material is a node-based custom shader material.

      Returns boolean

      True if this is a node-based material (has shaderNodeJson set)

    • get materialTypeName(): string

      Gets the material type name. This includes the full type name with variation identifier for internal use.

      Returns string

      The material type name

    • get materialVariationIdentifier(): string

      Gets the material variation identifier. This represents the parameter variation part of the material type.

      Returns string

      The variation identifier string

    • get objectUID(): number

      Gets the unique object identifier

      Returns number

      The object's UID

    • get shaderNodeFileName(): string | undefined

      Gets the shader node file name for export. This is used to specify the .rmn file name in the RHODONITE_materials_node extension.

      Returns string | undefined

      The shader node file name, or undefined if not set

    • set shaderNodeFileName(fileName: string | undefined): void

      Sets the shader node file name for export.

      Parameters

      • fileName: string | undefined

        The .rmn file name to use in the RHODONITE_materials_node extension

      Returns void

    • get shaderNodeJson(): unknown

      Gets the shader node JSON data for node-based materials. This is used by RHODONITE_materials_node extension.

      Returns unknown

      The shader node JSON data, or undefined if not a node-based material

    • set shaderNodeJson(json: unknown): void

      Sets the shader node JSON data for node-based materials. This marks the material as a node-based custom shader material.

      Parameters

      • json: unknown

        The shader node JSON data

      Returns void

    • get shaderNodeUniforms(): { [name: string]: number | number[] } | undefined

      Gets the uniform values for node-based materials.

      Returns { [name: string]: number | number[] } | undefined

      The uniform values object, or undefined if not set

    • set shaderNodeUniforms(
          uniforms: { [name: string]: number | number[] } | undefined,
      ): void

      Sets the uniform values for node-based materials.

      Parameters

      • uniforms: { [name: string]: number | number[] } | undefined

        The uniform values object

      Returns void

    • 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

    • get uniqueName(): string

      Gets the unique name of this object

      Returns string

      The unique name string

    Methods

    _addBelongPrimitive

    _copyFrom

    _createProgramByUpdatedSources

    • _createProgramByUpdatedSources(
          updatedShaderSources: ShaderSources,
          primitive: Primitive,
          onError?: (message: string) => void,
      ): [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

      Returns [number, boolean]

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

    _createProgramWebGL

    • _createProgramWebGL(
          engine: Engine,
          componentDataAccessMethodDefinitionsForVertexShader: string,
          componentDataAccessMethodDefinitionsForPixelShader: string,
          propertySetterOfGlobalDataRepository: getShaderPropertyFuncOfGlobalDataRepository,
          propertySetterOfMaterial: getShaderPropertyFuncOfMaterial,
          morphedPositionGetter: string,
          primitive: Primitive,
      ): [number, boolean]
      Internal

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

      Parameters

      • engine: Engine
      • componentDataAccessMethodDefinitionsForVertexShader: string

        method definitions for component data access for vertex shader

      • componentDataAccessMethodDefinitionsForPixelShader: string

        method definitions for component data access for pixel shader

      • propertySetterOfGlobalDataRepository: getShaderPropertyFuncOfGlobalDataRepository

        Function to set shader properties of global data repository

      • propertySetterOfMaterial: getShaderPropertyFuncOfMaterial

        Function to set shader properties of material

      • morphedPositionGetter: string

        Function to get the morphed position

      • primitive: Primitive

        The primitive to create the program for

      Returns [number, boolean]

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

    _createProgramWebGpu

    • _createProgramWebGpu(
          engine: Engine,
          primitive: Primitive,
          componentDataAccessMethodDefinitionsForVertexShader: string,
          componentDataAccessMethodDefinitionsForPixelShader: string,
          propertySetterOfGlobalDataRepository: getShaderPropertyFuncOfGlobalDataRepository,
          propertySetterOfMaterial: getShaderPropertyFuncOfMaterial,
          morphedPositionGetter: string,
      ): void

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

      Parameters

      • engine: Engine
      • primitive: Primitive

        The primitive to create the program for

      • componentDataAccessMethodDefinitionsForVertexShader: string

        method definitions for component data access for vertex shader

      • componentDataAccessMethodDefinitionsForPixelShader: string

        method definitions for component data access for pixel shader

      • propertySetterOfGlobalDataRepository: getShaderPropertyFuncOfGlobalDataRepository

        Function to set shader properties of global data repository

      • propertySetterOfMaterial: getShaderPropertyFuncOfMaterial

        Function to set shader properties of material

      • morphedPositionGetter: string

        Function to get the morphed position

      Returns void

    _getFingerPrint

    _getProperties

    _isAnimatedValue

    • _isAnimatedValue(value: any): 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: {
              args: RenderingArgWebGL;
              engine: Engine;
              firstTime: boolean;
              material: Material;
              shaderProgram: WebGLProgram;
          },
      ): void
      Internal

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

      Parameters

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

        Object containing rendering parameters

      Returns void

    _setParametersToGpuWebGLPerPrimitive

    • _setParametersToGpuWebGLPerPrimitive(
          params: {
              args: RenderingArgWebGL;
              firstTime: boolean;
              material: Material;
              shaderProgram: WebGLProgram;
          },
      ): 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: {
              args: RenderingArgWebGL;
              engine: Engine;
              firstTime: boolean;
              material: Material;
              shaderProgram: WebGLProgram;
          },
      ): void

      Sets parameters to GPU for WebGL rendering per shader program.

      Parameters

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

        Object containing rendering parameters

      Returns void

    _setParametersToGpuWebGLWithOutInternalSetting

    • _setParametersToGpuWebGLWithOutInternalSetting(
          params: {
              firstTime: boolean;
              isUniformMode: boolean;
              shaderProgram: WebGLProgram;
          },
      ): void

      Sets parameters to GPU for WebGL rendering without internal settings.

      Parameters

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

        Object containing rendering parameters

      Returns void

    _setUniformLocationsOfMaterialNodes

    • _setUniformLocationsOfMaterialNodes(
          isUniformOnlyMode: boolean,
          primitive: 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: ShaderSemanticsInfo[],
          isUniformOnlyMode: boolean,
          primitive: 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: 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

    • 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

    • 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

    • 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

    • 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

    • 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

    • 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

    • 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

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

      Returns boolean

      True if in blend mode or translucent, false otherwise

    • 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

    • 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

    • 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

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

      Returns void

    • 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

    • 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

    • 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

    • 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

    • 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

    • 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

    • 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

    • 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

    • 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

    • 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

    • 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

    • 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

    • 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

    • Retrieves an RnObject instance by its unique identifier

      Parameters

      • objectUid: number

        The unique identifier of the object to retrieve

      Returns RnObject | undefined

      The RnObject instance or undefined if not found or garbage collected

    • 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 WeakRef<RnObject> | undefined

      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_setupBasicUniformsLocationsaddShaderDefinecalcFingerPrintgetBelongPrimitivesgetParametergetShaderDefinesgetShaderProgramUidgetTaggetTagValuegetTextureParameterhasTagisBlendisBlendOrTranslucentisMaskisOpaqueisShaderDefineisShaderProgramReadyisTranslucentOpaquemakeShadersInvalidatematchTagmatchTagsmatchTagsAsFreeStringsremoveShaderDefineremoveTagsetBlendEquationModesetBlendFuncFactorsetBlendFuncSeparateFactorsetParametersetTextureParametersetTextureParameterAsPromisetryToSetTagtryToSetUniqueNameunregisterupdateStateVersionvalidateTagString_resetgetRnObjectgetRnObjectByNamesearchByTag