Skip to content

Commit 5a24dac

Browse files
mrdoobmrdoob
authored
Merge pull request mrdoob#10362 from looeee/docs/lights/update
Updated docs for lights
2 parents 3ac9be7 + adcfead commit 5a24dac

10 files changed

Lines changed: 516 additions & 316 deletions

‎docs/api/lights/AmbientLight.html‎

Lines changed: 32 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -13,17 +13,21 @@
1313
<h1>[name]</h1>
1414

1515
<div class="desc">
16-
This light's color gets applied to all the objects in the scene globally.
16+
This light globally illuminates all objects in the scene equally.<br /><br />
17+
18+
This light cannot be used to cast shadows as it does not have a direction.
1719
</div>
1820

1921

2022
<h2>Example</h2>
21-
<div>[example:canvas_camera_orthographic camera / orthographic ]</div>
22-
<div>[example:canvas_interactive_voxelpainter interactive / voxelpainter ]</div>
23-
<div>[example:canvas_materials materials ]</div>
24-
<div>[example:canvas_sandbox sandbox ]</div>
25-
<div>[example:webgl_animation_cloth animation / cloth ]</div>
26-
<div>[example:webgl_animation_skinning_blending animation / skinning / blending ]</div>
23+
<div>
24+
[example:canvas_camera_orthographic camera / orthographic ]<br />
25+
[example:canvas_interactive_voxelpainter interactive / voxelpainter ]<br />
26+
[example:canvas_materials materials ]<br />
27+
[example:canvas_sandbox sandbox ]<br />
28+
[example:webgl_animation_cloth animation / cloth ]<br />
29+
[example:webgl_animation_skinning_blending animation / skinning / blending ]
30+
</div>
2731

2832
<code>var light = new THREE.AmbientLight( 0x404040 ); // soft white light
2933
scene.add( light );</code>
@@ -33,20 +37,35 @@ <h2>Constructor</h2>
3337
<h3>[name]( [page:Integer color], [page:Float intensity] )</h3>
3438
<div>
3539
[page:Integer color] — Numeric value of the RGB component of the color. <br />
36-
[page:Float intensity] -- Numeric value of the light's strength/intensity.
40+
[page:Float intensity] -- Numeric value of the light's strength/intensity.<br /><br />
41+
42+
Creates a new [name].
3743
</div>
44+
45+
<h2>Properties</h2>
3846
<div>
39-
This creates an Ambientlight with a color and intensity.
47+
See the base [page:Light Light] class for common properties.
4048
</div>
4149

42-
<h2>Properties</h2>
50+
<h3>[property:Boolean castShadow]</h3>
51+
<div>
52+
This is set to *undefined* in the constructor as ambient lights cannot cast shadows.
53+
</div>
4354

44-
See the base [page:Light Light] class for common properties.
4555

46-
<h2>Methods</h2>
56+
<h3>[property:Boolean isAmbientLight]</h3>
57+
<div>
58+
Used to check whether this or derived classes are ambient lights. Default is *true*.<br /><br />
59+
60+
You should not change this, as it used internally for optimisation.
61+
</div>
4762

48-
See the base [page:Light Light] class for common methods.
4963

64+
65+
<h2>Methods</h2>
66+
<div>
67+
See the base [page:Light Light] class for common methods.
68+
</div>
5069
<h2>Source</h2>
5170

