Class: StandardMaterial

pc.StandardMaterial

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.

Constructor

new StandardMaterial()

Properties:
Name Type Description
ambient pc.Color The ambient color of the material. This color value is 3-component (RGB), where each component is between 0 and 1.
diffuse pc.Color 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).
diffuseTint Boolean Multiply diffuse map and/or diffuse vertex color by the constant diffuse value.
diffuseMap pc.Texture The diffuse map of the material.
diffuseMapUv Number Diffuse map UV channel
diffuseMapTiling pc.Vec2 Controls the 2D tiling of the diffuse map.
diffuseMapOffset pc.Vec2 Controls the 2D offset of the diffuse map. Each component is between 0 and 1.
diffuseMapChannel String Color channels of the diffuse map to use. Can be "r", "g", "b", "a", "rgb" or any swizzled combination.
diffuseVertexColor Boolean Use mesh vertex colors for diffuse. If diffuseMap or are diffuseTint are set, they'll be multiplied by vertex colors.
diffuseVertexColorChannel String Vertex color channels to use for diffuse. Can be "r", "g", "b", "a", "rgb" or any swizzled combination.
specular pc.Color 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.
specularTint Boolean Multiply specular map and/or specular vertex color by the constant specular value.
specularMap pc.Texture The specular map of the material.
specularMapUv Number Specular map UV channel
specularMapTiling pc.Vec2 Controls the 2D tiling of the specular map.
specularMapOffset pc.Vec2 Controls the 2D offset of the specular map. Each component is between 0 and 1.
specularMapChannel String Color channels of the specular map to use. Can be "r", "g", "b", "a", "rgb" or any swizzled combination.
specularVertexColor Boolean Use mesh vertex colors for specular. If specularMap or are specularTint are set, they'll be multiplied by vertex colors.
specularVertexColorChannel String Vertex color channels to use for specular. Can be "r", "g", "b", "a", "rgb" or any swizzled combination.
useMetalness Boolean 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.
metalness Number Defines how much the surface is metallic. From 0 (dielectric) to 1 (metal).
metalnessMap pc.Texture Monochrome metalness map.
metalnessMapUv Number Metalness map UV channel
metalnessMapTiling pc.Vec2 Controls the 2D tiling of the metalness map.
metalnessMapOffset pc.Vec2 Controls the 2D offset of the metalness map. Each component is between 0 and 1.
metalnessMapChannel String Color channel of the metalness map to use. Can be "r", "g", "b" or "a".
metalnessVertexColor Boolean Use mesh vertex colors for metalness. If metalnessMap is set, it'll be multiplied by vertex colors.
metalnessVertexColorChannel String Vertex color channel to use for metalness. Can be "r", "g", "b" or "a".
shininess Number 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.
glossMap pc.Texture Glossiness map. If set, will be multiplied by normalized 'shininess' value and/or vertex colors.
glossMapUv Number Gloss map UV channel
glossMapChannel String Color channel of the gloss map to use. Can be "r", "g", "b" or "a".
glossMapTiling pc.Vec2 Controls the 2D tiling of the gloss map.
glossMapOffset pc.Vec2 Controls the 2D offset of the gloss map. Each component is between 0 and 1.
glossVertexColor Boolean Use mesh vertex colors for glossiness. If glossMap is set, it'll be multiplied by vertex colors.
glossVertexColorChannel String Vertex color channel to use for glossiness. Can be "r", "g", "b" or "a".
refraction Number Defines the visibility of refraction. Material can refract the same cube map as used for reflections.
refractionIndex Number 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 it's own surface. In most situations outer medium is air, so outerIor will be approximately 1. Then you only need to do (1.0 / surfaceIor).
emissive pc.Color The emissive color of the material. This color value is 3-component (RGB), where each component is between 0 and 1.
emissiveTint Boolean Multiply emissive map and/or emissive vertex color by the constant emissive value.
emissiveMap pc.Texture The emissive map of the material. Can be HDR.
emissiveIntensity Number Emissive color multiplier.
emissiveMapUv Number Emissive map UV channel.
emissiveMapTiling pc.Vec2 Controls the 2D tiling of the emissive map.
emissiveMapOffset pc.Vec2 Controls the 2D offset of the emissive map. Each component is between 0 and 1.
emissiveMapChannel String Color channels of the emissive map to use. Can be "r", "g", "b", "a", "rgb" or any swizzled combination.
emissiveVertexColor Boolean Use mesh vertex colors for emission. If emissiveMap or emissiveTint are set, they'll be multiplied by vertex colors.
emissiveVertexColorChannel String Vertex color channels to use for emission. Can be "r", "g", "b", "a", "rgb" or any swizzled combination.
opacity Number 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 pc.Material#blendType to pc.BLEND_NORMAL, pc.BLEND_ADDITIVE or any other mode. Also note that for most semi-transparent objects you want pc.Material#depthWrite to be false, otherwise they can fully occlude objects behind them.
opacityMap pc.Texture The opacity map of the material.
opacityMapUv Number Opacity map UV channel
opacityMapChannel String Color channel of the opacity map to use. Can be "r", "g", "b" or "a".
opacityMapTiling pc.Vec2 Controls the 2D tiling of the opacity map.
opacityMapOffset pc.Vec2 Controls the 2D offset of the opacity map. Each component is between 0 and 1.
opacityVertexColor Boolean Use mesh vertex colors for opacity. If opacityMap is set, it'll be multiplied by vertex colors.
opacityVertexColorChannel String Vertex color channels to use for opacity. Can be "r", "g", "b" or "a".
normalMap pc.Texture The normal map of the material. The texture must contains normalized, tangent space normals.
normalMapUv Number Normal map UV channel
normalMapTiling pc.Vec2 Controls the 2D tiling of the normal map.
normalMapOffset pc.Vec2 Controls the 2D offset of the normal map. Each component is between 0 and 1.
bumpiness Number The bumpiness of the material. This value scales the assigned 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.
heightMap pc.Texture The height map of the material. 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.
heightMapUv Number Height map UV channel
heightMapChannel String Color channel of the height map to use. Can be "r", "g", "b" or "a".
heightMapTiling pc.Vec2 Controls the 2D tiling of the height map.
heightMapOffset pc.Vec2 Controls the 2D offset of the height map. Each component is between 0 and 1.
heightMapFactor Number Height map multiplier. Affects the strength of the parallax effect.
sphereMap pc.Texture The spherical environment map of the material. Affects reflections.
cubeMap pc.Texture The cubic environment map of the material. Overrides sphereMap. Affects reflections. If cubemap is prefiltered, will also affect ambient color.
cubeMapProjection Number The type of projection applied to the cubeMap property:
  • pc.CUBEPROJ_NONE: The cube map is treated as if it is infinitely far away.
  • pc.CUBEPROJ_BOX: Box-projection based on a world space axis-aligned bounding box.
