API Reference

Class List

pc.StandardMaterial

Extends: pc.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 simlulate dynamic reflected light.

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

Summary

Properties

ambientThe ambient color of the material.
ambientTintEnables scene ambient multiplication by material ambient color.
aoMapBaked ambient occlusion map.
aoMapChannelColor channel of the AO map to use.
aoMapOffsetControls the 2D offset of the AO map.
aoMapTilingControls the 2D tiling of the AO map.
aoMapUvAO map UV channel
aoMapVertexColorUse vertex colors for AO instead of a map
bumpinessThe bumpiness of the material.
conserveEnergyDefines how diffuse and specular components are combined when Fresnel is on.
cubeMapThe cubic environment map of the material.
cubeMapProjectionThe type of projection applied to the cubeMap property:
  • pc.CUBEPROJ_NONE: The cube map is treated as if it is infinitely far away.
cubeMapProjectionBoxThe world space axis-aligned bounding box defining the box-projection used for the cubeMap property.
diffuseThe diffuse color of the material.
diffuseMapThe diffuse map of the material.
diffuseMapChannelColor channels of the diffuse map to use.
diffuseMapOffsetControls the 2D offset of the diffuse map.
diffuseMapTilingControls the 2D tiling of the diffuse map.
diffuseMapTintEnables diffuseMap multiplication by diffuse color.
diffuseMapUvDiffuse map UV channel
diffuseMapVertexColorUse vertex colors for diffuse instead of a map
emissiveThe emissive color of the material.
emissiveIntensityEmissive color multiplier.
emissiveMapThe emissive map of the material.
emissiveMapChannelColor channels of the emissive map to use.
emissiveMapOffsetControls the 2D offset of the emissive map.
emissiveMapTilingControls the 2D tiling of the emissive map.
emissiveMapTintEnables emissiveMap multiplication by emissive color.
emissiveMapUvEmissive map UV channel
emissiveMapVertexColorUse vertex colors for emission instead of a map
fresnelModelDefines the formula used for Fresnel effect.
glossMapThe per-pixel gloss of the material.
glossMapChannelColor channel of the gloss map to use.
glossMapOffsetControls the 2D offset of the gloss map.
glossMapTilingControls the 2D tiling of the gloss map.
glossMapUvGloss map UV channel
glossMapVertexColorUse vertex colors for glossiness instead of a map
heightMapThe height map of the material.
heightMapChannelColor channel of the height map to use.
heightMapFactorHeight map multiplier.
heightMapOffsetControls the 2D offset of the height map.
heightMapTilingControls the 2D tiling of the height map.
heightMapUvHeight map UV channel
lightMapThe light map of the material.
lightMapChannelColor channels of the lightmap to use.
lightMapOffsetControls the 2D offset of the lightmap.
lightMapTilingControls the 2D tiling of the lightmap.
lightMapUvLightmap UV channel
lightMapVertexColorUse vertex lightmap instead of a texture-based one
metalnessDefines how much the surface is metallic.
metalnessMapMonochrome metalness map.
metalnessMapChannelColor channel of the metalness map to use.
metalnessMapOffsetControls the 2D offset of the metalness map.
metalnessMapTilingControls the 2D tiling of the metalness map.
metalnessMapUvMetnalness map UV channel
metalnessMapVertexColorUse vertex colors for metalness instead of a map
normalMapThe normal map of the material.
normalMapOffsetControls the 2D offset of the normal map.
normalMapTilingControls the 2D tiling of the normal map.
normalMapUvNormal map UV channel
occludeSpecularUses aoMap to occlude specular/reflection.
occludeSpecularIntensityControls visibility of specular occlusion.
opacityThe opacity of the material.
opacityMapThe opacity map of the material.
opacityMapChannelColor channel of the opacity map to use.
opacityMapOffsetControls the 2D offset of the opacity map.
opacityMapTilingControls the 2D tiling of the opacity map.
opacityMapUvOpacity map UV channel
opacityMapVertexColorUse vertex colors for opacity instead of a map
reflectivityThe reflectivity of the material.
refractionDefines the visibility of refraction.
refractionIndexDefines the index of refraction, i.
shadingModelDefines the shading model.
shininessDefines glossiness of the material from 0 (rough) to 100 (mirror).
specularThe specular color of the material.
specularAntialiasEnables Toksvig AA for mipmapped normal maps with specular.
specularMapThe per-pixel specular map of the material.
specularMapChannelColor channels of the specular map to use.
specularMapOffsetControls the 2D offset of the specular map.
specularMapTilingControls the 2D tiling of the specular map.
specularMapTintEnables specularMap multiplication by specular color.
specularMapUvSpecular map UV channel
specularMapVertexColorUse vertex colors for specular instead of a map
sphereMapThe spherical environment map of the material.
useFogApply fogging (as configured in scene settings)
useGammaTonemapApply gamma correction and tonemapping (as configured in scene settings)
useLightingApply lighting
useMetalnessUse metalness properties instead of specular.
useSkyboxApply scene skybox as prefiltered environment map

