/** @packageDocumentation * @module DisplayStyles */ import { CompressedId64Set, Constructor, Id64Set, Id64String } from "@bentley/bentleyjs-core"; import { ClipVector, Plane3dByOriginAndUnitNormal, Point4d, Range1d, Transform, Vector3d, XYAndZ } from "@bentley/geometry-core"; import { RgbColor } from "./RgbColor"; import { FeatureAppearance, FeatureOverrides } from "./FeatureSymbology"; /** 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. * @public */ export declare namespace RenderSchedule { /** Defines how two interpolate between two entries in a [[RenderSchedule.Timeline]]. * @note Currently only Linear and Step are supported. Any other value is treated as Step. * @see [[RenderSchedule.TimelineEntry]]. */ enum Interpolation { /** Each timeline entry's value is discrete - the timeline jumps from one entry's value directly to another. */ Step = 1, /** Given two entries on the timeline and a timepoint in between them, linearly interpolate based on the timepoint's distance between the * two entries. */ Linear = 2 } /** JSON representation of a [[RenderSchedule.TimelineEntry]]. */ interface TimelineEntryProps { /** The time point in seconds in the [Unix Epoch](https://en.wikipedia.org/wiki/Unix_time). */ time: number; /** How to interpolate from this entry to the next entry in the timeline. * Currently, anything other than [[RenderSchedule.Interpolation.Linear]] is treated as [[RenderSchedule.Interpolation.Step]]. * Additional interpolation modes may become supported in the future. */ interpolation?: Interpolation; } /** JSON representation of a [[RenderSchedule.VisibilityEntry]]. */ interface VisibilityEntryProps extends TimelineEntryProps { /** Visibility of the geometry from 0 (invisible) to 100 (fully visible), with intermediate values appearing increasingly less transparent. * Default: 100 (fully visible). */ value?: number; } /** JSON representation of a [[RenderSchedule.ColorEntry]]. */ interface ColorEntryProps extends TimelineEntryProps { /** The color applied to the geometry, with each component specified as an integer in [0, 255]. * e.g., (0, 0, 0) represents black and (255, 255, 255) represents white. * If `undefined`, the geometry is displayed in its actual color. */ value?: { red: number; green: number; blue: number; }; } /** JSON representation of a [[RenderSchedule.CuttingPlane]]. */ interface CuttingPlaneProps { /** (x,y,z) of a point on the plane. */ position: number[]; /** (x, y, z) of the plane direction (towards the clip) */ direction: number[]; /** If true, the clip plane is ignored and the geometry is displayed unclipped. */ visible?: boolean; /** If true, the clip plane is ignored and the geometry is not displayed. */ hidden?: boolean; } /** JSON representation of a [[RenderSchedule.CuttingPlaneEntry]]. */ interface CuttingPlaneEntryProps extends TimelineEntryProps { /** The clip plane, or undefined if the geometry is not clipped. */ value?: CuttingPlaneProps; } /** JSON representation of a [[RenderSchedule.TransformComponents]]. */ interface TransformComponentsProps { /** (x, y, z) of position - applied after rotation. */ position?: number[]; /** Quaternion representing rotation. */ orientation?: number[]; /** (x, y, z) of pivot - applied before rotation. */ pivot?: number[]; } /** JSON representation of a [Transform]($geometry-core) associated with a [[RenderSchedule.TransformEntryProps]]. */ interface TransformProps extends TransformComponentsProps { /** 3 X 4 transformation matrix containing 3 arrays of matrix rows consisting of 4 numbers each: [qx qy qz ax] * where the fourth columnn in each row holds the translation. * `undefined` is equivalent to an identity transform. * This transform is only used if position, orientation, and/or pivot are undefined. */ transform?: number[][]; } /** JSON representation of a [[RenderSchedule.TransformEntry]]. */ interface TransformEntryProps extends TimelineEntryProps { /** The transformation matrix, with `undefined` corresponding to an identity matrix. */ value?: TransformProps; } /** JSON representation of a [[RenderSchedule.Timeline]]. */ interface TimelineProps { /** Timeline controlling the visibility of the associated geometry. */ visibilityTimeline?: VisibilityEntryProps[]; /** Timeline controlling the colors of the associated geometry. */ colorTimeline?: ColorEntryProps[]; /** Timeline applying transforms to the associated geometry. */ transformTimeline?: TransformEntryProps[]; /** Timeline applying [ClipVector]($geometry-core)s to the associated geometry. */ cuttingPlaneTimeline?: CuttingPlaneEntryProps[]; } /** JSON representation of an [[RenderSchedule.ElementTimeline]]. */ interface ElementTimelineProps extends TimelineProps { /** A positive integer that uniquely identifies this timeline among all element timelines in the [[RenderSchedule.Script]]. */ batchId: number; /** The Ids of the elements to which this timeline applies. * @note Prefer the compressed representation - lists of element Ids can be comparatively enormous. * @note For a [[DisplayStyleSettingsProps]] associated with a [DisplayStyleState]($frontend) obtained via [IModelConnection.Views.load]($frontend), * this property will be an empty `CompressedId64Set`. They are omitted to conserve bandwidth and memory because they are not needed for display on the frontend. */ elementIds: Id64String[] | CompressedId64Set; } /** JSON representation of a [[RenderSchedule.ModelTimeline]]. */ interface ModelTimelineProps extends TimelineProps { /** The Id of the [GeometricModelState]($frontend) to which the timeline applies. */ modelId: Id64String; /** @alpha */ realityModelUrl?: string; /** Timelines affecting groups of elements. */ elementTimelines: ElementTimelineProps[]; } /** JSON representation of a [[RenderSchedule.Script]]. */ type ScriptProps = ModelTimelineProps[]; /** Describes the value of some property at a specific point along a [[RenderSchedule.Timeline]]. * @see [[RenderSchedule.VisibilityEntry]] * @see [[RenderSchedule.ColorEntry]] * @see [[RenderSchedule.TransformEntry]] * @see [[RenderSchedule.CuttingPlaneEntry]] */ class TimelineEntry { /** The time point in seconds in the [Unix Epoch](https://en.wikipedia.org/wiki/Unix_time). */ readonly time: number; /** How to interpolate from this entry to the next entry in the timeline. */ readonly interpolation: Interpolation; constructor(props: TimelineEntryProps); toJSON(): TimelineEntryProps; } /** A timeline entry that controls the visibility of the associated geometry. */ class VisibilityEntry extends TimelineEntry { /** The visibility of the geometry at this point on the timeline, in the range [0, 100] where 0 is completely invisible, 100 is completely visible, * and values in between indicate increasing opacity. */ readonly value: number; constructor(props: VisibilityEntryProps); toJSON(): VisibilityEntryProps; } /** A timeline entry controlling the color of the affected geometry. */ class ColorEntry extends TimelineEntry { /** If defined, the color in which to draw the geometry. If undefined, the geometry is drawn in its actual color. */ readonly value: RgbColor | undefined; constructor(props: ColorEntryProps); toJSON(): ColorEntryProps; } /** Describes the components of a [[RenderSchedule.TransformEntry]] as a rotation around a pivot point followed by a translation. */ class TransformComponents { /** Pivot point - applied before rotation. */ readonly pivot: Vector3d; /** Quaternion rotation. */ readonly orientation: Point4d; /** Translation - applied after rotation. */ readonly position: Vector3d; constructor(position: Vector3d, pivot: Vector3d, orientation: Point4d); static fromJSON(props: TransformComponentsProps): TransformComponents | undefined; toJSON(): TransformComponentsProps; } /** A timeline entry that applies rotation, scaling, and/or translation to the affected geometry. */ class TransformEntry extends TimelineEntry { /** The transform matrix to be applied to the geometry, used only if [[components]] is not defined. */ readonly value: Readonly; /** The transform represented as a rotation about a pivot point followed by a translation. If undefined, [[value]] is used instead. */ readonly components?: TransformComponents; constructor(props: TransformEntryProps); toJSON(): TransformEntryProps; } /** Defines a [ClipPlane]($geometry-core) associated with a [[RenderSchedule.CuttingPlaneEntry]]. */ class CuttingPlane { /** A point on the plane. */ readonly position: XYAndZ; /** The direction perpendicular to the plane pointing toward the clip. */ readonly direction: XYAndZ; /** If true, the clip plane is ignored and the geometry is never clipped. */ readonly visible: boolean; /** If true, the clip plane is ignored and the geometry is always clipped. */ readonly hidden: boolean; constructor(props: CuttingPlaneProps); toJSON(): CuttingPlaneProps; } /** A timeline entry that applies a [ClipPlane]($geometry-core) to the affected geometry. */ class CuttingPlaneEntry extends TimelineEntry { /** The definition of the [ClipPlane]($geometry-core), or undefined if this entry applies no clipping. */ readonly value: CuttingPlane | undefined; constructor(props: CuttingPlaneEntryProps); toJSON(): CuttingPlaneEntryProps; } /** Identifies a fractional position along a [[RenderSchedule.Timeline]] between any two [[RenderSchedule.TimelineEntry]]'s within a [[RenderSchedule.TimelineEntryList]]. * @internal */ class Interval { /** The index of the first timeline entry within the list. */ lowerIndex: number; /** The index of the second timeline entry within the list. */ upperIndex: number; /** The normalized distance between the two timeline entries. */ fraction: number; constructor(lower?: number, upper?: number, fraction?: number); init(lower?: number, upper?: number, fraction?: number): void; } /** A list of the [[RenderSchedule.TimelineEntry]] objects within a [[RenderSchedule.Timeline]]. The type parameters are: * - T, a subclass of TimelineEntry with a `value` property specifying the value of the property controlled by the timeline at that entry's time point. * - P, the JSON representation from which T is to be constructed. * - V, the type of `T.value`. */ class TimelineEntryList implements Iterable { private readonly _entries; /** The total time period represented by the entries in this list. */ readonly duration: Range1d; constructor(props: P[], ctor: Constructor); /** The number of entries in the list. */ get length(): number; /** An iterator over the entries in the list. */ [Symbol.iterator](): Iterator; /** Look up an entry by its position in the list. */ getEntry(index: number): T | undefined; /** Look up the value of an entry by its position in the list. */ getValue(index: number): V | undefined; toJSON(): P[]; /** @internal */ findInterval(time: number, interval?: Interval): Interval | undefined; } /** A list of [[RenderSchedule.VisibilityEntry]]s within a [[RenderSchedule.Timeline]]. */ class VisibilityTimelineEntries extends TimelineEntryList { /** Returns the visibility value for the entry at the specified position in the list, or 100 (fully-visible) if no such entry exists. */ getValue(index: number): number; } /** A list of [[RenderSchedule.TransformEntry]]s within a [[RenderSchedule.Timeline]]. */ class TransformTimelineEntries extends TimelineEntryList> { /** Returns the transform for the entry at the specified position in the list, or an identity transform if no such entry exists. */ getValue(index: number): Readonly; } /** Specifies how to animate a set of geometry over time within a [[RenderSchedule.Script]]. * A [[RenderSchedule.Script]] can contain any number of [[RenderSchedule.Timeline]]s, each affecting different sets of geometry. * @see [[RenderSchedule.ElementTimeline]] and [[RenderSchedule.ModelTimeline]]. */ class Timeline { /** Sequence controlling the visibility of the geometry. */ readonly visibility?: VisibilityTimelineEntries; /** Sequence controlling the color of the geometry. */ readonly color?: TimelineEntryList; /** Sequence controlling the position, orientation, and/or scale of the geometry. */ readonly transform?: TransformTimelineEntries; /** Sequence controlling how the geometry is clipped. */ readonly cuttingPlane?: TimelineEntryList; /** The total time period represented by this timeline. */ readonly duration: Range1d; constructor(props: TimelineProps); toJSON(): TimelineProps; /** Get the visibility of the geometry at the specified time point. */ getVisibility(time: number): number; /** Get the color of the geometry at the specified time point, or undefined if the color is not overridden at that time point. */ getColor(time: number): RgbColor | undefined; /** Get the transform applied to the geometry at the specified time point. */ getAnimationTransform(time: number): Readonly; /** Get the clipping plane applied to the geometry at the specified time point, or undefined if the geometry is unclipped at that time point. */ getCuttingPlane(time: number): Plane3dByOriginAndUnitNormal | undefined; /** Create a ClipVector from the [[RenderSchedule.CuttingPlane]] applied to the geometry at the specified time point, if any. */ getClipVector(time: number): ClipVector | undefined; /** @internal */ protected getFeatureAppearance(visibility: number, time: number): FeatureAppearance | undefined; } /** Specifies how to animate the geometry belonging to a set of [GeometricElement]($backend)s as part of a [[RenderSchedule.Script]]. */ class ElementTimeline extends Timeline { /** A positive integer that uniquely identififes this timeline among all ElementTimelines in the [[RenderSchedule.Script]]. */ readonly batchId: number; private readonly _elementIds; private constructor(); static fromJSON(props?: ElementTimelineProps): ElementTimeline; toJSON(): ElementTimelineProps; /** @internal */ static getElementIds(ids: Id64String[] | CompressedId64Set): Iterable; /** The Ids of the elements controlled by this timeline. */ get elementIds(): Iterable; /** True if this timeline affects the color or transparency of the elements. */ get containsFeatureOverrides(): boolean; /** If true, applying this timeline requires special tiles to be generated in which groups of elements are batched into nodes. * @internal */ get requiresBatching(): boolean; /** True if this timeline affects the position, orientation, or scale of the elements. */ get containsTransform(): boolean; /** @internal */ addSymbologyOverrides(overrides: FeatureOverrides, time: number): void; } /** Specifies how to animate the geometry within a [GeometricModel]($backend) as part of a [[RenderSchedule.Script]]. */ class ModelTimeline extends Timeline { /** The Id of the [GeometricModel]($backend) to be animated. */ readonly modelId: Id64String; /** @internal */ readonly realityModelUrl?: string; /** Timelines specifying how to animate groups of [GeometricElement]($backend)s within the model. */ readonly elementTimelines: ReadonlyArray; /** @internal */ readonly transformBatchIds: ReadonlyArray; /** True if this timeline affects the color or transparency of the geometry. */ readonly containsFeatureOverrides: boolean; /** True if this timeline applies clipping to the model. */ readonly containsModelClipping: boolean; /** If true, applying this timeline requires special tiles to be generated in which groups of elements are batched into nodes. * @internal */ readonly requiresBatching: boolean; /** True if this timeline affects the position, orientation, or scale of the geometry. */ readonly containsTransform: boolean; private constructor(); static fromJSON(props?: ModelTimelineProps): ModelTimeline; toJSON(): ModelTimelineProps; /** Look up the element timeline with the specified batch Id. */ findByBatchId(batchId: number): ElementTimeline | undefined; /** @internal */ addSymbologyOverrides(overrides: FeatureOverrides, time: number): void; /** Obtain the transform applied to the model at the specified time point, if any. */ getTransform(batchId: number, time: number): Readonly | undefined; } /** Specifies how to animate the contents of a [ViewState]($frontend) over time. The script contains any number of [[RenderSchedule.ModelTimeline]]s, each describing how * to animate one of the models in the view. * @see [RenderTimeline]($backend) to create an [Element]($backend) to host a script. * @see [[DisplayStyleSettings.renderTimeline]] to associate a [RenderTimeline]($backend)'s script with a [DisplayStyle]($backend). * @see [DisplayStyleState.scheduleScript]($frontend) to obtain the script associated with a display style. * @see [[RenderSchedule.ScriptBuilder]] to define a new script. */ class Script { /** Timelines specifying how to animate individual models within the view. */ readonly modelTimelines: ReadonlyArray; /** True if this script applies clipping to any models. */ readonly containsModelClipping: boolean; /** If true, applying this timeline requires special tiles to be generated in which groups of elements are batched into nodes. * @internal */ readonly requiresBatching: boolean; /** True if this script affects the position, orientation, or scale of the geometry. */ readonly containsTransform: boolean; /** True if this script affects the color or transparency of the geometry. */ readonly containsFeatureOverrides: boolean; /** The total time period over which this script animates. */ readonly duration: Range1d; protected constructor(props: Readonly); static fromJSON(props: Readonly): Script | undefined; toJSON(): ScriptProps; /** Look up the timeline that animates the specified model, if any. */ find(modelId: Id64String): ModelTimeline | undefined; /** @internal */ getTransformBatchIds(modelId: Id64String): ReadonlyArray | undefined; /** @internal */ getTransform(modelId: Id64String, batchId: number, time: number): Readonly | undefined; /** @internal */ addSymbologyOverrides(overrides: FeatureOverrides, time: number): void; /** Used by collectPredecessorIds methods of RenderTimeline and DisplayStyle. * @internal */ discloseIds(ids: Id64Set): void; } /** 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. */ class ScriptReference { /** The Id of the [RenderTimeline]($backend) or [DisplayStyle]($backend) element that hosts the script. */ readonly sourceId: Id64String; /** The script. */ readonly script: Script; constructor(sourceId: Id64String, script: Script); } /** Used as part of a [[RenderSchedule.ScriptBuilder]] to define a [[RenderSchedule.Timeline]]. * @see [[RenderSchedule.ElementTimelineBuilder]] and [[RenderSchedule.ModelTimelineBuilder]]. */ class TimelineBuilder { /** Timeline controlling visibility. */ visibility?: VisibilityEntryProps[]; /** Timeline controlling color. */ color?: ColorEntryProps[]; /** Timeline controlling position and orientation. */ transform?: TransformEntryProps[]; /** Timeline controlling clipping. */ cuttingPlane?: CuttingPlaneEntryProps[]; /** Append a new [[RenderSchedule.VisibilityEntry]] to the timeline. */ addVisibility(time: number, visibility: number | undefined, interpolation?: Interpolation): void; /** Append a new [[RenderSchedule.ColorEntry]] to the timeline. */ addColor(time: number, color: RgbColor | { red: number; green: number; blue: number; } | undefined, interpolation?: Interpolation): void; /** Append a new [[RenderSchedule.CuttingPlaneEntry]] to the timeline. */ addCuttingPlane(time: number, plane: { position: XYAndZ; direction: XYAndZ; visible?: boolean; hidden?: boolean; } | undefined, interpolation?: Interpolation): void; /** Append a new [[RenderSchedule.TransformEntry]] to the timeline. */ addTransform(time: number, transform: Transform | undefined, components?: { pivot: XYAndZ; orientation: Point4d; position: XYAndZ; }, interpolation?: Interpolation): void; /** Obtain the JSON representation of the [[RenderSchedule.Timeline]] produced by this builder. * @see [[RenderSchedule.ScriptBuilder.finish]] to obtain the JSON for the entire [[RenderSchedule.Script]]. */ finish(): TimelineProps; } /** As part of a [[RenderSchedule.ScriptBuilder]], assembles a [[RenderSchedule.ElementTimeline]]. * @see [[RenderSchedule.ModelTimelineBuilder.addElementTimeline]]. */ class ElementTimelineBuilder extends TimelineBuilder { /** A positive integer that uniquely identifies this timeline among all element timelines in the [[RenderSchedule.Script]]. * [[RenderSchedule.ScriptBuilder]] ensures each ElementTimelineBuilder receives a unique batch Id. */ readonly batchId: number; /** The compressed set of Ids of the elements affected by this timeline. */ readonly elementIds: CompressedId64Set; /** Constructor - typically not used directly. * @see [[RenderSchedule.ModelTimelineBuilder.addElementTimeline]] to create an ElementTimelineBuilder. */ constructor(batchId: number, elementIds: CompressedId64Set); /** Obtain the JSON representation of the [[RenderSchedule.ElementTimeline]] produced by this builder. * @see [[RenderSchedule.ScriptBuilder.finish]] to obtain the JSON for the entire [[RenderSchedule.Script]]. */ finish(): ElementTimelineProps; } /** As part of a [[RenderSchedule.ScriptBuilder, assembles a [[RenderSchedule.ModelTimeline]]. * @see [[RenderSchedule.ScriptBuilder.addModelTimeline]]. */ class ModelTimelineBuilder extends TimelineBuilder { /** The Id of the model affected by this timeline. */ readonly modelId: Id64String; /** @internal */ realityModelUrl?: string; private readonly _obtainNextBatchId; private readonly _elements; /** Constructor - typically not used directly. * @see [[RenderSchedule.ScriptBuilder.addModelTimeline]] to create a ModelTimelineBuilder. */ constructor(modelId: Id64String, obtainNextBatchId: () => number); /** Add a new [[RenderSchedule.ElementTimeline]] to be applied to the specified elements. * This function will sort and compress the Ids if they are not already compressed. * */ addElementTimeline(elementIds: CompressedId64Set | Iterable): ElementTimelineBuilder; /** Obtain the JSON representation of the [[RenderSchedule.ModelTimeline]] produced by this builder. * @see [[RenderSchedule.ScriptBuilder.finish]] to obtain the JSON for the entire [[RenderSchedule.Script]]. */ finish(): ModelTimelineProps; } /** Assembles the JSON representation for a new [[RenderSchedule.Script]]. As an extremely simple example, the following code produces a script that changes the color of a single element: * ```ts * const script = new ScriptBuilder(); * const model = script.addModelTimeline("0x123"); * const element = model.addElementTimeline([ "0x456" ]); * element.addColor(Date.now(), new RgbColor(0xff, 0x7f, 0)); * const scriptProps = script.finish(); * ``` */ class ScriptBuilder { private _nextBatchId; private readonly _models; /** Add a new [[RenderSchedule.ModelTimeline]] to be applied to the specified model. */ addModelTimeline(modelId: Id64String): ModelTimelineBuilder; /** Obtain the JSON representation of the [[RenderSchedule.Script]] produced by this builder. * @see [RenderTimeline.scriptProps]($backend) to assign the new script to a RenderTimeline element. */ finish(): ScriptProps; } } //# sourceMappingURL=RenderSchedule.d.ts.map