@itwin/core-common 3.3.0-dev.9 → 3.4.0-dev.10

package/lib/esm/RenderSchedule.js

@@ -5,7 +5,7 @@
 /** @packageDocumentation
  * @module DisplayStyles
  */
-import { assert, CompressedId64Set, Id64, OrderedId64Iterable } from "@itwin/core-bentley";
+import { assert, compareBooleans, compareNumbers, comparePossiblyUndefined, compareStrings, compareStringsOrUndefined, CompressedId64Set, Id64, OrderedId64Iterable, } from "@itwin/core-bentley";
 import { ClipPlane, ClipPrimitive, ClipVector, ConvexClipPlaneSet, Matrix3d, Plane3dByOriginAndUnitNormal, Point3d, Point4d, Range1d, Transform, UnionOfConvexClipPlaneSets, Vector3d, } from "@itwin/core-geometry";
 import { RgbColor } from "./RgbColor";
 import { FeatureAppearance } from "./FeatureSymbology";
@@ -15,6 +15,22 @@ function interpolate(start, end, fraction) {
 function interpolateRgb(start, end, fraction) {
     return new RgbColor(interpolate(start.r, end.r, fraction), interpolate(start.g, end.g, fraction), interpolate(start.b, end.b, fraction));
 }
+function compareXYZ(lhs, rhs) {
+    return compareNumbers(lhs.x, rhs.x) || compareNumbers(lhs.y, rhs.y) || compareNumbers(lhs.z, rhs.z);
+}
+function compare4d(lhs, rhs) {
+    return compareNumbers(lhs.x, rhs.x) || compareNumbers(lhs.y, rhs.y) || compareNumbers(lhs.z, rhs.z) || compareNumbers(lhs.w, rhs.w);
+}
+const scratchVec3a = new Vector3d();
+const scratchVec3b = new Vector3d();
+function compareMatrices(lhs, rhs) {
+    return compareXYZ(lhs.columnX(scratchVec3a), rhs.columnX(scratchVec3b))
+        || compareXYZ(lhs.columnY(scratchVec3a), rhs.columnY(scratchVec3b))
+        || compareXYZ(lhs.columnZ(scratchVec3a), rhs.columnZ(scratchVec3b));
+}
+function compareDurations(lhs, rhs) {
+    return compareNumbers(lhs.low, rhs.low) || compareNumbers(lhs.high, rhs.high);
+}
 /** Namespace containing types that collectively define a script that animates the contents of a view by adjusting the visibility, position,
  * and/or symbology of groups of elements over time. A [[RenderSchedule.Script]] is hosted by a [RenderTimeline]($backend) element. The script
  * can be associated with a [DisplayStyleState]($frontend) by way of its [[DisplayStyleSettings.renderTimeline]] property.
@@ -54,6 +70,12 @@ export var RenderSchedule;
                 props.interpolation = this.interpolation;
             return props;
         }
+        compareTo(other) {
+            return compareNumbers(this.interpolation, other.interpolation) || compareNumbers(this.time, other.time);
+        }
+        equals(other) {
+            return 0 === this.compareTo(other);
+        }
     }
     RenderSchedule.TimelineEntry = TimelineEntry;
     /** A timeline entry that controls the visibility of the associated geometry. */
@@ -71,6 +93,10 @@ export var RenderSchedule;
                 props.value = this.value;
             return props;
         }
+        compareTo(other) {
+            assert(other instanceof VisibilityEntry);
+            return super.compareTo(other) || compareNumbers(this.value, other.value);
+        }
     }
     RenderSchedule.VisibilityEntry = VisibilityEntry;
     /** A timeline entry controlling the color of the affected geometry. */
@@ -91,6 +117,10 @@ export var RenderSchedule;
             }
             return props;
         }