Methods

cloneDuplicates a Standard material.

Inherited

Properties

alphaTestThe alpha test reference value to control which fragements are written to the currently active render target based on alpha value.
alphaWriteIf 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.
blendTypeControls how primitives are blended when being written to the currently active render target.
blueWriteIf 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.
cullControls how triangles are culled based on their face direction with respect to the viewpoint.
depthTestIf true, fragments generated by the shader of this material are only written to the current render target if they pass the depth test.
depthWriteIf true, fragments generated by the shader of this material write a depth value to the depth buffer of the currently active render target.
greenWriteIf 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.
nameThe name of the material.
redWriteIf 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.
shaderThe shader used by this material to render mesh instances.
stencilBackStencil parameters for back faces (default is null).
stencilFrontStencil parameters for front faces (default is null).

Methods

deleteParameterDeletes a shader parameter on a material.
getParameterRetrieves the specified shader parameter from a material.
initInitializes the material with the properties in the specified data.
setParameterSets a shader parameter on a material.
setParametersPushes all material parameters into scope.
updateApplies any changes made to the material's properties.

Details

Constructor

StandardMaterial()

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

Properties

pc.Colorambient

The ambient color of the material. This color value is 3-component (RGB), where each component is between 0 and 1.

BooleanambientTint

Enables scene ambient multiplication by material ambient color.

pc.TextureaoMap

Baked ambient occlusion map. Modulates ambient color.

StringaoMapChannel

Color channel of the AO map to use. Can be "r", "g", "b" or "a".

pc.Vec2aoMapOffset

Controls the 2D offset of the AO map. Each component is between 0 and 1.

pc.Vec2aoMapTiling

Controls the 2D tiling of the AO map.

NumberaoMapUv

AO map UV channel

BooleanaoMapVertexColor

Use vertex colors for AO instead of a map

Numberbumpiness

The bumpiness of the material. This value scales the assigned normal map and can be between 0 and 1, where 0 shows no contribution from the normal map and 1 results in a full contribution.

BooleanconserveEnergy

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.

pc.TexturecubeMap

The cubic environment map of the material.

NumbercubeMapProjection

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.

pc.BoundingBoxcubeMapProjectionBox

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.

pc.Colordiffuse

The diffuse color of the material. This color value is 3-component (RGB), where each component is between 0 and 1.

pc.TexturediffuseMap

The diffuse map of the material. This must be a 2D texture rather than a cube map. If this property is set to a valid texture, the texture is used as the source for diffuse color in preference to the 'diffuse' property.

StringdiffuseMapChannel

Color channels of the diffuse map to use. Can be "r", "g", "b", "a", "rgb" or any swizzled combination.

pc.Vec2diffuseMapOffset

Controls the 2D offset of the diffuse map. Each component is between 0 and 1.

pc.Vec2diffuseMapTiling

Controls the 2D tiling of the diffuse map.

BooleandiffuseMapTint

Enables diffuseMap multiplication by diffuse color.

NumberdiffuseMapUv

Diffuse map UV channel

BooleandiffuseMapVertexColor

Use vertex colors for diffuse instead of a map

pc.Vec3emissive

The emissive color of the material. This color value is 3-component (RGB), where each component is between 0 and 1.

NumberemissiveIntensity

Emissive color multiplier.

pc.TextureemissiveMap

The emissive map of the material. This must be a 2D texture rather than a cube map. If this property is set to a valid texture, the texture is used as the source for emissive color in preference to the 'emissive' property.

StringemissiveMapChannel

Color channels of the emissive map to use. Can be "r", "g", "b", "a", "rgb" or any swizzled combination.

pc.Vec2emissiveMapOffset

Controls the 2D offset of the emissive map. Each component is between 0 and 1.

pc.Vec2emissiveMapTiling

Controls the 2D tiling of the emissive map.

BooleanemissiveMapTint

Enables emissiveMap multiplication by emissive color.

NumberemissiveMapUv

Emissive map UV channel

BooleanemissiveMapVertexColor

Use vertex colors for emission instead of a map

NumberfresnelModel

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.

pc.TextureglossMap

