Merge pull request #10362 from looeee/docs/lights/update

Updated docs for lights

docs/api/lights/AmbientLight.html

@@ -13,17 +13,21 @@
 		<h1>[name]</h1>
 
 		<div class="desc">
-			This light's color gets applied to all the objects in the scene globally.
+			This light globally illuminates all objects in the scene equally.<br /><br />
+
+			This light cannot be used to cast shadows as it does not have a direction. 
 		</div>
 
 
 		<h2>Example</h2>
-		<div>[example:canvas_camera_orthographic camera / orthographic ]</div>
-		<div>[example:canvas_interactive_voxelpainter interactive / voxelpainter ]</div>
-		<div>[example:canvas_materials materials ]</div>
-		<div>[example:canvas_sandbox sandbox ]</div>
-		<div>[example:webgl_animation_cloth animation / cloth ]</div>
-		<div>[example:webgl_animation_skinning_blending animation / skinning / blending ]</div>
+		<div>
+			[example:canvas_camera_orthographic camera / orthographic ]<br />
+		  [example:canvas_interactive_voxelpainter interactive / voxelpainter ]<br />
+		  [example:canvas_materials materials ]<br />
+		  [example:canvas_sandbox sandbox ]<br />
+		  [example:webgl_animation_cloth animation / cloth ]<br />
+		  [example:webgl_animation_skinning_blending animation / skinning / blending ]
+		</div>
 
 <code>var light = new THREE.AmbientLight( 0x404040 ); // soft white light
 scene.add( light );</code>
@@ -33,20 +37,35 @@ scene.add( light );</code>
 		<h3>[name]( [page:Integer color], [page:Float intensity] )</h3>
 		<div>
 		[page:Integer color] — Numeric value of the RGB component of the color. <br />
-		[page:Float intensity] -- Numeric value of the light's strength/intensity.
+		[page:Float intensity] -- Numeric value of the light's strength/intensity.<br /><br />
+
+		Creates a new [name].
 		</div>
+
+		<h2>Properties</h2>
 		<div>
-		This creates an Ambientlight with a color and intensity.
+				See the base [page:Light Light] class for common properties.
 		</div>
 
-		<h2>Properties</h2>
+		<h3>[property:Boolean castShadow]</h3>
+		<div>
+			This is set to *undefined* in the constructor as ambient lights cannot cast shadows.
+		</div>
 
-		See the base [page:Light Light] class for common properties.
 
-		<h2>Methods</h2>
+		<h3>[property:Boolean isAmbientLight]</h3>
+		<div>
+			Used to check whether this or derived classes are ambient lights. Default is *true*.<br /><br />
+
+			You should not change this, as it used internally for optimisation.
+		</div>
 
-		See the base [page:Light Light] class for common methods.
 
