opt-in light.target (docs)

Author: mbredif

docs/api/lights/DirectionalLight.html

@@ -60,10 +60,11 @@ <h2>Example</h2>
 
 		<h2>Constructor</h2>
 
-		<h3>[name]( [param:Integer color], [param:Float intensity] )</h3>
+		<h3>[name]( [param:Integer color], [param:Float intensity], [param:OrthographicCamera camera] )</h3>
 		<p>
 			[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 intensity] - (optional) numeric value of the light's strength/intensity. Default is 1.<br />
+			[page:OrthographicCamera camera] - (optional) the light's view of the world.<br /><br />
 
 			Creates a new [name].
 		</p>
@@ -99,30 +100,26 @@ <h3>[property:DirectionalLightShadow shadow]</h3>
 
 		<h3>[property:Object3D target]</h3>
 		<p>
-			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 target's position to be changed to anything other than the default,
-			it must be added to the [page:Scene scene] using
-		</p>
-		<code>
-		scene.add( light.target );
-		</code>
-		<p>
-			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:
-		</p>
-		<code>
-		var targetObject = new THREE.Object3D();
-		scene.add(targetObject);
-
-		light.target = targetObject;
-		</code>
-		<p>
-			The directionalLight will now track the target object.
+			The DirectionalLight points from its [page:.position position] to target.position.
+			If target is undefined, it points to to the origin *(0, 0, 0)* of its parent frame.<br />
+
+			The position pointed to by the DirectionalLight may be changed using lookAt
+			<code>
+light.lookAt( x, y, z ); // or
+light.lookAt( lookAtPosition );
+			</code>
+			*Note*: the LookAt position must be expressed in the parent frame of the light, which is typically
+			the world frame if the light has been added to the scene with no rotation/translation.
+
+			Alternatively, it may be set to track a target object.
+			<code>
+var targetObject = new THREE.Object3D();
+scene.add(targetObject);
+
+light.target = targetObject;
+			</code>
+			*Note*: The target object mush be added to the [page:Scene scene] to get its
+			[page:Object3D.matrixWorld matrixWorld] automatically updated each frame.
 		</p>
 
 

docs/api/lights/SpotLight.html

@@ -67,7 +67,7 @@ <h2>Code Example</h2>
 		<h2>Constructor</h2>
 
 
-		<h3>[name]( [param:Integer color], [param:Float intensity], [param:Float distance], [param:Radians angle], [param:Float penumbra], [param:Float decay] )</h3>
+		<h3>[name]( [param:Integer color], [param:Float intensity], [param:Float distance], [param:Radians angle], [param:Float penumbra], [param:Float decay], [param:PerspectiveCamera camera] )</h3>
 		<p>
 			[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 />
@@ -78,6 +78,7 @@ <h3>[name]( [param:Integer color], [param:Float intensity], [param:Float distanc
 			[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 />
+			[page:PerspectiveCamera camera] - (optional) the light's view of the world.<br /><br />
 
 			Creates a new [name].
 		</p>
@@ -152,30 +153,28 @@ <h3>[property:SpotLightShadow shadow]</h3>
 
 		<h3>[property:Object3D target]</h3>
 		<p>
-			The Spotlight points from its [page:.position position] to target.position. The default
-			position of the target is *(0, 0, 0)*.<br />
+			The Spotlight points from its [page:.position position] to target.position.
+			If target is undefined, it points to to the origin *(0, 0, 0)* of its parent frame.<br />
 
-			*Note*: For the target's position to be changed to anything other than the default,
-			it must be added to the [page:Scene scene] using
+			The position pointed to by the Spotlight may be changed using lookAt
 			<code>
-				scene.add( light.target );
+light.lookAt( x, y, z ); // or
+light.lookAt( vector3 );
 			</code>
+			*Note*: the LookAt position must be expressed in the parent frame of the light, which is typically
+			the world frame if the light has been added to the scene with no rotation/translation.
 
-			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:
+			Alternatively, it may be set to track a target object.
 			<code>
 var targetObject = new THREE.Object3D();
 scene.add(targetObject);
 
 light.target = targetObject;
 			</code>
-			The spotlight will now track the target object.
+			*Note*: The target object mush be added to the [page:Scene scene] to get its
+			[page:Object3D.matrixWorld matrixWorld] automatically updated each frame.
 		</p>
 
-
 		<h2>Methods</h2>
 
 		See the base [page:Light Light] class for common methods.

docs/api/lights/shadows/DirectionalLightShadow.html

@@ -61,6 +61,16 @@ <h2>Example</h2>
 			</code>
 		</p>
 
+		<h3>[name]( [param:OrthographicCamera camera] )</h3>
+		<p>
+		[page:OrthographicCamera camera] - (optional) the light's view of the world.<br /><br />
+
+		Create a new [name]. If not provided, the constructor creates an [page:OrthographicCamera]
+		to manage the shadow's view of the world. This is not intended to be called directly - it is called
+		internally by [page:DirectionalLight].
+		</p>
+
+
 		<h2>Constructor</h2>
 		<h3>[name]( )</h3>
 		<p>
@@ -73,7 +83,7 @@ <h2>Properties</h2>
 			See the base [page:LightShadow LightShadow] class for common properties.
 		</p>
 
-		<h3>[property:Camera camera]</h3>
+		<h3>[property:OrthographicCamera camera]</h3>
 		<p>
 			The light's view of the world. This is used to generate a depth map of the scene; objects behind
 			other objects from the light's perspective will be in shadow.<br /><br />

docs/api/lights/shadows/SpotLightShadow.html

@@ -59,13 +59,20 @@ <h2>Example</h2>
 
 		<h2>Constructor</h2>
 
-		The constructor creates a [param:PerspectiveCamera PerspectiveCamera] to manage the shadow's view of the world.
+		<h3>[name]( [param:PerspectiveCamera camera] )</h3>
+		<p>
+		[page:PerspectiveCamera camera] - (optional) the light's view of the world.<br /><br />
+
+		Create a new [name]. If not provided, the constructor creates a [page:PerspectiveCamera]
+		to manage the shadow's view of the world.
+		</p>
+
 
 		<h2>Properties</h2>
 		See the base [page:LightShadow LightShadow] class for common properties.
 
 
-	 <h3>[property:Camera camera]</h3>
+	 <h3>[property:PerspectiveCamera camera]</h3>
 	 <p>
 		 The light's view of the world. This is used to generate a depth map of the scene; objects behind
 		 other objects from the light's perspective will be in shadow.<br /><br />
@@ -79,13 +86,6 @@ <h3>[property:Camera camera]</h3>
 
 	 </p>
 
-	 <h3>[property:Boolean isSpotLightShadow]</h3>
-	 <p>
-		 Used to check whether this or derived classes are spot light shadows. Default is *true*.<br /><br />
-
-		 You should not change this, as it used internally for optimisation.
-	 </p>
-
 		<h2>Methods</h2>
 		See the base [page:LightShadow LightShadow] class for common methods.