Object3D → Light →

DirectionalLight

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 DirectionalLightShadowCSM page for details.

Target and Free Directional Lights

In Verge3D, directional lights can operate in two different modes depending on the value of the .isFreeLight flag. If isFreeLight=true DirectionalLight is the equivalent to what is often called a "Target Directional Light" in 3ds Max. When isFreeLight=true the light is equivalent to "Free Directional Light" in 3ds Max, "Sun" in Blender, or just "Directional Light" in Maya.

In any case, the light direction is calculated as pointing from the light's position to the target's position. In the first mode, target is specified explicitly, while in the second mode, target is calculated by the engine from the light object rotation.

Code Example


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

Constructor

DirectionalLight(color : Integer, intensity : Float)

color — (optional) hexadecimal color of the light. Default is 0xffffff (white).
intensity — (optional) numeric value of the light's strength/intensity. Default is 1.

Creates a new DirectionalLight.

Properties

See the base Light class for common properties.

# .castShadow : Boolean

If set to true light will cast dynamic shadows. This might require tweaking to get shadows looking right. See the DirectionalLightShadowCSM for details. The default is false.

# .isDirectionalLight : Boolean

Read-only flag to check if a given object is of type DirectionalLight.

# .isFreeLight : Boolean

Flag which used to define the lights with no explicit target. For such lights the virtual target is calculated from the rotation applied to the light object.

# .position : Vector3

This is set equal to Object3D.DefaultUp (0, 1, 0), so that the light shines from the top down.

# .shadow : DirectionalLightShadowCSM

A DirectionalLightShadowCSM used to calculate shadows for this light.

# .target : Object3D

The DirectionalLight points from its position to target.position. The default position of the target is (0, 0, 0).

For the target's position to be changed to anything other than the default, it must be added to the scene using


    app.scene.add(light.target);

This is so that the target's matrixWorld gets automatically updated each frame.

If isFreeLight=false is also possible to set the target to be another object in the scene (anything with a position property), like so:


    const targetObject = new v3d.Object3D();
    app.scene.add(targetObject);

    light.target = targetObject;

The directionalLight will now track the target object.

Methods

See the base Light class for common methods.

# .dispose()

Frees the GPU-related resources allocated by this instance. Call this method whenever this instance is no longer used in your app.

# .copy(source : DirectionalLight) → this

Copies value of all the properties from the source to this DirectionalLight.

Puzzles

The following puzzles work with the directional lights:

create object — select light, then directional.
set light param — to set various light parameters.
get light param — to obtain light parameters.

Source

For more info on how to obtain the source code of this module see this page.