+
+		<h2>Methods</h2>
+		<div>
+				See the base [page:Light Light] class for common methods.
+		</div>
 		<h2>Source</h2>
 
 		[link:https://github.com/mrdoob/three.js/blob/master/src/[path].js src/[path].js]

docs/api/lights/DirectionalLight.html

@@ -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>

docs/api/lights/HemisphereLight.html

@@ -12,40 +12,75 @@
 
 		<h1>[name]</h1>
 
-		<div class="desc">A light source positioned directly above the scene.</div>
+		<div class="desc">
+			A light source positioned directly above the scene, with color fading from the
+			sky color to the ground color. <br /><br />
+
+			This light cannot be used to cast shadows.
+		</div>
 
 		<h2>Example</h2>
 
-		<div>[example:webgl_lights_hemisphere lights / hemisphere ]</div>
-		<div>[example:misc_controls_pointerlock controls / pointerlock ]</div>
-		<div>[example:webgl_decals decals ]</div>
-		<div>[example:webgl_loader_collada_kinematics loader / collada / kinematics ]</div>
-		<div>[example:webgl_materials_lightmap materials / lightmap ]</div>
-		<div>[example:webgl_shaders_ocean shaders / ocean ]</div>
+		<div>
+			[example:webgl_lights_hemisphere lights / hemisphere ]<br />
+		  [example:misc_controls_pointerlock controls / pointerlock ]<br />
+		  [example:webgl_decals decals ]<br />
+		  [example:webgl_loader_collada_kinematics loader / collada / kinematics ]<br />
+		  [example:webgl_materials_lightmap materials / lightmap ]<br />
+		  [example:webgl_shaders_ocean shaders / ocean ]
+		</div>
 
-<code>var light = new THREE.HemisphereLight( 0xffffbb, 0x080820, 1 );
-scene.add( light );</code>
+<code>
+var light = new THREE.HemisphereLight( 0xffffbb, 0x080820, 1 );
+scene.add( light );
+</code>
 
 		<h2>Constructor</h2>
-
-
 		<h3>[name]( [page:Integer skyColor], [page:Integer groundColor], [page:Float intensity] )</h3>
-        <div>
-		[page:Integer skyColor] — Numeric value of the RGB sky color.<br />
-		[page:Integer groundColor] — Numeric value of the RGB ground color.<br />
-		[page:Float intensity] — Numeric value of the light's strength/intensity.
+    <div>
+		[page:Integer skyColor] - (optional) hexadecimal color of the sky. Default is 0xffffff.<br />
+		[page:Integer groundColor] - (optional) hexadecimal color of the ground. Default is 0xffffff.<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>
+		<div>
+			See the base [page:Light Light] class for common properties.
+		</div>
+
+		<h3>[property:Boolean castShadow]</h3>
+		<div>
+			This is set to *undefined* in the constructor as hemisphere lights cannot cast shadows.
+		</div>
+
 
-		See the base [page:Light Light] class for common properties.
+		<h3>[property:Float color]</h3>
+		<div>
+			The light's sky color, as passed in the constructor.
+			Default is a new [page:Color] set to white (0xffffff).
+		</div>
 
 		<h3>[property:Float groundColor]</h3>
+		<div>
+			The light's ground color, as passed in the constructor.
+			Default is a new [page:Color] set to white (0xffffff).
+		</div>
 
+		<h3>[property:Boolean isHemisphereLight]</h3>
 		<div>
-			Light's ground color.<br />
+			Used to check whether this or derived classes are hemisphere 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>
+
+
 
 		<h2>Methods</h2>
 
@@ -53,8 +88,8 @@ scene.add( light );</code>
 
 		<h3>[method:HemisphereLight copy]( [page:HemisphereLight source] )</h3>
 		<div>
-		<br />
-		Copies value of *source* to this HemisphereLight object.
+			Copies the value of [page:.color color], [page:.intensity intensity] and
+			[page:.groundColor groundColor] from the [page:Light source] light into this one.
 		</div>
 
 		<h2>Source</h2>

docs/api/lights/Light.html

@@ -12,7 +12,10 @@
 
 		<h1>[name]</h1>
 
-		<div class="desc">Abstract base class for lights.</div>
+		<div class="desc">
+			Abstract base class for lights - all other light types inherit the properties and methods
+			described here.
+		</div>
 
 
 		<h2>Constructor</h2>
@@ -20,37 +23,50 @@
 
 		<h3>[name]( [page:Integer color], [page:float intensity] )</h3>
 		<div>
-		[page:Integer color] — Numeric value of the RGB component of the color.<br />
-		[page:Float intensity] — Numeric value of the light's strength/intensity.
-		</div>
-		<div>
-		This creates a light with color and intensity.<br />
+		[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]. Note that this is not intended to be called directly (use one of <thead>
+			derived classes instead).
+		</thead>)
 		</div>
 
 		<h2>Properties</h2>
-
-		See the base [page:Object3D Object3D] class for common properties.
+		<div>
+			See the base [page:Object3D Object3D] class for common properties.
+		</div>
 
 		<h3>[property:Color color]</h3>
 		<div>
-			Color of the light.<br />
+			Color of the light. Defaults to a new [page:Color] set to white, if not passed in the constructor.<br />
 		</div>
 
 		<h3>[property:Float intensity]</h3>
 		<div>
-			Light's intensity.<br />
-			In "physically correct" mode, the product of color * intensity is interpreted as luminous intensity measured in candela.<br/>
-			Default — *1.0*.
+			The light's intensity, or strength.<br />
+			In [page:WebGLRenderer.physicallyCorrectLights physically correct] mode, the product of
+			[page:.color color] * intensity is interpreted as luminous intensity measured in candela.<br />
+			Default - *1.0*.
 		</div>
 
