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.
Summary
Properties
| alphaTest | The alpha test reference value to control which fragments are written to the currently active render target based on alpha value. |
| alphaToCoverage | Enables or disables alpha to coverage (WebGL2 only). |
| alphaWrite | 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. |
| blendState | Controls how fragment shader outputs are blended when being written to the currently active render target. |
| blendType | Controls how fragment shader outputs are blended when being written to the currently active render target. |
| blueWrite | 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. |
| cull | Controls how triangles are culled based on their face direction with respect to the viewpoint. |
| depthBias | Offsets the output depth buffer value. |
| depthFunc | Controls how the depth of new fragments is compared against the current depth contained in the depth buffer. |
| depthState | Sets the depth state. |
| depthTest | If true, fragments generated by the shader of this material are only written to the current render target if they pass the depth test. |
| depthWrite | If true, fragments generated by the shader of this material write a depth value to the depth buffer of the currently active render target. |
| greenWrite | 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. |
| name | The name of the material. |
| redWrite | 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. |
| shader | The shader used by this material to render mesh instances (default is null). |
| slopeDepthBias | Same as Material#depthBias, but also depends on the slope of the triangle relative to the camera. |
| stencilBack | Stencil parameters for back faces (default is null). |
| stencilFront | Stencil parameters for front faces (default is null). |
| userId | A unique id the user can assign to the material. |
Methods
| clone | Clone a material. |
| copy | Copy a material. |
| deleteParameter | Deletes a shader parameter on a material. |
| destroy | Removes this material from the scene and possibly frees up memory from its shaders (if there are no other materials using it). |
| getParameter | Retrieves the specified shader parameter from a material. |
| setParameter | Sets a shader parameter on a material. |
| update | Applies any changes made to the material's properties. |
Details
Constructor
Material()
Properties
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).
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.
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.
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.
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. Check app.graphicsDevice.extBlendMinmax for support.
- BLEND_MAX: Maximum color. Check app.graphicsDevice.extBlendMinmax for support.
Defaults to BLEND_NONE.
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.
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.
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.
Sets the depth state. Note that this can also be done by using Material#depthTest, Material#depthFunc and Material#depthWrite.
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.
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.
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.
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.
Same as Material#depthBias, but also depends on the slope of the triangle relative to the camera.
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.
Methods
copy(source)
Copy a material.
Parameters
| source | Material | The material to copy. |
Returns
MaterialThe destination material.
deleteParameter(name)
Deletes a shader parameter on a material.
Parameters
| name | string | The name of the parameter to delete. |
destroy()
Removes this material from the scene and possibly frees up memory from its shaders (if there are no other materials using it).
getParameter(name)
Retrieves the specified shader parameter from a material.
Parameters
| name | string | The name of the parameter to query. |
Returns
objectThe named parameter.
setParameter(name, data)
Sets a shader parameter on a material.
Parameters
| name | string | The name of the parameter to set. |
| data | number, number[], Float32Array, Texture | The value for the specified parameter. |
update()
Applies any changes made to the material's properties.