Merge pull request #12783 from WestLangley/dev-optTgt_1

Remove optionalTarget - part 1

docs/api/cameras/Camera.html

@@ -69,16 +69,13 @@ <h3>[method:Camera copy]( [param:Camera source] )</h3>
 		Copy the properties from the source camera into this one.
 		</div>
 
-		<h3>[method:Vector3 getWorldDirection]( [param:Vector3 optionalTarget] )</h3>
+		<h3>[method:Vector3 getWorldDirection]( [page:Vector3 target] )</h3>
 		<div>
-		Returns a [page:Vector3] representing the world space direction in which the camera is looking.<br /><br />
 
-		Note: This is not the camera’s positive, but its negative z-axis, in contrast to
-		[page:Object3D.getWorldDirection getWorldDirection] of the base class (Object3D).<br /><br />
+		[page:Vector3 target] — the result will be copied into this Vector3. <br /><br />
 
-		If an [page:Vector3 optionalTarget] vector is specified, the result will be copied into this vector
-		(which can be reused in this way), otherwise a new vector will be created.
-		</div>
+		Returns a [page:Vector3] representing the world space direction in which the camera is looking.
+		(Note: A camera looks down its local, negative z-axis).<br /><br />
 
 		<h2>Source</h2>
 

docs/api/core/Object3D.html