+		<h3>[property:Boolean isLight]</h3>
+		<div>
+			Used to check whether this or derived classes are lights. Default is *true*.<br /><br />
+
+			You should not change this, as it used internally for optimisation.
+		</div>
+
+
 		<h2>Methods</h2>
+		<div>
+			See the base [page:Object3D Object3D] class for common methods.
+		</div>
 
-		See the base [page:Object3D Object3D] class for common methods.
 
 		<h3>[method:Light copy]( [page:Light source] )</h3>
 		<div>
-		<br />
-		Copies value of *source* to this Light object.
+		Copies the value of [page:.color color] and [page:.intensity intensity] from the
+		[page:Light source] light into this one.
 		</div>
 
 		<h3>[method:JSON toJSON]( [page:String meta] )</h3>

docs/api/lights/PointLight.html

@@ -13,79 +13,104 @@
 		<h1>[name]</h1>
 
 		<div class="desc">
-			Affects objects using [page:MeshLambertMaterial] or [page:MeshPhongMaterial].
+			A light that gets emitted from a single point in all directions. A common use case for this
+			is to replicate the light emitted from a bare lightbulb.<br /><br />
+
+			 This light can cast shadows - see [page:LightShadow] page for details.
 		</div>
 
 
 		<h2>Example</h2>
 
-		<div>[example:canvas_lights_pointlights lights / pointlights ]</div>
-		<div>[example:webgl_lights_pointlights lights / pointlights ]</div>
-		<div>[example:webgl_lights_pointlights2 lights / pointlights2 ]</div>
-		<div>[example:webgldeferred_animation animation ]</div>
-		<div>[example:webgldeferred_pointlights pointlights ]</div>
-		<div>[example:webgl_effects_anaglyph effects / anaglyph ]</div>
-		<div>[example:webgl_geometry_large_mesh geometry / large / mesh ]</div>
-		<div>[example:webgl_geometry_text geometry / text ]</div>
-		<div>[example:webgl_lensflares lensflares ]</div>
-
-		<code>var light = new THREE.PointLight( 0xff0000, 1, 100 );
+		<div>
+			[example:canvas_lights_pointlights lights / pointlights ]<br />
+			[example:webgl_lights_pointlights lights / pointlights ]<br />
+			[example:webgl_lights_pointlights2 lights / pointlights2 ]<br />
+			[example:webgldeferred_animation animation ]<br />
+			[example:webgldeferred_pointlights pointlights ]<br />
+			[example:webgl_effects_anaglyph effects / anaglyph ]<br />
+			[example:webgl_geometry_large_mesh geometry / large / mesh ]<br />
+			[example:webgl_geometry_text geometry / text ]<br />
+			[example:webgl_lensflares lensflares ]
+		</div>
+
+		<code>
+var light = new THREE.PointLight( 0xff0000, 1, 100 );
 light.position.set( 50, 50, 50 );
-scene.add( light );</code>
+scene.add( light );
+		</code>
 
 
 		<h2>Constructor</h2>
 
-
 		<h3>[name]( [page:Integer color], [page:Float intensity], [page:Number distance], [page:Float decay] )</h3>
 		<div>
