API
API|
@babylonjs/core|
IShadowLight

Interface IShadowLight

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.

interface IShadowLight {
    animations: Animation[];
    customProjectionMatrixBuilder: (
        viewMatrix: Matrix,
        renderList: AbstractMesh[],
        result: Matrix,
    ) => void;
    diffuse: Color3;
    direction: Vector3;
    falloffType: number;
    id: string;
    inspectableCustomProperties: IInspectable[];
    intensity: number;
    metadata: any;
    name: string;
    onAccessibilityTagChangedObservable: Observable<
        Nullable<IAccessibilityTag>,
    >;
    onDisposeObservable: Observable<Node>;
    onReady: Nullable<(node: Node) => void>;
    position: Vector3;
    reservedDataStore: any;
    shadowMaxZ: number;
    shadowMinZ: number;
    specular: Color3;
    state: string;
    transformedDirection: Vector3;
    transformedPosition: Vector3;
    uniqueId: number;
    get accessibilityTag(): Nullable<IAccessibilityTag>;
    set accessibilityTag(value: Nullable<IAccessibilityTag>): void;
    get animationPropertiesOverride(): Nullable<AnimationPropertiesOverride>;
    set animationPropertiesOverride(
        value: Nullable<AnimationPropertiesOverride>,
    ): void;
    get behaviors(): Behavior<Node>[];
    get doNotSerialize(): boolean;
    set doNotSerialize(value: boolean): void;
    get excludedMeshes(): AbstractMesh[];
    set excludedMeshes(value: AbstractMesh[]): void;
    get excludeWithLayerMask(): number;
    set excludeWithLayerMask(value: number): void;
    get includedOnlyMeshes(): AbstractMesh[];
    set includedOnlyMeshes(value: AbstractMesh[]): void;
    get includeOnlyWithLayerMask(): number;
    set includeOnlyWithLayerMask(value: number): void;
    get inheritVisibility(): boolean;
    set inheritVisibility(value: boolean): void;
    get intensityMode(): number;
    set intensityMode(value: number): void;
    get isVisible(): boolean;
    set isVisible(value: boolean): void;
    get lightmapMode(): number;
    set lightmapMode(value: number): void;
    get onClonedObservable(): Observable<Node>;
    set onDispose(callback: () => void): void;
    get onEffectiveEnabledStateChangedObservable(): Observable<boolean>;
    get onEnabledStateChangedObservable(): Observable<boolean>;
    get parent(): Nullable<Node>;
    set parent(parent: Nullable<Node>): void;
    get radius(): number;
    set radius(value: number): void;
    get range(): number;
    set range(value: number): void;
    renderPriority: number;
    get shadowEnabled(): boolean;
    set shadowEnabled(value: boolean): void;
    get worldMatrixFromCache(): Matrix;
    _bindLight(
        lightIndex: number,
        scene: Scene,
        effect: Effect,
        useSpecular: boolean,
        receiveShadows?: boolean,
    ): void;
    addBehavior(behavior: Behavior<Node>, attachImmediately?: boolean): Node;
    areLightTexturesReady(): boolean;
    beginAnimation(
        name: string,
        loop?: boolean,
        speedRatio?: number,
        onAnimationEnd?: () => void,
    ): Nullable<Animatable>;
    canAffectMesh(mesh: AbstractMesh): boolean;
    clone(name: string, newParent?: Nullable<Node>): Nullable<Light>;
    computeTransformedInformation(): boolean;
    computeWorldMatrix(_force?: boolean): Matrix;
    createAnimationRange(name: string, from: number, to: number): void;
    deleteAnimationRange(name: string, deleteFrames?: boolean): void;
    dispose(doNotRecurse?: boolean, disposeMaterialAndTextures?: boolean): void;
    forceProjectionMatrixCompute(): void;
    getAbsolutePosition(): Vector3;
    getAnimationByName(name: string): Nullable<Animation>;
    getAnimationRange(name: string): Nullable<AnimationRange>;
    getAnimationRanges(): Nullable<AnimationRange>[];
    getBehaviorByName(name: string): Nullable<Behavior<Node>>;
    getChildMeshes<T extends AbstractMesh>(
        directDescendantsOnly?: boolean,
        predicate?: (node: Node) => node is T,
    ): T[];
    getChildMeshes(
        directDescendantsOnly?: boolean,
        predicate?: (node: Node) => boolean,
    ): AbstractMesh[];
    getChildren<T extends Node>(
        predicate?: (node: Node) => node is T,
        directDescendantsOnly?: boolean,
    ): T[];
    getChildren(
        predicate?: (node: Node) => boolean,
        directDescendantsOnly?: boolean,
    ): Node[];
    getClassName(): string;
    getDepthMaxZ(activeCamera: Nullable<Camera>): number;
    getDepthMinZ(activeCamera: Nullable<Camera>): number;
    getDepthScale(): number;
    getDescendants<T extends Node>(
        directDescendantsOnly?: boolean,
        predicate?: (node: Node) => node is T,
    ): T[];
    getDescendants(
        directDescendantsOnly?: boolean,
        predicate?: (node: Node) => boolean,
    ): Node[];
    getEngine(): AbstractEngine;
    getHierarchyBoundingVectors(
        includeDescendants?: boolean,
        predicate?: Nullable<(abstractMesh: AbstractMesh) => boolean>,
    ): { max: Vector3; min: Vector3 };
    getProjectionMatrix(
        _viewMatrix?: Matrix,
        _renderList?: AbstractMesh[],
    ): Nullable<Matrix>;
    getScaledIntensity(): number;
    getScene(): Scene;
    getShadowDirection(faceIndex?: number): Vector3;
    getShadowGenerator(camera?: Nullable<Camera>): Nullable<IShadowGenerator>;
    getShadowGenerators(): Nullable<Map<Nullable<Camera>, IShadowGenerator>>;
    getTypeID(): number;
    getViewMatrix(_faceIndex?: number): Nullable<Matrix>;
    getWorldMatrix(): Matrix;
    isDescendantOf(ancestor: Node): boolean;
    isDisposed(): boolean;
    isEnabled(checkAncestors?: boolean): boolean;
    isReady(_completeCheck?: boolean): boolean;
    markAsDirty(_property?: string): Node;
    needCube(): boolean;
    needProjectionMatrixCompute(): boolean;
    prepareLightSpecificDefines(defines: any, lightIndex: number): void;
    removeBehavior(behavior: Behavior<Node>): Node;
    serialize(): any;
    serializeAnimationRanges(): any;
    setEnabled(value: boolean): void;
    setShadowProjectionMatrix(
        matrix: Matrix,
        viewMatrix: Matrix,
        renderList: AbstractMesh[],
    ): IShadowLight;
    toString(fullDetails?: boolean): string;
    transferTexturesToEffect(effect: Effect, lightIndex: string): Light;
    transferToEffect(effect: Effect, lightIndex: string): Light;
    transferToNodeMaterialEffect(
        effect: Effect,
        lightDataUniformName: string,
    ): Light;
}