The per-pixel gloss of the material. This must be a 2D texture rather than a cube map. If this property is set to a valid texture, the texture is used as the source for shininess in preference to the 'shininess' property.

StringglossMapChannel

Color channel of the gloss map to use. Can be "r", "g", "b" or "a".

pc.Vec2glossMapOffset

Controls the 2D offset of the gloss map. Each component is between 0 and 1.

pc.Vec2glossMapTiling

Controls the 2D tiling of the gloss map.

NumberglossMapUv

Gloss map UV channel

BooleanglossMapVertexColor

Use vertex colors for glossiness instead of a map

pc.TextureheightMap

The height map of the material. This must be a 2D texture rather than a cube map. The texture contain values defining the height of the surface at that point where darker pixels are lower and lighter pixels are higher.

StringheightMapChannel

Color channel of the height map to use. Can be "r", "g", "b" or "a".

NumberheightMapFactor

Height map multiplier. Height maps are used to create a parallax mapping effect and modifying this value will alter the strength of the parallax effect.

pc.Vec2heightMapOffset

Controls the 2D offset of the height map. Each component is between 0 and 1.

pc.Vec2heightMapTiling

Controls the 2D tiling of the height map.

NumberheightMapUv

Height map UV channel

pc.TexturelightMap

The light map of the material.

StringlightMapChannel

Color channels of the lightmap to use. Can be "r", "g", "b", "a", "rgb" or any swizzled combination.

pc.Vec2lightMapOffset

Controls the 2D offset of the lightmap. Each component is between 0 and 1.

pc.Vec2lightMapTiling

Controls the 2D tiling of the lightmap.

NumberlightMapUv

Lightmap UV channel

BooleanlightMapVertexColor

Use vertex lightmap instead of a texture-based one

Numbermetalness

Defines how much the surface is metallic. From 0 (dielectric) to 1 (metal). This can be used as alternative to specular color to save space. Metallic surfaces have their reflection tinted with diffuse color.

pc.TexturemetalnessMap

Monochrome metalness map.

StringmetalnessMapChannel

Color channel of the metalness map to use. Can be "r", "g", "b" or "a".

pc.Vec2metalnessMapOffset

Controls the 2D offset of the metalness map. Each component is between 0 and 1.

pc.Vec2metalnessMapTiling

Controls the 2D tiling of the metalness map.

NumbermetalnessMapUv

Metnalness map UV channel

BooleanmetalnessMapVertexColor

Use vertex colors for metalness instead of a map

pc.TexturenormalMap

The normal map of the material. This must be a 2D texture rather than a cube map. The texture must contains normalized, tangent space normals.

pc.Vec2normalMapOffset

Controls the 2D offset of the normal map. Each component is between 0 and 1.

pc.Vec2normalMapTiling

Controls the 2D tiling of the normal map.

NumbernormalMapUv

Normal map UV channel

NumberoccludeSpecular

Uses aoMap to occlude specular/reflection. It's a hack, because real specular occlusion is view-dependent. However, it's much better than nothing.

  • pc.SPECOCC_NONE: No specular occlusion
  • pc.SPECOCC_AO: Use AO map directly to occlude specular.
  • pc.SPECOCC_GLOSSDEPENDENT: Modify AO map based on material glossiness/view angle to occlude specular.

NumberoccludeSpecularIntensity

Controls visibility of specular occlusion.

Numberopacity

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 transparent you also need to set the pc.Material#blendType to pc.BLEND_NORMAL or pc.BLEND_ADDITIVE.

pc.TextureopacityMap

The opacity map of the material. This must be a 2D texture rather than a cube map. If this property is set to a valid texture, the texture is used as the source for opacity in preference to the 'opacity' property. If you want the material to be transparent you also need to set the pc.Material#blendType to pc.BLEND_NORMAL or pc.BLEND_ADDITIVE.

StringopacityMapChannel

Color channel of the opacity map to use. Can be "r", "g", "b" or "a".

pc.Vec2opacityMapOffset

Controls the 2D offset of the opacity map. Each component is between 0 and 1.

pc.Vec2opacityMapTiling

Controls the 2D tiling of the opacity map.

NumberopacityMapUv

Opacity map UV channel

BooleanopacityMapVertexColor

Use vertex colors for opacity instead of a map

Numberreflectivity

The reflectivity of the material. This value scales the reflection map and can be between 0 and 1, where 0 shows no reflection and 1 is fully reflective.

Numberrefraction

Defines the visibility of refraction. Material can refract the same cube map as used for reflections.

NumberrefractionIndex

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

