playcanvas
Version:
PlayCanvas WebGL game engine
832 lines (752 loc) • 71.7 kB
TypeScript
/**
* Callback used by {@link StandardMaterial#onUpdateShader}.
*/
export type UpdateShaderCallback = (options: StandardMaterialOptions) => StandardMaterialOptions;
/**
* @callback UpdateShaderCallback
* Callback used by {@link StandardMaterial#onUpdateShader}.
* @param {StandardMaterialOptions} options - An object with shader generator settings (based on current
* material and scene properties), that you can change and then return. Properties of the object passed
* into this function are documented in {@link StandardMaterial}. Also contains a member named litOptions
* which holds some of the options only used by the lit shader backend {@link LitShaderOptions}.
* @returns {StandardMaterialOptions} Returned settings will be used by the shader.
*/
/**
* A standard material is the main, general purpose material that is most often used for rendering.
* It can approximate a wide variety of surface types and can simulate dynamic reflected light.
* Most maps can use 3 types of input values in any combination: constant ({@link Color} or number),
* mesh vertex colors and a {@link Texture}. All enabled inputs are multiplied together.
*
* @property {Color} ambient The ambient color of the material. This color value is 3-component
* (RGB), where each component is between 0 and 1.
* @property {Color} diffuse The diffuse color of the material. This color value is 3-component
* (RGB), where each component is between 0 and 1. Defines basic surface color (aka albedo).
* @property {Texture|null} diffuseMap The main (primary) diffuse map of the material (default is
* null).
* @property {number} diffuseMapUv Main (primary) diffuse map UV channel.
* @property {Vec2} diffuseMapTiling Controls the 2D tiling of the main (primary) diffuse map.
* @property {Vec2} diffuseMapOffset Controls the 2D offset of the main (primary) diffuse map. Each
* component is between 0 and 1.
* @property {number} diffuseMapRotation Controls the 2D rotation (in degrees) of the main
* (primary) diffuse map.
* @property {string} diffuseMapChannel Color channels of the main (primary) diffuse map to use.
* Can be "r", "g", "b", "a", "rgb" or any swizzled combination.
* @property {boolean} diffuseVertexColor Multiply diffuse by the mesh vertex colors.
* @property {string} diffuseVertexColorChannel Vertex color channels to use for diffuse. Can be
* "r", "g", "b", "a", "rgb" or any swizzled combination.
* @property {Texture|null} diffuseDetailMap The detail (secondary) diffuse map of the material
* (default is null). Will only be used if main (primary) diffuse map is non-null.
* @property {number} diffuseDetailMapUv Detail (secondary) diffuse map UV channel.
* @property {Vec2} diffuseDetailMapTiling Controls the 2D tiling of the detail (secondary) diffuse
* map.
* @property {Vec2} diffuseDetailMapOffset Controls the 2D offset of the detail (secondary) diffuse
* map. Each component is between 0 and 1.
* @property {number} diffuseDetailMapRotation Controls the 2D rotation (in degrees) of the main
* (secondary) diffuse map.
* @property {string} diffuseDetailMapChannel Color channels of the detail (secondary) diffuse map
* to use. Can be "r", "g", "b", "a", "rgb" or any swizzled combination.
* @property {string} diffuseDetailMode Determines how the main (primary) and detail (secondary)
* diffuse maps are blended together. Can be:
*
* - {@link DETAILMODE_MUL}: Multiply together the primary and secondary colors.
* - {@link DETAILMODE_ADD}: Add together the primary and secondary colors.
* - {@link DETAILMODE_SCREEN}: Softer version of {@link DETAILMODE_ADD}.
* - {@link DETAILMODE_OVERLAY}: Multiplies or screens the colors, depending on the primary color.
* - {@link DETAILMODE_MIN}: Select whichever of the primary and secondary colors is darker,
* component-wise.
* - {@link DETAILMODE_MAX}: Select whichever of the primary and secondary colors is lighter,
* component-wise.
*
* Defaults to {@link DETAILMODE_MUL}.
* @property {Color} specular The specular color of the material. This color value is 3-component
* (RGB), where each component is between 0 and 1. Defines surface reflection/specular color.
* Affects specular intensity and tint.
* @property {boolean} specularTint Multiply specular map and/or specular vertex color by the
* constant specular value.
* @property {Texture|null} specularMap The specular map of the material (default is null).
* @property {number} specularMapUv Specular map UV channel.
* @property {Vec2} specularMapTiling Controls the 2D tiling of the specular map.
* @property {Vec2} specularMapOffset Controls the 2D offset of the specular map. Each component is
* between 0 and 1.
* @property {number} specularMapRotation Controls the 2D rotation (in degrees) of the specular map.
* @property {string} specularMapChannel Color channels of the specular map to use. Can be "r", "g",
* "b", "a", "rgb" or any swizzled combination.
* @property {boolean} specularVertexColor Use mesh vertex colors for specular. If specularMap or
* are specularTint are set, they'll be multiplied by vertex colors.
* @property {string} specularVertexColorChannel Vertex color channels to use for specular. Can be
* "r", "g", "b", "a", "rgb" or any swizzled combination.
* @property {boolean} specularityFactorTint Multiply specularity factor map and/or specular vertex color by the
* constant specular value.
* @property {number} specularityFactor The factor of specular intensity, used to weight the fresnel and specularity. Default is 1.0.
* @property {Texture|null} specularityFactorMap The factor of specularity as a texture (default is
* null).
* @property {number} specularityFactorMapUv Specularity factor map UV channel.
* @property {Vec2} specularityFactorMapTiling Controls the 2D tiling of the specularity factor map.
* @property {Vec2} specularityFactorMapOffset Controls the 2D offset of the specularity factor map. Each component is
* between 0 and 1.
* @property {number} specularityFactorMapRotation Controls the 2D rotation (in degrees) of the specularity factor map.
* @property {string} specularityFactorMapChannel The channel used by the specularity factor texture to sample from (default is 'a').
* @property {boolean} specularityFactorVertexColor Use mesh vertex colors for specularity factor. If specularityFactorMap or
* are specularityFactorTint are set, they'll be multiplied by vertex colors.
* @property {string} specularityFactorVertexColorChannel Vertex color channels to use for specularity factor. Can be
* "r", "g", "b", "a", "rgb" or any swizzled combination.
* @property {boolean} enableGGXSpecular Enables GGX specular. Also enables
* {@link StandardMaterial#anisotropyIntensity} parameter to set material anisotropy.
* @property {number} anisotropyIntensity Defines amount of anisotropy. Requires
* {@link StandardMaterial#enableGGXSpecular} is set to true.
* - When anisotropyIntensity == 0, specular is isotropic.
* - Specular anisotropy increases as anisotropyIntensity value increases to maximum of 1.
* @property {number} anisotropyRotation Defines the rotation (in degrees) of anisotropy.
* @property {Texture|null} anisotropyMap The anisotropy map of the material (default is null).
* @property {number} anisotropyMapUv Anisotropy map UV channel.
* @property {Vec2} anisotropyMapTiling Controls the 2D tiling of the anisotropy map.
* @property {Vec2} anisotropyMapOffset Controls the 2D offset of the anisotropy map. Each
* component is between 0 and 1.
* @property {number} anisotropyMapRotation Controls the 2D rotation (in degrees) of the anisotropy map.
* @property {number} clearCoat Defines intensity of clearcoat layer from 0 to 1. Clearcoat layer
* is disabled when clearCoat == 0. Default value is 0 (disabled).
* @property {Texture|null} clearCoatMap Monochrome clearcoat intensity map (default is null). If
* specified, will be multiplied by normalized 'clearCoat' value and/or vertex colors.
* @property {number} clearCoatMapUv Clearcoat intensity map UV channel.
* @property {Vec2} clearCoatMapTiling Controls the 2D tiling of the clearcoat intensity map.
* @property {Vec2} clearCoatMapOffset Controls the 2D offset of the clearcoat intensity map. Each
* component is between 0 and 1.
* @property {number} clearCoatMapRotation Controls the 2D rotation (in degrees) of the clearcoat
* intensity map.
* @property {string} clearCoatMapChannel Color channel of the clearcoat intensity map to use. Can
* be "r", "g", "b" or "a".
* @property {boolean} clearCoatVertexColor Use mesh vertex colors for clearcoat intensity. If
* clearCoatMap is set, it'll be multiplied by vertex colors.
* @property {string} clearCoatVertexColorChannel Vertex color channel to use for clearcoat
* intensity. Can be "r", "g", "b" or "a".
* @property {number} clearCoatGloss Defines the clearcoat glossiness of the clearcoat layer
* from 0 (rough) to 1 (mirror).
* @property {boolean} clearCoatGlossInvert Invert the clearcoat gloss component (default is false).
* Enabling this flag results in material treating the clear coat gloss members as roughness.
* @property {Texture|null} clearCoatGlossMap Monochrome clearcoat glossiness map (default is
* null). If specified, will be multiplied by normalized 'clearCoatGloss' value and/or vertex
* colors.
* @property {number} clearCoatGlossMapUv Clearcoat gloss map UV channel.
* @property {Vec2} clearCoatGlossMapTiling Controls the 2D tiling of the clearcoat gloss map.
* @property {Vec2} clearCoatGlossMapOffset Controls the 2D offset of the clearcoat gloss map.
* Each component is between 0 and 1.
* @property {number} clearCoatGlossMapRotation Controls the 2D rotation (in degrees) of the clear
* coat gloss map.
* @property {string} clearCoatGlossMapChannel Color channel of the clearcoat gloss map to use.
* Can be "r", "g", "b" or "a".
* @property {boolean} clearCoatGlossVertexColor Use mesh vertex colors for clearcoat glossiness.
* If clearCoatGlossMap is set, it'll be multiplied by vertex colors.
* @property {string} clearCoatGlossVertexColorChannel Vertex color channel to use for clearcoat
* glossiness. Can be "r", "g", "b" or "a".
* @property {Texture|null} clearCoatNormalMap The clearcoat normal map of the material (default is
* null). The texture must contains normalized, tangent space normals.
* @property {number} clearCoatNormalMapUv Clearcoat normal map UV channel.
* @property {Vec2} clearCoatNormalMapTiling Controls the 2D tiling of the main clearcoat normal
* map.
* @property {Vec2} clearCoatNormalMapOffset Controls the 2D offset of the main clearcoat normal
* map. Each component is between 0 and 1.
* @property {number} clearCoatNormalMapRotation Controls the 2D rotation (in degrees) of the main
* clearcoat map.
* @property {number} clearCoatBumpiness The bumpiness of the clearcoat layer. This value scales
* the assigned main clearcoat normal map. It should be normally between 0 (no bump mapping) and 1
* (full bump mapping), but can be set to e.g. 2 to give even more pronounced bump effect.
* @property {boolean} useIridescence Enable thin-film iridescence.
* @property {Texture|null} iridescenceMap The per-pixel iridescence intensity. Only used when
* useIridescence is enabled.
* @property {number} iridescenceMapUv Iridescence map UV channel.
* @property {Vec2} iridescenceMapTiling Controls the 2D tiling of the iridescence map.
* @property {Vec2} iridescenceMapOffset Controls the 2D offset of the iridescence map. Each component is
* between 0 and 1.
* @property {number} iridescenceMapRotation Controls the 2D rotation (in degrees) of the iridescence
* map.
* @property {string} iridescenceMapChannel Color channels of the iridescence map to use. Can be "r",
* "g", "b" or "a".
* @property {Texture|null} iridescenceThicknessMap The per-pixel iridescence thickness. Defines a
* gradient weight between iridescenceThicknessMin and iridescenceThicknessMax. Only used when
* useIridescence is enabled.
* @property {number} iridescenceThicknessMapUv Iridescence thickness map UV channel.
* @property {Vec2} iridescenceThicknessMapTiling Controls the 2D tiling of the iridescence
* thickness map.
* @property {Vec2} iridescenceThicknessMapOffset Controls the 2D offset of the iridescence
* thickness map. Each component is between 0 and 1.
* @property {number} iridescenceThicknessMapRotation Controls the 2D rotation (in degrees)
* of the iridescence map.
* @property {string} iridescenceThicknessMapChannel Color channels of the iridescence thickness
* map to use. Can be "r", "g", "b" or "a".
* @property {number} iridescenceThicknessMin The minimum thickness for the iridescence layer.
* Only used when an iridescence thickness map is used. The unit is in nm.
* @property {number} iridescenceThicknessMax The maximum thickness for the iridescence layer.
* Used as the 'base' thickness when no iridescence thickness map is defined. The unit is in nm.
* @property {number} iridescenceRefractionIndex The index of refraction of the iridescent
* thin-film. Affects the color phase shift as described here:
* https://github.com/KhronosGroup/glTF/tree/main/extensions/2.0/Khronos/KHR_materials_iridescence
* @property {boolean} useMetalness Use metalness properties instead of specular. When enabled,
* diffuse colors also affect specular instead of the dedicated specular map. This can be used as
* alternative to specular color to save space. With metalness == 0, the pixel is assumed to be
* dielectric, and diffuse color is used as normal. With metalness == 1, the pixel is fully
* metallic, and diffuse color is used as specular color instead.
* @property {boolean} useMetalnessSpecularColor When metalness is enabled, use the
* specular map to apply color tint to specular reflections.
* at direct angles.
* @property {number} metalness Defines how much the surface is metallic. From 0 (dielectric) to 1
* (metal).
* @property {Texture|null} metalnessMap Monochrome metalness map (default is null).
* @property {number} metalnessMapUv Metalness map UV channel.
* @property {Vec2} metalnessMapTiling Controls the 2D tiling of the metalness map.
* @property {Vec2} metalnessMapOffset Controls the 2D offset of the metalness map. Each component
* is between 0 and 1.
* @property {number} metalnessMapRotation Controls the 2D rotation (in degrees) of the metalness
* map.
* @property {string} metalnessMapChannel Color channel of the metalness map to use. Can be "r",
* "g", "b" or "a".
* @property {boolean} metalnessVertexColor Use mesh vertex colors for metalness. If metalnessMap
* is set, it'll be multiplied by vertex colors.
* @property {string} metalnessVertexColorChannel Vertex color channel to use for metalness. Can be
* "r", "g", "b" or "a".
* @property {number} gloss Defines the glossiness of the material from 0 (rough) to 1 (shiny).
* @property {Texture|null} glossMap Gloss map (default is null). If specified, will be multiplied
* by normalized gloss value and/or vertex colors.
* @property {boolean} glossInvert Invert the gloss component (default is false). Enabling this
* flag results in material treating the gloss members as roughness.
* @property {number} glossMapUv Gloss map UV channel.
* @property {string} glossMapChannel Color channel of the gloss map to use. Can be "r", "g", "b"
* or "a".
* @property {Vec2} glossMapTiling Controls the 2D tiling of the gloss map.
* @property {Vec2} glossMapOffset Controls the 2D offset of the gloss map. Each component is
* between 0 and 1.
* @property {number} glossMapRotation Controls the 2D rotation (in degrees) of the gloss map.
* @property {boolean} glossVertexColor Use mesh vertex colors for glossiness. If glossMap is set,
* it'll be multiplied by vertex colors.
* @property {string} glossVertexColorChannel Vertex color channel to use for glossiness. Can be
* "r", "g", "b" or "a".
* @property {number} refraction Defines the visibility of refraction. Material can refract the
* same cube map as used for reflections.
* @property {Texture|null} refractionMap The map of the refraction visibility.
* @property {number} refractionMapUv Refraction map UV channel.
* @property {Vec2} refractionMapTiling Controls the 2D tiling of the refraction map.
* @property {Vec2} refractionMapOffset Controls the 2D offset of the refraction map. Each component
* is between 0 and 1.
* @property {number} refractionMapRotation Controls the 2D rotation (in degrees) of the emissive
* map.
* @property {string} refractionMapChannel Color channels of the refraction map to use. Can be "r",
* "g", "b", "a", "rgb" or any swizzled combination.
* @property {boolean} refractionVertexColor Use mesh vertex colors for refraction. If
* refraction map is set, it will be be multiplied by vertex colors.
* @property {boolean} refractionVertexColorChannel Vertex color channel to use for refraction.
* Can be "r", "g", "b" or "a".
* @property {number} refractionIndex Defines the index of refraction, i.e. The amount of
* distortion. The value is calculated as (outerIor / surfaceIor), where inputs are measured
* indices of refraction, the one around the object and the one of its own surface. In most
* situations outer medium is air, so outerIor will be approximately 1. Then you only need to do
* (1.0 / surfaceIor).
* @property {number} dispersion The strength of the angular separation of colors (chromatic
* aberration) transmitting through a volume. Defaults to 0, which is equivalent to no dispersion.
* @property {boolean} useDynamicRefraction Enables higher quality refractions using the grab pass
* instead of pre-computed cube maps for refractions.
* @property {number} thickness The thickness of the medium, only used when useDynamicRefraction
* is enabled. The unit is in base units, and scales with the size of the object.
* @property {Texture|null} thicknessMap The per-pixel thickness of the medium, only used when
* useDynamicRefraction is enabled.
* @property {number} thicknessMapUv Thickness map UV channel.
* @property {Vec2} thicknessMapTiling Controls the 2D tiling of the thickness map.
* @property {Vec2} thicknessMapOffset Controls the 2D offset of the thickness map. Each component is
* between 0 and 1.
* @property {number} thicknessMapRotation Controls the 2D rotation (in degrees) of the thickness
* map.
* @property {string} thicknessMapChannel Color channels of the thickness map to use. Can be "r",
* "g", "b" or "a".
* @property {boolean} thicknessVertexColor Use mesh vertex colors for thickness. If
* thickness map is set, it will be be multiplied by vertex colors.
* @property {Color} attenuation The attenuation color for refractive materials, only used when
* useDynamicRefraction is enabled.
* @property {number} attenuationDistance The distance defining the absorption rate of light
* within the medium. Only used when useDynamicRefraction is enabled.
* @property {Color} emissive The emissive color of the material. This color value is 3-component
* (RGB), where each component is between 0 and 1.
* @property {Texture|null} emissiveMap The emissive map of the material (default is null). Can be
* HDR. When the emissive map is applied, the emissive color is multiplied by the texel color in the
* map. Since the emissive color is black by default, the emissive map won't be visible unless the
* emissive color is changed.
* @property {number} emissiveIntensity Emissive color multiplier.
* @property {number} emissiveMapUv Emissive map UV channel.
* @property {Vec2} emissiveMapTiling Controls the 2D tiling of the emissive map.
* @property {Vec2} emissiveMapOffset Controls the 2D offset of the emissive map. Each component is
* between 0 and 1.
* @property {number} emissiveMapRotation Controls the 2D rotation (in degrees) of the emissive
* map.
* @property {string} emissiveMapChannel Color channels of the emissive map to use. Can be "r",
* "g", "b", "a", "rgb" or any swizzled combination.
* @property {boolean} emissiveVertexColor Use mesh vertex colors for emission. If emissiveMap or
* emissive are set, they'll be multiplied by vertex colors.
* @property {string} emissiveVertexColorChannel Vertex color channels to use for emission. Can be
* "r", "g", "b", "a", "rgb" or any swizzled combination.
* @property {boolean} useSheen Toggle sheen specular effect on/off.
* @property {Color} sheen The specular color of the sheen (fabric) microfiber structure.
* This color value is 3-component (RGB), where each component is between 0 and 1.
* @property {Texture|null} sheenMap The sheen microstructure color map of the material (default is
* null).
* @property {number} sheenMapUv Sheen map UV channel.
* @property {Vec2} sheenMapTiling Controls the 2D tiling of the sheen map.
* @property {Vec2} sheenMapOffset Controls the 2D offset of the sheen map. Each component is
* between 0 and 1.
* @property {number} sheenMapRotation Controls the 2D rotation (in degrees) of the sheen
* map.
* @property {string} sheenMapChannel Color channels of the sheen map to use. Can be "r",
* "g", "b", "a", "rgb" or any swizzled combination.
* @property {boolean} sheenVertexColor Use mesh vertex colors for sheen. If sheen map or
* sheen tint are set, they'll be multiplied by vertex colors.
* @property {number} sheenGloss The glossiness of the sheen (fabric) microfiber structure.
* This color value is a single value between 0 and 1.
* @property {boolean} sheenGlossInvert Invert the sheen gloss component (default is false).
* Enabling this flag results in material treating the sheen gloss members as roughness.
* @property {Texture|null} sheenGlossMap The sheen glossiness microstructure color map of the
* material (default is null).
* @property {number} sheenGlossMapUv Sheen map UV channel.
* @property {Vec2} sheenGlossMapTiling Controls the 2D tiling of the sheen glossiness map.
* @property {Vec2} sheenGlossMapOffset Controls the 2D offset of the sheen glossiness map.
* Each component is between 0 and 1.
* @property {number} sheenGlossMapRotation Controls the 2D rotation (in degrees) of the sheen
* glossiness map.
* @property {string} sheenGlossMapChannel Color channels of the sheen glossiness map to use.
* Can be "r", "g", "b", "a", "rgb" or any swizzled combination.
* @property {boolean} sheenGlossVertexColor Use mesh vertex colors for sheen glossiness.
* If sheen glossiness map or sheen glossiness tint are set, they'll be multiplied by vertex colors.
* @property {string} sheenGlossVertexColorChannel Vertex color channels to use for sheen glossiness.
* Can be "r", "g", "b" or "a".
* @property {number} opacity The opacity of the material. This value can be between 0 and 1, where
* 0 is fully transparent and 1 is fully opaque. If you want the material to be semi-transparent
* you also need to set the {@link Material#blendType} to {@link BLEND_NORMAL},
* {@link BLEND_ADDITIVE} or any other mode. Also note that for most semi-transparent objects you
* want {@link Material#depthWrite} to be false, otherwise they can fully occlude objects behind
* them.
* @property {Texture|null} opacityMap The opacity map of the material (default is null).
* @property {number} opacityMapUv Opacity map UV channel.
* @property {string} opacityMapChannel Color channel of the opacity map to use. Can be "r", "g",
* "b" or "a".
* @property {Vec2} opacityMapTiling Controls the 2D tiling of the opacity map.
* @property {Vec2} opacityMapOffset Controls the 2D offset of the opacity map. Each component is
* between 0 and 1.
* @property {number} opacityMapRotation Controls the 2D rotation (in degrees) of the opacity map.
* @property {boolean} opacityVertexColor Use mesh vertex colors for opacity. If opacityMap is set,
* it'll be multiplied by vertex colors.
* @property {string} opacityVertexColorChannel Vertex color channels to use for opacity. Can be
* "r", "g", "b" or "a".
* @property {boolean} opacityFadesSpecular Used to specify whether specular and reflections are
* faded out using {@link StandardMaterial#opacity}. Default is true. When set to false use
* {@link Material#alphaFade} to fade out materials.
* @property {string} opacityDither Used to specify whether opacity is dithered, which allows
* transparency without alpha blending. Can be:
*
* - {@link DITHER_NONE}: Opacity dithering is disabled.
* - {@link DITHER_BAYER8}: Opacity is dithered using a Bayer 8 matrix.
* - {@link DITHER_BLUENOISE}: Opacity is dithered using a blue noise.
* - {@link DITHER_IGNNOISE}: Opacity is dithered using an interleaved gradient noise.
*
* Defaults to {@link DITHER_NONE}.
* @property {boolean} opacityShadowDither Used to specify whether shadow opacity is dithered, which
* allows shadow transparency without alpha blending. Can be:
*
* - {@link DITHER_NONE}: Opacity dithering is disabled.
* - {@link DITHER_BAYER8}: Opacity is dithered using a Bayer 8 matrix.
* - {@link DITHER_BLUENOISE}: Opacity is dithered using a blue noise.
* - {@link DITHER_IGNNOISE}: Opacity is dithered using an interleaved gradient noise.
*
* Defaults to {@link DITHER_NONE}.
* @property {number} alphaFade Used to fade out materials when
* {@link StandardMaterial#opacityFadesSpecular} is set to false.
* @property {Texture|null} normalMap The main (primary) normal map of the material (default is
* null). The texture must contains normalized, tangent space normals.
* @property {number} normalMapUv Main (primary) normal map UV channel.
* @property {Vec2} normalMapTiling Controls the 2D tiling of the main (primary) normal map.
* @property {Vec2} normalMapOffset Controls the 2D offset of the main (primary) normal map. Each
* component is between 0 and 1.
* @property {number} normalMapRotation Controls the 2D rotation (in degrees) of the main (primary)
* normal map.
* @property {number} bumpiness The bumpiness of the material. This value scales the assigned main
* (primary) normal map. It should be normally between 0 (no bump mapping) and 1 (full bump
* mapping), but can be set to e.g. 2 to give even more pronounced bump effect.
* @property {Texture|null} normalDetailMap The detail (secondary) normal map of the material
* (default is null). Will only be used if main (primary) normal map is non-null.
* @property {number} normalDetailMapUv Detail (secondary) normal map UV channel.
* @property {Vec2} normalDetailMapTiling Controls the 2D tiling of the detail (secondary) normal
* map.
* @property {Vec2} normalDetailMapOffset Controls the 2D offset of the detail (secondary) normal
* map. Each component is between 0 and 1.
* @property {number} normalDetailMapRotation Controls the 2D rotation (in degrees) of the detail
* (secondary) normal map.
* @property {number} normalDetailMapBumpiness The bumpiness of the material. This value scales the
* assigned detail (secondary) normal map. It should be normally between 0 (no bump mapping) and 1
* (full bump mapping), but can be set to e.g. 2 to give even more pronounced bump effect.
* @property {Texture|null} heightMap The height map of the material (default is null). Used for a
* view-dependent parallax effect. The texture must represent the height of the surface where
* darker pixels are lower and lighter pixels are higher. It is recommended to use it together with
* a normal map.
* @property {number} heightMapUv Height map UV channel.
* @property {string} heightMapChannel Color channel of the height map to use. Can be "r", "g", "b"
* or "a".
* @property {Vec2} heightMapTiling Controls the 2D tiling of the height map.
* @property {Vec2} heightMapOffset Controls the 2D offset of the height map. Each component is
* between 0 and 1.
* @property {number} heightMapRotation Controls the 2D rotation (in degrees) of the height map.
* @property {number} heightMapFactor Height map multiplier. Affects the strength of the parallax
* effect.
* @property {Texture|null} envAtlas The prefiltered environment lighting atlas (default is null).
* This setting overrides cubeMap and sphereMap and will replace the scene lighting environment.
* @property {Texture|null} cubeMap The cubic environment map of the material (default is null).
* This setting overrides sphereMap and will replace the scene lighting environment.
* @property {Texture|null} sphereMap The spherical environment map of the material (default is
* null). This will replace the scene lighting environment.
* @property {number} cubeMapProjection The type of projection applied to the cubeMap property:
* - {@link CUBEPROJ_NONE}: The cube map is treated as if it is infinitely far away.
* - {@link CUBEPROJ_BOX}: Box-projection based on a world space axis-aligned bounding box.
* Defaults to {@link CUBEPROJ_NONE}.
* @property {BoundingBox} cubeMapProjectionBox The world space axis-aligned bounding box
* defining the box-projection used for the cubeMap property. Only used when cubeMapProjection is
* set to {@link CUBEPROJ_BOX}.
* @property {number} reflectivity Environment map intensity.
* @property {Texture|null} lightMap A custom lightmap of the material (default is null). Lightmaps
* are textures that contain pre-rendered lighting. Can be HDR.
* @property {number} lightMapUv Lightmap UV channel
* @property {string} lightMapChannel Color channels of the lightmap to use. Can be "r", "g", "b",
* "a", "rgb" or any swizzled combination.
* @property {Vec2} lightMapTiling Controls the 2D tiling of the lightmap.
* @property {Vec2} lightMapOffset Controls the 2D offset of the lightmap. Each component is
* between 0 and 1.
* @property {number} lightMapRotation Controls the 2D rotation (in degrees) of the lightmap.
* @property {boolean} lightVertexColor Use baked vertex lighting. If lightMap is set, it'll be
* multiplied by vertex colors.
* @property {string} lightVertexColorChannel Vertex color channels to use for baked lighting. Can
* be "r", "g", "b", "a", "rgb" or any swizzled combination.
* @property {number} aoIntensity Ambient occlusion intensity. Defaults to 1.
* @property {Texture|null} aoMap The main (primary) baked ambient occlusion (AO) map (default is
* null). Modulates ambient color.
* @property {number} aoMapUv Main (primary) AO map UV channel
* @property {string} aoMapChannel Color channel of the main (primary) AO map to use. Can be "r", "g", "b" or "a".
* @property {Vec2} aoMapTiling Controls the 2D tiling of the main (primary) AO map.
* @property {Vec2} aoMapOffset Controls the 2D offset of the main (primary) AO map. Each component is between 0
* and 1.
* @property {number} aoMapRotation Controls the 2D rotation (in degrees) of the main (primary) AO map.
* @property {boolean} aoVertexColor Use mesh vertex colors for AO. If aoMap is set, it'll be
* multiplied by vertex colors.
* @property {string} aoVertexColorChannel Vertex color channels to use for AO. Can be "r", "g",
* "b" or "a".
* @property {Texture|null} aoDetailMap The detail (secondary) baked ambient occlusion (AO) map of
* the material (default is null). Will only be used if main (primary) ao map is non-null.
* @property {number} aoDetailMapUv Detail (secondary) AO map UV channel.
* @property {Vec2} aoDetailMapTiling Controls the 2D tiling of the detail (secondary) AO map.
* @property {Vec2} aoDetailMapOffset Controls the 2D offset of the detail (secondary) AO map. Each
* component is between 0 and 1.
* @property {number} aoDetailMapRotation Controls the 2D rotation (in degrees) of the detail
* (secondary) AO map.
* @property {string} aoDetailMapChannel Color channels of the detail (secondary) AO map to use.
* Can be "r", "g", "b" or "a" (default is "g").
* @property {string} aoDetailMode Determines how the main (primary) and detail (secondary)
* AO maps are blended together. Can be:
*
* - {@link DETAILMODE_MUL}: Multiply together the primary and secondary colors.
* - {@link DETAILMODE_ADD}: Add together the primary and secondary colors.
* - {@link DETAILMODE_SCREEN}: Softer version of {@link DETAILMODE_ADD}.
* - {@link DETAILMODE_OVERLAY}: Multiplies or screens the colors, depending on the primary color.
* - {@link DETAILMODE_MIN}: Select whichever of the primary and secondary colors is darker,
* component-wise.
* - {@link DETAILMODE_MAX}: Select whichever of the primary and secondary colors is lighter,
* component-wise.
*
* Defaults to {@link DETAILMODE_MUL}.
* @property {number} occludeSpecular Uses ambient occlusion to darken specular/reflection. It's a
* hack, because real specular occlusion is view-dependent. However, it can be better than nothing.
*
* - {@link SPECOCC_NONE}: No specular occlusion
* - {@link SPECOCC_AO}: Use AO directly to occlude specular.
* - {@link SPECOCC_GLOSSDEPENDENT}: Modify AO based on material glossiness/view angle to occlude
* specular.
*
* @property {number} occludeSpecularIntensity Controls visibility of specular occlusion.
* @property {boolean} occludeDirect Tells if AO should darken directional lighting. Defaults to
* false.
* @property {number} fresnelModel Defines the formula used for Fresnel effect.
* As a side-effect, enabling any Fresnel model changes the way diffuse and reflection components
* are combined. When Fresnel is off, legacy non energy-conserving combining is used. When it is
* on, combining behavior is energy-conserving.
*
* - {@link FRESNEL_NONE}: No Fresnel.
* - {@link FRESNEL_SCHLICK}: Schlick's approximation of Fresnel (recommended). Parameterized by
* specular color.
*
* @property {boolean} useFog Apply fogging (as configured in scene settings)
* @property {boolean} useLighting Apply lighting
* @property {boolean} useSkybox Apply scene skybox as prefiltered environment map
* @property {boolean} useTonemap Apply tonemapping (as configured in {@link Scene#rendering} or
* {@link CameraComponent.rendering}). Defaults to true.
* @property {boolean} pixelSnap Align vertices to pixel coordinates when rendering. Useful for
* pixel perfect 2D graphics.
* @property {boolean} twoSidedLighting Calculate proper normals (and therefore lighting) on
* backfaces.
* @property {boolean} shadowCatcher When enabled, the material will output accumulated directional
* shadow value in linear space as the color.
*
* @category Graphics
*/
export class StandardMaterial extends Material {
static TEXTURE_PARAMETERS: any[];
static CUBEMAP_PARAMETERS: any[];
userAttributes: Map<any, any>;
/**
* A custom function that will be called after all shader generator properties are collected
* and before shader code is generated. This function will receive an object with shader
* generator settings (based on current material and scene properties), that you can change and
* then return. Returned value will be used instead. This is mostly useful when rendering the
* same set of objects, but with different shader variations based on the same material. For
* example, you may wish to render a depth or normal pass using textures assigned to the
* material, a reflection pass with simpler shaders and so on. These properties are split into
* two sections, generic standard material options and lit options. Properties of the standard
* material options are {@link StandardMaterialOptions} and the options for the lit options are
* {@link LitShaderOptions}.
*
* @type {UpdateShaderCallback|undefined}
*/
onUpdateShader: UpdateShaderCallback | undefined;
_assetReferences: {};
_activeParams: Set<any>;
_activeLightingParams: Set<any>;
shaderOptBuilder: StandardMaterialOptionsBuilder;
reset(): void;
set alphaFade(arg: boolean);
get alphaFade(): boolean;
/** The ambient color of the material. This color value is 3-component (RGB), where each component is between 0 and 1. */
set ambient(arg: Color);
get ambient(): Color;
/** Intensity Defines amount of anisotropy. Requires {@link StandardMaterial#enableGGXSpecular} is set to true. - When anisotropyIntensity == 0, specular is isotropic. - Specular anisotropy increases as anisotropyIntensity value increases to maximum of 1. */
set anisotropy(arg: number);
get anisotropy(): number;
/** Defines amount of anisotropy. Requires {@link StandardMaterial#enableGGXSpecular} is set to true. - When anisotropyIntensity == 0, specular is isotropic. - Specular anisotropy increases as anisotropyIntensity value increases to maximum of 1. */
set anisotropyIntensity(arg: number);
get anisotropyIntensity(): number;
/** Defines the rotation (in degrees) of anisotropy. */
set anisotropyRotation(arg: number);
get anisotropyRotation(): number;
/** e main (primary) diffuse map of the material (default is null). */
set anisotropyMap(arg: Texture|null);
get anisotropyMap(): Texture|null;
/** Controls the 2D offset of the anisotropy map. Each component is between 0 and 1. */
set anisotropyMapOffset(arg: Vec2);
get anisotropyMapOffset(): Vec2;
/** Controls the 2D rotation (in degrees) of the anisotropy map. */
set anisotropyMapRotation(arg: number);
get anisotropyMapRotation(): number;
/** Controls the 2D tiling of the anisotropy map. */
set anisotropyMapTiling(arg: Vec2);
get anisotropyMapTiling(): Vec2;
/** Anisotropy map UV channel. */
set anisotropyMapUv(arg: number);
get anisotropyMapUv(): number;
/** Ambient occlusion intensity. Defaults to 1. */
set aoIntensity(arg: number);
get aoIntensity(): number;
/** seMap The main (primary) diffuse map of the material (default is null). */
set aoMap(arg: Texture|null);
get aoMap(): Texture|null;
/** Color channel of the main (primary) AO map to use. Can be "r", "g", "b" or "a". */
set aoMapChannel(arg: string);
get aoMapChannel(): string;
/** Controls the 2D offset of the main (primary) AO map. Each component is between 0 and 1. */
set aoMapOffset(arg: Vec2);
get aoMapOffset(): Vec2;
/** Controls the 2D rotation (in degrees) of the main (primary) AO map. */
set aoMapRotation(arg: number);
get aoMapRotation(): number;
/** Controls the 2D tiling of the main (primary) AO map. */
set aoMapTiling(arg: Vec2);
get aoMapTiling(): Vec2;
/** Main (primary) AO map UV channel */
set aoMapUv(arg: number);
get aoMapUv(): number;
/** The main (primary) diffuse map of the material (default is null). */
set aoDetailMap(arg: Texture|null);
get aoDetailMap(): Texture|null;
/** Color channels of the detail (secondary) AO map to use. Can be "r", "g", "b" or "a" (default is "g"). */
set aoDetailMapChannel(arg: string);
get aoDetailMapChannel(): string;
/** Controls the 2D offset of the detail (secondary) AO map. Each component is between 0 and 1. */
set aoDetailMapOffset(arg: Vec2);
get aoDetailMapOffset(): Vec2;
/** Controls the 2D rotation (in degrees) of the detail (secondary) AO map. */
set aoDetailMapRotation(arg: number);
get aoDetailMapRotation(): number;
/** Controls the 2D tiling of the detail (secondary) AO map. */
set aoDetailMapTiling(arg: Vec2);
get aoDetailMapTiling(): Vec2;
/** Detail (secondary) AO map UV channel. */
set aoDetailMapUv(arg: number);
get aoDetailMapUv(): number;
/** Determines how the main (primary) and detail (secondary) AO maps are blended together. Can be: - {@link DETAILMODE_MUL}: Multiply together the primary and secondary colors. - {@link DETAILMODE_ADD}: Add together the primary and secondary colors. - {@link DETAILMODE_SCREEN}: Softer version of {@link DETAILMODE_ADD}. - {@link DETAILMODE_OVERLAY}: Multiplies or screens the colors, depending on the primary color. - {@link DETAILMODE_MIN}: Select whichever of the primary and secondary colors is darker, component-wise. - {@link DETAILMODE_MAX}: Select whichever of the primary and secondary colors is lighter, component-wise. Defaults to {@link DETAILMODE_MUL}. */
set aoDetailMode(arg: string);
get aoDetailMode(): string;
/** Use mesh vertex colors for AO. If aoMap is set, it'll be multiplied by vertex colors. */
set aoVertexColor(arg: boolean);
get aoVertexColor(): boolean;
/** Vertex color channels to use for AO. Can be "r", "g", "b" or "a". */
set aoVertexColorChannel(arg: string);
get aoVertexColorChannel(): string;
/** The bumpiness of the material. This value scales the assigned main (primary) normal map. It should be normally between 0 (no bump mapping) and 1 (full bump mapping), but can be set to e.g. 2 to give even more pronounced bump effect. */
set bumpiness(arg: number);
get bumpiness(): number;
/** Defines intensity of clearcoat layer from 0 to 1. Clearcoat layer is disabled when clearCoat == 0. Default value is 0 (disabled). */
set clearCoat(arg: number);
get clearCoat(): number;
/** The bumpiness of the clearcoat layer. This value scales the assigned main clearcoat normal map. It should be normally between 0 (no bump mapping) and 1 (full bump mapping), but can be set to e.g. 2 to give even more pronounced bump effect. */
set clearCoatBumpiness(arg: number);
get clearCoatBumpiness(): number;
/** Invert the clearcoat gloss component (default is false). Enabling this flag results in material treating the clear coat gloss members as roughness. */
set clearCoatGlossInvert(arg: boolean);
get clearCoatGlossInvert(): boolean;
/** in (primary) diffuse map of the material (default is null). */
set clearCoatGlossMap(arg: Texture|null);
get clearCoatGlossMap(): Texture|null;
/** Color channel of the clearcoat gloss map to use. Can be "r", "g", "b" or "a". */
set clearCoatGlossMapChannel(arg: string);
get clearCoatGlossMapChannel(): string;
/** Controls the 2D offset of the clearcoat gloss map. Each component is between 0 and 1. */
set clearCoatGlossMapOffset(arg: Vec2);
get clearCoatGlossMapOffset(): Vec2;
/** Controls the 2D rotation (in degrees) of the clear coat gloss map. */
set clearCoatGlossMapRotation(arg: number);
get clearCoatGlossMapRotation(): number;
/** Controls the 2D tiling of the clearcoat gloss map. */
set clearCoatGlossMapTiling(arg: Vec2);
get clearCoatGlossMapTiling(): Vec2;
/** Clearcoat gloss map UV channel. */
set clearCoatGlossMapUv(arg: number);
get clearCoatGlossMapUv(): number;
/** Use mesh vertex colors for clearcoat glossiness. If clearCoatGlossMap is set, it'll be multiplied by vertex colors. */
set clearCoatGlossVertexColor(arg: boolean);
get clearCoatGlossVertexColor(): boolean;
/** Vertex color channel to use for clearcoat glossiness. Can be "r", "g", "b" or "a". */
set clearCoatGlossVertexColorChannel(arg: string);
get clearCoatGlossVertexColorChannel(): string;
/** Defines the clearcoat glossiness of the clearcoat layer from 0 (rough) to 1 (mirror). */
set clearCoatGloss(arg: number);
get clearCoatGloss(): number;
/** he main (primary) diffuse map of the material (default is null). */
set clearCoatMap(arg: Texture|null);
get clearCoatMap(): Texture|null;
/** Color channel of the clearcoat intensity map to use. Can be "r", "g", "b" or "a". */
set clearCoatMapChannel(arg: string);
get clearCoatMapChannel(): string;
/** Controls the 2D offset of the clearcoat intensity map. Each component is between 0 and 1. */
set clearCoatMapOffset(arg: Vec2);
get clearCoatMapOffset(): Vec2;
/** Controls the 2D rotation (in degrees) of the clearcoat intensity map. */
set clearCoatMapRotation(arg: number);
get clearCoatMapRotation(): number;
/** Controls the 2D tiling of the clearcoat intensity map. */
set clearCoatMapTiling(arg: Vec2);
get clearCoatMapTiling(): Vec2;
/** Clearcoat intensity map UV channel. */
set clearCoatMapUv(arg: number);
get clearCoatMapUv(): number;
/** n (primary) diffuse map of the material (default is null). */
set clearCoatNormalMap(arg: Texture|null);
get clearCoatNormalMap(): Texture|null;
/** Controls the 2D offset of the main clearcoat normal map. Each component is between 0 and 1. */
set clearCoatNormalMapOffset(arg: Vec2);
get clearCoatNormalMapOffset(): Vec2;
/** Controls the 2D rotation (in degrees) of the main clearcoat map. */
set clearCoatNormalMapRotation(arg: number);
get clearCoatNormalMapRotation(): number;
/** Controls the 2D tiling of the main clearcoat normal map. */
set clearCoatNormalMapTiling(arg: Vec2);
get clearCoatNormalMapTiling(): Vec2;
/** Clearcoat normal map UV channel. */
set clearCoatNormalMapUv(arg: number);
get clearCoatNormalMapUv(): number;
/** Use mesh vertex colors for clearcoat intensity. If clearCoatMap is set, it'll be multiplied by vertex colors. */
set clearCoatVertexColor(arg: boolean);
get clearCoatVertexColor(): boolean;
/** Vertex color channel to use for clearcoat intensity. Can be "r", "g", "b" or "a". */
set clearCoatVertexColorChannel(arg: string);
get clearCoatVertexColorChannel(): string;
/** Map The main (primary) diffuse map of the material (default is null). */
set cubeMap(arg: Texture|null);
get cubeMap(): Texture|null;
/** The type of projection applied to the cubeMap property: - {@link CUBEPROJ_NONE}: The cube map is treated as if it is infinitely far away. - {@link CUBEPROJ_BOX}: Box-projection based on a world space axis-aligned bounding box. Defaults to {@link CUBEPROJ_NONE}. */
set cubeMapProjection(arg: number);
get cubeMapProjection(): number;
/** The world space axis-aligned bounding box defining the box-projection used for the cubeMap property. Only used when cubeMapProjection is set to {@link CUBEPROJ_BOX}. */
set cubeMapProjectionBox(arg: BoundingBox);
get cubeMapProjectionBox(): BoundingBox;
/** The diffuse color of the material. This color value is 3-component (RGB), where each component is between 0 and 1. Defines basic surface color (aka albedo). */
set diffuse(arg: Color);
get diffuse(): Color;
/** ain (primary) diffuse map of the material (default is null). */
set diffuseDetailMap(arg: Texture|null);
get diffuseDetailMap(): Texture|null;
/** Color channels of the detail (secondary) diffuse map to use. Can be "r", "g", "b", "a", "rgb" or any swizzled combination. */
set diffuseDetailMapChannel(arg: string);
get diffuseDetailMapChannel(): string;
/** Controls the 2D offset of the detail (secondary) diffuse map. Each component is between 0 and 1. */
set diffuseDetailMapOffset(arg: Vec2);
get diffuseDetailMapOffset(): Vec2;
/** Controls the 2D rotation (in degrees) of the main (secondary) diffuse map. */
set diffuseDetailMapRotation(arg: number);
get diffuseDetailMapRotation(): number;
/** Controls the 2D tiling of the detail (secondary) diffuse map. */
set diffuseDetailMapTiling(arg: Vec2);
get diffuseDetailMapTiling(): Vec2;
/** Detail (secondary) diffuse map UV channel. */
set diffuseDetailMapUv(arg: number);
get diffuseDetailMapUv(): number;
/** Determines how the main (primary) and detail (secondary) diffuse maps are blended together. Can be: - {@link DETAILMODE_MUL}: Multiply together the primary and secondary colors. - {@link DETAILMODE_ADD}: Add together the primary and secondary colors. - {@link DETAILMODE_SCREEN}: Softer version of {@link DETAILMODE_ADD}. - {@link DETAILMODE_OVERLAY}: Multiplies or screens the colors, depending on the primary color. - {@link DETAILMODE_MIN}: Select whichever of the primary and secondary colors is darker, component-wise. - {@link DETAILMODE_MAX}: Select whichever of the primary and secondary colors is lighter, component-wise. Defaults to {@link DETAILMODE_MUL}. */
set diffuseDetailMode(arg: string);
get diffuseDetailMode(): string;
/** The main (primary) diffuse map of the material (default is null). */
set diffuseMap(arg: Texture|null);
get diffuseMap(): Texture|null;
/** Color channels of the main (primary) diffuse map to use. Can be "r", "g", "b", "a", "rgb" or any swizzled combination. */
set diffuseMapChannel(arg: string);
get diffuseMapChannel(): string;
/** Controls the 2D offset of the main (primary) diffuse map. Each component is between 0 and 1. */
set diffuseMapOffset(arg: Vec2);
get diffuseMapOffset(): Vec2;
/** Controls the 2D rotation (in degrees) of the main (primary) diffuse map. */
set diffuseMapRotation(arg: number);
get diffuseMapRotation(): number;
/** Controls the 2D tiling of the main (primary) diffuse map. */
set diffuseMapTiling(arg: Vec2);
get diffuseMapTiling(): Vec2;
/** Main (primary) diffuse map UV channel. */
set diffuseMapUv(arg: number);
get diffuseMapUv(): number;
/** Multiply diffuse by the mesh vertex colors. */
set diffuseVertexColor(arg: boolean);
get diffuseVertexColor(): boolean;
/** Vertex color channels to use for diffuse. Can be "r", "g", "b", "a", "rgb" or any swizzled combination. */
set diffuseVertexColorChannel(arg: string);
get diffuseVertexColorChannel(): string;
/** The emissive color of the material. This color value is 3-component (RGB), where each component is between 0 and 1. */
set emissive(arg: Color);
get emissive(): Color;
/** Emissive color multiplier. */
set emissiveIntensity(arg: number);
get emissiveIntensity(): number;
/** The main (primary) diffuse map of the material (default is null). */
set emissiveMap(arg: Texture|null);
get emissiveMap(): Texture|null;
/** Color channels of the emissive map to use. Can be "r", "g", "b", "a", "rgb" or any swizzled combination. */
set emissiveMapChannel(arg: string);
get emissiveMapChannel(): string;
/** Controls the 2D offset of the emissive map. Each component is between 0 and 1. */
set emissiveMapOffset(arg: Vec2);
get emissiveMapOffset(): Vec2;
/** Controls the 2D rotation (in degrees) of the emissive map. */
set emissiveMapRotation(arg: number);
get emissiveMapRotation(): number;
/** Controls the 2D tiling of the emissive map. */
set emissiveMapTiling(arg: Vec2);
get emissiveMapTiling(): Vec2;
/** Emissive map UV channel. */
set emissiveMapUv(arg: number);
get emissiveMapUv(): number;
/** Use mesh vertex colors for emission. If emissiveMap or emissive are set, they'll be multiplied by vertex colors. */
set emissiveVertexColor(arg: boolean);
get