Merge pull request #10405 from fta2012/vec3-applyMatrix4-applyProjection

Combine Vector3.applyProjection into applyMatrix4 and deprecate applyProjection

docs/api/deprecated/DeprecatedList.html

@@ -119,7 +119,7 @@
 		<h2>Core</h2>
 
 		<h3>[page:EventDispatcher]</h3>
-		<div>EventDispatcher.apply has been has been removed. Inherit or Object.assign the prototype to mix-in instead.</div>
+		<div>EventDispatcher.apply has been removed. Inherit or Object.assign the prototype to mix-in instead.</div>
 
 		<h3>[page:Raycaster]</h3>
 		<div>Raycaster.params.PointCloud has been renamed to [page:Raycaster.params.Points].</div>
@@ -127,9 +127,9 @@
 
 		<h3>[page:Uniform]</h3>
 		<div>
-			Uniform.dynamic has been has been removed. Use object.onBeforeRender() instead.<br /><br />
+			Uniform.dynamic has been removed. Use object.onBeforeRender() instead.<br /><br />
 
-			Uniform.onUpdate has been has been removed. Use object.onBeforeRender() instead.
+			Uniform.onUpdate has been removed. Use object.onBeforeRender() instead.
 		</div>
 
 
@@ -318,8 +318,7 @@
 
 			Matrix4.setRotationFromQuaternion() has been renamed to [page:Matrix4.makeRotationFromQuaternion]( quaternion ).<br /><br />
 
-			Matrix4.multiplyVector3() has been has been removed. Use vector.applyMatrix4( matrix )
-			or vector.applyProjection( matrix ) instead.<br /><br />
+			Matrix4.multiplyVector3() has been removed. Use vector.applyMatrix4( matrix ) instead.<br /><br />
 
 			Matrix4.multiplyVector4() has been removed. Use vector.applyMatrix4( matrix ) instead.<br /><br />
 
@@ -374,6 +373,8 @@
 
 			Vector3.getColumnFromMatrix() has been renamed to [page:Vector3.setFromMatrixColumn]().<br /><br />
 
+			Vector3.applyProjection() has been removed. Use [page:Vector3.applyMatrix4]() instead.<br /><br />
+
 			Vector3.fromAttribute() has been renamed to [page:Vector3.fromBufferAttribute]().
 		</div>
 

docs/api/math/Vector3.html

@@ -108,29 +108,7 @@ var d = a.distanceTo( b );
 
 		<h3>[method:Vector3 applyMatrix4]( [page:Matrix4 m] )</h3>
 		<div>