NumbershadingModel

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.

Numbershininess

Defines glossiness of the material from 0 (rough) to 100 (mirror). A higher shininess value results in a more focussed specular highlight.

pc.Colorspecular

The specular color of the material. This color value is 3-component (RGB),

BooleanspecularAntialias

Enables Toksvig AA for mipmapped normal maps with specular.

pc.TexturespecularMap

The per-pixel specular map of the material. This must be a 2D texture rather than a cube map. If this property is set to a valid texture, the texture is used as the source for specular color in preference to the 'specular' property.

StringspecularMapChannel

Color channels of the specular map to use. Can be "r", "g", "b", "a", "rgb" or any swizzled combination.

pc.Vec2specularMapOffset

Controls the 2D offset of the specular map. Each component is between 0 and 1.

pc.Vec2specularMapTiling

Controls the 2D tiling of the specular map.

BooleanspecularMapTint

Enables specularMap multiplication by specular color.

NumberspecularMapUv

Specular map UV channel

BooleanspecularMapVertexColor

Use vertex colors for specular instead of a map

pc.TexturesphereMap

The spherical environment map of the material.

BooleanuseFog

Apply fogging (as configured in scene settings)

BooleanuseGammaTonemap

Apply gamma correction and tonemapping (as configured in scene settings)

BooleanuseLighting

Apply lighting

BooleanuseMetalness

Use metalness properties instead of specular.

BooleanuseSkybox

Apply scene skybox as prefiltered environment map

Methods

clone()

Duplicates a Standard material. All properties are duplicated except textures where only the references are copied.

Returns

pc.StandardMaterial A cloned Standard material.

Inherited

Properties

NumberalphaTest

The alpha test reference value to control which fragements 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).

BooleanalphaWrite

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.

NumberblendType

Controls how primitives are blended when being written to the currently active render target. Can be one of the following values:

  • pc.BLEND_SUBTRACTIVE: Subtract the color of the source fragment from the destination fragment and write the result to the frame buffer.
  • pc.BLEND_ADDITIVE: Add the color of the source fragment to the destination fragment and write the result to the frame buffer.
  • pc.BLEND_NORMAL: Enable simple translucency for materials such as glass. This is equivalent to enabling a source blend mode of pc.BLENDMODE_SRC_ALPHA and a destination blend mode of pc.BLENDMODE_ONE_MINUS_SRC_ALPHA.
  • pc.BLEND_NONE: Disable blending.
  • pc.BLEND_PREMULTIPLIED: Similar to pc.BLEND_NORMAL expect the source fragment is assumed to have already been multiplied by the source alpha value.
  • pc.BLEND_MULTIPLICATIVE: Multiply the color of the source fragment by the color of the destination fragment and write the result to the frame buffer.
  • pc.BLEND_ADDITIVEALPHA: Same as pc.BLEND_ADDITIVE except the source RGB is multiplied by the source alpha.
Defaults to pc.BLEND_NONE.

BooleanblueWrite

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.

Numbercull

Controls how triangles are culled based on their face direction with respect to the viewpoint. Can be one of the following values:

  • pc.CULLFACE_NONE: Do not cull triangles based on face direction.
  • pc.CULLFACE_BACK: Cull the back faces of triangles (do not render triangles facing away from the view point).
  • pc.CULLFACE_FRONT: Cull the front faces of triangles (do not render triangles facing towards the view point).
  • pc.CULLFACE_FRONTANDBACK: Cull both front and back faces (triangles will not be rendered).
Defaults to pc.CULLFACE_BACK.

BooleandepthTest

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.

BooleandepthWrite

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.

BooleangreenWrite

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.

Stringname

The name of the material.

BooleanredWrite

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.

pc.Shadershader

The shader used by this material to render mesh instances.

pc.StencilParametersstencilBack

Stencil parameters for back faces (default is null).

pc.StencilParametersstencilFront

Stencil parameters for front faces (default is null).

Methods

deleteParameter(name)

Deletes a shader parameter on a material.

Parameters

nameStringThe name of the parameter to delete.

getParameter(name)

Retrieves the specified shader parameter from a material.

Parameters

nameStringThe name of the parameter to query.

Returns

Object The named parameter.

init(data)

Initializes the material with the properties in the specified data.

Parameters

dataObjectThe initial data for the material.

setParameter(name, data)

Sets a shader parameter on a material.

Parameters

nameStringThe name of the parameter to set.
dataNumber, Array, pc.TextureThe value for the specified parameter.

setParameters()

Pushes all material parameters into scope.

update()

Applies any changes made to the material's properties.