Hierarchy (View Summary)

Implemented by

Index
animations customProjectionMatrixBuilder diffuse direction falloffType id inspectableCustomProperties intensity metadata name onAccessibilityTagChangedObservable onDisposeObservable onReady position reservedDataStore shadowMaxZ shadowMinZ specular state transformedDirection transformedPosition uniqueId
accessibilityTag animationPropertiesOverride behaviors doNotSerialize excludedMeshes excludeWithLayerMask includedOnlyMeshes includeOnlyWithLayerMask inheritVisibility intensityMode isVisible lightmapMode onClonedObservable onDispose onEffectiveEnabledStateChangedObservable onEnabledStateChangedObservable parent radius range renderPriority shadowEnabled worldMatrixFromCache
_bindLight addBehavior areLightTexturesReady beginAnimation canAffectMesh clone computeTransformedInformation computeWorldMatrix createAnimationRange deleteAnimationRange dispose forceProjectionMatrixCompute getAbsolutePosition getAnimationByName getAnimationRange getAnimationRanges getBehaviorByName getChildMeshes getChildren getClassName getDepthMaxZ getDepthMinZ getDepthScale getDescendants getEngine getHierarchyBoundingVectors getProjectionMatrix getScaledIntensity getScene getShadowDirection getShadowGenerator getShadowGenerators getTypeID getViewMatrix getWorldMatrix isDescendantOf isDisposed isEnabled isReady markAsDirty needCube needProjectionMatrixCompute prepareLightSpecificDefines removeBehavior serialize serializeAnimationRanges setEnabled setShadowProjectionMatrix toString transferTexturesToEffect transferToEffect transferToNodeMaterialEffect
animations: Animation[] = []

