basic dynamic instancing

Author: lukemckinstry

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

@@ -753,6 +753,32 @@ Object.defineProperties(Model.prototype, {
     },
   },
 
+  /**
+   * Sets model matrices for instancing
+   *
+   * @memberof Model.prototype
+   * @type {boolean}
+   *
+   * @default []
+   */
+  apiInstances: {
+    get: function () {
+      return this._apiInstances;
+    },
+    set: function (value) {
+      this._apiInstances = value;
+      for (const runtimeNode in this._sceneGraph._runtimeNodes) {
+        if (
+          defined(
+            this._sceneGraph._runtimeNodes[runtimeNode]._apiInstancesDirty,
+          )
+        ) {
+          this._sceneGraph._runtimeNodes[runtimeNode]._apiInstancesDirty = true;
+        }
+      }
+    },
+  },
+
   /**
    * Whether or not to cull the model using frustum/horizon culling. If the model is part of a 3D Tiles tileset, this property
    * will always be false, since the 3D Tiles culling system is used.
@@ -3086,7 +3112,7 @@ Model.fromGltfAsync = async function (options) {
   const model = new Model(modelOptions);
 
   if (defined(options.apiInstances)) {
-    model.apiInstances = options.apiInstances;
+    model._apiInstances = options.apiInstances;
   }
 
   const resourceCredits = model._resource.credits;

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

@@ -0,0 +1,101 @@
+import SceneMode from "../SceneMode.js";
+
+/**
+ * The model matrix update stage is responsible for updating the instancingTransformsBuffer of a runtime node.
+ *
+ * @namespace ModelInstancesUpdateStage
+ *
+ * @private
+ */
+const ModelInstancesUpdateStage = {};
+ModelInstancesUpdateStage.name = "ModelInstancesUpdateStage"; // Helps with debugging
+
+/**
+ * Processes a runtime node. Updates the instancingTransformsBuffer.
+ *
+ * @param {ModelRuntimeNode} runtimeNode
+ * @param {ModelSceneGraph} sceneGraph
+ * @param {FrameState} frameState
+ *
+ * @private
+ */
+ModelInstancesUpdateStage.update = function (
+  runtimeNode,
+  sceneGraph,
+  frameState,
+) {
+  if (!runtimeNode._apiInstancesDirty) {
+    return;
+  }
+
+  const use2D = frameState.mode !== SceneMode.SCENE3D;
+  if (use2D && sceneGraph._model._projectTo2D) {
+    return;
+  }
+
+  updateRuntimeNode(runtimeNode, sceneGraph, frameState);
+  runtimeNode._apiInstancesDirty = false;
+};
+
+/**
+ * Recursively update all child runtime nodes and their runtime primitives.
+ *
+ * @private
+ */
+function updateRuntimeNode(runtimeNode, sceneGraph, frameState) {
+  let i;
+
+  const instances = runtimeNode._sceneGraph._model._apiInstances;
+  const model = runtimeNode._sceneGraph._model;
+  const buffer = runtimeNode.instancingTransformsBuffer;
+  const transformsTypedArray = transformsToTypedArray(instances);
+
+  runtimeNode.instancingTransformsBuffer.copyFromArrayView(
+    transformsTypedArray,
+  );
+
+  model._modelResources.push(buffer);
+  const keepTypedArray = model._enablePick && !frameState.context.webgl2;
+
+  if (keepTypedArray) {
+    runtimeNode.transformsTypedArray = transformsTypedArray;
+  }
+
+  runtimeNode.instancingTransformsBuffer = buffer;
+
+  const childrenLength = runtimeNode.children.length;
+
+  for (i = 0; i < childrenLength; i++) {
+    const childRuntimeNode = sceneGraph._runtimeNodes[runtimeNode.children[i]];
+
+    updateRuntimeNode(childRuntimeNode, sceneGraph, frameState);
+  }
+}
+
+function transformsToTypedArray(transforms) {
+  const elements = 12;
+  const count = transforms.length;
+  const transformsTypedArray = new Float32Array(count * elements);
+
+  for (let i = 0; i < count; i++) {
+    const transform = transforms[i];
+    const offset = elements * i;
+
+    transformsTypedArray[offset + 0] = transform[0];
+    transformsTypedArray[offset + 1] = transform[4];
+    transformsTypedArray[offset + 2] = transform[8];
+    transformsTypedArray[offset + 3] = transform[12];
+    transformsTypedArray[offset + 4] = transform[1];
+    transformsTypedArray[offset + 5] = transform[5];
+    transformsTypedArray[offset + 6] = transform[9];
+    transformsTypedArray[offset + 7] = transform[13];
+    transformsTypedArray[offset + 8] = transform[2];
+    transformsTypedArray[offset + 9] = transform[6];
+    transformsTypedArray[offset + 10] = transform[10];
+    transformsTypedArray[offset + 11] = transform[14];
+  }
+
+  return transformsTypedArray;
+}
+
+export default ModelInstancesUpdateStage;

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

@@ -8,6 +8,7 @@ import TranslationRotationScale from "../../Core/TranslationRotationScale.js";
 import Quaternion from "../../Core/Quaternion.js";
 import InstancingPipelineStage from "./InstancingPipelineStage.js";
 import ModelMatrixUpdateStage from "./ModelMatrixUpdateStage.js";
+import ModelInstancesUpdateStage from "./ModelInstancesUpdateStage.js";
 import NodeStatisticsPipelineStage from "./NodeStatisticsPipelineStage.js";
 
 /**
@@ -55,6 +56,8 @@ function ModelRuntimeNode(options) {
   this._computedTransform = new Matrix4(); // Computed in initialize()
   this._transformDirty = false;
 
+  this._apiInstancesDirty = false;
+
   // Used for animation
   this._transformParameters = undefined;
   this._morphWeights = [];
@@ -585,8 +588,10 @@ ModelRuntimeNode.prototype.configurePipeline = function () {
     pipelineStages.push(InstancingPipelineStage);
   }
 
-  if (defined(this.sceneGraph._model.apiInstances)) {
+  if (defined(this.sceneGraph._model._apiInstances)) {
     pipelineStages.push(InstancingPipelineStage);
+    updateStages.push(ModelInstancesUpdateStage);
+    this.apiInstances = this.sceneGraph._model._apiInstances;
   }
 
   pipelineStages.push(NodeStatisticsPipelineStage);

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

@@ -507,7 +507,7 @@ ModelSceneGraph.prototype.buildDrawCommands = function (frameState) {
       nodePipelineStage.process(
         nodeRenderResources,
         runtimeNode.node,
-        runtimeNode.sceneGraph._model.apiInstances,
+        runtimeNode.sceneGraph._model._apiInstances,
         frameState,
       );
     }