API
API|
@babylonjs/core|
MaterialHelper

Class MaterialHelper

"Static Class" containing the most commonly used helper while dealing with material for rendering purpose.

It contains the basic tools to help defining defines, binding uniform for the common part of the materials.

This works by convention in BabylonJS but is meant to be use only with shader following the in place naming rules and conventions.

Index
constructor
BindBonesParameters BindFogParameters BindLight BindLightProperties BindLights BindLogDepth BindMorphTargetParameters BindSceneUniformBuffer BindTextureMatrix GetFogState HandleFallbacksForShadows PrepareAttributesForBakedVertexAnimation PrepareAttributesForBones PrepareAttributesForInstances PrepareAttributesForMorphTargets PrepareAttributesForMorphTargetsInfluencers PrepareDefinesForAttributes PrepareDefinesForBakedVertexAnimation PrepareDefinesForBones PrepareDefinesForCamera PrepareDefinesForFrameBoundValues PrepareDefinesForLight PrepareDefinesForLights PrepareDefinesForMergedUV PrepareDefinesForMisc PrepareDefinesForMorphTargets PrepareDefinesForMultiview PrepareDefinesForOIT PrepareDefinesForPrePass PrepareUniformsAndSamplersForLight PrepareUniformsAndSamplersList PushAttributesForInstances
BindBonesParameters: (
    mesh?: AbstractMesh,
    effect?: Effect,
    prePassConfiguration?: PrePassConfiguration,
) => void = BindBonesParameters

Binds the bones information from the mesh to the effect.

Type Declaration

    • (
          mesh?: AbstractMesh,
          effect?: Effect,
          prePassConfiguration?: PrePassConfiguration,
      ): void

    • Parameters

      • Optionalmesh: AbstractMesh

        The mesh we are binding the information to render

      • Optionaleffect: Effect

        The effect we are binding the data to

      • OptionalprePassConfiguration: PrePassConfiguration

        Configuration for the prepass, in case prepass is activated

      Returns void

BindFogParameters: (
    scene: Scene,
    mesh?: AbstractMesh,
    effect?: Effect,
    linearSpace?: boolean,
) => void = BindFogParameters

Binds the fog information from the scene to the effect for the given mesh.

Type Declaration

    • (
          scene: Scene,
          mesh?: AbstractMesh,
          effect?: Effect,
          linearSpace?: boolean,
      ): void

    • Parameters

      • scene: Scene

        The scene the lights belongs to

      • Optionalmesh: AbstractMesh

        The mesh we are binding the information to render

      • Optionaleffect: Effect

        The effect we are binding the data to

      • OptionallinearSpace: boolean

        Defines if the fog effect is applied in linear space

      Returns void

BindLight: (
    light: Light,
    lightIndex: number,
    scene: Scene,
    effect: Effect,
    useSpecular: boolean,
    receiveShadows?: boolean,
) => void = BindLight

Binds the lights information from the scene to the effect for the given mesh.

Type Declaration

    • (
          light: Light,
          lightIndex: number,
          scene: Scene,
          effect: Effect,
          useSpecular: boolean,
          receiveShadows?: boolean,
      ): void

    • Parameters

      • light: Light

        Light to bind

      • lightIndex: number

        Light index

      • scene: Scene

        The scene where the light belongs to

      • effect: Effect

        The effect we are binding the data to

      • useSpecular: boolean

        Defines if specular is supported

      • OptionalreceiveShadows: boolean

        Defines if the effect (mesh) we bind the light for receives shadows

      Returns void

BindLightProperties: (light: Light, effect: Effect, lightIndex: number) => void = BindLightProperties

Binds the light information to the effect.

Type Declaration

    • (light: Light, effect: Effect, lightIndex: number): void

    • Parameters

      • light: Light

        The light containing the generator

      • effect: Effect

        The effect we are binding the data to

      • lightIndex: number

        The light index in the effect used to render

      Returns void

BindLights: (
    scene: Scene,
    mesh: AbstractMesh,
    effect: Effect,
    defines: any,
    maxSimultaneousLights?: number,
) => void = BindLights

Binds the lights information from the scene to the effect for the given mesh.

Type Declaration

    • (
          scene: Scene,
          mesh: AbstractMesh,
          effect: Effect,
          defines: any,
          maxSimultaneousLights?: number,
      ): void

    • Parameters

      • scene: Scene

        The scene the lights belongs to

      • mesh: AbstractMesh

        The mesh we are binding the information to render

      • effect: Effect

        The effect we are binding the data to

      • defines: any

        The generated defines for the effect

      • OptionalmaxSimultaneousLights: number

        The maximum number of light that can be bound to the effect

      Returns void

