DirectionalLight class

A light that gets emitted in a specific direction. This light will behave as though it is infinitely far away and the rays produced from it are all parallel. The common use case for this is to simulate daylight; the sun is far enough away that its position can be considered to be infinite, and all light rays coming from it are parallel.

This light can cast shadows - see the DirectionalLightShadow page for details.

A Note about Position, Target and rotation

A common point of confusion for directional lights is that setting the rotation has no effect. This is because three.js's DirectionalLight is the equivalent to what is often called a 'Target Direct Light' in other applications.

This means that its direction is calculated as pointing from the light's position to the target's position (as opposed to a 'Free Direct Light' that just has a rotation component).

The reason for this is to allow the light to cast shadows - the shadow camera needs a position to calculate shadows from.

See the target property below for details on updating the target.

// White directional light at half intensity shining from the top.
final directionalLight = DirectionalLight(0xffffff, 0.5 );
scene.add( directionalLight );
Inheritance

Constructors

DirectionalLight([int? color, double? intensity])
color - (optional) hexadecimal color of the light. Default is 0xffffff.

Properties

angle ↔ double?
getter/setter pairinherited
autoUpdate ↔ bool
getter/setter pairinherited
background ↔ dynamic
getter/setter pairinherited
bindMatrix ↔ Matrix4?
getter/setter pairinherited
castShadow ↔ bool
getter/setter pairinherited
children ↔ List<Object3D>
getter/setter pairinherited
color ↔ Color?
getter/setter pairinherited
count ↔ int?
getter/setter pairinherited
customDepthMaterial ↔ Material?
  • Custom depth material to be used when rendering to the depth map. Can only be used in context of meshes.
  • When shadow-casting with a DirectionalLight or SpotLight, if you are (a) modifying vertex positions in
  • the vertex shader, (b) using a displacement map, (c) using an alpha map with alphaTest, or (d) using a
  • transparent texture with alphaTest, you must specify a customDepthMaterial for proper shadows.
  • getter/setter pairinherited
    customDistanceMaterial ↔ Material?
    getter/setter pairinherited
    decay ↔ double?
    getter/setter pairinherited
    disposed ↔ bool
    getter/setter pairoverride
    distance ↔ double?
    getter/setter pairinherited
    environment ↔ Texture?
    getter/setter pairinherited
    extra ↔ Map<String, dynamic>
    getter/setter pairinherited
    frustumCulled ↔ bool
    getter/setter pairinherited
    geometry ↔ BufferGeometry?
    getter/setter pairinherited
    groundColor ↔ Color?
    getter/setter pairinherited
    hashCode → int
    The hash code for this object.
    no setterinherited
    height ↔ double?
    getter/setter pairinherited
    id ↔ int
    getter/setter pairinherited
    instanceColor ↔ BufferAttribute<NativeArray<num>>?
    getter/setter pairinherited
    instanceMatrix ↔ InstancedBufferAttribute?
    getter/setter pairinherited
    intensity ↔ double
    getter/setter pairinherited
    isDirectionalLight ↔ bool
    getter/setter pair
    isHemisphereLight ↔ bool
    getter/setter pairinherited
    isHemisphereLightProbe ↔ bool
    getter/setter pairinherited
    isImmediateRenderObject ↔ bool
    getter/setter pairinherited
    isRectAreaLight ↔ bool
    getter/setter pairinherited
    layers ↔ Layers
    getter/setter pairinherited
    material ↔ Material?
    getter/setter pairinherited
    matrix ↔ Matrix4
    getter/setter pairinherited
    matrixAutoUpdate ↔ bool
    getter/setter pairinherited
    matrixWorld ↔ Matrix4
    getter/setter pairinherited
    matrixWorldNeedsUpdate ↔ bool
    getter/setter pairinherited
    modelViewMatrix ↔ Matrix4
    getter/setter pairinherited
    morphTargetDictionary ↔ Map<String, dynamic>?
    getter/setter pairinherited
    morphTargetInfluences ↔ List<double>
    getter/setter pairinherited
    name ↔ String
    getter/setter pairinherited
    normalMatrix ↔ Matrix3
    getter/setter pairinherited
    onAfterRender ↔ OnAfterRender?
    An optional callback that is executed immediately after a 3D object is rendered. This function is called with the following parameters: renderer, scene, camera, geometry, material, group.
    getter/setter pairinherited
    onBeforeRender ↔ OnBeforeRender?
    getter/setter pairinherited
    overrideMaterial ↔ Material?
    getter/setter pairinherited
    parent ↔ Object3D?
    getter/setter pairinherited
    penumbra ↔ double?
    getter/setter pairinherited
    position ↔ Vector3
    getter/setter pairinherited
    quaternion ↔ Quaternion
    getter/setter pairinherited
    receiveShadow ↔ bool
    getter/setter pairinherited
    renderOrder ↔ int
    getter/setter pairinherited
    rotation ↔ Euler
    getter/setter pairinherited
    runtimeType → Type
    A representation of the runtime type of the object.
    no setterinherited
    scale ↔ Vector3
    getter/setter pairinherited
    sh ↔ SphericalHarmonics3?
    getter/setter pairinherited
    shadow ↔ LightShadow?
    getter/setter pairinherited
    skeleton ↔ Skeleton?
    getter/setter pairinherited
    tag ↔ String?
    getter/setter pairinherited
    target ↔ Object3D?
    getter/setter pairinherited
    type ↔ String
    getter/setter pairinherited
    up ↔ Vector3
    getter/setter pairinherited
    userData ↔ Map<String, dynamic>
    getter/setter pairinherited
    uuid ↔ String
    getter/setter pairinherited
    visible ↔ bool
    getter/setter pairinherited
    width ↔ double?
    getter/setter pairinherited

    Methods

    add(Object3D? object) → Object3D
    Adds object as child of this object. An arbitrary number of objects may be added. Any current parent on an object passed in here will be removed, since an object can have at most one parent.
    inherited
    addAll(List<Object3D> objects) → Object3D
    Adds list objects as child of this object.
    inherited
    addEventListener(String type, Function listener) → void
    type - The type of event to listen to.
    inherited
    applyMatrix4(Matrix4 matrix) → void
    Applies the matrix transform to the object and updates the object's position, rotation and scale.
    inherited
    applyQuaternion(Quaternion q) → Object3D
    Applies the rotation represented by the quaternion to the object.
    inherited
    attach(Object3D object) → Object3D
    inherited
    clear() → Object3D
    Removes all child objects.
    inherited
    clearListeners() → void
    Remove all Listeners.
    inherited
    clone([bool? recursive]) → Object3D
    recursive -- if true, descendants of the object are also cloned. Default is true.
    inherited
    copy(Object3D source, [bool? recursive]) → DirectionalLight
    Copies value of all the properties from the source to this DirectionalLight.
    override
    dispatchEvent(Event event) → void
    event - The event that gets fired.
    inherited
    dispose() → void
    Frees the GPU-related resources allocated by this instance. Call this method whenever this instance is no longer used in your app.
    override
    extractFromCache(Map<String, dynamic> cache) → List<Map<String, dynamic>>
    inherited
    getObjectById(String id) → Object3D?
    id -- Unique number of the object instance
    inherited
    getObjectByName(String name) → Object3D?
    name -- String to match to the children's Object3D.name property.
    inherited
    getObjectByProperty(String name, String value) → Object3D?
    name -- the property name to search for.
    inherited
    getProperty(String propertyName) → dynamic
    inherited
    getValue(String name) → Matrix4?
    inherited
    getWorldDirection(Vector3 target) → Vector3
    target — the result will be copied into this Vector3.
    inherited
    getWorldPosition(Vector3? target) → Vector3
    target — the result will be copied into this Vector3.
    inherited
    getWorldQuaternion(Quaternion target) → Quaternion
    target — the result will be copied into this Quaternion.
    inherited
    getWorldScale(Vector3 target) → Vector3
    target — the result will be copied into this Vector3.
    inherited
    hasEventListener(String type, Function listener) → bool
    type - The type of event to listen to.
    inherited
    init() → void
    inherited
    localToWorld(Vector3 vector) → Vector3
    vector - A vector representing a position in this object's local space.
    inherited
    lookAt(Vector3 position) → void
    vector - A vector representing a position in world space. Optionally, the x, y and z components of the world space position.
    inherited
    noSuchMethod(Invocation invocation) → dynamic
    Invoked when a nonexistent method or property is accessed.
    inherited
    onQuaternionChange() → void
    inherited
    onRotationChange() → void
    inherited
    raycast(Raycaster raycaster, List<Intersection> intersects) → void
    Abstract (empty) method to get intersections between a casted ray and this object. Subclasses such as Mesh, Line, and Points implement this method in order to use raycasting.
    inherited
    remove(Object3D object) → Object3D
    Removes object as child of this object. An arbitrary number of objects may be removed.
    inherited
    removeEventListener(String type, Function listener) → void
    type - The type of the listener that gets removed.
    inherited
    removeFromParent() → Object3D
    Removes this object from its current parent.
    inherited
    removeList(List<Object3D> objects) → Object3D
    Removes list of objects from this object.
    inherited
    rotateOnAxis(Vector3 axis, double angle) → Object3D
    axis -- A normalized vector in object space.
    inherited
    rotateOnWorldAxis(Vector3 axis, double angle) → Object3D
    axis -- A normalized vector in world space.
    inherited
    rotateX(double angle) → Object3D
    angle - the angle to rotate in radians.
    inherited
    rotateY(double angle) → Object3D
    angle - the angle to rotate in radians.
    inherited
    rotateZ(double angle) → Object3D
    angle - the angle to rotate in radians.
    inherited
    serialize(Map<String, dynamic> library, dynamic element, Object3dMeta? meta) → String
    inherited
    setProperty(String propertyName, dynamic value) → Light
    inherited
    setRotationFromAxisAngle(Vector3 axis, double angle) → void
    axis - A normalized vector in object space.
    inherited
    setRotationFromEuler(Euler euler) → void
    euler -- Euler angle specifying rotation amount.
    inherited
    setRotationFromMatrix(dynamic m) → void
    m - rotate the quaternion by the rotation component of the matrix.
    inherited
    setRotationFromQuaternion(Quaternion q) → void
    q - normalized Quaternion.
    inherited
    toJson({Object3dMeta? meta}) → Map<String, dynamic>
    meta - object containing metadata such as materials, textures for objects.
    inherited
    toString() → String
    A string representation of this object.
    inherited
    translateOnAxis(Vector3 axis, double distance) → Object3D
    axis - A normalized vector in object space.
    inherited
    translateX(double distance) → Object3D
    Translates object along x axis in object space by distance units.
    inherited
    translateY(double distance) → Object3D
    Translates object along y axis in object space by distance units.
    inherited
    translateZ(double distance) → Object3D
    Translates object along z axis in object space by distance units.
    inherited
    traverse(dynamic callback(Object3D)) → void
    callback - A function with as first argument an object3D object.
    inherited
    traverseAncestors(dynamic callback(Object3D?)) → void
    callback - A function with as first argument an object3D object.
    inherited
    traverseVisible(dynamic callback(Object3D?)) → void
    callback - A function with as first argument an object3D object.
    inherited
    updateMatrix() → void
    Updates the local transform.
    inherited
    updateMatrixWorld([bool force = false]) → void
    force - A boolean that can be used to bypass matrixWorldAutoUpdate, to recalculate the world matrix of the object and descendants on the current frame. Useful if you cannot wait for the renderer to update it on the next frame (assuming matrixWorldAutoUpdate set to true).
    inherited
    updateWorldMatrix(bool updateParents, bool updateChildren) → void
    updateParents - recursively updates global transform of ancestors.
    inherited
    worldToLocal(Vector3 vector) → Vector3
    vector - A vector representing a position in world space.
    inherited

    Operators

    operator ==(Object other) → bool
    The equality operator.
    inherited