Merge pull request #13518 from WestLangley/dev-optTgt_4

Remove optionalTarget - part 4

docs/api/math/Plane.html

@@ -49,10 +49,9 @@
 		<h3>[method:Plane clone]()</h3>
 		<div>Returns a new plane with the same [page:.normal normal] and [page:.constant constant] as this one.</div>
 
-		<h3>[method:Vector3 coplanarPoint]( [param:Vector3 optionalTarget] )</h3>
+		<h3>[method:Vector3 coplanarPoint]( [param:Vector3 target] )</h3>
 		<div>
-			[page:Vector3 optionalTarget] - (optional) if specified, the result will be copied into this [page:Vector3],
-			otherwise a new [page:Vector3] will be created.<br /><br />
+		[page:Vector3 target] — the result will be copied into this Vector3.<br /><br />
 
 		Returns a [page:Vector3] coplanar to the plane, by calculating the projection of the
 		normal vector at the origin onto the plane.
@@ -76,11 +75,10 @@
 			[page:.constant constant] properties match).
 		</div>
 
-		<h3>[method:Vector3 intersectLine]( [param:Line3 line], [param:Vector3 optionalTarget] ) or [param:undefined]</h3>
+		<h3>[method:Vector3 intersectLine]( [param:Line3 line], [param:Vector3 target] )</h3>
 		<div>
 		[page:Line3 line] - the [page:Line3] to check for intersection.<br />
-		[page:Vector3 optionalTarget] - (optional) if specified, the result will be copied into this [page:Vector3],
-		otherwise a new [page:Vector3] will be created.<br /><br />
+		[page:Vector3 target] — the result will be copied into this Vector3.<br /><br />
 
 		Returns the intersection point of the passed line and the plane. Returns undefined
 		 if the line does not intersect. Returns the line's starting point if the line is
@@ -119,11 +117,10 @@
 			value accordingly.
 		</div>
 
-		<h3>[method:Vector3 projectPoint]( [param:Vector3 point], [param:Vector3 optionalTarget] )</h3>
+		<h3>[method:Vector3 projectPoint]( [param:Vector3 point], [param:Vector3 target] )</h3>
 		<div>
 		[page:Vector3 point] - the [page:Vector3] to project onto the plane.<br />
-		[page:Vector3 optionalTarget] - (optional) if specified, the result will be copied into this [page:Vector3],
-		otherwise a new [page:Vector3] will be created.<br /><br />
+		[page:Vector3 target] — the result will be copied into this Vector3.<br /><br />
 
 		Projects a [page:Vector3 point] onto the plane.
 		</div>

docs/api/math/Ray.html

@@ -53,11 +53,10 @@
 		Transform this [page:Ray] by the [page:Matrix4].
 		</div>
 
-		<h3>[method:Vector3 at]( [param:Float t], [param:Vector3 optionalTarget] ) </h3>
+		<h3>[method:Vector3 at]( [param:Float t], [param:Vector3 target] ) </h3>
 		<div>
 		[page:Float t] - the distance along the [page:Ray] to retrieve a position for.<br />
-		[page:Vector3 optionalTarget] - (optional) if specified, the result will be copied into this [page:Vector3],
-		otherwise a new [page:Vector3] will be created.<br /><br />
+		[page:Vector3 target] — the result will be copied into this Vector3.<br /><br />
 
 		Get a [page:Vector3] that is a given distance along this [page:Ray].
 		</div>
@@ -67,11 +66,10 @@
 			Creates a new Ray with identical [page:.origin origin] and [page:.direction direction]  to this one.
 		</div>
 
-		<h3>[method:Vector3 closestPointToPoint]( [param:Vector3 point], [param:Vector3 optionalTarget] )</h3>
+		<h3>[method:Vector3 closestPointToPoint]( [param:Vector3 point], [param:Vector3 target] )</h3>
 		<div>
 		[page:Vector3 point] - the point to get the closest approach to. <br />
-		[page:Vector3 optionalTarget] - (optional) if specified, the result will be copied into this [page:Vector3],
-		otherwise a new [page:Vector3] will be created.<br /><br />
+		[page:Vector3 target] — the result will be copied into this Vector3.<br /><br />
 
 		Get the point along this [page:Ray] that is closest to the [page:Vector3] provided.
 		</div>
@@ -124,42 +122,38 @@
 		 and [page:.direction direction].
 		</div>
 
-		<h3>[method:Vector3 intersectBox]( [param:Box3 box], [param:Vector3 optionalTarget] )</h3>
+		<h3>[method:Vector3 intersectBox]( [param:Box3 box], [param:Vector3 target] )</h3>
 		<div>
 		[page:Box3 box] - the [page:Box3] to intersect with.<br />