BindLogDepth: (defines: any, effect: Effect, scene: Scene) => void = BindLogDepth

Binds the logarithmic depth information from the scene to the effect for the given defines.

Type Declaration

    • (defines: any, effect: Effect, scene: Scene): void

    • Parameters

      • defines: any

        The generated defines used in the effect

      • effect: Effect

        The effect we are binding the data to

      • scene: Scene

        The scene we are willing to render with logarithmic scale for

      Returns void

BindMorphTargetParameters: (abstractMesh: AbstractMesh, effect: Effect) => void = BindMorphTargetParameters

Binds the morph targets information from the mesh to the effect.

Type Declaration

    • (abstractMesh: AbstractMesh, effect: Effect): void

    • Parameters

      • abstractMesh: AbstractMesh

        The mesh we are binding the information to render

      • effect: Effect

        The effect we are binding the data to

      Returns void

BindSceneUniformBuffer: (effect: Effect, sceneUbo: UniformBuffer) => void = BindSceneUniformBuffer

Binds the scene's uniform buffer to the effect.

Type Declaration

    • (effect: Effect, sceneUbo: UniformBuffer): void

    • Parameters

      • effect: Effect

        defines the effect to bind to the scene uniform buffer

      • sceneUbo: UniformBuffer

        defines the uniform buffer storing scene data

      Returns void

BindTextureMatrix: (
    texture: BaseTexture,
    uniformBuffer: UniformBuffer,
    key: string,
) => void = BindTextureMatrix

Binds a texture matrix value to its corresponding uniform

Type Declaration

    • (texture: BaseTexture, uniformBuffer: UniformBuffer, key: string): void

    • Parameters

      • texture: BaseTexture

        The texture to bind the matrix for

      • uniformBuffer: UniformBuffer

        The uniform buffer receiving the data

      • key: string

        The channel key "diffuse", "specular"... used in the shader

      Returns void

GetFogState: (mesh: AbstractMesh, scene: Scene) => boolean = GetFogState

Gets the current status of the fog (should it be enabled?)

Type Declaration

    • (mesh: AbstractMesh, scene: Scene): boolean

    • Parameters

      • mesh: AbstractMesh

        defines the mesh to evaluate for fog support

      • scene: Scene

        defines the hosting scene

      Returns boolean

      true if fog must be enabled

HandleFallbacksForShadows: (
    defines: any,
    fallbacks: EffectFallbacks,
    maxSimultaneousLights?: number,
    rank?: number,
) => number = HandleFallbacksForShadows

This helps decreasing rank by rank the shadow quality (0 being the highest rank and quality)

Type Declaration

    • (
          defines: any,
          fallbacks: EffectFallbacks,
          maxSimultaneousLights?: number,
          rank?: number,
      ): number

    • Parameters

      • defines: any

        The defines to update while falling back

      • fallbacks: EffectFallbacks

        The authorized effect fallbacks

      • OptionalmaxSimultaneousLights: number

        The maximum number of lights allowed

      • Optionalrank: number

        the current rank of the Effect

      Returns number

      The newly affected rank

PrepareAttributesForBakedVertexAnimation: (
    attribs: string[],
    mesh: AbstractMesh,
    defines: any,
) => void = PrepareAttributesForBakedVertexAnimation

Prepares the list of attributes required for baked vertex animations according to the effect defines.

Type Declaration

    • (attribs: string[], mesh: AbstractMesh, defines: any): void

    • Parameters

      • attribs: string[]

        The current list of supported attribs

      • mesh: AbstractMesh

        The mesh to prepare for baked vertex animations

      • defines: any

        The current Defines of the effect

      Returns void

PrepareAttributesForBones: (
    attribs: string[],
    mesh: AbstractMesh,
    defines: any,
    fallbacks: EffectFallbacks,
) => void = PrepareAttributesForBones

Prepares the list of attributes required for bones according to the effect defines.

Type Declaration

    • (
          attribs: string[],
          mesh: AbstractMesh,
          defines: any,
          fallbacks: EffectFallbacks,
      ): void

    • Parameters

      • attribs: string[]

        The current list of supported attribs

      • mesh: AbstractMesh

        The mesh to prepare the bones attributes for

      • defines: any

        The current Defines of the effect

      • fallbacks: EffectFallbacks

        The current effect fallback strategy

      Returns void

PrepareAttributesForInstances: (
    attribs: string[],
    defines: MaterialDefines,
) => void = PrepareAttributesForInstances

