@cesium/engine 12.0.1 → 13.0.0

package/Source/Scene/DerivedCommand.js

@@ -1,3 +1,4 @@
+import { MetadataComponentType } from "@cesium/engine";
 import defined from "../Core/defined.js";
 import DrawCommand from "../Renderer/DrawCommand.js";
 import RenderState from "../Renderer/RenderState.js";
@@ -416,6 +417,98 @@ function getGlslType(classProperty) {
   return `ivec${componentCount}`;
 }
 
+/**
+ * Returns a shader statement that applies the inverse of the
+ * value transform to the given value, based on the given offset
+ * and scale.
+ *
+ * @param {string} input The input value
+ * @param {string} offset The offset
+ * @param {string} scale The scale
+ * @returns {string} The statement
+ */
+function unapplyValueTransform(input, offset, scale) {
+  return `((${input} - float(${offset})) / float(${scale}))`;
+}
+
+/**
+ * Returns a shader statement that applies the inverse of the
+ * normalization, based on the given component type
+ *
+ * @param {string} input The input value
+ * @param {string} componentType The component type
+ * @returns {string} The statement
+ */
+function unnormalize(input, componentType) {
+  const max = MetadataComponentType.getMaximum(componentType);
+  return `(${input}) / float(${max})`;
+}
+
+/**
+ * Creates a shader statement that returns the value of the specified
+ * property, normalized to the range [0, 1].
+ *
+ * @param {MetadataClassProperty} classProperty The class property
+ * @param {object} metadataProperty The metadata property, either
+ * a `PropertyTextureProperty` or a `PropertyAttributeProperty`
+ * @returns {string} The string
+ */
+function getSourceValueStringScalar(classProperty, metadataProperty) {
+  let result = `float(value)`;
+
+  // The 'hasValueTransform' indicates whether the property
+  // (or its class property) did define an 'offset' or 'scale'.
+  // Even when they had not been defined in the JSON, they are
+  // defined in the object, with default values.
+  if (metadataProperty.hasValueTransform) {
+    const offset = metadataProperty.offset;
+    const scale = metadataProperty.scale;
+    result = unapplyValueTransform(result, offset, scale);
+  }
+  if (!classProperty.normalized) {
+    result = unnormalize(result, classProperty.componentType);
+  }
+  return result;
+}
+
+/**
+ * Creates a shader statement that returns the value of the specified
+ * component of the given property, normalized to the range [0, 1].
+ *
+ * @param {MetadataClassProperty} classProperty The class property
+ * @param {object} metadataProperty The metadata property, either
+ * a `PropertyTextureProperty` or a `PropertyAttributeProperty`
+ * @param {string} componentName The name, in ["x", "y", "z", "w"]
+ * @returns {string} The string
+ */
+function getSourceValueStringComponent(
+  classProperty,
+  metadataProperty,
+  componentName,
+) {
+  const valueString = `value.${componentName}`;
+  let result = `float(${valueString})`;
+
+  // The 'hasValueTransform' indicates whether the property
+  // (or its class property) did define an 'offset' or 'scale'.
+  // Even when they had not been defined in the JSON, they are
+  // defined in the object, with default values
+  // Note that in the 'PropertyTextureProperty' and the
+  // 'PropertyAttributeProperty', these values are
+  // stored as "object types" (like 'Cartesian2'), whereas
+  // in the 'MetadataClassProperty', they are stored as
+  // "array types", e.g. a `[number, number]`
+  if (metadataProperty.hasValueTransform) {
+    const offset = metadataProperty.offset[componentName];
+    const scale = metadataProperty.scale[componentName];
+    result = unapplyValueTransform(result, offset, scale);
+  }
+  if (!classProperty.normalized) {
+    result = unnormalize(result, classProperty.componentType);
+  }
+  return result;
+}
+
 /**
  * Creates a new `ShaderProgram` from the given input that renders metadata
  * values into the frame buffer, according to the given picked metadata info.
@@ -452,34 +545,34 @@ function getPickMetadataShaderProgram(
     return shader;
   }
 
+  const metadataProperty = pickedMetadataInfo.metadataProperty;
   const classProperty = pickedMetadataInfo.classProperty;
   const glslType = getGlslType(classProperty);
 
   // Define the components that will go into the output `metadataValues`.
+  // This will be the 'color' that is written into the frame buffer,
+  // meaning that the values should be in [0.0, 1.0], and will become
+  // values in [0, 255] in the frame buffer.
   // By default, all of them are 0.0.
   const sourceValueStrings = ["0.0", "0.0", "0.0", "0.0"];
   const componentCount = getComponentCount(classProperty);
   if (componentCount === 1) {
-    // When the property is a scalar, store its value directly
-    // in `metadataValues.x`
-    sourceValueStrings[0] = `float(value)`;
+    // When the property is a scalar, store the source value
+    // string directly in `metadataValues.x`
+    sourceValueStrings[0] = getSourceValueStringScalar(
+      classProperty,
+      metadataProperty,
+    );
   } else {
     // When the property is an array, store the array elements
     // in `metadataValues.x/y/z/w`
-    const components = ["x", "y", "z", "w"];
-    for (let i = 0; i < componentCount; i++) {
-      const component = components[i];
-      const valueString = `value.${component}`;
-      sourceValueStrings[i] = `float(${valueString})`;
-    }
-  }
-
-  // Make sure that the `metadataValues` components are all in
-  // the range [0, 1] (which will result in RGBA components
-  // in [0, 255] during rendering)
-  if (!classProperty.normalized) {
+    const componentNames = ["x", "y", "z", "w"];
     for (let i = 0; i < componentCount; i++) {
-      sourceValueStrings[i] += " / 255.0";
+      sourceValueStrings[i] = getSourceValueStringComponent(
+        classProperty,
+        metadataProperty,
+        componentNames[i],
+      );
     }
   }
 

package/Source/Scene/DynamicEnvironmentMapManager.js

@@ -12,6 +12,7 @@ import PixelFormat from "../Core/PixelFormat.js";
 import SceneMode from "./SceneMode.js";
 import Transforms from "../Core/Transforms.js";
 import ComputeCommand from "../Renderer/ComputeCommand.js";
+import ContextLimits from "../Renderer/ContextLimits.js";
 import CubeMap from "../Renderer/CubeMap.js";
 import Framebuffer from "../Renderer/Framebuffer.js";
 import Texture from "../Renderer/Texture.js";
@@ -79,7 +80,11 @@ function DynamicEnvironmentMapManager(options) {
 
   options = defaultValue(options, defaultValue.EMPTY_OBJECT);
 
-  const mipmapLevels = defaultValue(options.mipmapLevels, 10);
+  const mipmapLevels = Math.min(
+    defaultValue(options.mipmapLevels, 10),
+    Math.log2(ContextLimits.maximumCubeMapSize),
+  );
+
   this._mipmapLevels = mipmapLevels;
   this._radianceMapComputeCommands = new Array(6);
   this._convolutionComputeCommands = new Array((mipmapLevels - 1) * 6);
@@ -295,6 +300,63 @@ Object.defineProperties(DynamicEnvironmentMapManager.prototype, {
   },
 });
 
+// Internally manage a queue of commands across all instances to prevent too many commands from being added in a single frame and using too much memory at once.
+DynamicEnvironmentMapManager._maximumComputeCommandCount = 8; // This value is updated once a context is created.
+DynamicEnvironmentMapManager._activeComputeCommandCount = 0;
+DynamicEnvironmentMapManager._nextFrameCommandQueue = [];
+/**
+ * Add a command to the queue. If possible, it will be added to the list of commands for the next frame. Otherwise, it will be added to a backlog
+ * and attempted next frame.
+ * @private
+ * @param {ComputeCommand} command The created command
+ * @param {FrameState} frameState The current frame state
+ */
+DynamicEnvironmentMapManager._queueCommand = (command, frameState) => {
+  if (
+    DynamicEnvironmentMapManager._activeComputeCommandCount >=
+    DynamicEnvironmentMapManager._maximumComputeCommandCount
+  ) {
+    // Command will instead be scheduled next frame
+    DynamicEnvironmentMapManager._nextFrameCommandQueue.push(command);
+    return;
+  }
+
+  frameState.commandList.push(command);
+  DynamicEnvironmentMapManager._activeComputeCommandCount++;
+};
+/**
+ * If there are any backlogged commands, queue up as many as possible for the next frame.
+ * @private
+ * @param {FrameState} frameState The current frame state
+ */
+DynamicEnvironmentMapManager._updateCommandQueue = (frameState) => {
+  DynamicEnvironmentMapManager._maximumComputeCommandCount = Math.log2(
+    ContextLimits.maximumCubeMapSize,
+  ); // Scale relative to GPU resources available
+
+  if (
+    DynamicEnvironmentMapManager._nextFrameCommandQueue.length > 0 &&
+    DynamicEnvironmentMapManager._activeComputeCommandCount <
+      DynamicEnvironmentMapManager._maximumComputeCommandCount
+  ) {
+    let command = DynamicEnvironmentMapManager._nextFrameCommandQueue.shift();
+    while (
+      defined(command) &&
+      DynamicEnvironmentMapManager._activeComputeCommandCount <
+        DynamicEnvironmentMapManager._maximumComputeCommandCount
+    ) {
+      if (command.canceled) {
+        command = DynamicEnvironmentMapManager._nextFrameCommandQueue.shift();
+        continue;
+      }
+
+      frameState.commandList.push(command);
+      DynamicEnvironmentMapManager._activeComputeCommandCount++;
+      command = DynamicEnvironmentMapManager._nextFrameCommandQueue.shift();
+    }
+  }
+};
+
 /**
  * Sets the owner for the input DynamicEnvironmentMapManager if there wasn't another owner.
  * Destroys the owner's previous DynamicEnvironmentMapManager if setting is successful.
@@ -334,15 +396,25 @@ DynamicEnvironmentMapManager.setOwner = function (
 DynamicEnvironmentMapManager.prototype.reset = function () {
   let length = this._radianceMapComputeCommands.length;
   for (let i = 0; i < length; ++i) {
+    if (defined(this._radianceMapComputeCommands[i])) {
+      this._radianceMapComputeCommands[i].canceled = true;
+      DynamicEnvironmentMapManager._activeComputeCommandCount--;
+    }
     this._radianceMapComputeCommands[i] = undefined;
   }
 
   length = this._convolutionComputeCommands.length;
   for (let i = 0; i < length; ++i) {
+    if (defined(this._convolutionComputeCommands[i])) {
+      this._convolutionComputeCommands[i].canceled = true;
+      DynamicEnvironmentMapManager._activeComputeCommandCount--;
+    }
     this._convolutionComputeCommands[i] = undefined;
   }
 
   if (defined(this._irradianceComputeCommand)) {
+    this._irradianceComputeCommand.canceled = true;
+    DynamicEnvironmentMapManager._activeComputeCommandCount--;
     this._irradianceComputeCommand = undefined;
   }
 
@@ -520,14 +592,17 @@ function updateRadianceMap(manager, frameState) {
           framebuffer._unBind();
           framebuffer.destroy();
 
+          DynamicEnvironmentMapManager._activeComputeCommandCount--;
+
           if (!commands.some(defined)) {
             manager._convolutionsCommandsDirty = true;
             manager._shouldRegenerateShaders = true;
           }
         },
       });
-      frameState.commandList.push(command);
+
       manager._radianceMapComputeCommands[i] = command;
+      DynamicEnvironmentMapManager._queueCommand(command, frameState);
       i++;
     }
     manager._radianceCommandsDirty = false;
@@ -554,7 +629,7 @@ function updateSpecularMaps(manager, frameState) {
   const getPostExecute = (index, texture, face, level) => () => {
     // Copy output texture to corresponding face and mipmap level
     const commands = manager._convolutionComputeCommands;
-    if (!defined(commands[index])) {
+    if (!defined(commands[index]) || commands[index].canceled) {
       // This command was cancelled
       return;
     }
@@ -562,6 +637,7 @@ function updateSpecularMaps(manager, frameState) {
 
     radianceCubeMap.copyFace(frameState, texture, face, level);
     facesCopied++;
+    DynamicEnvironmentMapManager._activeComputeCommandCount--;
 
     // All faces and levels have been copied
     if (facesCopied === manager._specularMapTextures.length) {
@@ -611,7 +687,7 @@ function updateSpecularMaps(manager, frameState) {
         owner: manager,
         uniformMap: {
           u_roughness: () => level / (mipmapLevels - 1),
-          u_radianceTexture: () => radianceCubeMap,
+          u_radianceTexture: () => radianceCubeMap ?? context.defaultTexture,
           u_faceDirection: () => {
             return CubeMap.getDirection(face, scratchCartesian);
           },
@@ -619,7 +695,7 @@ function updateSpecularMaps(manager, frameState) {
         postExecute: getPostExecute(index, texture, face, level),
       });
       manager._convolutionComputeCommands[index] = command;
-      frameState.commandList.push(command);
+      DynamicEnvironmentMapManager._queueCommand(command, frameState);
       ++index;
     }
 
@@ -664,7 +740,7 @@ function updateIrradianceResources(manager, frameState) {
     fragmentShaderSource: fs,
     outputTexture: texture,
     uniformMap: {
-      u_radianceMap: () => manager._radianceCubeMap,
+      u_radianceMap: () => manager._radianceCubeMap ?? context.defaultTexture,
     },
     postExecute: () => {
       if (!defined(manager._irradianceComputeCommand)) {
@@ -674,10 +750,12 @@ function updateIrradianceResources(manager, frameState) {
       manager._irradianceTextureDirty = false;
       manager._irradianceComputeCommand = undefined;
       manager._sphericalHarmonicCoefficientsDirty = true;
+
+      DynamicEnvironmentMapManager._activeComputeCommandCount--;
     },
   });
   manager._irradianceComputeCommand = command;
-  frameState.commandList.push(command);
+  DynamicEnvironmentMapManager._queueCommand(command, frameState);
   manager._irradianceTextureDirty = true;
 }
 
@@ -744,6 +822,8 @@ DynamicEnvironmentMapManager.prototype.update = function (frameState) {
     return;
   }
 
+  DynamicEnvironmentMapManager._updateCommandQueue(frameState);
+
   const dynamicLighting = frameState.atmosphere.dynamicLighting;
   const regenerateEnvironmentMap =
     atmosphereNeedsUpdate(this, frameState) ||

package/Source/Scene/GltfTextureLoader.js

@@ -170,6 +170,7 @@ GltfTextureLoader.prototype.load = async function () {
 function CreateTextureJob() {
   this.gltf = undefined;
   this.textureInfo = undefined;
+  this.textureId = undefined;
   this.image = undefined;
   this.context = undefined;
   this.texture = undefined;
@@ -178,12 +179,14 @@ function CreateTextureJob() {
 CreateTextureJob.prototype.set = function (
   gltf,
   textureInfo,
+  textureId,
   image,
   mipLevels,
   context,
 ) {
   this.gltf = gltf;
   this.textureInfo = textureInfo;
+  this.textureId = textureId;
   this.image = image;
   this.mipLevels = mipLevels;
   this.context = context;
@@ -193,13 +196,21 @@ CreateTextureJob.prototype.execute = function () {
   this.texture = createTexture(
     this.gltf,
     this.textureInfo,
+    this.textureId,
     this.image,
     this.mipLevels,
     this.context,
   );
 };
 
-function createTexture(gltf, textureInfo, image, mipLevels, context) {
+function createTexture(
+  gltf,
+  textureInfo,
+  textureId,
+  image,
+  mipLevels,
+  context,
+) {
   // internalFormat is only defined for CompressedTextureBuffer
   const internalFormat = image.internalFormat;
 
@@ -261,6 +272,7 @@ function createTexture(gltf, textureInfo, image, mipLevels, context) {
     }
 
     texture = Texture.create({
+      id: textureId,
       context: context,
       source: {
         arrayBufferView: image.bufferView, // Only defined for CompressedTextureBuffer
@@ -276,6 +288,7 @@ function createTexture(gltf, textureInfo, image, mipLevels, context) {
       image = resizeImageToNextPowerOfTwo(image);
     }
     texture = Texture.create({
+      id: textureId,
       context: context,
       source: image,
       sampler: sampler,
@@ -332,6 +345,7 @@ GltfTextureLoader.prototype.process = function (frameState) {
     textureJob.set(
       this._gltf,
       this._textureInfo,
+      this._cacheKey,
       this._image,
       this._mipLevels,
       frameState.context,
@@ -346,6 +360,7 @@ GltfTextureLoader.prototype.process = function (frameState) {
     texture = createTexture(
       this._gltf,
       this._textureInfo,
+      this._cacheKey,
       this._image,
       this._mipLevels,
       frameState.context,

package/Source/Scene/ITwinData.js

@@ -0,0 +1,138 @@
+import Cesium3DTileset from "./Cesium3DTileset.js";
+import defined from "../Core/defined.js";
+import Resource from "../Core/Resource.js";
+import ITwinPlatform from "../Core/ITwinPlatform.js";
+import RuntimeError from "../Core/RuntimeError.js";
+import Check from "../Core/Check.js";
+
+/**
+ * Methods for loading iTwin platform data into CesiumJS
+ *
+ * @experimental This feature is not final and is subject to change without Cesium's standard deprecation policy.
+ *
+ * @see ITwinPlatform
+ * @namespace ITwinData
+ */
+const ITwinData = {};
+
+/**
+ * Create a {@link Cesium3DTileset} for the given iModel id using iTwin's Mesh Export API.
+ *
+ * If there is not a completed export available for the given iModel id, the returned promise will resolve to <code>undefined</code>.
+ * We recommend waiting 10-20 seconds and trying to load the tileset again.
+ * If all exports are Invalid this will throw an error.
+ *
+ * @example
+ * const tileset = await Cesium.ITwinData.createTilesetFromIModelId(iModelId);
+ * if (Cesium.defined(tileset)) {
+ *   viewer.scene.primitives.add(tileset);
+ * }
+ *
+ * @experimental This feature is not final and is subject to change without Cesium's standard deprecation policy.
+ *
+ * @param {string} iModelId The id of the iModel to load
+ * @param {Cesium3DTileset.ConstructorOptions} [options] Object containing options to pass to the internally created {@link Cesium3DTileset}.
+ * @returns {Promise<Cesium3DTileset | undefined>} A promise that will resolve to the created 3D tileset or <code>undefined</code> if there is no completed export for the given iModel id
+ *
+ * @throws {RuntimeError} If all exports for the given iModel are Invalid
+ * @throws {RuntimeError} If the iTwin API request is not successful
+ */
+ITwinData.createTilesetFromIModelId = async function (iModelId, options) {
+  const { exports } = await ITwinPlatform.getExports(iModelId);
+
+  if (
+    exports.length > 0 &&
+    exports.every((exportObj) => {
+      return exportObj.status === ITwinPlatform.ExportStatus.Invalid;
+    })
+  ) {
+    throw new RuntimeError(
+      `All exports for this iModel are Invalid: ${iModelId}`,
+    );
+  }
+
+  const completeExport = exports.find((exportObj) => {
+    return exportObj.status === ITwinPlatform.ExportStatus.Complete;
+  });
+
+  if (!defined(completeExport)) {
+    return;
+  }
+
+  // Convert the link to the tileset url while preserving the search paramaters
+  // This link is only valid 1 hour
+  const baseUrl = new URL(completeExport._links.mesh.href);
+  baseUrl.pathname = `${baseUrl.pathname}/tileset.json`;
+  const tilesetUrl = baseUrl.toString();
+
+  const resource = new Resource({
+    url: tilesetUrl,
+  });
+
+  return Cesium3DTileset.fromUrl(resource, options);
+};
+
+/**
+ * Create a tileset for the specified reality data id. This function only works
+ * with 3D Tiles meshes and point clouds.
+ *
+ * If the <code>type</code> or <code>rootDocument</code> are not provided this function
+ * will first request the full metadata for the specified reality data to fill these values.
+ *
+ * @experimental This feature is not final and is subject to change without Cesium's standard deprecation policy.
+ *
+ * @param {string} iTwinId The id of the iTwin to load data from
+ * @param {string} realityDataId The id of the reality data to load
+ * @param {ITwinPlatform.RealityDataType} [type] The type of this reality data
+ * @param {string} [rootDocument] The path of the root document for this reality data
+ * @returns {Promise<Cesium3DTileset>}
+ */
+ITwinData.createTilesetForRealityDataId = async function (
+  iTwinId,
+  realityDataId,
+  type,
+  rootDocument,
+) {
+  //>>includeStart('debug', pragmas.debug);
+  Check.typeOf.string("iTwinId", iTwinId);
+  Check.typeOf.string("realityDataId", realityDataId);
+  if (defined(type)) {
+    Check.typeOf.string("type", type);
+  }
+  if (defined(rootDocument)) {
+    Check.typeOf.string("rootDocument", rootDocument);
+  }
+  //>>includeEnd('debug')
+
+  if (!defined(type) || !defined(rootDocument)) {
+    const metadata = await ITwinPlatform.getRealityDataMetadata(
+      iTwinId,
+      realityDataId,
+    );
+    rootDocument = metadata.rootDocument;
+    type = metadata.type;
+  }
+
+  const supportedRealityDataTypes = [
+    ITwinPlatform.RealityDataType.Cesium3DTiles,
+    ITwinPlatform.RealityDataType.PNTS,
+    ITwinPlatform.RealityDataType.RealityMesh3DTiles,
+    ITwinPlatform.RealityDataType.Terrain3DTiles,
+  ];
+
+  if (!supportedRealityDataTypes.includes(type)) {
+    throw new RuntimeError(`Reality data type is not a mesh type: ${type}`);
+  }
+
+  const tilesetAccessUrl = await ITwinPlatform.getRealityDataURL(
+    iTwinId,
+    realityDataId,
+    rootDocument,
+  );
+
+  return Cesium3DTileset.fromUrl(tilesetAccessUrl, {
+    maximumScreenSpaceError: 4,
+  });
+};
+
+export default ITwinData;

