/home/lindsay/xeolabs/xeogl-next/xeogl/src/materials/metallicMaterial.js

xeogl / API Docs

API Docs for:

File: /home/lindsay/xeolabs/xeogl-next/xeogl/src/materials/metallicMaterial.js

  1. /**
  2.  A **MetallicMaterial** is a physically-based {{#crossLink "Material"}}{{/crossLink}} that defines the surface appearance of
  3.  {{#crossLink "Mesh"}}Meshes{{/crossLink}} using the *metallic-roughness* workflow.
  4.  
  5.  ## Examples
  6.  
  7.  | <a href="../../examples/#importing_gltf_pbr_metallic_helmet"><img src="../../assets/images/screenshots/MetallicMaterial/helmet.png"></img></a> | <a href="../../examples/#materials_metallic_fireHydrant"><img src="../../assets/images/screenshots/MetallicMaterial/hydrant3.png"></img></a> | <a href="../../examples/#materials_metallic_samples_metals"><img src="../../assets/images/screenshots/MetallicMaterial/metals.png"></img></a> | <a href="../../examples/#materials_metallic_metallicVsRoughness"><img alt="Metallic Vs Roughness" src="../../assets/images/screenshots/MetallicMaterial/metalVsRough.png"></img></a> |
  8.  |:------:|:----:|:-----:|:-----:|
  9.  |[glTF models with PBR materials](../../examples/#importing_gltf_pbr_metallic_helmet)|[Fire hydrant model](../../examples/#materials_metallic_fireHydrant)| [Sample metal materials ](../../examples/#materials_metallic_samples_metals)|[Metallic Vs. roughness](../../examples/#materials_metallic_metallicVsRoughness)|
  10.  
  11.  ## Overview
  12.  
  13.  * MetallicMaterial is usually used for conductive materials, such as metal.
  14.  * {{#crossLink "SpecularMaterial"}}{{/crossLink}} is usually used for insulators, such as wood, ceramics and plastic.
  15.  * {{#crossLink "PhongMaterial"}}{{/crossLink}} is usually used for non-realistic objects.
  16.  
  17.  For an introduction to PBR concepts, try these articles:
  18.  
  19.  * Joe Wilson's [Basic Theory of Physically-Based Rendering](https://www.marmoset.co/posts/basic-theory-of-physically-based-rendering/)
  20.  * Jeff Russel's [Physically-based Rendering, and you can too!](https://www.marmoset.co/posts/physically-based-rendering-and-you-can-too/)
  21.  * Sebastien Legarde's [Adapting a physically-based shading model](http://seblagarde.wordpress.com/tag/physically-based-rendering/)
  22.  
  23.  The following table summarizes MetallicMaterial properties:
  24.  
  25.  | Property | Type | Range | Default Value | Space | Description |
  26.  |:--------:|:----:|:-----:|:-------------:|:-----:|:-----------:|
  27.  | {{#crossLink "MetallicMaterial/baseColor:property"}}{{/crossLink}} | Array | [0, 1] for all components | [1,1,1,1] | linear | The RGB components of the base color of the material. |
  28.  | {{#crossLink "MetallicMaterial/metallic:property"}}{{/crossLink}} | Number | [0, 1] | 1 | linear | The metallic-ness the material (1 for metals, 0 for non-metals). |
  29.  | {{#crossLink "MetallicMaterial/roughness:property"}}{{/crossLink}} | Number | [0, 1] | 1 | linear | The roughness of the material surface. |
  30.  | {{#crossLink "MetallicMaterial/specularF0:property"}}{{/crossLink}} | Number | [0, 1] | 1 | linear | The specular Fresnel of the material surface. |
  31.  | {{#crossLink "MetallicMaterial/emissive:property"}}{{/crossLink}} | Array | [0, 1] for all components | [0,0,0] | linear | The RGB components of the emissive color of the material. |
  32.  | {{#crossLink "MetallicMaterial/alpha:property"}}{{/crossLink}} | Number | [0, 1] | 1 | linear | The transparency of the material surface (0 fully transparent, 1 fully opaque). |
  33.  | {{#crossLink "MetallicMaterial/baseColorMap:property"}}{{/crossLink}} | {{#crossLink "Texture"}}{{/crossLink}} |  | null | sRGB | Texture RGB components multiplying by {{#crossLink "MetallicMaterial/baseColor:property"}}{{/crossLink}}. If the fourth component (A) is present, it multiplies by {{#crossLink "MetallicMaterial/alpha:property"}}{{/crossLink}}. |
  34.  | {{#crossLink "MetallicMaterial/metallicMap:property"}}{{/crossLink}} | {{#crossLink "Texture"}}{{/crossLink}} |  | null | linear | Texture with first component multiplying by {{#crossLink "MetallicMaterial/metallic:property"}}{{/crossLink}}. |
  35.  | {{#crossLink "MetallicMaterial/roughnessMap:property"}}{{/crossLink}} | {{#crossLink "Texture"}}{{/crossLink}} |  | null | linear | Texture with first component multiplying by {{#crossLink "MetallicMaterial/roughness:property"}}{{/crossLink}}. |
  36.  | {{#crossLink "MetallicMaterial/metallicRoughnessMap:property"}}{{/crossLink}} | {{#crossLink "Texture"}}{{/crossLink}} |  | null | linear | Texture with first component multiplying by {{#crossLink "MetallicMaterial/metallic:property"}}{{/crossLink}} and second component multiplying by {{#crossLink "MetallicMaterial/roughness:property"}}{{/crossLink}}. |
  37.  | {{#crossLink "MetallicMaterial/emissiveMap:property"}}{{/crossLink}} | {{#crossLink "Texture"}}{{/crossLink}} |  | null | linear | Texture with RGB components multiplying by {{#crossLink "MetallicMaterial/emissive:property"}}{{/crossLink}}. |
  38.  | {{#crossLink "MetallicMaterial/alphaMap:property"}}{{/crossLink}} | {{#crossLink "Texture"}}{{/crossLink}} |  | null | linear | Texture with first component multiplying by {{#crossLink "MetallicMaterial/alpha:property"}}{{/crossLink}}. |
  39.  | {{#crossLink "MetallicMaterial/occlusionMap:property"}}{{/crossLink}} | {{#crossLink "Texture"}}{{/crossLink}} |  | null | linear | Ambient occlusion texture multiplying by surface's reflected diffuse and specular light. |
  40.  | {{#crossLink "MetallicMaterial/normalMap:property"}}{{/crossLink}} | {{#crossLink "Texture"}}{{/crossLink}} |  | null | linear | Tangent-space normal map. |
  41.  | {{#crossLink "MetallicMaterial/alphaMode:property"}}{{/crossLink}} | String | "opaque", "blend", "mask" | "blend" |  | Alpha blend mode. |
  42.  | {{#crossLink "MetallicMaterial/alphaCutoff:property"}}{{/crossLink}} | Number | [0..1] | 0.5 |  | Alpha cutoff value. |
  43.  | {{#crossLink "MetallicMaterial/backfaces:property"}}{{/crossLink}} | Boolean |  | false |  | Whether to render {{#crossLink "Geometry"}}Geometry{{/crossLink}} backfaces. |
  44.  | {{#crossLink "MetallicMaterial/frontface:property"}}{{/crossLink}} | String | "ccw", "cw" | "ccw" |  | The winding order for {{#crossLink "Geometry"}}Geometry{{/crossLink}} frontfaces - "cw" for clockwise, or "ccw" for counter-clockwise. |
  45.  
  46.  ## Usage
  47.  
  48.  In the example below we'll create the [yellow fire hydrant](../../examples/#materials_metallic_fireHydrant) shown in the example screen shots above. Our hydrant {{#crossLink "Mesh"}}{{/crossLink}} has:
  49.  
  50.  * a {{#crossLink "OBJGeometry"}}{{/crossLink}} which loads the fire hydrant mesh from an .OBJ file,
  51.  * a MetallicMaterial with {{#crossLink "Texture"}}Textures{{/crossLink}} providing diffuse, metallic, roughness, occlusion and normal maps.
  52.  
  53.  We'll also provide its {{#crossLink "Scene"}}{{/crossLink}}'s {{#crossLink "Lights"}}{{/crossLink}} with
  54.  {{#crossLink "DirLight"}}DirLights{{/crossLink}}, plus {{#crossLink "CubeTexture"}}CubeTextures{{/crossLink}} for light
  55.  and reflection maps.
  56.  
  57.  Note that in this example we're providing separate {{#crossLink "Texture"}}Textures{{/crossLink}} for the {{#crossLink "MetallicMaterial/metallic:property"}}{{/crossLink}} and {{#crossLink "MetallicMaterial/roughness:property"}}{{/crossLink}}
  58.  channels, which allows us a little creative flexibility. Then, in the next example further down, we'll combine those channels
  59.  within the same {{#crossLink "Texture"}}{{/crossLink}} for efficiency.
  60.  
  61.  ````javascript
  62.  var hydrant = new xeogl.Mesh({
  63.  
  64.     geometry: new xeogl.OBJGeometry({
  65.         src: "models/obj/FireHydrantMesh.obj"
  66.     }),
  67.  
  68.     material: new xeogl.MetallicMaterial({
  69.  
  70.         // Channels with default values, just to show them
  71.  
  72.         baseColor: [1.0, 1.0, 1.0],
  73.         metallic: 1.0,
  74.         roughness: 1.0,
  75.         emissive: [0.0, 0.0, 0.0],
  76.         alpha: 1.0,
  77.  
  78.         // Textures to multiply by some of the channels
  79.  
  80.         baseColorMap : new xeogl.Texture({  // Multiplies by baseColor
  81.             src: "textures/diffuse/fire_hydrant_Base_Color.png"
  82.         }),
  83.  
  84.         metallicMap : new xeogl.Texture({   // R component multiplies by metallic
  85.             src: "textures/metallic/fire_hydrant_Metallic.png"
  86.         }),
  87.  
  88.         roughnessMap : new xeogl.Texture({  // R component multiplies by roughness
  89.             src: "textures/roughness/fire_hydrant_Roughness.png"
  90.         }),
  91.  
  92.         occlusionMap : new xeogl.Texture({  // Multiplies by fragment alpha
  93.             src: "textures/occlusion/fire_hydrant_Mixed_AO.png"
  94.         }),
  95.  
  96.         normalMap : new xeogl.Texture({
  97.             src: "textures/normal/fire_hydrant_Normal_OpenGL.png"
  98.         })
  99.     })
  100.  });
  101.  
  102.  var scene = hydrant.scene;
  103.  
  104.  scene.lights.lights = [
  105.  new xeogl.DirLight({
  106.          dir: [0.8, -0.6, -0.8],
  107.          color: [0.8, 0.8, 0.8],
  108.          space: "view"
  109.      }),
  110.  new xeogl.DirLight({
  111.          dir: [-0.8, -0.4, -0.4],
  112.          color: [0.4, 0.4, 0.5],
  113.          space: "view"
  114.      }),
  115.  new xeogl.DirLight({
  116.          dir: [0.2, -0.8, 0.8],
  117.          color: [0.8, 0.8, 0.8],
  118.          space: "view"
  119.      }
  120.  ];
  121.  
  122.  scene.lights.lightMap = new xeogl.CubeTexture({
  123.      src: [
  124.          "textures/light/Uffizi_Gallery/Uffizi_Gallery_Irradiance_PX.png",
  125.          "textures/light/Uffizi_Gallery/Uffizi_Gallery_Irradiance_NX.png",
  126.          "textures/light/Uffizi_Gallery/Uffizi_Gallery_Irradiance_PY.png",
  127.          "textures/light/Uffizi_Gallery/Uffizi_Gallery_Irradiance_NY.png",
  128.          "textures/light/Uffizi_Gallery/Uffizi_Gallery_Irradiance_PZ.png",
  129.          "textures/light/Uffizi_Gallery/Uffizi_Gallery_Irradiance_NZ.png"
  130.      ]
  131.  });
  132.  
  133.  scene.lights.reflectionMap = new xeogl.CubeTexture({
  134.      src: [
  135.          "textures/reflect/Uffizi_Gallery/Uffizi_Gallery_Radiance_PX.png",
  136.          "textures/reflect/Uffizi_Gallery/Uffizi_Gallery_Radiance_NX.png",
  137.          "textures/reflect/Uffizi_Gallery/Uffizi_Gallery_Radiance_PY.png",
  138.          "textures/reflect/Uffizi_Gallery/Uffizi_Gallery_Radiance_NY.png",
  139.          "textures/reflect/Uffizi_Gallery/Uffizi_Gallery_Radiance_PZ.png",
  140.          "textures/reflect/Uffizi_Gallery/Uffizi_Gallery_Radiance_NZ.png"
  141.      ]
  142.  });
  143.  ````
  144.  
  145.  ### Combining channels within the same textures
  146.  
  147.  In the previous example we provided separate {{#crossLink "Texture"}}Textures{{/crossLink}} for the {{#crossLink "MetallicMaterial/metallic:property"}}{{/crossLink}} and
  148.  {{#crossLink "MetallicMaterial/roughness:property"}}{{/crossLink}} channels, but we can combine those channels into the same {{#crossLink "Texture"}}{{/crossLink}} to reduce download time, memory footprint and rendering time (and also for glTF compatibility).
  149.  
  150.  Here's our MetallicMaterial again with those channels combined in the
  151.  {{#crossLink "MetallicMaterial/metallicRoughnessMap:property"}}{{/crossLink}} {{#crossLink "Texture"}}Texture{{/crossLink}}, where the
  152.  *R* component multiplies by {{#crossLink "MetallicMaterial/metallic:property"}}{{/crossLink}} and *G* multiplies by {{#crossLink "MetallicMaterial/roughness:property"}}{{/crossLink}}.
  153.  
  154.  ````javascript
  155.  hydrant.material = new xeogl.MetallicMaterial({
  156.  
  157.     baseColor: [1,1,1], // Default value
  158.     metallic: 1.0,      // Default value
  159.     roughness: 1.0,     // Default value
  160.  
  161.     baseColorMap : new xeogl.Texture({
  162.         src: "textures/diffuse/fire_hydrant_Base_Color.png"
  163.     }),
  164.     metallicRoughnessMap : new xeogl.Texture({
  165.         src: "textures/metallicRoughness/fire_hydrant_MetallicRoughness.png"
  166.     }),
  167.     occlusionMap : new xeogl.Texture({
  168.         src: "textures/occlusion/fire_hydrant_Mixed_AO.png"
  169.     }),
  170.     normalMap : new xeogl.Texture({
  171.         src: "textures/normal/fire_hydrant_Normal_OpenGL.png"
  172.     })
  173.  });
  174.  ````
  175.  
  176.  Although not shown in this example, we can also texture {{#crossLink "MetallicMaterial/alpha:property"}}{{/crossLink}} with
  177.  the *A* component of {{#crossLink "MetallicMaterial/baseColorMap:property"}}{{/crossLink}}'s {{#crossLink "Texture"}}{{/crossLink}},
  178.  if required.
  179.  
  180.  ## Transparency
  181.  
  182.  ### Alpha Blending
  183.  
  184.  Let's make our hydrant transparent.
  185.  
  186.  We'll update its MetallicMaterial's {{#crossLink "MetallicMaterial/alpha:property"}}{{/crossLink}}
  187.  and {{#crossLink "MetallicMaterial/alphaMode:property"}}{{/crossLink}}, causing it to blend 50% with the background:
  188.  
  189.  ````javascript
  190.  hydrant.material.alpha = 0.5;
  191.  hydrant.material.alphaMode = "blend";
  192.  ````
  193.  
  194.  <img src="../../../assets/images/screenshots/MetallicMaterial/alphaBlend.png"></img>
  195.  
  196.  ### Alpha Masking
  197.  
  198.  Let's apply an alpha mask to our hydrant.
  199.  
  200.  We'll give its MetallicMaterial an {{#crossLink "MetallicMaterial/alphaMap:property"}}{{/crossLink}}
  201.  and configure {{#crossLink "MetallicMaterial/alpha:property"}}{{/crossLink}}, {{#crossLink "MetallicMaterial/alphaMode:property"}}{{/crossLink}},
  202.  and {{#crossLink "MetallicMaterial/alphaCutoff:property"}}{{/crossLink}} to treat it as an alpha mask:
  203.  
  204.  ````javascript
  205.  hydrant.material.alphaMap = new xeogl.Texture({
  206.         src: "textures/diffuse/crossGridColorMap.jpg"
  207.     });
  208.  
  209.  hydrant.material.alpha = 1.0;
  210.  hydrant.material.alphaMode = "mask";
  211.  hydrant.material.alphaCutoff = 0.2;
  212.  ````
  213.  
  214.  <img src="../../../assets/images/screenshots/MetallicMaterial/alphaMask.png"></img>
  215.  
  216.  @class MetallicMaterial
  217.  @module xeogl
  218.  @submodule materials
  219.  @constructor
  220.  @extends Material
  221.  
  222.  @param [owner] {Component} Owner component. When destroyed, the owner will destroy this component as well. Creates this component within the default {{#crossLink "Scene"}}{{/crossLink}} when omitted.
  223.  
  224.  @param [cfg] {*} The MetallicMaterial configuration.
  225.  
  226.  @param [cfg.id] {String} Optional ID, unique among all components in the parent {{#crossLink "Scene"}}Scene{{/crossLink}}, generated automatically when omitted.
  227.  
  228.  @param [cfg.meta=null] {String:Object} Metadata to attach to this material.
  229.  
  230.  @param [cfg.baseColor=[1,1,1]] {Float32Array}  RGB diffuse color of this MetallicMaterial. Multiplies by the RGB
  231.  components of {{#crossLink "MetallicMaterial/baseColorMap:property"}}{{/crossLink}}.
  232.  
  233.  @param [cfg.metallic=1.0] {Number} Factor in the range 0..1 indicating how metallic this MetallicMaterial is.
  234.  1 is metal, 0 is non-metal. Multiplies by the *R* component of {{#crossLink "MetallicMaterial/metallicMap:property"}}{{/crossLink}} and the *A* component of
  235.  {{#crossLink "MetallicMaterial/metalRoughnessMap:property"}}{{/crossLink}}.
  236.  
  237.  @param [cfg.roughness=1.0] {Number} Factor in the range 0..1 indicating the roughness of this MetallicMaterial.
  238.  0 is fully smooth, 1 is fully rough. Multiplies by the *R* component of {{#crossLink "MetallicMaterial/roughnessMap:property"}}{{/crossLink}}.
  239.  
  240.  @param [cfg.specularF0=0.0] {Number} Factor in the range 0..1 indicating specular Fresnel.
  241.  
  242.  @param [cfg.emissive=[0,0,0]] {Float32Array}  RGB emissive color of this MetallicMaterial. Multiplies by the RGB
  243.  components of {{#crossLink "MetallicMaterial/emissiveMap:property"}}{{/crossLink}}.
  244.  
  245.  @param [cfg.alpha=1.0] {Number} Factor in the range 0..1 indicating the alpha of this MetallicMaterial.
  246.  Multiplies by the *R* component of {{#crossLink "MetallicMaterial/alphaMap:property"}}{{/crossLink}} and the *A* component,
  247.  if present, of {{#crossLink "MetallicMaterial/baseColorMap:property"}}{{/crossLink}}. The value of
  248.  {{#crossLink "MetallicMaterial/alphaMode:property"}}{{/crossLink}} indicates how alpha is interpreted when rendering.
  249.  
  250.  @param [cfg.baseColorMap=undefined] {Texture} RGBA {{#crossLink "Texture"}}{{/crossLink}} containing the diffuse color
  251.  of this MetallicMaterial, with optional *A* component for alpha. The RGB components multiply by the
  252.  {{#crossLink "MetallicMaterial/baseColor:property"}}{{/crossLink}} property,
  253.  while the *A* component, if present, multiplies by the {{#crossLink "MetallicMaterial/alpha:property"}}{{/crossLink}} property.
  254.  
  255.  @param [cfg.alphaMap=undefined] {Texture} RGB {{#crossLink "Texture"}}{{/crossLink}} containing this MetallicMaterial's
  256.  alpha in its *R* component. The *R* component multiplies by the {{#crossLink "MetallicMaterial/alpha:property"}}{{/crossLink}} property. Must
  257.  be within the same {{#crossLink "Scene"}}Scene{{/crossLink}} as this MetallicMaterial.
  258.  
  259.  @param [cfg.metallicMap=undefined] {Texture} RGB {{#crossLink "Texture"}}{{/crossLink}} containing this MetallicMaterial's
  260.  metallic factor in its *R* component. The *R* component multiplies by the
  261.  {{#crossLink "MetallicMaterial/metallic:property"}}{{/crossLink}} property. Must be within the same
  262.  {{#crossLink "Scene"}}Scene{{/crossLink}} as this MetallicMaterial.
  263.  
  264.  @param [cfg.roughnessMap=undefined] {Texture} RGB {{#crossLink "Texture"}}{{/crossLink}} containing this MetallicMaterial's
  265.  roughness factor in its *R* component. The *R* component multiplies by the
  266.  {{#crossLink "MetallicMaterial/roughness:property"}}{{/crossLink}} property. Must be within the same
  267.  {{#crossLink "Scene"}}Scene{{/crossLink}} as this MetallicMaterial.
  268.  
  269.  @param [cfg.metallicRoughnessMap=undefined] {Texture} RGB {{#crossLink "Texture"}}{{/crossLink}} containing this
  270.  MetallicMaterial's metalness in its *R* component and roughness in its *G* component. Its *R* component multiplies by the
  271.  {{#crossLink "MetallicMaterial/metallic:property"}}{{/crossLink}} property, while its *G* component multiplies by the
  272.  {{#crossLink "MetallicMaterial/roughness:property"}}{{/crossLink}} property. Must be within the same
  273.  {{#crossLink "Scene"}}Scene{{/crossLink}} as this MetallicMaterial.
  274.  
  275.  @param [cfg.emissiveMap=undefined] {Texture} RGB {{#crossLink "Texture"}}{{/crossLink}} containing the emissive color of this
  276.  MetallicMaterial. Multiplies by the {{#crossLink "MetallicMaterial/emissive:property"}}{{/crossLink}} property.
  277.  Must be within the same {{#crossLink "Scene"}}Scene{{/crossLink}} as this MetallicMaterial.
  278.  
  279.  @param [cfg.occlusionMap=undefined] {Texture} RGB ambient occlusion {{#crossLink "Texture"}}{{/crossLink}}. Within shaders,
  280.  multiplies by the specular and diffuse light reflected by surfaces. Must be within the same {{#crossLink "Scene"}}{{/crossLink}}
  281.  as this MetallicMaterial.
  282.  
  283.  @param [cfg.normalMap=undefined] {Texture} RGB tangent-space normal {{#crossLink "Texture"}}{{/crossLink}}. Must be
  284.  within the same {{#crossLink "Scene"}}Scene{{/crossLink}} as this MetallicMaterial.
  285.  
  286.  @param [cfg.alphaMode="opaque"] {String} The alpha blend mode, which specifies how alpha is to be interpreted. Accepted
  287.  values are "opaque", "blend" and "mask". See the {{#crossLink "MetallicMaterial/alphaMode:property"}}{{/crossLink}} property for more info.
  288.  
  289.  @param [cfg.alphaCutoff=0.5] {Number} The alpha cutoff value.
  290.  See the {{#crossLink "MetallicMaterial/alphaCutoff:property"}}{{/crossLink}} property for more info.
  291.  
  292.  @param [cfg.backfaces=false] {Boolean} Whether to render {{#crossLink "Geometry"}}Geometry{{/crossLink}} backfaces.
  293.  @param [cfg.frontface="ccw"] {Boolean} The winding order for {{#crossLink "Geometry"}}Geometry{{/crossLink}} front faces - "cw" for clockwise, or "ccw" for counter-clockwise.
  294.  
  295.  @param [cfg.lineWidth=1] {Number} Scalar that controls the width of lines for {{#crossLink "Geometry"}}{{/crossLink}} with {{#crossLink "Geometry/primitive:property"}}{{/crossLink}} set to "lines".
  296.  @param [cfg.pointSize=1] {Number} Scalar that controls the size of points for {{#crossLink "Geometry"}}{{/crossLink}} with {{#crossLink "Geometry/primitive:property"}}{{/crossLink}} set to "points".
  297.  
  298.  */
  299.  
  300. import {Material} from './material.js';
  301. import {State} from '../renderer/state.js';
  302. import {math} from '../math/math.js';
  303. import {componentClasses} from "./../componentClasses.js";
  304.  
  305. const modes = {"opaque": 0, "mask": 1, "blend": 2};
  306. const modeNames = ["opaque", "mask", "blend"];
  307. const type = "xeogl.MetallicMaterial";
  308.  
  309.  class MetallicMaterial extends Material {
  310.  
  311.     /**
  312.      JavaScript class name for this Component.
  313.  
  314.      For example: "xeogl.AmbientLight", "xeogl.MetallicMaterial" etc.
  315.  
  316.      @property type
  317.      @type String
  318.      @final
  319.      */
  320.     get type() {
  321.         return type;
  322.     }
  323.  
  324.     init(cfg) {
  325.  
  326.         super.init(cfg);
  327.  
  328.         this._state = new State({
  329.             type: "MetallicMaterial",
  330.             baseColor: math.vec4([1.0, 1.0, 1.0]),
  331.             emissive: math.vec4([0.0, 0.0, 0.0]),
  332.             metallic: null,
  333.             roughness: null,
  334.             specularF0: null,
  335.             alpha: null,
  336.             alphaMode: null, // "opaque"
  337.             alphaCutoff: null,
  338.             lineWidth: null,
  339.             pointSize: null,
  340.             backfaces: null,
  341.             frontface: null, // Boolean for speed; true == "ccw", false == "cw"
  342.             hash: null
  343.         });
  344.  
  345.         this.baseColor = cfg.baseColor;
  346.         this.metallic = cfg.metallic;
  347.         this.roughness = cfg.roughness;
  348.         this.specularF0 = cfg.specularF0;
  349.         this.emissive = cfg.emissive;
  350.         this.alpha = cfg.alpha;
  351.  
  352.         if (cfg.baseColorMap) {
  353.             this._baseColorMap = this._checkComponent("xeogl.Texture", cfg.baseColorMap);
  354.         }
  355.         if (cfg.metallicMap) {
  356.             this._metallicMap = this._checkComponent("xeogl.Texture", cfg.metallicMap);
  357.  
  358.         }
  359.         if (cfg.roughnessMap) {
  360.             this._roughnessMap = this._checkComponent("xeogl.Texture", cfg.roughnessMap);
  361.         }
  362.         if (cfg.metallicRoughnessMap) {
  363.             this._metallicRoughnessMap = this._checkComponent("xeogl.Texture", cfg.metallicRoughnessMap);
  364.         }
  365.         if (cfg.emissiveMap) {
  366.             this._emissiveMap = this._checkComponent("xeogl.Texture", cfg.emissiveMap);
  367.         }
  368.         if (cfg.occlusionMap) {
  369.             this._occlusionMap = this._checkComponent("xeogl.Texture", cfg.occlusionMap);
  370.         }
  371.         if (cfg.alphaMap) {
  372.             this._alphaMap = this._checkComponent("xeogl.Texture", cfg.alphaMap);
  373.         }
  374.         if (cfg.normalMap) {
  375.             this._normalMap = this._checkComponent("xeogl.Texture", cfg.normalMap);
  376.         }
  377.  
  378.         this.alphaMode = cfg.alphaMode;
  379.         this.alphaCutoff = cfg.alphaCutoff;
  380.         this.backfaces = cfg.backfaces;
  381.         this.frontface = cfg.frontface;
  382.         this.lineWidth = cfg.lineWidth;
  383.         this.pointSize = cfg.pointSize;
  384.  
  385.         this._makeHash();
  386.     }
  387.  
  388.     _makeHash() {
  389.         const state = this._state;
  390.         const hash = ["/met"];
  391.         if (this._baseColorMap) {
  392.             hash.push("/bm");
  393.             if (this._baseColorMap._state.hasMatrix) {
  394.                 hash.push("/mat");
  395.             }
  396.             hash.push("/" + this._baseColorMap._state.encoding);
  397.         }
  398.         if (this._metallicMap) {
  399.             hash.push("/mm");
  400.             if (this._metallicMap._state.hasMatrix) {
  401.                 hash.push("/mat");
  402.             }
  403.         }
  404.         if (this._roughnessMap) {
  405.             hash.push("/rm");
  406.             if (this._roughnessMap._state.hasMatrix) {
  407.                 hash.push("/mat");
  408.             }
  409.         }
  410.         if (this._metallicRoughnessMap) {
  411.             hash.push("/mrm");
  412.             if (this._metallicRoughnessMap._state.hasMatrix) {
  413.                 hash.push("/mat");
  414.             }
  415.         }
  416.         if (this._emissiveMap) {
  417.             hash.push("/em");
  418.             if (this._emissiveMap._state.hasMatrix) {
  419.                 hash.push("/mat");
  420.             }
  421.         }
  422.         if (this._occlusionMap) {
  423.             hash.push("/ocm");
  424.             if (this._occlusionMap._state.hasMatrix) {
  425.                 hash.push("/mat");
  426.             }
  427.         }
  428.         if (this._alphaMap) {
  429.             hash.push("/am");
  430.             if (this._alphaMap._state.hasMatrix) {
  431.                 hash.push("/mat");
  432.             }
  433.         }
  434.         if (this._normalMap) {
  435.             hash.push("/nm");
  436.             if (this._normalMap._state.hasMatrix) {
  437.                 hash.push("/mat");
  438.             }
  439.         }
  440.         hash.push(";");
  441.         state.hash = hash.join("");
  442.     }
  443.  
  444.  
  445.     /**
  446.      RGB diffuse color.
  447.  
  448.      Multiplies by the RGB components of {{#crossLink "MetallicMaterial/baseColorMap:property"}}{{/crossLink}}.
  449.  
  450.      @property baseColor
  451.      @default [1.0, 1.0, 1.0]
  452.      @type Float32Array
  453.      */
  454.     set baseColor(value) {
  455.         let baseColor = this._state.baseColor;
  456.         if (!baseColor) {
  457.             baseColor = this._state.baseColor = new Float32Array(3);
  458.         } else if (value && baseColor[0] === value[0] && baseColor[1] === value[1] && baseColor[2] === value[2]) {
  459.             return;
  460.         }
  461.         if (value) {
  462.             baseColor[0] = value[0];
  463.             baseColor[1] = value[1];
  464.             baseColor[2] = value[2];
  465.         } else {
  466.             baseColor[0] = 1;
  467.             baseColor[1] = 1;
  468.             baseColor[2] = 1;
  469.         }
  470.         this._renderer.imageDirty();
  471.     }
  472.  
  473.     get baseColor() {
  474.         return this._state.baseColor;
  475.     }
  476.  
  477.  
  478.     /**
  479.      RGB {{#crossLink "Texture"}}{{/crossLink}} containing the diffuse color of this MetallicMaterial, with optional *A* component for alpha.
  480.  
  481.      The RGB components multiply by the {{#crossLink "MetallicMaterial/baseColor:property"}}{{/crossLink}} property,
  482.      while the *A* component, if present, multiplies by the {{#crossLink "MetallicMaterial/alpha:property"}}{{/crossLink}} property.
  483.  
  484.      @property baseColorMap
  485.      @default undefined
  486.      @type {Texture}
  487.      @final
  488.      */
  489.     get baseColorMap() {
  490.         return this._baseColorMap;
  491.     }
  492.  
  493.     /**
  494.      Factor in the range [0..1] indicating how metallic this MetallicMaterial is.
  495.  
  496.      1 is metal, 0 is non-metal.
  497.  
  498.      Multiplies by the *R* component of {{#crossLink "MetallicMaterial/metallicMap:property"}}{{/crossLink}}
  499.      and the *A* component of {{#crossLink "MetallicMaterial/metalRoughnessMap:property"}}{{/crossLink}}.
  500.  
  501.      @property metallic
  502.      @default 1.0
  503.      @type Number
  504.      */
  505.     set metallic(value) {
  506.         value = (value !== undefined && value !== null) ? value : 1.0;
  507.         if (this._state.metallic === value) {
  508.             return;
  509.         }
  510.         this._state.metallic = value;
  511.         this._renderer.imageDirty();
  512.     }
  513.  
  514.     get metallic() {
  515.         return this._state.metallic;
  516.     }
  517.  
  518.     /**
  519.      RGB {{#crossLink "Texture"}}{{/crossLink}} containing this MetallicMaterial's metallic factor in its *R* component.
  520.  
  521.      The *R* component multiplies by the {{#crossLink "MetallicMaterial/metallic:property"}}{{/crossLink}} property.
  522.  
  523.      @property metallicMap
  524.      @default undefined
  525.      @type {Texture}
  526.      @final
  527.      */
  528.     get metallicMap() {
  529.         return this._attached.metallicMap;
  530.     }
  531.  
  532.     /**
  533.      Factor in the range [0..1] indicating the roughness of this MetallicMaterial.
  534.  
  535.      0 is fully smooth, 1 is fully rough.
  536.  
  537.      Multiplies by the *R* component of {{#crossLink "MetallicMaterial/roughnessMap:property"}}{{/crossLink}}.
  538.  
  539.      @property roughness
  540.      @default 1.0
  541.      @type Number
  542.      */
  543.     set roughness(value) {
  544.         value = (value !== undefined && value !== null) ? value : 1.0;
  545.         if (this._state.roughness === value) {
  546.             return;
  547.         }
  548.         this._state.roughness = value;
  549.         this._renderer.imageDirty();
  550.     }
  551.  
  552.     get roughness() {
  553.         return this._state.roughness;
  554.     }
  555.  
  556.     /**
  557.      RGB {{#crossLink "Texture"}}{{/crossLink}} containing this MetallicMaterial's roughness factor in its *R* component.
  558.  
  559.      The *R* component multiplies by the {{#crossLink "MetallicMaterial/roughness:property"}}{{/crossLink}} property.
  560.  
  561.      Must be within the same {{#crossLink "Scene"}}Scene{{/crossLink}} as this MetallicMaterial.
  562.  
  563.      @property roughnessMap
  564.      @default undefined
  565.      @type {Texture}
  566.      @final
  567.      */
  568.     get roughnessMap() {
  569.         return this._attached.roughnessMap;
  570.     }
  571.  
  572.     /**
  573.      RGB {{#crossLink "Texture"}}{{/crossLink}} containing this MetallicMaterial's metalness in its *R* component and roughness in its *G* component.
  574.  
  575.      Its *B* component multiplies by the {{#crossLink "MetallicMaterial/metallic:property"}}{{/crossLink}} property, while
  576.      its *G* component multiplies by the {{#crossLink "MetallicMaterial/roughness:property"}}{{/crossLink}} property.
  577.  
  578.      Must be within the same {{#crossLink "Scene"}}Scene{{/crossLink}} as this MetallicMaterial.
  579.  
  580.      @property metallicRoughnessMap
  581.      @default undefined
  582.      @type {Texture}
  583.      @final
  584.      */
  585.     get metallicRoughnessMap() {
  586.         return this._attached.metallicRoughnessMap;
  587.     }
  588.  
  589.     /**
  590.      Factor in the range [0..1] indicating specular Fresnel value.
  591.  
  592.      @property specularF0
  593.      @default 0.0
  594.      @type Number
  595.      */
  596.     set specularF0(value) {
  597.         value = (value !== undefined && value !== null) ? value : 0.0;
  598.         if (this._state.specularF0 === value) {
  599.             return;
  600.         }
  601.         this._state.specularF0 = value;
  602.         this._renderer.imageDirty();
  603.     }
  604.  
  605.     get specularF0() {
  606.         return this._state.specularF0;
  607.     }
  608.  
  609.     /**
  610.      RGB emissive color.
  611.  
  612.      Multiplies by {{#crossLink "MetallicMaterial/emissiveMap:property"}}{{/crossLink}}.
  613.  
  614.      @property emissive
  615.      @default [0.0, 0.0, 0.0]
  616.      @type Float32Array
  617.      */
  618.     set emissive(value) {
  619.         let emissive = this._state.emissive;
  620.         if (!emissive) {
  621.             emissive = this._state.emissive = new Float32Array(3);
  622.         } else if (value && emissive[0] === value[0] && emissive[1] === value[1] && emissive[2] === value[2]) {
  623.             return;
  624.         }
  625.         if (value) {
  626.             emissive[0] = value[0];
  627.             emissive[1] = value[1];
  628.             emissive[2] = value[2];
  629.         } else {
  630.             emissive[0] = 0;
  631.             emissive[1] = 0;
  632.             emissive[2] = 0;
  633.         }
  634.         this._renderer.imageDirty();
  635.     }
  636.  
  637.     get emissive() {
  638.         return this._state.emissive;
  639.     }
  640.  
  641.     /**
  642.      RGB emissive map.
  643.  
  644.      Multiplies by {{#crossLink "MetallicMaterial/emissive:property"}}{{/crossLink}}.
  645.  
  646.      @property emissiveMap
  647.      @default undefined
  648.      @type {Texture}
  649.      @final
  650.      */
  651.     get emissiveMap() {
  652.         return this._attached.emissiveMap;
  653.     }
  654.  
  655.     /**
  656.      RGB ambient occlusion map.
  657.  
  658.      Within objectRenderers, multiplies by the specular and diffuse light reflected by surfaces.
  659.  
  660.      @property occlusionMap
  661.      @default undefined
  662.      @type {Texture}
  663.      @final
  664.      */
  665.     get occlusionMap() {
  666.         return this._attached.occlusionMap;
  667.     }
  668.  
  669.     /**
  670.      Factor in the range [0..1] indicating the alpha value.
  671.  
  672.      Multiplies by the *R* component of {{#crossLink "MetallicMaterial/alphaMap:property"}}{{/crossLink}} and
  673.      the *A* component, if present, of {{#crossLink "MetallicMaterial/baseColorMap:property"}}{{/crossLink}}.
  674.  
  675.      The value of {{#crossLink "MetallicMaterial/alphaMode:property"}}{{/crossLink}} indicates how alpha is
  676.      interpreted when rendering.
  677.  
  678.      @property alpha
  679.      @default 1.0
  680.      @type Number
  681.      */
  682.     set alpha(value) {
  683.         value = (value !== undefined && value !== null) ? value : 1.0;
  684.         if (this._state.alpha === value) {
  685.             return;
  686.         }
  687.         this._state.alpha = value;
  688.         this._renderer.imageDirty();
  689.     }
  690.  
  691.     get alpha() {
  692.         return this._state.alpha;
  693.     }
  694.  
  695.     /**
  696.      RGB {{#crossLink "Texture"}}{{/crossLink}} containing this MetallicMaterial's alpha in its *R* component.
  697.  
  698.      The *R* component multiplies by the {{#crossLink "MetallicMaterial/alpha:property"}}{{/crossLink}} property.
  699.  
  700.      @property alphaMap
  701.      @default undefined
  702.      @type {Texture}
  703.      @final
  704.      */
  705.     get alphaMap() {
  706.         return this._attached.alphaMap;
  707.     }
  708.  
  709.     /**
  710.      RGB tangent-space normal map {{#crossLink "Texture"}}{{/crossLink}}.
  711.  
  712.      Must be within the same {{#crossLink "Scene"}}Scene{{/crossLink}} as this MetallicMaterial.
  713.  
  714.      @property normalMap
  715.      @default undefined
  716.      @type {Texture}
  717.      @final
  718.      */
  719.     get normalMap() {
  720.         return this._attached.normalMap;
  721.     }
  722.  
  723.     /**
  724.      The alpha rendering mode.
  725.  
  726.      This specifies how alpha is interpreted. Alpha is the combined result of the
  727.      {{#crossLink "MetallicMaterial/alpha:property"}}{{/crossLink}} and
  728.      {{#crossLink "MetallicMaterial/alphaMap:property"}}{{/crossLink}} properties.
  729.  
  730.      * "opaque" - The alpha value is ignored and the rendered output is fully opaque.
  731.      * "mask" - The rendered output is either fully opaque or fully transparent depending on the alpha and {{#crossLink "MetallicMaterial/alphaCutoff:property"}}{{/crossLink}}.
  732.      * "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).
  733.  
  734.      @property alphaMode
  735.      @default "opaque"
  736.      @type {String}
  737.      */
  738.  
  739.     set alphaMode(alphaMode) {
  740.         alphaMode = alphaMode || "opaque";
  741.         let value = modes[alphaMode];
  742.         if (value === undefined) {
  743.             this.error("Unsupported value for 'alphaMode': " + alphaMode + " defaulting to 'opaque'");
  744.             value = "opaque";
  745.         }
  746.         if (this._state.alphaMode === value) {
  747.             return;
  748.         }
  749.         this._state.alphaMode = value;
  750.         this._renderer.imageDirty();
  751.     }
  752.  
  753.     get alphaMode() {
  754.         return modeNames[this._state.alphaMode];
  755.     }
  756.  
  757.     /**
  758.      The alpha cutoff value.
  759.  
  760.      Specifies the cutoff threshold when {{#crossLink "MetallicMaterial/alphaMode:property"}}{{/crossLink}}
  761.      equals "mask". If the alpha is greater than or equal to this value then it is rendered as fully
  762.      opaque, otherwise, it is rendered as fully transparent. A value greater than 1.0 will render the entire
  763.      material as fully transparent. This value is ignored for other modes.
  764.  
  765.      Alpha is the combined result of the
  766.      {{#crossLink "MetallicMaterial/alpha:property"}}{{/crossLink}} and
  767.      {{#crossLink "MetallicMaterial/alphaMap:property"}}{{/crossLink}} properties.
  768.  
  769.      @property alphaCutoff
  770.      @default 0.5
  771.      @type {Number}
  772.      */
  773.     set alphaCutoff(alphaCutoff) {
  774.         if (alphaCutoff === null || alphaCutoff === undefined) {
  775.             alphaCutoff = 0.5;
  776.         }
  777.         if (this._state.alphaCutoff === alphaCutoff) {
  778.             return;
  779.         }
  780.         this._state.alphaCutoff = alphaCutoff;
  781.     }
  782.  
  783.     get alphaCutoff() {
  784.         return this._state.alphaCutoff;
  785.     }
  786.  
  787.     /**
  788.      Whether backfaces are visible on attached {{#crossLink "Mesh"}}Meshes{{/crossLink}}.
  789.  
  790.      The backfaces will belong to {{#crossLink "Geometry"}}{{/crossLink}} compoents that are also attached to
  791.      the {{#crossLink "Mesh"}}Meshes{{/crossLink}}.
  792.  
  793.      @property backfaces
  794.      @default false
  795.      @type Boolean
  796.      */
  797.     set backfaces(value) {
  798.         value = !!value;
  799.         if (this._state.backfaces === value) {
  800.             return;
  801.         }
  802.         this._state.backfaces = value;
  803.         this._renderer.imageDirty();
  804.     }
  805.  
  806.     get backfaces() {
  807.         return this._state.backfaces;
  808.     }
  809.  
  810.     /**
  811.      Indicates the winding direction of front faces on attached {{#crossLink "Mesh"}}Meshes{{/crossLink}}.
  812.  
  813.      The faces will belong to {{#crossLink "Geometry"}}{{/crossLink}} components that are also attached to
  814.      the {{#crossLink "Mesh"}}Meshes{{/crossLink}}.
  815.  
  816.      @property frontface
  817.      @default "ccw"
  818.      @type String
  819.      */
  820.     set frontface(value) {
  821.         value = value !== "cw";
  822.         if (this._state.frontface === value) {
  823.             return;
  824.         }
  825.         this._state.frontface = value;
  826.         this._renderer.imageDirty();
  827.     }
  828.  
  829.     get frontface() {
  830.         return this._state.frontface ? "ccw" : "cw";
  831.     }
  832.  
  833.     /**
  834.      The MetallicMaterial's line width.
  835.  
  836.      @property lineWidth
  837.      @default 1.0
  838.      @type Number
  839.      */
  840.     set lineWidth(value) {
  841.         this._state.lineWidth = value || 1.0;
  842.         this._renderer.imageDirty();
  843.     }
  844.  
  845.     get lineWidth() {
  846.         return this._state.lineWidth;
  847.     }
  848.  
  849.     /**
  850.      The MetallicMaterial's point size.
  851.  
  852.      @property pointSize
  853.      @default 1.0
  854.      @type Number
  855.      */
  856.     set pointSize(value) {
  857.         this._state.pointSize = value || 1.0;
  858.         this._renderer.imageDirty();
  859.     }
  860.  
  861.     get pointSize() {
  862.         return this._state.pointSize;
  863.     }
  864.  
  865.     destroy() {
  866.         super.destroy();
  867.         this._state.destroy();
  868.     }
  869. }
  870.  
  871. componentClasses[type] = MetallicMaterial;
  872.  
  873. export{MetallicMaterial};
  874.