Make Light targets optional

docs/api/lights/DirectionalLight.html

@@ -21,23 +21,6 @@ <h1>[name]</h1>
 			This light can cast shadows - see the [page:DirectionalLightShadow] page for details.
 		</p>
 
-		<h2>A Note about Position, Target and rotation</h2>
-		<p>
-			A common point of confusion for directional lights is that setting the rotation has no effect.
-			This is because three.js'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 '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.
-		</p>
-
-
 		<h2>Example</h2>
 		<p>
 			[example:canvas_morphtargets_horse morphtargets / horse ]<br />
@@ -99,30 +82,34 @@ <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
+			If [page:.targeted targeted] is *true*, the DirectionalLight points from its world [page:.position position]
+			to the world position of its [page:.target target] object, extracted from [page:Object3D.matrixWorld target.matrixWorld].
+			This 'Target Direct Light' mode may be used to have the light track a moving object :
+			<code>
+// track an existing object, already added to the scene
+light.targeted = true;
+light.target = targetObject;
+
+// or use the default target object
+light.targeted = true;
+scene.add( light.target );
+			</code>
+			*Note*: The target object mush be added to the [page:Scene scene] to get its
+			[page:Object3D.matrixWorld matrixWorld] automatically updated each frame.<br/>
+			*Note*: The light [page:Object3D.rotation rotation] and [page:Object3D.quaternion quaternion] are
+			unused when the [page:.targeted targeted] is true.<br/>
 		</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>
+		<h3>[property:Boolean targeted]</h3>
 		<p>
-			The directionalLight will now track the target object.
+			If set to *true*, the light direction will track the [page:.target target] world position, otherwise the SpotLight is directed along the positive Z axis of its local
+			frame ('Free Direct Light' mode) and thus affected by its world rotation.<br/>
+
+			The default is *false*.<br/>
+
+			*Note*: In both modes, the [page:.position position] is used by the [page:.shadow shadow] camera
+			to cast shadows.
 		</p>
 
 

docs/api/lights/SpotLight.html

@@ -149,32 +149,33 @@ <h3>[property:SpotLightShadow shadow]</h3>
 			A [page:SpotLightShadow] used to calculate shadows for this light.
 		</p>
 
-
 		<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 />
-
-			*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
-			<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:
+			If [page:.targeted targeted] is *true*, the SpotLight points from its world [page:.position position]
+			to the world position of its [page:.target target] object, extracted from [page:Object3D.matrixWorld target.matrixWorld].
+			This may be used to have the light track a moving object :
 			<code>
-var targetObject = new THREE.Object3D();
-scene.add(targetObject);
-
+// track an existing object, already added to the scene
+light.targeted = true;
 light.target = targetObject;
+
+// or use the default target object
+light.targeted = true;
+scene.add( light.target );
 			</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.<br/>
+			*Note*: The light [page:Object3D.rotation rotation] and [page:Object3D.quaternion quaternion] are
+			unused when the [page:.targeted targeted] is true.<br/>
 		</p>
 
+		<h3>[property:Boolean targeted]</h3>
+		<p>
+			If set to *true*, the light direction will track the [page:.target target] world position, otherwise the SpotLight is directed along the positive Z axis of its local
+			frame and thus affected by its world rotation.<br/>
+
+			The default is *false*.
+		</p>
 
 		<h2>Methods</h2>
 

examples/canvas_camera_orthographic.html

@@ -85,13 +85,15 @@
 				directionalLight.position.y = Math.random() - 0.5;
 				directionalLight.position.z = Math.random() - 0.5;
 				directionalLight.position.normalize();
+				directionalLight.lookAt( 0, 0, 0 );
 				scene.add( directionalLight );
 
 				var directionalLight = new THREE.DirectionalLight( Math.random() * 0xffffff );
 				directionalLight.position.x = Math.random() - 0.5;
 				directionalLight.position.y = Math.random() - 0.5;
 				directionalLight.position.z = Math.random() - 0.5;
 				directionalLight.position.normalize();