+        compareTo(other) {
+            assert(other instanceof ColorEntry);
+            return super.compareTo(other) || comparePossiblyUndefined((lhs, rhs) => lhs.compareTo(rhs), this.value, other.value);
+        }
     }
     RenderSchedule.ColorEntry = ColorEntry;
     /** Describes the components of a [[RenderSchedule.TransformEntry]] as a rotation around a pivot point followed by a translation. */
@@ -113,6 +143,12 @@ export var RenderSchedule;
                 orientation: [this.orientation.x, this.orientation.y, this.orientation.z, this.orientation.w],
             };
         }
+        compareTo(other) {
+            return compareXYZ(this.pivot, other.pivot) || compareXYZ(this.position, other.position) || compare4d(this.orientation, other.orientation);
+        }
+        equals(other) {
+            return this.pivot.isAlmostEqual(other.pivot) && this.position.isAlmostEqual(other.position) && this.orientation.isAlmostEqual(other.orientation);
+        }
     }
     RenderSchedule.TransformComponents = TransformComponents;
     /** A timeline entry that applies rotation, scaling, and/or translation to the affected geometry. */
@@ -134,6 +170,18 @@ export var RenderSchedule;
             }
             return props;
         }
+        compareTo(other) {
+            assert(other instanceof TransformEntry);
+            const cmp = super.compareTo(other);
+            if (0 !== cmp)
+                return cmp;
+            if (this.components || other.components) {
+                if (!this.components || !other.components)
+                    return this.components ? 1 : -1;
+                return this.components.compareTo(other.components);
+            }
+            return compareXYZ(this.value.origin, other.value.origin) || compareMatrices(this.value.matrix, other.value.matrix);
+        }
     }
     RenderSchedule.TransformEntry = TransformEntry;
     /** Defines a [ClipPlane]($core-geometry) associated with a [[RenderSchedule.CuttingPlaneEntry]]. */
@@ -155,6 +203,12 @@ export var RenderSchedule;
                 props.hidden = true;
             return props;
         }
+        compareTo(other) {
+            return compareXYZ(this.position, other.position) || compareXYZ(this.direction, other.direction) || compareBooleans(this.visible, other.visible) || compareBooleans(this.hidden, other.hidden);
+        }
+        equals(other) {
+            return 0 === this.compareTo(other);
+        }
     }
     RenderSchedule.CuttingPlane = CuttingPlane;
     /** A timeline entry that applies a [ClipPlane]($core-geometry) to the affected geometry. */
@@ -170,6 +224,10 @@ export var RenderSchedule;
                 props.value = this.value.toJSON();
             return props;
         }
+        compareTo(other) {
+            assert(other instanceof CuttingPlaneEntry);
+            return super.compareTo(other) || comparePossiblyUndefined((x, y) => x.compareTo(y), this.value, other.value);
+        }
     }
     RenderSchedule.CuttingPlaneEntry = CuttingPlaneEntry;
     /** Identifies a fractional position along a [[RenderSchedule.Timeline]] between any two [[RenderSchedule.TimelineEntry]]'s within a [[RenderSchedule.TimelineEntryList]].
@@ -220,6 +278,18 @@ export var RenderSchedule;
         toJSON() {
             return this._entries.map((x) => x.toJSON());
         }
+        compareTo(other) {
+            let cmp = compareNumbers(this._entries.length, other._entries.length) || compareDurations(this.duration, other.duration);
+            if (0 === cmp) {
+                for (let i = 0; i < this.length; i++)
+                    if (0 !== (cmp = this._entries[i].compareTo(other._entries[i])))
+                        break;
+            }
+            return cmp;
+        }
+        equals(other) {
+            return 0 === this.compareTo(other);
+        }
         /** @internal */
         findInterval(time, interval) {
             if (this.length === 0)
@@ -303,6 +373,25 @@ export var RenderSchedule;
                 cuttingPlaneTimeline: (_d = this.cuttingPlane) === null || _d === void 0 ? void 0 : _d.toJSON(),
             };
         }
