API
API|
@babylonjs/core|
DirectionalLight

Class DirectionalLight

A directional light is defined by a direction (what a surprise!). The light is emitted from everywhere in the specified direction, and has an infinite range. An example of a directional light is when a distance planet is lit by the apparently parallel lines of light from its sun. Light in a downward direction will light the top of an object. Documentation: https://doc.babylonjs.com/features/featuresDeepDive/lights/lights_introduction

Hierarchy (View Summary)

Index
constructor
animations autoCalcShadowZBounds autoUpdateExtends customProjectionMatrixBuilder diffuse falloffType id inspectableCustomProperties intensity metadata name onAccessibilityTagChangedObservable onDisposeObservable onReady reservedDataStore specular state transformedDirection transformedPosition uniqueId FALLOFF_DEFAULT FALLOFF_GLTF FALLOFF_PHYSICAL FALLOFF_STANDARD INTENSITYMODE_AUTOMATIC INTENSITYMODE_ILLUMINANCE INTENSITYMODE_LUMINANCE INTENSITYMODE_LUMINOUSINTENSITY INTENSITYMODE_LUMINOUSPOWER LIGHTMAP_DEFAULT LIGHTMAP_SHADOWSONLY LIGHTMAP_SPECULAR LIGHTTYPEID_DIRECTIONALLIGHT LIGHTTYPEID_HEMISPHERICLIGHT LIGHTTYPEID_POINTLIGHT LIGHTTYPEID_RECT_AREALIGHT LIGHTTYPEID_SPOTLIGHT
accessibilityTag animationPropertiesOverride behaviors direction doNotSerialize excludedMeshes excludeWithLayerMask includedOnlyMeshes includeOnlyWithLayerMask inheritVisibility intensityMode isVisible lightmapMode onClonedObservable onDispose onEffectiveEnabledStateChangedObservable onEnabledStateChangedObservable orthoBottom orthoLeft orthoRight orthoTop parent position radius range renderPriority shadowEnabled shadowFrustumSize shadowMaxZ shadowMinZ shadowOrthoScale 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 getRotation getScaledIntensity getScene getShadowDirection getShadowGenerator getShadowGenerators getTypeID getViewMatrix getWorldMatrix isDescendantOf isDisposed isEnabled isReady markAsDirty needCube needProjectionMatrixCompute prepareLightSpecificDefines removeBehavior serialize serializeAnimationRanges setDirectionToTarget setEnabled setShadowProjectionMatrix toString transferTexturesToEffect transferToEffect transferToNodeMaterialEffect AddNodeConstructor Construct GetConstructorFromName Parse ParseAnimationRanges
animations: Animation[] = []

Gets a list of Animations associated with the node

autoCalcShadowZBounds: boolean = false

Automatically compute the shadowMinZ and shadowMaxZ for the projection matrix to best fit (including all the casters) on each frame. autoUpdateExtends must be set to true for this to work

autoUpdateExtends: boolean = true

Automatically compute the projection matrix to best fit (including all the casters) on each frame.

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.

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

Gets or sets the id of the node

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

Gets or sets the name of the node

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

reservedDataStore: any = null

For internal use only. Please do not use.

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. Needs to be computed by calling computeTransformedInformation.

uniqueId: number

Gets or sets the unique id of the node

FALLOFF_DEFAULT: 0 = LightConstants.FALLOFF_DEFAULT

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.

FALLOFF_GLTF: 2 = LightConstants.FALLOFF_GLTF

Falloff gltf: light is falling off as described in the gltf moving to PBR document to enhance interoperability with other engines.

FALLOFF_PHYSICAL: 1 = LightConstants.FALLOFF_PHYSICAL

Falloff Physical: light is falling off following the inverse squared distance law.

FALLOFF_STANDARD: 3 = LightConstants.FALLOFF_STANDARD

Falloff Standard: light is falling off like in the standard material to enhance interoperability with other materials.

INTENSITYMODE_AUTOMATIC: 0 = LightConstants.INTENSITYMODE_AUTOMATIC

Each light type uses the default quantity according to its type: point/spot lights use luminous intensity directional lights use illuminance

INTENSITYMODE_ILLUMINANCE: 3 = LightConstants.INTENSITYMODE_ILLUMINANCE

lux (lm/m^2)

INTENSITYMODE_LUMINANCE: 4 = LightConstants.INTENSITYMODE_LUMINANCE

nit (cd/m^2)

INTENSITYMODE_LUMINOUSINTENSITY: 2 = LightConstants.INTENSITYMODE_LUMINOUSINTENSITY

