Added Vector3.projectPoint() as suggested in #2921.

@WestLangley I've changed most of the vector.applyMatrix4() to vector.projectPoint().
Feel free to change back the ones that aren't needed (or let me know which ones can need to be changed back and I will do it).

src/core/Geometry.js

@@ -65,7 +65,7 @@ THREE.Geometry.prototype = {
 		for ( var i = 0, il = this.vertices.length; i < il; i ++ ) {
 
 			var vertex = this.vertices[ i ];
-			vertex.applyMatrix4( matrix );
+			vertex.projectPoint( matrix );
 
 		}
 
@@ -80,7 +80,7 @@ THREE.Geometry.prototype = {
 
 			}
 
-			face.centroid.applyMatrix4( matrix );
+			face.centroid.projectPoint( matrix );
 
 		}
 

src/core/Object3D.js

@@ -91,13 +91,13 @@ THREE.Object3D.prototype = {
 
 	localToWorld: function ( vector ) {
 
-		return vector.applyMatrix4( this.matrixWorld );
+		return vector.projectPoint( this.matrixWorld );
 
 	},
 
 	worldToLocal: function ( vector ) {
 
-		return vector.applyMatrix4( THREE.Object3D.__m1.getInverse( this.matrixWorld ) );
+		return vector.projectPoint( THREE.Object3D.__m1.getInverse( this.matrixWorld ) );
 
 	},
 

src/core/Projector.js

@@ -47,7 +47,7 @@ THREE.Projector = function() {
 
 		_viewProjectionMatrix.multiplyMatrices( camera.projectionMatrix, camera.matrixWorldInverse );
 
-		return vector.applyMatrix4( _viewProjectionMatrix );
+		return vector.projectPoint( _viewProjectionMatrix );
 
 	};
 
@@ -57,7 +57,7 @@ THREE.Projector = function() {
 
 		_viewProjectionMatrix.multiplyMatrices( camera.matrixWorld, camera.projectionMatrixInverse );
 
-		return vector.applyMatrix4( _viewProjectionMatrix );
+		return vector.projectPoint( _viewProjectionMatrix );
 
 	};
 
@@ -111,7 +111,7 @@ THREE.Projector = function() {
 						} else {
 
 							_vector3.copy( object.matrixWorld.getPosition() );
-							_vector3.applyMatrix4( _viewProjectionMatrix );
+							_vector3.projectPoint( _viewProjectionMatrix );
 							_object.z = _vector3.z;
 
 						}
@@ -134,7 +134,7 @@ THREE.Projector = function() {
 					} else {
 
 						_vector3.copy( object.matrixWorld.getPosition() );
-						_vector3.applyMatrix4( _viewProjectionMatrix );
+						_vector3.projectPoint( _viewProjectionMatrix );
 						_object.z = _vector3.z;
 
 					}
@@ -153,7 +153,7 @@ THREE.Projector = function() {
 					} else {
 
 						_vector3.copy( object.matrixWorld.getPosition() );
-						_vector3.applyMatrix4( _viewProjectionMatrix );
+						_vector3.projectPoint( _viewProjectionMatrix );
 						_object.z = _vector3.z;
 
 					}
@@ -231,7 +231,7 @@ THREE.Projector = function() {
 
 					_vertex = getNextVertexInPool();
 
-					_vertex.positionWorld.copy( vertices[ v ] ).applyMatrix4( _modelMatrix );
+					_vertex.positionWorld.copy( vertices[ v ] ).projectPoint( _modelMatrix );
 					_vertex.positionScreen.copy( _vertex.positionWorld ).applyMatrix4( _viewProjectionMatrix );
 
 					_vertex.positionScreen.x /= _vertex.positionScreen.w;
@@ -348,7 +348,7 @@ THREE.Projector = function() {
 
 					_face.normalModelView.copy( _face.normalModel ).applyMatrix3( _normalViewMatrix );
 
-					_face.centroidModel.copy( face.centroid ).applyMatrix4( _modelMatrix );
+					_face.centroidModel.copy( face.centroid ).projectPoint( _modelMatrix );
 
 					faceVertexNormals = face.vertexNormals;
 
@@ -389,7 +389,7 @@ THREE.Projector = function() {
 					_face.color = face.color;
 					_face.material = material;
 
-					_centroid.copy( _face.centroidModel ).applyMatrix4( _viewProjectionMatrix );
+					_centroid.copy( _face.centroidModel ).projectPoint( _viewProjectionMatrix );
 
 					_face.z = _centroid.z;
 

src/extras/GeometryUtils.js

@@ -40,7 +40,7 @@ THREE.GeometryUtils = {
 
 			var vertexCopy = vertex.clone();
 
-			if ( matrix ) vertexCopy.applyMatrix4( matrix );
+			if ( matrix ) vertexCopy.projectPoint( matrix );
 
 			vertices1.push( vertexCopy );
 
@@ -101,7 +101,7 @@ THREE.GeometryUtils = {
 
 			if ( matrix ) {
 
-				faceCopy.centroid.applyMatrix4( matrix );
+				faceCopy.centroid.projectPoint( matrix );
 
 			}
 

src/extras/geometries/TubeGeometry.js

@@ -246,7 +246,7 @@ THREE.TubeGeometry.FrenetFrames = function(path, segments, closed) {
 
 			theta = Math.acos( tangents[ i-1 ].dot( tangents[ i ] ) );
 
-			normals[ i ].applyMatrix4( mat.makeRotationAxis( vec, theta ) );
+			normals[ i ].projectPoint( mat.makeRotationAxis( vec, theta ) );
 
 		}
 
@@ -271,7 +271,7 @@ THREE.TubeGeometry.FrenetFrames = function(path, segments, closed) {
 		for ( i = 1; i < numpoints; i++ ) {
 
 			// twist a little...
-			normals[ i ].applyMatrix4( mat.makeRotationAxis( tangents[ i ], theta * i ) );
+			normals[ i ].projectPoint( mat.makeRotationAxis( tangents[ i ], theta * i ) );
 			binormals[ i ].crossVectors( tangents[ i ], normals[ i ] );
 
 		}

src/extras/renderers/plugins/LensFlarePlugin.js

@@ -160,8 +160,8 @@ THREE.LensFlarePlugin = function ( ) {
 
 			tempPosition.set( flare.matrixWorld.elements[12], flare.matrixWorld.elements[13], flare.matrixWorld.elements[14] );
 
-			tempPosition.applyMatrix4( camera.matrixWorldInverse );
-			tempPosition.applyMatrix4( camera.projectionMatrix );
+			tempPosition.projectPoint( camera.matrixWorldInverse );
+			tempPosition.projectPoint( camera.projectionMatrix );
 
 			// setup arrays for gl programs
 

src/extras/renderers/plugins/ShadowMapPlugin.js

@@ -451,7 +451,7 @@ THREE.ShadowMapPlugin = function ( ) {
 			p.copy( pointsFrustum[ i ] );
 			THREE.ShadowMapPlugin.__projector.unprojectVector( p, camera );
 
-			p.applyMatrix4( shadowCamera.matrixWorldInverse );
+			p.projectPoint( shadowCamera.matrixWorldInverse );
 
 			if ( p.x < _min.x ) _min.x = p.x;
 			if ( p.x > _max.x ) _max.x = p.x;

src/math/Box3.js

@@ -259,15 +259,15 @@ THREE.Box3.prototype = {
 
 		// NOTE: I am using a binary pattern to specify all 2^3 combinations below
 		var newPoints = [
-			THREE.Box3.__v0.set( this.min.x, this.min.y, this.min.z ).applyMatrix4( matrix ),
-			THREE.Box3.__v0.set( this.min.x, this.min.y, this.min.z ).applyMatrix4( matrix ), // 000
-			THREE.Box3.__v1.set( this.min.x, this.min.y, this.max.z ).applyMatrix4( matrix ), // 001
-			THREE.Box3.__v2.set( this.min.x, this.max.y, this.min.z ).applyMatrix4( matrix ), // 010
-			THREE.Box3.__v3.set( this.min.x, this.max.y, this.max.z ).applyMatrix4( matrix ), // 011
-			THREE.Box3.__v4.set( this.max.x, this.min.y, this.min.z ).applyMatrix4( matrix ), // 100
-			THREE.Box3.__v5.set( this.max.x, this.min.y, this.max.z ).applyMatrix4( matrix ), // 101
-			THREE.Box3.__v6.set( this.max.x, this.max.y, this.min.z ).applyMatrix4( matrix ), // 110
-			THREE.Box3.__v7.set( this.max.x, this.max.y, this.max.z ).applyMatrix4( matrix )  // 111
+			THREE.Box3.__v0.set( this.min.x, this.min.y, this.min.z ).projectPoint( matrix ),
+			THREE.Box3.__v0.set( this.min.x, this.min.y, this.min.z ).projectPoint( matrix ), // 000
+			THREE.Box3.__v1.set( this.min.x, this.min.y, this.max.z ).projectPoint( matrix ), // 001
+			THREE.Box3.__v2.set( this.min.x, this.max.y, this.min.z ).projectPoint( matrix ), // 010
+			THREE.Box3.__v3.set( this.min.x, this.max.y, this.max.z ).projectPoint( matrix ), // 011
+			THREE.Box3.__v4.set( this.max.x, this.min.y, this.min.z ).projectPoint( matrix ), // 100
+			THREE.Box3.__v5.set( this.max.x, this.min.y, this.max.z ).projectPoint( matrix ), // 101
+			THREE.Box3.__v6.set( this.max.x, this.max.y, this.min.z ).projectPoint( matrix ), // 110
+			THREE.Box3.__v7.set( this.max.x, this.max.y, this.max.z ).projectPoint( matrix )  // 111
 		];
 
 		this.makeEmpty();

src/math/Matrix3.js

@@ -65,7 +65,7 @@ THREE.Matrix3.prototype = {
 
 	multiplyVector3: function ( vector ) {
 
-		console.warn( 'DEPRECATED: Matrix3\'s .multiplyVector3() has been removed. Use is now vector.applyMatrix3( matrix ) instead.' );
+		console.warn( 'DEPRECATED: Matrix3\'s .multiplyVector3() has been removed. Use vector.applyMatrix3( matrix ) instead.' );
 		return vector.applyMatrix3( this );
 
 	},

src/math/Matrix4.js

@@ -331,14 +331,14 @@ THREE.Matrix4.prototype = {
 
 	multiplyVector3: function ( vector ) {
 
-		console.warn( 'DEPRECATED: Matrix4\'s .multiplyVector3() has been removed. Use is now vector.applyMatrix4( matrix ) instead.' );
-		return vector.applyMatrix4( this );
+		console.warn( 'DEPRECATED: Matrix4\'s .multiplyVector3() has been removed. Use vector.applyMatrix4( matrix ) or vector.projectPoint( matrix ) instead.' );
+		return vector.projectPoint( this );
 
 	},
 
 	multiplyVector4: function ( vector ) {
 
-		console.warn( 'DEPRECATED: Matrix4\'s .multiplyVector4() has been removed. Use is now vector.applyMatrix4( matrix ) instead.' );
+		console.warn( 'DEPRECATED: Matrix4\'s .multiplyVector4() has been removed. Use vector.applyMatrix4( matrix ) instead.' );
 		return vector.applyMatrix4( this );
 
 	},
@@ -353,7 +353,7 @@ THREE.Matrix4.prototype = {
 			tmp.y = a[ i + 1 ];
 			tmp.z = a[ i + 2 ];
 
-			tmp.applyMatrix4(this);
+			tmp.projectPoint( this );
 
 			a[ i ]     = tmp.x;
 			a[ i + 1 ] = tmp.y;

src/math/Plane.js

@@ -169,7 +169,7 @@ THREE.Plane.prototype = {
 		var newNormal = THREE.Plane.__v1.copy( this.normal ).applyMatrix3( optionalNormalMatrix );
 
 		var newCoplanarPoint = this.coplanarPoint( THREE.Plane.__v2 );
-		newCoplanarPoint.applyMatrix4( matrix );
+		newCoplanarPoint.projectPoint( matrix );
 
 		this.setFromNormalAndCoplanarPoint( newNormal, newCoplanarPoint );
 

src/math/Ray.js

@@ -132,8 +132,8 @@ THREE.Ray.prototype = {
 
 	transform: function ( matrix4 ) {
 
-		this.direction.add( this.origin ).applyMatrix4( matrix4 );
-		this.origin.applyMatrix4( matrix4 );
+		this.direction.add( this.origin ).projectPoint( matrix4 );
+		this.origin.projectPoint( matrix4 );
 		this.direction.sub( this.origin );
 
 		return this;

src/math/Sphere.js

@@ -106,7 +106,7 @@ THREE.Sphere.prototype = {
 
 	transform: function ( matrix ) {
 
-		this.center.applyMatrix4( matrix );
+		this.center.projectPoint( matrix );
 		this.radius = this.radius * matrix.getMaxScaleOnAxis();
 
 		return this;

src/math/Vector3.js

@@ -209,16 +209,15 @@ THREE.Vector3.prototype = {
 
 	applyMatrix4: function ( m ) {
 
-		var x = this.x;
-		var y = this.y;
-		var z = this.z;
+		// input: THREE.Matrix4 affine matrix
+
+		var x = this.x, y = this.y, z = this.z;
 
 		var e = m.elements;
-		var d = 1 / ( e[3] * x + e[7] * y + e[11] * z + e[15] );
 
-		this.x = ( e[0] * x + e[4] * y + e[8] * z + e[12] ) * d;
-		this.y = ( e[1] * x + e[5] * y + e[9] * z + e[13] ) * d;
-		this.z = ( e[2] * x + e[6] * y + e[10] * z + e[14] ) * d;
+		this.x = e[0] * x + e[4] * y + e[8]  * z + e[12];
+		this.y = e[1] * x + e[5] * y + e[9]  * z + e[13];
+		this.z = e[2] * x + e[6] * y + e[10] * z + e[14];
 
 		return this;
 
@@ -272,6 +271,23 @@ THREE.Vector3.prototype = {
 
 	},
 
+	projectPoint: function ( m ) {
+
+		// input: THREE.Matrix4 projection matrix
+
+		var x = this.x, y = this.y, z = this.z;
+
+		var e = m.elements;
+		var d = 1 / ( e[3] * x + e[7] * y + e[11] * z + e[15] ); // perspective divide
+
+		this.x = ( e[0] * x + e[4] * y + e[8]  * z + e[12] ) * d;
+		this.y = ( e[1] * x + e[5] * y + e[9]  * z + e[13] ) * d;
+		this.z = ( e[2] * x + e[6] * y + e[10] * z + e[14] ) * d;
+
+		return this;
+
+	},
+
 	divide: function ( v ) {
 
 		this.x /= v.x;

src/renderers/WebGLRenderer.js

@@ -1176,7 +1176,7 @@ THREE.WebGLRenderer = function ( parameters ) {
 				vertex = vertices[ v ];
 
 				_vector3.copy( vertex );
-				_vector3.applyMatrix4( _projScreenMatrixPS );
+				_vector3.projectPoint( _projScreenMatrixPS );
 
 				sortArray[ v ] = [ _vector3.z, v ];
 
@@ -4178,7 +4178,7 @@ THREE.WebGLRenderer = function ( parameters ) {
 						} else {
 
 							_vector3.copy( object.matrixWorld.getPosition() );
-							_vector3.applyMatrix4( _projScreenMatrix );
+							_vector3.projectPoint( _projScreenMatrix );
 
 							webglObject.z = _vector3.z;
 

src/renderers/WebGLRenderer2.js

@@ -1299,7 +1299,7 @@ THREE.WebGLRenderer = THREE.WebGLRenderer2 = function ( parameters ) {
 						} else {
 
 							_vector3.copy( object.matrixWorld.getPosition() );
-							_vector3.applyMatrix4(_projScreenMatrix);
+							_vector3.projectPoint(_projScreenMatrix);
 
 							webglObject.z = _vector3.z;
 

src/renderers/webgl/objects/ParticleRenderer.js

@@ -68,7 +68,7 @@ THREE.WebGLRenderer2.ParticleRenderer.prototype.setBuffers = function( geometry,
 			vertex = vertices[ v ];
 
 			_vector3.copy( vertex );
-			_vector3.applyMatrix4(_projScreenMatrixPS);
+			_vector3.projectPoint(_projScreenMatrixPS);
 
 			sortArray[ v ] = [ _vector3.z, v ];