@onerjs/addons 8.25.3 → 8.25.5

package/atmosphere/atmosphere.d.ts

@@ -0,0 +1,418 @@
+import type { AbstractEngine } from "@onerjs/core/Engines/abstractEngine.js";
+import { AtmospherePerCameraVariables } from "./atmospherePerCameraVariables.js";
+import { AtmospherePhysicalProperties } from "./atmospherePhysicalProperties.js";
+import type { BaseTexture } from "@onerjs/core/Materials/Textures/baseTexture.js";
+import type { Camera } from "@onerjs/core/Cameras/camera.js";
+import type { DeepImmutable, Nullable } from "@onerjs/core/types.js";
+import { DiffuseSkyIrradianceLut } from "./diffuseSkyIrradianceLut.js";
+import type { DirectionalLight } from "@onerjs/core/Lights/directionalLight.js";
+import type { Effect } from "@onerjs/core/Materials/effect.js";
+import type { IAtmosphereOptions } from "./atmosphereOptions.js";
+import type { IColor3Like, IVector3Like } from "@onerjs/core/Maths/math.like.js";
+import type { IDisposable, Scene } from "@onerjs/core/scene.js";
+import { Observable } from "@onerjs/core/Misc/observable.js";
+import { RenderTargetTexture } from "@onerjs/core/Materials/Textures/renderTargetTexture.js";
+import { TransmittanceLut } from "./transmittanceLut.js";
+import { UniformBuffer } from "@onerjs/core/Materials/uniformBuffer.js";
+import "./Shaders/compositeAerialPerspective.fragment.js";
+import "./Shaders/compositeSky.fragment.js";
+import "./Shaders/compositeGlobeAtmosphere.fragment.js";
+import "./Shaders/fullscreenTriangle.vertex.js";
+import "./Shaders/multiScattering.fragment.js";
+import "./Shaders/skyView.fragment.js";
+import "./Shaders/aerialPerspective.fragment.js";
+import "./Shaders/ShadersInclude/atmosphereFragmentDeclaration.js";
+import "./Shaders/ShadersInclude/atmosphereFunctions.js";
+import "./Shaders/ShadersInclude/atmosphereUboDeclaration.js";
+import "./Shaders/ShadersInclude/atmosphereVertexDeclaration.js";
+import "./Shaders/ShadersInclude/depthFunctions.js";
+/**
+ * Renders a physically based atmosphere.
+ * Use {@link IsSupported} to check if the atmosphere is supported before creating an instance.
+ * @experimental
+ */
+export declare class Atmosphere implements IDisposable {
+    readonly name: string;
+    readonly scene: Scene;
+    private readonly _directionToLight;
+    private readonly _tempSceneAmbient;
+    private readonly _engine;
+    private _physicalProperties;
+    private _transmittanceLut;
+    private _diffuseSkyIrradianceLut;
+    private _isSkyViewLutEnabled;
+    private _isAerialPerspectiveLutEnabled;
+    private _aerialPerspectiveTransmittanceScale;
+    private _aerialPerspectiveSaturation;
+    private _aerialPerspectiveIntensity;
+    private _aerialPerspectiveRadianceBias;
+    private _diffuseSkyIrradianceDesaturationFactor;
+    private _additionalDiffuseSkyIrradianceIntensity;
+    private _additionalDiffuseSkyIrradianceColor;
+    private _additionalDiffuseSkyIrradiance;
+    private _diffuseSkyIrradianceIntensity;
+    private _multiScatteringIntensity;
+    private _groundAlbedo;
+    private _minimumMultiScatteringColor;
+    private _minimumMultiScatteringIntensity;
+    private _lights;
+    private _atmosphereUbo;
+    private _minimumMultiScattering;
+    private _cameraAtmosphereVariables;
+    private _isLinearSpaceComposition;
+    private _isLinearSpaceLight;
+    private _lightRadianceAtCamera;
+    private _linearLightColor;
+    private _originHeight;
+    private _applyApproximateTransmittance;
+    private _exposure;
+    private _atmosphereUniformBufferAsArray;
+    private _effectRenderer;
+    private _skyRenderingGroup;
+    private _aerialPerspectiveRenderingGroup;
+    private _globeAtmosphereRenderingGroup;
+    private _isEnabled;
+    private _hasRenderedMultiScatteringLut;
+    private _multiScatteringEffectWrapper;
+    private _multiScatteringLutRenderTarget;
+    private _aerialPerspectiveLutEffectWrapper;
+    private _aerialPerspectiveLutEffectRenderer;
+    private _aerialPerspectiveLutRenderTarget;
+    private _skyViewLutEffectWrapper;
+    private _skyViewLutEffectRenderer;
+    private _skyViewLutRenderTarget;
+    private _aerialPerspectiveCompositorEffectWrapper;
+    private _skyCompositorEffectWrapper;
+    private _globeAtmosphereCompositorEffectWrapper;
+    private _onBeforeCameraRenderObserver;
+    private _onBeforeDrawPhaseObserver;
+    private _onAfterRenderingGroupObserver;
+    /**
+     * Checks if the {@link Atmosphere} is supported.
+     * @param engine - The engine to check.
+     * @returns True if the atmosphere is supported, false otherwise.
+     */
+    static IsSupported(engine: AbstractEngine): boolean;
+    /**
+     * Called after the atmosphere variables have been updated for the specified camera.
+     */
+    readonly onAfterUpdateVariablesForCameraObservable: Observable<Camera>;
+    /**
+     * Called immediately before the light variables are finalized.
+     */
+    readonly onBeforeLightVariablesUpdateObservable: Observable<void>;
+    /**
+     * Called before the LUTs are rendered for this camera. This happens after the per-camera UBO update.
+     */
+    readonly onBeforeRenderLutsForCameraObservable: Observable<void>;
+    /**
+     * Called after the LUTs were rendered.
+     */
+    readonly onAfterRenderLutsForCameraObservable: Observable<void>;
+    /**
+     * If provided, this is the depth texture used for composition passes.
+     * Expects an infinite far plane on the camera (camera.maxZ = 0) and the non-linear depth accessible in red channel.
+     * @internal
+     */
+    readonly depthTexture: Nullable<BaseTexture>;
+    /**
+     * Controls the overall brightness of the atmosphere rendering.
+     */
+    get exposure(): number;
+    set exposure(value: number);
+    /**
+     * Affects the overall intensity of the multiple scattering.
+     */
+    get multiScatteringIntensity(): number;
+    set multiScatteringIntensity(value: number);
+    /**
+     * Affects the multiply scattered light contribution in the atmosphere by describing the average light color reflected off the ground.
+     */
+    get groundAlbedo(): DeepImmutable<IColor3Like>;
+    set groundAlbedo(value: DeepImmutable<IColor3Like>);
+    /**
+     * Can be used to clamp the multiple scattering to a minimum value.
+     */
+    get minimumMultiScatteringColor(): DeepImmutable<IColor3Like>;
+    set minimumMultiScatteringColor(value: DeepImmutable<IColor3Like>);
+    /**
+     * This is an additional scaling factor applied to the {@link minimumMultiScatteringColor}.
+     */
+    get minimumMultiScatteringIntensity(): number;
+    set minimumMultiScatteringIntensity(value: number);
+    /**
+     * Can be used to force the diffuse irradiance towards a gray color.
+     */
+    get diffuseSkyIrradianceDesaturationFactor(): number;
+    set diffuseSkyIrradianceDesaturationFactor(value: number);
+    /**
+     * This is an additional amount of irradiance added to the diffuse irradiance.
+     */
+    get additionalDiffuseSkyIrradianceIntensity(): number;
+    set additionalDiffuseSkyIrradianceIntensity(value: number);
+    /**
+     * This is the color for the additional amount of irradiance added to the diffuse irradiance.
+     */
+    get additionalDiffuseSkyIrradianceColor(): DeepImmutable<IColor3Like>;
+    set additionalDiffuseSkyIrradianceColor(value: DeepImmutable<IColor3Like>);
+    /**
+     * The final additional diffuse irradiance, taking into account the intensity and color.
+     */
+    get additionalDiffuseSkyIrradiance(): DeepImmutable<IColor3Like>;
+    /**
+     * The intensity of the diffuse irradiance.
+     */
+    get diffuseSkyIrradianceIntensity(): number;
+    set diffuseSkyIrradianceIntensity(value: number);
+    /**
+     * True if the sky view LUT should be used for compositing the sky instead of a per-pixel ray march.
+     */
+    get isSkyViewLutEnabled(): boolean;
+    set isSkyViewLutEnabled(value: boolean);
+    /**
+     * Gets the sky view LUT render target or null if not enabled.
+     * @returns The render target.
+     */
+    get skyViewLutRenderTarget(): Nullable<RenderTargetTexture>;
+    /**
+     * True if the aerial perspective LUT should be used.
+     * If false, full ray marching would be used instead.
+     */
+    get isAerialPerspectiveLutEnabled(): boolean;
+    set isAerialPerspectiveLutEnabled(value: boolean);
+    /**
+     * Gets the aerial perspective LUT render target or null if not enabled.
+     * @returns The render target.
+     */
+    get aerialPerspectiveLutRenderTarget(): Nullable<RenderTargetTexture>;
+    /**
+     * The intensity of the aerial perspective.
+     */
+    get aerialPerspectiveIntensity(): number;
+    set aerialPerspectiveIntensity(value: number);
+    /**
+     * The amount of light transmitted into aerial perspective.
+     * A scale of 1 is physically correct.
+     */
+    get aerialPerspectiveTransmittanceScale(): number;
+    set aerialPerspectiveTransmittanceScale(value: number);
+    /**
+     * The amount of saturation applied to the aerial perspective.
+     * Reducing to zero desaturates the aerial perspective completely.
+     * A value of 1 has no effect.
+     */
+    get aerialPerspectiveSaturation(): number;
+    set aerialPerspectiveSaturation(value: number);
+    /**
+     * A radiance bias applied to aerial perspective.
+     */
+    get aerialPerspectiveRadianceBias(): number;
+    set aerialPerspectiveRadianceBias(value: number);
+    /**
+     * True if the composition should be in linear space (e.g. for HDR rendering).
+     * Typically linear space is expected when ImageProcessing is enabled via PostProcesses.
+     * False for non-linear output.
+     */
+    get isLinearSpaceComposition(): boolean;
+    set isLinearSpaceComposition(value: boolean);
+    /**
+     * True if the {@link light} value should be specified in linear space.
+     * If using PBRMaterials, light value is expected to be linear.
+     */
+    get isLinearSpaceLight(): boolean;
+    set isLinearSpaceLight(value: boolean);
+    /**
+     * The lookup table for transmittance.
+     */
+    get transmittanceLut(): Nullable<TransmittanceLut>;
+    /**
+     * Gets the multiple scattering LUT render target.
+     * @returns The render target.
+     */
+    get multiScatteringLutRenderTarget(): Nullable<RenderTargetTexture>;
+    /**
+     * The lookup table for diffuse sky irradiance, or null if not enabled.
+     */
+    get diffuseSkyIrradianceLut(): Nullable<DiffuseSkyIrradianceLut>;
+    /**
+     * The properties used to describe the size and optical parameters of the atmosphere.
+     */
+    get physicalProperties(): AtmospherePhysicalProperties;
+    /**
+     * The height in kilometers of the scene's origin.
+     */
+    get originHeight(): number;
+    set originHeight(value: number);
+    /**
+     * When atmospheric scattering is applied to surfaces, if this value is set to true,
+     * a grayscale approximation of the transmittance is used to dim surfaces.
+     *
+     * When set to false, the atmospheric composition does not dim the surfaces behind it.
+     * It is up to the client application to apply transmittance manually.
+     */
+    get applyApproximateTransmittance(): boolean;
+    set applyApproximateTransmittance(value: boolean);
+    /**
+     * The directional lights in the scene which represent the suns illuminating the atmosphere.
+     * Each frame, the color and intensity of the lights are updated based on the camera position and the light's direction.
+     */
+    get lights(): ReadonlyArray<DirectionalLight>;
+    /**
+     * The rendering group ID for the sky compositor.
+     * The sky will only be rendered for this group.
+     */
+    get skyRenderingGroup(): number;
+    set skyRenderingGroup(value: number);
+    /**
+     * The rendering group ID for the aerial perspective compositor.
+     * Aerial perspective will only be rendered for this group.
+     */
+    get aerialPerspectiveRenderingGroup(): number;
+    set aerialPerspectiveRenderingGroup(value: number);
+    /**
+     * The rendering group ID for the globe atmosphere compositor.
+     * The globe atmosphere will only be rendered for this group.
+     */
+    get globeAtmosphereRenderingGroup(): number;
+    set globeAtmosphereRenderingGroup(value: number);
+    /**
+     * Gets the uniform buffer used to store the atmosphere's physical properties.
+     */
+    get uniformBuffer(): UniformBuffer;
+    /**
+     * Gets the camera-related variables for this atmosphere. Updated each frame.
+     */
+    get cameraAtmosphereVariables(): AtmospherePerCameraVariables;
+    private _peakRayleighScatteringMmInternal;
+    private _peakRayleighScatteringKm;
+    private _peakMieScatteringMmInternal;
+    private _peakMieScatteringKm;
+    private _peakMieAbsorptionMmInternal;
+    private _peakMieAbsorptionKm;
+    private _peakOzoneAbsorptionMmInternal;
+    private _peakOzoneAbsorptionKm;
+    private get _planetRadius();
+    private set _planetRadius(value);
+    private get _planetRadiusOffset();
+    private set _planetRadiusOffset(value);
+    private get _atmosphereThickness();
+    private set _atmosphereThickness(value);
+    private get _rayleighScatteringScale();
+    private set _rayleighScatteringScale(value);
+    private get _peakRayleighScatteringMm();
+    private set _peakRayleighScatteringMm(value);
+    private get _mieScatteringScale();
+    private set _mieScatteringScale(value);
+    private get _peakMieScatteringMm();
+    private set _peakMieScatteringMm(value);
+    private get _mieAbsorptionScale();
+    private set _mieAbsorptionScale(value);
+    private get _peakMieAbsorptionMm();
+    private set _peakMieAbsorptionMm(value);
+    private get _ozoneAbsorptionScale();
+    private set _ozoneAbsorptionScale(value);
+    private get _peakOzoneAbsorptionMm();
+    private set _peakOzoneAbsorptionMm(value);
+    /**
+     * Constructs the {@link Atmosphere}.
+     * @param name - The name of this instance.
+     * @param scene - The scene to which the atmosphere will be added.
+     * @param lights - The light sources that illuminate the atmosphere. Currently only supports one light, and that light should be the first light in the scene.
+     * @param options - The options used to create the atmosphere.
+     */
+    constructor(name: string, scene: Scene, lights: DirectionalLight[], options?: IAtmosphereOptions);
+    /**
+     * @override
+     */
+    dispose(): void;
+    /**
+     * True if the atmosphere is enabled.
+     * @returns - True if the atmosphere is enabled.
+     */
+    isEnabled(): boolean;
+    /**
+     * Sets the enabled state of the atmosphere.
+     * @param enabled - True to enable the atmosphere, false to disable it.
+     */
+    setEnabled(enabled: boolean): void;
+    /**
+     * The class name of the {@link Atmosphere}.
+     * @returns - The class name of the atmosphere.
+     */
+    getClassName(): string;
+    /**
+     * Gets the color of a light after being transmitted through the atmosphere to a point specified by its distance to the planet center and its geocentric normal.
+     * NOTE, the result is always a linear space color.
+     * @param directionToLight - The direction of the light.
+     * @param pointRadius - The distance from the planet center to the point in kilometers.
+     * @param pointGeocentricNormal - The geocentric normal at the point i.e., normalize(point - planet center).
+     * @param result - The color to store the result in.
+     * @returns The result color.
+     */
+    getTransmittedColorToRef: <T extends IColor3Like>(directionToLight: IVector3Like, pointRadius: number, pointGeocentricNormal: IVector3Like, result: T) => T;
+    /**
+     * Gets the diffuse sky irradiance. Result is always in linear space.
+     * @param directionToLight - The direction of the point to the light.
+     * @param pointRadius - The distance from the planet center to the point in kilometers.
+     * @param pointGeocentricNormal - The geocentric normal at the point: normalize(point - planet center).
+     * @param lightIrradiance - The irradiance of the light.
+     * @param result - The color to store the result in.
+     * @returns The result color.
+     */
+    getDiffuseSkyIrradianceToRef: <T extends IColor3Like>(directionToLight: IVector3Like, pointRadius: number, pointGeocentricNormal: IVector3Like, lightIrradiance: number, result: T) => T;
+    /**
+     * Creates a new {@link EffectWrapper} for the multiple scattering LUT
+     * @returns The newly created {@link EffectWrapper}.
+     */
+    private _createMultiScatteringEffectWrapper;
+    /**
+     * Draws the multiple scattering LUT using {@link EffectWrapper} and {@link EffectRenderer}.
+     */
+    private _drawMultiScatteringLut;
+    /**
+     * Draws the aerial perspective compositor using {@link EffectWrapper} and {@link EffectRenderer}.
+     */
+    drawAerialPerspectiveCompositor(): void;
+    /**
+     * Draws the sky compositor using {@link EffectWrapper} and {@link EffectRenderer}.
+     */
+    drawSkyCompositor(): void;
+    /**
+     * Draws the globe atmosphere compositor using {@link EffectWrapper} and {@link EffectRenderer}.
+     */
+    drawGlobeAtmosphereCompositor(): void;
+    private _disposeSkyCompositor;
+    private _disposeAerialPerspectiveCompositor;
+    private _disposeGlobeAtmosphereCompositor;
+    /**
+     * Updates the camera variables that are specific to the atmosphere.
+     * @param camera - The camera to update the variables for.
+     */
+    private _updatePerCameraVariables;
+    /**
+     * Renders the lookup tables, some of which can vary per-camera.
+     * It is expected that updatePerCameraVariables was previously called.
+     */
+    private _renderLutsForCamera;
+    /**
+     * Renders the lookup tables that do not depend on a camera position.
+     */
+    renderGlobalLuts(): void;
+    /**
+     * Binds the atmosphere's uniform buffer to an {@link Effect}.
+     * @param effect - The {@link Effect} to bind the uniform buffer to.
+     */
+    bindUniformBufferToEffect(effect: Effect): void;
+    /**
+     * Updates the atmosphere's uniform buffer.
+     */
+    updateUniformBuffer(): void;
+    /**
+     * Draws the aerial perspective LUT using {@link EffectWrapper} and {@link EffectRenderer}.
+     */
+    private _drawAerialPerspectiveLut;
+    /**
+     * Draws the sky view LUT using {@link EffectWrapper} and {@link EffectRenderer}.
+     */
+    private _drawSkyViewLut;
+}