-		[page:Vector3 optionalTarget] - (optional) if specified, the result will be copied into this [page:Vector3],
-		otherwise a new [page:Vector3] will be created.<br /><br />
+		[page:Vector3 target] — the result will be copied into this Vector3.<br /><br />
 
 		Intersect this [page:Ray] with a [page:Box3], returning the intersection point or
 		*null* if there is no intersection.
 		</div>
 
-		<h3>[method:Vector3 intersectPlane]( [param:Plane plane], [param:Vector3 optionalTarget] )</h3>
+		<h3>[method:Vector3 intersectPlane]( [param:Plane plane], [param:Vector3 target] )</h3>
 		<div>
 		[page:Plane plane] - the [page:Plane] to intersect with.<br />
-		[page:Vector3 optionalTarget] - (optional) if specified, the result will be copied into this [page:Vector3],
-		otherwise a new [page:Vector3] will be created.<br /><br />
+		[page:Vector3 target] — the result will be copied into this Vector3.<br /><br />
 
 		Intersect this [page:Ray] with a [page:Plane], returning the intersection point or
 		*null* if there is no intersection.
 		</div>
 
-		<h3>[method:Vector3 intersectSphere]( [param:Sphere sphere], [param:Vector3 optionalTarget] )</h3>
+		<h3>[method:Vector3 intersectSphere]( [param:Sphere sphere], [param:Vector3 target] )</h3>
 		<div>
 		[page:Sphere sphere] - the [page:Sphere] to intersect with.<br />
-		[page:Vector3 optionalTarget] - (optional) if specified, the result will be copied into this [page:Vector3],
-		otherwise a new [page:Vector3] will be created.<br /><br />
+		[page:Vector3 target] — the result will be copied into this Vector3.<br /><br />
 
 		Intersect this [page:Ray] with a [page:Sphere], returning the intersection point or
 		*null* if there is no intersection.
 		</div>
 
-		<h3>[method:Vector3 intersectTriangle]( [param:Vector3 a], [param:Vector3 b], [param:Vector3 c], [param:Boolean backfaceCulling], [param:Vector3 optionalTarget] )</h3>
+		<h3>[method:Vector3 intersectTriangle]( [param:Vector3 a], [param:Vector3 b], [param:Vector3 c], [param:Boolean backfaceCulling], [param:Vector3 target] )</h3>
 		<div>
 		[page:Vector3 a], [page:Vector3 b], [page:Vector3 c] - The [page:Vector3] points making up the triangle.<br />
 		[page:Boolean backfaceCulling] - whether to use backface culling.<br />
-		[page:Vector3 optionalTarget] - (optional) if specified, the result will be copied into this [page:Vector3],
-		otherwise a new [page:Vector3] will be created.<br /><br />
+		[page:Vector3 target] — the result will be copied into this Vector3.<br /><br />
 
 		Intersect this [page:Ray] with a triangle, returning the intersection point or *null*
 		if there is no intersection.

src/math/Plane.js

