Reference Source
public class | source

SpecularMaterial

Extends:

ComponentMaterial → SpecularMaterial

Configures the normal rendered appearance of Meshes using the physically-accurate specular-glossiness shading model.

  • Useful for insulators, such as wood, ceramics and plastic.
  • MetallicMaterial is best for conductive materials, such as metal.
  • PhongMaterial is appropriate for non-realistic objects.
  • LambertMaterial is appropriate for high-detail models that need to render as efficiently as possible.

Usage

In the example below we'll create a Mesh with a buildTorusGeometry and a SpecularMaterial.

Note that in this example we're providing separate Texture for the SpecularMaterial#specular and SpecularMaterial#glossiness channels, which allows us a little creative flexibility. Then, in the next example further down, we'll combine those channels within the same Texture for efficiency.

import {Viewer} from "src/viewer/Viewer.js";
import {Mesh} from "src/scene/mesh/Mesh.js";
import {buildTorusGeometry} from "src/scene/geometry/builders/buildTorusGeometry.js";
import {SpecularMaterial} from "src/scene/materials/SpecularMaterial.js";
import {Texture} from "src/scene/materials/Texture.js";

const viewer = new Viewer({ canvasId: "myCanvas" });

const myMesh = new Mesh(viewer.scene,{

     geometry: new ReadableGeometry(viewer.scene, buildTorusGeometry()),

     material: new SpecularMaterial(viewer.scene,{

         // Channels with default values, just to show them

         diffuse: [1.0, 1.0, 1.0],
         specular: [1.0, 1.0, 1.0],
         glossiness: 1.0,
         emissive: [0.0, 0.0, 0.0]
         alpha: 1.0,

         // Textures to multiply some of the channels

         diffuseMap: new Texture(viewer.scene, { // RGB components multiply by diffuse
             src: "textures/diffuse.jpg"
         }),
         specularMap: new Texture(viewer.scene, { // RGB component multiplies by specular
             src: "textures/specular.jpg"
         }),
         glossinessMap: new Texture(viewer.scene, { // R component multiplies by glossiness
             src: "textures/glossiness.jpg"
         }),
         normalMap: new Texture(viewer.scene, {
             src: "textures/normalMap.jpg"
         })
     })
});

Combining Channels Within the Same Textures

In the previous example we provided separate Texture for the SpecularMaterial#specular and SpecularMaterial#glossiness channels, but we can combine those channels into the same Texture to reduce download time, memory footprint and rendering time (and also for glTF compatibility).

Here's our SpecularMaterial again with those channels combined in the SpecularMaterial#specularGlossinessMap Texture, where the RGB component multiplies by SpecularMaterial#specular and A multiplies by SpecularMaterial#glossiness.

const myMesh = new Mesh(viewer.scene,{

     geometry: new ReadableGeometry(viewer.scene, buildTorusGeometry()),

     material: new SpecularMaterial(viewer.scene,{

         // Channels with default values, just to show them

         diffuse: [1.0, 1.0, 1.0],
         specular: [1.0, 1.0, 1.0],
         glossiness: 1.0,
         emissive: [0.0, 0.0, 0.0]
         alpha: 1.0,

         diffuseMap: new Texture(viewer.scene, {
             src: "textures/diffuse.jpg"
         }),
         specularGlossinessMap: new Texture(viewer.scene, { // RGB multiplies by specular, A by glossiness
             src: "textures/specularGlossiness.jpg"
         }),
         normalMap: new Texture(viewer.scene, {
             src: "textures/normalMap.jpg"
         })
     })
});

Although not shown in this example, we can also texture SpecularMaterial#alpha with the A component of SpecularMaterial#diffuseMap's Texture, if required.

Alpha Blending

Let's make our Mesh transparent. We'll redefine SpecularMaterial#alpha and SpecularMaterial#alphaMode, causing it to blend 50% with the background:

const myMesh = new Mesh(viewer.scene,{

     geometry: new ReadableGeometry(viewer.scene, buildTorusGeometry()),

     material: new SpecularMaterial(viewer.scene,{

         // Channels with default values, just to show them

         diffuse: [1.0, 1.0, 1.0],
         specular: [1.0, 1.0, 1.0],
         glossiness: 1.0,
         emissive: [0.0, 0.0, 0.0]
         alpha: 0.5,         // <<----------- Changed
         alphaMode: "blend", // <<----------- Added

         diffuseMap: new Texture(viewer.scene, {
             src: "textures/diffuse.jpg"
         }),
         specularGlossinessMap: new Texture(viewer.scene, { // RGB multiplies by specular, A by glossiness
             src: "textures/specularGlossiness.jpg"
         }),
         normalMap: new Texture(viewer.scene, {
             src: "textures/normalMap.jpg"
         })
     })
});

Alpha Masking

Now let's make holes in our Mesh. We'll give its SpecularMaterial an SpecularMaterial#alphaMap and configure SpecularMaterial#alpha, SpecularMaterial#alphaMode, and SpecularMaterial#alphaCutoff to treat it as an alpha mask:

const myMesh = new Mesh(viewer.scene,{

    geometry: buildTorusGeometry(viewer.scene, ReadableGeometry, {}),

     material: new SpecularMaterial(viewer.scene, {

         // Channels with default values, just to show them

         diffuse: [1.0, 1.0, 1.0],
         specular: [1.0, 1.0, 1.0],
         glossiness: 1.0,
         emissive: [0.0, 0.0, 0.0]
         alpha: 1.0,         // <<----------- Changed
         alphaMode: "mask",  // <<----------- Changed
         alphaCutoff: 0.2,   // <<----------- Added

         alphaMap: new Texture(viewer.scene, { // <<---------- Added
             src: "textures/diffuse/crossGridColorMap.jpg"
         }),
         diffuseMap: new Texture(viewer.scene, {
             src: "textures/diffuse.jpg"
         }),
         specularGlossinessMap: new Texture(viewer.scene, { // RGB multiplies by specular, A by glossiness
             src: "textures/specularGlossiness.jpg"
         }),
         normalMap: new Texture(viewer.scene, {
             src: "textures/normalMap.jpg"
         })
     })
});

Background Theory

For an introduction to physically-based rendering (PBR) concepts, try these articles:

SpecularMaterial Properties

The following table summarizes SpecularMaterial properties:

Property Type Range Default Value Space Description
SpecularMaterial#diffuse Array [0, 1] for all components [1,1,1,1] linear The RGB components of the diffuse color of the material.
SpecularMaterial#specular Array [0, 1] for all components [1,1,1,1] linear The RGB components of the specular color of the material.
SpecularMaterial#glossiness Number [0, 1] 1 linear The glossiness the material.
SpecularMaterial#specularF0 Number [0, 1] 1 linear The specularF0 of the material surface.
SpecularMaterial#emissive Array [0, 1] for all components [0,0,0] linear The RGB components of the emissive color of the material.
SpecularMaterial#alpha Number [0, 1] 1 linear The transparency of the material surface (0 fully transparent, 1 fully opaque).
SpecularMaterial#diffuseMap Texture null sRGB Texture RGB components multiplying by SpecularMaterial#diffuse. If the fourth component (A) is present, it multiplies by SpecularMaterial#alpha.
SpecularMaterial#specularMap Texture null sRGB Texture RGB components multiplying by SpecularMaterial#specular. If the fourth component (A) is present, it multiplies by SpecularMaterial#alpha.
SpecularMaterial#glossinessMap Texture null linear Texture with first component multiplying by SpecularMaterial#glossiness.
SpecularMaterial#specularGlossinessMap Texture null linear Texture with first three components multiplying by SpecularMaterial#specular and fourth component multiplying by SpecularMaterial#glossiness.
SpecularMaterial#emissiveMap Texture null linear Texture with RGB components multiplying by SpecularMaterial#emissive.
SpecularMaterial#alphaMap Texture null linear Texture with first component multiplying by SpecularMaterial#alpha.
SpecularMaterial#occlusionMap Texture null linear Ambient occlusion texture multiplying by surface's reflected diffuse and specular light.
SpecularMaterial#normalMap Texture null linear Tangent-space normal map.
SpecularMaterial#alphaMode String "opaque", "blend", "mask" "blend" Alpha blend mode.
SpecularMaterial#alphaCutoff Number [0..1] 0.5 Alpha cutoff value.
SpecularMaterial#backfaces Boolean false Whether to render Geometry backfaces.
SpecularMaterial#frontface String "ccw", "cw" "ccw" The winding order for Geometry frontfaces - "cw" for clockwise, or "ccw" for counter-clockwise.

Constructor Summary

Public Constructor
public

constructor(owner: Component, cfg: *)

Member Summary

Public Members
public get

Gets the factor in the range [0..1] indicating how transparent this SpecularMaterial is.

public set

Sets the factor in the range [0..1] indicating how transparent this SpecularMaterial is.

public get

Gets the alpha cutoff value.

public set

Sets the alpha cutoff value.

public get

Gets the RGB Texture with alpha in its R component.

public get
public set

Sets the alpha rendering mode.

public get

Gets whether backfaces are visible on attached Meshes.

public set

Sets whether backfaces are visible on attached Meshes.

public get

Gets the RGB diffuse color of this SpecularMaterial.

public set

Sets the RGB diffuse color of this SpecularMaterial.

public get

Gets the RGB Texture containing the diffuse color of this SpecularMaterial, with optional A component for alpha.

public set

Sets the RGB emissive color of this SpecularMaterial.

public get

Gets the RGB emissive color of this SpecularMaterial.

public get

Gets the RGB texture containing the emissive color of this SpecularMaterial.

public get

Gets the winding direction of front faces of Geometry of attached Meshes.

public set

Sets the winding direction of front faces of Geometry of attached Meshes.

public get

Gets the Factor in the range [0..1] indicating how glossy this SpecularMaterial is.

public set

Sets the Factor in the range [0..1] indicating how glossy this SpecularMaterial is.

public get

Gets the RGB texture containing this SpecularMaterial's glossiness in its R component.

The R component multiplies by SpecularMaterial#glossiness.

  • @type {Texture}
public set

Sets the SpecularMaterial's line width.

This is not supported by WebGL implementations based on DirectX [2019].

Default value is 1.0.

public get

Gets the SpecularMaterial's line width.

public get

Gets the RGB tangent-space normal Texture attached to this SpecularMaterial.

public get

Gets the RGB ambient occlusion Texture attached to this SpecularMaterial.

public set

Sets the SpecularMaterial's point size.

Default value is 1.0.

public get

Sets the SpecularMaterial's point size.

public set

Sets the RGB specular color of this SpecularMaterial.

public get

Gets the RGB specular color of this SpecularMaterial.

public get

Gets the factor in the range [0..1] indicating amount of specular Fresnel.

public set

Sets the factor in the range [0..1] indicating amount of specular Fresnel.

public get

Gets the RGBA texture containing this SpecularMaterial's specular color in its RGB components and glossiness in its A component.

The RGB components multiplies SpecularMaterial#specular, while the A component multiplies by SpecularMaterial#glossiness.

public get

Gets the RGB texture containing the specular color of this SpecularMaterial.

Method Summary

Public Methods
public

Destroys this SpecularMaterial.

Inherited Summary

From class Component
public get

The Component that owns the lifecycle of this Component, if any.

public

True as soon as this Component has been destroyed

public

ID of this Component, unique within the Scene.

public

meta: *

Arbitrary, user-defined metadata on this component.

public

The parent Scene that contains this Component.

public

The viewer that contains this Scene.

public

clear()

Destroys all Components that are owned by this.

public

Destroys this component.

public

error(message: String)

Logs an error for this component to the JavaScript console.

public

fire(event: String, value: Object, forget: Boolean)

Fires an event on this component.

public

Returns true if there are any subscribers to the given event on this component.

public

isType(type: *): *: Boolean

Tests if this component is of the given type, or is a subclass of the given type.

public

log(message: String)

Logs a console debugging message for this component.

public

off(subId: String)

Cancels an event subscription that was previously made with Component#on or Component#once.

public

on(event: String, callback: Function, scope: Object): String

Subscribes to an event on this component.

public

once(event: String, callback: Function, scope: Object)

Subscribes to the next occurrence of the given event, then un-subscribes as soon as the event is subIdd.

public

warn(message: String)

Logs a warning for this component to the JavaScript console.

From class Material
public

Public Constructors

public constructor(owner: Component, cfg: *) source

Override:

Material#constructor

Params:

NameTypeAttributeDescription
owner Component

Owner component. When destroyed, the owner will destroy this component as well.

cfg *
  • optional

The SpecularMaterial configuration

cfg.id String
  • optional

Optional ID, unique among all components in the parent Scene, generated automatically when omitted.

cfg.diffuse Number[]
  • optional
  • default: [1,1,1]

RGB diffuse color of this SpecularMaterial. Multiplies by the RGB components of SpecularMaterial#diffuseMap.

cfg.diffuseMap Texture
  • optional
  • default: undefined

RGBA Texture containing the diffuse color of this SpecularMaterial, with optional A component for alpha. The RGB components multiply by SpecularMaterial#diffuse, while the A component, if present, multiplies by SpecularMaterial#alpha.

cfg.specular Number
  • optional
  • default: [1,1,1]

RGB specular color of this SpecularMaterial. Multiplies by the SpecularMaterial#specularMap and the RGB components of SpecularMaterial#specularGlossinessMap.

cfg.specularMap Texture
  • optional
  • default: undefined

RGB texture containing the specular color of this SpecularMaterial. Multiplies by the SpecularMaterial#specular property. Must be within the same Scene as this SpecularMaterial.

cfg.glossiness Number
  • optional
  • default: 1.0

Factor in the range [0..1] indicating how glossy this SpecularMaterial is. 0 is no glossiness, 1 is full glossiness. Multiplies by the R component of SpecularMaterial#glossinessMap and the A component of SpecularMaterial#specularGlossinessMap.

cfg.specularGlossinessMap Texture
  • optional
  • default: undefined

RGBA Texture containing this SpecularMaterial's specular color in its RGB component and glossiness in its A component. Its RGB components multiply by SpecularMaterial#specular, while its A component multiplies by SpecularMaterial#glossiness. Must be within the same Scene as this SpecularMaterial.

cfg.specularF0 Number
  • optional
  • default: 0.0

Factor in the range 0..1 indicating how reflective this SpecularMaterial is.

cfg.emissive Number[]
  • optional
  • default: [0,0,0]

RGB emissive color of this SpecularMaterial. Multiplies by the RGB components of SpecularMaterial#emissiveMap.

cfg.emissiveMap Texture
  • optional
  • default: undefined

RGB Texture containing the emissive color of this SpecularMaterial. Multiplies by the SpecularMaterial#emissive property. Must be within the same Scene as this SpecularMaterial.

cfg.occlusionMap Texture
  • optional
  • default: undefined

RGB ambient occlusion Texture. Within shaders, multiplies by the specular and diffuse light reflected by surfaces. Must be within the same Scene as this SpecularMaterial.

cfg.normalMap Texture
  • optional
  • default: undefined

{Texture} RGB tangent-space normal Texture. Must be within the same Scene as this SpecularMaterial.

cfg.alpha Number
  • optional
  • default: 1.0

Factor in the range 0..1 indicating how transparent this SpecularMaterial is. A value of 0.0 indicates fully transparent, 1.0 is fully opaque. Multiplies by the R component of SpecularMaterial#alphaMap and the A component, if present, of SpecularMaterial#diffuseMap.

cfg.alphaMap Texture
  • optional
  • default: undefined

RGB Texture containing this SpecularMaterial's alpha in its R component. The R component multiplies by the SpecularMaterial#alpha property. Must be within the same Scene as this SpecularMaterial.

cfg.alphaMode String
  • optional
  • default: "opaque"

The alpha blend mode - accepted values are "opaque", "blend" and "mask". See the SpecularMaterial#alphaMode property for more info.

cfg.alphaCutoff Number
  • optional
  • default: 0.5

The alpha cutoff value. See the SpecularMaterial#alphaCutoff property for more info.

cfg.backfaces Boolean
  • optional
  • default: false

Whether to render Geometry backfaces.

cfg.frontface Boolean
  • optional
  • default: "ccw"

The winding order for Geometry front faces - "cw" for clockwise, or "ccw" for counter-clockwise.

cfg.lineWidth Number
  • optional
  • default: 1

