Class BasicMaterial

A BasicMaterial is for rendering unlit geometry, either using a constant color or a color map modulated with a color.

// Create a new Basic material
const material = new pc.BasicMaterial();

// Set the material to have a texture map that is multiplied by a red color
material.color.set(1, 0, 0);
material.colorMap = diffuseMap;

// Notify the material that it has been modified
material.update();

Hierarchy (view full)

Material
- BasicMaterial

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.

color

color: Color = ...

The flat color of the material (RGBA, where each component is 0 to 1).

colorMap

colorMap: Texture = null

The color map of the material (default is null). If specified, the color map is modulated by the color property.

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: StencilParameters = null

Stencil parameters for back faces (default is null).

stencilFront

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

Accessors

alphaWrite

get alphaWrite(): boolean
Returns boolean
Inherited from Material.alphaWrite
- Defined in engine/src/scene/materials/material.js:241
set alphaWrite(value): void
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.
Parameters
- value: boolean
Returns void
Inherited from Material.alphaWrite
- Defined in engine/src/scene/materials/material.js:237

blendState

get blendState(): BlendState
Returns BlendState
Inherited from Material.blendState
- Defined in engine/src/scene/materials/material.js:283
set blendState(value): void
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
- Defined in engine/src/scene/materials/material.js:278

blendType

get blendType(): number
Returns number
Inherited from Material.blendType
- Defined in engine/src/scene/materials/material.js:329
set blendType(type): void
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.
Parameters
- type: number
Returns void
Inherited from Material.blendType
- Defined in engine/src/scene/materials/material.js:314

blueWrite

get blueWrite(): boolean
Returns boolean
Inherited from Material.blueWrite
- Defined in engine/src/scene/materials/material.js:226
set blueWrite(value): void
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.
Parameters
- value: boolean
Returns void
Inherited from Material.blueWrite
- Defined in engine/src/scene/materials/material.js:222

depthBias

get depthBias(): number
Returns number
Inherited from Material.depthBias
- Defined in engine/src/scene/materials/material.js:161
set depthBias(value): void
Offsets 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
- Defined in engine/src/scene/materials/material.js:157

depthFunc

get depthFunc(): number
Returns number
Inherited from Material.depthFunc
- Defined in engine/src/scene/materials/material.js:398
set depthFunc(value): void
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
- Defined in engine/src/scene/materials/material.js:394

depthState

get depthState(): DepthState
Returns DepthState
Inherited from Material.depthState
- Defined in engine/src/scene/materials/material.js:357
set depthState(value): 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
- Defined in engine/src/scene/materials/material.js:353

depthTest

get depthTest(): boolean
Returns boolean
Inherited from Material.depthTest
- Defined in engine/src/scene/materials/material.js:373
set depthTest(value): void
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
- Defined in engine/src/scene/materials/material.js:369

depthWrite

get depthWrite(): boolean
Returns boolean
Inherited from Material.depthWrite
- Defined in engine/src/scene/materials/material.js:413
set depthWrite(value): void
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
- Defined in engine/src/scene/materials/material.js:409

greenWrite

get greenWrite(): boolean
Returns boolean
Inherited from Material.greenWrite
- Defined in engine/src/scene/materials/material.js:211
set greenWrite(value): void
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.
Parameters
- value: boolean
Returns void
Inherited from Material.greenWrite
- Defined in engine/src/scene/materials/material.js:207

redWrite

get redWrite(): boolean
Returns boolean
Inherited from Material.redWrite
- Defined in engine/src/scene/materials/material.js:196
set redWrite(value): void
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
- Defined in engine/src/scene/materials/material.js:192

shader

get shader(): Shader
Returns Shader
Inherited from Material.shader
- Defined in engine/src/scene/materials/material.js:254
set shader(shader): void
The shader used by this material to render mesh instances (default is null).
Parameters
- shader: Shader
Returns void
Inherited from Material.shader
- Defined in engine/src/scene/materials/material.js:250

slopeDepthBias

get slopeDepthBias(): number
Returns number
Inherited from Material.slopeDepthBias
- Defined in engine/src/scene/materials/material.js:175
set slopeDepthBias(value): void
Same as Material#depthBias, but also depends on the slope of the triangle relative to the camera.
Parameters
- value: number
Returns void
Inherited from Material.slopeDepthBias
- Defined in engine/src/scene/materials/material.js:171

transparent

get transparent(): boolean
Returns boolean
Inherited from Material.transparent
- Defined in engine/src/scene/materials/material.js:259

Methods

clone

clone(): BasicMaterial
Clone a material.

Returns BasicMaterial
A newly cloned material.
Inherited from Material.clone
- Defined in engine/src/scene/materials/material.js:449

copy

copy(source): BasicMaterial
Copy a BasicMaterial.
Parameters
- source: BasicMaterial
  The material to copy from.
Returns BasicMaterial
The destination material.
Overrides Material.copy
- Defined in engine/src/scene/materials/basic-material.js:59

deleteParameter

deleteParameter(name): void
Deletes a shader parameter on a material.
Parameters
- name: string
  The name of the parameter to delete.
Returns void
Inherited from Material.deleteParameter
- Defined in engine/src/scene/materials/material.js:549

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
Inherited from Material.destroy
- Defined in engine/src/scene/materials/material.js:575

getParameter

getParameter(name): object
Retrieves the specified shader parameter from a material.
Parameters
- name: string
  The name of the parameter to query.
Returns object
The named parameter.
Inherited from Material.getParameter
- Defined in engine/src/scene/materials/material.js:508

setParameter

setParameter(name, data): void
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.
Returns void
Inherited from Material.setParameter
- Defined in engine/src/scene/materials/material.js:519

update

update(): void
Applies any changes made to the material's properties.

Returns void
Inherited from Material.update
- Defined in engine/src/scene/materials/material.js:475

Class BasicMaterial

Hierarchy (view full)

Index

Properties

Accessors

Methods

Properties

alphaTest

alphaToCoverage

color

colorMap

cull

name

stencilBack

stencilFront

userId

Accessors

alphaWrite

Returns boolean

Parameters

Returns void

blendState

Returns BlendState

Parameters

Returns void

blendType

Returns number

Parameters

Returns void

blueWrite

Returns boolean

Parameters

Returns void

depthBias

Returns number

Parameters

Returns void

depthFunc

Returns number

Parameters

Returns void

depthState

Returns DepthState

Parameters

Returns void

depthTest

Returns boolean

Parameters

Returns void

depthWrite

Returns boolean

Parameters

Returns void

greenWrite

Returns boolean

Parameters

Returns void

redWrite

Returns boolean

Parameters

Returns void

shader

Returns Shader

Parameters

Returns void

slopeDepthBias

Returns number

Parameters

Returns void

transparent

Returns boolean

Methods

clone

Returns BasicMaterial

copy

Parameters

Returns BasicMaterial

deleteParameter

Parameters

Returns void