@@ -110,11 +110,16 @@ Object.assign( Plane.prototype, {
 
 	},
 
-	projectPoint: function ( point, optionalTarget ) {
+	projectPoint: function ( point, target ) {
 
-		var result = optionalTarget || new Vector3();
+		if ( target === undefined ) {
 
-		return result.copy( this.normal ).multiplyScalar( - this.distanceToPoint( point ) ).add( point );
+			console.warn( 'THREE.Plane: .projectPoint() target is now required' );
+			target = new Vector3();
+
+		}
+
+		return target.copy( this.normal ).multiplyScalar( - this.distanceToPoint( point ) ).add( point );
 
 	},
 
@@ -122,9 +127,14 @@ Object.assign( Plane.prototype, {
 
 		var v1 = new Vector3();
 
-		return function intersectLine( line, optionalTarget ) {
+		return function intersectLine( line, target ) {
 
-			var result = optionalTarget || new Vector3();
+			if ( target === undefined ) {
+
+				console.warn( 'THREE.Plane: .intersectLine() target is now required' );
+				target = new Vector3();
+
+			}
 
 			var direction = line.delta( v1 );
 
@@ -135,7 +145,7 @@ Object.assign( Plane.prototype, {
 				// line is coplanar, return origin
 				if ( this.distanceToPoint( line.start ) === 0 ) {
 
-					return result.copy( line.start );
+					return target.copy( line.start );
 
 				}
 
@@ -152,7 +162,7 @@ Object.assign( Plane.prototype, {
 
 			}
 
-			return result.copy( direction ).multiplyScalar( t ).add( line.start );
+			return target.copy( direction ).multiplyScalar( t ).add( line.start );
 
 		};
 
@@ -181,11 +191,16 @@ Object.assign( Plane.prototype, {
 
 	},
 
-	coplanarPoint: function ( optionalTarget ) {
+	coplanarPoint: function ( target ) {
+
+		if ( target === undefined ) {
+
+			console.warn( 'THREE.Plane: .coplanarPoint() target is now required' );
+			target = new Vector3();
 
-		var result = optionalTarget || new Vector3();
+		}
 
-		return result.copy( this.normal ).multiplyScalar( - this.constant );
+		return target.copy( this.normal ).multiplyScalar( - this.constant );
 
 	},
 

src/math/Ray.js

@@ -37,11 +37,16 @@ Object.assign( Ray.prototype, {
 
 	},
 
-	at: function ( t, optionalTarget ) {
+	at: function ( t, target ) {
 
-		var result = optionalTarget || new Vector3();
+		if ( target === undefined ) {
 
-		return result.copy( this.direction ).multiplyScalar( t ).add( this.origin );
+			console.warn( 'THREE.Ray: .at() target is now required' );
+			target = new Vector3();
+
+		}
+
+		return target.copy( this.direction ).multiplyScalar( t ).add( this.origin );
 
 	},
 
@@ -67,19 +72,26 @@ Object.assign( Ray.prototype, {
 
 	}(),
 
-	closestPointToPoint: function ( point, optionalTarget ) {
+	closestPointToPoint: function ( point, target ) {
+
+		if ( target === undefined ) {
+
+			console.warn( 'THREE.Ray: .closestPointToPoint() target is now required' );
+			target = new Vector3();
+
+		}
+
+		target.subVectors( point, this.origin );
 
-		var result = optionalTarget || new Vector3();
-		result.subVectors( point, this.origin );
-		var directionDistance = result.dot( this.direction );
+		var directionDistance = target.dot( this.direction );
 
 		if ( directionDistance < 0 ) {
 
-			return result.copy( this.origin );
+			return target.copy( this.origin );
 
 		}
 
-		return result.copy( this.direction ).multiplyScalar( directionDistance ).add( this.origin );
+		return target.copy( this.direction ).multiplyScalar( directionDistance ).add( this.origin );
 
 	},
 
@@ -244,7 +256,7 @@ Object.assign( Ray.prototype, {
 
 		var v1 = new Vector3();
 
-		return function intersectSphere( sphere, optionalTarget ) {
+		return function intersectSphere( sphere, target ) {
 
 			v1.subVectors( sphere.center, this.origin );
 			var tca = v1.dot( this.direction );
@@ -267,10 +279,10 @@ Object.assign( Ray.prototype, {
 			// test to see if t0 is behind the ray:
 			// if it is, the ray is inside the sphere, so return the second exit point scaled by t1,
 			// in order to always return an intersect point that is in front of the ray.
-			if ( t0 < 0 ) return this.at( t1, optionalTarget );
+			if ( t0 < 0 ) return this.at( t1, target );
 
 			// else t0 is in front of the ray, so return the first collision point scaled by t0
-			return this.at( t0, optionalTarget );
+			return this.at( t0, target );
 
 		};
 
@@ -309,7 +321,7 @@ Object.assign( Ray.prototype, {
 
 	},
 
-	intersectPlane: function ( plane, optionalTarget ) {
+	intersectPlane: function ( plane, target ) {
 
 		var t = this.distanceToPlane( plane );
 
@@ -319,7 +331,7 @@ Object.assign( Ray.prototype, {
 
 		}
 
-		return this.at( t, optionalTarget );
+		return this.at( t, target );
 
 	},
 
@@ -349,7 +361,7 @@ Object.assign( Ray.prototype, {
 
 	},
 
-	intersectBox: function ( box, optionalTarget ) {
+	intersectBox: function ( box, target ) {
 
 		var tmin, tmax, tymin, tymax, tzmin, tzmax;
 
@@ -414,7 +426,7 @@ Object.assign( Ray.prototype, {
 
 		if ( tmax < 0 ) return null;
 
-		return this.at( tmin >= 0 ? tmin : tmax, optionalTarget );
+		return this.at( tmin >= 0 ? tmin : tmax, target );
 
 	},
 
@@ -438,7 +450,7 @@ Object.assign( Ray.prototype, {
 		var edge2 = new Vector3();
 		var normal = new Vector3();
 
-		return function intersectTriangle( a, b, c, backfaceCulling, optionalTarget ) {
+		return function intersectTriangle( a, b, c, backfaceCulling, target ) {
 
 			// from http://www.geometrictools.com/GTEngine/Include/Mathematics/GteIntrRay3Triangle3.h
 
@@ -507,7 +519,7 @@ Object.assign( Ray.prototype, {
 			}
 
 			// Ray intersects triangle.
-			return this.at( QdN / DdN, optionalTarget );
+			return this.at( QdN / DdN, target );
 
 		};