# StandardMaterial

Class · extends [`Material`](https://api.playcanvas.com/engine/classes/Material.md) · category: Graphics

Source: https://github.com/playcanvas/engine/blob/970d89f6d3bc6667f4e1f88153abd6e7e82ed52c/src/scene/materials/standard-material.js#L627

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](https://api.playcanvas.com/engine/classes/Color.md) or number),
mesh vertex colors and a [Texture](https://api.playcanvas.com/engine/classes/Texture.md). All enabled inputs are multiplied together. A texture
samples one of the mesh's UV sets, selected by the map's UV channel property (0 to 7), and is
ignored when the mesh does not provide that set. UV sets 6 and 7 share their vertex attribute
locations with the default hardware instancing format, so an instanced mesh sampling them needs a
custom instancing vertex format, see [MeshInstance#setInstancing](https://api.playcanvas.com/engine/classes/MeshInstance.md#setinstancing).

A property assignment only reaches the GPU once [Material#update](https://api.playcanvas.com/engine/classes/Material.md#update) is called: a `diffuse`
or `emissive` change made after the material's first frame is not applied until
`material.update()` runs. The debug build reports unapplied changes to the properties stored in
the material uniform buffer, such as `diffuse`.

Properties come in families that share a naming pattern. A family such as `diffuse` has a
constant (`diffuse`), a texture (`diffuseMap`) with its `diffuseMapUv`, `diffuseMapTiling`,
`diffuseMapOffset`, `diffuseMapRotation` and `diffuseMapChannel`, and a vertex color switch
(`diffuseVertexColor`). The main families are `diffuse`; `specular`, or `metalness` when
`useMetalness` is set; `gloss`; `normalMap` with `bumpiness`; `emissive`; `opacity` together
with [Material#blendType](https://api.playcanvas.com/engine/classes/Material.md#blendtype); `ao`; `lightMap`; and the advanced layers `clearCoat`, `sheen`,
`iridescence` and `refraction`. Lighting can be turned off entirely with `useLighting`.

To go beyond the properties, replace individual shader chunks with
[Material#getShaderChunks](https://api.playcanvas.com/engine/classes/Material.md#getshaderchunks). When the surface is not a lit material at all, use
[ShaderMaterial](https://api.playcanvas.com/engine/classes/ShaderMaterial.md) instead.

**Example**

```ts
const material = new StandardMaterial();
material.diffuse.set(0.8, 0.2, 0.2);
material.diffuseMap = brickAsset.resource;
material.useMetalness = true;
material.metalness = 0.1;
material.gloss = 0.6;
material.update();
entity.render.material = material;
```

## Constructors

### constructor

```ts
new StandardMaterial()
```

Create a new StandardMaterial instance.

**Example**

```ts
// Create a new Standard material
const material = new 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();
```

**Example**

```ts
// Create a new Standard material
const material = new 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

### anisotropyMap

```ts
anisotropyMap: Texture | null
```

The anisotropy map of the material (default is null).

### anisotropyMapOffset

```ts
anisotropyMapOffset: Vec2
```

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

### anisotropyMapRotation

```ts
anisotropyMapRotation: number
```

Controls the 2D rotation (in degrees) of the anisotropy map.

### anisotropyMapTiling

```ts
anisotropyMapTiling: Vec2
```

Controls the 2D tiling of the anisotropy map.

### anisotropyMapUv

```ts
anisotropyMapUv: number
```

Anisotropy map UV channel. Valid values are 0 to 7.

### aoDetailMap

```ts
aoDetailMap: Texture | null
```

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.

### aoDetailMapChannel

```ts
aoDetailMapChannel: string
```

Color channels of the detail (secondary) AO map to use.
Can be "r", "g", "b" or "a" (default is "g").

### aoDetailMapOffset

```ts
aoDetailMapOffset: Vec2
```

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

### aoDetailMapRotation

```ts
aoDetailMapRotation: number
```

Controls the 2D rotation (in degrees) of the detail
(secondary) AO map.

### aoDetailMapTiling

```ts
aoDetailMapTiling: Vec2
```

Controls the 2D tiling of the detail (secondary) AO map.

### aoDetailMapUv

```ts
aoDetailMapUv: number
```

Detail (secondary) AO map UV channel. Valid values are 0 to 7.

### aoDetailMode

```ts
aoDetailMode: string
```

Determines how the main (primary) and detail (secondary)
AO 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.

### aoMap

```ts
aoMap: Texture | null
```

The main (primary) baked ambient occlusion (AO) map (default is
null). Modulates ambient color.

### aoMapChannel

```ts
aoMapChannel: string
```

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

### aoMapOffset

```ts
aoMapOffset: Vec2
```

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

### aoMapRotation

```ts
aoMapRotation: number
```

Controls the 2D rotation (in degrees) of the main (primary) AO map.

### aoMapTiling

```ts
aoMapTiling: Vec2
```

Controls the 2D tiling of the main (primary) AO map.

### aoMapUv

```ts
aoMapUv: number
```

Main (primary) AO map UV channel. Valid values are 0 to 7.

### aoVertexColor

```ts
aoVertexColor: boolean
```

Use mesh vertex colors for AO. If aoMap is set, it'll be
multiplied by vertex colors.

### aoVertexColorChannel

```ts
aoVertexColorChannel: string
```

Vertex color channels to use for AO. Can be "r", "g",
"b" or "a".

### clearCoatGlossInvert

```ts
clearCoatGlossInvert: boolean
```

Invert the clearcoat gloss component (default is false).
Enabling this flag results in material treating the clear coat gloss members as roughness.

### clearCoatGlossMap

```ts
clearCoatGlossMap: Texture | null
```

Monochrome clearcoat glossiness map (default is
null). If specified, will be multiplied by normalized 'clearCoatGloss' value and/or vertex
colors.

### clearCoatGlossMapChannel

```ts
clearCoatGlossMapChannel: string
```

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

### clearCoatGlossMapOffset

```ts
clearCoatGlossMapOffset: Vec2
```

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

### clearCoatGlossMapRotation

```ts
clearCoatGlossMapRotation: number
```

Controls the 2D rotation (in degrees) of the clear
coat gloss map.

### clearCoatGlossMapTiling

```ts
clearCoatGlossMapTiling: Vec2
```

Controls the 2D tiling of the clearcoat gloss map.

### clearCoatGlossMapUv

```ts
clearCoatGlossMapUv: number
```

Clearcoat gloss map UV channel. Valid values are 0 to 7.

### clearCoatGlossVertexColor

```ts
clearCoatGlossVertexColor: boolean
```

Use mesh vertex colors for clearcoat glossiness.
If clearCoatGlossMap is set, it'll be multiplied by vertex colors.

### clearCoatGlossVertexColorChannel

```ts
clearCoatGlossVertexColorChannel: string
```

Vertex color channel to use for clearcoat
glossiness. Can be "r", "g", "b" or "a".

### clearCoatMap

```ts
clearCoatMap: Texture | null
```

Monochrome clearcoat intensity map (default is null). If
specified, will be multiplied by normalized 'clearCoat' value and/or vertex colors.

### clearCoatMapChannel

```ts
clearCoatMapChannel: string
```

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

### clearCoatMapOffset

```ts
clearCoatMapOffset: Vec2
```

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

### clearCoatMapRotation

```ts
clearCoatMapRotation: number
```

Controls the 2D rotation (in degrees) of the clearcoat
intensity map.

### clearCoatMapTiling

```ts
clearCoatMapTiling: Vec2
```

Controls the 2D tiling of the clearcoat intensity map.

### clearCoatMapUv

```ts
clearCoatMapUv: number
```

Clearcoat intensity map UV channel. Valid values are 0 to 7.

### clearCoatNormalMap

```ts
clearCoatNormalMap: Texture | null
```

The clearcoat normal map of the material (default is
null). The texture must contains normalized, tangent space normals.

### clearCoatNormalMapOffset

```ts
clearCoatNormalMapOffset: Vec2
```

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

### clearCoatNormalMapRotation

```ts
clearCoatNormalMapRotation: number
```

Controls the 2D rotation (in degrees) of the main
clearcoat map.

### clearCoatNormalMapTiling

```ts
clearCoatNormalMapTiling: Vec2
```

Controls the 2D tiling of the main clearcoat normal
map.

### clearCoatNormalMapUv

```ts
clearCoatNormalMapUv: number
```

Clearcoat normal map UV channel. Valid values are 0 to 7.

### clearCoatVertexColor

```ts
clearCoatVertexColor: boolean
```

Use mesh vertex colors for clearcoat intensity. If
clearCoatMap is set, it'll be multiplied by vertex colors.

### clearCoatVertexColorChannel

```ts
clearCoatVertexColorChannel: string
```

Vertex color channel to use for clearcoat
intensity. Can be "r", "g", "b" or "a".

### cubeMap

```ts
cubeMap: Texture | null
```

The cubic environment map of the material (default is null).
This setting overrides sphereMap and will replace the scene lighting environment.

### cubeMapProjection

```ts
cubeMapProjection: number
```

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.

### diffuseDetailMap

```ts
diffuseDetailMap: Texture | null
```

The detail (secondary) diffuse map of the material
(default is null). Will only be used if main (primary) diffuse map is non-null.

### diffuseDetailMapChannel

```ts
diffuseDetailMapChannel: string
```

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

### diffuseDetailMapOffset

```ts
diffuseDetailMapOffset: Vec2
```

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

### diffuseDetailMapRotation

```ts
diffuseDetailMapRotation: number
```

Controls the 2D rotation (in degrees) of the detail
(secondary) diffuse map.

### diffuseDetailMapTiling

```ts
diffuseDetailMapTiling: Vec2
```

Controls the 2D tiling of the detail (secondary) diffuse
map.

### diffuseDetailMapUv

```ts
diffuseDetailMapUv: number
```

Detail (secondary) diffuse map UV channel. Valid values are 0 to 7.

### diffuseDetailMode

```ts
diffuseDetailMode: string
```

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.

### diffuseMap

```ts
diffuseMap: Texture | null
```

The main (primary) diffuse map of the material (default is
null).

### diffuseMapChannel

```ts
diffuseMapChannel: string
```

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

### diffuseMapOffset

```ts
diffuseMapOffset: Vec2
```

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

### diffuseMapRotation

```ts
diffuseMapRotation: number
```

Controls the 2D rotation (in degrees) of the main
(primary) diffuse map.

### diffuseMapTiling

```ts
diffuseMapTiling: Vec2
```

Controls the 2D tiling of the main (primary) diffuse map.

### diffuseMapUv

```ts
diffuseMapUv: number
```

Main (primary) diffuse map UV channel. Valid values are 0 to 7.

### diffuseVertexColor

```ts
diffuseVertexColor: boolean
```

Multiply diffuse by the mesh vertex colors.

### diffuseVertexColorChannel

```ts
diffuseVertexColorChannel: string
```

Vertex color channels to use for diffuse. Can be
"r", "g", "b", "a", "rgb" or any swizzled combination.

### emissiveMap

```ts
emissiveMap: Texture | null
```

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.

### emissiveMapChannel

```ts
emissiveMapChannel: string
```

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

### emissiveMapOffset

```ts
emissiveMapOffset: Vec2
```

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

### emissiveMapRotation

```ts
emissiveMapRotation: number
```

Controls the 2D rotation (in degrees) of the emissive
map.

### emissiveMapTiling

```ts
emissiveMapTiling: Vec2
```

Controls the 2D tiling of the emissive map.

### emissiveMapUv

```ts
emissiveMapUv: number
```

Emissive map UV channel. Valid values are 0 to 7.

### emissiveVertexColor

```ts
emissiveVertexColor: boolean
```

Use mesh vertex colors for emission. If emissiveMap or
emissive are set, they'll be multiplied by vertex colors.

### emissiveVertexColorChannel

```ts
emissiveVertexColorChannel: string
```

Vertex color channels to use for emission. Can be
"r", "g", "b", "a", "rgb" or any swizzled combination.

### enableGGXSpecular

```ts
enableGGXSpecular: boolean
```

Enables GGX specular. Also enables
anisotropyIntensity parameter to set material anisotropy.

### envAtlas

```ts
envAtlas: Texture | null
```

The prefiltered environment lighting atlas (default is null).
This setting overrides cubeMap and sphereMap and will replace the scene lighting environment.

### fresnelModel

```ts
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 behavior is energy-conserving.

- FRESNEL_NONE: No Fresnel.
- FRESNEL_SCHLICK: Schlick's approximation of Fresnel (recommended). Parameterized by
specular color.

### glossInvert

```ts
glossInvert: boolean
```

Invert the gloss component (default is false). Enabling this
flag results in material treating the gloss members as roughness.

### glossMap

```ts
glossMap: Texture | null
```

Gloss map (default is null). If specified, will be multiplied
by normalized gloss value and/or vertex colors.

### glossMapChannel

```ts
glossMapChannel: string
```

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

### glossMapOffset

```ts
glossMapOffset: Vec2
```

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

### glossMapRotation

```ts
glossMapRotation: number
```

Controls the 2D rotation (in degrees) of the gloss map.

### glossMapTiling

```ts
glossMapTiling: Vec2
```

Controls the 2D tiling of the gloss map.

### glossMapUv

```ts
glossMapUv: number
```

Gloss map UV channel. Valid values are 0 to 7.

### glossVertexColor

```ts
glossVertexColor: boolean
```

Use mesh vertex colors for glossiness. If glossMap is set,
it'll be multiplied by vertex colors.

### glossVertexColorChannel

```ts
glossVertexColorChannel: string
```

Vertex color channel to use for glossiness. Can be
"r", "g", "b" or "a".

### heightMap

```ts
heightMap: Texture | null
```

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, with heightMapBase selecting the
value that sits at the level of the original geometry. It is recommended to use it together with
a normal map. Note that the parallax offset is applied to all other maps of the material, so the
height map should use the same tiling and offset as those maps.

### heightMapChannel

```ts
heightMapChannel: string
```

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

### heightMapOffset

```ts
heightMapOffset: Vec2
```

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

### heightMapRotation

```ts
heightMapRotation: number
```

Controls the 2D rotation (in degrees) of the height map.

### heightMapTiling

```ts
heightMapTiling: Vec2
```

Controls the 2D tiling of the height map.

### heightMapUv

```ts
heightMapUv: number
```

Height map UV channel. Valid values are 0 to 7.

### iridescenceMap

```ts
iridescenceMap: Texture | null
```

The per-pixel iridescence intensity. Only used when
useIridescence is enabled.

### iridescenceMapChannel

```ts
iridescenceMapChannel: string
```

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

### iridescenceMapOffset

```ts
iridescenceMapOffset: Vec2
```

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

### iridescenceMapRotation

```ts
iridescenceMapRotation: number
```

Controls the 2D rotation (in degrees) of the iridescence
map.

### iridescenceMapTiling

```ts
iridescenceMapTiling: Vec2
```

Controls the 2D tiling of the iridescence map.

### iridescenceMapUv

```ts
iridescenceMapUv: number
```

Iridescence map UV channel. Valid values are 0 to 7.

### iridescenceThicknessMap

```ts
iridescenceThicknessMap: Texture | null
```

The per-pixel iridescence thickness. Defines a
gradient weight between iridescenceThicknessMin and iridescenceThicknessMax. Only used when
useIridescence is enabled.

### iridescenceThicknessMapChannel

```ts
iridescenceThicknessMapChannel: string
```

Color channels of the iridescence thickness
map to use. Can be "r", "g", "b" or "a".

### iridescenceThicknessMapOffset

```ts
iridescenceThicknessMapOffset: Vec2
```

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

### iridescenceThicknessMapRotation

```ts
iridescenceThicknessMapRotation: number
```

Controls the 2D rotation (in degrees)
of the iridescence thickness map.

### iridescenceThicknessMapTiling

```ts
iridescenceThicknessMapTiling: Vec2
```

Controls the 2D tiling of the iridescence
thickness map.

### iridescenceThicknessMapUv

```ts
iridescenceThicknessMapUv: number
```

Iridescence thickness map UV channel. Valid values are 0 to 7.

### lightMap

```ts
lightMap: Texture | null
```

A custom lightmap of the material (default is null). Lightmaps
are textures that contain pre-rendered lighting. Can be HDR. When a mesh instance rendered with
this material has a lightmap of its own, baked by the Lightmapper, that lightmap is used
instead of this one.

### lightMapChannel

```ts
lightMapChannel: string
```

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

### lightMapOffset

```ts
lightMapOffset: Vec2
```

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

### lightMapRotation

```ts
lightMapRotation: number
```

Controls the 2D rotation (in degrees) of the lightmap.

### lightMapTiling

```ts
lightMapTiling: Vec2
```

Controls the 2D tiling of the lightmap.

### lightMapUv

```ts
lightMapUv: number
```

Lightmap UV channel. Valid values are 0 to 7.

### lightVertexColor

```ts
lightVertexColor: boolean
```

Use baked vertex lighting. If lightMap is set, it'll be
multiplied by vertex colors.

### lightVertexColorChannel

```ts
lightVertexColorChannel: string
```

Vertex color channels to use for baked lighting. Can
be "r", "g", "b", "a", "rgb" or any swizzled combination.

### metalnessMap

```ts
metalnessMap: Texture | null
```

Monochrome metalness map (default is null).

### metalnessMapChannel

```ts
metalnessMapChannel: string
```

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

### metalnessMapOffset

```ts
metalnessMapOffset: Vec2
```

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

### metalnessMapRotation

```ts
metalnessMapRotation: number
```

Controls the 2D rotation (in degrees) of the metalness
map.

### metalnessMapTiling

```ts
metalnessMapTiling: Vec2
```

Controls the 2D tiling of the metalness map.

### metalnessMapUv

```ts
metalnessMapUv: number
```

Metalness map UV channel. Valid values are 0 to 7.

### metalnessVertexColor

```ts
metalnessVertexColor: boolean
```

Use mesh vertex colors for metalness. If metalnessMap
is set, it'll be multiplied by vertex colors.

### metalnessVertexColorChannel

```ts
metalnessVertexColorChannel: string
```

Vertex color channel to use for metalness. Can be
"r", "g", "b" or "a".

### normalDetailMap

```ts
normalDetailMap: Texture | null
```

The detail (secondary) normal map of the material
(default is null). Will only be used if main (primary) normal map is non-null.

### normalDetailMapOffset

```ts
normalDetailMapOffset: Vec2
```

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

### normalDetailMapRotation

```ts
normalDetailMapRotation: number
```

Controls the 2D rotation (in degrees) of the detail
(secondary) normal map.

### normalDetailMapTiling

```ts
normalDetailMapTiling: Vec2
```

Controls the 2D tiling of the detail (secondary) normal
map.

### normalDetailMapUv

```ts
normalDetailMapUv: number
```

Detail (secondary) normal map UV channel. Valid values are 0 to 7.

### normalMap

```ts
normalMap: Texture | null
```

The main (primary) normal map of the material (default is
null). The texture must contains normalized, tangent space normals.

### normalMapOffset

```ts
normalMapOffset: Vec2
```

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

### normalMapRotation

```ts
normalMapRotation: number
```

Controls the 2D rotation (in degrees) of the main (primary)
normal map.

### normalMapTiling

```ts
normalMapTiling: Vec2
```

Controls the 2D tiling of the main (primary) normal map.

### normalMapUv

```ts
normalMapUv: number
```

Main (primary) normal map UV channel. Valid values are 0 to 7.

### occludeDirect

```ts
occludeDirect: boolean
```

Tells if AO should darken directional lighting. Defaults to
false.

### occludeSpecular

```ts
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.

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

### onUpdateShader

```ts
onUpdateShader: UpdateShaderCallback | undefined
```

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 [StandardMaterialOptions](https://api.playcanvas.com/engine/classes/StandardMaterialOptions.md) and the options for the lit options are
[LitShaderOptions](https://api.playcanvas.com/engine/classes/LitShaderOptions.md).

### opacityDither

```ts
opacityDither: string
```

Used to specify whether opacity is dithered, which allows
transparency without alpha blending. Can be:

- DITHER_NONE: Opacity dithering is disabled.
- DITHER_BAYER2: Opacity is dithered using a Bayer 2 matrix.
- DITHER_BAYER4: Opacity is dithered using a Bayer 4 matrix.
- DITHER_BAYER8: Opacity is dithered using a Bayer 8 matrix.
- DITHER_BAYER16: Opacity is dithered using a Bayer 16 matrix.
- DITHER_BLUENOISE: Opacity is dithered using a blue noise.
- DITHER_IGNNOISE: Opacity is dithered using an interleaved gradient noise.

Defaults to DITHER_NONE.

### opacityFadesSpecular

```ts
opacityFadesSpecular: boolean
```

Used to specify whether specular and reflections are
faded out using opacity. Default is true. When set to false use alphaFade to
fade out materials.

### opacityMap

```ts
opacityMap: Texture | null
```

The opacity map of the material (default is null).

### opacityMapChannel

```ts
opacityMapChannel: string
```

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

### opacityMapOffset

```ts
opacityMapOffset: Vec2
```

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

### opacityMapRotation

```ts
opacityMapRotation: number
```

Controls the 2D rotation (in degrees) of the opacity map.

### opacityMapTiling

```ts
opacityMapTiling: Vec2
```

Controls the 2D tiling of the opacity map.

### opacityMapUv

```ts
opacityMapUv: number
```

Opacity map UV channel. Valid values are 0 to 7.

### opacityShadowDither

```ts
opacityShadowDither: string
```

Used to specify whether shadow opacity is dithered, which
allows shadow transparency without alpha blending. Can be:

- DITHER_NONE: Opacity dithering is disabled.
- DITHER_BAYER2: Opacity is dithered using a Bayer 2 matrix.
- DITHER_BAYER4: Opacity is dithered using a Bayer 4 matrix.
- DITHER_BAYER8: Opacity is dithered using a Bayer 8 matrix.
- DITHER_BAYER16: Opacity is dithered using a Bayer 16 matrix.
- DITHER_BLUENOISE: Opacity is dithered using a blue noise.
- DITHER_IGNNOISE: Opacity is dithered using an interleaved gradient noise.

Defaults to DITHER_NONE.

### opacityVertexColor

```ts
opacityVertexColor: boolean
```

Use mesh vertex colors for opacity. If opacityMap is set,
it'll be multiplied by vertex colors.

### opacityVertexColorChannel

```ts
opacityVertexColorChannel: string
```

Vertex color channels to use for opacity. Can be
"r", "g", "b" or "a".

### parallaxMode

```ts
parallaxMode: string
```

Selects how the height map is used to offset the UV of the other
maps of the material. Can be:

- PARALLAX_OFFSET: A single tap of the height map, which pivots the surface around the
heightMapBase level of the map.
- PARALLAX_OCCLUSION: The view ray is marched through the height field, which spans
heightMapFactor of depth with the geometry sitting at the heightMapBase level.
This represents deeper displacement without smearing, at the cost of multiple taps per pixel.
Note that the silhouette of the mesh is not affected, and the depth buffer still sees the flat
surface.

Defaults to PARALLAX_OFFSET.

### pixelSnap

```ts
pixelSnap: boolean
```

Align vertices to pixel coordinates when rendering. Useful for
pixel perfect 2D graphics.

### refractionMap

```ts
refractionMap: Texture | null
```

The map of the refraction visibility.

### refractionMapChannel

```ts
refractionMapChannel: string
```

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

### refractionMapOffset

```ts
refractionMapOffset: Vec2
```

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

### refractionMapRotation

```ts
refractionMapRotation: number
```

Controls the 2D rotation (in degrees) of the
refraction map.

### refractionMapTiling

```ts
refractionMapTiling: Vec2
```

Controls the 2D tiling of the refraction map.

### refractionMapUv

```ts
refractionMapUv: number
```

Refraction map UV channel. Valid values are 0 to 7.

### refractionVertexColor

```ts
refractionVertexColor: boolean
```

Use mesh vertex colors for refraction. If
refraction map is set, it will be multiplied by vertex colors.

### refractionVertexColorChannel

```ts
refractionVertexColorChannel: string
```

Vertex color channel to use for refraction.
Can be "r", "g", "b" or "a".

### shadowCatcher

```ts
shadowCatcher: boolean
```

When enabled, the material will output accumulated directional
shadow value in linear space as the color.

### sheenGlossInvert

```ts
sheenGlossInvert: boolean
```

Invert the sheen gloss component (default is false).
Enabling this flag results in material treating the sheen gloss members as roughness.

### sheenGlossMap

```ts
sheenGlossMap: Texture | null
```

The sheen glossiness microstructure color map of the
material (default is null).

### sheenGlossMapChannel

```ts
sheenGlossMapChannel: string
```

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

### sheenGlossMapOffset

```ts
sheenGlossMapOffset: Vec2
```

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

### sheenGlossMapRotation

```ts
sheenGlossMapRotation: number
```

Controls the 2D rotation (in degrees) of the sheen
glossiness map.

### sheenGlossMapTiling

```ts
sheenGlossMapTiling: Vec2
```

Controls the 2D tiling of the sheen glossiness map.

### sheenGlossMapUv

```ts
sheenGlossMapUv: number
```

Sheen glossiness map UV channel. Valid values are 0 to 7.

### sheenGlossVertexColor

```ts
sheenGlossVertexColor: boolean
```

Use mesh vertex colors for sheen glossiness.
If sheen glossiness map or sheen glossiness tint are set, they'll be multiplied by vertex colors.

### sheenGlossVertexColorChannel

```ts
sheenGlossVertexColorChannel: string
```

Vertex color channels to use for sheen glossiness.
Can be "r", "g", "b" or "a".

### sheenMap

```ts
sheenMap: Texture | null
```

The sheen microstructure color map of the material (default is
null).

### sheenMapChannel

```ts
sheenMapChannel: string
```

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

### sheenMapOffset

```ts
sheenMapOffset: Vec2
```

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

### sheenMapRotation

```ts
sheenMapRotation: number
```

Controls the 2D rotation (in degrees) of the sheen
map.

### sheenMapTiling

```ts
sheenMapTiling: Vec2
```

Controls the 2D tiling of the sheen map.

### sheenMapUv

```ts
sheenMapUv: number
```

Sheen map UV channel. Valid values are 0 to 7.

### sheenVertexColor

```ts
sheenVertexColor: boolean
```

Use mesh vertex colors for sheen. If sheen map or
sheen tint are set, they'll be multiplied by vertex colors.

### sheenVertexColorChannel

```ts
sheenVertexColorChannel: string
```

Vertex color channels to use for sheen. Can be "r",
"g", "b", "a", "rgb" or any swizzled combination.

### specularityFactorMap

```ts
specularityFactorMap: Texture | null
```

The factor of specularity as a texture (default is
null).

### specularityFactorMapChannel

```ts
specularityFactorMapChannel: string
```

The channel used by the specularity factor texture to sample from (default is 'a').

### specularityFactorMapOffset

```ts
specularityFactorMapOffset: Vec2
```

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

### specularityFactorMapRotation

```ts
specularityFactorMapRotation: number
```

Controls the 2D rotation (in degrees) of the specularity factor map.

### specularityFactorMapTiling

```ts
specularityFactorMapTiling: Vec2
```

Controls the 2D tiling of the specularity factor map.

### specularityFactorMapUv

```ts
specularityFactorMapUv: number
```

Specularity factor map UV channel. Valid values are 0 to 7.

### specularityFactorTint

```ts
specularityFactorTint: boolean
```

Force inclusion of the constant `specularityFactor`
when compositing with `specularityFactorMap` and/or specularity factor vertex colors. Defaults
to `false`. Setting this to `true` is rarely needed - the constant is automatically applied
whenever `specularityFactor` differs from 1. Provided as an explicit override.

### specularityFactorVertexColor

```ts
specularityFactorVertexColor: boolean
```

Use mesh vertex colors for specularity factor. If specularityFactorMap or
are specularityFactorTint are set, they'll be multiplied by vertex colors.

### specularityFactorVertexColorChannel

```ts
specularityFactorVertexColorChannel: string
```

Vertex color channels to use for specularity factor. Can be
"r", "g", "b", "a", "rgb" or any swizzled combination.

### specularMap

```ts
specularMap: Texture | null
```

The specular map of the material (default is null).

### specularMapChannel

```ts
specularMapChannel: string
```

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

### specularMapOffset

```ts
specularMapOffset: Vec2
```

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

### specularMapRotation

```ts
specularMapRotation: number
```

Controls the 2D rotation (in degrees) of the specular map.

### specularMapTiling

```ts
specularMapTiling: Vec2
```

Controls the 2D tiling of the specular map.

### specularMapUv

```ts
specularMapUv: number
```

Specular map UV channel. Valid values are 0 to 7.

### specularVertexColor

```ts
specularVertexColor: boolean
```

Multiply specular by the mesh vertex colors.

### specularVertexColorChannel

```ts
specularVertexColorChannel: string
```

Vertex color channels to use for specular. Can be
"r", "g", "b", "a", "rgb" or any swizzled combination.

### sphereMap

```ts
sphereMap: Texture | null
```

The spherical environment map of the material (default is
null). This will replace the scene lighting environment.

### thicknessMap

```ts
thicknessMap: Texture | null
```

The per-pixel thickness of the medium, only used when
useDynamicRefraction is enabled.

### thicknessMapChannel

```ts
thicknessMapChannel: string
```

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

### thicknessMapOffset

```ts
thicknessMapOffset: Vec2
```

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

### thicknessMapRotation

```ts
thicknessMapRotation: number
```

Controls the 2D rotation (in degrees) of the thickness
map.

### thicknessMapTiling

```ts
thicknessMapTiling: Vec2
```

Controls the 2D tiling of the thickness map.

### thicknessMapUv

```ts
thicknessMapUv: number
```

Thickness map UV channel. Valid values are 0 to 7.

### thicknessVertexColor

```ts
thicknessVertexColor: boolean
```

Use mesh vertex colors for thickness. If
thickness map is set, it will be multiplied by vertex colors.

### thicknessVertexColorChannel

```ts
thicknessVertexColorChannel: string
```

Vertex color channel to use for thickness. Can
be "r", "g", "b" or "a".

### twoSidedLighting

```ts
twoSidedLighting: boolean
```

Calculate proper normals (and therefore lighting) on
backfaces.

### useDynamicRefraction

```ts
useDynamicRefraction: boolean
```

Enables higher quality refractions using the grab pass
instead of pre-computed cube maps for refractions.

### useFog

```ts
useFog: boolean
```

Apply fogging (as configured in scene settings)

### useIridescence

```ts
useIridescence: boolean
```

Enable thin-film iridescence.

### useLighting

```ts
useLighting: boolean
```

Apply lighting

### useMetalness

```ts
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 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.

### useMetalnessSpecularColor

```ts
useMetalnessSpecularColor: boolean
```

When metalness is enabled, use the
specular map to apply color tint to specular reflections.

### useSheen

```ts
useSheen: boolean
```

Toggle sheen specular effect on/off.

### useSkybox

```ts
useSkybox: boolean
```

Apply scene skybox as prefiltered environment map

### useTonemap

```ts
useTonemap: boolean
```

Apply tonemapping (as configured via
CameraComponent#toneMapping). Defaults to true.

### vertexColorGamma

```ts
vertexColorGamma: boolean
```

When set to true, the vertex shader converts vertex colors
from gamma to linear space to ensure correct interpolation in the fragment shader. This flag is
provided for backwards compatibility, allowing users to mark their materials to handle vertex
colors in gamma space. Defaults to false, which indicates that vertex colors are stored in
linear space.

## Accessors

### alphaDither

```ts
get alphaDither(): number
set alphaDither(value: number)
```

Gets the dither alpha of the material.

### alphaFade

```ts
get alphaFade(): number
set alphaFade(value: number)
```

Gets the alpha fade of the material.

### alphaTest

```ts
get alphaTest(): number
set alphaTest(value: number)
```

Gets the alpha test reference value.

### ambient

```ts
get ambient(): Color
set ambient(value: Color)
```

Gets the ambient color of the material.

### anisotropyIntensity

```ts
get anisotropyIntensity(): number
set anisotropyIntensity(value: number)
```

Gets the anisotropy intensity of the material.

### anisotropyRotation

```ts
get anisotropyRotation(): number
set anisotropyRotation(value: number)
```

Gets the anisotropy rotation of the material.

### aoIntensity

```ts
get aoIntensity(): number
set aoIntensity(value: number)
```

Gets the ambient occlusion intensity of the material.

### attenuation

```ts
get attenuation(): Color
set attenuation(value: Color)
```

Gets the attenuation color of the material.

### attenuationDistance

```ts
get attenuationDistance(): number
set attenuationDistance(value: number)
```

Gets the attenuation distance of the material.

### bumpiness

```ts
get bumpiness(): number
set bumpiness(value: number)
```

Gets the bumpiness of the material.

### clearCoat

```ts
get clearCoat(): number
set clearCoat(value: number)
```

Gets the clearcoat intensity of the material.

### clearCoatBumpiness

```ts
get clearCoatBumpiness(): number
set clearCoatBumpiness(value: number)
```

Gets the clearcoat bumpiness of the material.

### clearCoatGloss

```ts
get clearCoatGloss(): number
set clearCoatGloss(value: number)
```

Gets the clearcoat glossiness of the material.

### cubeMapProjectionBox

```ts
get cubeMapProjectionBox(): BoundingBox | null
set cubeMapProjectionBox(value: BoundingBox | null)
```

Gets the world space axis-aligned bounding box of the box-projection, or null. A change of
its center or half extents is applied by [StandardMaterial#update](https://api.playcanvas.com/engine/classes/StandardMaterial.md#update).

### diffuse

```ts
get diffuse(): Color
set diffuse(value: Color)
```

Gets the diffuse color of the material.

### dispersion

```ts
get dispersion(): number
set dispersion(value: number)
```

Gets the dispersion of the material.

### emissive

```ts
get emissive(): Color
set emissive(value: Color)
```

Gets the emissive color of the material.

### emissiveIntensity

```ts
get emissiveIntensity(): number
set emissiveIntensity(value: number)
```

Gets the emissive color multiplier.

### gloss

```ts
get gloss(): number
set gloss(value: number)
```

Gets the glossiness of the material.

### heightMapBase

```ts
get heightMapBase(): number
set heightMapBase(value: number)
```

Gets the height map base level of the material.

### heightMapFactor

```ts
get heightMapFactor(): number
set heightMapFactor(value: number)
```

Gets the height map factor of the material.

### iridescence

```ts
get iridescence(): number
set iridescence(value: number)
```

Gets the iridescence intensity of the material.

### iridescenceRefractionIndex

```ts
get iridescenceRefractionIndex(): number
set iridescenceRefractionIndex(value: number)
```

Gets the index of refraction of the iridescent thin-film of the material.

### iridescenceThicknessMax

```ts
get iridescenceThicknessMax(): number
set iridescenceThicknessMax(value: number)
```

Gets the maximum iridescence thickness of the material.

### iridescenceThicknessMin

```ts
get iridescenceThicknessMin(): number
set iridescenceThicknessMin(value: number)
```

Gets the minimum iridescence thickness of the material.

### metalness

```ts
get metalness(): number
set metalness(value: number)
```

Gets the metalness of the material.

### normalDetailMapBumpiness

```ts
get normalDetailMapBumpiness(): number
set normalDetailMapBumpiness(value: number)
```

Gets the detail normal map bumpiness of the material.

### occludeSpecularIntensity

```ts
get occludeSpecularIntensity(): number
set occludeSpecularIntensity(value: number)
```

Gets the specular occlusion intensity of the material.

### opacity

```ts
get opacity(): number
set opacity(value: number)
```

Gets the opacity of the material.

### parallaxSamples

```ts
get parallaxSamples(): number
set parallaxSamples(value: number)
```

Gets the maximum number of height map taps of parallax occlusion mapping of the material.

### parallaxShadowSamples

```ts
get parallaxShadowSamples(): number
set parallaxShadowSamples(value: number)
```

Gets the maximum number of height map taps of the parallax self shadowing of the material.

### reflectivity

```ts
get reflectivity(): number
set reflectivity(value: number)
```

Gets the environment map intensity of the material.

### refraction

```ts
get refraction(): number
set refraction(value: number)
```

Gets the refraction of the material.

### refractionIndex

```ts
get refractionIndex(): number
set refractionIndex(value: number)
```

Gets the index of refraction of the material.

### sheen

```ts
get sheen(): Color
set sheen(value: Color)
```

Gets the sheen color of the material.

### sheenGloss

```ts
get sheenGloss(): number
set sheenGloss(value: number)
```

Gets the sheen glossiness of the material.

### specular

```ts
get specular(): Color
set specular(value: Color)
```

Gets the specular color of the material.

### specularityFactor

```ts
get specularityFactor(): number
set specularityFactor(value: number)
```

Gets the specularity factor of the material.

### thickness

```ts
get thickness(): number
set thickness(value: number)
```

Gets the thickness of the medium of the material.

## Methods

### copy

```ts
copy(source: StandardMaterial): StandardMaterial
```

Copy a `StandardMaterial`.

**Parameters**

- `source` ([`StandardMaterial`](https://api.playcanvas.com/engine/classes/StandardMaterial.md)): The material to copy from.

**Returns** [`StandardMaterial`](https://api.playcanvas.com/engine/classes/StandardMaterial.md): The destination material.

### destroy

```ts
destroy(): void
```

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

### setAttribute

```ts
setAttribute(name: string, semantic: string): void
```

Sets a vertex shader attribute on a material.

**Parameters**

- `name` (`string`): The name of the parameter to set.
- `semantic` (`string`): Semantic to map the vertex data. Must match with the semantic set
  on vertex stream of the mesh.

**Example**

```ts
mesh.setVertexStream(SEMANTIC_ATTR15, offset, 3);
material.setAttribute('offset', SEMANTIC_ATTR15);
```

### update

```ts
update(): void
```

## Inherited from [Material](https://api.playcanvas.com/engine/classes/Material.md)

- `alphaToCoverage: boolean = false`
- `cull: number = CULLFACE_BACK`
- `frontFace: number = FRONTFACE_CCW`
- `name: string = 'Untitled'`
- `stencilBack: StencilParameters | null = null`
- `stencilFront: StencilParameters | null = null`
- `userId: string = ''`
- `get alphaWrite(): boolean` · `set alphaWrite(value: boolean)`
- `get blendState(): Readonly<BlendState>` · `set blendState(value: Readonly<BlendState>)`
- `get blendType(): number` · `set blendType(type: number)`
- `get blueWrite(): boolean` · `set blueWrite(value: boolean)`
- `get depthBias(): number` · `set depthBias(value: number)`
- `get depthFunc(): number` · `set depthFunc(value: number)`
- `get depthState(): DepthState` · `set depthState(value: DepthState)`
- `get depthTest(): boolean` · `set depthTest(value: boolean)`
- `get depthWrite(): boolean` · `set depthWrite(value: boolean)`
- `get flatShading(): boolean` · `set flatShading(value: boolean)`
- `get greenWrite(): boolean` · `set greenWrite(value: boolean)`
- `get redWrite(): boolean` · `set redWrite(value: boolean)`
- `get shaderChunksVersion(): string` · `set shaderChunksVersion(value: string)`
- `get slopeDepthBias(): number` · `set slopeDepthBias(value: number)`
- `protected _markLayoutDirty(): void`
- `protected _markPropertyModified(property: MaterialProperty): void`
- `protected _markPropertyMutable(property: MaterialProperty, value: any): void`
- `clone(): StandardMaterial`
- `deleteParameter(name: string): void`
- `getDefine(name: string): boolean`
- `getParameter(name: string): any`
- `getShaderChunks(shaderLanguage?: string): ShaderChunkMap`
- `setDefine(name: string, value: string | boolean | undefined): void`
- `setParameter(name: string, data: number | number[] | ArrayBufferView<ArrayBufferLike> | Texture | StorageBuffer): void`