-		Multiply this vector by 4 x 3 subset of a [page:Matrix4 m]. If [page:Matrix4 m] is:
-		<code>
-a, b, c, d,
-e, f, g, h,
-i, j, k, l,
-m, n, o, p
-		</code>
-		Then the 4 x 3 matrix will be:
-		<code>
-a, b, c,
-e, f, g,
-i, j, k,
-m, n, o
-		</code>
-		Note that the input matrix [page:Matrix4 m] is assumed to be
-		[link:https://en.wikipedia.org/wiki/Affine_transformation affine].
-		</div>
-
-		<h3>[method:Vector3 applyProjection]( [page:Matrix4 m] )</h3>
-		<div>
-		[page:Matrix4 m] - [page:Matrix4] projection matrix.<br /><br />
-
-		Multiplies this vector and m, and divides by perspective.
+		Multiplies this vector (with an implicit 1 in the 4th dimension) and m, and divides by perspective.
 		</div>
 
 		<h3>[method:Vector3 applyQuaternion]( [page:Quaternion quaternion] )</h3>

examples/js/renderers/CSS2DRenderer.js

@@ -60,7 +60,7 @@ THREE.CSS2DRenderer = function () {
 		if ( object instanceof THREE.CSS2DObject ) {
 
 			vector.setFromMatrixPosition( object.matrixWorld );
-			vector.applyProjection( viewProjectionMatrix );
+			vector.applyMatrix4( viewProjectionMatrix );
 
 			var element = object.element;
 			var style = 'translate(-50%,-50%) translate(' + ( vector.x * _widthHalf + _widthHalf ) + 'px,' + ( - vector.y * _heightHalf + _heightHalf ) + 'px)';

examples/js/renderers/Projector.js

@@ -346,7 +346,7 @@ THREE.Projector = function () {
 			_object.object = object;
 
 			_vector3.setFromMatrixPosition( object.matrixWorld );
-			_vector3.applyProjection( _viewProjectionMatrix );
+			_vector3.applyMatrix4( _viewProjectionMatrix );
 			_object.z = _vector3.z;
 			_object.renderOrder = object.renderOrder;
 

examples/js/renderers/SVGRenderer.js

@@ -225,7 +225,7 @@ THREE.SVGRenderer = function () {
 			 if ( object instanceof THREE.SVGObject ) {
 
 				_vector3.setFromMatrixPosition( object.matrixWorld );
-				_vector3.applyProjection( _viewProjectionMatrix );
+				_vector3.applyMatrix4( _viewProjectionMatrix );
 
 				var x =   _vector3.x * _svgWidthHalf;
 				var y = - _vector3.y * _svgHeightHalf;

examples/webgl_custom_attributes_points2.html

@@ -226,7 +226,7 @@
 			for ( var i = 0; i < length; i ++ ) {
 
 				vector.fromArray( positions, i * 3 );
-				vector.applyProjection( matrix );
+				vector.applyMatrix4( matrix );
 
 				sortArray.push( [ vector.z, i ] );
 

src/Three.Legacy.js

@@ -424,8 +424,8 @@ Object.assign( Matrix4.prototype, {
 	},
 	multiplyVector3: function ( vector ) {
 
-		console.warn( 'THREE.Matrix4: .multiplyVector3() has been removed. Use vector.applyMatrix4( matrix ) or vector.applyProjection( matrix ) instead.' );
-		return vector.applyProjection( this );
+		console.warn( 'THREE.Matrix4: .multiplyVector3() has been removed. Use vector.applyMatrix4( matrix ) instead.' );
+		return vector.applyMatrix4( this );
 
 	},
 	multiplyVector4: function ( vector ) {
@@ -592,7 +592,12 @@ Object.assign( Vector3.prototype, {
 		return this.setFromMatrixColumn( matrix, index );
 
 	},
+	applyProjection: function ( m ) {
+
+		console.warn( 'THREE.Vector3: .applyProjection() has been removed. Use .applyMatrix4( m ) instead.' );
+		return this.applyMatrix4( m );
 
+	},
 	fromAttribute: function ( attribute, index, offset ) {
 
 		console.error( 'THREE.Vector3: .fromAttribute() has been renamed to .fromBufferAttribute().' );

src/math/Vector3.js

@@ -293,32 +293,15 @@ Vector3.prototype = {
 
 	applyMatrix4: function ( m ) {
 
-		// input: THREE.Matrix4 affine matrix
-
 		var x = this.x, y = this.y, z = this.z;
 		var e = m.elements;
 
 		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 ];
+		var w =  e[ 3 ] * x + e[ 7 ] * y + e[ 11 ] * z + e[ 15 ];
 
-		return this;
-
-	},
-
-	applyProjection: 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;
+		return this.divideScalar( w );
 
 	},
 
@@ -353,7 +336,7 @@ Vector3.prototype = {
 			if ( matrix === undefined ) matrix = new Matrix4();
 
 			matrix.multiplyMatrices( camera.projectionMatrix, matrix.getInverse( camera.matrixWorld ) );
-			return this.applyProjection( matrix );
+			return this.applyMatrix4( matrix );
 
 		};
 
@@ -368,7 +351,7 @@ Vector3.prototype = {
 			if ( matrix === undefined ) matrix = new Matrix4();
 
 			matrix.multiplyMatrices( camera.matrixWorld, matrix.getInverse( camera.projectionMatrix ) );
-			return this.applyProjection( matrix );
+			return this.applyMatrix4( matrix );
 
 		};
 

src/renderers/WebGLRenderer.js

@@ -1382,7 +1382,7 @@ function WebGLRenderer( parameters ) {
 				if ( _this.sortObjects === true ) {
 
 					_vector3.setFromMatrixPosition( object.matrixWorld );
-					_vector3.applyProjection( _projScreenMatrix );
+					_vector3.applyMatrix4( _projScreenMatrix );
 
 				}
 
@@ -1405,7 +1405,7 @@ function WebGLRenderer( parameters ) {
 						if ( _this.sortObjects === true ) {
 
 							_vector3.setFromMatrixPosition( object.matrixWorld );
-							_vector3.applyProjection( _projScreenMatrix );
+							_vector3.applyMatrix4( _projScreenMatrix );
 
 						}
 

src/renderers/webgl/plugins/LensFlarePlugin.js

@@ -242,7 +242,7 @@ function LensFlarePlugin( renderer, flares ) {
 			tempPosition.set( flare.matrixWorld.elements[ 12 ], flare.matrixWorld.elements[ 13 ], flare.matrixWorld.elements[ 14 ] );
 
 			tempPosition.applyMatrix4( camera.matrixWorldInverse );
-			tempPosition.applyProjection( camera.projectionMatrix );
+			tempPosition.applyMatrix4( camera.projectionMatrix );
 
 			// setup arrays for gl programs
 

test/unit/math/Vector3.js

@@ -344,3 +344,36 @@ test( "equals", function() {
 	ok( a.equals( b ), "Passed!" );
 	ok( b.equals( a ), "Passed!" );
 });
+
+test( "applyMatrix4", function() {
+
+	var a = new THREE.Vector3( x, y, z );
+	var b = new THREE.Vector4( x, y, z, 1 );
+
+	var m = new THREE.Matrix4().makeRotationX( Math.PI );
+	a.applyMatrix4( m );
+	b.applyMatrix4( m );
+	ok( a.x == b.x / b.w, "Passed!" );
+	ok( a.y == b.y / b.w, "Passed!" );
+	ok( a.z == b.z / b.w, "Passed!" );
+
+	m = new THREE.Matrix4().makeTranslation( 3, 2, 1 );
+	a.applyMatrix4( m );
+	b.applyMatrix4( m );
+	ok( a.x == b.x / b.w, "Passed!" );
+	ok( a.y == b.y / b.w, "Passed!" );
+	ok( a.z == b.z / b.w, "Passed!" );
+
+	m = new THREE.Matrix4().set(
+		1, 0, 0, 0,
+		0, 1, 0, 0,
+		0, 0, 1, 0,
+		0, 0, 1, 0
+	);
+	a.applyMatrix4( m );
+	b.applyMatrix4( m );
+	ok( a.x == b.x / b.w, "Passed!" );
+	ok( a.y == b.y / b.w, "Passed!" );
+	ok( a.z == b.z / b.w, "Passed!" );
+
+});