package/Source/Scene/Label.js

@@ -400,8 +400,7 @@ Object.defineProperties(Label.prototype, {
       if (this._text !== value) {
         this._text = value;
 
-        // Strip soft-hyphen (auto-wrap) characters from input string
-        const renderedValue = value.replace(/\u00ad/g, "");
+        const renderedValue = Label.filterUnsupportedCharacters(value);
         this._renderedText = Label.enableRightToLeftDetection
           ? reverseRtl(renderedValue)
           : renderedValue;
@@ -1346,6 +1345,21 @@ Label.getScreenSpaceBoundingBox = function (
   return result;
 };
 
+/**
+ * Removes control characters and soft hyphon (auto-wrap) characters, which will cause an error when rendering a glyph. This does not remove tabs, carriage returns, or newlines.
+ * @private
+ * @param {string} text The original label text
+ * @returns {string} The renderable filtered text
+ */
+Label.filterUnsupportedCharacters = function (text) {
+  const problematicCharactersRegex = new RegExp(
+    // eslint-disable-next-line no-control-regex
+    /[\u0000-\u0008\u000E-\u001F\u00ad\u202a-\u206f\u200b-\u200f]/,
+    "g",
+  );
+  return text.replace(problematicCharactersRegex, "");
+};
+
 /**
  * Determines if this label equals another label.  Labels are equal if all their properties
  * are equal.  Labels in different collections can be equal.
@@ -1502,7 +1516,7 @@ function reverseBrackets(bracket) {
   }
 }
 
-//To add another language, simply add its Unicode block range(s) to the below regex.
+// To add another language, add its Unicode block range(s) to the below regex.
 const hebrew = "\u05D0-\u05EA";
 const arabic = "\u0600-\u06FF\u0750-\u077F\u08A0-\u08FF";
 const rtlChars = new RegExp(`[${hebrew}${arabic}]`);

package/Source/Scene/MetadataClassProperty.js

@@ -438,6 +438,10 @@ Object.defineProperties(MetadataClassProperty.prototype, {
   /**
    * The offset to be added to property values as part of the value transform.
    *
+   * This is always defined, even when `hasValueTransform` is `false`. If
+   * the class property JSON itself did not define it, then it will be
+   * initialized to the default value.
+   *
    * @memberof MetadataClassProperty.prototype
    * @type {number|number[]|number[][]}
    * @readonly
@@ -451,6 +455,10 @@ Object.defineProperties(MetadataClassProperty.prototype, {
   /**
    * The scale to be multiplied to property values as part of the value transform.
    *
+   * This is always defined, even when `hasValueTransform` is `false`. If
+   * the class property JSON itself did not define it, then it will be
+   * initialized to the default value.
+   *
    * @memberof MetadataClassProperty.prototype
    * @type {number|number[]|number[][]}
    * @readonly
@@ -1139,6 +1147,24 @@ function normalizeInPlace(values, valueType, normalizeFunction) {
 }
 
 /**
+ * Applies the value transform that is defined with the given offsets
+ * and scales to the given values.
+ *
+ * If the given values are not an array, then the given transformation
+ * function will be applied directly.
+ *
+ * If the values are an array, then this function will be called recursively
+ * with the array elements, boiling down to a component-wise application
+ * of the transformation function to the innermost array elements.
+ *
+ * @param {number|number[]|number[][]} values The input values
+ * @param {number|number[]|number[][]} offsets The offsets
+ * @param {number|number[]|number[][]} scales The scales
+ * @param {Function} transformationFunction The function with the signature
+ * `(value:number, offset:number, scale:number) : number` that will be
+ * applied to the innermost elements
+ * @returns The input values (or the result of applying the transformation
+ * function to a single value if the values have not been an array).
  * @private
  */
 MetadataClassProperty.valueTransformInPlace = function (