Check and prepare the list of attributes required for instances according to the effect defines.

Type Declaration

    • (attribs: string[], defines: MaterialDefines): void

    • Parameters

      • attribs: string[]

        The current list of supported attribs

      • defines: MaterialDefines

        The current MaterialDefines of the effect

      Returns void

PrepareAttributesForMorphTargets: (
    attribs: string[],
    mesh: AbstractMesh,
    defines: any,
) => void = PrepareAttributesForMorphTargets

Prepares the list of attributes required for morph targets according to the effect defines.

Type Declaration

    • (attribs: string[], mesh: AbstractMesh, defines: any): void

    • Parameters

      • attribs: string[]

        The current list of supported attribs

      • mesh: AbstractMesh

        The mesh to prepare the morph targets attributes for

      • defines: any

        The current Defines of the effect

      Returns void

PrepareAttributesForMorphTargetsInfluencers: (
    attribs: string[],
    mesh: AbstractMesh,
    influencers: number,
) => void = PrepareAttributesForMorphTargetsInfluencers

Prepares the list of attributes required for morph targets according to the effect defines.

Type Declaration

    • (attribs: string[], mesh: AbstractMesh, influencers: number): void

    • Parameters

      • attribs: string[]

        The current list of supported attribs

      • mesh: AbstractMesh

        The mesh to prepare the morph targets attributes for

      • influencers: number

        The number of influencers

      Returns void

PrepareDefinesForAttributes: (
    mesh: AbstractMesh,
    defines: any,
    useVertexColor: boolean,
    useBones: boolean,
    useMorphTargets?: boolean,
    useVertexAlpha?: boolean,
    useBakedVertexAnimation?: boolean,
) => boolean = PrepareDefinesForAttributes

Prepares the defines used in the shader depending on the attributes data available in the mesh

Type Declaration

    • (
          mesh: AbstractMesh,
          defines: any,
          useVertexColor: boolean,
          useBones: boolean,
          useMorphTargets?: boolean,
          useVertexAlpha?: boolean,
          useBakedVertexAnimation?: boolean,
      ): boolean

    • Parameters

      • mesh: AbstractMesh

        The mesh containing the geometry data we will draw

      • defines: any

        The defines to update

      • useVertexColor: boolean

        Precise whether vertex colors should be used or not (override mesh info)

      • useBones: boolean

        Precise whether bones should be used or not (override mesh info)

      • OptionaluseMorphTargets: boolean

        Precise whether morph targets should be used or not (override mesh info)

      • OptionaluseVertexAlpha: boolean

        Precise whether vertex alpha should be used or not (override mesh info)

      • OptionaluseBakedVertexAnimation: boolean

        Precise whether baked vertex animation should be used or not (override mesh info)

      Returns boolean

      false if defines are considered not dirty and have not been checked

PrepareDefinesForBakedVertexAnimation: (
    mesh: AbstractMesh,
    defines: any,
) => void = PrepareDefinesForBakedVertexAnimation

Prepares the defines for baked vertex animation

Type Declaration

    • (mesh: AbstractMesh, defines: any): void

    • Parameters

      • mesh: AbstractMesh

        The mesh containing the geometry data we will draw

      • defines: any

        The defines to update

      Returns void

PrepareDefinesForBones: (mesh: AbstractMesh, defines: any) => void = PrepareDefinesForBones

Prepares the defines for bones

Type Declaration

    • (mesh: AbstractMesh, defines: any): void

    • Parameters

      • mesh: AbstractMesh

        The mesh containing the geometry data we will draw

      • defines: any

        The defines to update

      Returns void

PrepareDefinesForCamera: (scene: Scene, defines: any) => boolean = PrepareDefinesForCamera

Helper used to prepare the defines relative to the active camera

Type Declaration

    • (scene: Scene, defines: any): boolean

    • Parameters

      • scene: Scene

        defines the current scene

      • defines: any

        specifies the list of active defines

      Returns boolean

      true if the defines have been updated, else false

PrepareDefinesForFrameBoundValues: (
    scene: Scene,
    engine: AbstractEngine,
    material: Material,
    defines: any,
    useInstances: boolean,
    useClipPlane?: Nullable<boolean>,
    useThinInstances?: boolean,
) => void = PrepareDefinesForFrameBoundValues

Helper used to prepare the list of defines associated with frame values for shader compilation

