@itwin/core-common

/** @packageDocumentation * @module Rendering */ import { Id64, Id64String } from "@itwin/core-bentley"; import { BatchType, Feature } from "./FeatureTable"; import { ColorDef } from "./ColorDef"; import { GeometryClass } from "./GeometryParams"; import { LinePixels } from "./LinePixels"; import { RgbColor, RgbColorProps } from "./RgbColor"; import { SubCategoryOverride } from "./SubCategoryOverride"; /** JSON representation of a [[FeatureAppearance]]. * @public * @extensions */ export interface FeatureAppearanceProps { /** See [[FeatureAppearance.rgb]]. */ rgb?: RgbColorProps; /** See [[FeatureAppearance.lineRgb]]. */ lineRgb?: RgbColorProps | false; /** See [[FeatureAppearance.weight]]. */ weight?: number; /** See [[FeatureAppearance.transparency]]. */ transparency?: number; /** See [[FeatureAppearance.lineTransparency]]. */ lineTransparency?: number | false; /** See [[FeatureAppearance.viewDependentTransparency]]. */ viewDependentTransparency?: true; /** See [[FeatureAppearance.linePixels]]. */ linePixels?: LinePixels; /** See [[FeatureAppearance.ignoresMaterial]]. */ ignoresMaterial?: true; /** See [[FeatureAppearance.nonLocatable]]. */ nonLocatable?: true; /** See [[FeatureAppearance.emphasized]]. */ emphasized?: true; } /** Defines overrides for selected aspects of a [[Feature]]'s symbology. * Any member defined in the appearance overrides that aspect of symbology for all [[Feature]]s to which the appearance is applied. * * The [[rgb]] and [[transparency]] overrides, if defined, apply to all geometry by default. * However, the color and transparency of "linear" geometry can optionally be controlled independently from the rest of the geometry via [[lineRgb]] and [[lineTransparency]]. * Linear geometry consists of any of the following: * - Curves and line strings; * - Points and point strings; and * - The outlines of planar regions. * The edges of 3d surfaces like spheres are not considered linear geometry. * * @see [[FeatureOverrides]] to customize the appearance of multiple features. * @public */ export declare class FeatureAppearance { /** Overrides the feature's color. * If [[lineRgb]] is `undefined`, this color also applies to linear geometry. */ readonly rgb?: RgbColor; /** If defined, overrides the color of linear geometry independently of [[rgb]]. * If `false`, linear geometry draws using its normal color; otherwise, it uses the specified color. */ readonly lineRgb?: RgbColor | false; /** The width of lines and edges in pixels as an integer in [1, 31]. */ readonly weight?: number; /** The transparency in the range [0, 1] where 0 indicates fully opaque and 1 indicates fully transparent. * If [[lineTransparency]] is `undefined`, this transparency also applies to linear geometry. * @see [[viewDependentTransparency]] for details on how this override interacts with the [DisplayStyle]($backend). */ readonly transparency?: number; /** If defined, overrides the transparency of linear geometry independently of [[transparency]]. * If `false`, linear geometry draws using its normal transparency; otherwise, it uses the specified transparency. * @see [[viewDependentTransparency]] for details on how this override interacts with the [DisplayStyle]($backend). */ readonly lineTransparency?: number | false; /** The pixel pattern applied to lines and edges. */ readonly linePixels?: LinePixels; /** If true, don't apply the [[RenderMaterial]] to the feature's surfaces. */ readonly ignoresMaterial?: true; /** If true, the feature will not be drawn when using [Viewport.readPixels]($frontend), meaning [Tool]($frontend)s will not be able to interact with it. */ readonly nonLocatable?: true; /** If true, the feature will be rendered using the [[Hilite.Settings]] defined by [Viewport.emphasisSettings]($frontend) to make it stand out. */ readonly emphasized?: true; /** If true, then [[transparency]] and/or [[lineTransparency]] will only be applied if [[ViewFlags.transparency]] is enabled and the current [[RenderMode]] supports transparency. * Default: false, meaning the transparency will be applied regardless of view flags or render mode. * This property has no effect if this appearance does not override transparency. */ readonly viewDependentTransparency?: true; /** An appearance that overrides nothing. */ static readonly defaults: FeatureAppearance; static fromJSON(props?: FeatureAppearanceProps): FeatureAppearance; /** Create a FeatureAppearance that overrides only the RGB color. * @note The transparency component of the ColorDef is ignored. */ static fromRgb(color: ColorDef): FeatureAppearance; /** Create a FeatureAppearance that overrides the RGB and transparency. * The appearance's transparency is derived from the transparency component of the ColorDef. */ static fromRgba(color: ColorDef, viewDependentTransparency?: boolean): FeatureAppearance; /** Create a FeatureAppearance that overrides only the transparency */ static fromTransparency(transparencyValue: number, viewDependent?: boolean): FeatureAppearance; /** Create a FeatureAppearance with overrides corresponding to those defined by the supplied SubCategoryOverride. * @note Subcategory overrides set [[viewDependentTransparency]] to `true`. */ static fromSubCategoryOverride(ovr: SubCategoryOverride): FeatureAppearance; /** Returns true if this appearance does not override any aspects of symbology. */ get matchesDefaults(): boolean; get overridesRgb(): boolean; get overridesTransparency(): boolean; get overridesLinePixels(): boolean; get overridesWeight(): boolean; /** Get the color that will be applied to linear geometry, or undefined if not overridden. * This is the same as [[rgb]] if [[lineRgb]] is `undefined`. */ getLineRgb(): RgbColor | undefined; /** Get the transparency that will be applied to linear geometry, or undefined if not overridden. * This is the same as [[transparency]] if [[lineTransparency]] is `undefined`. */ getLineTransparency(): number | undefined; get overridesSymbology(): boolean; get overridesNonLocatable(): boolean; get isFullyTransparent(): boolean; /** Returns true if any aspect of the appearance is overridden (i.e., if any member is not undefined). */ get anyOverridden(): boolean; equals(other: FeatureAppearance): boolean; toJSON(): FeatureAppearanceProps; /** Convert this appearance to JSON, and override any properties explicitly specified by `changedProps` in the result. * Example: * ```ts * const base = FeatureAppearance.fromRgba(ColorDef.white); // transparency=0, rgb=white * const clone = base.cloneProps({ transparency: undefined, weight: 5 }); // transparency=undefined, rgb=white, weight=5 * ``` * @see [[FeatureAppearance.clone]]. */ cloneProps(changedProps: FeatureAppearanceProps): FeatureAppearanceProps; /** Create a copy of this appearance, overriding any properties explicitly specified by `changedProps`. * Example: * ```ts * const base = FeatureAppearance.fromRgba(ColorDef.white); // transparency=0, rgb=white * const clone = base.clone({ transparency: undefined, weight: 5 }); // transparency=undefined, rgb=white, weight=5 * ``` * @see [[FeatureAppearance.cloneProps]]. */ clone(changedProps: FeatureAppearanceProps): FeatureAppearance; /** Produce a FeatureAppearance from the supplied appearance in which any aspect not defined by the base appearance is overridden by this appearance. */ extendAppearance(base: FeatureAppearance): FeatureAppearance; protected constructor(props: FeatureAppearanceProps); } /** Interface adopted by an object that can supply a [[FeatureAppearance]] given a low-level description of a [[Feature]]. * @see [[FeatureOverrides]] for the commonly-used implementation. * @see [[FeatureAppearanceProvider]] to supplement the appearance supplied by this interface. * @public * @extensions */ export interface FeatureAppearanceSource { /** Supplies the desired appearance overrides for the specified [[Feature]], or `undefined` if the feature should not be drawn. * The feature is described by its components for efficiency reasons. * @param elemLo The lower 32 bits of the feature's element Id. * @param elemHi The upper 32 bits of the feature's element Id. * @param subcatLo The lower 32 bits of the feature's subcategory Id. * @param subcatHi The upper 32 bits of the feature's subcategory Id. * @param geomClass The geometry class of the feature. * @param modelLo The lower 32 bits of the feature's model Id. * @param modelHi The upper 32 bits of the feature's model Id. * @param type The type of batch to which the feature belongs. * @param animationNodeId The Id of the corresponding node in the [[RenderSchedule]], or `0` if none. * @returns The desired appearance overrides, or `undefined` to indicate the feature should not be displayed. * @see [Id64.isValidUint32Pair]($core-bentley) to determine if the components of an [Id64String]($core-bentley) represent a valid Id. */ getAppearance(elemLo: number, elemHi: number, subcatLo: number, subcatHi: number, geomClass: GeometryClass, modelLo: number, modelHi: number, type: BatchType, animationNodeId: number): FeatureAppearance | undefined; } /** Common options for [[FeatureOverrides.override]]. * @public */ export interface OverrideFeatureAppearanceOptions { /** Specifies the aspects of the [[Feature]]'s appearance to be overridden. */ appearance: FeatureAppearance; /** Specifies what to do if a [[FeatureAppearance]] has already been configured for the specified element, model, or subcategory by a previous call to [[FeatureOverrides.override]]. * - "subsume" (the default): Merge the two appearances using the logic described by [[FeatureAppearance.extendAppearance]] such that any aspect overridden by the existing appearance will be overwritten * if also overridden by [[appearance]]. * - The resulting appearance is computed as `existingAppearance.extendAppearance(newAppearance)`. * - "extend": Merge the two appearances using the logic described by [[FeatureAppearance.extendAppearance]] such that any aspect overridden by [[appearance]] will only * apply if that aspect is not already overridden by a previous appearance. * - The resulting appearance is computed as `newAppearance.extendAppearance(existingAppearance)`. * - "replace": Completely replace the existing appearance with [[appearance]]. * - "skip": Keep the existing appearance. */ onConflict?: "extend" | "subsume" | "replace" | "skip"; } /** Options for using [[FeatureOverrides.override]] to override the appearance of a [GeometricModel]($backend). * @public */ export interface OverrideModelAppearanceOptions extends OverrideFeatureAppearanceOptions { /** The Id of the model whose appearance is to be overridden. */ modelId: Id64String; elementId?: never; subCategoryId?: never; } /** Options for using [[FeatureOverrides.override]] to override the appearance of a [GeometricElement]($backend). * @public */ export interface OverrideElementAppearanceOptions extends OverrideFeatureAppearanceOptions { /** The Id of the element whose appearance is to be overridden. */ elementId: Id64String; modelId?: never; subCategoryId?: never; } /** Options for using [[FeatureOverrides.override]] to override the appearance of a [SubCategory]($backend). * @public */ export interface OverrideSubCategoryAppearanceOptions extends OverrideFeatureAppearanceOptions { /** The Id of the subcategory whose appearance is to be overridden. */ subCategoryId: Id64String; modelId?: never; elementId?: never; } /** Arguments supplied to [[FeatureOverrides.override]]. * @public */ export type OverrideFeatureAppearanceArgs = OverrideElementAppearanceOptions | OverrideModelAppearanceOptions | OverrideSubCategoryAppearanceOptions; /** Arguments provided to a function of type [[IgnoreAnimationOverrides]]. * @see [[FeatureOverrides.ignoreAnimationOverrides]] to register such a function. * @public */ export interface IgnoreAnimationOverridesArgs { /** The Id of the element under consideration. * @see [Id64.fromUint32Pair]($bentley) to convert a Uint32Pair into an [Id64String]($bentley), if needed. */ readonly elementId: Readonly<Id64.Uint32Pair>; /** The [[RenderSchedule.ElementTimeline.batchId]] identifying the [[RenderSchedule.ElementTimeline]] to which the element under consideration belongs. */ readonly animationNodeId: number; } /** A function that can be supplied to [[FeatureOverrides.ignoreAnimationOverrides]] to indicate whether the color or transparency overrides defined * by the view's [[RenderSchedule.Script]] should be ignored. The arguments describe the element under consideration. The function should return true if that * element should not have its color or transparency modified by the schedule script. * @public */ export type IgnoreAnimationOverrides = (args: IgnoreAnimationOverridesArgs) => boolean; /** Specifies how to customize the appearance of individual [[Feature]]s, typically within the context of a [Viewport]($frontend). * Individual aspects of a feature's appearance - like visibility, color, and transparency - are overridden by supplying a [[FeatureAppearance]]. * Those overrides can be specified on the basis of the feature's model, element, and/or subcategory. A default set of overrides can also be specified to * apply to the appearance of any feature not otherwise overridden. * * It is possible to override multiple aspects of a feature on different bases. For example, you might specify that all features belonging to subcategory "A" should be drawn in red, * and that all features belonging to model "B" should be drawn 50% transparent. In this case, a feature belonging to both subcategory "A" and model "B" will be drawn as 50% transparent red - * the separate overrides are combined to produce the feature's overall appearance. * * In the case of conflicts, there is an order of precedence: * - Model overrides take highest precedence. * - Element overrides are of higher precedence than subcategory and animation overrides. * - Overrides applied by a [[RenderSchedule.Script]]'s [[RenderSchedule.ElementTimeline]] are of higher precedence than subcategory overrides, but can be suppressed on a per-element basis via [[ignoreAnimationOverrides]]. * - Subcategory overrides have lowest precedence. * * For example, you might specify that all features belonging to subcategory "A" should be drawn in red, and all those belonging to model "B" should be drawn in green. * Then a feature belonging to subcategory "A" and model "B" will be drawn in green, because the model overrides take precedence. * * Instances of this class are not typically instantiated by an application directly; instead, an application can implement a [FeatureOverrideProvider]($frontend) * that augments the overrides supplied by a viewport. * * @see [FeatureSymbology.Overrides]($frontend) to create overrides specific to a [Viewport]($frontend) or [ViewState]($frontend). * @see [FeatureOverrideProvider]($frontend) to customize the appearance of features within a [Viewport]($frontend). * @public */ export declare class FeatureOverrides implements FeatureAppearanceSource { /** @internal */ private readonly _ignoreAnimationOverrides; /** Ids of elements that should never be drawn. This takes precedence over [[alwaysDrawn]]. @internal */ private readonly _neverDrawn; /** Ids of elements that should always be drawn. [[neverDrawn]] takes precedence over this set. @internal */ private readonly _alwaysDrawn; /** If true, no elements *except* those defined in the "always drawn" set will be drawn. * @see [[setAlwaysDrawn]] */ isAlwaysDrawnExclusive: boolean; /** If true, the always-drawn elements are drawn even if their subcategories are not visible. * @see [[setAlwaysDrawn]] */ alwaysDrawnIgnoresSubCategory: boolean; /** If true, all subcategories are considered visible. This is used for drawing sheets via section callouts in the absence of an actual sheet view. */ ignoreSubCategory: boolean; /** Overrides applied to any feature not explicitly overridden. @internal */ private _defaultOverrides; /** Whether construction geometry should be drawn. */ protected _constructions: boolean; /** Whether dimensions should be drawn. */ protected _dimensions: boolean; /** Whether area patterns should be drawn. */ protected _patterns: boolean; /** Whether line weights should be applied. If false, all lines are rendered 1-pixel wide. */ protected _lineWeights: boolean; /** Overrides applied to all elements belonging to each model. @internal */ private readonly _modelOverrides; /** Overrides applied to specific elements. */ protected readonly _elementOverrides: Id64.Uint32Map<FeatureAppearance>; /** Overrides applied to geometry belonging to each subcategory. */ protected readonly _subCategoryOverrides: Id64.Uint32Map<FeatureAppearance>; /** The set of displayed subcategories. Geometry belonging to subcategories not included in this set will not be drawn. */ protected readonly _visibleSubCategories: Id64.Uint32Set; /** Display priorities assigned to subcategories, possibly overridden by display style. Only applicable for plan projection models. */ protected readonly _subCategoryPriorities: Id64.Uint32Map<number>; /** Per-model, a set of subcategories whose visibility should be inverted for elements within that model. * Populated by Viewport. */ protected readonly _modelSubCategoryOverrides: Id64.Uint32Map<Id64.Uint32Set>; /** Ids of animation nodes that should never be drawn. */ readonly neverDrawnAnimationNodes: Set<number>; /** Mapping of animation node Ids to overrides applied to the corresponding animation nodes. * @internal */ readonly animationNodeOverrides: Map<number, FeatureAppearance>; /** Accepts a criterion that determines whether color and transparency overrides originating from the view's [[RenderSchedule.Script]] should be ignored for a given element. * The function receives a description of the element in question and returns `true` if the script's overrides should be ignored. * Any number of such functions can be registered; if any one of them returns `true`, the script's overrides are not applied to the specified element. * * For example, applications commonly emphasize a set of elements by applying a [[FeatureAppearance.emphasized]] override to them, and specifying a highly-transparent * default appearance to de-emphasize the rest of the elements in the view. If some of the de-emphasized elements' appearances are also being overridden by the schedule script, then * they won't appear de-emphasized, making it difficult for the emphasized elements to stand out. In situations like this, [FeatureOverrideProvider]($frontend)s like [EmphasizeElements]($frontend) can register an [[IgnoreAnimationOverrides]] function that returns true if the element in question is not in the set of emphasized elements. */ ignoreAnimationOverrides(ignore: IgnoreAnimationOverrides): void; /** Overrides applied to features for which no other overrides are defined */ get defaultOverrides(): FeatureAppearance; /** Whether or not line weights are applied. If false, all lines are drawn with a weight of 1. */ get lineWeights(): boolean; /** A set of elements that are always invisible. * @note If an element is present in both `alwaysDrawn` and [[neverDrawn]], it will not be displayed - `neverDrawn` takes precedence. */ get neverDrawn(): Id64.Uint32Set; /** A set of elements that are unconditionally displayed. * @see [[isAlwaysDrawnExclusive]] to specify that *only* elements in this set will be displayed. * @note If an element is present in both `alwaysDrawn` and [[neverDrawn]], it will not be displayed - `neverDrawn` takes precedence. */ get alwaysDrawn(): Id64.Uint32Set; private isNeverDrawn; private isAlwaysDrawn; /** Returns true if the [SubCategory]($backend) specified by Id is in the set of visible subcategories. */ isSubCategoryVisible(idLo: number, idHi: number): boolean; /** Returns true if the [SubCategory]($backend) specified by Id is in the set of visible subcategories in the context of the specified model. */ isSubCategoryVisibleInModel(subcatLo: number, subcatHi: number, modelLo: number, modelHi: number): boolean; private getModelOverrides; private getElementAnimationOverrides; private getElementOverrides; private getSubCategoryOverrides; /** Add a [SubCategory]($backend) to the set of visible subcategories. */ setVisibleSubCategory(id: Id64String): void; /** Specify the Id of an element that should never be drawn. */ setNeverDrawn(id: Id64String): void; /** Specify the Id of an element that should always be drawn. */ setAlwaysDrawn(id: Id64String): void; /** Specify the Id of a animation node that should never be drawn. */ setAnimationNodeNeverDrawn(id: number): void; /** Specify the Ids of elements that should never be drawn. */ setNeverDrawnSet(ids: Iterable<Id64String>): void; /** Specify the Ids of elements that should always be drawn. */ setAlwaysDrawnSet(ids: Iterable<Id64String>, exclusive: boolean, ignoreSubCategory?: boolean): void; /** Returns the feature's appearance overrides, or undefined if the feature is not visible. */ getFeatureAppearance(feature: Feature, modelId: Id64String, type?: BatchType, animationNodeId?: number): FeatureAppearance | undefined; private static readonly _weight1Appearance; /** Returns a feature's appearance overrides, or undefined if the feature is not visible. * Takes Id64s as pairs of unsigned 32-bit integers for efficiency, because that is how they are stored by the PackedFeatureTable associated with each batch of graphics. * @see [[getFeatureAppearance]] for an equivalent function that accepts [Id64String]($core-bentley)s instead of integer pairs. */ getAppearance(elemLo: number, elemHi: number, subcatLo: number, subcatHi: number, geomClass: GeometryClass, modelLo: number, modelHi: number, type: BatchType, animationNodeId: number): FeatureAppearance | undefined; /** Classifiers behave totally differently...in particular they are never invisible unless fully-transparent. */ private getClassifierAppearance; /** Return whether geometry of the specified class should be drawn. * @see [[ViewFlags.constructions]], [[ViewFlags.dimensions]], and [[ViewFlags.patterns]]. */ isClassVisible(geomClass: GeometryClass): boolean; /** Specify overrides for all elements belonging to a specified [GeometricModel]($backend), or all geometry belonging to a specified [GeometricElement]($backend) or [SubCategory]($backend). */ override(args: OverrideFeatureAppearanceArgs): void; /** Specify overrides for all geometry originating from the specified animation node. * @param id The Id of the animation node. * @param app The symbology overrides. * @note These overrides do not take precedence over element overrides. */ overrideAnimationNode(id: number, app: FeatureAppearance): void; /** Defines a default appearance to be applied to any [[Feature]] *not* explicitly overridden. * @param appearance The symbology overrides. * @param replaceExisting Specifies whether to replace the current default overrides if they are already defined. */ setDefaultOverrides(appearance: FeatureAppearance, replaceExisting?: boolean): void; /** Get the display priority of a subcategory. This is only relevant when using [[PlanProjectionSettings]]. */ getSubCategoryPriority(idLo: number, idHi: number): number; /** Adds all fully transparent elements to the _neverDrawn set. This is used for BatchedModels planar masks. */ addInvisibleElementOverridesToNeverDrawn(): void; /** Construct a new Overrides that overrides nothing. * @see [FeatureSymbology.Overrides]($frontend) to construct overrides based on a [ViewState]($frontend) or [Viewport]($frontend). */ constructor(); /** Returns true if geometry belonging to the specified subcategory will be drawn. */ isSubCategoryIdVisible(id: Id64String): boolean; /** Returns the overrides applied to geometry belonging to the specified model, if any such are defined. */ getModelOverridesById(id: Id64String): FeatureAppearance | undefined; /** Returns the overrides applied to geometry belonging to the specified element, if any such are defined. */ getElementOverridesById(id: Id64String): FeatureAppearance | undefined; /** Returns the overrides applied to geometry belonging to the specified subcategory, if any such are defined. */ getSubCategoryOverridesById(id: Id64String): FeatureAppearance | undefined; /** Returns true if the specified Feature will be drawn. */ isFeatureVisible(feature: Feature): boolean; } /** Interface adopted by an object that can supply the [[FeatureAppearance]] supplied by a [[FeatureAppearanceSource]]. * This is useful for selectively overriding or agumenting a [Viewport]($frontend)'s symbology overrides. * A typical implementation will invoke [[FeatureAppearanceSource.getAppearance]] and customize the returned appearance. * @see [[FeatureAppearanceProvider.chain]] to chain two providers together. * @public * @extensions */ export interface FeatureAppearanceProvider { /** Supply the desired appearance overrides for the specified [[Feature]], or `undefined` if the feature should not be drawn. * The feature is described by its components for efficiency reasons. * @param source The base symbology overrides, e.g., typically defined by a [Viewport]($frontend). * @param elemLo The lower 32 bits of the feature's element Id. * @param elemHi The upper 32 bits of the feature's element Id. * @param subcatLo The lower 32 bits of the feature's subcategory Id. * @param subcatHi The upper 32 bits of the feature's subcategory Id. * @param geomClass The geometry class of the feature. * @param modelLo The lower 32 bits of the feature's model Id. * @param modelHi The upper 32 bits of the feature's model Id. * @param type The type of batch to which the feature belongs. * @param animationNodeId The Id of the corresponding node in the [[RenderSchedule]], or `0` if none. * @returns The desired appearance overrides, or `undefined` to indicate the feature should not be displayed. * @see [[FeatureAppearanceSource.getAppearance]] to forward the request to the source. * @see [Id64.isValidUint32Pair]($core-bentley) to determine if the components of an [Id64String]($core-bentley) represent a valid Id. */ getFeatureAppearance(source: FeatureAppearanceSource, elemLo: number, elemHi: number, subcatLo: number, subcatHi: number, geomClass: GeometryClass, modelLo: number, modelHi: number, type: BatchType, animationNodeId: number): FeatureAppearance | undefined; } /** @public */ export declare namespace FeatureAppearanceProvider { /** Create a provider that obtains each feature's appearance from the source, and if the feature is visible, modifies the appearance. * @param supplementAppearance A function accepting the feature's base appearance and returning a supplemental appearance. * @public */ function supplement(supplementAppearance: (appearance: FeatureAppearance) => FeatureAppearance): FeatureAppearanceProvider; /** Chain two FeatureAppearanceProviders together such that `first`'s `getFeatureAppearance` function is applied before `second`'s. * If `second` invokes `source.getAppearance()`, the returned appearance will include any modifications applied by `first`. * @public */ function chain(first: FeatureAppearanceProvider, second: FeatureAppearanceProvider): FeatureAppearanceProvider; } //# sourceMappingURL=FeatureSymbology.d.ts.map