V5

How To

Mirror Engine API

Mirror Engine API / StandardMaterial

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

Extends

Material

Constructors

new StandardMaterial()

new StandardMaterial(): StandardMaterial

Create a new StandardMaterial instance.

Returns

StandardMaterial

Examples

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

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

Overrides

Material.constructor

Properties

alphaTest

alphaTest: number = 0

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

Inherited from

Material.alphaTest

alphaToCoverage

alphaToCoverage: boolean = false

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.

Inherited from

Material.alphaToCoverage

cull

cull: number = CULLFACE_BACK

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

Defaults to CULLFACE_BACK.

Inherited from

Material.cull

name

name: string = 'Untitled'

The name of the material.

Inherited from

Material.name

stencilBack

stencilBack: null | StencilParameters = null;

Stencil parameters for back faces (default is null).

Inherited from

Material.stencilBack

stencilFront

stencilFront: null | StencilParameters = null;

Stencil parameters for front faces (default is null).

Inherited from

Material.stencilFront

userId

userId: string = ''

A unique id the user can assign to the material. The engine internally does not use this for anything, and the user can assign a value to this id for any purpose they like. Defaults to an empty string.

Inherited from

Material.userId

alphaWrite

Get Signature

get alphaWrite(): boolean

Gets whether the alpha channel is written to the color buffer.

Returns

boolean

Set Signature

set alphaWrite(value: boolean): void

Sets whether the alpha channel is written to the color buffer. 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 alpha component will not be written. Defaults to true.

Parameters

value

boolean

Returns

void

Inherited from

Material.alphaWrite

blendState

Get Signature

get blendState(): BlendState

Gets the blend state for this material.

Returns

BlendState

Set Signature

set blendState(value: BlendState): void

Sets the blend state for this material. Controls how fragment shader outputs are blended when being written to the currently active render target. This overwrites blending type set using Material#blendType, and offers more control over blending.

Parameters

value

BlendState

Returns

void

Inherited from

Material.blendState

blendType

Get Signature

get blendType(): number

Gets the blend mode for this material.

Returns

number

Set Signature

set blendType(type: number): void

Sets the blend mode for this material. Controls how fragment shader outputs 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.
BLEND_MAX: Maximum color.

Defaults to BLEND_NONE.

Parameters

type

number

Returns

void

Inherited from

Material.blendType

blueWrite

Get Signature

get blueWrite(): boolean

Gets whether the blue channel is written to the color buffer.

Returns

boolean

Set Signature

set blueWrite(value: boolean): void

Sets whether the blue channel is written to the color buffer. 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 blue component will not be written. Defaults to true.

Parameters

value

boolean

Returns

void

Inherited from

Material.blueWrite

chunks

Get Signature

get chunks(): {}

Gets the object containing custom shader chunks.

Returns

{
}

Set Signature

set chunks(value: {}): void

Sets the object containing custom shader chunks that will replace default ones.

Parameters

value

Returns

void

Inherited from

Material.chunks

depthBias

Get Signature

get depthBias(): number

Gets the offset for the output depth buffer value.

Returns

number

Set Signature

set depthBias(value: number): void

Sets the offset for the output depth buffer value. Useful for decals to prevent z-fighting. Typically a small negative value (-0.1) is used to render the mesh slightly closer to the camera.

Parameters

value

number

Returns

void

Inherited from

Material.depthBias

depthFunc

Get Signature

get depthFunc(): number

Gets the depth test function.

Returns

number

Set Signature

set depthFunc(value: number): void

Sets the depth test function. 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.

Parameters

value

number

Returns

void

Inherited from

Material.depthFunc

depthState

Get Signature

get depthState(): DepthState

Gets the depth state.

Returns

DepthState

Set Signature

set depthState(value: DepthState): void

Sets the depth state. Note that this can also be done by using Material#depthTest, Material#depthFunc and Material#depthWrite.

Parameters

value

DepthState

Returns

void

Inherited from

Material.depthState

depthTest

Get Signature

get depthTest(): boolean

Gets whether depth testing is enabled.

Returns

boolean

Set Signature

set depthTest(value: boolean): void

Sets whether depth testing is enabled. 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.

Parameters

value

boolean

Returns

void

Inherited from

Material.depthTest

depthWrite

Get Signature

get depthWrite(): boolean

Gets whether depth writing is enabled.

Returns

boolean

Set Signature

set depthWrite(value: boolean): void

Sets whether depth writing is enabled. 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.

Parameters

value

boolean

Returns

void

Inherited from

Material.depthWrite

greenWrite

Get Signature

get greenWrite(): boolean

Gets whether the green channel is written to the color buffer.

Returns

boolean

Set Signature

set greenWrite(value: boolean): void

Sets whether the green channel is written to the color buffer. 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 green component will not be written. Defaults to true.

Parameters

value

boolean

Returns

void

Inherited from

Material.greenWrite

redWrite

Get Signature

get redWrite(): boolean

Gets whether the red channel is written to the color buffer.

Returns

boolean

Set Signature

set redWrite(value: boolean): void

Sets whether the red channel is written to the color buffer. 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.

Parameters

value

boolean

Returns

void

Inherited from

Material.redWrite

slopeDepthBias

Get Signature

get slopeDepthBias(): number

Gets the offset for the output depth buffer value based on the slope of the triangle relative to the camera.

Returns

number

Set Signature

set slopeDepthBias(value: number): void

Sets the offset for the output depth buffer value based on the slope of the triangle relative to the camera.

Parameters

value

number

Returns

void

Inherited from

Material.slopeDepthBias

Methods

clone()

clone(): StandardMaterial

Clone a material.

Returns

StandardMaterial

A newly cloned material.

Inherited from

Material.clone

copy()

copy(source: StandardMaterial): StandardMaterial

Copy a StandardMaterial.

Parameters

source

StandardMaterial

The material to copy from.

Returns

StandardMaterial

The destination material.

Overrides

Material.copy

deleteParameter()

deleteParameter(name: string): void

Deletes a shader parameter on a material.

Parameters

name

string

The name of the parameter to delete.

Returns

void

Inherited from

Material.deleteParameter

destroy()

destroy(): void

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

Returns

void

Overrides

Material.destroy

getDefine()

getDefine(name: string): boolean

Returns true if a define is enabled on the material, otherwise false.

Parameters

name

string

The name of the define to check.

Returns

boolean

The value of the define.

Inherited from

Material.getDefine

getParameter()

getParameter(name: string): any

Retrieves the specified shader parameter from a material.

Parameters

name

string

The name of the parameter to query.

Returns

any

The named parameter.

Inherited from

Material.getParameter

setAttribute()

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.

Returns

void

Example

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

setDefine()

setDefine(name: string, value: undefined | string | false): void

Adds or removes a define on the material. Defines can be used to enable or disable various parts of the shader code.

Parameters

name

string

The name of the define to set.

value

The value of the define. If undefined or false, the define is removed.

undefined | string | false

Returns

void

Inherited from

Material.setDefine

setParameter()

setParameter(name: string, data:
  | number
  | number[]
  | Float32Array<ArrayBufferLike>
  | Texture): void

Sets a shader parameter on a material.

Parameters

name

string

The name of the parameter to set.

data

The value for the specified parameter.

number | number[] | Float32Array<ArrayBufferLike> | Texture

Returns

void

Inherited from

Material.setParameter

update()

update(): void

Applies any changes made to the material's properties.

Returns

void

Inherited from

Material.update