Type Declaration

    • (
          scene: Scene,
          engine: AbstractEngine,
          material: Material,
          defines: any,
          useInstances: boolean,
          useClipPlane?: Nullable<boolean>,
          useThinInstances?: boolean,
      ): void

    • Parameters

      • scene: Scene

        defines the current scene

      • engine: AbstractEngine

        defines the current engine

      • material: Material

        defines the material we are compiling the shader for

      • defines: any

        specifies the list of active defines

      • useInstances: boolean

        defines if instances have to be turned on

      • OptionaluseClipPlane: Nullable<boolean>

        defines if clip plane have to be turned on

      • OptionaluseThinInstances: boolean

        defines if thin instances have to be turned on

      Returns void

PrepareDefinesForLight: (
    scene: Scene,
    mesh: AbstractMesh,
    light: Light,
    lightIndex: number,
    defines: any,
    specularSupported: boolean,
    state: {
        lightmapMode: boolean;
        needNormals: boolean;
        needRebuild: boolean;
        shadowEnabled: boolean;
        specularEnabled: boolean;
    },
) => void = PrepareDefinesForLight

Prepares the defines related to the light information passed in parameter

Type Declaration

    • (
          scene: Scene,
          mesh: AbstractMesh,
          light: Light,
          lightIndex: number,
          defines: any,
          specularSupported: boolean,
          state: {
              lightmapMode: boolean;
              needNormals: boolean;
              needRebuild: boolean;
              shadowEnabled: boolean;
              specularEnabled: boolean;
          },
      ): void

    • Parameters

      • scene: Scene

        The scene we are intending to draw

      • mesh: AbstractMesh

        The mesh the effect is compiling for

      • light: Light

        The light the effect is compiling for

      • lightIndex: number

        The index of the light

      • defines: any

        The defines to update

      • specularSupported: boolean

        Specifies whether specular is supported or not (override lights data)

      • state: {
            lightmapMode: boolean;
            needNormals: boolean;
            needRebuild: boolean;
            shadowEnabled: boolean;
            specularEnabled: boolean;
        }

        Defines the current state regarding what is needed (normals, etc...)

      Returns void

PrepareDefinesForLights: (
    scene: Scene,
    mesh: AbstractMesh,
    defines: any,
    specularSupported: boolean,
    maxSimultaneousLights?: number,
    disableLighting?: boolean,
) => boolean = PrepareDefinesForLights

Prepares the defines related to the light information passed in parameter

Type Declaration

    • (
          scene: Scene,
          mesh: AbstractMesh,
          defines: any,
          specularSupported: boolean,
          maxSimultaneousLights?: number,
          disableLighting?: boolean,
      ): boolean

    • Parameters

      • scene: Scene

        The scene we are intending to draw

      • mesh: AbstractMesh

        The mesh the effect is compiling for

      • defines: any

        The defines to update

      • specularSupported: boolean

        Specifies whether specular is supported or not (override lights data)

      • OptionalmaxSimultaneousLights: number

        Specifies how manuy lights can be added to the effect at max

      • OptionaldisableLighting: boolean

        Specifies whether the lighting is disabled (override scene and light)

      Returns boolean

      true if normals will be required for the rest of the effect

PrepareDefinesForMergedUV: (
    texture: BaseTexture,
    defines: any,
    key: string,
) => void = PrepareDefinesForMergedUV

Helps preparing the defines values about the UVs in used in the effect. UVs are shared as much as we can across channels in the shaders.

Type Declaration

    • (texture: BaseTexture, defines: any, key: string): void

    • Parameters

      • texture: BaseTexture

        The texture we are preparing the UVs for

      • defines: any

        The defines to update

      • key: string

        The channel key "diffuse", "specular"... used in the shader

      Returns void

PrepareDefinesForMisc: (
    mesh: AbstractMesh,
    scene: Scene,
    useLogarithmicDepth: boolean,
    pointsCloud: boolean,
    fogEnabled: boolean,
    alphaTest: boolean,
    defines: any,
    applyDecalAfterDetail?: boolean,
) => void = PrepareDefinesForMisc

Helper used to prepare the list of defines associated with misc. values for shader compilation

Type Declaration

    • (
          mesh: AbstractMesh,
          scene: Scene,
          useLogarithmicDepth: boolean,
          pointsCloud: boolean,
          fogEnabled: boolean,
          alphaTest: boolean,
          defines: any,
          applyDecalAfterDetail?: boolean,
      ): void

    • Parameters

      • mesh: AbstractMesh

        defines the current mesh

      • scene: Scene

        defines the current scene

      • useLogarithmicDepth: boolean

        defines if logarithmic depth has to be turned on

      • pointsCloud: boolean

        defines if point cloud rendering has to be turned on

      • fogEnabled: boolean

        defines if fog has to be turned on

      • alphaTest: boolean

        defines if alpha testing has to be turned on

      • defines: any

        defines the current list of defines

      • OptionalapplyDecalAfterDetail: boolean

        Defines if the decal is applied after or before the detail

      Returns void