+        compareTo(other) {
+            const cmp = compareDurations(this.duration, other.duration);
+            if (0 !== cmp)
+                return cmp;
+            // Do cheaper checks before iterating through timeline entries
+            if (!!this.visibility !== !!other.visibility)
+                return this.visibility ? 1 : -1;
+            else if (!!this.color !== !!other.color)
+                return this.color ? 1 : -1;
+            else if (!!this.transform !== !!other.transform)
+                return this.transform ? 1 : -1;
+            else if (!!this.cuttingPlane !== !!other.cuttingPlane)
+                return this.cuttingPlane ? 1 : -1;
+            return comparePossiblyUndefined((x, y) => x.compareTo(y), this.visibility, other.visibility) || comparePossiblyUndefined((x, y) => x.compareTo(y), this.color, other.color)
+                || comparePossiblyUndefined((x, y) => x.compareTo(y), this.transform, other.transform) || comparePossiblyUndefined((x, y) => x.compareTo(y), this.cuttingPlane, other.cuttingPlane);
+        }
+        equals(other) {
+            return 0 === this.compareTo(other);
+        }
         /** Get the visibility of the geometry at the specified time point. */
         getVisibility(time) {
             var _a, _b;
@@ -419,6 +508,38 @@ export var RenderSchedule;
                 elementIds: this._elementIds,
             };
         }
+        get containsElementIds() {
+            return this._elementIds.length > 0;
+        }
+        compareElementIds(other) {
+            if (typeof this._elementIds === typeof other._elementIds) {
+                const cmp = compareNumbers(this._elementIds.length, other._elementIds.length);
+                if (0 !== cmp)
+                    return cmp;
+                if (typeof this._elementIds === "string") {
+                    assert(typeof other._elementIds === "string");
+                    return compareStrings(this._elementIds, other._elementIds);
+                }
+            }
+            // One or both are stored as arrays, in which case they might contain the same Ids in different orders. We will consider them different in that case.
+            const mine = this.elementIds[Symbol.iterator]();
+            const theirs = other.elementIds[Symbol.iterator]();
+            while (true) {
+                const a = mine.next();
+                const b = theirs.next();
+                if (a.done !== b.done)
+                    return compareBooleans(!!a.done, !!b.done);
+                else if (a.done)
+                    return 0;
+                const cmp = compareStrings(a.value, b.value);
+                if (0 !== cmp)
+                    return cmp;
+            }
+        }
+        compareTo(other) {
+            assert(other instanceof ElementTimeline);
+            return compareNumbers(this.batchId, other.batchId) || this.compareElementIds(other) || super.compareTo(other);
+        }
         /** @internal */
         static getElementIds(ids) {
             if (typeof ids === "string")
@@ -468,6 +589,8 @@ export var RenderSchedule;
     class ModelTimeline extends Timeline {
         constructor(props) {
             super(props);
+            /** Tile tree suppliers perform **very** frequent ordered comparisons of ModelTimelines. They need to be fast. */
+            this._cachedComparisons = new WeakMap();
             this.modelId = props.modelId;
             this.realityModelUrl = props.realityModelUrl;
             this.containsModelClipping = undefined !== this.cuttingPlane;
@@ -476,6 +599,7 @@ export var RenderSchedule;
             let containsTransform = false;
             const transformBatchIds = [];
             const elementTimelines = [];
+            let containsElementIds = false;
             for (const elProps of props.elementTimelines) {
                 const el = ElementTimeline.fromJSON(elProps);
                 elementTimelines.push(el);
@@ -487,9 +611,11 @@ export var RenderSchedule;
                 }
                 containsFeatureOverrides || (containsFeatureOverrides = el.containsFeatureOverrides);
                 requiresBatching || (requiresBatching = el.requiresBatching);
+                containsElementIds = containsElementIds || el.containsElementIds;
             }
             this.elementTimelines = elementTimelines;
             this.transformBatchIds = transformBatchIds;
+            this.omitsElementIds = elementTimelines.length > 0 && !containsElementIds;
             this.containsFeatureOverrides = containsFeatureOverrides;
             this.requiresBatching = requiresBatching;
             this.containsTransform = containsTransform;
@@ -505,6 +631,26 @@ export var RenderSchedule;
                 elementTimelines: this.elementTimelines.map((x) => x.toJSON()),
             };
         }