Gets a list of Animations associated with the node

customProjectionMatrixBuilder: (
    viewMatrix: Matrix,
    renderList: AbstractMesh[],
    result: Matrix,
) => void

Callback defining a custom Projection Matrix Builder. This can be used to override the default projection matrix computation.

diffuse: Color3 = ...

Diffuse gives the basic color to an object.

direction: Vector3

In 2d mode (needCube being false), the direction used to cast the shadow.

falloffType: number = Light.FALLOFF_DEFAULT

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.

id: string

The light id in the scene (used in scene.getLightById for instance)

inspectableCustomProperties: IInspectable[]

List of inspectable custom properties (used by the Inspector)

https://doc.babylonjs.com/toolsAndResources/inspector#extensibility

intensity: number = 1.0

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.

metadata: any = null

Gets or sets an object used to store user defined information for the node

name: string

The friendly name of the light in the scene.

onAccessibilityTagChangedObservable: Observable<Nullable<IAccessibilityTag>> = ...

Observable fired when an accessibility tag is changed

onDisposeObservable: Observable<Node> = ...

An event triggered when the mesh is disposed

onReady: Nullable<(node: Node) => void> = null

Callback raised when the node is ready to be used

position: Vector3

The position the shadow will be casted from.

reservedDataStore: any = null

For internal use only. Please do not use.

shadowMaxZ: number

Defines the shadow projection clipping maximum z value.

shadowMinZ: number

Defines the shadow projection clipping minimum z value.

specular: Color3 = ...

Specular produces a highlight color on an object. Note: This is not affecting PBR materials.

state: string = ""

Gets or sets a string used to store user defined state for the node

transformedDirection: Vector3

The transformed direction. Direction of the light in world space taking parenting in account.

transformedPosition: Vector3

The transformed position. Position of the light in world space taking parenting in account.

uniqueId: number

Gets or sets the unique id of the node

  • get doNotSerialize(): boolean

    Gets or sets a boolean used to define if the node must be serialized

    Returns boolean

  • set doNotSerialize(value: boolean): void

    Parameters

    • value: boolean

    Returns void

  • get excludeWithLayerMask(): number

    Gets the layer id use to find what meshes are not impacted by the light. Inactive if 0

    Returns number

  • set excludeWithLayerMask(value: number): void

    Sets the layer id use to find what meshes are not impacted by the light. Inactive if 0

    Parameters

    • value: number

    Returns void

  • get includeOnlyWithLayerMask(): number

    Gets the layer id use to find what meshes are impacted by the light. Inactive if 0

    Returns number

  • set includeOnlyWithLayerMask(value: number): void

    Sets the layer id use to find what meshes are impacted by the light. Inactive if 0

    Parameters

    • value: number

    Returns void

  • get inheritVisibility(): boolean

    If set to true, this node, when renderable, will only be visible if its parent(s) are also visible.

    Returns boolean

    false
  • set inheritVisibility(value: boolean): void

    Parameters

    • value: boolean

    Returns void

  • get intensityMode(): number

    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.

    Returns number

  • set intensityMode(value: number): void

    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.

    Parameters

    • value: number

    Returns void

  • get isVisible(): boolean

    Gets or sets a boolean indicating whether this node is visible, either this node itself when it is renderable or its renderable child nodes when inheritVisibility is true.

    Returns boolean

    true
  • set isVisible(value: boolean): void

    Parameters

    • value: boolean

    Returns void

  • get lightmapMode(): number

    Gets the lightmap mode of this light (should be one of the constants defined by Light.LIGHTMAP_x)

    Returns number

  • set lightmapMode(value: number): void

    Sets the lightmap mode of this light (should be one of the constants defined by Light.LIGHTMAP_x)

    Parameters

    • value: number

    Returns void

  • set onDispose(callback: () => void): void

    Sets a callback that will be raised when the node will be disposed

    Parameters

    • callback: () => void

    Returns void

  • get onEffectiveEnabledStateChangedObservable(): Observable<boolean>

    An event triggered when the effective enabled state of the node changes, i.e. whenever the value returned by isEnabled changes. Unlike onEnabledStateChangedObservable, this fires for changes caused by an ancestor's enabled state as well as this node's own state. The observable is created on first access, so no cost is incurred for nodes that never observe it.

    Returns Observable<boolean>

  • get radius(): number

    Gets the light radius used by PBR Materials to simulate soft area lights.

    Returns number

  • set radius(value: number): void

    sets the light radius used by PBR Materials to simulate soft area lights.

    Parameters

    • value: number

    Returns void

  • 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.

    Returns number

  • set range(value: number): void

    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.

    Parameters

    • value: number

    Returns void