Defaults to pc.CUBEPROJ_NONE.
cubeMapProjectionBox pc.BoundingBox The world space axis-aligned bounding box defining the box-projection used for the cubeMap property. Only used when cubeMapProjection is set to pc.CUBEPROJ_BOX.
reflectivity Number Environment map intensity.
lightMap pc.Texture A custom lightmap of the material. Lightmaps are textures that contain pre-rendered lighting. Can be HDR.
lightMapUv Number Lightmap UV channel
lightMapChannel String Color channels of the lightmap to use. Can be "r", "g", "b", "a", "rgb" or any swizzled combination.
lightMapTiling pc.Vec2 Controls the 2D tiling of the lightmap.
lightMapOffset pc.Vec2 Controls the 2D offset of the lightmap. Each component is between 0 and 1.
lightVertexColor Boolean Use baked vertex lighting. If lightMap is set, it'll be multiplied by vertex colors.
lightVertexColorChannel String Vertex color channels to use for baked lighting. Can be "r", "g", "b", "a", "rgb" or any swizzled combination.
ambientTint Boolean Enables scene ambient multiplication by material ambient color.
aoMap pc.Texture Baked ambient occlusion (AO) map. Modulates ambient color.
aoMapUv Number AO map UV channel
aoMapChannel String Color channel of the AO map to use. Can be "r", "g", "b" or "a".
aoMapTiling pc.Vec2 Controls the 2D tiling of the AO map.
aoMapOffset pc.Vec2 Controls the 2D offset of the AO map. Each component is between 0 and 1.
aoVertexColor Boolean Use mesh vertex colors for AO. If aoMap is set, it'll be multiplied by vertex colors.
aoVertexColorChannel String Vertex color channels to use for AO. Can be "r", "g", "b" or "a".
occludeSpecular Number 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.
  • pc.SPECOCC_NONE: No specular occlusion
  • pc.SPECOCC_AO: Use AO directly to occlude specular.
  • pc.SPECOCC_GLOSSDEPENDENT: Modify AO based on material glossiness/view angle to occlude specular.
occludeSpecularIntensity Number Controls visibility of specular occlusion.
occludeDirect Number Tells if AO should darken directional lighting.
specularAntialias Boolean Enables Toksvig AA for mipmapped normal maps with specular.
conserveEnergy Boolean 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.
shadingModel Number Defines the shading model.
  • pc.SPECULAR_PHONG: Phong without energy conservation. You should only use it as a backwards compatibility with older projects.
  • pc.SPECULAR_BLINN: Energy-conserving Blinn-Phong.
fresnelModel Number 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 behaviour is defined by conserveEnergy parameter.
  • pc.FRESNEL_NONE: No Fresnel.
  • pc.FRESNEL_SCHLICK: Schlick's approximation of Fresnel (recommended). Parameterized by specular color.
