@itwin/core-common/lib/cjs/FeatureTable.d.ts

iTwin.js components common to frontend and backend

/** @packageDocumentation
 * @module Rendering
 */
import { Id64, Id64String, IndexedValue, IndexMap, UintArray } from "@itwin/core-bentley";
import { GeometryClass } from "./GeometryParams";
/** Describes a discrete entity within a batched [RenderGraphic]($frontend) that can be
 * grouped with other such entities in a [[FeatureTable]].
 * Features roughly correlate to elements: a [Tile]($frontend)'s graphics combines geometry from every
 * [GeometricElement]($backend) that intersects the tile's volume, so each element produces at least one feature.
 * However, an element's geometry stream can contain geometry belonging to multiple different combinations of [SubCategory]($backend) and
 * [[GeometryClass]], so an individual element may produce more than one feature.
 * @see [[FeatureOverrides]] for customizing the appearance of individual features.
 * @public
 */
export declare class Feature {
    readonly elementId: Id64String;
    readonly subCategoryId: Id64String;
    readonly geometryClass: GeometryClass;
    constructor(elementId?: Id64String, subCategoryId?: Id64String, geometryClass?: GeometryClass);
    get isDefined(): boolean;
    get isUndefined(): boolean;
    /** Returns true if this feature is equivalent to the supplied feature. */
    equals(other: Feature): boolean;
    /** Performs ordinal comparison of this feature with another.
     * @param rhs The feature to compare with.
     * @returns zero if the features are equivalent, a negative value if this feature compares as "less than" `rhs`, or a positive value if this feature compares "greater than" `rhs`.
     */
    compare(rhs: Feature): number;
}
/** A [[Feature]] with a modelId identifying the model containing the feature, obtained from a [[RenderFeatureTable]].
 * @public
 */
export interface ModelFeature {
    modelId: Id64String;
    elementId: Id64String;
    subCategoryId: Id64String;
    geometryClass: GeometryClass;
}
/** @public */
export declare namespace ModelFeature {
    /** Create a ModelFeature of [[GeometryClass.Primary]] with all invalid Ids.
     * This is primarily useful for creating a `result` argument for [[RenderFeatureTable.findFeature]] and [[RenderFeatureTable.getFeature]].
     */
    function create(): ModelFeature;
    /** Returns `true` if any of `feature`'s properties differ from the defaults (invalid Ids and [[GeometryClass.Primary]]). */
    function isDefined(feature: ModelFeature): boolean;
    /** @alpha */
    function unpack(packed: PackedFeature, result: ModelFeature, unpackedModelId?: Id64String): ModelFeature;
}
/** Represents a [[Feature]] within a [[RenderFeatureTable]]. This representation is optimized for use on the GPU.
 * @public
 */
export interface PackedFeature {
    modelId: Id64.Uint32Pair;
    elementId: Id64.Uint32Pair;
    subCategoryId: Id64.Uint32Pair;
    geometryClass: GeometryClass;
    /** @alpha */
    animationNodeId: number;
}
/** Represents a [[PackedFeature]] obtained from a [[RenderFeatureTable]], including the index of that feature within the table.
 * @public
 */
export interface PackedFeatureWithIndex extends PackedFeature {
    index: number;
}
/** @public */
export declare namespace PackedFeature {
    /** Create a PackedFeature of [[GeometryClass.Primary]] with all invalid Ids.
     * This is primarily useful for creating a `result` argument for [[RenderFeatureTable.getPackedFeature]].
     */
    function create(): PackedFeature;
    /** Create a PackedFeatureWithIndex of [[GeometryClass.Primary]] with all invalid Ids and an index of zero.
     * This is primarily useful for creating a reusable `output` argument for [[RenderFeatureTable.iterable]].
     */
    function createWithIndex(): PackedFeatureWithIndex;
}
/** Describes the type of a 'batch' of graphics representing multiple [[Feature]]s.
 * The most commonly-encountered batches are Tiles, which can be of either Primary or
 * Classifier type.
 * @public
 * @extensions
 */
export declare enum BatchType {
    /** This batch contains graphics derived from a model's visible geometry. */
    Primary = 0,
    /**
     * This batch contains color volumes which are used to classify a model's visible geometry.
     * The graphics themselves are not rendered to the screen; instead they are rendered to the stencil buffer
     * to resymbolize the primary geometry.
     */
    VolumeClassifier = 1,
    /**
     * This batch contains planar graphics which are used to classify a model's visible geometry.
     * The graphics themselves are not rendered to the screen; instead they are rendered to a texture buffer
     * to resymbolize the primary geometry.
     */
    PlanarClassifier = 2
}
/** Defines a look-up table for [[Feature]]s within a batched [RenderGraphic]($frontend). Consecutive 32-bit
 * indices are assigned to each unique Feature. Primitives within the RenderGraphic can
 * use per-vertex indices to specify the distribution of Features within the primitive. The appearance of individual
 * features can be customized using [[FeatureOverrides]]. Typically a [Tile]($frontend) will contain a feature table
 * identifying the elements whose geometry appears within that tile.
 * @see [[FeatureOverrides]] for customizing the appearance of individual features.
 * @public
 */
export declare class FeatureTable extends IndexMap<Feature> {
    readonly modelId: Id64String;
    readonly type: BatchType;
    /** Construct an empty FeatureTable. */
    constructor(maxFeatures: number, modelId?: Id64String, type?: BatchType);
    /** Returns the maximum number of [[Feature]]s this FeatureTable can contain. */
    get maxFeatures(): number;
    /** Returns true if this table contains at least one [[Feature]] with a valid element and/or subcategory Id. */
    get anyDefined(): boolean;
    /** Returns true if this FeatureTable contains exactly one [[Feature]]. */
    get isUniform(): boolean;
    /** If this FeatureTable contains exactly one [[Feature]], returns that Feature; otherwise returns undefined. */
    get uniform(): Feature | undefined;
    /** Returns true if this FeatureTable is associated with [[BatchType.VolumeClassifier]] geometry. */
    get isVolumeClassifier(): boolean;
    /** Returns true if this FeatureTable is associated with [[BatchType.PlanarClassifier]] geometry. */
    get isPlanarClassifier(): boolean;
    /** Returns the Feature corresponding to the specified index, or undefined if the index is not present. */
    findFeature(index: number): Feature | undefined;
    /** Inserts the specified [[Feature]] at the specified index. This is really only useful when reconstructing a previously-create feature table
     * for which you know the index assigned to each feature.
     */
    insertWithIndex(feature: Feature, index: number): void;
    /** Access the underlying array containing the table's current contents. */
    getArray(): ReadonlyArray<IndexedValue<Feature>>;
    /** Convert this feature table to a representation that can be supplied to [RenderSystem.createBatch]($frontend). */
    pack(): RenderFeatureTable;
}
/** @alpha */
export type ComputeNodeId = (feature: PackedFeatureWithIndex) => number;
/** Representation of a [[FeatureTable]] suitable for use with [RenderSystem.createBatch]($frontend).
 * The [[Feature]]s are represented as [[PackedFeature]]s. The feature table may contain features from multiple [Model]($backend)s.
 * @see [[FeatureTable.pack]] to produce a RenderFeatureTable.
 * @public
 */
export interface RenderFeatureTable {
    /** The "model Id" of the tile tree containing the tile from which this feature table originated.
     * It may be a transient Id if, for example, the tile tree represents a reality model or represents the geometry of multiple
     * persistent models batched together.
     */
    readonly batchModelId: Id64String;
    /** A split representation of [[batchModelId]], to avoid having to constantly having to parse the string. */
    readonly batchModelIdPair: Id64.Uint32Pair;
    /** The number of features in the table; equivalently, one more than the largest feature index. */
    readonly numFeatures: number;
    /** The number of bytes consumed by the feature table, strictly for diagnostic purposes. */
    readonly byteLength: number;
    readonly type: BatchType;
    /** @alpha */
    animationNodeIds?: UintArray;
    /** Get the feature at the specified index. The caller is responsible for validating featureIndex less than numFeatures. */
    getFeature(featureIndex: number, result: ModelFeature): ModelFeature;
    /** Find the feature at the specified index. Returns undefined if featureIndex >= [[numFeatures]]. */
    findFeature(featureIndex: number, result: ModelFeature): ModelFeature | undefined;
    /** Find the Id of the element associated with the feature at the specified index. */
    findElementId(featureIndex: number): Id64String | undefined;
    /** Get the Id of the element associated with the feature at the specified index as a pair of 32-bit integers.
     * The caller is responsible for validating that `featureIndex` is less than [[numFeatures]].
     */
    getElementIdPair(featureIndex: number, out: Id64.Uint32Pair): Id64.Uint32Pair;
    /** Get the feature at the specified index. The caller is responsible for validating featureIndex less than numFeatures. */
    getPackedFeature(featureIndex: number, result: PackedFeature): PackedFeature;
    /** Get an object that provides ordered iteration over all features.
     * @note The `output` object is reused (mutated in place) as the current value on each iteration.
     */
    iterable(output: PackedFeatureWithIndex): Iterable<PackedFeatureWithIndex>;
    /** @alpha */
    populateAnimationNodeIds(computeNodeId: ComputeNodeId, maxNodeId: number): void;
    /** @alpha */
    getAnimationNodeId(featureIndex: number): number;
    /** Get the Id of the model associated with the feature at the specified index.
     * The caller is responsible for validating that `featureIndex` is less than [[numFeatures]].
     * This is more efficient than [[getFeature]] for callers who are only interested in the model Id.
     */
    getModelIdPair(featureIndex: number, out: Id64.Uint32Pair): Id64.Uint32Pair;
}
//# sourceMappingURL=FeatureTable.d.ts.map