Documentation

Class: BasicMaterial

BasicMaterial

BasicMaterial is the default physically plausible rendering material.

new BasicMaterial(options)

Parameters:
Name Type Description
options

An object with key/value pairs describing the initial values of the material.

  • color: Color or hexcode Number
  • doubleSided: Boolean
  • colorMap: Texture2D
  • normalMap: Texture2D
  • specularMap: Texture2D
  • maskMap: Texture2D
  • translucencyMap: Texture2D
  • occlusionMap: Texture2D
  • specularMapMode: BasicMaterial#SPECULAR_MAP_ROUGHNESS_ONLY
  • metallicness: Number
  • translucency: Color
  • alpha: Number
  • roughness: Number
  • roughnessRange: Number
  • normalSpecularReflectance: Number
  • alphaThreshold: Number
  • useVertexColors: Boolean
  • lightingModel: LightingModel
Properties:
Name Type Description
doubleSided boolean

Defines whether the material is double sided (no back-face culling) or not. An easier-to-read alternative to Material#cullMode
alpha number

The overall transparency of the object. Has no effect without a matching blendState value.
useVertexColors boolean

Defines whether the material should use the hx_vertexColor attribute. Only available for meshes that have this attribute.
billboardMode number

Defines whether or not the material renders the geometry aligned to the camera.
color Color

The base color of the material. Multiplied with the colorMap if provided.
emissiveColor Color

The emission color of the material. Multiplied with the emissionMap if provided.
colorMap Texture2D

A Texture2D object containing color data.
normalMap Texture2D

A Texture2D object containing surface normals.
occlusionMap Texture2D

A Texture2D object containing baked ambient occlusion.
emissionMap Texture2D

A Texture2D object containing color emission.
specularMap Texture2D

A texture containing specular reflection data. The contents of the map depend on BasicMaterial#specularMapMode. The roughness in the specular map is encoded as shininess; ie: lower values result in higher roughness to reflect the apparent brighness of the reflection. This is visually more intuitive.
translucencyMap Texture2D

A texture containing translucency data
maskMap Texture2D

A Texture2D object containing transparency data. Requires a matching blendState.
colorMapScale Float2

A Float2 with which the uv coordinates are scaled.
colorMapOffset Float2

A Float2 with which the uv coordinates are offset.
normalMapScale Float2

A Float2 with which the uv coordinates are scaled.
normalMapOffset Float2

A Float2 with which the uv coordinates are offset.
specularMapScale Float2

A Float2 with which the uv coordinates are scaled.
specularMapOffset Float2

A Float2 with which the uv coordinates are offset.
emissionMapScale Float2

A Float2 with which the uv coordinates are scaled.
emissionMapOffset Float2

A Float2 with which the uv coordinates are offset.
translucencyMapScale Float2

A Float2 with which the uv coordinates are scaled.
translucencyMapOffset Float2

A Float2 with which the uv coordinates are offset.
maskMapScale Float2

A Float2 with which the uv coordinates are scaled.
maskMapOffset Float2

A Float2 with which the uv coordinates are offset.
specularMapMode number

Defines the contents of the specular map. One of the following:

  • BasicMaterial#SPECULAR_MAP_ROUGHNESS_ONLY
  • BasicMaterial#SPECULAR_MAP_ALL
  • BasicMaterial#SPECULAR_MAP_SHARE_NORMAL_MAP
  • BasicMaterial#SPECULAR_MAP_METALLIC_ROUGHNESS
metallicness number

A value describing the overall "metallicness" of an object. Normally 0 or 1, but it can be used for some hybrid materials.
normalSpecularReflectance number

The amount of light reflecting off a surface at 90 degrees (ie: the minimum reflectance in the Fresnel equation according to Schlick's approximation). This is generally 0.027 for most materials.
roughness number

The microfacet roughness of the material. Higher values will result in dimmer but larger highlights.
roughnessRange number

Represents the range at which the roughness map operates. When using a roughness texture, roughness represents the middle roughness, range the deviation from there. So textured roughness ranges from [roughness - roughnessRange, roughness + roughnessRange]
alphaThreshold number

The alpha threshold that prevents pixels with opacity below this from being rendered. This is not recommended on certain mobile platforms due to depth buffer hierarchy performance.
translucency Color

The translucency color for the material. This causes lighting from the back to come through.
Author:
  • derschmale <http://www.derschmale.com>

Extends

Members

<static> BILLBOARD

Used for billboardMode to specify the geometry should be aligned to the camera, but the Z axis still aligns to the world up axis.

<static> MESH

Used for billboardMode to specify the material should render as a default Mesh.

<static> SPECULAR_MAP_ALL

Used for specularMapMode to specify the specular map has rgb channels containing roughness, normal reflectance and metallicness, respectively

<static> SPECULAR_MAP_METALLIC_ROUGHNESS

Used for specularMapMode to specify the specular map has gb channels containing metallicness and roughness. This is the glTF standard.

<static> SPECULAR_MAP_ROUGHNESS_ONLY

Used for specularMapMode to specify the specular map only uses roughness data

<static> SPECULAR_MAP_SHARE_NORMAL_MAP

Used for specularMapMode to specify there is no explicit specular map, but roughness data is present in the alpha channel of the normal map.

<static> SPRITE

Used for billboardMode to specify the geometry should be aligned to the camera completely.

blendState

The blend state used for this material.

Inherited From:
See:

cullMode

Defines how back-face culling is applied. One of CullMode.

Inherited From:

debugMode

Allows setting the output to something different than the lit material, such as normals.

Inherited From:

fixedLights

Allows setting a specific set of lights to this material, avoiding having to figure out lighting dynamically. This will cause all lighting to happen in a single pass, which is generally much faster than any other option.

Inherited From:

lightingModel

The {@options LightingModel} used to light this material.

Inherited From:
Overrides:

writeColor

Defines whether or not this material should write color information. This should only be used for some special cases.

Inherited From:

writeDepth

Defines whether or not this material should write depth information.

Inherited From:

Methods

<static> roughnessFromShininess(specularPower)

Converts to roughness from a "shininess" or "gloss" property, traditionally used in Phong lighting.

Parameters:
Name Type Description
specularPower

The specular power used as the gloss parameter.

setTexture(slotName, texture)

Assigns a texture to the shaders with a given name.

Parameters:
Name Type Description
slotName string

The name of the texture as it appears in the shader code.
texture Texture2D

The texture to assign
Inherited From:

setTextureArray(slotName, texture)

Assigns a texture array to the shaders with a given name.

Parameters:
Name Type Description
slotName string

The name of the texture array as it appears in the shader code.
texture Array

An Array of Texture2D objects
Inherited From:

setUniform(name, value [, overwrite])

Sets a uniform value to the shaders.

Parameters:
Name Type Argument Description
name

The uniform name as it appears in the shader code.
value

The uniform value. For vectors, this can be a Float2, Float4, or an Array
overwrite <optional>

If the value was already set, ignore the new value. Defaults to true.
Inherited From:

setUniformArray(name, value, overwrite)

Sets the value for a uniform array to the shaders.

Parameters:
Name Type Description
name

The uniform array name as it appears in the shader code.
value

An array of values.
overwrite

(Optional) If the value was already set, ignore the new value.
Inherited From: