Reference Source
public class | source

MetallicMaterial

Extends:

ComponentMaterial → MetallicMaterial

Configures the normal rendered appearance of Meshes using the physically-accurate metallic-roughness shading model.

  • Useful for conductive materials, such as metal, but also appropriate for insulators.
  • SpecularMaterial is best for insulators, such as wood, ceramics and plastic.
  • 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 MetallicMaterial and ReadableGeometry loaded from OBJ.

Note that in this example we're providing separate Texture for the MetallicMaterial#metallic and MetallicMaterial#roughness 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.

[Run this example]

import {Viewer, Mesh, loadOBJGeometry, ReadableGeometry, MetallicMaterial, Texture} from "xeokit-sdk.es.js";

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

viewer.scene.camera.eye = [0.57, 1.37, 1.14];
viewer.scene.camera.look = [0.04, 0.58, 0.00];
viewer.scene.camera.up = [-0.22, 0.84, -0.48];

loadOBJGeometry(viewer.scene, {
     src: "models/obj/fireHydrant/FireHydrantMesh.obj"
})
.then(function (geometry) {

     // Success

     new Mesh(viewer.scene, {

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

         material: new MetallicMaterial(viewer.scene, {

             baseColor: [1, 1, 1],
             metallic: 1.0,
             roughness: 1.0,

             baseColorMap: new Texture(viewer.scene, {
                 src: "models/obj/fireHydrant/fire_hydrant_Base_Color.png",
                 encoding: "sRGB"
             }),
             normalMap: new Texture(viewer.scene, {
                 src: "models/obj/fireHydrant/fire_hydrant_Normal_OpenGL.png"
             }),
             roughnessMap: new Texture(viewer.scene, {
                 src: "models/obj/fireHydrant/fire_hydrant_Roughness.png"
             }),
             metallicMap: new Texture(viewer.scene, {
                 src: "models/obj/fireHydrant/fire_hydrant_Metallic.png"
             }),
             occlusionMap: new Texture(viewer.scene, {
                 src: "models/obj/fireHydrant/fire_hydrant_Mixed_AO.png"
             }),

             specularF0: 0.7
         })
     });
}, function () {
         // Error
     });

Background Theory

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

MetallicMaterial Properties

The following table summarizes MetallicMaterial properties:

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

Combining Channels Within the Same Textures

In the previous example we provided separate Texture for the MetallicMaterial#metallic and MetallicMaterial#roughness 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 the Mesh again, with our MetallicMaterial with those channels combined in the MetallicMaterial#metallicRoughnessMap Texture, where the R component multiplies by MetallicMaterial#metallic and G multiplies by MetallicMaterial#roughness.

