playcanvas
Version:
Open-source WebGL/WebGPU 3D engine for the web
382 lines (381 loc) • 14.9 kB
TypeScript
/**
* A camera.
*
* @ignore
*/
export class Camera {
/** @private */
private static _flipYProjectionMatrix;
/** @private */
private static _webGpuDepthRangeMatrix;
/** @private */
private static _applyShaderProjectionScratch;
/**
* Builds the projection matrix matching shader `matrix_projection` after optional flip-Y
* for render targets and optional WebGPU clip-depth range adjustment.
*
* @param {Mat4} projection - Source projection ({@link Camera#projectionMatrix}).
* @param {Mat4} out - Receives the transformed matrix.
* @param {boolean} flipY - When true, apply render-target Y flip first.
* @param {boolean} applyWebGpuDepthRange - When true, map clip Z from -1..1 to 0..1.
* @returns {Mat4} out
*/
static applyShaderProjectionTransform(projection: Mat4, out: Mat4, flipY: boolean, applyWebGpuDepthRange: boolean): Mat4;
/**
* @param {GraphicsDevice} graphicsDevice - The graphics device this camera will use for
* automatic aspect ratio calculation against the backbuffer size.
*/
constructor(graphicsDevice: GraphicsDevice);
/**
* @type {ShaderPassInfo|null}
*/
shaderPassInfo: ShaderPassInfo | null;
/**
* @type {FramePassColorGrab|null}
*/
renderPassColorGrab: FramePassColorGrab | null;
/**
* @type {FramePassDepthGrab|null}
*/
renderPassDepthGrab: FramePassDepthGrab | null;
/**
* The fog parameters.
*
* @type {FogParams|null}
*/
fogParams: FogParams | null;
/**
* Shader parameters used to generate and use matching shaders.
*
* @type {CameraShaderParams}
*/
shaderParams: CameraShaderParams;
/**
* Frame passes used to render this camera. If empty, the camera will render using the default
* frame passes.
*
* @type {FramePass[]}
*/
framePasses: FramePass[];
/**
* Frame passes that execute before this camera's main scene rendering, after the camera's
* directional shadow passes. Entries are picked up by the RenderPassForward that renders
* this camera's layers.
*
* @type {FramePass[]}
*/
beforePasses: FramePass[];
/** @type {number} */
jitter: number;
/**
* The graphics device used by this camera. Required so the camera can compute its aspect
* ratio from the backbuffer size when no render target is assigned.
*
* @type {GraphicsDevice}
*/
device: GraphicsDevice;
_aspectRatio: number;
_aspectRatioMode: number;
_calculateProjection: any;
_calculateTransform: any;
_clearColor: Color;
_clearColorBuffer: boolean;
_clearDepth: number;
_clearDepthBuffer: boolean;
_clearStencil: number;
_clearStencilBuffer: boolean;
_cullFaces: boolean;
_farClip: number;
_flipFaces: boolean;
_fov: number;
_frustumCulling: boolean;
_horizontalFov: boolean;
_layers: number[];
_layersSet: Set<number>;
_nearClip: number;
_node: any;
_orthoHeight: number;
_projection: number;
_rect: Vec4;
_renderTarget: any;
_scissorRect: Vec4;
_scissorRectClear: boolean;
_aperture: number;
_shutter: number;
_sensitivity: number;
_projMat: Mat4;
_projMatDirty: boolean;
_projMatSkybox: Mat4;
_viewMat: Mat4;
_viewMatDirty: boolean;
_viewProjMat: Mat4;
_viewProjMatDirty: boolean;
_shaderMatricesVersion: number;
_viewProjInverse: Mat4;
_viewProjCurrent: any;
_viewProjPrevious: Mat4;
_jitters: number[];
frustum: Frustum;
/** @type {Set<Layer>} */
_cullLayers: Set<Layer>;
/** @type {RenderView[]|null} */
_xrViews: RenderView[] | null;
_xrProperties: {
horizontalFov: boolean;
fov: number;
aspectRatio: number;
farClip: number;
nearClip: number;
};
destroy(): void;
/**
* Store camera matrices required by TAA. Only update them once per frame.
*/
_storeShaderMatrices(viewProjMat: any, jitterX: any, jitterY: any, renderVersion: any): void;
/**
* True if the camera clears the full render target. (viewport / scissor are full size)
*/
get fullSizeClearRect(): boolean;
set aspectRatio(newValue: number);
get aspectRatio(): number;
set aspectRatioMode(newValue: number);
get aspectRatioMode(): number;
set calculateProjection(newValue: any);
get calculateProjection(): any;
set calculateTransform(newValue: any);
get calculateTransform(): any;
set clearColor(newValue: Color);
get clearColor(): Color;
set clearColorBuffer(newValue: boolean);
get clearColorBuffer(): boolean;
set clearDepth(newValue: number);
get clearDepth(): number;
set clearDepthBuffer(newValue: boolean);
get clearDepthBuffer(): boolean;
set clearStencil(newValue: number);
get clearStencil(): number;
set clearStencilBuffer(newValue: boolean);
get clearStencilBuffer(): boolean;
set cullFaces(newValue: boolean);
get cullFaces(): boolean;
set farClip(newValue: number);
get farClip(): number;
set flipFaces(newValue: boolean);
get flipFaces(): boolean;
set fov(newValue: number);
get fov(): number;
set frustumCulling(newValue: boolean);
get frustumCulling(): boolean;
set horizontalFov(newValue: boolean);
get horizontalFov(): boolean;
set layers(newValue: ReadonlyArray<number>);
/**
* Gets the layer IDs this camera renders. Use the setter to replace the array; do not mutate
* the returned array.
*
* @type {ReadonlyArray<number>}
*/
get layers(): ReadonlyArray<number>;
get layersSet(): Set<number>;
set nearClip(newValue: number);
get nearClip(): number;
set node(newValue: any);
get node(): any;
set orthoHeight(newValue: number);
get orthoHeight(): number;
set projection(newValue: number);
get projection(): number;
get projectionMatrix(): Mat4;
set rect(newValue: Vec4);
get rect(): Vec4;
set renderTarget(newValue: any);
get renderTarget(): any;
set scissorRect(newValue: Vec4);
get scissorRect(): Vec4;
get viewMatrix(): Mat4;
set aperture(newValue: number);
get aperture(): number;
set sensitivity(newValue: number);
get sensitivity(): number;
set shutter(newValue: number);
get shutter(): number;
/**
* Sets the list of {@link RenderView}s this camera renders with (one per XR eye/screen), or
* null when not rendering an XR session. Set by the XR manager.
*
* @param {RenderView[]|null} value - The per-view list, or null when not in XR.
*/
set xrViews(value: RenderView[] | null);
/**
* @type {RenderView[]|null}
*/
get xrViews(): RenderView[] | null;
/**
* True while an XR session owns this camera (equivalent to {@link Camera#xrViews} being set).
*
* @type {boolean}
*/
get xrActive(): boolean;
/**
* Registers a layer to be culled for this camera in the current frame. Used by the renderer's
* request/execute mesh-instance culling.
*
* @param {Layer} layer - The layer to cull for this camera.
* @returns {boolean} True if this is the first layer registered for this camera this frame,
* letting the caller track the camera exactly once.
* @ignore
*/
addCullLayer(layer: Layer): boolean;
/**
* Gets the set of layers registered to be culled for this camera in the current frame. For
* read-only iteration; use {@link Camera#addCullLayer} and {@link Camera#clearCullLayers} to
* mutate it.
*
* @type {Set<Layer>}
* @ignore
*/
get cullLayers(): Set<Layer>;
/**
* Clears the set of layers registered to be culled for this camera, called once the camera's
* culling has been performed.
*
* @ignore
*/
clearCullLayers(): void;
/**
* Calculates the aspect ratio that should be used for the camera, based on the size of the
* given render target (or the backbuffer if no render target is given), and the camera's
* `rect`. The `rect` is included so that a camera rendering into a sub-region of a render
* target gets the aspect ratio of the actual rendered pixel area (important for split-screen
* and similar setups, otherwise rendering would appear stretched).
*
* @param {RenderTarget|null} [rt] - Optional render target. If unspecified, the camera's
* own render target (or, if that is also null, the backbuffer) is used.
* @returns {number} The computed aspect ratio.
*/
calculateAspectRatio(rt?: RenderTarget | null): number;
/**
* Creates a duplicate of the camera.
*
* @returns {Camera} A cloned Camera.
*/
clone(): Camera;
/**
* Copies one camera to another.
*
* @param {Camera} other - Camera to copy.
* @returns {Camera} Self for chaining.
*/
copy(other: Camera): Camera;
_enableRenderPassColorGrab(device: any, enable: any): void;
_enableRenderPassDepthGrab(device: any, renderer: any, enable: any): void;
_updateViewProjMat(): void;
/**
* Refreshes the derived per-view matrices of all {@link Camera#xrViews}, using this camera's
* parent world transform. The renderer (and the gsplat passes, which run earlier in the frame)
* call this before reading the per-view matrices.
*
* Note: this recomputes on every call. Within a frame the parent transform is stable, so the
* 2-3 calls/frame could be collapsed to a single recompute by guarding on
* `device.renderVersion` (as {@link Camera#_storeShaderMatrices} does) - left as a future
* optimization, as it needs checking against cameras that render multiple times per frame
* (e.g. multiple render targets).
*/
updateViewTransforms(): void;
/**
* Updates {@link Camera#frustum} to the combined volume of all XR views, to avoid culling
* objects visible in any view (e.g. the right edge of the right eye in stereo rendering).
* The views are merged conservatively via {@link Frustum#add}, which handles the asymmetric
* per-eye projections real headsets report (matching planes of the two eyes have different
* normals, so a simple outermost-plane selection would over-cull at a distance).
*
* @returns {boolean} True when XR views were present and the frustum was updated, false
* otherwise (the caller should fall back to the mono frustum path).
* @ignore
*/
updateXrFrustum(): boolean;
/**
* Updates {@link Camera#frustum} for the camera's current transform and projection, for
* visibility culling. Uses the combined (VIEW_CENTER) view; XR cameras delegate to
* {@link Camera#updateXrFrustum}. Honors the {@link Camera#calculateProjection} and
* {@link Camera#calculateTransform} overrides.
*
* @ignore
*/
updateFrustum(): void;
/**
* Convert a point from 3D world space to 2D canvas pixel space based on the camera's rect.
*
* @param {Vec3} worldCoord - The world space coordinate to transform.
* @param {number} cw - The width of PlayCanvas' canvas element.
* @param {number} ch - The height of PlayCanvas' canvas element.
* @param {Vec3} [screenCoord] - 3D vector to receive screen coordinate result.
* @returns {Vec3} The screen space coordinate.
*/
worldToScreen(worldCoord: Vec3, cw: number, ch: number, screenCoord?: Vec3): Vec3;
/**
* Convert a point from 2D canvas pixel space to 3D world space based on the camera's rect.
*
* @param {number} x - X coordinate on PlayCanvas' canvas element.
* @param {number} y - Y coordinate on PlayCanvas' canvas element.
* @param {number} z - The distance from the camera in world space to create the new point.
* @param {number} cw - The width of PlayCanvas' canvas element.
* @param {number} ch - The height of PlayCanvas' canvas element.
* @param {Vec3} [worldCoord] - 3D vector to receive world coordinate result.
* @returns {Vec3} The world space coordinate.
*/
screenToWorld(x: number, y: number, z: number, cw: number, ch: number, worldCoord?: Vec3): Vec3;
_evaluateProjectionMatrix(): void;
getProjectionMatrixSkybox(): Mat4;
getExposure(): number;
getScreenSize(sphere: any): number;
/**
* Returns an array of corners of the frustum of the camera in the local coordinate system of the camera.
*
* @param {number} [near] - Near distance for the frustum points. Defaults to the near clip distance of the camera.
* @param {number} [far] - Far distance for the frustum points. Defaults to the far clip distance of the camera.
* @returns {Vec3[]} - An array of corners, using a global storage space.
*/
getFrustumCorners(near?: number, far?: number): Vec3[];
/**
* Sets XR camera properties that should be derived physical camera in {@link XrManager}.
*
* @param {object} [properties] - Properties object.
* @param {number} [properties.aspectRatio] - Aspect ratio.
* @param {number} [properties.farClip] - Far clip.
* @param {number} [properties.fov] - Field of view.
* @param {boolean} [properties.horizontalFov] - Enable horizontal field of view.
* @param {number} [properties.nearClip] - Near clip.
*/
setXrProperties(properties?: {
aspectRatio?: number;
farClip?: number;
fov?: number;
horizontalFov?: boolean;
nearClip?: number;
}): void;
/**
* Fills the provided array with camera parameters for use in shaders.
* The array format is: [1/far, far, near, isOrtho].
*
* @param {Float32Array} output - Array to fill with camera parameters.
* @returns {Float32Array} The output array.
* @ignore
*/
fillShaderParams(output: Float32Array): Float32Array;
}
import type { ShaderPassInfo } from './shader-pass.js';
import { FramePassColorGrab } from './graphics/frame-pass-color-grab.js';
import { FramePassDepthGrab } from './graphics/frame-pass-depth-grab.js';
import type { FogParams } from './fog-params.js';
import { CameraShaderParams } from './camera-shader-params.js';
import type { FramePass } from '../platform/graphics/frame-pass.js';
import type { GraphicsDevice } from '../platform/graphics/graphics-device.js';
import { Color } from '../core/math/color.js';
import { Vec4 } from '../core/math/vec4.js';
import { Mat4 } from '../core/math/mat4.js';
import { Frustum } from '../core/shape/frustum.js';
import type { Layer } from './layer.js';
import type { RenderView } from './render-view.js';
import type { RenderTarget } from '../platform/graphics/render-target.js';
import { Vec3 } from '../core/math/vec3.js';