candela (lm/sr)

INTENSITYMODE_LUMINOUSPOWER: 1 = LightConstants.INTENSITYMODE_LUMINOUSPOWER

lumen (lm)

LIGHTMAP_DEFAULT: 0 = LightConstants.LIGHTMAP_DEFAULT

If every light affecting the material is in this lightmapMode, material.lightmapTexture adds or multiplies (depends on material.useLightmapAsShadowmap) after every other light calculations.

LIGHTMAP_SHADOWSONLY: 2 = LightConstants.LIGHTMAP_SHADOWSONLY

material.lightmapTexture as only lighting no light calculation from this light only adds dynamic shadows from this light

LIGHTMAP_SPECULAR: 1 = LightConstants.LIGHTMAP_SPECULAR

material.lightmapTexture as only diffuse lighting from this light adds only specular lighting from this light adds dynamic shadows

LIGHTTYPEID_DIRECTIONALLIGHT: 1 = LightConstants.LIGHTTYPEID_DIRECTIONALLIGHT

Light type const id of the directional light.

LIGHTTYPEID_HEMISPHERICLIGHT: 3 = LightConstants.LIGHTTYPEID_HEMISPHERICLIGHT

Light type const id of the hemispheric light.

LIGHTTYPEID_POINTLIGHT: 0 = LightConstants.LIGHTTYPEID_POINTLIGHT

Light type const id of the point light.

LIGHTTYPEID_RECT_AREALIGHT: 4 = LightConstants.LIGHTTYPEID_RECT_AREALIGHT

Light type const id of the area light.

LIGHTTYPEID_SPOTLIGHT: 2 = LightConstants.LIGHTTYPEID_SPOTLIGHT

Light type const id of the spot light.

  • 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

  • get shadowOrthoScale(): number

    Gets the shadow projection scale against the optimal computed one. 0.1 by default which means that the projection window is increase by 10% from the optimal size. This does not impact in fixed frustum size (shadowFrustumSize being set)

    Returns number

  • set shadowOrthoScale(value: number): void

    Sets the shadow projection scale against the optimal computed one. 0.1 by default which means that the projection window is increase by 10% from the optimal size. This does not impact in fixed frustum size (shadowFrustumSize being set)

    Parameters

    • value: number

    Returns void

  • get worldMatrixFromCache(): Matrix

    Returns directly the latest state of the mesh World matrix. A Matrix is returned.

    Returns Matrix

_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

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

    Values are fixed on directional lights as it relies on an ortho projection hence the need to convert being -1 and 1 to 0 and 1 doing (depth + min) / (min + max) -> (depth + 1) / (1 + 1) -> (depth * 0.5) + 0.5. (when not using reverse depth buffer / NDC half Z range)

    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.

    Values are fixed on directional lights as it relies on an ortho projection hence the need to convert being -1 and 1 to 0 and 1 doing (depth + min) / (min + max) -> (depth + 1) / (1 + 1) -> (depth * 0.5) + 0.5. (when not using reverse depth buffer / NDC half Z range)

    Parameters

    • _activeCamera: Nullable<Camera>

      The camera we are returning the min for (not used)

    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

    • OptionalviewMatrix: Matrix

      The view transform matrix of the light (optional).

    • OptionalrenderList: 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

    • OptionalfaceIndex: 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

  • 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

  • Returns a node constructor based on type name

    Parameters

    • type: string

      defines the type name

    • name: string

      defines the new node name

    • scene: Scene

      defines the hosting scene

    • Optionaloptions: any

      defines optional options to transmit to constructors

    Returns Nullable<() => Node>

    the new constructor or null

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

    Parameters

    • type: number

      Type according to the types available in Light.LIGHTTYPEID_x

    • name: string

      The friendly name of the light

    • scene: Scene

      The scene the new light will belong to

    Returns Nullable<() => Light>

    the constructor function

  • Parses the passed "parsedLight" and returns a new instanced Light from this parsing.

    Parameters

    • parsedLight: any

      The JSON representation of the light

    • scene: Scene

      The scene to create the parsed light in

    • rootUrl: string = ""

      The root url to use to load assets referenced by the light (e.g. textures)

    Returns Nullable<Light>

    the created light after parsing

  • Parse animation range data from a serialization object and store them into a given node

    Parameters

    • node: Node

      defines where to store the animation ranges

    • parsedNode: any

      defines the serialization object to read data from

    • _scene: Scene

      defines the hosting scene

    Returns void