Merge pull request #12018 from CesiumGS/texture-scale

Add support for glTF normalTextureInfo.scale

CHANGES.md

@@ -1,5 +1,13 @@
 # Change Log
 
+### 1.119 - 2024-07-01
+
+#### @cesium/engine
+
+##### Additions :tada:
+
+- Added support for the `scale` property of a normal texture in a glTF material. [#12018](https://github.com/CesiumGS/cesium/pull/12018)
+
 ### 1.118.2 - 2024-06-03
 
 This is an npm-only release to fix a dependency issue published in 1.118.1
@@ -12,13 +20,13 @@ This is an npm-only release to fix a dependency issue published in 1.118
 
 #### @cesium/engine
 
-###### Additions :tada:
+##### Additions :tada:
 
 - Added support for glTF models with the [KHR_materials_specular extension](https://github.com/KhronosGroup/glTF/tree/main/extensions/2.0/Khronos/KHR_materials_specular). [#11970](https://github.com/CesiumGS/cesium/pull/11970)
 - Added support for glTF models with the [KHR_materials_anisotropy extension](https://github.com/KhronosGroup/glTF/blob/main/extensions/2.0/Khronos/KHR_materials_anisotropy/README.md). [#11988](https://github.com/CesiumGS/cesium/pull/11988)
 - Added support for glTF models with the [KHR_materials_clearcoat extension](https://github.com/KhronosGroup/glTF/blob/main/extensions/2.0/Khronos/KHR_materials_clearcoat/README.md). [#12006](https://github.com/CesiumGS/cesium/pull/12006)
 
-#### Fixes :wrench:
+##### Fixes :wrench:
 
 - Fixed a bug where `scene.pickPosition` returned incorrect results against the globe when `depthTestAgainstTerrain` is `false`. [#4368](https://github.com/CesiumGS/cesium/issues/4368)
 - Fixed a bug where `TaskProcessor` worker loading would check the worker module ID rather than the absolute URL when determining if it is cross-origin. [#11833](https://github.com/CesiumGS/cesium/pull/11833)

Specs/Data/Models/glTF-2.0/BoxClearcoat/glTF/BoxClearcoat.gltf

@@ -140,7 +140,8 @@
                         "index": 0
                     },
                     "clearcoatNormalTexture": {
-                        "index": 0
+                        "index": 0,
+                        "scale": 0.5
                     }
                 }
             }

Specs/Data/Models/glTF-2.0/BoxScaledNormalTexture/README.md

@@ -0,0 +1,7 @@
+# Box with Scaled Normal Texture
+
+## License Information
+
+Developed by Cesium for testing a scaled normal texture. Please follow the [Cesium Trademark Terms and Conditions](https://github.com/AnalyticalGraphicsInc/cesium/wiki/CesiumTrademark.pdf).
+
+This model is licensed under a [Creative Commons Attribution 4.0 International License](http://creativecommons.org/licenses/by/4.0/).

Specs/Data/Models/glTF-2.0/BoxScaledNormalTexture/glTF/BoxScaledNormalTexture.gltf

@@ -0,0 +1,191 @@
+{
+    "asset": {
+        "generator": "COLLADA2GLTF",
+        "version": "2.0"
+    },
+    "scene": 0,
+    "scenes": [
+        {
+            "nodes": [
+                0
+            ]
+        }
+    ],
+    "nodes": [
+        {
+            "children": [
+                1
+            ],
+            "matrix": [
+                1.0,
+                0.0,
+                0.0,
+                0.0,
+                0.0,
+                0.0,
+                -1.0,
+                0.0,
+                0.0,
+                1.0,
+                0.0,
+                0.0,
+                0.0,
+                0.0,
+                0.0,
+                1.0
+            ]
+        },
+        {
+            "mesh": 0
+        }
+    ],
+    "meshes": [
+        {
+            "primitives": [
+                {
+                    "attributes": {
+                        "NORMAL": 1,
+                        "POSITION": 2,
+                        "TEXCOORD_0": 3
+                    },
+                    "indices": 0,
+                    "mode": 4,
+                    "material": 0
+                }
+            ],
+            "name": "Mesh"
+        }
+    ],
+    "accessors": [
+        {
+            "bufferView": 0,
+            "byteOffset": 0,
+            "componentType": 5123,
+            "count": 36,
+            "max": [
+                23
+            ],
+            "min": [
+                0
+            ],
+            "type": "SCALAR"
+        },
+        {
+            "bufferView": 1,
+            "byteOffset": 0,
+            "componentType": 5126,
+            "count": 24,
+            "max": [
+                1.0,
+                1.0,
+                1.0
+            ],
+            "min": [
+                -1.0,
+                -1.0,
+                -1.0
+            ],
+            "type": "VEC3"
+        },
+        {
+            "bufferView": 1,
+            "byteOffset": 288,
+            "componentType": 5126,
+            "count": 24,
+            "max": [
+                0.5,
+                0.5,
+                0.5
+            ],
+            "min": [
+                -0.5,
+                -0.5,
+                -0.5
+            ],
+            "type": "VEC3"
+        },
+        {
+            "bufferView": 2,
+            "byteOffset": 0,
+            "componentType": 5126,
+            "count": 24,
+            "max": [
+                6.0,
+                1.0
+            ],
+            "min": [
+                0.0,
+                0.0
+            ],
+            "type": "VEC2"
+        }
+    ],
+    "materials": [
+        {
+            "pbrMetallicRoughness": {
+                "baseColorTexture": {
+                    "index": 0
+                },
+                "metallicFactor": 0.0
+            },
+            "normalTexture": {
+                "index": 0,
+                "scale": 0.5
+            },
+            "name": "Texture"
+        }
+    ],
+    "textures": [
+        {
+            "sampler": 0,
+            "source": 0
+        }
+    ],
+    "images": [
+        {
+            "uri": "CesiumLogoFlat.png"
+        }
+    ],
+    "samplers": [
+        {
+            "magFilter": 9729,
+            "minFilter": 9986,
+            "wrapS": 10497,
+            "wrapT": 10497
+        }
+    ],
+    "bufferViews": [
+        {
+            "buffer": 0,
+            "byteOffset": 768,
+            "byteLength": 72,
+            "target": 34963
+        },
+        {
+            "buffer": 0,
+            "byteOffset": 0,
+            "byteLength": 576,
+            "byteStride": 12,
+            "target": 34962
+        },
+        {
+            "buffer": 0,
+            "byteOffset": 576,
+            "byteLength": 192,
+            "byteStride": 8,
+            "target": 34962
+        }
+    ],
+    "buffers": [
+        {
+            "byteLength": 840,
+            "uri": "BoxScaledNormalTexture.bin"
+        }
+    ],
+    "extensionsRequired": [
+      "KHR_draco_mesh_compression"
+    ],
+    "extensionsUsed": [
+      "KHR_draco_mesh_compression"
+    ]
+}

packages/engine/Source/Scene/GltfLoaderUtil.js

@@ -142,10 +142,7 @@ GltfLoaderUtil.createModelTextureReader = function (options) {
   let texCoord = defaultValue(textureInfo.texCoord, 0);
   let transform;
 
-  const textureTransform = defaultValue(
-    textureInfo.extensions,
-    defaultValue.EMPTY_OBJECT
-  ).KHR_texture_transform;
+  const textureTransform = textureInfo.extensions?.KHR_texture_transform;
 
   if (defined(textureTransform)) {
     texCoord = defaultValue(textureTransform.texCoord, texCoord);
@@ -177,6 +174,7 @@ GltfLoaderUtil.createModelTextureReader = function (options) {
   modelTextureReader.index = textureInfo.index;
   modelTextureReader.texture = texture;
   modelTextureReader.texCoord = texCoord;
+  modelTextureReader.scale = textureInfo.scale;
   modelTextureReader.transform = transform;
   modelTextureReader.channels = channels;
 

packages/engine/Source/Scene/Model/MaterialPipelineStage.js

@@ -216,6 +216,44 @@ function processTextureTransform(
   };
 }
 
+/**
+ * Process a single texture scale and add it to the shader and uniform map.
+ *
+ * @param {ShaderBuilder} shaderBuilder The shader builder to modify
+ * @param {Object<string, Function>} uniformMap The uniform map to modify.
+ * @param {ModelComponents.TextureReader} textureReader The texture to add to the shader
+ * @param {string} uniformName The name of the sampler uniform such as <code>u_baseColorTexture</code>
+ * @param {string} defineName The name of the texture for use in the defines, minus any prefix or suffix. For example, "BASE_COLOR" or "EMISSIVE"
+ *
+ * @private
+ */
+function processTextureScale(
+  shaderBuilder,
+  uniformMap,
+  textureReader,
+  uniformName,
+  defineName
+) {
+  // Add a define to enable the texture transformation code in the shader.
+  const transformDefine = `HAS_${defineName}_TEXTURE_SCALE`;
+  shaderBuilder.addDefine(
+    transformDefine,
+    undefined,
+    ShaderDestination.FRAGMENT
+  );
+
+  // Add a uniform for the transformation matrix
+  const scaleUniformName = `${uniformName}Scale`;
+  shaderBuilder.addUniform(
+    "float",
+    scaleUniformName,
+    ShaderDestination.FRAGMENT
+  );
+  uniformMap[scaleUniformName] = function () {
+    return textureReader.scale;
+  };
+}
+
 /**
  * Process a single texture and add it to the shader and uniform map.
  *
@@ -274,6 +312,17 @@ function processTexture(
       defineName
     );
   }
+
+  const { scale } = textureReader;
+  if (defined(scale) && scale !== 1.0) {
+    processTextureScale(
+      shaderBuilder,
+      uniformMap,
+      textureReader,
+      uniformName,
+      defineName
+    );
+  }
 }
 
 function processMaterialUniforms(

packages/engine/Source/Scene/ModelComponents.js

@@ -1187,6 +1187,15 @@ function TextureReader() {
    */
   this.transform = Matrix3.clone(Matrix3.IDENTITY);
 
+  /**
+   * Scale to apply to texture values.
+   *
+   * @type {number}
+   * @default 1.0
+   * @private
+   */
+  this.scale = 1.0;
+
   /**
    * The texture channels to read from. When undefined all channels are read.
    *

packages/engine/Source/Shaders/Model/MaterialStageFS.glsl

@@ -65,7 +65,11 @@ NormalInfo getNormalInfo(ProcessedAttributes attributes)
     #ifdef HAS_NORMAL_TEXTURE
         mat3 tbn = mat3(tangent, bitangent, geometryNormal);
         vec3 normalSample = texture(u_normalTexture, normalTexCoords).rgb;
-        vec3 normal = normalize(tbn * (2.0 * normalSample - 1.0));
+        normalSample = 2.0 * normalSample - 1.0;
+        #ifdef HAS_NORMAL_TEXTURE_SCALE
+            normalSample.xy *= u_normalTextureScale;
+        #endif
+        vec3 normal = normalize(tbn * normalSample);
     #else
         vec3 normal = geometryNormal;
     #endif
@@ -105,10 +109,12 @@ vec3 getNormalFromTexture(ProcessedAttributes attributes, vec3 geometryNormal)
     #endif
 
     mat3 tbn = mat3(t, b, geometryNormal);
-    vec3 n = texture(u_normalTexture, normalTexCoords).rgb;
-    vec3 textureNormal = normalize(tbn * (2.0 * n - 1.0));
-
-    return textureNormal;
+    vec3 normalSample = texture(u_normalTexture, normalTexCoords).rgb;
+    normalSample = 2.0 * normalSample - 1.0;
+    #ifdef HAS_NORMAL_TEXTURE_SCALE
+        normalSample.xy *= u_normalTextureScale;
+    #endif
+    return normalize(tbn * normalSample);
 }
 #endif
 
@@ -131,10 +137,12 @@ vec3 getClearcoatNormalFromTexture(ProcessedAttributes attributes, vec3 geometry
     #endif
 
     mat3 tbn = mat3(t, b, geometryNormal);
-    vec3 n = texture(u_clearcoatNormalTexture, normalTexCoords).rgb;
-    vec3 textureNormal = normalize(tbn * (2.0 * n - 1.0));
-
-    return textureNormal;
+    vec3 normalSample = texture(u_clearcoatNormalTexture, normalTexCoords).rgb;
+    normalSample = 2.0 * normalSample - 1.0;
+    #ifdef HAS_CLEARCOAT_NORMAL_TEXTURE_SCALE
+        normalSample.xy *= u_normalTextureScale;
+    #endif
+    return normalize(tbn * normalSample);
 }
 #endif