LitOptions class to hold backend options

src/deprecated/deprecated.js

@@ -71,6 +71,8 @@ import { SkinInstance } from '../scene/skin-instance.js';
 import { StandardMaterial } from '../scene/materials/standard-material.js';
 import { Batch } from '../scene/batching/batch.js';
 import { getDefaultMaterial } from '../scene/materials/default-material.js';
+import { StandardMaterialOptions } from '../scene/materials/standard-material-options.js';
+import { LitOptions } from '../scene/materials/lit-options.js';
 
 import { Animation, Key, Node } from '../scene/animation/animation.js';
 import { Skeleton } from '../scene/animation/skeleton.js';
@@ -785,6 +787,28 @@ _defineAlias('glossVertexColor', 'glossMapVertexColor');
 _defineAlias('opacityVertexColor', 'opacityMapVertexColor');
 _defineAlias('lightVertexColor', 'lightMapVertexColor');
 
+function _defineOption(name, newName) {
+    if (name !== 'chunks' && name !== '_pass') {
+        Object.defineProperty(StandardMaterialOptions.prototype, name, {
+            get: function () {
+                Debug.deprecated(`Getting pc.Options#${name} has been deprecated as the property has been moved to pc.Options.LitOptions#${newName || name}.`);
+                return this.litOptions[newName || name];
+            },
+            set: function (value) {
+                Debug.deprecated(`Setting pc.Options#${name} has been deprecated as the property has been moved to pc.Options.LitOptions#${newName || name}.`);
+                this.litOptions[newName || name] = value;
+            }
+        });
+    }
+}
+_defineOption('refraction', 'useRefraction');
+
+const tempOptions = new LitOptions();
+const litOptionProperties = Object.getOwnPropertyNames(tempOptions);
+for (const litOption in litOptionProperties) {
+    _defineOption(litOptionProperties[litOption]);
+}
+
 // ANIMATION
 
 export const anim = {

src/index.js

@@ -115,6 +115,7 @@ export { Layer } from './scene/layer.js';
 export { LayerComposition } from './scene/composition/layer-composition.js';
 export { Light } from './scene/light.js';
 export { LightingParams } from './scene/lighting/lighting-params.js';
+export { LitOptions } from './scene/materials/lit-options.js';
 export { Material } from './scene/materials/material.js';
 export { Mesh } from './scene/mesh.js';
 export { MeshInstance, Command } from './scene/mesh-instance.js';
@@ -128,6 +129,7 @@ export { Skin } from './scene/skin.js';
 export { SkinInstance } from './scene/skin-instance.js';
 export { Sprite } from './scene/sprite.js';
 export { StandardMaterial } from './scene/materials/standard-material.js';
+export { StandardMaterialOptions } from './scene/materials/standard-material-options.js';
 export { StencilParameters } from './scene/stencil-parameters.js';
 export { TextureAtlas } from './scene/texture-atlas.js';
 

src/scene/materials/lit-options.js

@@ -0,0 +1,155 @@
+import { Debug } from '../../core/debug.js';
+import {
+    BLEND_NONE, FOG_NONE, GAMMA_NONE
+} from '../constants.js';
+
+/**
+ * The lit options determines how the lit-shader gets generated. It specifies a set of
+ * parameters which triggers different fragment and vertex shader generation in the backend.
+ *
+ * @property {object} chunks Object containing custom shader chunks that will replace default ones.
+ * @property {string} customFragmentShader Replaced the whole fragment shader with this string.
+ * @property {number} fog The type of fog being applied in the shader. See {@link Scene#fog} for the list of
+ * possible values.
+ * @property {number} gamma The type of gamma correction being applied in the shader. See
+ * {@link Scene#gammaCorrection} for the list of possible values.
+ * @property {number} toneMap The type of tone mapping being applied in the shader. See {@link Scene#toneMapping}
+ * for the list of possible values.
+ * @property {boolean} conserveEnergy The value of {@link StandardMaterial#conserveEnergy}.
+ * @property {number} occludeSpecular The value of {@link StandardMaterial#occludeSpecular}.
+ * @property {boolean} occludeDirect The value of {@link StandardMaterial#occludeDirect}.
+ * @property {number} shadingModel The value of {@link StandardMaterial#shadingModel}.
+ * @property {number} fresnelModel The value of {@link StandardMaterial#fresnelModel}.
+ * @property {number} cubeMapProjection The value of {@link StandardMaterial#cubeMapProjection}.
+ * @property {boolean} useMetalness The value of {@link StandardMaterial#useMetalness}.
+ * @property {number} blendType The value of {@link Material#blendType}.
+ * @property {boolean} twoSidedLighting The value of {@link Material#twoSidedLighting}.
+ * @property {number} occludeSpecularFloat Defines if {@link StandardMaterial#occludeSpecularIntensity} constant
+ * should affect specular occlusion.
+ * @property {boolean} alphaTest Enable alpha testing. See {@link Material#alphaTest}.
+ * @property {boolean} alphaToCoverage Enable alpha to coverage. See {@link Material#alphaToCoverage}.
+ * @property {boolean} opacityFadesSpecular Enable specular fade. See {@link Material#opacityFadesSpecular}.
+ * @property {float} ambientSH If ambient spherical harmonics are used. Ambient SH replace prefiltered cubemap
+ * ambient on certain platform (mostly Android) for performance reasons.
+ * @property {boolean} useSpecular If any specular or reflections are needed at all.
+ * @property {boolean} fixSeams If cubemaps require seam fixing (see {@link Texture#options.fixCubemapSeams}).
+ * @property {string} forceFragmentPrecision Override fragment shader numeric precision. Can be "lowp", "mediump",
+ * "highp" or null to use default.
+ * @property {boolean} fastTbn Use slightly cheaper normal mapping code (skip tangent space normalization). Can look
+ * buggy sometimes.
+ * @property {boolean} useRefraction If refraction is used.
+ * @property {number} skyboxIntensity If reflected skybox intensity should be modulated.
+ * @property {boolean} useCubeMapRotation If cube map rotation is enabled.
+ * @property {boolean} useInstancing If hardware instancing compatible shader should be generated. Transform is read
+ * from per-instance {@link VertexBuffer} instead of shader's uniforms.
+ * @property {boolean} useMorphPosition If morphing code should be generated to morph positions.
+ * @property {boolean} useMorphNormal If morphing code should be generated to morph normals.
+ * @property {string} reflectionSource One of "envAtlasHQ", "envAtlas", "cubeMap", "sphereMap".
+ * @property {boolean} ambientSource One of "ambientSH", "envAtlas", "constant".
+ */
+class LitOptions {
+    constructor() {
+        this.hasTangents = false;
+        this.chunks = [];
+
+        this._pass = 0;
+        this.alphaTest = false;
+        this.forceFragmentPrecision = false;
+        this.blendType = BLEND_NONE;
+        this.separateAmbient = false;
+        this.screenSpace = false;
+        this.skin = false;
+        this.useInstancing = false;
+        this.useMorphPosition = false;
+        this.useMorphNormal = false;
+        this.useMorphTextureBased = false;
+
+        this.nineSlicedMode = false;
+
+        this.clusteredLightingEnabled = true;
+
+        this.clusteredLightingCookiesEnabled = false;
+        this.clusteredLightingShadowsEnabled = false;
+        this.clusteredLightingShadowType = 0;
+        this.clusteredLightingAreaLightsEnabled = false;
+
+        this.vertexColors = false;
+        this.lightMapEnabled = false;
+        this.useLightMapVertexColors = false;
+        this.dirLightMapEnabled = false;
+        this.heightMapEnabled = false;
+        this.normalMapEnabled = false;
+        this.clearCoatNormalMapEnabled = false;
+        this.aoMapEnabled = false;
+        this.useAoVertexColors = false;
+        this.diffuseMapEnabled = false;
+
+        this.useAmbientTint = false;
+        this.customFragmentShader = null;
+        this.pixelSnap = false;
+
+        this.useClearCoatNormalMap = false;
+        this.useDiffuseMap = false;
+        this.useAoMap = false;
+
+        this.detailModes = 0;
+        this.shadingModel = 0;
+        this.ambientSH = false;
+        this.fastTbn = false;
+        this.twoSidedLighting = false;
+        this.occludeSpecular = false;
+        this.occludeSpecularFloat = false;
+
+        this.useMsdf = false;
+        this.msdfTextAttribute = 0;
+
+        this.alphaToCoverage = false;
+        this.opacityFadesSpecular = false;
+
+        this.cubeMapProjection = false;
+
+        this.occludeDirect = false;
+        this.conserveEnergy = false;
+        this.useSpecular = false;
+        this.useSpecularityFactor = false;
+        this.useSpecularColor = false;
+        this.enableGGXSpecular = false;
+        this.fresnelModel = 0;
+        this.useRefraction = false;
+        this.useClearCoat = false;
+        this.useSheen = false;
+        this.useIridescence = false;
+        this.useMetalness = false;
+        this.useDynamicRefraction = false;
+
+        this.fog = FOG_NONE;
+        this.gamma = GAMMA_NONE;
+        this.toneMap = -1;
+        this.fixSeams = false;
+
+        this.reflectionSource = null;
+        this.reflectionEncoding = null;
+        this.ambientSource = 'constant';
+        this.ambientEncoding = null;
+
+        // TODO: add a test for if non skybox cubemaps have rotation (when this is supported) - for now assume no non-skybox cubemap rotation
+        this.skyboxIntensity = 1.0;
+        this.useCubeMapRotation = false;
+
+        this.lightMapWithoutAmbient = false;
+
+        this.lights = [];
+        this.noShadow = false;
+        this.lightMaskDynamic = 0x0;
+    }
+
+    set pass(p) {
+        Debug.warn(`pc.LitOptions#pass should be set by its parent pc.StandardMaterialOptions, setting it directly has no effect.`);
+    }
+
+    get pass() {
+        return this._pass;
+    }
+}
+
+export { LitOptions };

src/scene/materials/standard-material-options-builder.js

@@ -44,21 +44,19 @@ class StandardMaterialOptionsBuilder {
 
     // Minimal options for Depth and Shadow passes
     updateMinRef(options, scene, stdMat, objDefs, staticLightList, pass, sortedLights) {
-        options.litOptions = {};
         this._updateSharedOptions(options, scene, stdMat, objDefs, pass);
         this._updateMinOptions(options, stdMat);
         this._updateUVOptions(options, stdMat, objDefs, true);
         options.litOptions.chunks = options.chunks;
     }
 
     updateRef(options, scene, stdMat, objDefs, staticLightList, pass, sortedLights) {
-        options.litOptions = {};
         this._updateSharedOptions(options, scene, stdMat, objDefs, pass);
         this._updateEnvOptions(options, stdMat, scene);
         this._updateMaterialOptions(options, stdMat);
         if (pass === SHADER_FORWARDHDR) {
-            if (options.gamma) options.gamma = GAMMA_SRGBHDR;
-            options.toneMap = TONEMAP_LINEAR;
+            if (options.litOptions.gamma) options.litOptions.gamma = GAMMA_SRGBHDR;
+            options.litOptions.toneMap = TONEMAP_LINEAR;
         }
         options.litOptions.hasTangents = objDefs && ((objDefs & SHADERDEF_TANGENTS) !== 0);
         this._updateLightOptions(options, scene, stdMat, objDefs, sortedLights, staticLightList);
@@ -70,7 +68,7 @@ class StandardMaterialOptionsBuilder {
         options.forceUv1 = stdMat.forceUv1;
         options.chunks = stdMat.chunks || '';
 
-        options.litOptions.pass = pass;
+        options.pass = pass;
         options.litOptions.alphaTest = stdMat.alphaTest > 0;
         options.litOptions.forceFragmentPrecision = stdMat.forceFragmentPrecision || '';
         options.litOptions.blendType = stdMat.blendType;
@@ -120,13 +118,13 @@ class StandardMaterialOptionsBuilder {
 
         // All texture related lit options
         options.litOptions.lightMapEnabled = options.lightMap;
-        options.litOptions.lightMapVertexColors = options.lightVertexColors;
+        options.litOptions.useLightMapVertexColors = options.lightVertexColors;
         options.litOptions.dirLightMapEnabled = options.dirLightMap;
         options.litOptions.heightMapEnabled = options.heightMap;
         options.litOptions.normalMapEnabled = options.normalMap;
         options.litOptions.clearCoatNormalMapEnabled = options.clearCoatNormalMap;
         options.litOptions.aoMapEnabled = options.aoMap;
-        options.litOptions.aoVertexColors = options.aoVertexColors;
+        options.litOptions.useAoVertexColors = options.aoVertexColors;
         options.litOptions.diffuseMapEnabled = options.diffuseMap;
     }
 
@@ -248,7 +246,7 @@ class StandardMaterialOptionsBuilder {
         options.sheenGlossinessTint = 1;
 
         // LIT OPTIONS
-        options.litOptions.ambientTint = options.ambientTint;
+        options.litOptions.useAmbientTint = options.ambientTint;
         options.litOptions.customFragmentShader = stdMat.customFragmentShader;
         options.litOptions.pixelSnap = stdMat.pixelSnap;
 
@@ -279,7 +277,7 @@ class StandardMaterialOptionsBuilder {
         options.litOptions.useSpecularColor = useSpecularColor;
         options.litOptions.enableGGXSpecular = stdMat.enableGGXSpecular;
         options.litOptions.fresnelModel = stdMat.fresnelModel;
-        options.litOptions.useRefraction = (stdMat.refraction || !!stdMat.refractionMap) && (stdMat.useDynamicRefraction || !!options.reflectionSource);
+        options.litOptions.useRefraction = (stdMat.refraction || !!stdMat.refractionMap) && (stdMat.useDynamicRefraction || !!options.litOptions.reflectionSource);
         options.litOptions.useClearCoat = !!stdMat.clearCoat;
         options.litOptions.useSheen = stdMat.useSheen;
         options.litOptions.useIridescence = stdMat.useIridescence && stdMat.iridescence !== 0.0;

src/scene/materials/standard-material-options.js

@@ -0,0 +1,53 @@
+import { LitOptions } from "./lit-options.js";
+
+/**
+ * The standard material options define a set of options used to control the shader frontend shader generation,
+ * such as textures, tints and multipliers.
+ *
+ * @property {number} pass Value of {@link Layer#shaderPass} of the Layer being rendered. Must be set to the
+ * same in {@link LitOptions#pass}.
+ * @property {boolean} forceUv1 If UV1 (second set of texture coordinates) is required in the shader. Will be
+ * declared as "vUv1" and passed to the fragment shader.
+ * @property {boolean} ambientTint The value of {@link StandardMaterial#ambientTint}.
+ * @property {boolean} diffuseTint Defines if {@link StandardMaterial#diffuse} constant should affect diffuse color.
+ * @property {boolean} specularTint Defines if {@link StandardMaterial#specular} constant should affect specular
+ * color.
+ * @property {boolean} metalnessTint Defines if {@link StandardMaterial#metalness} constant should affect metalness
+ * value.
+ * @property {boolean} glossTint Defines if {@link StandardMaterial#shininess} constant should affect glossiness
+ * value.
+ * @property {boolean} emissiveTint Defines if {@link StandardMaterial#emissive} constant should affect emission
+ * value.
+ * @property {boolean} opacityTint Defines if {@link StandardMaterial#opacity} constant should affect opacity value.
+ * @property {boolean} packedNormal If normal map contains X in RGB, Y in Alpha, and Z must be reconstructed.
+ */
+class StandardMaterialOptions {
+    constructor() {
+        this.chunks = [];
+        this._pass = 0;
+        this.forceUv1 = false;
+        this.ambientTint = false;
+        this.diffuseTint = false;
+        this.specularTint = false;
+        this.metalnessTint = false;
+        this.glossTint = false;
+        this.emissiveTint = false;
+        this.opacityTint = false;
+        this.emissiveEncoding = 'linear';
+        this.lightMapEncoding = 'linear';
+        this.packedNormal = false;
+
+        this.litOptions = new LitOptions();
+    }
+
+    set pass(p) {
+        this._pass = p;
+        this.litOptions._pass = p;
+    }
+
+    get pass() {
+        return this._pass;
+    }
+}
+
+export { StandardMaterialOptions };