new Mesh(viewer.scene, {

    geometry: geometry,

    material: new MetallicMaterial(viewer.scene, {

        baseColor: [1, 1, 1],
        metallic: 1.0,
        roughness: 1.0,

        baseColorMap: new Texture(viewer.scene, {
            src: "models/obj/fireHydrant/fire_hydrant_Base_Color.png",
            encoding: "sRGB"
        }),
        normalMap: new Texture(viewer.scene, {
            src: "models/obj/fireHydrant/fire_hydrant_Normal_OpenGL.png"
        }),
        metallicRoughnessMap: new Texture(viewer.scene, {
            src: "models/obj/fireHydrant/fire_hydrant_MetallicRoughness.png"
        }),
        metallicRoughnessMap : new Texture(viewer.scene, {                  // <<----------- Added
            src: "models/obj/fireHydrant/fire_hydrant_MetallicRoughness.png"  // R component multiplies by metallic
        }),                                                                   // G component multiplies by roughness
        occlusionMap: new Texture(viewer.scene, {
            src: "models/obj/fireHydrant/fire_hydrant_Mixed_AO.png"
        }),

        specularF0: 0.7
 })

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

Alpha Blending

Let's make our Mesh transparent.

We'll update the MetallicMaterial#alpha and MetallicMaterial#alphaMode, causing it to blend 50% with the background:

hydrant.material.alpha = 0.5;
hydrant.material.alphaMode = "blend";

Alpha Masking

Let's apply an alpha mask to our Mesh.

We'll configure an MetallicMaterial#alphaMap to multiply by MetallicMaterial#alpha, with MetallicMaterial#alphaMode and MetallicMaterial#alphaCutoff to treat it as an alpha mask:

new Mesh(viewer.scene, {

    geometry: geometry,

    material: new MetallicMaterial(viewer.scene, {

        baseColor: [1, 1, 1],
        metallic: 1.0,
        roughness: 1.0,
        alpha: 1.0,
        alphaMode : "mask",  // <<---------------- Added
        alphaCutoff : 0.2,   // <<---------------- Added

        alphaMap : new Texture(viewer.scene{ // <<---------------- Added
             src: "textures/alphaMap.jpg"
        }),
        baseColorMap: new Texture(viewer.scene, {
            src: "models/obj/fireHydrant/fire_hydrant_Base_Color.png",
            encoding: "sRGB"
        }),
        normalMap: new Texture(viewer.scene, {
            src: "models/obj/fireHydrant/fire_hydrant_Normal_OpenGL.png"
        }),
        metallicRoughnessMap: new Texture(viewer.scene, {
            src: "models/obj/fireHydrant/fire_hydrant_MetallicRoughness.png"
        }),
        metallicRoughnessMap : new Texture(viewer.scene, {                  // <<----------- Added
            src: "models/obj/fireHydrant/fire_hydrant_MetallicRoughness.png"  // R component multiplies by metallic
        }),                                                                   // G component multiplies by roughness
        occlusionMap: new Texture(viewer.scene, {
            src: "models/obj/fireHydrant/fire_hydrant_Mixed_AO.png"
        }),

        specularF0: 0.7
 })

Constructor Summary

Public Constructor
public

constructor(owner: Component, cfg: *)

Member Summary

Public Members
public set

Sets factor in the range [0..1] that indicates the alpha value.

public get

Gets factor in the range [0..1] that indicates the alpha value.

public set

Sets the alpha cutoff value.

public get

Gets the alpha cutoff value.

public get

Gets the RGB Texture containing this MetallicMaterial's alpha in its R component.

The R component multiplies by the MetallicMaterial#alpha property.

public set

Sets the alpha rendering mode.

public get

Gets the alpha rendering mode.

public set

Sets whether backfaces are visible on attached Meshes.

public get

Gets whether backfaces are visible on attached Meshes.

public set

Sets the RGB diffuse color.

public get

Gets the RGB diffuse color.

public get

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

public set

Sets the RGB emissive color.

public get

Gets the RGB emissive color.

public get

Gets the RGB emissive map.

public set

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

public get

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

public set

Sets the MetallicMaterial's line width.

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

Default value is 1.0.

public get

Gets the MetallicMaterial's line width.

public set

Sets the metallic factor.

public get

Gets the metallic factor.

public get

Gets the RGB Texture containing this MetallicMaterial's metallic factor in its R component.

The R component multiplies by MetallicMaterial#metallic.

public get

Gets the RGB Texture containing this MetallicMaterial's metalness in its R component and roughness in its G component.

Its B component multiplies by the MetallicMaterial#metallic property, while its G component multiplies by the MetallicMaterial#roughness property.

public get

Gets the RGB tangent-space normal map Texture.

public get

Gets the RGB ambient occlusion map.

public set

Sets the MetallicMaterial's point size.

Default value is 1.0.

public get

Gets the MetallicMaterial's point size.

public set

Sets the roughness factor.

public get

Gets the roughness factor.

public get

Gets the RGB Texture containing this MetallicMaterial's roughness factor in its R component.

The R component multiplies by MetallicMaterial#roughness.

public set

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

public get

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

Method Summary

Public Methods
public

Destroys this MetallicMaterial.

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

scheduleTask(task: *)

Schedule a task to perform on the next browser interval

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 MetallicMaterial as well.

cfg *
  • optional

The MetallicMaterial configuration.

cfg.id String
  • optional

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

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

RGB diffuse color of this MetallicMaterial. Multiplies by the RGB components of MetallicMaterial#baseColorMap.

cfg.metallic Number
  • optional
  • default: 1.0

Factor in the range [0..1] indicating how metallic this MetallicMaterial is. 1 is metal, 0 is non-metal. Multiplies by the R component of MetallicMaterial#metallicMap and the A component of MetallicMaterial#metallicRoughnessMap.

cfg.roughness Number
  • optional
  • default: 1.0

Factor in the range [0..1] indicating the roughness of this MetallicMaterial. 0 is fully smooth, 1 is fully rough. Multiplies by the R component of MetallicMaterial#roughnessMap.

cfg.specularF0 Number
  • optional
  • default: 0.0

Factor in the range [0..1] indicating specular Fresnel.

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

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

cfg.alpha Number
  • optional
  • default: 1.0

Factor in the range [0..1] indicating the alpha of this MetallicMaterial. Multiplies by the R component of MetallicMaterial#alphaMap and the A component, if present, of MetallicMaterial#baseColorMap. The value of MetallicMaterial#alphaMode indicates how alpha is interpreted when rendering.

cfg.baseColorMap Texture
  • optional
  • default: undefined

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

cfg.alphaMap Texture
  • optional
  • default: undefined

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

cfg.metallicMap Texture
  • optional
  • default: undefined

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

cfg.roughnessMap Texture
  • optional
  • default: undefined

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

cfg.metallicRoughnessMap Texture
  • optional
  • default: undefined

RGB Texture containing this MetallicMaterial's metalness in its R component and roughness in its G component. Its R component multiplies by the MetallicMaterial#metallic property, while its G component multiplies by the MetallicMaterial#roughness property. Must be within the same Scene as this MetallicMaterial.

cfg.emissiveMap Texture
  • optional
  • default: undefined

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

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

cfg.normalMap Texture
  • optional
  • default: undefined

RGB tangent-space normal Texture. Must be within the same Scene as this MetallicMaterial.

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

The alpha blend mode, which specifies how alpha is to be interpreted. Accepted values are "opaque", "blend" and "mask". See the MetallicMaterial#alphaMode property for more info.

cfg.alphaCutoff Number
  • optional
  • default: 0.5

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

cfg.backfaces Boolean
  • optional
  • default: false

Whether to render ReadableGeometry backfaces.

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

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

cfg.lineWidth Number
  • optional
  • default: 1

Scalar that controls the width of lines for ReadableGeometry with ReadableGeometry#primitive set to "lines".

cfg.pointSize Number
  • optional
  • default: 1

Scalar that controls the size of points for ReadableGeometry with ReadableGeometry#primitive set to "points".

Public Members

public set alpha: Number source

Sets factor in the range [0..1] that indicates the alpha value.

Multiplies by the R component of MetallicMaterial#alphaMap and the A component, if present, of MetallicMaterial#baseColorMap.

The value of MetallicMaterial#alphaMode indicates how alpha is interpreted when rendering.

Default value is 1.0.

public get alpha: Number source

Gets factor in the range [0..1] that indicates the alpha value.

public set alphaCutoff: Number source

Sets the alpha cutoff value.

Specifies the cutoff threshold when MetallicMaterial#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 MetallicMaterial#alpha and MetallicMaterial#alphaMap properties.

Default value is 0.5.

public get alphaCutoff: Number source

Gets the alpha cutoff value.

public get alphaMap: Texture source

Gets the RGB Texture containing this MetallicMaterial's alpha in its R component.

The R component multiplies by the MetallicMaterial#alpha property.

public set alphaMode: String source

Sets the alpha rendering mode.

This specifies how alpha is interpreted. Alpha is the combined result of the MetallicMaterial#alpha and MetallicMaterial#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 and MetallicMaterial#alphaCutoff.
  • "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 alphaMode: String source

Gets the alpha rendering mode.

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 backfaces: Boolean source

Gets whether backfaces are visible on attached Meshes.

public set baseColor: Number[] source

Sets the RGB diffuse color.

Multiplies by the RGB components of MetallicMaterial#baseColorMap.

Default value is [1.0, 1.0, 1.0].

public get baseColor: Number[] source

Gets the RGB diffuse color.

Multiplies by the RGB components of MetallicMaterial#baseColorMap.

Default value is [1.0, 1.0, 1.0].

public get baseColorMap: Texture source

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

The RGB components multiply by MetallicMaterial#baseColor, while the A component, if present, multiplies by MetallicMaterial#alpha.

public set emissive: Number[] source

Sets the RGB emissive color.

Multiplies by MetallicMaterial#emissiveMap.

Default value is [0.0, 0.0, 0.0].

public get emissive: Number[] source

Gets the RGB emissive color.

public get emissiveMap: Texture source

Gets the RGB emissive map.

Multiplies by MetallicMaterial#emissive.

public set frontface: String source

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

Default value is "ccw".

public get frontface: String source

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

public set lineWidth: Number source

Sets the MetallicMaterial'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 MetallicMaterial's line width.

public set metallic: Number source

Sets the metallic factor.

This is in the range [0..1] and indicates how metallic this MetallicMaterial is.

1 is metal, 0 is non-metal.

Multiplies by the R component of MetallicMaterial#metallicMap and the A component of MetallicMaterial#metallicRoughnessMap.

Default value is 1.0.

public get metallic: Number source

Gets the metallic factor.

public get metallicMap: Texture source

Gets the RGB Texture containing this MetallicMaterial's metallic factor in its R component.

The R component multiplies by MetallicMaterial#metallic.

public get metallicRoughnessMap: Texture source

Gets the RGB Texture containing this MetallicMaterial's metalness in its R component and roughness in its G component.

Its B component multiplies by the MetallicMaterial#metallic property, while its G component multiplies by the MetallicMaterial#roughness property.

public get normalMap: Texture source

Gets the RGB tangent-space normal map Texture.

public get occlusionMap: Texture source

Gets the RGB ambient occlusion map.

Multiplies by the specular and diffuse light reflected by surfaces.

public set pointSize: Number source

Sets the MetallicMaterial's point size.

Default value is 1.0.

public get pointSize: Number source

Gets the MetallicMaterial's point size.

public set roughness: Number source

Sets the roughness factor.

This factor is in the range [0..1], where 0 is fully smooth,1 is fully rough.

Multiplies by the R component of MetallicMaterial#roughnessMap.

Default value is 1.0.

public get roughness: Number source

Gets the roughness factor.

public get roughnessMap: Texture source

Gets the RGB Texture containing this MetallicMaterial's roughness factor in its R component.

The R component multiplies by MetallicMaterial#roughness.

public set specularF0: Number source

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

Default value is 0.0.

public get specularF0: Number source

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

Public Methods

public destroy() source

Destroys this MetallicMaterial.

Override:

Material#destroy