StandardMaterial
Extends: Material
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 (color or number), mesh vertex colors and a texture. All enabled inputs are multiplied together.
// Create a new Standard material
var material = new pc.StandardMaterial();
// Update the material's diffuse and specular properties
material.diffuse.set(1, 0, 0);
material.specular.set(1, 1, 1);
// Notify the material that it has been modified
material.update();
// Create a new Standard material
var material = new pc.StandardMaterial();
// Assign a texture to the diffuse slot
material.diffuseMap = texture;
// Use the alpha channel of the texture for alpha testing with a reference value of 0.5
material.opacityMap = texture;
material.alphaTest = 0.5;
// Notify the material that it has been modified
material.update();
Summary
Properties
alphaFade | used to fade out materials when StandardMaterial#opacityFadesSpecular is set to false. |
ambient | The ambient color of the material. |
ambientTint | Enables scene ambient multiplication by material ambient color. |
anisotropy | Defines amount of anisotropy. |
aoMap | Baked ambient occlusion (AO) map (default is null). |
aoMapChannel | Color channel of the AO map to use. |
aoMapOffset | Controls the 2D offset of the AO map. |
aoMapRotation | Controls the 2D rotation (in degrees) of the AO map. |
aoMapTiling | Controls the 2D tiling of the AO map. |
aoMapUv | AO map UV channel |
aoVertexColor | Use mesh vertex colors for AO. |
aoVertexColorChannel | Vertex color channels to use for AO. |
bumpiness | The bumpiness of the material. |
chunks | Object containing custom shader chunks that will replace default ones. |
clearCoat | Defines intensity of clear coat layer from 0 to 1. |
clearCoatBumpiness | The bumpiness of the clear coat layer. |
clearCoatGlossMap | Monochrome clear coat glossiness map (default is null). |
clearCoatGlossMapChannel | Color channel of the clear coat gloss map to use. |
clearCoatGlossMapOffset | Controls the 2D offset of the clear coat gloss map. |
clearCoatGlossMapRotation | Controls the 2D rotation (in degrees) of the clear coat gloss map. |
clearCoatGlossMapTiling | Controls the 2D tiling of the clear coat gloss map. |
clearCoatGlossMapUv | Clear coat gloss map UV channel. |
clearCoatGlossVertexColor | Use mesh vertex colors for clear coat glossiness. |
clearCoatGlossVertexColorChannel | Vertex color channel to use for clear coat glossiness. |
clearCoatGlossiness | Defines the clear coat glossiness of the clear coat layer from 0 (rough) to 1 (mirror). |
clearCoatMap | Monochrome clear coat intensity map (default is null). |
clearCoatMapChannel | Color channel of the clear coat intensity map to use. |
clearCoatMapOffset | Controls the 2D offset of the clear coat intensity map. |
clearCoatMapRotation | Controls the 2D rotation (in degrees) of the clear coat intensity map. |
clearCoatMapTiling | Controls the 2D tiling of the clear coat intensity map. |
clearCoatMapUv | Clear coat intensity map UV channel. |
clearCoatNormalMap | The clear coat normal map of the material (default is null). |
clearCoatNormalMapOffset | Controls the 2D offset of the main clear coat normal map. |
clearCoatNormalMapRotation | Controls the 2D rotation (in degrees) of the main clear coat map. |
clearCoatNormalMapTiling | Controls the 2D tiling of the main clear coat normal map. |
clearCoatNormalMapUv | Clear coat normal map UV channel. |
clearCoatVertexColor | Use mesh vertex colors for clear coat intensity. |
clearCoatVertexColorChannel | Vertex color channel to use for clear coat intensity. |
conserveEnergy | Defines how diffuse and specular components are combined when Fresnel is on. |
cubeMap | The cubic environment map of the material (default is null). |
cubeMapProjection | The type of projection applied to the cubeMap property:
|
cubeMapProjectionBox | The world space axis-aligned bounding box defining the box-projection used for the cubeMap property. |
diffuse | The diffuse color of the material. |
diffuseDetailMap | The detail (secondary) diffuse map of the material (default is null). |
diffuseDetailMapChannel | Color channels of the detail (secondary) diffuse map to use. |
diffuseDetailMapOffset | Controls the 2D offset of the detail (secondary) diffuse map. |
diffuseDetailMapRotation | Controls the 2D rotation (in degrees) of the main (secondary) diffuse map. |
diffuseDetailMapTiling | Controls the 2D tiling of the detail (secondary) diffuse map. |
diffuseDetailMapUv | Detail (secondary) diffuse map UV channel. |
diffuseDetailMode | Determines how the main (primary) and detail (secondary) diffuse maps are blended together. |
diffuseMap | The main (primary) diffuse map of the material (default is null). |
diffuseMapChannel | Color channels of the main (primary) diffuse map to use. |
diffuseMapOffset | Controls the 2D offset of the main (primary) diffuse map. |
diffuseMapRotation | Controls the 2D rotation (in degrees) of the main (primary) diffuse map. |
diffuseMapTiling | Controls the 2D tiling of the main (primary) diffuse map. |
diffuseMapUv | Main (primary) diffuse map UV channel. |
diffuseTint | Multiply main (primary) diffuse map and/or diffuse vertex color by the constant diffuse value. |
diffuseVertexColor | Use mesh vertex colors for diffuse. |
diffuseVertexColorChannel | Vertex color channels to use for diffuse. |
emissive | The emissive color of the material. |
emissiveIntensity | Emissive color multiplier. |
emissiveMap | The emissive map of the material (default is null). |
emissiveMapChannel | Color channels of the emissive map to use. |
emissiveMapOffset | Controls the 2D offset of the emissive map. |
emissiveMapRotation | Controls the 2D rotation (in degrees) of the emissive map. |
emissiveMapTiling | Controls the 2D tiling of the emissive map. |
emissiveMapUv | Emissive map UV channel. |
emissiveTint | Multiply emissive map and/or emissive vertex color by the constant emissive value. |
emissiveVertexColor | Use mesh vertex colors for emission. |
emissiveVertexColorChannel | Vertex color channels to use for emission. |
enableGGXSpecular | Enables GGX specular. |
fresnelModel | Defines the formula used for Fresnel effect. |
glossMap | Glossiness map (default is null). |
glossMapChannel | Color channel of the gloss map to use. |
glossMapOffset | Controls the 2D offset of the gloss map. |
glossMapRotation | Controls the 2D rotation (in degrees) of the gloss map. |
glossMapTiling | Controls the 2D tiling of the gloss map. |
glossMapUv | Gloss map UV channel. |
glossVertexColor | Use mesh vertex colors for glossiness. |
glossVertexColorChannel | Vertex color channel to use for glossiness. |
heightMap | The height map of the material (default is null). |
heightMapChannel | Color channel of the height map to use. |
heightMapFactor | Height map multiplier. |
heightMapOffset | Controls the 2D offset of the height map. |
heightMapRotation | Controls the 2D rotation (in degrees) of the height map. |
heightMapTiling | Controls the 2D tiling of the height map. |
heightMapUv | Height map UV channel. |
lightMap | A custom lightmap of the material (default is null). |
lightMapChannel | Color channels of the lightmap to use. |
lightMapOffset | Controls the 2D offset of the lightmap. |
lightMapRotation | Controls the 2D rotation (in degrees) of the lightmap. |
lightMapTiling | Controls the 2D tiling of the lightmap. |
lightMapUv | Lightmap UV channel |
lightVertexColor | Use baked vertex lighting. |
lightVertexColorChannel | Vertex color channels to use for baked lighting. |
metalness | Defines how much the surface is metallic. |
metalnessMap | Monochrome metalness map (default is null). |
metalnessMapChannel | Color channel of the metalness map to use. |
metalnessMapOffset | Controls the 2D offset of the metalness map. |
metalnessMapRotation | Controls the 2D rotation (in degrees) of the metalness map. |
metalnessMapTiling | Controls the 2D tiling of the metalness map. |
metalnessMapUv | Metalness map UV channel. |
metalnessVertexColor | Use mesh vertex colors for metalness. |
metalnessVertexColorChannel | Vertex color channel to use for metalness. |
normalDetailMap | The detail (secondary) normal map of the material (default is null). |
normalDetailMapBumpiness | The bumpiness of the material. |
normalDetailMapOffset | Controls the 2D offset of the detail (secondary) normal map. |
normalDetailMapRotation | Controls the 2D rotation (in degrees) of the detail (secondary) normal map. |
normalDetailMapTiling | Controls the 2D tiling of the detail (secondary) normal map. |
normalDetailMapUv | Detail (secondary) normal map UV channel. |
normalMap | The main (primary) normal map of the material (default is null). |
normalMapOffset | Controls the 2D offset of the main (primary) normal map. |
normalMapRotation | Controls the 2D rotation (in degrees) of the main (primary) normal map. |
normalMapTiling | Controls the 2D tiling of the main (primary) normal map. |
normalMapUv | Main (primary) normal map UV channel. |
occludeDirect | Tells if AO should darken directional lighting. |
occludeSpecular | Uses ambient occlusion to darken specular/reflection. |
occludeSpecularIntensity | Controls visibility of specular occlusion. |
onUpdateShader | A custom function that will be called after all shader generator properties are collected and before shader code is generated. |
opacity | The opacity of the material. |
opacityFadesSpecular | used to specify whether specular and reflections are faded out using StandardMaterial#opacity. |
opacityMap | The opacity map of the material (default is null). |
opacityMapChannel | Color channel of the opacity map to use. |
opacityMapOffset | Controls the 2D offset of the opacity map. |
opacityMapRotation | Controls the 2D rotation (in degrees) of the opacity map. |
opacityMapTiling | Controls the 2D tiling of the opacity map. |
opacityMapUv | Opacity map UV channel. |
opacityVertexColor | Use mesh vertex colors for opacity. |
opacityVertexColorChannel | Vertex color channels to use for opacity. |
pixelSnap | Align vertices to pixel coordinates when rendering. |
reflectivity | Environment map intensity. |
refraction | Defines the visibility of refraction. |
refractionIndex | Defines the index of refraction, i. |
shadingModel | Defines the shading model. |
shininess | Defines glossiness of the material from 0 (rough) to 100 (shiny mirror). |
specular | The specular color of the material. |
specularAntialias | Enables Toksvig AA for mipmapped normal maps with specular. |
specularMap | The specular map of the material (default is null). |
specularMapChannel | Color channels of the specular map to use. |
specularMapOffset | Controls the 2D offset of the specular map. |
specularMapRotation | Controls the 2D rotation (in degrees) of the specular map. |
specularMapTiling | Controls the 2D tiling of the specular map. |
specularMapUv | Specular map UV channel. |
specularTint | Multiply specular map and/or specular vertex color by the constant specular value. |
specularVertexColor | Use mesh vertex colors for specular. |
specularVertexColorChannel | Vertex color channels to use for specular. |
sphereMap | The spherical environment map of the material (default is null). |
twoSidedLighting | Calculate proper normals (and therefore lighting) on backfaces. |
useFog | Apply fogging (as configured in scene settings) |
useGammaTonemap | Apply gamma correction and tonemapping (as configured in scene settings). |
useLighting | Apply lighting |
useMetalness | Use metalness properties instead of specular. |
useSkybox | Apply scene skybox as prefiltered environment map |
Methods
copy | Copy a |
destroy | Removes this material from the scene and possibly frees up memory from its shaders (if there are no other materials using it). |
Inherited
Properties
alphaTest | The alpha test reference value to control which fragments are written to the currently active render target based on alpha value. |
alphaToCoverage | Enables or disables alpha to coverage (WebGL2 only). |
alphaWrite | If true, the alpha component of fragments generated by the shader of this material is written to the color buffer of the currently active render target. |
blendType | Controls how primitives are blended when being written to the currently active render target. |
blueWrite | If true, the blue component of fragments generated by the shader of this material is written to the color buffer of the currently active render target. |
cull | Controls how triangles are culled based on their face direction with respect to the viewpoint. |
depthBias | Offsets the output depth buffer value. |
depthFunc | Controls how the depth of new fragments is compared against the current depth contained in the depth buffer. |
depthTest | If true, fragments generated by the shader of this material are only written to the current render target if they pass the depth test. |
depthWrite | If true, fragments generated by the shader of this material write a depth value to the depth buffer of the currently active render target. |
greenWrite | If true, the green component of fragments generated by the shader of this material is written to the color buffer of the currently active render target. |
name | The name of the material. |
redWrite | If true, the red component of fragments generated by the shader of this material is written to the color buffer of the currently active render target. |
shader | The shader used by this material to render mesh instances (default is null). |
slopeDepthBias | Same as Material#depthBias, but also depends on the slope of the triangle relative to the camera. |
stencilBack | Stencil parameters for back faces (default is null). |
stencilFront | Stencil parameters for front faces (default is null). |
Methods
clone | Clone a material. |
deleteParameter | Deletes a shader parameter on a material. |
getParameter | Retrieves the specified shader parameter from a material. |
setParameter | Sets a shader parameter on a material. |
update | Applies any changes made to the material's properties. |
Details
Constructor
StandardMaterial()
Create a new StandardMaterial instance.
// Create a new Standard material
var material = new pc.StandardMaterial();
// Update the material's diffuse and specular properties
material.diffuse.set(1, 0, 0);
material.specular.set(1, 1, 1);
// Notify the material that it has been modified
material.update();
// Create a new Standard material
var material = new pc.StandardMaterial();
// Assign a texture to the diffuse slot
material.diffuseMap = texture;
// Use the alpha channel of the texture for alpha testing with a reference value of 0.5
material.opacityMap = texture;
material.alphaTest = 0.5;
// Notify the material that it has been modified
material.update();
Properties
used to fade out materials when StandardMaterial#opacityFadesSpecular is set to false.
The ambient color of the material. This color value is 3-component (RGB), where each component is between 0 and 1.
Defines amount of anisotropy. Requires StandardMaterial#enableGGXSpecular is set to true.
- When anisotropy == 0, specular is isotropic.
- When anisotropy < 0, anisotropy direction aligns with the tangent, and specular anisotropy increases as the anisotropy value decreases to minimum of -1.
- When anisotropy > 0, anisotropy direction aligns with the bi-normal, and specular anisotropy increases as anisotropy value increases to maximum of 1.
Use mesh vertex colors for AO. If aoMap is set, it'll be multiplied by vertex colors.
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.
Defines intensity of clear coat layer from 0 to 1. Clear coat layer is disabled when clearCoat == 0. Default value is 0 (disabled).
The bumpiness of the clear coat layer. This value scales the assigned main clear coat 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.
Monochrome clear coat glossiness map (default is null). If specified, will be multiplied by normalized 'clearCoatGlossiness' value and/or vertex colors.
Color channel of the clear coat gloss map to use. Can be "r", "g", "b" or "a".
Controls the 2D offset of the clear coat gloss map. Each component is between 0 and 1.
Controls the 2D rotation (in degrees) of the clear coat gloss map.
Use mesh vertex colors for clear coat glossiness. If clearCoatGlossMap is set, it'll be multiplied by vertex colors.
Vertex color channel to use for clear coat glossiness. Can be "r", "g", "b" or "a".
Defines the clear coat glossiness of the clear coat layer from 0 (rough) to 1 (mirror).
Monochrome clear coat intensity map (default is null). If specified, will be multiplied by normalized 'clearCoat' value and/or vertex colors.
Color channel of the clear coat intensity map to use. Can be "r", "g", "b" or "a".
Controls the 2D offset of the clear coat intensity map. Each component is between 0 and 1.
The clear coat normal map of the material (default is null). The texture must contains normalized, tangent space normals.
Controls the 2D offset of the main clear coat normal map. Each component is between 0 and 1.
Controls the 2D rotation (in degrees) of the main clear coat map.
Use mesh vertex colors for clear coat intensity. If clearCoatMap is set, it'll be multiplied by vertex colors.
Vertex color channel to use for clear coat intensity. Can be "r", "g", "b" or "a".
Defines how diffuse and specular components are combined when Fresnel is on. It is recommended that you leave this option enabled, although you may want to disable it in case when all reflection comes only from a few light sources, and you don't use an environment map, therefore having mostly black reflection.
The cubic environment map of the material (default is null). Overrides sphereMap. Affects reflections. If cubemap is prefiltered, will also affect ambient color.
The type of projection applied to the cubeMap property:
- CUBEPROJ_NONE: The cube map is treated as if it is infinitely far away.
- CUBEPROJ_BOX: Box-projection based on a world space axis-aligned bounding box. Defaults to CUBEPROJ_NONE.
The world space axis-aligned bounding box defining the box-projection used for the cubeMap property. Only used when cubeMapProjection is set to CUBEPROJ_BOX.
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).
The detail (secondary) diffuse map of the material (default is null). Will only be used if main (primary) diffuse map is non-null.
Color channels of the detail (secondary) diffuse map to use. Can be "r", "g", "b", "a", "rgb" or any swizzled combination.
Controls the 2D offset of the detail (secondary) diffuse map. Each component is between 0 and 1.
Controls the 2D rotation (in degrees) of the main (secondary) diffuse map.
Determines how the main (primary) and detail (secondary) diffuse maps are blended together. Can be:
- DETAILMODE_MUL: Multiply together the primary and secondary colors.
- DETAILMODE_ADD: Add together the primary and secondary colors.
- DETAILMODE_SCREEN: Softer version of DETAILMODE_ADD.
- DETAILMODE_OVERLAY: Multiplies or screens the colors, depending on the primary color.
- DETAILMODE_MIN: Select whichever of the primary and secondary colors is darker, component-wise.
- DETAILMODE_MAX: Select whichever of the primary and secondary colors is lighter, component-wise.
Defaults to DETAILMODE_MUL.
Color channels of the main (primary) diffuse map to use. Can be "r", "g", "b", "a", "rgb" or any swizzled combination.
Controls the 2D offset of the main (primary) diffuse map. Each component is between 0 and 1.
Multiply main (primary) diffuse map and/or diffuse vertex color by the constant diffuse value.
Use mesh vertex colors for diffuse. If diffuseMap or are diffuseTint are set, they'll be multiplied by vertex colors.
Vertex color channels to use for diffuse. Can be "r", "g", "b", "a", "rgb" or any swizzled combination.
The emissive color of the material. This color value is 3-component (RGB), where each component is between 0 and 1.
Color channels of the emissive map to use. Can be "r", "g", "b", "a", "rgb" or any swizzled combination.
Controls the 2D offset of the emissive map. Each component is between 0 and 1.
Multiply emissive map and/or emissive vertex color by the constant emissive value.
Use mesh vertex colors for emission. If emissiveMap or emissiveTint are set, they'll be multiplied by vertex colors.
Vertex color channels to use for emission. Can be "r", "g", "b", "a", "rgb" or any swizzled combination.
Enables GGX specular. Also enables StandardMaterial#anisotropy parameter to set material anisotropy.
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 defined by conserveEnergy parameter.
- FRESNEL_NONE: No Fresnel.
- FRESNEL_SCHLICK: Schlick's approximation of Fresnel (recommended). Parameterized by specular color.
Glossiness map (default is null). If specified, will be multiplied by normalized 'shininess' value and/or vertex colors.
Use mesh vertex colors for glossiness. If glossMap is set, it'll be multiplied by vertex colors.
Vertex color channel to use for glossiness. Can be "r", "g", "b" or "a".
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.
A custom lightmap of the material (default is null). Lightmaps are textures that contain pre-rendered lighting. Can be HDR.
Color channels of the lightmap to use. Can be "r", "g", "b", "a", "rgb" or any swizzled combination.
Use baked vertex lighting. If lightMap is set, it'll be multiplied by vertex colors.
Vertex color channels to use for baked lighting. Can be "r", "g", "b", "a", "rgb" or any swizzled combination.
Controls the 2D offset of the metalness map. Each component is between 0 and 1.
Use mesh vertex colors for metalness. If metalnessMap is set, it'll be multiplied by vertex colors.
Vertex color channel to use for metalness. Can be "r", "g", "b" or "a".
The detail (secondary) normal map of the material (default is null). Will only be used if main (primary) normal map is non-null.
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.
Controls the 2D offset of the detail (secondary) normal map. Each component is between 0 and 1.
Controls the 2D rotation (in degrees) of the detail (secondary) normal map.
The main (primary) normal map of the material (default is null). The texture must contains normalized, tangent space normals.
Controls the 2D offset of the main (primary) normal map. Each component is between 0 and 1.
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.
- SPECOCC_NONE: No specular occlusion
- SPECOCC_AO: Use AO directly to occlude specular.
- SPECOCC_GLOSSDEPENDENT: Modify AO based on material glossiness/view angle to occlude specular.
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. Properties of the object passed into this function are:
- pass: value of Layer#shaderPass of the Layer being rendered.
- chunks: Object containing custom shader chunks that will replace default ones.
- customFragmentShader: Completely replace fragment shader with this code.
- forceUv1: if UV1 (second set of texture coordinates) is required in the shader. Will be declared as "vUv1" and passed to the fragment shader.
- fog: the type of fog being applied in the shader. See Scene#fog for the list of possible values.
- gamma: the type of gamma correction being applied in the shader. See Scene#gammaCorrection for the list of possible values.
- toneMap: the type of tone mapping being applied in the shader. See Scene#toneMapping for the list of possible values.
- ambientTint: the value of StandardMaterial#ambientTint.
- specularAntialias: the value of StandardMaterial#specularAntialias.
- conserveEnergy: the value of StandardMaterial#conserveEnergy.
- occludeSpecular: the value of StandardMaterial#occludeSpecular.
- occludeDirect: the value of StandardMaterial#occludeDirect.
- shadingModel: the value of StandardMaterial#shadingModel.
- fresnelModel: the value of StandardMaterial#fresnelModel.
- cubeMapProjection: the value of StandardMaterial#cubeMapProjection.
- useMetalness: the value of StandardMaterial#useMetalness.
- blendType: the value of Material#blendType.
- twoSidedLighting: the value of Material#twoSidedLighting.
- diffuseTint: defines if StandardMaterial#diffuse constant should affect diffuse color.
- specularTint: defines if StandardMaterial#specular constant should affect specular color.
- metalnessTint: defines if StandardMaterial#metalness constant should affect metalness value.
- glossTint: defines if StandardMaterial#shininess constant should affect glossiness value.
- emissiveTint: defines if StandardMaterial#emissive constant should affect emission value.
- opacityTint: defines if StandardMaterial#opacity constant should affect opacity value.
- occludeSpecularFloat: defines if StandardMaterial#occludeSpecularIntensity constant should affect specular occlusion.
- alphaTest: enable alpha testing. See Material#alphaTest.
- alphaToCoverage: enable alpha to coverage. See Material#alphaToCoverage.
- opacityFadesSpecular: enable specular fade. See Material#opacityFadesSpecular.
- alphaFade: fade value. See Material#alphaFade.
- sphereMap: if StandardMaterial#sphereMap is used.
- cubeMap: if StandardMaterial#cubeMap is used.
- ambientSH: if ambient spherical harmonics are used. Ambient SH replace prefiltered cubemap ambient on certain platform (mostly Android) for performance reasons.
- useSpecular: if any specular or reflections are needed at all.
- fixSeams: if cubemaps require seam fixing (see Texture#options.fixCubemapSeams).
- emissiveFormat: how emissiveMap must be sampled. This value is based on
Texture#options.rgbm and Texture#options.format. Possible values are:
- 0: sRGB texture
- 1: RGBM-encoded HDR texture
- 2: Simple read (no conversion from sRGB)
- lightMapFormat: how lightMap must be sampled. This value is based on
Texture#options.rgbm and Texture#options.format. Possible values are:
- 0: sRGB texture
- 1: RGBM-encoded HDR texture
- 2: Simple read (no conversion from sRGB)
- useRgbm: if decodeRGBM() function is needed in the shader at all.
- packedNormal: if normal map contains X in RGB, Y in Alpha, and Z must be reconstructed.
- forceFragmentPrecision: Override fragment shader numeric precision. Can be "lowp", "mediump", "highp" or null to use default.
- fastTbn: Use slightly cheaper normal mapping code (skip tangent space normalization). Can look buggy sometimes.
- refraction: if refraction is used.
- skyboxIntensity: if reflected skybox intensity should be modulated.
- useCubeMapRotation: if cube map rotation is enabled.
- useInstancing: if hardware instancing compatible shader should be generated. Transform is read from per-instance VertexBuffer instead of shader's uniforms.
- useMorphPosition: if morphing code should be generated to morph positions.
- useMorphNormal: if morphing code should be generated to morph normals.
- reflectionSource: one of "envAtlas", "cubeMap", "sphereMap"
- reflectionEncoding: one of null, "rgbm", "rgbe", "linear", "srgb"
- ambientSource: one of "ambientSH", "envAtlas", "constant"
- ambientEncoding: one of null, "rgbm", "rgbe", "linear", "srgb"
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 Material#blendType to BLEND_NORMAL, BLEND_ADDITIVE or any other mode. Also note that for most semi-transparent objects you want Material#depthWrite to be false, otherwise they can fully occlude objects behind them.
used to specify whether specular and reflections are faded out using StandardMaterial#opacity. Default is true. When set to false use Material#alphaFade to fade out materials.
Controls the 2D offset of the opacity map. Each component is between 0 and 1.
Use mesh vertex colors for opacity. If opacityMap is set, it'll be multiplied by vertex colors.
Vertex color channels to use for opacity. Can be "r", "g", "b" or "a".
Align vertices to pixel coordinates when rendering. Useful for pixel perfect 2D graphics.
Defines the visibility of refraction. Material can refract the same cube map as used for reflections.
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).
Defines the shading model.
- SPECULAR_PHONG: Phong without energy conservation. You should only use it as a backwards compatibility with older projects.
- SPECULAR_BLINN: Energy-conserving Blinn-Phong.
Defines glossiness of the material from 0 (rough) to 100 (shiny mirror). A higher shininess value results in a more focused specular highlight. Glossiness map/ vertex colors are always multiplied by this value (normalized to 0 - 1 range), or it is used directly as constant output.
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.
Color channels of the specular map to use. Can be "r", "g", "b", "a", "rgb" or any swizzled combination.
Controls the 2D offset of the specular map. Each component is between 0 and 1.
Multiply specular map and/or specular vertex color by the constant specular value.
Use mesh vertex colors for specular. If specularMap or are specularTint are set, they'll be multiplied by vertex colors.
Vertex color channels to use for specular. Can be "r", "g", "b", "a", "rgb" or any swizzled combination.
The spherical environment map of the material (default is null). Affects reflections.
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 metaless == 0, the pixel is assumed to be dielectric, and diffuse color is used as normal. With metaless == 1, the pixel is fully metallic, and diffuse color is used as specular color instead.
Methods
copy(source)
Copy a StandardMaterial
.
Parameters
source | StandardMaterial | The material to copy from. |
Returns
StandardMaterialThe destination material.
destroy()
Removes this material from the scene and possibly frees up memory from its shaders (if there are no other materials using it).
Inherited
Properties
The alpha test reference value to control which fragments are written to the currently active render target based on alpha value. All fragments with an alpha value of less than the alphaTest reference value will be discarded. alphaTest defaults to 0 (all fragments pass).
Enables or disables alpha to coverage (WebGL2 only). When enabled, and if hardware anti-aliasing is on, limited order-independent transparency can be achieved. Quality depends on the number of MSAA samples of the current render target. It can nicely soften edges of otherwise sharp alpha cutouts, but isn't recommended for large area semi-transparent surfaces. Note, that you don't need to enable blending to make alpha to coverage work. It will work without it, just like alphaTest.
If true, the alpha component of fragments generated by the shader of this material is written to the color buffer of the currently active render target. If false, the alpha component will not be written. Defaults to true.
Controls how primitives are blended when being written to the currently active render target. Can be:
- BLEND_SUBTRACTIVE: Subtract the color of the source fragment from the destination fragment and write the result to the frame buffer.
- BLEND_ADDITIVE: Add the color of the source fragment to the destination fragment and write the result to the frame buffer.
- BLEND_NORMAL: Enable simple translucency for materials such as glass. This is equivalent to enabling a source blend mode of BLENDMODE_SRC_ALPHA and a destination blend mode of BLENDMODE_ONE_MINUS_SRC_ALPHA.
- BLEND_NONE: Disable blending.
- BLEND_PREMULTIPLIED: Similar to BLEND_NORMAL expect the source fragment is assumed to have already been multiplied by the source alpha value.
- BLEND_MULTIPLICATIVE: Multiply the color of the source fragment by the color of the destination fragment and write the result to the frame buffer.
- BLEND_ADDITIVEALPHA: Same as BLEND_ADDITIVE except the source RGB is multiplied by the source alpha.
- BLEND_MULTIPLICATIVE2X: Multiplies colors and doubles the result.
- BLEND_SCREEN: Softer version of additive.
- BLEND_MIN: Minimum color. Check app.graphicsDevice.extBlendMinmax for support.
- BLEND_MAX: Maximum color. Check app.graphicsDevice.extBlendMinmax for support.
Defaults to BLEND_NONE.
If true, the blue component of fragments generated by the shader of this material is written to the color buffer of the currently active render target. If false, the blue component will not be written. Defaults to true.
Controls how triangles are culled based on their face direction with respect to the viewpoint. Can be:
- CULLFACE_NONE: Do not cull triangles based on face direction.
- CULLFACE_BACK: Cull the back faces of triangles (do not render triangles facing away from the view point).
- CULLFACE_FRONT: Cull the front faces of triangles (do not render triangles facing towards the view point).
- CULLFACE_FRONTANDBACK: Cull both front and back faces (triangles will not be rendered).
Defaults to CULLFACE_BACK.
Controls how the depth of new fragments is compared against the current depth contained in the depth buffer. Can be:
- FUNC_NEVER: don't draw
- FUNC_LESS: draw if new depth < depth buffer
- FUNC_EQUAL: draw if new depth == depth buffer
- FUNC_LESSEQUAL: draw if new depth <= depth buffer
- FUNC_GREATER: draw if new depth > depth buffer
- FUNC_NOTEQUAL: draw if new depth != depth buffer
- FUNC_GREATEREQUAL: draw if new depth >= depth buffer
- FUNC_ALWAYS: always draw
Defaults to FUNC_LESSEQUAL.
If true, fragments generated by the shader of this material are only written to the current render target if they pass the depth test. If false, fragments generated by the shader of this material are written to the current render target regardless of what is in the depth buffer. Defaults to true.
If true, fragments generated by the shader of this material write a depth value to the depth buffer of the currently active render target. If false, no depth value is written. Defaults to true.
If true, the green component of fragments generated by the shader of this material is written to the color buffer of the currently active render target. If false, the green component will not be written. Defaults to true.
If true, the red component of fragments generated by the shader of this material is written to the color buffer of the currently active render target. If false, the red component will not be written. Defaults to true.
Same as Material#depthBias, but also depends on the slope of the triangle relative to the camera.
Methods
deleteParameter(name)
Deletes a shader parameter on a material.
Parameters
name | string | The name of the parameter to delete. |
getParameter(name)
Retrieves the specified shader parameter from a material.
Parameters
name | string | The name of the parameter to query. |
Returns
objectThe named parameter.
setParameter(name, data)
Sets a shader parameter on a material.
Parameters
name | string | The name of the parameter to set. |
data | number, number[], Float32Array, Texture | The value for the specified parameter. |
update()
Applies any changes made to the material's properties.