+        compareTo(other) {
+            if (this === other)
+                return 0;
+            const cached = this._cachedComparisons.get(other);
+            if (undefined !== cached)
+                return cached;
+            assert(other instanceof ModelTimeline);
+            let cmp = compareStrings(this.modelId, other.modelId) || compareStringsOrUndefined(this.realityModelUrl, other.realityModelUrl)
+                || compareNumbers(this.elementTimelines.length, other.elementTimelines.length) || compareBooleans(this.containsFeatureOverrides, other.containsFeatureOverrides)
+                || compareBooleans(this.containsModelClipping, other.containsModelClipping) || compareBooleans(this.containsTransform, other.containsTransform)
+                || super.compareTo(other);
+            if (0 === cmp) {
+                for (let i = 0; i < this.elementTimelines.length; i++)
+                    if (0 !== (cmp = this.elementTimelines[i].compareTo(other.elementTimelines[i])))
+                        break;
+            }
+            this._cachedComparisons.set(other, cmp);
+            other._cachedComparisons.set(this, -cmp);
+            return cmp;
+        }
         /** Look up the element timeline with the specified batch Id. */
         findByBatchId(batchId) {
             return this.elementTimelines.find((x) => x.batchId === batchId);
@@ -522,6 +668,43 @@ export var RenderSchedule;
             var _a;
             return (_a = this.findByBatchId(batchId)) === null || _a === void 0 ? void 0 : _a.getAnimationTransform(time);
         }
+        /** Get the highest batchId of any ElementTimeline in this timeline. */
+        get maxBatchId() {
+            if (undefined === this._maxBatchId) {
+                this._maxBatchId = 0;
+                for (const elem of this.elementTimelines)
+                    this._maxBatchId = Math.max(this._maxBatchId, elem.batchId);
+            }
+            return this._maxBatchId;
+        }
+        /** Given the two halves of an [Id64]($bentley) return the [[ElementTimeline]] containing the corresponding element.
+         * @note The first call to this method populates a mapping for fast lookup.
+         * @alpha
+         */
+        getTimelineForElement(idLo, idHi) {
+            if (!this._idPairToElementTimeline) {
+                this._idPairToElementTimeline = new Id64.Uint32Map();
+                for (const timeline of this.elementTimelines) {
+                    for (const elementId of timeline.elementIds) {
+                        // NB: a malformed script may place the same element Id into multiple timelines. We're not going to check for such data errors here.
+                        this._idPairToElementTimeline.setById(elementId, timeline);
+                    }
+                }
+            }
+            return this._idPairToElementTimeline.get(idLo, idHi);
+        }
+        /** The batch Ids of the subset of [[elementTimelines]] that apply a transform and/or cutting plane.
+         * @alpha
+         */
+        get discreteBatchIds() {
+            if (!this._discreteBatchIds) {
+                this._discreteBatchIds = new Set(this.transformBatchIds);
+                for (const timeline of this.elementTimelines)
+                    if (!timeline.containsTransform && undefined !== timeline.cuttingPlane)
+                        this._discreteBatchIds.add(timeline.batchId);
+            }
+            return this._discreteBatchIds;
+        }
     }
     RenderSchedule.ModelTimeline = ModelTimeline;
     /** Specifies how to animate the contents of a [ViewState]($frontend) over time. The script contains any number of [[RenderSchedule.ModelTimeline]]s, each describing how
@@ -533,6 +716,8 @@ export var RenderSchedule;
      */
     class Script {
         constructor(props) {
+            /** Tile tree references perform **very** frequent ordered comparisons of Scripts. They need to be fast. */
+            this._cachedComparisons = new WeakMap();
             this.duration = Range1d.createNull();
             const transformBatchIds = new Set();
             const modelTimelines = [];
@@ -558,6 +743,27 @@ export var RenderSchedule;
             this.containsFeatureOverrides = containsFeatureOverrides;
             this.transformBatchIds = transformBatchIds;
         }
+        compareTo(other) {
+            if (this === other)
+                return 0;
+            const cached = this._cachedComparisons.get(other);
+            if (undefined !== cached)
+                return cached;
+            let cmp = compareNumbers(this.modelTimelines.length, other.modelTimelines.length) || compareBooleans(this.containsModelClipping, other.containsModelClipping)
+                || compareBooleans(this.requiresBatching, other.requiresBatching) || compareBooleans(this.containsTransform, other.containsTransform)
+                || compareBooleans(this.containsFeatureOverrides, other.containsFeatureOverrides) || compareDurations(this.duration, other.duration);
+            if (0 === cmp) {
+                for (let i = 0; i < this.modelTimelines.length; i++)
+                    if (0 !== (cmp = this.modelTimelines[i].compareTo(other.modelTimelines[i])))
+                        break;
+            }
+            this._cachedComparisons.set(other, cmp);
+            other._cachedComparisons.set(this, -cmp);
+            return cmp;
+        }
+        equals(other) {
+            return 0 === this.compareTo(other);
+        }
         static fromJSON(props) {
             if (!Array.isArray(props) || props.length === 0)
                 return undefined;
@@ -585,7 +791,7 @@ export var RenderSchedule;
             for (const timeline of this.modelTimelines)
                 timeline.addSymbologyOverrides(overrides, time);
         }
-        /** Used by collectPredecessorIds methods of RenderTimeline and DisplayStyle.
+        /** Used by the [Element.collectReferenceIds]($backend) method overrides in RenderTimeline and DisplayStyle.
          * @internal
          */
         discloseIds(ids) {
@@ -596,17 +802,31 @@ export var RenderSchedule;
                         ids.add(id);
             }
         }
