@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.
417 lines (416 loc) • 16.5 kB
TypeScript
import type { Nullable } from "../types.js";
import type { Scene } from "../scene.js";
import type { Matrix } from "../Maths/math.vector.js";
import { Vector3 } from "../Maths/math.vector.js";
import { Color3 } from "../Maths/math.color.js";
import { Node } from "../node.js";
import type { AbstractMesh } from "../Meshes/abstractMesh.js";
import type { Effect } from "../Materials/effect.js";
import { UniformBuffer } from "../Materials/uniformBuffer.js";
import type { IShadowGenerator } from "./Shadows/shadowGenerator.js";
import type { ISortableLight } from "./lightConstants.js";
import type { Camera } from "../Cameras/camera.js";
/**
* Base class of all the lights in Babylon. It groups all the generic information about lights.
* Lights are used, as you would expect, to affect how meshes are seen, in terms of both illumination and colour.
* All meshes allow light to pass through them unless shadow generation is activated. The default number of lights allowed is four but this can be increased.
*/
export declare abstract class Light extends Node implements ISortableLight {
/**
* Falloff Default: light is falling off following the material specification:
* standard material is using standard falloff whereas pbr material can request special falloff per materials.
*/
static readonly FALLOFF_DEFAULT = 0;
/**
* Falloff Physical: light is falling off following the inverse squared distance law.
*/
static readonly FALLOFF_PHYSICAL = 1;
/**
* Falloff gltf: light is falling off as described in the gltf moving to PBR document
* to enhance interoperability with other engines.
*/
static readonly FALLOFF_GLTF = 2;
/**
* Falloff Standard: light is falling off like in the standard material
* to enhance interoperability with other materials.
*/
static readonly FALLOFF_STANDARD = 3;
/**
* If every light affecting the material is in this lightmapMode,
* material.lightmapTexture adds or multiplies
* (depends on material.useLightmapAsShadowmap)
* after every other light calculations.
*/
static readonly LIGHTMAP_DEFAULT = 0;
/**
* material.lightmapTexture as only diffuse lighting from this light
* adds only specular lighting from this light
* adds dynamic shadows
*/
static readonly LIGHTMAP_SPECULAR = 1;
/**
* material.lightmapTexture as only lighting
* no light calculation from this light
* only adds dynamic shadows from this light
*/
static readonly LIGHTMAP_SHADOWSONLY = 2;
/**
* Each light type uses the default quantity according to its type:
* point/spot lights use luminous intensity
* directional lights use illuminance
*/
static readonly INTENSITYMODE_AUTOMATIC = 0;
/**
* lumen (lm)
*/
static readonly INTENSITYMODE_LUMINOUSPOWER = 1;
/**
* candela (lm/sr)
*/
static readonly INTENSITYMODE_LUMINOUSINTENSITY = 2;
/**
* lux (lm/m^2)
*/
static readonly INTENSITYMODE_ILLUMINANCE = 3;
/**
* nit (cd/m^2)
*/
static readonly INTENSITYMODE_LUMINANCE = 4;
/**
* Light type const id of the point light.
*/
static readonly LIGHTTYPEID_POINTLIGHT = 0;
/**
* Light type const id of the directional light.
*/
static readonly LIGHTTYPEID_DIRECTIONALLIGHT = 1;
/**
* Light type const id of the spot light.
*/
static readonly LIGHTTYPEID_SPOTLIGHT = 2;
/**
* Light type const id of the hemispheric light.
*/
static readonly LIGHTTYPEID_HEMISPHERICLIGHT = 3;
/**
* Light type const id of the area light.
*/
static readonly LIGHTTYPEID_RECT_AREALIGHT = 4;
/**
* Diffuse gives the basic color to an object.
*/
diffuse: Color3;
/**
* Specular produces a highlight color on an object.
* Note: This is not affecting PBR materials.
*/
specular: Color3;
/**
* Defines the falloff type for this light. This lets overriding how punctual light are
* falling off base on range or angle.
* This can be set to any values in Light.FALLOFF_x.
*
* Note: This is only useful for PBR Materials at the moment. This could be extended if required to
* other types of materials.
*/
falloffType: number;
/**
* Strength of the light.
* Note: By default it is define in the framework own unit.
* Note: In PBR materials the intensityMode can be use to chose what unit the intensity is defined in.
*/
intensity: number;
private _range;
protected _inverseSquaredRange: number;
/**
* Defines how far from the source the light is impacting in scene units.
* Note: Unused in PBR material as the distance light falloff is defined following the inverse squared falloff.
*/
get range(): number;
/**
* Defines how far from the source the light is impacting in scene units.
* Note: Unused in PBR material as the distance light falloff is defined following the inverse squared falloff.
*/
set range(value: number);
/**
* Cached photometric scale default to 1.0 as the automatic intensity mode defaults to 1.0 for every type
* of light.
*/
private _photometricScale;
private _intensityMode;
/**
* Gets the photometric scale used to interpret the intensity.
* This is only relevant with PBR Materials where the light intensity can be defined in a physical way.
*/
get intensityMode(): number;
/**
* Sets the photometric scale used to interpret the intensity.
* This is only relevant with PBR Materials where the light intensity can be defined in a physical way.
*/
set intensityMode(value: number);
private _radius;
/**
* Gets the light radius used by PBR Materials to simulate soft area lights.
*/
get radius(): number;
/**
* sets the light radius used by PBR Materials to simulate soft area lights.
*/
set radius(value: number);
private _renderPriority;
/**
* Defines the rendering priority of the lights. It can help in case of fallback or number of lights
* exceeding the number allowed of the materials.
*/
renderPriority: number;
private _shadowEnabled;
/**
* Gets whether or not the shadows are enabled for this light. This can help turning off/on shadow without detaching
* the current shadow generator.
*/
get shadowEnabled(): boolean;
/**
* Sets whether or not the shadows are enabled for this light. This can help turning off/on shadow without detaching
* the current shadow generator.
*/
set shadowEnabled(value: boolean);
private _includedOnlyMeshes;
/**
* Gets the only meshes impacted by this light.
*/
get includedOnlyMeshes(): AbstractMesh[];
/**
* Sets the only meshes impacted by this light.
*/
set includedOnlyMeshes(value: AbstractMesh[]);
private _excludedMeshes;
/**
* Gets the meshes not impacted by this light.
*/
get excludedMeshes(): AbstractMesh[];
/**
* Sets the meshes not impacted by this light.
*/
set excludedMeshes(value: AbstractMesh[]);
private _excludeWithLayerMask;
/**
* Gets the layer id use to find what meshes are not impacted by the light.
* Inactive if 0
*/
get excludeWithLayerMask(): number;
/**
* Sets the layer id use to find what meshes are not impacted by the light.
* Inactive if 0
*/
set excludeWithLayerMask(value: number);
private _includeOnlyWithLayerMask;
/**
* Gets the layer id use to find what meshes are impacted by the light.
* Inactive if 0
*/
get includeOnlyWithLayerMask(): number;
/**
* Sets the layer id use to find what meshes are impacted by the light.
* Inactive if 0
*/
set includeOnlyWithLayerMask(value: number);
private _lightmapMode;
/**
* Gets the lightmap mode of this light (should be one of the constants defined by Light.LIGHTMAP_x)
*/
get lightmapMode(): number;
/**
* Sets the lightmap mode of this light (should be one of the constants defined by Light.LIGHTMAP_x)
*/
set lightmapMode(value: number);
/**
* 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>;
/**
* Shadow generators associated to the light.
* @internal Internal use only.
*/
_shadowGenerators: Nullable<Map<Nullable<Camera>, IShadowGenerator>>;
/**
* @internal Internal use only.
*/
_excludedMeshesIds: string[];
/**
* @internal Internal use only.
*/
_includedOnlyMeshesIds: string[];
/**
* The current light uniform buffer.
* @internal Internal use only.
*/
_uniformBuffer: UniformBuffer;
/** @internal */
_renderId: number;
private _lastUseSpecular;
/**
* Creates a Light object in the scene.
* Documentation : https://doc.babylonjs.com/features/featuresDeepDive/lights/lights_introduction
* @param name The friendly name of the light
* @param scene The scene the light belongs too
*/
constructor(name: string, scene?: Scene);
protected abstract _buildUniformLayout(): void;
/**
* Sets the passed Effect "effect" with the Light information.
* @param effect The effect to update
* @param lightIndex The index of the light in the effect to update
* @returns The light
*/
abstract transferToEffect(effect: Effect, lightIndex: string): Light;
/**
* Sets the passed Effect "effect" with the Light textures.
* @param effect The effect to update
* @param lightIndex The index of the light in the effect to update
* @returns The light
*/
transferTexturesToEffect(effect: Effect, lightIndex: string): Light;
/**
* Binds the lights information from the scene to the effect for the given mesh.
* @param lightIndex Light index
* @param scene The scene where the light belongs to
* @param effect The effect we are binding the data to
* @param useSpecular Defines if specular is supported
* @param receiveShadows Defines if the effect (mesh) we bind the light for receives shadows
*/
_bindLight(lightIndex: number, scene: Scene, effect: Effect, useSpecular: boolean, receiveShadows?: boolean): void;
/**
* Sets the passed Effect "effect" with the Light information.
* @param effect The effect to update
* @param lightDataUniformName The uniform used to store light data (position or direction)
* @returns The light
*/
abstract transferToNodeMaterialEffect(effect: Effect, lightDataUniformName: string): Light;
/**
* Returns the string "Light".
* @returns the class name
*/
getClassName(): string;
/** @internal */
readonly _isLight = true;
/**
* Converts the light information to a readable string for debug purpose.
* @param fullDetails Supports for multiple levels of logging within scene loading
* @returns the human readable light info
*/
toString(fullDetails?: boolean): string;
/** @internal */
protected _syncParentEnabledState(): void;
/**
* Set the enabled state of this node.
* @param value - the new enabled state
*/
setEnabled(value: boolean): void;
/**
* Returns the Light associated shadow generator if any.
* @param camera Camera for which the shadow generator should be retrieved (default: null). If null, retrieves the default shadow generator
* @returns the associated shadow generator.
*/
getShadowGenerator(camera?: Nullable<Camera>): Nullable<IShadowGenerator>;
/**
* Returns all the shadow generators associated to this light
* @returns
*/
getShadowGenerators(): Nullable<Map<Nullable<Camera>, IShadowGenerator>>;
/**
* Returns a Vector3, the absolute light position in the World.
* @returns the world space position of the light
*/
getAbsolutePosition(): Vector3;
/**
* Specifies if the light will affect the passed mesh.
* @param mesh The mesh to test against the light
* @returns true the mesh is affected otherwise, false.
*/
canAffectMesh(mesh: AbstractMesh): boolean;
/**
* Releases resources associated with this node.
* @param doNotRecurse Set to true to not recurse into each children (recurse into each children by default)
* @param disposeMaterialAndTextures Set to true to also dispose referenced materials and textures (false by default)
*/
dispose(doNotRecurse?: boolean, disposeMaterialAndTextures?: boolean): void;
/**
* Returns the light type ID (integer).
* @returns The light Type id as a constant defines in Light.LIGHTTYPEID_x
*/
getTypeID(): number;
/**
* Returns the intensity scaled by the Photometric Scale according to the light type and intensity mode.
* @returns the scaled intensity in intensity mode unit
*/
getScaledIntensity(): number;
/**
* Returns a new Light object, named "name", from the current one.
* @param name The name of the cloned light
* @param newParent The parent of this light, if it has one
* @returns the new created light
*/
clone(name: string, newParent?: Nullable<Node>): Nullable<Light>;
/**
* Serializes the current light into a Serialization object.
* @returns the serialized object.
*/
serialize(): any;
/**
* Creates a new typed light from the passed type (integer) : point light = 0, directional light = 1, spot light = 2, hemispheric light = 3.
* This new light is named "name" and added to the passed scene.
* @param type Type according to the types available in Light.LIGHTTYPEID_x
* @param name The friendly name of the light
* @param scene The scene the new light will belong to
* @returns the constructor function
*/
static GetConstructorFromName(type: number, name: string, scene: Scene): Nullable<() => Light>;
/**
* Parses the passed "parsedLight" and returns a new instanced Light from this parsing.
* @param parsedLight The JSON representation of the light
* @param scene The scene to create the parsed light in
* @returns the created light after parsing
*/
static Parse(parsedLight: any, scene: Scene): Nullable<Light>;
private _hookArrayForExcluded;
private _hookArrayForIncludedOnly;
private _resyncMeshes;
/**
* Forces the meshes to update their light related information in their rendering used effects
* @internal Internal Use Only
*/
_markMeshesAsLightDirty(): void;
/**
* Recomputes the cached photometric scale if needed.
*/
private _computePhotometricScale;
/**
* @returns the Photometric Scale according to the light type and intensity mode.
*/
private _getPhotometricScale;
/**
* Reorder the light in the scene according to their defined priority.
* @internal Internal Use Only
*/
_reorderLightsInScene(): void;
/**
* Prepares the list of defines specific to the light type.
* @param defines the list of defines
* @param lightIndex defines the index of the light for the effect
*/
abstract prepareLightSpecificDefines(defines: any, lightIndex: number): void;
/**
* @internal
*/
_isReady(): boolean;
}