Scalar that controls the width of {@link Geometry lines.

cfg.pointSize Number
  • optional
  • default: 1

Scalar that controls the size of Geometry points.

Public Members

public get alpha: Number source

Gets the factor in the range [0..1] indicating how transparent this SpecularMaterial is.

public set alpha: Number source

Sets the factor in the range [0..1] indicating how transparent this SpecularMaterial is.

A value of 0.0 is fully transparent, while 1.0 is fully opaque.

Multiplies by the R component of SpecularMaterial#alphaMap and the A component, if present, of SpecularMaterial#diffuseMap.

Default value is 1.0.

public get alphaCutoff: Number source

Gets the alpha cutoff value.

public set alphaCutoff: Number source

Sets the alpha cutoff value.

Specifies the cutoff threshold when SpecularMaterial#alphaMode equals "mask". If the alpha is greater than or equal to this value then it is rendered as fully opaque, otherwise, it is rendered as fully transparent. A value greater than 1.0 will render the entire material as fully transparent. This value is ignored for other modes.

Alpha is the combined result of the SpecularMaterial#alpha and SpecularMaterial#alphaMap properties.

Default value is 0.5.

public get alphaMap: Texture source

Gets the RGB Texture with alpha in its R component.

The R component multiplies by the SpecularMaterial#alpha property.

public get alphaMode: * source

public set alphaMode: String source

Sets the alpha rendering mode.

This governs how alpha is treated. Alpha is the combined result of the SpecularMaterial#alpha and SpecularMaterial#alphaMap properties.

Accepted values are:

  • "opaque" - The alpha value is ignored and the rendered output is fully opaque (default).
  • "mask" - The rendered output is either fully opaque or fully transparent depending on the alpha value and the specified alpha cutoff value.
  • "blend" - The alpha value is used to composite the source and destination areas. The rendered output is combined with the background using the normal painting operation (i.e. the Porter and Duff over operator)

public get backfaces: Boolean source

Gets whether backfaces are visible on attached Meshes.

public set backfaces: Boolean source

Sets whether backfaces are visible on attached Meshes.

The backfaces will belong to ReadableGeometry compoents that are also attached to the Meshes.

Default is false.

public get diffuse: Number[] source

Gets the RGB diffuse color of this SpecularMaterial.

public set diffuse: Number[] source

Sets the RGB diffuse color of this SpecularMaterial.

Multiplies by the RGB components of SpecularMaterial#diffuseMap.

Default value is [1.0, 1.0, 1.0].

public get diffuseMap: Texture source

Gets the RGB Texture containing the diffuse color of this SpecularMaterial, with optional A component for alpha.

The RGB components multipliues by the SpecularMaterial#diffuse property, while the A component, if present, multiplies by the SpecularMaterial#alpha property.

public set emissive: Number[] source

Sets the RGB emissive color of this SpecularMaterial.

Multiplies by SpecularMaterial#emissiveMap.

Default value is [0.0, 0.0, 0.0].

public get emissive: Number[] source

Gets the RGB emissive color of this SpecularMaterial.

public get emissiveMap: Texture source

Gets the RGB texture containing the emissive color of this SpecularMaterial.

Multiplies by SpecularMaterial#emissive.

public get frontface: String source

Gets the winding direction of front faces of Geometry of attached Meshes.

public set frontface: String source

Sets the winding direction of front faces of Geometry of attached Meshes.

Default value is "ccw".

public get glossiness: Number source

Gets the Factor in the range [0..1] indicating how glossy this SpecularMaterial is.

public set glossiness: Number source

Sets the Factor in the range [0..1] indicating how glossy this SpecularMaterial is.

0 is no glossiness, 1 is full glossiness.

Multiplies by the R component of SpecularMaterial#glossinessMap and the A component of SpecularMaterial#specularGlossinessMap.

Default value is 1.0.

public get glossinessMap: * source

Gets the RGB texture containing this SpecularMaterial's glossiness in its R component.

The R component multiplies by SpecularMaterial#glossiness.

  • @type {Texture}

public set lineWidth: Number source

Sets the SpecularMaterial's line width.

This is not supported by WebGL implementations based on DirectX [2019].

Default value is 1.0.

public get lineWidth: Number source

Gets the SpecularMaterial's line width.

public get normalMap: Texture source

Gets the RGB tangent-space normal Texture attached to this SpecularMaterial.

public get occlusionMap: Texture source

Gets the RGB ambient occlusion Texture attached to this SpecularMaterial.

Multiplies by the specular and diffuse light reflected by surfaces.

public set pointSize: Number source

Sets the SpecularMaterial's point size.

Default value is 1.0.

public get pointSize: Number source

Sets the SpecularMaterial's point size.

public set specular: Number[] source

Sets the RGB specular color of this SpecularMaterial.

Multiplies by SpecularMaterial#specularMap and the A component of SpecularMaterial#specularGlossinessMap.

Default value is [1.0, 1.0, 1.0].

public get specular: Number[] source

Gets the RGB specular color of this SpecularMaterial.

public get specularF0: Number source

Gets the factor in the range [0..1] indicating amount of specular Fresnel.

public set specularF0: Number source

Sets the factor in the range [0..1] indicating amount of specular Fresnel.

Default value is 0.0.

public get specularGlossinessMap: Texture source

Gets the RGBA texture containing this SpecularMaterial's specular color in its RGB components and glossiness in its A component.

The RGB components multiplies SpecularMaterial#specular, while the A component multiplies by SpecularMaterial#glossiness.

public get specularMap: Texture source

Gets the RGB texture containing the specular color of this SpecularMaterial.

Multiplies by SpecularMaterial#specular.

Public Methods

public destroy() source

Destroys this SpecularMaterial.

Override:

Material#destroy