PrepareDefinesForMorphTargets: (mesh: AbstractMesh, defines: any) => void = PrepareDefinesForMorphTargets

Prepares the defines for morph targets

Type Declaration

    • (mesh: AbstractMesh, defines: any): void

    • Parameters

      • mesh: AbstractMesh

        The mesh containing the geometry data we will draw

      • defines: any

        The defines to update

      Returns void

PrepareDefinesForMultiview: (scene: Scene, defines: any) => void = PrepareDefinesForMultiview

Prepares the defines related to multiview

Type Declaration

    • (scene: Scene, defines: any): void

    • Parameters

      • scene: Scene

        The scene we are intending to draw

      • defines: any

        The defines to update

      Returns void

PrepareDefinesForOIT: (
    scene: Scene,
    defines: any,
    needAlphaBlending: boolean,
) => void = PrepareDefinesForOIT

Prepares the defines related to order independant transparency

Type Declaration

    • (scene: Scene, defines: any, needAlphaBlending: boolean): void

    • Parameters

      • scene: Scene

        The scene we are intending to draw

      • defines: any

        The defines to update

      • needAlphaBlending: boolean

        Determines if the material needs alpha blending

      Returns void

PrepareDefinesForPrePass: (
    scene: Scene,
    defines: any,
    canRenderToMRT: boolean,
) => void = PrepareDefinesForPrePass

Prepares the defines related to the prepass

Type Declaration

    • (scene: Scene, defines: any, canRenderToMRT: boolean): void

    • Parameters

      • scene: Scene

        The scene we are intending to draw

      • defines: any

        The defines to update

      • canRenderToMRT: boolean

        Indicates if this material renders to several textures in the prepass

      Returns void

PrepareUniformsAndSamplersForLight: (
    lightIndex: number,
    uniformsList: string[],
    samplersList: string[],
    projectedLightTexture?: any,
    uniformBuffersList?: Nullable<string[]>,
    updateOnlyBuffersList?: boolean,
) => void = PrepareUniformsAndSamplersForLight

Prepares the uniforms and samplers list to be used in the effect (for a specific light)

Type Declaration

    • (
          lightIndex: number,
          uniformsList: string[],
          samplersList: string[],
          projectedLightTexture?: any,
          uniformBuffersList?: Nullable<string[]>,
          updateOnlyBuffersList?: boolean,
      ): void

    • Parameters

      • lightIndex: number

        defines the light index

      • uniformsList: string[]

        The uniform list

      • samplersList: string[]

        The sampler list

      • OptionalprojectedLightTexture: any

        defines if projected texture must be used

      • OptionaluniformBuffersList: Nullable<string[]>

        defines an optional list of uniform buffers

      • OptionalupdateOnlyBuffersList: boolean

        True to only update the uniformBuffersList array

      Returns void

PrepareUniformsAndSamplersList: (
    uniformsListOrOptions: string[] | IEffectCreationOptions,
    samplersList?: string[],
    defines?: any,
    maxSimultaneousLights?: number,
) => void = PrepareUniformsAndSamplersList

Prepares the uniforms and samplers list to be used in the effect

Type Declaration

    • (
          uniformsListOrOptions: string[] | IEffectCreationOptions,
          samplersList?: string[],
          defines?: any,
          maxSimultaneousLights?: number,
      ): void

    • Parameters

      • uniformsListOrOptions: string[] | IEffectCreationOptions

        The uniform names to prepare or an EffectCreationOptions containing the list and extra information

      • OptionalsamplersList: string[]

        The sampler list

      • Optionaldefines: any

        The defines helping in the list generation

      • OptionalmaxSimultaneousLights: number

        The maximum number of simultaneous light allowed in the effect

      Returns void

PushAttributesForInstances: (
    attribs: string[],
    needsPreviousMatrices?: boolean,
) => void = PushAttributesForInstances

Add the list of attributes required for instances to the attribs array.

Type Declaration

    • (attribs: string[], needsPreviousMatrices?: boolean): void

    • Parameters

      • attribs: string[]

        The current list of supported attribs

      • OptionalneedsPreviousMatrices: boolean

        If the shader needs previous matrices

      Returns void