@babylonjs/core
Version:
Getting started? Play directly with the Babylon.js API using our [playground](https://playground.babylonjs.com/). It also contains a lot of samples to learn how to use it.
263 lines (262 loc) • 11.3 kB
TypeScript
import type { Camera } from "../Cameras/camera.js";
import type { Scene } from "../scene.js";
import { Matrix, Vector3 } from "../Maths/math.vector.js";
import type { AbstractMesh } from "../Meshes/abstractMesh.js";
import { Light } from "./light.js";
import type { Nullable } from "../types.js";
/**
* Interface describing all the common properties and methods a shadow light needs to implement.
* This helps both the shadow generator and materials to generate the corresponding shadow maps
* as well as binding the different shadow properties to the effects.
*/
export interface IShadowLight extends Light {
/**
* The light id in the scene (used in scene.getLightById for instance)
*/
id: string;
/**
* The position the shadow will be casted from.
*/
position: Vector3;
/**
* In 2d mode (needCube being false), the direction used to cast the shadow.
*/
direction: Vector3;
/**
* The transformed position. Position of the light in world space taking parenting in account.
*/
transformedPosition: Vector3;
/**
* The transformed direction. Direction of the light in world space taking parenting in account.
*/
transformedDirection: Vector3;
/**
* The friendly name of the light in the scene.
*/
name: string;
/**
* Defines the shadow projection clipping minimum z value.
*/
shadowMinZ: number;
/**
* Defines the shadow projection clipping maximum z value.
*/
shadowMaxZ: number;
/**
* Computes the transformed information (transformedPosition and transformedDirection in World space) of the current light
* @returns true if the information has been computed, false if it does not need to (no parenting)
*/
computeTransformedInformation(): boolean;
/**
* Gets the scene the light belongs to.
* @returns The scene
*/
getScene(): Scene;
/**
* Callback defining a custom Projection Matrix Builder.
* This can be used to override the default projection matrix computation.
*/
customProjectionMatrixBuilder: (viewMatrix: Matrix, renderList: Array<AbstractMesh>, result: Matrix) => void;
/**
* Sets the shadow projection matrix in parameter to the generated projection matrix.
* @param matrix The matrix to update with the projection information
* @param viewMatrix The transform matrix of the light
* @param renderList The list of mesh to render in the map
* @returns The current light
*/
setShadowProjectionMatrix(matrix: Matrix, viewMatrix: Matrix, renderList: Array<AbstractMesh>): IShadowLight;
/**
* Gets the current depth scale used in ESM.
* @returns The scale
*/
getDepthScale(): number;
/**
* Returns whether or not the shadow generation require a cube texture or a 2d texture.
* @returns true if a cube texture needs to be use
*/
needCube(): boolean;
/**
* Detects if the projection matrix requires to be recomputed this frame.
* @returns true if it requires to be recomputed otherwise, false.
*/
needProjectionMatrixCompute(): boolean;
/**
* Forces the shadow generator to recompute the projection matrix even if position and direction did not changed.
*/
forceProjectionMatrixCompute(): void;
/**
* Get the direction to use to render the shadow map. In case of cube texture, the face index can be passed.
* @param faceIndex The index of the face we are computed the direction to generate shadow
* @returns The set direction in 2d mode otherwise the direction to the cubemap face if needCube() is true
*/
getShadowDirection(faceIndex?: number): Vector3;
/**
* Gets the minZ used for shadow according to both the scene and the light.
* @param activeCamera The camera we are returning the min for
* @returns the depth min z
*/
getDepthMinZ(activeCamera: Nullable<Camera>): number;
/**
* Gets the maxZ used for shadow according to both the scene and the light.
* @param activeCamera The camera we are returning the max for
* @returns the depth max z
*/
getDepthMaxZ(activeCamera: Nullable<Camera>): number;
}
/**
* Base implementation IShadowLight
* It groups all the common behaviour in order to reduce duplication and better follow the DRY pattern.
*/
export declare abstract class ShadowLight extends Light implements IShadowLight {
protected abstract _setDefaultShadowProjectionMatrix(matrix: Matrix, viewMatrix: Matrix, renderList: Array<AbstractMesh>): void;
protected _position: Vector3;
protected _setPosition(value: Vector3): void;
/**
* Sets the position the shadow will be casted from. Also use as the light position for both
* point and spot lights.
*/
get position(): Vector3;
/**
* Sets the position the shadow will be casted from. Also use as the light position for both
* point and spot lights.
*/
set position(value: Vector3);
protected _direction: Vector3;
protected _setDirection(value: Vector3): void;
/**
* In 2d mode (needCube being false), gets the direction used to cast the shadow.
* Also use as the light direction on spot and directional lights.
*/
get direction(): Vector3;
/**
* In 2d mode (needCube being false), sets the direction used to cast the shadow.
* Also use as the light direction on spot and directional lights.
*/
set direction(value: Vector3);
protected _shadowMinZ: number;
/**
* Gets the shadow projection clipping minimum z value.
*/
get shadowMinZ(): number;
/**
* Sets the shadow projection clipping minimum z value.
*/
set shadowMinZ(value: number);
protected _shadowMaxZ: number;
/**
* Sets the shadow projection clipping maximum z value.
*/
get shadowMaxZ(): number;
/**
* Gets the shadow projection clipping maximum z value.
*/
set shadowMaxZ(value: number);
/**
* Callback defining a custom Projection Matrix Builder.
* This can be used to override the default projection matrix computation.
*/
customProjectionMatrixBuilder: (viewMatrix: Matrix, renderList: Array<AbstractMesh>, result: Matrix) => void;
/**
* The transformed position. Position of the light in world space taking parenting in account. Needs to be computed by calling computeTransformedInformation.
*/
transformedPosition: Vector3;
/**
* The transformed direction. Direction of the light in world space taking parenting in account.
*/
transformedDirection: Vector3;
private _needProjectionMatrixCompute;
/**
* Computes the transformed information (transformedPosition and transformedDirection in World space) of the current light
* @returns true if the information has been computed, false if it does not need to (no parenting)
*/
computeTransformedInformation(): boolean;
/**
* Return the depth scale used for the shadow map.
* @returns the depth scale.
*/
getDepthScale(): number;
/**
* Get the direction to use to render the shadow map. In case of cube texture, the face index can be passed.
* @param faceIndex The index of the face we are computed the direction to generate shadow
* @returns The set direction in 2d mode otherwise the direction to the cubemap face if needCube() is true
*/
getShadowDirection(faceIndex?: number): Vector3;
/**
* If computeTransformedInformation has been called, returns the ShadowLight absolute position in the world. Otherwise, returns the local position.
* @returns the position vector in world space
*/
getAbsolutePosition(): Vector3;
/**
* Sets the ShadowLight direction toward the passed target.
* @param target The point to target in local space
* @returns the updated ShadowLight direction
*/
setDirectionToTarget(target: Vector3): Vector3;
/**
* Returns the light rotation in euler definition.
* @returns the x y z rotation in local space.
*/
getRotation(): Vector3;
/**
* Returns whether or not the shadow generation require a cube texture or a 2d texture.
* @returns true if a cube texture needs to be use
*/
needCube(): boolean;
/**
* Detects if the projection matrix requires to be recomputed this frame.
* @returns true if it requires to be recomputed otherwise, false.
*/
needProjectionMatrixCompute(): boolean;
/**
* Forces the shadow generator to recompute the projection matrix even if position and direction did not changed.
*/
forceProjectionMatrixCompute(): void;
/** @internal */
_initCache(): void;
/** @internal */
_isSynchronized(): boolean;
/**
* Computes the world matrix of the node
* @param force defines if the cache version should be invalidated forcing the world matrix to be created from scratch
* @returns the world matrix
*/
computeWorldMatrix(force?: boolean): Matrix;
/**
* Gets the minZ used for shadow according to both the scene and the light.
* @param activeCamera The camera we are returning the min for
* @returns the depth min z
*/
getDepthMinZ(activeCamera: Nullable<Camera>): number;
/**
* Gets the maxZ used for shadow according to both the scene and the light.
* @param activeCamera The camera we are returning the max for
* @returns the depth max z
*/
getDepthMaxZ(activeCamera: Nullable<Camera>): number;
/**
* Sets the shadow projection matrix in parameter to the generated projection matrix.
* @param matrix The matrix to updated with the projection information
* @param viewMatrix The transform matrix of the light
* @param renderList The list of mesh to render in the map
* @returns The current light
*/
setShadowProjectionMatrix(matrix: Matrix, viewMatrix: Matrix, renderList: Array<AbstractMesh>): IShadowLight;
/** @internal */
protected _syncParentEnabledState(): void;
protected _viewMatrix: Matrix;
protected _projectionMatrix: Matrix;
/**
* Returns the view matrix.
* @param faceIndex The index of the face for which we want to extract the view matrix. Only used for point light types.
* @returns The view matrix. Can be null, if a view matrix cannot be defined for the type of light considered (as for a hemispherical light, for example).
*/
getViewMatrix(faceIndex?: number): Nullable<Matrix>;
/**
* Returns the projection matrix.
* Note that viewMatrix and renderList are optional and are only used by lights that calculate the projection matrix from a list of meshes (e.g. directional lights with automatic extents calculation).
* @param viewMatrix The view transform matrix of the light (optional).
* @param renderList The list of meshes to take into account when calculating the projection matrix (optional).
* @returns The projection matrix. Can be null, if a projection matrix cannot be defined for the type of light considered (as for a hemispherical light, for example).
*/
getProjectionMatrix(viewMatrix?: Matrix, renderList?: Array<AbstractMesh>): Nullable<Matrix>;
}