renderPriority: number

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.

  • get shadowEnabled(): boolean

    Gets whether or not the shadows are enabled for this light. This can help turning off/on shadow without detaching the current shadow generator.

    Returns boolean

  • set shadowEnabled(value: boolean): void

    Sets whether or not the shadows are enabled for this light. This can help turning off/on shadow without detaching the current shadow generator.

    Parameters

    • value: boolean

    Returns void

_bindLight

  • _bindLight(
        lightIndex: number,
        scene: Scene,
        effect: Effect,
        useSpecular: boolean,
        receiveShadows?: boolean,
    ): void

    Binds the lights information from the scene to the effect for the given mesh.

    Parameters

    • lightIndex: number

      Light index

    • scene: Scene

      The scene where the light belongs to

    • effect: Effect

      The effect we are binding the data to

    • useSpecular: boolean

      Defines if specular is supported

    • receiveShadows: boolean = true

      Defines if the effect (mesh) we bind the light for receives shadows

    Returns void

  • Will start the animation sequence

    Parameters

    • name: string

      defines the range frames for animation sequence

    • Optionalloop: boolean

      defines if the animation should loop (false by default)

    • OptionalspeedRatio: number

      defines the speed factor in which to run the animation (1 by default)

    • OptionalonAnimationEnd: () => void

      defines a function to be executed when the animation ended (undefined by default)

    Returns Nullable<Animatable>

    the object created for this animation. If range does not exist, it will return null

  • Computes the transformed information (transformedPosition and transformedDirection in World space) of the current light

    Returns boolean

    true if the information has been computed, false if it does not need to (no parenting)

  • Creates an animation range for this node

    Parameters

    • name: string

      defines the name of the range

    • from: number

      defines the starting key

    • to: number

      defines the end key

    Returns void

  • Delete a specific animation range

    Parameters

    • name: string

      defines the name of the range to delete

    • deleteFrames: boolean = true

      defines if animation frames from the range must be deleted as well

    Returns void

  • Releases resources associated with this node.

    Parameters

    • OptionaldoNotRecurse: boolean

      Set to true to not recurse into each children (recurse into each children by default)

    • disposeMaterialAndTextures: boolean = false

      Set to true to also dispose referenced materials and textures (false by default)

    Returns void

  • Get all child-meshes of this node

    Type Parameters

    Parameters

    • OptionaldirectDescendantsOnly: boolean

      defines if true only direct descendants of 'this' will be considered, if false direct and also indirect (children of children, an so on in a recursive manner) descendants of 'this' will be considered (Default: false)

    • Optionalpredicate: (node: Node) => node is T

      defines an optional predicate that will be called on every evaluated child, the predicate must return true for a given child to be part of the result, otherwise it will be ignored

    Returns T[]

    an array of AbstractMesh

  • Get all child-meshes of this node

    Parameters

    • OptionaldirectDescendantsOnly: boolean

      defines if true only direct descendants of 'this' will be considered, if false direct and also indirect (children of children, an so on in a recursive manner) descendants of 'this' will be considered (Default: false)

    • Optionalpredicate: (node: Node) => boolean

      defines an optional predicate that will be called on every evaluated child, the predicate must return true for a given child to be part of the result, otherwise it will be ignored

    Returns AbstractMesh[]

    an array of AbstractMesh

  • Get all direct children of this node

    Type Parameters

    Parameters

    • Optionalpredicate: (node: Node) => node is T

      defines an optional predicate that will be called on every evaluated child, the predicate must return true for a given child to be part of the result, otherwise it will be ignored

    • OptionaldirectDescendantsOnly: boolean

      defines if true only direct descendants of 'this' will be considered, if false direct and also indirect (children of children, an so on in a recursive manner) descendants of 'this' will be considered (Default: true)

    Returns T[]

    an array of Node

  • Get all direct children of this node

    Parameters

    • Optionalpredicate: (node: Node) => boolean

      defines an optional predicate that will be called on every evaluated child, the predicate must return true for a given child to be part of the result, otherwise it will be ignored

    • OptionaldirectDescendantsOnly: boolean

      defines if true only direct descendants of 'this' will be considered, if false direct and also indirect (children of children, an so on in a recursive manner) descendants of 'this' will be considered (Default: true)

    Returns Node[]

    an array of Node

  • Gets the maxZ used for shadow according to both the scene and the light.

    Parameters

    • activeCamera: Nullable<Camera>

      The camera we are returning the max for

    Returns number

    the depth max z

  • Gets the minZ used for shadow according to both the scene and the light.

    Parameters

    • activeCamera: Nullable<Camera>

      The camera we are returning the min for

    Returns number

    the depth min z

  • Will return all nodes that have this node as ascendant

    Type Parameters

    Parameters

    • OptionaldirectDescendantsOnly: boolean

      defines if true only direct descendants of 'this' will be considered, if false direct and also indirect (children of children, an so on in a recursive manner) descendants of 'this' will be considered

    • Optionalpredicate: (node: Node) => node is T

      defines an optional predicate that will be called on every evaluated child, the predicate must return true for a given child to be part of the result, otherwise it will be ignored

    Returns T[]

    all children nodes of all types

  • Will return all nodes that have this node as ascendant

    Parameters

    • OptionaldirectDescendantsOnly: boolean

      defines if true only direct descendants of 'this' will be considered, if false direct and also indirect (children of children, an so on in a recursive manner) descendants of 'this' will be considered

    • Optionalpredicate: (node: Node) => boolean

      defines an optional predicate that will be called on every evaluated child, the predicate must return true for a given child to be part of the result, otherwise it will be ignored

    Returns Node[]

    all children nodes of all types

  • Return the minimum and maximum world vectors of the entire hierarchy under current node

    Parameters

    • includeDescendants: boolean = true

      Include bounding info from descendants as well (true by default)

    • predicate: Nullable<(abstractMesh: AbstractMesh) => boolean> = null

      defines a callback function that can be customize to filter what meshes should be included in the list used to compute the bounding vectors

    Returns { max: Vector3; min: Vector3 }

    the new bounding vectors

  • 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).

    Parameters

    • Optional_viewMatrix: Matrix

      The view transform matrix of the light (optional).

    • Optional_renderList: AbstractMesh[]

      The list of meshes to take into account when calculating the projection matrix (optional).

    Returns Nullable<Matrix>

    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).

  • Get the direction to use to render the shadow map. In case of cube texture, the face index can be passed.

    Parameters

    • OptionalfaceIndex: number

      The index of the face we are computed the direction to generate shadow

    Returns Vector3

    The set direction in 2d mode otherwise the direction to the cubemap face if needCube() is true

  • Returns the view matrix.

    Parameters

    • Optional_faceIndex: number

      The index of the face for which we want to extract the view matrix. Only used for point light types.

    Returns Nullable<Matrix>

    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).

  • Is this node a descendant of the given node? The function will iterate up the hierarchy until the ancestor was found or no more parents defined

    Parameters

    • ancestor: Node

      defines the parent node to inspect

    Returns boolean

    a boolean indicating if this node is a descendant of the given node

  • Is this node enabled? If the node has a parent, all ancestors will be checked and false will be returned if any are false (not enabled), otherwise will return true

    Parameters

    • checkAncestors: boolean = true

      indicates if this method should check the ancestors. The default is to check the ancestors. If set to false, the method will return the value of this node without checking ancestors

    Returns boolean

    whether this node (and its parent) is enabled

    To observe changes to the value returned when calling this with checkAncestors set to true (the default, i.e. the effective enabled state), subscribe to onEffectiveEnabledStateChangedObservable. To observe changes to the value returned when calling this with checkAncestors set to false (i.e. this node's own enabled state only), subscribe to onEnabledStateChangedObservable.

  • Is this node ready to be used/rendered

    Parameters

    • _completeCheck: boolean = false

      defines if a complete check (including materials and lights) has to be done (false by default)

    Returns boolean

    true if the node is ready

  • Detects if the projection matrix requires to be recomputed this frame.

    Returns boolean

    true if it requires to be recomputed otherwise, false.

  • Converts the light information to a readable string for debug purpose.

    Parameters

    • OptionalfullDetails: boolean

      Supports for multiple levels of logging within scene loading

    Returns string

    the human readable light info