@@ -240,41 +240,37 @@ <h3>[method:Object3D getObjectByProperty]( [param:String name], [param:Float val
 		Searches through the object's children and returns the first with a property that matches the value given.
 		</div>
 
-		<h3>[method:Vector3 getWorldPosition]( [param:Vector3 optionalTarget] )</h3>
+		<h3>[method:Vector3 getWorldPosition]( [page:Vector3 target] )</h3>
 		<div>
-		optionalTarget — (optional) target to set the result. Otherwise, a new [page:Vector3] is instantiated. <br /><br />
+		[page:Vector3 target] — the result will be copied into this Vector3. <br /><br />
 
 		Returns a vector representing the position of the object in world space.
 		</div>
 
-		<h3>[method:Quaternion getWorldQuaternion]( [param:Quaternion optionalTarget] )</h3>
+		<h3>[method:Quaternion getWorldQuaternion]( [page:Quaternion target] )</h3>
 		<div>
-		optionalTarget — (optional) if specified, the result will be copied into this Quaternion,
-		otherwise a new Quaternion will be created. <br /><br />
+		[page:Quaternion target] — the result will be copied into this Quaternion. <br /><br />
 
 		Returns a quaternion representing the rotation of the object in world space.
 		</div>
 
-		<h3>[method:Euler getWorldRotation]( [param:Euler optionalTarget] )</h3>
+		<h3>[method:Euler getWorldRotation]( [page:Euler target] )</h3>
 		<div>
-		optionalTarget — (optional) if specified, the result will be copied into this Euler,
-		otherwise a new Euler will be created. <br /><br />
+		[page:Euler target] — the result will be copied into this Euler. <br /><br />
 
 		Returns the euler angles representing the rotation of the object in world space.
 		</div>
 
-		<h3>[method:Vector3 getWorldScale]( [param:Vector3 optionalTarget] )</h3>
+		<h3>[method:Vector3 getWorldScale]( [page:Vector3 target] )</h3>
 		<div>
-		[page:Vector3 optionalTarget] — (optional) if specified, the result will be copied into this Vector3,
-		otherwise a new Vector3 will be created. <br /><br />
+		[page:Vector3 target] — the result will be copied into this Vector3. <br /><br />
 
 		Returns a vector of the scaling factors applied to the object for each axis in world space.
 		</div>
 
-		<h3>[method:Vector3 getWorldDirection]( [param:Vector3 optionalTarget] )</h3>
+		<h3>[method:Vector3 getWorldDirection]( [page:Vector3 target] )</h3>
 		<div>
-		[page:Vector3 optionalTarget] — (optional) if specified, the result will be copied into this Vector3,
-		otherwise a new Vector3 will be created. <br /><br />
+		[page:Vector3 target] — the result will be copied into this Vector3. <br /><br />
 
 		Returns a vector representing the direction of object's positive z-axis in world space.
 		</div>

src/cameras/Camera.js

@@ -41,13 +41,18 @@ Camera.prototype = Object.assign( Object.create( Object3D.prototype ), {
 
 		var quaternion = new Quaternion();
 
-		return function getWorldDirection( optionalTarget ) {
+		return function getWorldDirection( target ) {
 
-			var result = optionalTarget || new Vector3();
+			if ( target === undefined ) {
+
+				console.warn( 'THREE.Camera: .getWorldDirection() target is now required' );
+				target = new Vector3();
+
+			}
 
 			this.getWorldQuaternion( quaternion );
 
-			return result.set( 0, 0, - 1 ).applyQuaternion( quaternion );
+			return target.set( 0, 0, - 1 ).applyQuaternion( quaternion );
 
 		};
 

src/core/Object3D.js

@@ -443,13 +443,18 @@ Object3D.prototype = Object.assign( Object.create( EventDispatcher.prototype ),
 
 	},
 
-	getWorldPosition: function ( optionalTarget ) {
+	getWorldPosition: function ( target ) {
 
-		var result = optionalTarget || new Vector3();
+		if ( target === undefined ) {
+
+			console.warn( 'THREE.Object3D: .getWorldPosition() target is now required' );
+			target = new Vector3();
+
+		}
 
 		this.updateMatrixWorld( true );
 
-		return result.setFromMatrixPosition( this.matrixWorld );
+		return target.setFromMatrixPosition( this.matrixWorld );
 
 	},
 
@@ -458,15 +463,20 @@ Object3D.prototype = Object.assign( Object.create( EventDispatcher.prototype ),
 		var position = new Vector3();
 		var scale = new Vector3();
 
-		return function getWorldQuaternion( optionalTarget ) {
+		return function getWorldQuaternion( target ) {
+
+			if ( target === undefined ) {
 
-			var result = optionalTarget || new Quaternion();
+				console.warn( 'THREE.Object3D: .getWorldQuaternion() target is now required' );
+				target = new Quaternion();
+
+			}
 
 			this.updateMatrixWorld( true );
 
-			this.matrixWorld.decompose( position, result, scale );
+			this.matrixWorld.decompose( position, target, scale );
 
-			return result;
+			return target;
 
 		};
 
@@ -476,13 +486,18 @@ Object3D.prototype = Object.assign( Object.create( EventDispatcher.prototype ),
 
 		var quaternion = new Quaternion();
 
-		return function getWorldRotation( optionalTarget ) {
+		return function getWorldRotation( target ) {
 
-			var result = optionalTarget || new Euler();
+			if ( target === undefined ) {
+
+				console.warn( 'THREE.Object3D: .getWorldRotation() target is now required' );
+				target = new Euler();
+
+			}
 
 			this.getWorldQuaternion( quaternion );
 
-			return result.setFromQuaternion( quaternion, this.rotation.order, false );
+			return target.setFromQuaternion( quaternion, this.rotation.order, false );
 
 		};
 
@@ -493,15 +508,20 @@ Object3D.prototype = Object.assign( Object.create( EventDispatcher.prototype ),
 		var position = new Vector3();
 		var quaternion = new Quaternion();
 
-		return function getWorldScale( optionalTarget ) {
+		return function getWorldScale( target ) {
+
+			if ( target === undefined ) {
 
-			var result = optionalTarget || new Vector3();
+				console.warn( 'THREE.Object3D: .getWorldScale() target is now required' );
+				target = new Vector3();
+
+			}
 
 			this.updateMatrixWorld( true );
 
-			this.matrixWorld.decompose( position, quaternion, result );
+			this.matrixWorld.decompose( position, quaternion, target );
 
-			return result;
+			return target;
 
 		};
 
@@ -511,13 +531,18 @@ Object3D.prototype = Object.assign( Object.create( EventDispatcher.prototype ),
 
 		var quaternion = new Quaternion();
 
-		return function getWorldDirection( optionalTarget ) {
+		return function getWorldDirection( target ) {
 
-			var result = optionalTarget || new Vector3();
+			if ( target === undefined ) {
+
+				console.warn( 'THREE.Object3D: .getWorldDirection() target is now required' );
+				target = new Vector3();
+
+			}
 
 			this.getWorldQuaternion( quaternion );
 
-			return result.set( 0, 0, 1 ).applyQuaternion( quaternion );
+			return target.set( 0, 0, 1 ).applyQuaternion( quaternion );
 
 		};