Object3D → Light →

SpotLight

This light gets emitted from a single point in one direction, along a cone that increases in size the further from the light it gets.

This light can cast shadows — see the SpotLightShadow page for details.

Target and Free Spot Lights

In Verge3D, spot lights can operate in two different modes depending on the value of the .isFreeLight flag. If isFreeLight=true SpotLight is the equivalent to what is often called a "Target Spotlight" in 3ds Max. When isFreeLight=true the light is equivalent to "Free Spotlight" in 3ds Max or just "Spot Light" in Blender/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 spotlight shining from the side, modulated by a texture, casting a shadow
    const spotLight = new v3d.SpotLight(0xffffff);
    spotLight.position.set(100, 1000, 100);
    spotLight.map = new v3d.TextureLoader().load(url);

    spotLight.castShadow = true;

    spotLight.shadow.mapSize.width = 1024;
    spotLight.shadow.mapSize.height = 1024;

    spotLight.shadow.camera.near = 500;
    spotLight.shadow.camera.far = 4000;
    spotLight.shadow.camera.fov = 30;

    scene.add(spotLight);

Examples

lights / spotlight
lights / spotlights

Constructor

SpotLight(color : Integer, intensity : Float, distance : Float, angle : Radians, penumbra : Float, decay : 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.
distance — Maximum range of the light. Default is 0 (no limit).
angle — Maximum angle of light dispersion from its direction whose upper bound is Math.PI/2.
penumbra — Percent of the spotlight cone that is attenuated due to penumbra. Takes values between zero and 1. Default is zero.
decay — The amount the light dims along the distance of the light.

Creates a new SpotLight.

Properties

See the base Light class for common properties.

# .angle : Float

Maximum extent of the spotlight, in radians, from its direction. Should be no more than Math.PI/2. The default is Math.PI/3.

# .castShadow : Boolean

If set to true light will cast dynamic shadows. Warning: This is expensive and requires tweaking to get shadows looking right. See the SpotLightShadow for details. The default is false.

# .decay : Float

The amount the light dims along the distance of the light. Default is 2.
In context of physically-correct rendering the default value should not be changed.

# .distance : Float

Default mode — When distance is zero, light does not attenuate. When distance is non-zero, light will attenuate linearly from maximum intensity at the light's position down to zero at this distance from the light.

Physically correct mode — When distance is zero, light will attenuate according to inverse-square law to infinite distance. When distance is non-zero, light will attenuate according to inverse-square law until near the distance cutoff, where it will then attenuate quickly and smoothly to 0. Inherently, cutoffs are not physically correct.

Default is 0.0.

# .intensity : Float

The light's intensity. Default is 1. In physically correct mode, intensity is the luminous intensity of the light measured in candela (cd).

Changing the intensity will also change the light's power.

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

# .isSpotLight : Boolean

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

# .penumbra : Float

Percent of the spotlight cone that is attenuated due to penumbra. Takes values between zero and 1. The default is 0.0.

# .position : Vector3

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

# .power : Float

The light's power. In physically correct mode, power is the luminous power of the light measured in lumens (lm).

Changing the power will also change the light's intensity.

# .shadow : SpotLightShadow

A SpotLightShadow used to calculate shadows for this light.

# .target : Object3D

The Spotlight 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


    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();
    scene.add(targetObject);

    light.target = targetObject;

The spotlight will now track the target object.

# .map : Texture

A Texture used to modulate the color of the light. The spot light color is mixed with the RGB value of this texture, with a ratio corresponding to its alpha value. The cookie-like masking effect is reproduced using pixel values (0, 0, 0, 1-cookie_value). Warning: .map is disabled if .castShadow is false.

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 : SpotLight) → this

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

Puzzles

The following puzzles work with the spot lights:

create object — select light, then spot.
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.