|
|
@@ -13,70 +13,126 @@
|
|
|
<h1>[name]</h1>
|
|
|
|
|
|
<div class="desc">
|
|
|
- Affects objects using [page:MeshLambertMaterial] or [page:MeshPhongMaterial].
|
|
|
+ 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.<br /><br />
|
|
|
+
|
|
|
+ This light can cast shadows - see the [page:DirectionalLightShadow] page for details.
|
|
|
+ </div>
|
|
|
+
|
|
|
+ <h2>A Note about Position, Target and rotation</h2>
|
|
|
+ <div>
|
|
|
+ A common point of confusion for directional lights is that setting the rotation has no effect.
|
|
|
+ This is because Three's DirectionalLight is the equivalent to what is often called a 'Target
|
|
|
+ Direct Light' in other applications.<br /><br />
|
|
|
+
|
|
|
+ This means that its direction is calculated as pointing
|
|
|
+ from the light's [page:Object3D.position position] to the [page:.target target]'s position
|
|
|
+ (as opposed to a a 'Free Direct Light' that just has a rotation component).<br /><br />
|
|
|
+
|
|
|
+ The reason for this is to allow the light to cast shadows - the [page:.shadow shadow]
|
|
|
+ camera needs a position to calculate shadows from.<br /><br />
|
|
|
+
|
|
|
+ See the [page:.target target] property below for details on updating the target.
|
|
|
</div>
|
|
|
|
|
|
|
|
|
<h2>Example</h2>
|
|
|
- <div>[example:canvas_morphtargets_horse morphtargets / horse ]</div>
|
|
|
- <div>[example:misc_controls_fly controls / fly ]</div>
|
|
|
- <div>[example:misc_lights_test lights / test ]</div>
|
|
|
- <div>[example:vr_cubes cubes ]</div>
|
|
|
- <div>[example:webgl_effects_parallaxbarrier effects / parallaxbarrier ]</div>
|
|
|
- <div>[example:webgl_effects_stereo effects / stereo ]</div>
|
|
|
- <div>[example:webgl_geometry_extrude_splines geometry / extrude / splines ]</div>
|
|
|
- <div>[example:webgl_materials_bumpmap materials / bumpmap ]</div>
|
|
|
- <div>[example:webgl_materials_cubemap_balls_reflection materials / cubemap / balls / reflection ]</div>
|
|
|
-
|
|
|
- <code>// White directional light at half intensity shining from the top.
|
|
|
+ <div>
|
|
|
+ [example:canvas_morphtargets_horse morphtargets / horse ]<br />
|
|
|
+ [example:misc_controls_fly controls / fly ]<br />
|
|
|
+ [example:misc_lights_test lights / test ]<br />
|
|
|
+ [example:vr_cubes cubes ]<br />
|
|
|
+ [example:webgl_effects_parallaxbarrier effects / parallaxbarrier ]<br />
|
|
|
+ [example:webgl_effects_stereo effects / stereo ]<br />
|
|
|
+ [example:webgl_geometry_extrude_splines geometry / extrude / splines ]<br />
|
|
|
+ [example:webgl_materials_bumpmap materials / bumpmap ]<br />
|
|
|
+ [example:webgl_materials_cubemap_balls_reflection materials / cubemap / balls / reflection ]
|
|
|
+ </div>
|
|
|
|
|
|
+ <code>
|
|
|
+// White directional light at half intensity shining from the top.
|
|
|
var directionalLight = new THREE.DirectionalLight( 0xffffff, 0.5 );
|
|
|
directionalLight.position.set( 0, 1, 0 );
|
|
|
-scene.add( directionalLight );</code>
|
|
|
+scene.add( directionalLight );
|
|
|
+ </code>
|
|
|
|
|
|
|
|
|
<h2>Constructor</h2>
|
|
|
|
|
|
<h3>[name]( [page:Integer hex], [page:Float intensity] )</h3>
|
|
|
<div>
|
|
|
- [page:Integer hex] -- Numeric value of the RGB component of the color. <br />
|
|
|
- [page:Float intensity] -- Numeric value of the light's strength/intensity.
|
|
|
- </div>
|
|
|
- <div>
|
|
|
- Creates a light that shines from a specific direction not from a specific position. This light will behave
|
|
|
- as though it is infinitely far away and the rays produced from it are all parallel. The best
|
|
|
- analogy would be a light source that acts like the sun: the sun is so far away that all sunlight
|
|
|
- hitting objects comes from the same angle.
|
|
|
+ [page:Integer color] - (optional) hexadecimal color of the light. Default is 0xffffff (white).<br />
|
|
|
+ [page:Float intensity] - (optional) numeric value of the light's strength/intensity. Default is 1.<br /><br />
|
|
|
+
|
|
|
+ Creates a new [name].
|
|
|
</div>
|
|
|
|
|
|
<h2>Properties</h2>
|
|
|
|
|
|
See the base [page:Light Light] class for common properties.
|
|
|
|
|
|
- <h3>[property:Object3D target]</h3>
|
|
|
+ <h3>[property:Boolean castShadow]</h3>
|
|
|
<div>
|
|
|
- Target used for shadow camera orientation.
|
|
|
+ If set to *true* light will cast dynamic shadows. *Warning*: This is expensive and
|
|
|
+ requires tweaking to get shadows looking right. See the [page:DirectionalLightShadow] for details.
|
|
|
+ The default is *false*.
|
|
|
+ </div>
|
|
|
+
|
|
|
+ <h3>[property:Boolean isDirectionalLight]</h3>
|
|
|
+ <div>
|
|
|
+ Used to check whether this or derived classes are dircrectional lights. Default is *true*.<br /><br />
|
|
|
+
|
|
|
+ You should not change this, as it used internally for optimisation.
|
|
|
+ </div>
|
|
|
+
|
|
|
+
|
|
|
+ <h3>[property:Vector3 position]</h3>
|
|
|
+ <div>
|
|
|
+ This is set equal to [page:Object3D.DefaultUp] (0, 1, 0), so that the light shines from the top down.
|
|
|
</div>
|
|
|
|
|
|
<h3>[property:DirectionalLightShadow shadow]</h3>
|
|
|
<div>
|
|
|
- This property stores all relevant information for rendering the shadow of the light.<br />
|
|
|
+ A [page:DirectionalLightShadow] used to calculate shadows for this light.
|
|
|
</div>
|
|
|
|
|
|
- <h3>[property:Boolean castShadow]</h3>
|
|
|
+ <h3>[property:Object3D target]</h3>
|
|
|
<div>
|
|
|
- If set to *true* light will cast dynamic shadows. *Warning*: This is expensive and requires tweaking to get shadows looking right.<br />
|
|
|
- Default — *false*.
|
|
|
+ The DirectionalLight points from its [page:.position position] to target.position. The default
|
|
|
+ position of the target is *(0, 0, 0)*.<br />
|
|
|
+
|
|
|
+ *Note*: For the the target's position to be changed to anything other than the default,
|
|
|
+ it must be added to the [page:Scene scene] using
|
|
|
+ <code>
|
|
|
+ scene.add( light.target );
|
|
|
+ </code>
|
|
|
+
|
|
|
+ This is so that the target's [page:Object3D.matrixWorld matrixWorld] gets automatically
|
|
|
+ updated each frame.<br /><br />
|
|
|
+
|
|
|
+ It is also possible to set the target to be another object in the scene (anything with a
|
|
|
+ [page:Object3D.position position] property), like so:
|
|
|
+ <code>
|
|
|
+ var targetObject = new THREE.Object3D();
|
|
|
+ scene.add(targetObject);
|
|
|
+
|
|
|
+ light.target = targetObject;
|
|
|
+ </code>
|
|
|
+ The directionalLight will now track the target object.
|
|
|
</div>
|
|
|
|
|
|
+
|
|
|
+
|
|
|
<h2>Methods</h2>
|
|
|
|
|
|
See the base [page:Light Light] class for common methods.
|
|
|
|
|
|
<h3>[method:DirectionalLight copy]( [page:DirectionalLight source] )</h3>
|
|
|
<div>
|
|
|
- <br />
|
|
|
- Copies value of *source* to this DirectionalLight object.
|
|
|
+ Copies value of all the properties from the [page:DirectionalLight source] to this
|
|
|
+ DirectionalLight.
|
|
|
</div>
|
|
|
|
|
|
<h2>Source</h2>
|
Lewy Blue