+				directionalLight.lookAt( 0, 0, 0 );
 				scene.add( directionalLight );
 
 				renderer = new THREE.CanvasRenderer();

examples/canvas_interactive_voxelpainter.html

@@ -86,13 +86,15 @@
 				directionalLight.position.y = Math.random() - 0.5;
 				directionalLight.position.z = Math.random() - 0.5;
 				directionalLight.position.normalize();
+				directionalLight.lookAt( 0, 0, 0 );
 				scene.add( directionalLight );
 
 				var directionalLight = new THREE.DirectionalLight( 0x808080 );
 				directionalLight.position.x = Math.random() - 0.5;
 				directionalLight.position.y = Math.random() - 0.5;
 				directionalLight.position.z = Math.random() - 0.5;
 				directionalLight.position.normalize();
+				directionalLight.lookAt( 0, 0, 0 );
 				scene.add( directionalLight );
 
 				renderer = new THREE.CanvasRenderer();

examples/canvas_materials.html

@@ -117,6 +117,7 @@
 				directionalLight.position.y = Math.random() - 0.5;
 				directionalLight.position.z = Math.random() - 0.5;
 				directionalLight.position.normalize();
+				directionalLight.lookAt( 0, 0, 0 );
 				scene.add( directionalLight );
 
 				pointLight = new THREE.PointLight( 0xffffff, 1 );

examples/canvas_morphtargets_horse.html

@@ -57,10 +57,12 @@
 
 				var light = new THREE.DirectionalLight( 0xefefff, 1.5 );
 				light.position.set( 1, 1, 1 ).normalize();
+				light.lookAt( 0, 0, 0 );
 				scene.add( light );
 
 				var light = new THREE.DirectionalLight( 0xffefef, 1.5 );
 				light.position.set( -1, -1, -1 ).normalize();
+				light.lookAt( 0, 0, 0 );
 				scene.add( light );
 
 				var loader = new THREE.JSONLoader();

examples/canvas_performance.html

@@ -74,6 +74,7 @@
 
 				var directionalLight = new THREE.DirectionalLight( Math.random() * 0xffffff );
 				directionalLight.position.set( 0, 1, 0 );
+				directionalLight.lookAt( 0, 0, 0 );
 				scene.add( directionalLight );
 
 				light = new THREE.PointLight( 0xff0000, 1, 500 );

examples/css2d_label.html

@@ -72,6 +72,7 @@
 
 				var dirLight = new THREE.DirectionalLight( 0xffffff );
 				dirLight.position.set( 0, 0, 1 );
+				dirLight.lookAt( 0, 0, 0 );
 				scene.add( dirLight );
 
 				var axesHelper = new THREE.AxesHelper( 5 );

examples/js/crossfade/scenes.js