5271
[link:https://github.com/mrdoob/three.js/blob/master/src/[path].js src/[path].js]

‎docs/api/lights/DirectionalLight.html‎

Lines changed: 85 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -13,70 +13,126 @@
1313
<h1>[name]</h1>
1414

1515
<div class="desc">
16-
Affects objects using [page:MeshLambertMaterial] or [page:MeshPhongMaterial].
16+
A light that gets emitted in a specific direction. This light will behave as though it is
17+
infinitely far away and the rays produced from it are all parallel. The common use case
18+
for this is to simulate daylight; the sun is far enough away that its position can be
19+
considered to be infinite, and all light rays coming from it are parallel.<br /><br />
20+
21+
This light can cast shadows - see the [page:DirectionalLightShadow] page for details.
22+
</div>
23+
24+
<h2>A Note about Position, Target and rotation</h2>
25+
<div>
26+
A common point of confusion for directional lights is that setting the rotation has no effect.
27+
This is because Three's DirectionalLight is the equivalent to what is often called a 'Target
28+
Direct Light' in other applications.<br /><br />
29+
30+
This means that its direction is calculated as pointing
31+
from the light's [page:Object3D.position position] to the [page:.target target]'s position
32+
(as opposed to a a 'Free Direct Light' that just has a rotation component).<br /><br />
33+
34+
The reason for this is to allow the light to cast shadows - the [page:.shadow shadow]
35+
camera needs a position to calculate shadows from.<br /><br />
36+
37+
See the [page:.target target] property below for details on updating the target.
1738
</div>
1839

1940

2041
<h2>Example</h2>
21-
<div>[example:canvas_morphtargets_horse morphtargets / horse ]</div>
22-
<div>[example:misc_controls_fly controls / fly ]</div>
23-
<div>[example:misc_lights_test lights / test ]</div>
24-
<div>[example:vr_cubes cubes ]</div>
25-
<div>[example:webgl_effects_parallaxbarrier effects / parallaxbarrier ]</div>
26-
<div>[example:webgl_effects_stereo effects / stereo ]</div>
27-
<div>[example:webgl_geometry_extrude_splines geometry / extrude / splines ]</div>
28-
<div>[example:webgl_materials_bumpmap materials / bumpmap ]</div>
29-
<div>[example:webgl_materials_cubemap_balls_reflection materials / cubemap / balls / reflection ]</div>
30-
31-
<code>// White directional light at half intensity shining from the top.
42+
<div>
43+
[example:canvas_morphtargets_horse morphtargets / horse ]<br />
44+
[example:misc_controls_fly controls / fly ]<br />
45+
[example:misc_lights_test lights / test ]<br />
46+
[example:vr_cubes cubes ]<br />
47+
[example:webgl_effects_parallaxbarrier effects / parallaxbarrier ]<br />
48+
[example:webgl_effects_stereo effects / stereo ]<br />
49+
[example:webgl_geometry_extrude_splines geometry / extrude / splines ]<br />
50+
[example:webgl_materials_bumpmap materials / bumpmap ]<br />
51+
[example:webgl_materials_cubemap_balls_reflection materials / cubemap / balls / reflection ]
52+
</div>
3253

54+
<code>
55+
// White directional light at half intensity shining from the top.
3356
var directionalLight = new THREE.DirectionalLight( 0xffffff, 0.5 );
3457
directionalLight.position.set( 0, 1, 0 );
35-
scene.add( directionalLight );</code>
58+
scene.add( directionalLight );
59+
</code>
3660

3761

3862
<h2>Constructor</h2>
3963

4064
<h3>[name]( [page:Integer hex], [page:Float intensity] )</h3>
4165
<div>
42-
[page:Integer hex] -- Numeric value of the RGB component of the color. <br />
43-
[page:Float intensity] -- Numeric value of the light's strength/intensity.
44-
</div>
45-
<div>
46-
Creates a light that shines from a specific direction not from a specific position. This light will behave
47-
as though it is infinitely far away and the rays produced from it are all parallel. The best
48-
analogy would be a light source that acts like the sun: the sun is so far away that all sunlight
49-
hitting objects comes from the same angle.
66+
[page:Integer color] - (optional) hexadecimal color of the light. Default is 0xffffff (white).<br />
67+
[page:Float intensity] - (optional) numeric value of the light's strength/intensity. Default is 1.<br /><br />
68+
69+
Creates a new [name].
5070
</div>
5171

5272
<h2>Properties</h2>
5373

5474
See the base [page:Light Light] class for common properties.
5575

56-
<h3>[property:Object3D target]</h3>
76+
<h3>[property:Boolean castShadow]</h3>
5777
<div>
58-
Target used for shadow camera orientation.
78+
If set to *true* light will cast dynamic shadows. *Warning*: This is expensive and
79+
requires tweaking to get shadows looking right. See the [page:DirectionalLightShadow] for details.
80+
The default is *false*.
81+
</div>
82+
83+
<h3>[property:Boolean isDirectionalLight]</h3>
84+
<div>
85+
Used to check whether this or derived classes are dircrectional lights. Default is *true*.<br /><br />
86+
87+
You should not change this, as it used internally for optimisation.
88+
</div>
89+
90+
91+
<h3>[property:Vector3 position]</h3>
92+
<div>
93+
This is set equal to [page:Object3D.DefaultUp] (0, 1, 0), so that the light shines from the top down.
5994
</div>
6095

6196
<h3>[property:DirectionalLightShadow shadow]</h3>
6297
<div>
63-
This property stores all relevant information for rendering the shadow of the light.<br />
98+
A [page:DirectionalLightShadow] used to calculate shadows for this light.
6499
</div>
65100

66-
<h3>[property:Boolean castShadow]</h3>
101+
<h3>[property:Object3D target]</h3>
67102
<div>
68-
If set to *true* light will cast dynamic shadows. *Warning*: This is expensive and requires tweaking to get shadows looking right.<br />
69-
Default — *false*.
103+
The DirectionalLight points from its [page:.position position] to target.position. The default
104+
position of the target is *(0, 0, 0)*.<br />
105+
106+
*Note*: For the the target's position to be changed to anything other than the default,
107+
it must be added to the [page:Scene scene] using
108+
<code>
109+
scene.add( light.target );
110+
</code>
111+
112+
This is so that the target's [page:Object3D.matrixWorld matrixWorld] gets automatically
113+
updated each frame.<br /><br />
114+
115+
It is also possible to set the target to be another object in the scene (anything with a
116+
[page:Object3D.position position] property), like so:
117+
<code>
118+
var targetObject = new THREE.Object3D();
119+
scene.add(targetObject);
120+
121+
light.target = targetObject;
122+
</code>
123+
The directionalLight will now track the target object.
70124
</div>
71125

126+
127+
72128
<h2>Methods</h2>
73129

74130
See the base [page:Light Light] class for common methods.
75131

76132
<h3>[method:DirectionalLight copy]( [page:DirectionalLight source] )</h3>
77133
<div>
78-
<br />
79-
Copies value of *source* to this DirectionalLight object.
134+
Copies value of all the properties from the [page:DirectionalLight source] to this
135+
DirectionalLight.
80136
</div>
81137

82138
<h2>Source</h2>

‎docs/api/lights/HemisphereLight.html‎

Lines changed: 54 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -12,49 +12,84 @@
1212

1313
<h1>[name]</h1>
1414

15-
<div class="desc">A light source positioned directly above the scene.</div>
15+
<div class="desc">
16+
A light source positioned directly above the scene, with color fading from the
17+
sky color to the ground color. <br /><br />
18+
19+
This light cannot be used to cast shadows.
20+
</div>
1621

1722
<h2>Example</h2>
1823

19-
<div>[example:webgl_lights_hemisphere lights / hemisphere ]</div>
20-
<div>[example:misc_controls_pointerlock controls / pointerlock ]</div>
21-
<div>[example:webgl_decals decals ]</div>
22-
<div>[example:webgl_loader_collada_kinematics loader / collada / kinematics ]</div>
23-
<div>[example:webgl_materials_lightmap materials / lightmap ]</div>
24-
<div>[example:webgl_shaders_ocean shaders / ocean ]</div>
24+
<div>
25+
[example:webgl_lights_hemisphere lights / hemisphere ]<br />
26+
[example:misc_controls_pointerlock controls / pointerlock ]<br />
27+
[example:webgl_decals decals ]<br />
28+
[example:webgl_loader_collada_kinematics loader / collada / kinematics ]<br />
29+
[example:webgl_materials_lightmap materials / lightmap ]<br />
30+
[example:webgl_shaders_ocean shaders / ocean ]
31+
</div>
2532

26-
<code>var light = new THREE.HemisphereLight( 0xffffbb, 0x080820, 1 );
27-
scene.add( light );</code>
33+
<code>
34+
var light = new THREE.HemisphereLight( 0xffffbb, 0x080820, 1 );
35+
scene.add( light );
36+
</code>
2837

2938
<h2>Constructor</h2>
30-
31-
3239
<h3>[name]( [page:Integer skyColor], [page:Integer groundColor], [page:Float intensity] )</h3>
33-
<div>
34-
[page:Integer skyColor] — Numeric value of the RGB sky color.<br />
35-
[page:Integer groundColor] — Numeric value of the RGB ground color.<br />
36-
[page:Float intensity] — Numeric value of the light's strength/intensity.
40+
<div>
41+
[page:Integer skyColor] - (optional) hexadecimal color of the sky. Default is 0xffffff.<br />
42+
[page:Integer groundColor] - (optional) hexadecimal color of the ground. Default is 0xffffff.<br />
43+
[page:Float intensity] - (optional) numeric value of the light's strength/intensity. Default is 1.<br /><br />
44+
45+
Creates a new [name].
3746
</div>
3847

3948
<h2>Properties</h2>
49+
<div>
50+
See the base [page:Light Light] class for common properties.
51+
</div>
52+
53+
<h3>[property:Boolean castShadow]</h3>
54+
<div>
55+
This is set to *undefined* in the constructor as hemisphere lights cannot cast shadows.
56+
</div>
57+
4058

41-
See the base [page:Light Light] class for common properties.
59+
<h3>[property:Float color]</h3>
60+
<div>
61+
The light's sky color, as passed in the constructor.
62+
Default is a new [page:Color] set to white (0xffffff).
63+
</div>
4264

4365
<h3>[property:Float groundColor]</h3>
66+
<div>
67+
The light's ground color, as passed in the constructor.
68+
Default is a new [page:Color] set to white (0xffffff).
69+
</div>
4470

71+
<h3>[property:Boolean isHemisphereLight]</h3>
4572
<div>
46-
Light's ground color.<br />
73+
Used to check whether this or derived classes are hemisphere lights. Default is *true*.<br /><br />
74+
75+
You should not change this, as it used internally for optimisation.
4776
</div>
4877

78+
<h3>[property:Vector3 position]</h3>
79+
<div>
80+
This is set equal to [page:Object3D.DefaultUp] (0, 1, 0), so that the light shines from the top down.
81+
</div>
82+
83+
4984

5085
<h2>Methods</h2>
5186

5287
See the base [page:Light Light] class for common methods.
5388

5489
<h3>[method:HemisphereLight copy]( [page:HemisphereLight source] )</h3>
5590
<div>
56-
<br />
57-
Copies value of *source* to this HemisphereLight object.
91+
Copies the value of [page:.color color], [page:.intensity intensity] and
92+
[page:.groundColor groundColor] from the [page:Light source] light into this one.
5893
</div>
5994

6095
<h2>Source</h2>

0 commit comments

Comments
 (0)