@itwin/core-common 3.4.1 → 3.4.2

package/lib/esm/LightSettings.d.ts

@@ -1,225 +1,225 @@
-/** @packageDocumentation
- * @module DisplayStyles
- */
-import { Vector3d, XYZProps } from "@itwin/core-geometry";
-import { RgbColor, RgbColorProps } from "./RgbColor";
-/** Wire format for the solar directional light associated with a [[LightSettingsProps]].
- * The light is colored white and oriented in any direction in world coordinates.
- * It will cast shadows if it is above the world XY plane and if the shadows view flag is enabled for the view.
- * By default, the solar light is only applied when shadows are enabled, but can be set to be applied unconditionally.
- * @public
- * @extensions
- */
-export interface SolarLightProps {
-    /** Intensity of the light, typically in [0..1] but can range up to 5. Default: 1.0 */
-    intensity?: number;
-    /** Direction of the light in world coordinates. Defaults to a vector looking down on the scene at a 45 degree angle mostly along the Y axis. */
-    direction?: XYZProps;
-    /** If true, the light will be applied even when shadows are turned off for the view.
-     * If false, a roughly overhead light of the same intensity oriented in view space will be used instead.
-     * Default: false.
-     */
-    alwaysEnabled?: boolean;
-    /** If defined, the time in UNIX milliseconds from which [[direction]] was calculated.
-     * @see [[DisplayStyleSettings.setSunTime]] to compute the solar direction from a point in time.
-     */
-    timePoint?: number;
-}
-/** Describes the solar directional light associated with a [[LightSettings]].
- * @see [[SolarLightProps]].
- * @public
- */
-export declare class SolarLight {
-    /** Direction of the light in world coordinates. Defaults to a vector looking down on the scene at a 45 degree angle mostly along the Y axis. */
-    readonly direction: Readonly<Vector3d>;
-    /** Intensity of the light, typically in [0..1] but can range up to 5. Default: 1.0 */
-    readonly intensity: number;
-    /** If true, the light will be applied even when shadows are turned off for the view.
-     * If false, a roughly overhead light of the same intensity oriented in view space will be used instead.
-     * Default: false.
-     */
-    readonly alwaysEnabled: boolean;
-    /** If defined, the time in UNIX milliseconds from which [[direction]] was calculated.
-     * @see [[DisplayStyleSettings.setSunTime]] to compute the solar direction from a point in time.
-     */
-    readonly timePoint?: number;
-    constructor(json?: SolarLightProps);
-    toJSON(): SolarLightProps | undefined;
-    /** Create a copy of this SolarLight, identical except in any properties explicitly specified by `changedProps`, with a possible exception for [[timePoint]].
-     * If `this.timePoint` is defined and `changedProps` defines `direction` but **doesn't** define `timePoint`, the time point will only be preserved in the
-     * copy if `changesProps.direction` is equal to `this.direction`.
-     */
-    clone(changedProps?: SolarLightProps): SolarLight;
-    equals(rhs: SolarLight): boolean;
-}
-/** Wire format for the ambient light associated with a [[LightSettingsProps]].
- * Ambient light applies equally to all surfaces in the scene.
- * @public
- * @extensions
- */
-export interface AmbientLightProps {
-    /** The color of the light. Black is treated as a special case, indicating that the surface's own diffuse color should be used. */
-    color?: RgbColorProps;
-    /** The intensity of the light. Default: 0.2. */
-    intensity?: number;
-}
-/** Describes the ambient light associated with a [[LightSettings]].
- * @see [[AmbientLightProps]]
- * @public
- */
-export declare class AmbientLight {
-    readonly color: RgbColor;
-    readonly intensity: number;
-    constructor(json?: AmbientLightProps);
-    toJSON(): AmbientLightProps | undefined;
-    /** Create a copy of this light, identical except for any properties explicitly specified by `changed`. */
-    clone(changed?: AmbientLightProps): AmbientLight;
-    equals(rhs: AmbientLight): boolean;
-}
-/** Wire format for a pair of hemisphere lights associated with a [[LightSettingsProps]].
- * Hemisphere lights are oriented in opposite directions along the world Z axis. Each has its own color; they share one intensity.
- * They are often used to simulate outdoor reflection of light from the ground and sky, so the colors often match the ground and sky colors
- * of the [[SkyBox]].
- * @public
- * @extensions
- */
-export interface HemisphereLightsProps {
-    /** The color of the downward-facing light. Default: (143, 205, 255). */
-    upperColor?: RgbColorProps;
-    /** The color of the upward-facing light. Default: (120, 143, 125). */
-    lowerColor?: RgbColorProps;
-    /** Intensity of the lights. Default: 0. */
-    intensity?: number;
-}
-/** Describes a pair of hemisphere lights associated with a [[LightSettings]].
- * @see [[HemisphereLightsProps]]
- * @public
- */
-export declare class HemisphereLights {
-    readonly upperColor: RgbColor;
-    readonly lowerColor: RgbColor;
-    readonly intensity: number;
-    constructor(json?: HemisphereLightsProps);
-    toJSON(): HemisphereLightsProps | undefined;
-    /** Create a copy of these lights, identical except for any properties explicitly specified by `changed`. */
-    clone(changed?: HemisphereLightsProps): HemisphereLights;
-    equals(rhs: HemisphereLights): boolean;
-}
-/** JSON representation of a [[FresnelSettings]].
- * @public
- * @extensions
- */
-export interface FresnelSettingsProps {
-    /** See [[FresnelSettings.intensity]].
-     * Default value: 0
-     */
-    intensity?: number;
-    /** See [[FresnelSettings.invert]].
-     * Default value: false
-     */
-    invert?: boolean;
-}
-/** As part of a [[LightSettings]], describes how to apply a Fresnel effect to the contents of the view.
- * The "Fresnel effect" is based on the observation that the reflectivity of a surface varies based on the angle between the surface and
- * the viewer's line of sight. For example, a flat surface will appear more reflective when viewed at a glancing angle than it will when
- * viewed from above; and a sphere will appear more reflective around its edges than at its center.
- *
- * This principle can be used to improve photorealism, but the implementation provided here is intended to produce non-realistic but
- * aesthetically-pleasing results.
- * @see [[LightSettings.fresnel]].
- * @public
- */
-export declare class FresnelSettings {
-    /** The strength of the effect in terms of how much brighter the surface becomes. The intensity at a given point on the surface is determined by
-     * the angle between the viewer's line of sight and the vector from the viewer to that point. Maximum intensity is produced when those vectors are
-     * perpendicular, and zero intensity is produced when those vectors are parallel (unless [[invert]] is `true`).
-     *
-     * A value of zero turns off the effect. Values less than zero are clamped to zero. Typical values range between 0 and 1.
-     */
-    readonly intensity: number;
-    /** If true, inverts the effect's [[intensity]] such that maximum intensity is produced when the viewer's line of sight is parallel to the vector between
-     * the viewer and the point on the surface, and zero intensity is produced when the viewer's line of sight is perpendicular to that vector.
-     */
-    readonly invert: boolean;
-    private constructor();
-    private static readonly _defaults;
-    /** Create from JSON representation, using default values for any unspecified or `undefined` properties. */
-    static fromJSON(props?: FresnelSettingsProps): FresnelSettings;
-    /** Create a new FresnelSettings.
-     * @note Intensity values less than zero will be set to zero.
-     */
-    static create(intensity?: number, invert?: boolean): FresnelSettings;
-    /** Convert to JSON representation.
-     * @note If all settings match the default values, `undefined` will be returned.
-     */
-    toJSON(): FresnelSettingsProps | undefined;
-    /** Create a copy of these settings, modified to match any properties explicitly specified by `changedProps`. */
-    clone(changedProps?: FresnelSettingsProps): FresnelSettings;
-    /** Return true if these settings are equivalent to `rhs`. */
-    equals(rhs: FresnelSettings): boolean;
-}
-/** Wire format for a [[LightSettings]] describing lighting for a 3d scene.
- * 3d lighting provides the following lights, all of which are optional:
- *  - A "portrait" light affixed to the camera and pointing directly forward into the scene. Color: white.
- *  - A second directional light. Color: white.
- *    - This can be a solar shadow-casting light, or (when shadows are disabled) a roughly overhead light oriented in view space.
- *  - A pair of hemisphere lights pointing in opposite directions along the world Z axis. Each has its own customizable color.
- *  - An ambient light of any color applied equally to all surfaces.
- * Specular intensity of all lights is controlled separately.
- * Light intensities are typically expressed in [0..1] but can be as large as 5.
- * @see [[DisplayStyle3dSettingsProps]]
- * @public
- * @extensions
- */
-export interface LightSettingsProps {
-    /** A white portrait light affixed to the camera and pointing directly forward into the scene. */
-    portrait?: {
-        /** Intensity, typically in [0..1], maximum 5. Default: 0.3. */
-        intensity?: number;
-    };
-    /** Solar light settings. */
-    solar?: SolarLightProps;
-    /** Hemisphere light settings. */
-    hemisphere?: HemisphereLightsProps;
-    /** Ambient light settings. */
-    ambient?: AmbientLightProps;
-    /** Specular intensity applied to all lights. */
-    specularIntensity?: number;
-    /** Applies a [cel-shaded](https://en.wikipedia.org/wiki/Cel_shading) effect. If greater than zero, specifies the number of cels. Continuous lighting intensities
-     * are computed, then quantized to the specified number of cels. Values greater than 254 have no visible effect.
-     * Typically a value of 2 is appropriate if specular intensity is close to zero; 3 if specular intensity is larger.
-     * Cel-shading is often combined with thick, dark visible edges for a cartoon or comic book effect.
-     * Default: 0
-     */
-    numCels?: number;
-    /** Fresnel settings.
-     * @see [[FresnelSettings]].
-     */
-    fresnel?: FresnelSettingsProps;
-}
-/** Describes the lighting for a 3d scene, associated with a [[DisplayStyle3dSettings]] in turn associated with a [DisplayStyle3d]($backend) or [DisplayStyle3dState]($frontend).
- * @see [[LightSettingsProps]]
- * @public
- */
-export declare class LightSettings {
-    readonly solar: SolarLight;
-    readonly ambient: AmbientLight;
-    readonly hemisphere: HemisphereLights;
-    /** See [[LightSettingsProps.portrait]]. */
-    readonly portraitIntensity: number;
-    readonly specularIntensity: number;
-    /** See [[LightSettingsProps.numCels]]. */
-    readonly numCels: number;
-    readonly fresnel: FresnelSettings;
-    private constructor();
-    static fromJSON(props?: LightSettingsProps): LightSettings;
-    toJSON(): LightSettingsProps | undefined;
-    /** Create a copy of these light settings, identical except for any properties explicitly specified by `changed`.
-     * Note that the solar, ambient, and hemisphere lights will also be cloned using their own `clone` methods - so for example, the following:
-     * `  clone({ ambient: { intensity: 0.5 } })`
-     * will overwrite the ambient light's intensity but preserve its current color, rather than replacing the color with the default color.
-     */
-    clone(changed?: LightSettingsProps): LightSettings;
-    equals(rhs: LightSettings): boolean;
-}
+/** @packageDocumentation
+ * @module DisplayStyles
+ */
+import { Vector3d, XYZProps } from "@itwin/core-geometry";
+import { RgbColor, RgbColorProps } from "./RgbColor";
+/** Wire format for the solar directional light associated with a [[LightSettingsProps]].
+ * The light is colored white and oriented in any direction in world coordinates.
+ * It will cast shadows if it is above the world XY plane and if the shadows view flag is enabled for the view.
+ * By default, the solar light is only applied when shadows are enabled, but can be set to be applied unconditionally.
+ * @public
+ * @extensions
+ */
+export interface SolarLightProps {
+    /** Intensity of the light, typically in [0..1] but can range up to 5. Default: 1.0 */
+    intensity?: number;
+    /** Direction of the light in world coordinates. Defaults to a vector looking down on the scene at a 45 degree angle mostly along the Y axis. */
+    direction?: XYZProps;
+    /** If true, the light will be applied even when shadows are turned off for the view.
+     * If false, a roughly overhead light of the same intensity oriented in view space will be used instead.
+     * Default: false.
+     */
+    alwaysEnabled?: boolean;
+    /** If defined, the time in UNIX milliseconds from which [[direction]] was calculated.
+     * @see [[DisplayStyleSettings.setSunTime]] to compute the solar direction from a point in time.
+     */
+    timePoint?: number;
+}
+/** Describes the solar directional light associated with a [[LightSettings]].
+ * @see [[SolarLightProps]].
+ * @public
+ */
+export declare class SolarLight {
+    /** Direction of the light in world coordinates. Defaults to a vector looking down on the scene at a 45 degree angle mostly along the Y axis. */
+    readonly direction: Readonly<Vector3d>;
+    /** Intensity of the light, typically in [0..1] but can range up to 5. Default: 1.0 */
+    readonly intensity: number;
+    /** If true, the light will be applied even when shadows are turned off for the view.
+     * If false, a roughly overhead light of the same intensity oriented in view space will be used instead.
+     * Default: false.
+     */
+    readonly alwaysEnabled: boolean;
+    /** If defined, the time in UNIX milliseconds from which [[direction]] was calculated.
+     * @see [[DisplayStyleSettings.setSunTime]] to compute the solar direction from a point in time.
+     */
+    readonly timePoint?: number;
+    constructor(json?: SolarLightProps);
+    toJSON(): SolarLightProps | undefined;
+    /** Create a copy of this SolarLight, identical except in any properties explicitly specified by `changedProps`, with a possible exception for [[timePoint]].
+     * If `this.timePoint` is defined and `changedProps` defines `direction` but **doesn't** define `timePoint`, the time point will only be preserved in the
+     * copy if `changesProps.direction` is equal to `this.direction`.
+     */
+    clone(changedProps?: SolarLightProps): SolarLight;
+    equals(rhs: SolarLight): boolean;
+}
+/** Wire format for the ambient light associated with a [[LightSettingsProps]].
+ * Ambient light applies equally to all surfaces in the scene.
+ * @public
+ * @extensions
+ */
+export interface AmbientLightProps {
+    /** The color of the light. Black is treated as a special case, indicating that the surface's own diffuse color should be used. */
+    color?: RgbColorProps;
+    /** The intensity of the light. Default: 0.2. */
+    intensity?: number;
+}
+/** Describes the ambient light associated with a [[LightSettings]].
+ * @see [[AmbientLightProps]]
+ * @public
+ */
+export declare class AmbientLight {
+    readonly color: RgbColor;
+    readonly intensity: number;
+    constructor(json?: AmbientLightProps);
+    toJSON(): AmbientLightProps | undefined;
+    /** Create a copy of this light, identical except for any properties explicitly specified by `changed`. */
+    clone(changed?: AmbientLightProps): AmbientLight;
+    equals(rhs: AmbientLight): boolean;
+}
+/** Wire format for a pair of hemisphere lights associated with a [[LightSettingsProps]].
+ * Hemisphere lights are oriented in opposite directions along the world Z axis. Each has its own color; they share one intensity.
+ * They are often used to simulate outdoor reflection of light from the ground and sky, so the colors often match the ground and sky colors
+ * of the [[SkyBox]].
+ * @public
+ * @extensions
+ */
+export interface HemisphereLightsProps {
+    /** The color of the downward-facing light. Default: (143, 205, 255). */
+    upperColor?: RgbColorProps;
+    /** The color of the upward-facing light. Default: (120, 143, 125). */
+    lowerColor?: RgbColorProps;
+    /** Intensity of the lights. Default: 0. */
+    intensity?: number;
+}
+/** Describes a pair of hemisphere lights associated with a [[LightSettings]].
+ * @see [[HemisphereLightsProps]]
+ * @public
+ */
+export declare class HemisphereLights {
+    readonly upperColor: RgbColor;
+    readonly lowerColor: RgbColor;
+    readonly intensity: number;
+    constructor(json?: HemisphereLightsProps);
+    toJSON(): HemisphereLightsProps | undefined;
+    /** Create a copy of these lights, identical except for any properties explicitly specified by `changed`. */
+    clone(changed?: HemisphereLightsProps): HemisphereLights;
+    equals(rhs: HemisphereLights): boolean;
+}
+/** JSON representation of a [[FresnelSettings]].
+ * @public
+ * @extensions
+ */
+export interface FresnelSettingsProps {
+    /** See [[FresnelSettings.intensity]].
+     * Default value: 0
+     */
+    intensity?: number;
+    /** See [[FresnelSettings.invert]].
+     * Default value: false
+     */
+    invert?: boolean;
+}
+/** As part of a [[LightSettings]], describes how to apply a Fresnel effect to the contents of the view.
+ * The "Fresnel effect" is based on the observation that the reflectivity of a surface varies based on the angle between the surface and
+ * the viewer's line of sight. For example, a flat surface will appear more reflective when viewed at a glancing angle than it will when
+ * viewed from above; and a sphere will appear more reflective around its edges than at its center.
+ *
+ * This principle can be used to improve photorealism, but the implementation provided here is intended to produce non-realistic but
+ * aesthetically-pleasing results.
+ * @see [[LightSettings.fresnel]].
+ * @public
+ */
+export declare class FresnelSettings {
+    /** The strength of the effect in terms of how much brighter the surface becomes. The intensity at a given point on the surface is determined by
+     * the angle between the viewer's line of sight and the vector from the viewer to that point. Maximum intensity is produced when those vectors are
+     * perpendicular, and zero intensity is produced when those vectors are parallel (unless [[invert]] is `true`).
+     *
+     * A value of zero turns off the effect. Values less than zero are clamped to zero. Typical values range between 0 and 1.
+     */
+    readonly intensity: number;
+    /** If true, inverts the effect's [[intensity]] such that maximum intensity is produced when the viewer's line of sight is parallel to the vector between
+     * the viewer and the point on the surface, and zero intensity is produced when the viewer's line of sight is perpendicular to that vector.
+     */
+    readonly invert: boolean;
+    private constructor();
+    private static readonly _defaults;
+    /** Create from JSON representation, using default values for any unspecified or `undefined` properties. */
+    static fromJSON(props?: FresnelSettingsProps): FresnelSettings;
+    /** Create a new FresnelSettings.
+     * @note Intensity values less than zero will be set to zero.
+     */
+    static create(intensity?: number, invert?: boolean): FresnelSettings;
+    /** Convert to JSON representation.
+     * @note If all settings match the default values, `undefined` will be returned.
+     */
+    toJSON(): FresnelSettingsProps | undefined;
+    /** Create a copy of these settings, modified to match any properties explicitly specified by `changedProps`. */
+    clone(changedProps?: FresnelSettingsProps): FresnelSettings;
+    /** Return true if these settings are equivalent to `rhs`. */
+    equals(rhs: FresnelSettings): boolean;
+}
+/** Wire format for a [[LightSettings]] describing lighting for a 3d scene.
+ * 3d lighting provides the following lights, all of which are optional:
+ *  - A "portrait" light affixed to the camera and pointing directly forward into the scene. Color: white.
+ *  - A second directional light. Color: white.
+ *    - This can be a solar shadow-casting light, or (when shadows are disabled) a roughly overhead light oriented in view space.
+ *  - A pair of hemisphere lights pointing in opposite directions along the world Z axis. Each has its own customizable color.
+ *  - An ambient light of any color applied equally to all surfaces.
+ * Specular intensity of all lights is controlled separately.
+ * Light intensities are typically expressed in [0..1] but can be as large as 5.
+ * @see [[DisplayStyle3dSettingsProps]]
+ * @public
+ * @extensions
+ */
+export interface LightSettingsProps {
+    /** A white portrait light affixed to the camera and pointing directly forward into the scene. */
+    portrait?: {
+        /** Intensity, typically in [0..1], maximum 5. Default: 0.3. */
+        intensity?: number;
+    };
+    /** Solar light settings. */
+    solar?: SolarLightProps;
+    /** Hemisphere light settings. */
+    hemisphere?: HemisphereLightsProps;
+    /** Ambient light settings. */
+    ambient?: AmbientLightProps;
+    /** Specular intensity applied to all lights. */
+    specularIntensity?: number;
+    /** Applies a [cel-shaded](https://en.wikipedia.org/wiki/Cel_shading) effect. If greater than zero, specifies the number of cels. Continuous lighting intensities
+     * are computed, then quantized to the specified number of cels. Values greater than 254 have no visible effect.
+     * Typically a value of 2 is appropriate if specular intensity is close to zero; 3 if specular intensity is larger.
+     * Cel-shading is often combined with thick, dark visible edges for a cartoon or comic book effect.
+     * Default: 0
+     */
+    numCels?: number;
+    /** Fresnel settings.
+     * @see [[FresnelSettings]].
+     */
+    fresnel?: FresnelSettingsProps;
+}
+/** Describes the lighting for a 3d scene, associated with a [[DisplayStyle3dSettings]] in turn associated with a [DisplayStyle3d]($backend) or [DisplayStyle3dState]($frontend).
+ * @see [[LightSettingsProps]]
+ * @public
+ */
+export declare class LightSettings {
+    readonly solar: SolarLight;
+    readonly ambient: AmbientLight;
+    readonly hemisphere: HemisphereLights;
+    /** See [[LightSettingsProps.portrait]]. */
+    readonly portraitIntensity: number;
+    readonly specularIntensity: number;
+    /** See [[LightSettingsProps.numCels]]. */
+    readonly numCels: number;
+    readonly fresnel: FresnelSettings;
+    private constructor();
+    static fromJSON(props?: LightSettingsProps): LightSettings;
+    toJSON(): LightSettingsProps | undefined;
+    /** Create a copy of these light settings, identical except for any properties explicitly specified by `changed`.
+     * Note that the solar, ambient, and hemisphere lights will also be cloned using their own `clone` methods - so for example, the following:
+     * `  clone({ ambient: { intensity: 0.5 } })`
+     * will overwrite the ambient light's intensity but preserve its current color, rather than replacing the color with the default color.
+     */
+    clone(changed?: LightSettingsProps): LightSettings;
+    equals(rhs: LightSettings): boolean;
+}
 //# sourceMappingURL=LightSettings.d.ts.map