@@ -82,6 +82,7 @@ function Scene( type, numObjects, cameraZ, fov, rotationSpeed, clearColor ) {
 
 	var light = new THREE.SpotLight( 0xffffff, 1.5 );
 	light.position.set( 0, 500, 2000 );
+	light.lookAt( 0, 0, 0 );
 	this.scene.add( light );
 
 	this.rotationSpeed = rotationSpeed;

examples/js/loaders/BabylonLoader.js

@@ -168,10 +168,12 @@ THREE.BabylonLoader.prototype = {
 
 					case 1:
 						light = new THREE.DirectionalLight();
+						light.targeted = true;
 						break;
 
 					case 2:
 						light = new THREE.SpotLight();
+						light.targeted = true;
 						break;
 
 					case 3:

examples/js/loaders/ColladaLoader.js

@@ -1936,6 +1936,7 @@ THREE.ColladaLoader.prototype = {
 
 				case 'directional':
 					light = new THREE.DirectionalLight();
+					light.targeted = true;
 					break;
 
 				case 'point':
@@ -1944,6 +1945,7 @@ THREE.ColladaLoader.prototype = {
 
 				case 'spot':
 					light = new THREE.SpotLight();
+					light.targeted = true;
 					break;
 
 				case 'ambient':

examples/js/loaders/GLTFLoader.js

@@ -291,6 +291,7 @@ THREE.GLTFLoader = ( function () {
 
 				case 'directional':
 					lightNode = new THREE.DirectionalLight( color );
+					lightNode.targeted = true;
 					lightNode.target.position.set( 0, 0, 1 );
 					lightNode.add( lightNode.target );
 					break;
@@ -309,6 +310,7 @@ THREE.GLTFLoader = ( function () {
 					lightDef.spot.outerConeAngle = lightDef.spot.outerConeAngle !== undefined ? lightDef.spot.outerConeAngle : Math.PI / 4.0;
 					lightNode.angle = lightDef.spot.outerConeAngle;
 					lightNode.penumbra = 1.0 - lightDef.spot.innerConeAngle / lightDef.spot.outerConeAngle;
+					lightNode.targeted = true;
 					lightNode.target.position.set( 0, 0, 1 );
 					lightNode.add( lightNode.target );
 					break;

examples/js/loaders/deprecated/LegacyGLTFLoader.js

@@ -313,6 +313,7 @@ THREE.LegacyGLTFLoader = ( function () {
 				case "directional":
 					lightNode = new THREE.DirectionalLight( color );
 					lightNode.position.set( 0, 0, 1 );
+					lightNode.lookAt( 0, 0, 0 );
 					break;
 
 				case "point":
@@ -322,6 +323,7 @@ THREE.LegacyGLTFLoader = ( function () {
 				case "spot":
 					lightNode = new THREE.SpotLight( color );
 					lightNode.position.set( 0, 0, 1 );
+					lightNode.lookAt( 0, 0, 0 );
 					break;
 
 				case "ambient":

examples/js/renderers/WebGLDeferredRenderer.js

@@ -890,14 +890,12 @@ THREE.WebGLDeferredRenderer = function ( parameters ) {
 		uniforms.lightAngle.value = originalLight.angle;
 		uniforms.lightColor.value.copy( originalLight.color );
 		uniforms.lightIntensity.value = originalLight.intensity;
-		uniforms.lightPositionVS.value.setFromMatrixPosition( originalLight.matrixWorld ).applyMatrix4( _currentCamera.matrixWorldInverse );
+		uniforms.lightPositionVS.value.setFromMatrixPosition( originalLight.matrixWorld )
+		uniforms.lightPositionVS.value.applyMatrix4( _currentCamera.matrixWorldInverse );
 
-		var vec = uniforms.lightDirectionVS.value;
-		var vec2 = _tmpVector3;
-
-		vec.setFromMatrixPosition( originalLight.matrixWorld );
-		vec2.setFromMatrixPosition( originalLight.target.matrixWorld );
-		vec.sub( vec2 ).normalize().transformDirection( _currentCamera.matrixWorldInverse );
+		uniforms.lightDirectionVS.value.set( 0, 0, - 1 );
+		uniforms.lightDirectionVS.value.transformDirection( originalLight.shadow.camera.matrixWorld );
+		uniforms.lightDirectionVS.value.transformDirection(  _currentCamera.matrixWorldInverse );
 
 		updateDeferredLightCommonUniforms( uniforms );
 
@@ -933,12 +931,9 @@ THREE.WebGLDeferredRenderer = function ( parameters ) {
 		uniforms.lightColor.value.copy( originalLight.color );
 		uniforms.lightIntensity.value = originalLight.intensity;
 
-		var vec = uniforms.lightDirectionVS.value;
-		var vec2 = _tmpVector3;
-
-		vec.setFromMatrixPosition( originalLight.matrixWorld );
-		vec2.setFromMatrixPosition( originalLight.target.matrixWorld );
-		vec.sub( vec2 ).normalize().transformDirection( _currentCamera.matrixWorldInverse );
+		uniforms.lightDirectionVS.value.set( 0, 0, - 1 );
+		uniforms.lightDirectionVS.value.transformDirection( originalLight.shadow.camera.matrixWorld );
+		uniforms.lightDirectionVS.value.transformDirection(  _currentCamera.matrixWorldInverse );
 
 		updateDeferredLightCommonUniforms( uniforms );
 

examples/misc_animation_authoring.html

@@ -60,6 +60,7 @@
 
 				var light = new THREE.DirectionalLight( 0xffffff, 2 );
 				light.position.set( 1, 1, 1 );
+				light.lookAt( 0, 0, 0 );
 				scene.add( light );
 
 

examples/misc_controls_fly.html

@@ -97,6 +97,7 @@
 
 				dirLight = new THREE.DirectionalLight( 0xffffff );
 				dirLight.position.set( -1, 0, 1 ).normalize();
+				dirLight.lookAt( 0, 0, 0 );
 				scene.add( dirLight );
 
 				var materialNormalMap = new THREE.MeshPhongMaterial( {

examples/misc_controls_map.html

@@ -107,10 +107,12 @@
 
 				var light = new THREE.DirectionalLight( 0xffffff );
 				light.position.set( 1, 1, 1 );
+				light.lookAt( 0, 0, 0 );
 				scene.add( light );
 
 				var light = new THREE.DirectionalLight( 0x002288 );
 				light.position.set( - 1, - 1, - 1 );
+				light.lookAt( 0, 0, 0 );
 				scene.add( light );
 
 				var light = new THREE.AmbientLight( 0x222222 );

examples/misc_controls_orbit.html

@@ -101,10 +101,12 @@
 
 				var light = new THREE.DirectionalLight( 0xffffff );
 				light.position.set( 1, 1, 1 );
+				light.lookAt( 0, 0, 0 );
 				scene.add( light );
 
 				var light = new THREE.DirectionalLight( 0x002288 );
 				light.position.set( - 1, - 1, - 1 );
+				light.lookAt( 0, 0, 0 );
 				scene.add( light );
 
 				var light = new THREE.AmbientLight( 0x222222 );

examples/misc_controls_trackball.html

@@ -100,10 +100,12 @@
 
 				var light = new THREE.DirectionalLight( 0xffffff );
 				light.position.set( 1, 1, 1 );
+				light.lookAt( 0, 0, 0 );
 				scene.add( light );
 
 				var light = new THREE.DirectionalLight( 0x002288 );
 				light.position.set( -1, -1, -1 );
+				light.lookAt( 0, 0, 0 );
 				scene.add( light );
 
 				var light = new THREE.AmbientLight( 0x222222 );

examples/misc_controls_transform.html

@@ -58,6 +58,7 @@
 
 				var light = new THREE.DirectionalLight( 0xffffff, 2 );
 				light.position.set( 1, 1, 1 );
+				light.lookAt( 0, 0, 0 );
 				scene.add( light );
 
 				var texture = new THREE.TextureLoader().load( 'textures/crate.gif', render );

examples/misc_exporter_gltf.html

@@ -179,6 +179,7 @@
 				// ---------------------------------------------------------------------
 				light = new THREE.DirectionalLight( 0xffffff, 1 );
 				light.position.set( 1, 1, 0 );
+				light.lookAt( 0, 0, 0 );
 				light.name = 'DirectionalLight';
 				scene1.add( light );
 

examples/misc_exporter_stl.html

@@ -66,6 +66,7 @@
 
 				var directionalLight = new THREE.DirectionalLight( 0xffffff );
 				directionalLight.position.set( 0, 200, 100 );
+				directionalLight.lookAt( 0, 0, 0 );
 				directionalLight.castShadow = true;
 				directionalLight.shadow.camera.top = 180;
 				directionalLight.shadow.camera.bottom = - 100;

examples/misc_lights_test.html

@@ -98,6 +98,7 @@
 
 				directionalLight = new THREE.DirectionalLight( 0xffffff );
 				directionalLight.position.set( 0, -70, 100 ).normalize();
+				directionalLight.lookAt( 0, 0, 0 );
 
 				setTimeout( function () {