useFog Boolean Apply fogging (as configured in scene settings)
useLighting Boolean Apply lighting
useSkybox Boolean Apply scene skybox as prefiltered environment map
useGammaTonemap Boolean Apply gamma correction and tonemapping (as configured in scene settings)
pixelSnap Boolean Align vertices to pixel co-ordinates when rendering. Useful for pixel perfect 2D graphics
twoSidedLighting Boolean Calculate proper normals (and therefore lighting) on backfaces
onUpdateShader function 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 pc.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 pc.Scene#fog for the list of possible values.
  • gamma: the type of gamma correction being applied in the shader. See pc.Scene#gammaCorrection for the list of possible values.
  • toneMap: the type of tone mapping being applied in the shader. See pc.Scene#toneMapping for the list of possible values.
  • ambientTint: the value of pc.StandardMaterial#ambientTint.
  • specularAntialias: the value of pc.StandardMaterial#specularAntialias.
  • conserveEnergy: the value of pc.StandardMaterial#conserveEnergy.
  • occludeSpecular: the value of pc.StandardMaterial#occludeSpecular.
  • occludeDirect: the value of pc.StandardMaterial#occludeDirect.
  • shadingModel: the value of pc.StandardMaterial#shadingModel.
  • fresnelModel: the value of pc.StandardMaterial#fresnelModel.
  • cubeMapProjection: the value of pc.StandardMaterial#cubeMapProjection.
  • useMetalness: the value of pc.StandardMaterial#useMetalness.
  • blendType: the value of pc.Material#blendType.
  • twoSidedLighting: the value of pc.Material#twoSidedLighting.
  • diffuseTint: defines if pc.StandardMaterial#diffuse constant should affect diffuse color.
  • specularTint: defines if pc.StandardMaterial#specular constant should affect specular color.
  • metalnessTint: defines if pc.StandardMaterial#metalness constant should affect metalness value.
  • glossTint: defines if pc.StandardMaterial#shininess constant should affect glossiness value.
  • emissiveTint: defines if pc.StandardMaterial#emissive constant should affect emission value.
  • opacityTint: defines if pc.StandardMaterial#opacity constant should affect opacity value.
  • occludeSpecularFloat: defines if pc.StandardMaterial#occludeSpecularIntensity constant should affect specular occlusion.
  • alphaTest: enable alpha testing. See pc.Material#alphaTest.
  • alphaToCoverage: enable alpha to coverage. See pc.Material#alphaToCoverage.
  • sphereMap: if pc.StandardMaterial#sphereMap is used.
  • cubeMap: if pc.StandardMaterial#cubeMap is used.
  • dpAtlas: if dual-paraboloid reflection is used. Dual paraboloid reflections replace prefiltered cubemaps on certain platform (mostly Android) for performance reasons.
  • 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.
  • rgbmAmbient: if ambient cubemap or spherical harmonics are RGBM-encoded.
  • hdrAmbient: if ambient cubemap or spherical harmonics are plain float HDR data.
  • rgbmReflection: if reflection cubemap or dual paraboloid are RGBM-encoded.
  • hdrReflection: if reflection cubemap or dual paraboloid are plain float HDR data.
  • fixSeams: if cubemaps require seam fixing (see pc.Texture#options.fixCubemapSeams).
  • prefilteredCubemap: if prefiltered cubemaps are used.
  • emissiveFormat: how emissiveMap must be sampled. This value is based on pc.Texture#options.rgbm and pc.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 pc.Texture#options.rgbm and pc.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.
  • useTexCubeLod: if textureCubeLodEXT function should be used to read prefiltered cubemaps. Usually true of iOS, false on other devices due to quality/performance balance.
Source:
Example
// 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();

Extends

Methods

clone() → {pc.StandardMaterial}

Duplicates a Standard material. All properties are duplicated except textures where only the references are copied.
Source:
Returns:
A cloned Standard material.
Type
pc.StandardMaterial

deleteParameter(name)

Deletes a shader parameter on a material.
Parameters:
Name Type Description
name String The name of the parameter to delete.
Inherited From:
Source:

destroy()

Removes this material from the scene and possibly frees up memory from its shaders (if there are no other materials using it).
Inherited From:
Source:

getParameter(name) → {Object}

Retrieves the specified shader parameter from a material.
Parameters:
Name Type Description
name String The name of the parameter to query.
Inherited From:
Source:
Returns:
The named parameter.
Type
Object

setParameter(name, data, passFlagsopt)

Sets a shader parameter on a material.
Parameters:
Name Type Attributes Description
name String The name of the parameter to set.
data Number | Array | pc.Texture The value for the specified parameter.
passFlags Number <optional>
Mask describing which passes the material should be included in.
Inherited From:
Source:

setParameters()

Pushes all material parameters into scope.
Inherited From:
Source:

update()

Applies any changes made to the material's properties.
Inherited From:
Source: