Mirror Engine API / Material
Class: Material
A material determines how a particular mesh instance is rendered. It specifies the shader and render state that is set before the mesh instance is submitted to the graphics device.
Extended by
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).
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.
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.
name
name: string = 'Untitled'
The name of the material.
stencilBack
stencilBack: null | StencilParameters = null;
Stencil parameters for back faces (default is null).
stencilFront
stencilFront: null | StencilParameters = null;
Stencil parameters for front faces (default is null).
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.
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
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
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
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
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
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
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
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
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
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
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
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
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
Methods
clone()
clone(): Material
Clone a material.
Returns
A newly cloned material.
copy()
copy(source: Material): Material
Copy a material.
Parameters
source
The material to copy.
Returns
The destination material.
deleteParameter()
deleteParameter(name: string): void
Deletes a shader parameter on a material.
Parameters
name
string
The name of the parameter to delete.
Returns
void
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
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.
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.
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
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
update()
update(): void
Applies any changes made to the material's properties.
Returns
void