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
  • colorMap: Texture2D
  • doubleSided: Boolean
  • normalMap: Texture2D
  • specularMap: Texture2D
  • maskMap: Texture2D
  • specularMapMode: BasicMaterial#SPECULAR_MAP_ROUGHNESS_ONLY
  • metallicness: Number
  • 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.
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.
maskMap Texture2D

A Texture2D object containing transparency data. Requires a matching blendState.
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.
Author:
  • derschmale <http://www.derschmale.com>

Extends

Members

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

blendState

The blend state used for this material.

Inherited From:
See:

cullMode

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

Inherited From:

elementType

An ElementType to describe the type of elements to render.

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:

name

The name of the material.

Inherited From:

renderOrder

A Number that can force the order in which the material is rendered. Higher values will be rendered later!

Inherited From:

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: