@itwin/core-common

/** @packageDocumentation * @module DisplayStyles */ import { Mutable, NonFunctionPropertiesOf } from "@itwin/core-bentley"; /** Enumerates the available basic rendering modes, as part of a [DisplayStyle]($backend)'s [[ViewFlags]]. * The rendering mode broadly affects various aspects of the display style - in particular, whether and how surfaces and their edges are drawn. * @public * @extensions */ export declare enum RenderMode { /** Renders only the edges of surfaces, with exceptions for planar regions based on their [[FillFlags]]. * Lighting (and by extension, shadows) is not applied. * [[HiddenLine.Settings]] are not applied - edges use the elements' width, style, and color. * [[ViewFlags.hiddenEdges]] is ignored - hidden edges are never displayed in wireframe mode. */ Wireframe = 0, /** By default, renders surfaces without their edges. * Lighting and shadows can be applied using [[ViewFlags.lighting]] and [[ViewFlags.shadows]]. * Edges can be enabled using [[ViewFlags.visibleEdges]] and [[ViewFlags.hiddenEdges]], and their appearance customized using [[HiddenLine.Settings]]. * Surfaces can be drawn with transparency, based on [[ViewFlags.transparency]]. */ SmoothShade = 6, /** Renders surfaces and their edges. By default, edges are drawn in white; this can be overridden using [[HiddenLine.Settings]]. * All surfaces are rendered opaque. If a surface's transparency is below that specified by [[HiddenLine.Settings.transparencyThreshold]], it is not rendered. * Materials and textures are not applied - surfaces are drawn in their actual colors. * [[ViewFlags.visibleEdges]] is ignored - visible edges are always drawn. Hidden edges can be enabled using [[ViewFlags.hiddenEdges]]. * Lighting (and by extension, shadows) is not applied. */ SolidFill = 4, /** Identical to [[RenderMode.SolidFill]], except: * - Surfaces are drawn using the [DisplayStyle]($backend)'s background color. * - Edges are drawn using their surface's colors; this can be overridden using [[HiddenLine.Settings]]. */ HiddenLine = 3 } /** JSON representation of [[ViewFlags]]. * This is a persistence format with some unfortunate quirks that have been retained for backwards compatibility. * In particular, it supplies three separate flags intended to control lighting - [[noCameraLights]], [[noSourceLights]], and [[noSolarLight]] - * but there exists only a single [[ViewFlags.lighting]] flag. [[ViewFlags.lighting]] is set to true unless all three of the "no lighting" flags are true. * It also uses awkward negative ([[noConstruct]], [[noTransp]]) and/or abbreviated ([[clipVol]], [[visEdges]]) property names that differ from * those of the corresponding [[ViewFlags]] properties, making usage of this type in code error-prone. * Prefer to use [[ViewFlagsProperties]] unless you need to work directly with the persistence format. * @public * @extensions */ export interface ViewFlagProps { /** If true, don't display geometry of class [[GeometryClass.Construction]]. */ noConstruct?: boolean; /** If true, don't display geometry of class [[GeometryClass.Dimension]]. */ noDim?: boolean; /** If true, don't display geometry of class [[GeometryClass.Pattern]]. */ noPattern?: boolean; /** If true, all lines are drawn with a width of 1 pixel. */ noWeight?: boolean; /** If true, don't apply [[LinePixels]] styles. */ noStyle?: boolean; /** If true, display transparency geometry as opaque. */ noTransp?: boolean; /** If true, don't show filled planar regions, unless they use [[FillFlags.Always]]. */ noFill?: boolean; /** If true, display a grid in the view. */ grid?: boolean; /** If true, display graphics representing the [AuxCoordSystem]($backend). */ acs?: boolean; /** If true, don't apply [[RenderTexture]]s to surfaces. */ noTexture?: boolean; /** If true, don't apply [[RenderMaterial]]s to surfaces. */ noMaterial?: boolean; /** See [[ViewFlagProps]] for how this affects [[ViewFlags.lighting]]. */ noCameraLights?: boolean; /** See [[ViewFlagProps]] for how this affects [[ViewFlags.lighting]]. */ noSourceLights?: boolean; /** See [[ViewFlagProps]] for how this affects [[ViewFlags.lighting]]. */ noSolarLight?: boolean; /** If true, display the edges of surfaces. */ visEdges?: boolean; /** If true, display the edges of surfaces, even if they are behind other geometry. */ hidEdges?: boolean; /** If true, display shadows. */ shadows?: boolean; /** If true, apply the view's clipping volume. Has no effect on other types of clips like [[ModelClipGroups]]. */ clipVol?: boolean; /** If true, apply the view's [[DisplayStyleSettings.monochromeColor]] and [[DisplayStyleSettings.monochromeMode]] to produce a monochrome image. */ monochrome?: boolean; /** The basic rendering mode, which affects the behavior of other flags. */ renderMode?: RenderMode; /** Display a background map. */ backgroundMap?: boolean; /** If true, apply [[AmbientOcclusion]]. */ ambientOcclusion?: boolean; /** If true, apply [[ThematicDisplay]]. */ thematicDisplay?: boolean; /** If true, overlay surfaces with wiremesh to reveal their triangulation. */ wiremesh?: boolean; /** Controls whether surface discard is always applied regardless of other ViewFlags. * Surface shaders contain complicated logic to ensure that the edges of a surface always draw in front of the surface, and that planar surfaces sketched coincident with * non-planar surfaces always draw in front of those non-planar surfaces. * When this view flag is set to false (the default), then for 3d views if the render mode is wireframe (only edges are displayed) or smooth shader with visible edges turned off (only surfaces are displayed), * that logic does not execute, potentially improving performance for no degradation in visual quality. In some scenarios - such as wireframe views containing many planar regions with interior fill, or smooth views containing many coincident planar and non-planar surfaces - enabling this view flag improves display quality by forcing that logic to execute. */ forceSurfaceDiscard?: boolean; /** Disables the "white-on-white reversal" employed by some CAD applications. * @see [[ViewFlags.whiteOnWhiteReversal]]. */ noWhiteOnWhiteReversal?: boolean; } /** Flags controlling how graphics appear within a view. * A [[ViewFlags]] object is immutable. There are several ways to produce a modified copy of a ViewFlags object: * ```ts * // Start with the default values for all properties. * let vf = ViewFlags.defaults; * // Change a single boolean property: * vf = vf.with("visibleEdges", true); * // Change only the render mode: * vf = vf.withRenderMode(RenderMode.HiddenLine); * // Change multiple properties: * vf = vf.copy({ renderMode: RenderMode.SmoothShade, visibleEdges: true }); * // Reset multiple properties to their default values: * vf = vf.copy({ renderMode: undefined, visibleEdges: undefined }); * * ``` * [[with]] and [[withRenderMode]] should be preferred if you only need to change a single property, as they will not create a new object unless * the new value differs from the current value. * [[copy]] and [[override]] should be preferred if you need to change multiple properties, as they will create no more than one new object, vs * each call to [[with]] or [[withRenderMode]] potentially creating a new object. * @see [[DisplayStyleSettings.viewFlags]] to define the view flags for a [DisplayStyle]($backend). * @public */ export declare class ViewFlags { /** The basic rendering mode applied to the view. This modulates the behavior of some of the other flags. * Default: [[RenderMode.Wireframe]]. * @see [[RenderMode]] for details. */ readonly renderMode: RenderMode; /** Whether to display geometry of class [[GeometryClass.Dimension]]. Default: true. */ readonly dimensions: boolean; /** Whether to display geometry of class [[GeometryClass.Pattern]]. Default: true. */ readonly patterns: boolean; /** Whether to allow lines and edges to draw with width greater than one pixel. Default: true. */ readonly weights: boolean; /** Whether [[LinePixels]] are allowed to apply patterns to lines and edges. If false, they all draw as solid lines. Default: true. */ readonly styles: boolean; /** Whether element transparency is applied. If false, transparent geometry is drawn opaque. Default: true. * @see [[RenderMode]] for render mode-specific behavior. */ readonly transparency: boolean; /** In [[RenderMode.Wireframe]] only, whether to display the interiors of planar regions with [[FillFlags.ByView]]. Default: true. */ readonly fill: boolean; /** In [[RenderMode.SmoothShade]], whether to apply [[RenderTexture]]s to surfaces. Default: true. */ readonly textures: boolean; /** In [[RenderMode.SmoothShade]], whether to apply [[RenderMaterial]]s to surfaces. Default: true. */ readonly materials: boolean; /** Whether to display a graphical representation of the view's [AuxCoordSystem]($backend). Default: false. */ readonly acsTriad: boolean; /** Whether to display a grid. Default: false. */ readonly grid: boolean; /** In [[RenderMode.SmoothShade]], whether to display the edges of surfaces. Default: false. * @see [[HiddenLine.Settings]] to customize the appearance of the edges. */ readonly visibleEdges: boolean; /** In any mode except [[RenderMode.Wireframe]], whether to display the edges of surfaces occluded by other geometry. * This has no effect unless [[visibleEdges]] is also true. * Default: false. * @see [[HiddenLine.Settings]] to customize the appearance of the edges. */ readonly hiddenEdges: boolean; /** In [[RenderMode.SmoothShade]], whether to display solar shadows. This has no effect unless [[lighting]] is also true. Default: false. * @note Rendering shadows can reduce framerate, particularly on less capable graphics hardware or in complex scenes. */ readonly shadows: boolean; /** Whether to apply the view's clip volume to the geometry in the scene. * Default: true, except when using [[fromJSON]]. * @see [[ViewDetails.clipVector]] to define the view's clip volume. */ readonly clipVolume: boolean; /** Whether to display geometry of class [[GeometryClass.Construction]]. * Default: false, except when using [[fromJSON]]. */ readonly constructions: boolean; /** Whether to produce a monochrome image. Default: false. * @see [DisplayStyleSettings.monochromeColor]($common) to define the monochrome color. * @see [DisplayStyleSettings.monochromeMode]($common) to define how the monochrome image is produced. */ readonly monochrome: boolean; /** Whether to display background map imagery. Default: false. * @see [[DisplayStyleSettings.backgroundMap]] to customize the map settings. */ readonly backgroundMap: boolean; /** In [[RenderMode.SmoothShade]], whether to apply [[AmbientOcclusion]]. Default: false. */ readonly ambientOcclusion: boolean; /** Whether to apply [[ThematicDisplay]]. Default: false. */ readonly thematicDisplay: boolean; /** If true, overlay surfaces with wiremesh to reveal their triangulation. */ readonly wiremesh: boolean; /** Controls whether surface discard is always applied regardless of other ViewFlags. * Surface shaders contain complicated logic to ensure that the edges of a surface always draw in front of the surface, and that planar surfaces sketched coincident with * non-planar surfaces always draw in front of those non-planar surfaces. * When this view flag is set to false (the default), then for 3d views if the render mode is wireframe (only edges are displayed) or smooth shader with visible edges turned off (only surfaces are displayed), * that logic does not execute, potentially improving performance for no degradation in visual quality. In some scenarios - such as wireframe views containing many planar regions with interior fill, or smooth views containing many coincident planar and non-planar surfaces - enabling this view flag improves display quality by forcing that logic to execute. */ readonly forceSurfaceDiscard: boolean; /** Whether to apply white-on-white reversal. * Some CAD applications use this to cause white geometry to be drawn as black if the view's background color is white. * When enabled, the [[DisplayStyleSettings]]' [[WhiteOnWhiteReversalSettings]] control how white-on-white reversal is applied. * Default: true. */ readonly whiteOnWhiteReversal: boolean; /** In [[RenderMode.SmoothShade]], whether to apply lighting to surfaces. * Default: false, except when using [[fromJSON]]. * @see [[DisplayStyleSettings.lights]] to customize the light settings. */ readonly lighting: boolean; /** Create a new ViewFlags. * @param flags The properties to initialize. Any properties not specified are initialized to their default values. */ constructor(flags?: Partial<ViewFlagsProperties>); /** Produce a copy of these ViewFlags with some modified properties. Any properties not explicitly specified by `changedFlags` will retain their current values. * @param changedFlags Properties to modify. * @returns A copy of these ViewFlags modified according to the supplied properties. * @note Any explicitly `undefined` property of `changedFlags` will be set to its default value in the returned ViewFlags. * @see [[override]] to have `undefined` properties retain their current values. */ copy(changedFlags: Partial<ViewFlagsProperties>): ViewFlags; /** Produce a copy of these ViewFlags, overriding some of its properties. Any properties not explicitly specified by `overrides` will retain their current values, * as will any property explicitly set to `undefined`. * @param overrides The properties to override. * @see [[copy]] to have `undefined` properties reset to their default values. */ override(overrides: Partial<ViewFlagsProperties>): ViewFlags; /** Produce a copy of these ViewFlags with a single boolean property changed. * @param flag The name of the property. * @param value The value to change the property to. * @returns A new ViewFlags with the property changed as specified, or `this` if the property already has the specified value. * @see [[withRenderMode]] to change the [[renderMode]] property. * @see [[copy]] and [[override]] to change multiple properties. */ with(flag: keyof Omit<ViewFlagsProperties, "renderMode">, value: boolean): ViewFlags; /** Produce a copy of these ViewFlags with a different [[renderMode]]. * @param renderMode The new render mode. * @returns A new ViewFlags with the render mode changed as specified, or `this` if the render mode is already set to the requested value. * @see [[copy]] and [[override]] to change multiple properties. */ withRenderMode(renderMode: RenderMode): ViewFlags; /** Adjust some view flags based on [[renderMode]]. For example, [[transparency]] is always treated as `false` in [[RenderMode.SolidFill]]. */ normalize(): ViewFlags; /** Returns true if edges that could be occluded by other geometry are visible for the current [[RenderMode]]. */ hiddenEdgesVisible(): boolean; /** Returns true if the edges of surfaces should be displayed, based on [[RenderMode]] and the [[visibleEdges]] flag. */ edgesRequired(): boolean; /** Convert to JSON representation. * Properties are omitted if they match the default values. */ toJSON(): ViewFlagProps; /** Like [[toJSON]], but no properties are omitted. */ toFullyDefinedJSON(): Required<ViewFlagProps>; /** A ViewFlags object with all properties initialized to their default values. */ static readonly defaults: ViewFlags; /** Create a ViewFlags. * @param flags The properties to initialize. Any properties not specified are initialized to their default values. */ static create(flags?: Partial<ViewFlagsProperties>): ViewFlags; /** Create a ViewFlags from its JSON representation. * @note As described in [[ViewFlagProps]], the JSON representation is awkward and error-prone. Prefer to use [[create]] unless you * need to deal with the persistence format directly. * @note The default values differ slightly from those used by the constructor and [[create]]: * - [[clipVolume]] defaults to false. * - [[constructions]] defaults to true. * - [[lighting]] defaults to true unless all of [[ViewFlagProps.noSolarLight]], [[ViewFlagProps.noCameraLights]], and [[ViewFlagProps.noSourceLights]] are true. */ static fromJSON(json?: ViewFlagProps): ViewFlags; /** Returns true if `this` and `other` are equivalent. */ equals(other: Readonly<ViewFlagsProperties>): boolean; } /** A type containing all of the properties of [[ViewFlags]] with none of the methods and with the `readonly` modifiers removed. * @see [[ViewFlags.create]], [[ViewFlags.copy]], and [[ViewFlags.override]] for methods accepting an object of this type. * @public * @extensions */ export type ViewFlagsProperties = Mutable<NonFunctionPropertiesOf<ViewFlags>>; /** A type that describes how to override selected properties of a [[ViewFlags]]. * @see [[ViewFlags.override]] to apply the overrides to a ViewFlags object. * @public * @extensions */ export type ViewFlagOverrides = Partial<ViewFlagsProperties>; //# sourceMappingURL=ViewFlags.d.ts.map