@needle-tools/engine
Version:
Needle Engine is a web-based runtime for 3D apps. It runs on your machine for development with great integrations into editors like Unity or Blender - and can be deployed onto any device! It is flexible, extensible and networking and XR are built-in.
232 lines (231 loc) • 9.37 kB
TypeScript
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;
}