-		[page:Integer color] — Numeric value of the RGB component of the color. <br />
-		[page:Float intensity] — Numeric value of the light's strength/intensity. <br />
-		[page:Number distance] -- The distance of the light where the intensity is 0. When distance is 0, then the distance is endless. <br />
-		[page:Float decay] -- The amount the light dims along the distance of the light.
-		</div>
-		<div>
-		Creates a light at a specific position in the scene.  The light shines in all directions (roughly similar to a light bulb.)
-
+			[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 />
+			[page:Number distance] - The distance from the light where the intensity is 0.
+			When set to 0, then the light never stops. Default is 0.<br />
+			[page:Float decay] - The amount the light dims along the distance of the light. Default is 1.
+			For [page:WebGLRenderer.physicallyCorrectLights physically correct] lighting, set this to 2.<br /><br />
+
+			Creates a new [name].
 		</div>
 
 		<h2>Properties</h2>
+		<div>
+			See the base [page:Light Light] class for common properties.
+		</div>
 
-		See the base [page:Light Light] class for common properties.
-
-		<h3>[property:Float power]</h3>
+		<h3>[property:Float decay]</h3>
 		<div>
-			Light's power.<br />
-			In "physically correct" mode, the luminous power of the light measured in lumens.<br/>
-			Default - *4PI*.
+			The amount the light dims along the distance of the light<br />
+			In [page:WebGLRenderer.physicallyCorrectLights physically correct] mode, decay = 2 leads to physically realistic light falloff.<br/>
+			Default is *1*.
 		</div>
 
 		<h3>[property:Float distance]</h3>
 		<div>
-			If non-zero, light will attenuate linearly from maximum intensity at light *position* down to zero at *distance*.<br />
-			Default — *0.0*.
+			If non-zero, light will attenuate linearly from maximum intensity at the light's
+			position down to zero at this distance from the light. Default is *0.0*.
 		</div>
 
-		<h3>[property:Float decay]</h3>
+		<h3>[property:Boolean isPointLight]</h3>
 		<div>
-			The amount the light dims along the distance of the light<br />
-			In "physically correct" mode, decay = 2 leads to physically realistic light falloff.<br/>
-			Default — *1*.
+			Used to check whether this or derived classes are point lights. Default is *true*.<br /><br />
+
+			You should not change this, as it used internally for optimisation.
+		</div>
+
+		<h3>[property:Float power]</h3>
+		<div>
+			The light's power.<br />
+			In [page:WebGLRenderer.physicallyCorrectLights physically correct] mode, the luminous
+			power of the light measured in lumens. Default - *4PI*. <br /><br />
+
+			This is directly related to the [page:.intensity intensity] in the ratio
+			<code>
+				power = intensity * 4&Pi;
+			</code>
+			and changing this will also change the intensity.
 		</div>
 
 		<h3>[property:LightShadow shadow]</h3>
 		<div>
-			This property stores all relevant information for rendering the shadow of the light.<br />
+			A [page:LightShadow] used to calculate shadows for this light.<br />
+			 The lightShadow's [page:LightShadow.camera camera]
+			is set to a  [page:PerspectiveCamera] with [page:PerspectiveCamera.fov fov] of 90,
+			[page:PerspectiveCamera.aspect aspect] of 1, [page:PerspectiveCamera.near near]
+			clipping plane at 0.5 and	[page:PerspectiveCamera.far far] clipping plane at 500.
 		</div>
 
 		<h2>Methods</h2>
-
-		See the base [page:Light Light] class for common methods.
+		<div>
+			See the base [page:Light Light] class for common methods.
+		</div>
 
 		<h3>[method:PointLight copy]( [page:PointLight source] )</h3>
 		<div>
-		<br />
-		Copies value of *source* to this PointLight object.
+		Copies value of all the properties from the [page:PointLight source] to this
+		PointLight.
 		</div>
 
 		<h2>Source</h2>

docs/api/lights/SpotLight.html

@@ -12,28 +12,42 @@
 
 		<h1>[name]</h1>
 
-		<div class="desc">A point light that can cast a shadow in one direction within a falloff cone.</div>
+		<div class="desc">
+			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. <br /><br />
+
+			This light can cast shadows - see the [page:SpotLightShadow] page for details.
+		</div>
+
 
-		<div class="desc">Affects objects using [page:MeshLambertMaterial] or [page:MeshPhongMaterial].</div>
 
 
 		<h2>Example</h2>
 
 		<iframe src='../examples/webgl_lights_spotlight.html'></iframe>
-		<a target="THREE_Examples" href="../examples/#webgl_lights_spotlight">View in Examples</a><br />
+		<div>
+			[example:webgl_lights_spotlight View in Examples ]
+		</div>
+
 		<h2>Other Examples</h2>
 
-		<div>[example:webgl_lights_spotlights lights / spotlights ]</div>
-		<div>[example:webgl_interactive_cubes_gpu interactive / cubes / gpu ]</div>
-		<div>[example:webgl_interactive_draggablecubes interactive / draggablecubes ]</div>
-		<div>[example:webgl_materials_bumpmap_skin materials / bumpmap / skin ]</div>
-		<div>[example:webgl_materials_cubemap_dynamic materials / cubemap / dynamic ]</div>
-		<div>[example:webgl_morphtargets_md2 morphtargets / md2 ]</div>
-		<div>[example:webgl_shading_physical shading / physical ]</div>
+		<div>
+			[example:webgl_interactive_cubes_gpu interactive / cubes / gpu ]<br />
+			[example:webgl_interactive_draggablecubes interactive / draggablecubes ]<br />
+			[example:webgl_materials_bumpmap_skin materials / bumpmap / skin ]<br />
+			[example:webgl_materials_cubemap_dynamic materials / cubemap / dynamic ]<br />
+			[example:webgl_morphtargets_md2 morphtargets / md2 ]<br />
+			[example:webgl_shading_physical shading / physical ]<br />
+			[example:webgl_materials_bumpmap materials / bumpmap]<br/>
+			[example:webgl_shading_physical shading / physical]<br/>
+			[example:webgl_shadowmap shadowmap]<br/>
+			[example:webgl_shadowmap_performance shadowmap / performance]<br/>
+			[example:webgl_shadowmap_viewer shadowmap / viewer]
+		</div>
 
 		<h2>Code Example</h2>
 		<code>
-		// white spotlight shining from the side, casting shadow
+		// white spotlight shining from the side, casting a shadow
 
 		var spotLight = new THREE.SpotLight( 0xffffff );
 		spotLight.position.set( 100, 1000, 100 );
@@ -50,91 +64,126 @@
 		scene.add( spotLight );
 		</code>
 
-		<h2>Extra Examples</h2>
-		<div>
-		[example:webgl_materials_bumpmap materials / bumpmap]<br/>
-		[example:webgl_shading_physical shading / physical]<br/>
-		[example:webgl_shadowmap shadowmap]<br/>
-		[example:webgl_shadowmap_performance shadowmap / performance]<br/>
-		[example:webgl_shadowmap_viewer shadowmap / viewer]
-		</div>
-
-
 		<h2>Constructor</h2>
 
 
 		<h3>[name]( [page:Integer color], [page:Float intensity], [page:Float distance], [page:Radians angle], [page:Float penumbra], [page:Float decay] )</h3>
 		<div>
-		[page:Integer color] — Numeric value of the RGB component of the color. <br />
-		[page:Float intensity] — Numeric value of the light's strength/intensity. <br />
-		[page:Float distance] -- Maximum distance from origin where light will shine whose intensity is attenuated linearly based on distance from origin. <br />
-		[page:Radians angle] -- Maximum angle of light dispersion from its direction whose upper bound is Math.PI/2.<br />
-		[page:Float penumbra] -- Percent of the spotlight cone that is attenuated due to penumbra. Takes values between zero and 1. Default is zero.<br />
-		[page:Float decay] -- The amount the light dims along the distance of the light.
+			[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 />
+			[page:Float distance] - Maximum distance from origin where light will shine whose intensity
+			is attenuated linearly based on distance from origin. <br />
+			[page:Radians angle] - Maximum angle of light dispersion from its direction whose upper
+			bound is Math.PI/2.<br />
+			[page:Float penumbra] - Percent of the spotlight cone that is attenuated due to penumbra.
+			Takes values between zero and 1. Default is zero.<br />
+			[page:Float decay] - The amount the light dims along the distance of the light.<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:Float angle]</h3>
 		<div>
-			Spotlight focus points at target.position.<br />
-			Default position — *(0,0,0)*.<br />
-			*Note*: Currently for target property to work properly, it must be part of the [page:Scene scene], e.g. this will help: <code>scene.add( light.target )</code>
+			Maximum extent of the spotlight, in radians, from its direction. Should be no more than
+			*Math.PI/2*. The default is *Math.PI/3*.
 		</div>
 
-		<h3>[property:Float power]</h3>
+
+		<h3>[property:Boolean castShadow]</h3>
+		<div>
+			If set to *true* light will cast dynamic shadows. *Warning*: This is expensive and
+			requires tweaking to get shadows looking right. See the [page:SpotLightShadow] for details.
+			The default is *false*.
+		</div>
+
+		<h3>[property:Float decay]</h3>
 		<div>
-			Light's power.<br />
-			In "physically correct" mode, the luminous power of the light measured in lumens.<br/>
-			Default - *4PI*.
+			The amount the light dims along the distance of the light.<br />
+			In [page:WebGLRenderer.physicallyCorrectLights physically correct] mode, decay = 2 leads to
+			physically realistic light falloff. The default is *1*.
 		</div>
 
 		<h3>[property:Float distance]</h3>
 		<div>
-			If non-zero, light will attenuate linearly from maximum intensity at light *position* down to zero at *distance*.<br />
-			Default — *0.0*.
+			If non-zero, light will attenuate linearly from maximum intensity at the light's
+			position down to zero at this distance from the light. Default is *0.0*.
 		</div>
 
-		<h3>[property:Float angle]</h3>
+		<h3>[property:Boolean isSpotLight]</h3>
 		<div>
-			Maximum extent of the spotlight, in radians, from its direction. Should be no more than *Math.PI/2*.<br />
-			Default — *Math.PI/3*.
+			Used to check whether this or derived classes are spot lights. Default is *true*.<br /><br />
+
+			You should not change this, as it used internally for optimisation.
 		</div>
 
 		<h3>[property:Float penumbra]</h3>
 		<div>
-			Percent of the spotlight cone that is attenuated due to penumbra. Takes values between zero and 1.<br />
-			Default — *0.0*.
+			Percent of the spotlight cone that is attenuated due to penumbra. Takes values between
+			zero and 1. The default is *0.0*.
 		</div>
 
-		<h3>[property:Float decay]</h3>
+		<h3>[property:Vector3 position]</h3>
 		<div>
-			The amount the light dims along the distance of the light<br />
-			In "physically correct" mode, decay = 2 leads to physically realistic light falloff.<br/>
-			Default — *1*.
+			This is set equal to [page:Object3D.DefaultUp] (0, 1, 0), so that the light shines from the top down.
+		</div>
+
+		<h3>[property:Float power]</h3>
+		<div>
+			The light's power.<br />
+			In [page:WebGLRenderer.physicallyCorrectLights physically correct] mode, the luminous
+			power of the light measured in lumens. Default - *4PI*. <br /><br />
+
+			This is directly related to the [page:.intensity intensity] in the ratio
+			<code>
+				power = intensity * &Pi;
+			</code>
+			and changing this will also change the intensity.
 		</div>
 
 		<h3>[property:SpotLightShadow shadow]</h3>
 		<div>
-			This property stores all relevant information for rendering the shadow of the light.<br />
+			A [page:SpotLightShadow] 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 Spotlight 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 spotlight will now track the target object.
 		</div>
 
+
 		<h2>Methods</h2>
 
 		See the base [page:Light Light] class for common methods.
 
 		<h3>[method:SpotLight copy]( [page:SpotLight source] )</h3>
 		<div>
-		<br />
-		Copies value of *source* to this SpotLight object.
+		Copies value of all the properties from the [page:SpotLight source] to this
+		SpotLight.
 		</div>
 
 		[link:https://github.com/mrdoob/three.js/blob/master/src/[path].js src/[path].js]

docs/api/lights/DirectionalLightShadow.html → docs/api/lights/shadows/DirectionalLightShadow.html

@@ -1,33 +1,33 @@
-<!DOCTYPE html>
-<html lang="en">
-	<head>
-		<meta charset="utf-8" />
-		<base href="../../" />
-		<script src="list.js"></script>
-		<script src="page.js"></script>
-		<link type="text/css" rel="stylesheet" href="page.css" />
-	</head>
-	<body>
-		[page:LightShadow] &rarr;
-
-		<h1>[name]</h1>
-
-		<div class="desc">TODO</div>
-
-		<h2>Constructor</h2>
-
-		The constructor creates an [page:OrthographicCamera OrthographicCamera] to manage the shadow's view of the world.
-
-		<h2>Properties</h2>
-
-		See the base [page:LightShadow LightShadow] class for common properties.
-
-		<h2>Methods</h2>
-
-		See the base [page:LightShadow LightShadow] class for common methods.
-
-		<h2>Source</h2>
-
-		[link:https://github.com/mrdoob/three.js/blob/master/src/[path].js src/[path].js]
-	</body>
-</html>
+<!DOCTYPE html>
+<html lang="en">
+	<head>
+		<meta charset="utf-8" />
+		<base href="../../../" />
+		<script src="list.js"></script>
+		<script src="page.js"></script>
+		<link type="text/css" rel="stylesheet" href="page.css" />
+	</head>
+	<body>
+		[page:LightShadow] &rarr;
+
+		<h1>[name]</h1>
+
+		<div class="desc">TODO</div>
+
+		<h2>Constructor</h2>
+
+		The constructor creates an [page:OrthographicCamera OrthographicCamera] to manage the shadow's view of the world.
+
+		<h2>Properties</h2>
+
+		See the base [page:LightShadow LightShadow] class for common properties.
+
+		<h2>Methods</h2>
+
+		See the base [page:LightShadow LightShadow] class for common methods.
+
+		<h2>Source</h2>
+
+		[link:https://github.com/mrdoob/three.js/blob/master/src/[path].js src/[path].js]
+	</body>
+</html>

docs/api/lights/LightShadow.html → docs/api/lights/shadows/LightShadow.html

@@ -1,75 +1,75 @@
-<!DOCTYPE html>
-<html lang="en">
-	<head>
-		<meta charset="utf-8" />
-		<base href="../../" />
-		<script src="list.js"></script>
-		<script src="page.js"></script>
-		<link type="text/css" rel="stylesheet" href="page.css" />
-	</head>
-	<body>
-
-		<h1>[name]</h1>
-
-		<div class="desc">TODO</div>
-
-		<h2>Constructor</h2>
-
-
-		<h3>[name]( [page:Camera camera] )</h3>
-		<div>
-		[page:Camera camera] — The shadow's view of the world.
-		</div>
-
-		<h2>Properties</h2>
-
-		<h3>[property:Camera camera]</h3>
-		<div>
-			The shadow's view of the world.
-		</div>
-
-		<h3>[property:Float bias]</h3>
-		<div>
-			Shadow map bias, how much to add or subtract from the normalized depth when deciding whether a surface is in shadow.<br />
-			Default — *0*.
-		</div>
-
-		<h3>[property:Float radius]</h3>
-		<div>
-			TODO<br />
-			Default - *0*.
-		</div>
-
-		<h3>[property:Vector2 mapSize]</h3>
-		<div>
-			The width and height of the shadow map stored in a [page:Vector2 Vector2].<br />
-			Default — *( 512, 512 )*.
-		</div>
-
-		<h3>[property:WebGLRenderTarget map]</h3>
-		<div>
-			The depth map generated using the internal camera; a location beyond a pixel's depth is in shadow. Computed internally during rendering.
-		</div>
-
-		<h3>[property:Matrix4 matrix]</h3>
-		<div>
-			Model to shadow camera space, to compute location and depth in shadow map. Stored in a [page:Matrix4 Matrix4]. Computed internally during rendering.
-		</div>
-
-
-		<h2>Methods</h2>
-		<h3>[method:LightShadow copy]( [page:LightShadow source] )</h3>
-		<div>
-		Copies value of *source* to this LightShadow object.
-		</div>
-
-		<h3>[method:LightShadow clone]()</h3>
-		<div>
-		It returns a clone of LightShadow.
-		</div>
-
-		<h2>Source</h2>
-
-		[link:https://github.com/mrdoob/three.js/blob/master/src/[path].js src/[path].js]
-	</body>
-</html>
+<!DOCTYPE html>
+<html lang="en">
+	<head>
+		<meta charset="utf-8" />
+		<base href="../../../" />
+		<script src="list.js"></script>
+		<script src="page.js"></script>
+		<link type="text/css" rel="stylesheet" href="page.css" />
+	</head>
+	<body>
+
+		<h1>[name]</h1>
+
+		<div class="desc">TODO</div>
+
+		<h2>Constructor</h2>
+
+
+		<h3>[name]( [page:Camera camera] )</h3>
+		<div>
+		[page:Camera camera] — The shadow's view of the world.
+		</div>
+
+		<h2>Properties</h2>
+
+		<h3>[property:Camera camera]</h3>
+		<div>
+			The shadow's view of the world.
+		</div>
+
+		<h3>[property:Float bias]</h3>
+		<div>
+			Shadow map bias, how much to add or subtract from the normalized depth when deciding whether a surface is in shadow.<br />
+			Default — *0*.
+		</div>
+
+		<h3>[property:Float radius]</h3>
+		<div>
+			TODO<br />
+			Default - *0*.
+		</div>
+
+		<h3>[property:Vector2 mapSize]</h3>
+		<div>
+			The width and height of the shadow map stored in a [page:Vector2 Vector2].<br />
+			Default — *( 512, 512 )*.
+		</div>
+
+		<h3>[property:WebGLRenderTarget map]</h3>
+		<div>
+			The depth map generated using the internal camera; a location beyond a pixel's depth is in shadow. Computed internally during rendering.
+		</div>
+
+		<h3>[property:Matrix4 matrix]</h3>
+		<div>
+			Model to shadow camera space, to compute location and depth in shadow map. Stored in a [page:Matrix4 Matrix4]. Computed internally during rendering.
+		</div>
+
+
+		<h2>Methods</h2>
+		<h3>[method:LightShadow copy]( [page:LightShadow source] )</h3>
+		<div>
+		Copies value of *source* to this LightShadow object.
+		</div>
+
+		<h3>[method:LightShadow clone]()</h3>
+		<div>
+		It returns a clone of LightShadow.
+		</div>
+
+		<h2>Source</h2>
+
+		[link:https://github.com/mrdoob/three.js/blob/master/src/[path].js src/[path].js]
+	</body>
+</html>

docs/api/lights/SpotLightShadow.html → docs/api/lights/shadows/SpotLightShadow.html

@@ -1,38 +1,38 @@
-<!DOCTYPE html>
-<html lang="en">
-	<head>
-		<meta charset="utf-8" />
-		<base href="../../" />
-		<script src="list.js"></script>
-		<script src="page.js"></script>
-		<link type="text/css" rel="stylesheet" href="page.css" />
-	</head>
-	<body>
-		[page:LightShadow] &rarr;
-
-		<h1>[name]</h1>
-
-		<div class="desc">TODO</div>
-
-		<h2>Constructor</h2>
-
-		The constructor creates a [page:PerspectiveCamera PerspectiveCamera] to manage the shadow's view of the world.
-
-		<h2>Properties</h2>
-
-		See the base [page:LightShadow LightShadow] class for common properties.
-
-		<h2>Methods</h2>
-
-		See the base [page:LightShadow LightShadow] class for common methods.
-
-		<h3>[method:SpotLightShadow update]( [page:SpotLight light] )</h3>
-		<div>
-		Updates the internal perspective camera.
-		</div>
-
-		<h2>Source</h2>
-
-		[link:https://github.com/mrdoob/three.js/blob/master/src/[path].js src/[path].js]
-	</body>
-</html>
+<!DOCTYPE html>
+<html lang="en">
+	<head>
+		<meta charset="utf-8" />
+		<base href="../../../" />
+		<script src="list.js"></script>
+		<script src="page.js"></script>
+		<link type="text/css" rel="stylesheet" href="page.css" />
+	</head>
+	<body>
+		[page:LightShadow] &rarr;
+
+		<h1>[name]</h1>
+
+		<div class="desc">TODO</div>
+
+		<h2>Constructor</h2>
+
+		The constructor creates a [page:PerspectiveCamera PerspectiveCamera] to manage the shadow's view of the world.
+
+		<h2>Properties</h2>
+
+		See the base [page:LightShadow LightShadow] class for common properties.
+
+		<h2>Methods</h2>
+
+		See the base [page:LightShadow LightShadow] class for common methods.
+
+		<h3>[method:SpotLightShadow update]( [page:SpotLight light] )</h3>
+		<div>
+		Updates the internal perspective camera.
+		</div>
+
+		<h2>Source</h2>
+
+		[link:https://github.com/mrdoob/three.js/blob/master/src/[path].js src/[path].js]
+	</body>
+</html>

docs/list.js

@@ -186,9 +186,9 @@ var list = {
 		],
 
 		"Lights / Shadows": [
-			[ "DirectionalLightShadow", "api/lights/DirectionalLightShadow" ],
-			[ "LightShadow", "api/lights/LightShadow" ],
-			[ "SpotLightShadow", "api/lights/SpotLightShadow" ]
+			[ "DirectionalLightShadow", "api/lights/shadows/DirectionalLightShadow" ],
+			[ "LightShadow", "api/lights/shadows/LightShadow" ],
+			[ "SpotLightShadow", "api/lights/shadows/SpotLightShadow" ]
 		],
 
 		"Loaders": [