+        /** @internal */
+        modelRequiresBatching(modelId) {
+            // Only if the script contains animation (cutting plane, transform or visibility by node ID) do we require separate tilesets for animations.
+            return this.requiresBatching && this.modelTimelines.some((x) => x.modelId === modelId && x.requiresBatching);
+        }
     }
     RenderSchedule.Script = Script;
-    /** A reference to a [[RenderSchedule.Script]] indicating the persistent [Element]($backend) from which the script was obtained.
-     * Prior to the introduction of the [RenderTimeline]($backend) class in version 01.00.13 of the BisCore ECSchema, scripts were
-     * stored in the JSON properties of [DisplayStyle]($backend) elements. Now they are stored in the Script property of a RenderTimeline element.
-     * The `sourceId` can refer to either a DisplayStyle or a RenderTimeline.
+    /** A reference to a [[RenderSchedule.Script]], optionally identifying the source of the script.
+     * @see [DisplayStyle.loadScheduleScript]($backend) and [DisplayStyleState.scheduleScript]($frontend) to obtain the script reference for a display style on the frontend
+     * and backend respectively.
+     * @see [DisplayStyleState.scheduleScript]($frontend) or [DisplayStyleState.changeRenderTimeline]($frontend) to change a display style's script on the frontend.
      */
     class ScriptReference {
-        constructor(sourceId, script) {
-            this.sourceId = sourceId;
-            this.script = script;
+        /** @internal Use one of the public constructor overloads which forward to this one. */
+        constructor(sourceIdOrScript, scriptIfSourceId) {
+            if (typeof sourceIdOrScript === "string") {
+                assert(scriptIfSourceId instanceof Script);
+                this.sourceId = sourceIdOrScript;
+                this.script = scriptIfSourceId;
+            }
+            else {
+                assert(undefined === scriptIfSourceId);
+                this.script = sourceIdOrScript;
+                this.sourceId = Id64.invalid;
+            }
         }
     }
     RenderSchedule.ScriptReference = ScriptReference;