@needle-tools/engine 4.7.0 → 4.7.2-alpha

package/lib/engine-components/Camera.d.ts

@@ -1,231 +1,231 @@
-import { Color, Euler, Frustum, Matrix4, OrthographicCamera, PerspectiveCamera, Ray } from "three";
-import { Context } from "../engine/engine_setup.js";
-import { RenderTexture } from "../engine/engine_texture.js";
-import type { ICamera } from "../engine/engine_types.js";
-import { RGBAColor } from "../engine/js-extensions/index.js";
-import { Behaviour } from "./Component.js";
-/**
- * The ClearFlags enum is used to determine how the camera clears the background
- */
-export declare enum ClearFlags {
-    /** Don't clear the background */
-    None = 0,
-    /** Clear the background with a skybox */
-    Skybox = 1,
-    /** Clear the background with a solid color. The alpha channel of the color determines the transparency */
-    SolidColor = 2,
-    /** Clear the background with a transparent color */
-    Uninitialized = 4
-}
-/**
- * Camera component that handles rendering from a specific viewpoint in the scene.
- * Supports both perspective and orthographic cameras with various rendering options.
- * Internally, this component uses {@link PerspectiveCamera} and {@link OrthographicCamera} three.js objects.
- *
- * @category Camera Controls
- * @group Components
- */
-export declare class Camera extends Behaviour implements ICamera {
-    /**
-     * Returns whether this component is a camera
-     * @returns {boolean} Always returns true
-     */
-    get isCamera(): boolean;
-    /**
-     * Gets or sets the camera's aspect ratio (width divided by height).
-     * For perspective cameras, this directly affects the camera's projection matrix.
-     * When set, automatically updates the projection matrix.
-     */
-    get aspect(): number;
-    set aspect(value: number);
-    /**
-     * Gets or sets the camera's field of view in degrees for perspective cameras.
-     * When set, automatically updates the projection matrix.
-     */
-    get fieldOfView(): number | undefined;
-    set fieldOfView(val: number | undefined);
-    /**
-     * Gets or sets the camera's near clipping plane distance.
-     * Objects closer than this distance won't be rendered.
-     * When set, automatically updates the projection matrix.
-     */
-    get nearClipPlane(): number;
-    set nearClipPlane(val: number);
-    private _nearClipPlane;
-    /**
-     * Gets or sets the camera's far clipping plane distance.
-     * Objects farther than this distance won't be rendered.
-     * When set, automatically updates the projection matrix.
-     */
-    get farClipPlane(): number;
-    set farClipPlane(val: number);
-    private _farClipPlane;
-    /**
-     * Applies both the camera's near and far clipping planes and updates the projection matrix.
-     * This ensures rendering occurs only within the specified distance range.
-     */
-    applyClippingPlane(): void;
-    /**
-     * Gets or sets the camera's clear flags that determine how the background is rendered.
-     * Options include skybox, solid color, or transparent background.
-     */
-    get clearFlags(): ClearFlags;
-    set clearFlags(val: ClearFlags | "skybox" | "solidcolor");
-    /**
-     * Determines if the camera should use orthographic projection instead of perspective.
-     */
-    orthographic: boolean;
-    /**
-     * The size of the orthographic camera's view volume when in orthographic mode.
-     * Larger values show more of the scene.
-     */
-    orthographicSize: number;
-    /**
-     * Controls the transparency level of the camera background in AR mode on supported devices.
-     * Value from 0 (fully transparent) to 1 (fully opaque).
-     */
-    ARBackgroundAlpha: number;
-    /**
-     * Gets or sets the layers mask that determines which objects this camera will render.
-     * Uses the {@link https://threejs.org/docs/#api/en/core/Layers.mask|three.js layers mask} convention.
-     */
-    set cullingMask(val: number);
-    get cullingMask(): number;
-    private _cullingMask;
-    /**
-     * Sets only a specific layer to be active for rendering by this camera.
-     * This is equivalent to calling `layers.set(val)` on the three.js camera object.
-     * @param val The layer index to set active
-     */
-    set cullingLayer(val: number);
-    /**
-     * Gets or sets the blurriness of the skybox background.
-     * Values range from 0 (sharp) to 1 (maximum blur).
-     */
-    set backgroundBlurriness(val: number | undefined);
-    get backgroundBlurriness(): number | undefined;
-    private _backgroundBlurriness?;
-    /**
-     * Gets or sets the intensity of the skybox background.
-     * Values range from 0 (dark) to 10 (very bright).
-     */
-    set backgroundIntensity(val: number | undefined);
-    get backgroundIntensity(): number | undefined;
-    private _backgroundIntensity?;
-    /**
-     * Gets or sets the rotation of the skybox background.
-     * Controls the orientation of the environment map.
-     */
-    set backgroundRotation(val: Euler | undefined);
-    get backgroundRotation(): Euler | undefined;
-    private _backgroundRotation?;
-    /**
-     * Gets or sets the intensity of the environment lighting.
-     * Controls how strongly the environment map affects scene lighting.
-     */
-    set environmentIntensity(val: number | undefined);
-    get environmentIntensity(): number | undefined;
-    private _environmentIntensity?;
-    /**
-     * Gets or sets the background color of the camera when {@link ClearFlags} is set to {@link ClearFlags.SolidColor}.
-     * The alpha component controls transparency.
-     */
-    get backgroundColor(): RGBAColor | null;
-    set backgroundColor(val: RGBAColor | Color | null);
-    /**
-     * Gets or sets the texture that the camera should render to instead of the screen.
-     * Useful for creating effects like mirrors, portals or custom post processing.
-     */
-    set targetTexture(rt: RenderTexture | null);
-    get targetTexture(): RenderTexture | null;
-    private _targetTexture;
-    private _backgroundColor?;
-    private _fov?;
-    private _cam;
-    private _clearFlags;
-    private _skybox?;
-    /**
-     * Gets the three.js camera object. Creates one if it doesn't exist yet.
-     * @returns {PerspectiveCamera | OrthographicCamera} The three.js camera object
-     * @deprecated Use {@link threeCamera} instead
-     */
-    get cam(): PerspectiveCamera | OrthographicCamera;
-    /**
-     * Gets the three.js camera object. Creates one if it doesn't exist yet.
-     * @returns {PerspectiveCamera | OrthographicCamera} The three.js camera object
-     */
-    get threeCamera(): PerspectiveCamera | OrthographicCamera;
-    private static _origin;
-    private static _direction;
-    /**
-     * Converts screen coordinates to a ray in world space.
-     * Useful for implementing picking or raycasting from screen to world.
-     *
-     * @param x The x screen coordinate
-     * @param y The y screen coordinate
-     * @param ray Optional ray object to reuse instead of creating a new one
-     * @returns {Ray} A ray originating from the camera position pointing through the screen point
-     */
-    screenPointToRay(x: number, y: number, ray?: Ray): Ray;
-    private _frustum?;
-    /**
-     * Gets the camera's view frustum for culling and visibility checks.
-     * Creates the frustum if it doesn't exist and returns it.
-     *
-     * @returns {Frustum} The camera's view frustum
-     */
-    getFrustum(): Frustum;
-    /**
-     * Forces an update of the camera's frustum.
-     * This is automatically called every frame in onBeforeRender.
-     */
-    updateFrustum(): void;
-    /**
-     * Gets this camera's projection-screen matrix.
-     *
-     * @param target Matrix4 object to store the result in
-     * @param forceUpdate Whether to force recalculation of the matrix
-     * @returns {Matrix4} The requested projection screen matrix
-     */
-    getProjectionScreenMatrix(target: Matrix4, forceUpdate?: boolean): Matrix4;
-    private readonly _projScreenMatrix;
-    /** @internal */
-    awake(): void;
-    /** @internal */
-    onEnable(): void;
-    /** @internal */
-    onDisable(): void;
-    /** @internal */
-    onBeforeRender(): void;
-    /**
-     * Creates a three.js camera object if it doesn't exist yet and sets its properties.
-     * This is called internally when accessing the {@link threeCamera} property.
-     */
-    buildCamera(): void;
-    /**
-     * Applies clear flags if this is the active main camera.
-     * @param opts Options for applying clear flags
-     */
-    applyClearFlagsIfIsActiveCamera(opts?: {
-        applySkybox: boolean;
-    }): void;
-    /**
-     * Applies this camera's clear flags and related settings to the renderer.
-     * This controls how the background is rendered (skybox, solid color, transparent).
-     * @param opts Options for applying clear flags
-     */
-    applyClearFlags(opts?: {
-        applySkybox: boolean;
-    }): void;
-    /**
-     * Applies the skybox texture to the scene background.
-     */
-    applySceneSkybox(): void;
-    /**
-     * Determines if the background should be transparent when in passthrough AR mode.
-     *
-     * @param context The current rendering context
-     * @returns {boolean} True when in XR on a pass through device where the background should be invisible
-     */
-    static backgroundShouldBeTransparent(context: Context): boolean;
-}
+import { Color, Euler, Frustum, Matrix4, OrthographicCamera, PerspectiveCamera, Ray } from "three";
+import { Context } from "../engine/engine_setup.js";
+import { RenderTexture } from "../engine/engine_texture.js";
+import type { ICamera } from "../engine/engine_types.js";
+import { RGBAColor } from "../engine/js-extensions/index.js";
+import { Behaviour } from "./Component.js";
+/**
+ * The ClearFlags enum is used to determine how the camera clears the background
+ */
+export declare enum ClearFlags {
+    /** Don't clear the background */
+    None = 0,
+    /** Clear the background with a skybox */
+    Skybox = 1,
+    /** Clear the background with a solid color. The alpha channel of the color determines the transparency */
+    SolidColor = 2,
+    /** Clear the background with a transparent color */
+    Uninitialized = 4
+}
+/**
+ * Camera component that handles rendering from a specific viewpoint in the scene.
+ * Supports both perspective and orthographic cameras with various rendering options.
+ * Internally, this component uses {@link PerspectiveCamera} and {@link OrthographicCamera} three.js objects.
+ *
+ * @category Camera Controls
+ * @group Components
+ */
+export declare class Camera extends Behaviour implements ICamera {
+    /**
+     * Returns whether this component is a camera
+     * @returns {boolean} Always returns true
+     */
+    get isCamera(): boolean;
+    /**
+     * Gets or sets the camera's aspect ratio (width divided by height).
+     * For perspective cameras, this directly affects the camera's projection matrix.
+     * When set, automatically updates the projection matrix.
+     */
+    get aspect(): number;
+    set aspect(value: number);
+    /**
+     * Gets or sets the camera's field of view in degrees for perspective cameras.
+     * When set, automatically updates the projection matrix.
+     */
+    get fieldOfView(): number | undefined;
+    set fieldOfView(val: number | undefined);
+    /**
+     * Gets or sets the camera's near clipping plane distance.
+     * Objects closer than this distance won't be rendered.
+     * When set, automatically updates the projection matrix.
+     */
+    get nearClipPlane(): number;
+    set nearClipPlane(val: number);
+    private _nearClipPlane;
+    /**
+     * Gets or sets the camera's far clipping plane distance.
+     * Objects farther than this distance won't be rendered.
+     * When set, automatically updates the projection matrix.
+     */
+    get farClipPlane(): number;
+    set farClipPlane(val: number);
+    private _farClipPlane;
+    /**
+     * Applies both the camera's near and far clipping planes and updates the projection matrix.
+     * This ensures rendering occurs only within the specified distance range.
+     */
+    applyClippingPlane(): void;
+    /**
+     * Gets or sets the camera's clear flags that determine how the background is rendered.
+     * Options include skybox, solid color, or transparent background.
+     */
+    get clearFlags(): ClearFlags;
+    set clearFlags(val: ClearFlags | "skybox" | "solidcolor");
+    /**
+     * Determines if the camera should use orthographic projection instead of perspective.
+     */
+    orthographic: boolean;
+    /**
+     * The size of the orthographic camera's view volume when in orthographic mode.
+     * Larger values show more of the scene.
+     */
+    orthographicSize: number;
+    /**
+     * Controls the transparency level of the camera background in AR mode on supported devices.
+     * Value from 0 (fully transparent) to 1 (fully opaque).
+     */
+    ARBackgroundAlpha: number;
+    /**
+     * Gets or sets the layers mask that determines which objects this camera will render.
+     * Uses the {@link https://threejs.org/docs/#api/en/core/Layers.mask|three.js layers mask} convention.
+     */
+    set cullingMask(val: number);
+    get cullingMask(): number;
+    private _cullingMask;
+    /**
+     * Sets only a specific layer to be active for rendering by this camera.
+     * This is equivalent to calling `layers.set(val)` on the three.js camera object.
+     * @param val The layer index to set active
+     */
+    set cullingLayer(val: number);
+    /**
+     * Gets or sets the blurriness of the skybox background.
+     * Values range from 0 (sharp) to 1 (maximum blur).
+     */
+    set backgroundBlurriness(val: number | undefined);
+    get backgroundBlurriness(): number | undefined;
+    private _backgroundBlurriness?;
+    /**
+     * Gets or sets the intensity of the skybox background.
+     * Values range from 0 (dark) to 10 (very bright).
+     */
+    set backgroundIntensity(val: number | undefined);
+    get backgroundIntensity(): number | undefined;
+    private _backgroundIntensity?;
+    /**
+     * Gets or sets the rotation of the skybox background.
+     * Controls the orientation of the environment map.
+     */
+    set backgroundRotation(val: Euler | undefined);
+    get backgroundRotation(): Euler | undefined;
+    private _backgroundRotation?;
+    /**
+     * Gets or sets the intensity of the environment lighting.
+     * Controls how strongly the environment map affects scene lighting.
+     */
+    set environmentIntensity(val: number | undefined);
+    get environmentIntensity(): number | undefined;
+    private _environmentIntensity?;
+    /**
+     * Gets or sets the background color of the camera when {@link ClearFlags} is set to {@link ClearFlags.SolidColor}.
+     * The alpha component controls transparency.
+     */
+    get backgroundColor(): RGBAColor | null;
+    set backgroundColor(val: RGBAColor | Color | null);
+    /**
+     * Gets or sets the texture that the camera should render to instead of the screen.
+     * Useful for creating effects like mirrors, portals or custom post processing.
+     */
+    set targetTexture(rt: RenderTexture | null);
+    get targetTexture(): RenderTexture | null;
+    private _targetTexture;
+    private _backgroundColor?;
+    private _fov?;
+    private _cam;
+    private _clearFlags;
+    private _skybox?;
+    /**
+     * Gets the three.js camera object. Creates one if it doesn't exist yet.
+     * @returns {PerspectiveCamera | OrthographicCamera} The three.js camera object
+     * @deprecated Use {@link threeCamera} instead
+     */
+    get cam(): PerspectiveCamera | OrthographicCamera;
+    /**
+     * Gets the three.js camera object. Creates one if it doesn't exist yet.
+     * @returns {PerspectiveCamera | OrthographicCamera} The three.js camera object
+     */
+    get threeCamera(): PerspectiveCamera | OrthographicCamera;
+    private static _origin;
+    private static _direction;
+    /**
+     * Converts screen coordinates to a ray in world space.
+     * Useful for implementing picking or raycasting from screen to world.
+     *
+     * @param x The x screen coordinate
+     * @param y The y screen coordinate
+     * @param ray Optional ray object to reuse instead of creating a new one
+     * @returns {Ray} A ray originating from the camera position pointing through the screen point
+     */
+    screenPointToRay(x: number, y: number, ray?: Ray): Ray;
+    private _frustum?;
+    /**
+     * Gets the camera's view frustum for culling and visibility checks.
+     * Creates the frustum if it doesn't exist and returns it.
+     *
+     * @returns {Frustum} The camera's view frustum
+     */
+    getFrustum(): Frustum;
+    /**
+     * Forces an update of the camera's frustum.
+     * This is automatically called every frame in onBeforeRender.
+     */
+    updateFrustum(): void;
+    /**
+     * Gets this camera's projection-screen matrix.
+     *
+     * @param target Matrix4 object to store the result in
+     * @param forceUpdate Whether to force recalculation of the matrix
+     * @returns {Matrix4} The requested projection screen matrix
+     */
+    getProjectionScreenMatrix(target: Matrix4, forceUpdate?: boolean): Matrix4;
+    private readonly _projScreenMatrix;
+    /** @internal */
+    awake(): void;
+    /** @internal */
+    onEnable(): void;
+    /** @internal */
+    onDisable(): void;
+    /** @internal */
+    onBeforeRender(): void;
+    /**
+     * Creates a three.js camera object if it doesn't exist yet and sets its properties.
+     * This is called internally when accessing the {@link threeCamera} property.
+     */
+    buildCamera(): void;
+    /**
+     * Applies clear flags if this is the active main camera.
+     * @param opts Options for applying clear flags
+     */
+    applyClearFlagsIfIsActiveCamera(opts?: {
+        applySkybox: boolean;
+    }): void;
+    /**
+     * Applies this camera's clear flags and related settings to the renderer.
+     * This controls how the background is rendered (skybox, solid color, transparent).
+     * @param opts Options for applying clear flags
+     */
+    applyClearFlags(opts?: {
+        applySkybox: boolean;
+    }): void;
+    /**
+     * Applies the skybox texture to the scene background.
+     */
+    applySceneSkybox(): void;
+    /**
+     * Determines if the background should be transparent when in passthrough AR mode.
+     *
+     * @param context The current rendering context
+     * @returns {boolean} True when in XR on a pass through device where the background should be invisible
+     */
+    static backgroundShouldBeTransparent(context: Context): boolean;
+}