Texture rotation: new API

d1e46316 · WestLangley · 529a142e · d1e46316 · d1e46316 · d1e46316
5 changed file
--- a/docs/api/math/Matrix3.html
+++ b/docs/api/math/Matrix3.html
-	<!DOCTYPE html>
+<!DOCTYPE html>
 <html lang="en">
 	<head>
 		<meta charset="utf-8" />

--- a/docs/api/textures/Texture.html
+++ b/docs/api/textures/Texture.html
@@ -147,15 +147,18 @@
 		assigned to achieve the desired repetiton.
 		</div>

-		<h3>[property:number rotation]</h3>
+		<h3>[property:boolean matrixAutoUpdate]</h3>
 		<div>
-		How much the texture is rotated, in radians. Postive values are counter-clockwise. Default is *0*.
+		Whether to update the texture's uv-transform [property:Matrix3 matrix] based on the [property:Vector2 offset] and
+		[property:Vector2 repeat] settings. True by default.
+		Set this to false if you are specifying the uv-transform matrix directly.
 		</div>

-		<h3>[property:Vector2 center]</h3>
+		<h3>[property:Matrix3 matrix]</h3>
 		<div>
-		The center point of the texture -- used for both rotation and scaling. The range for each component is *0.0* to *1.0*. The default is [ *0*, *0* ],
-		which corresponds to the lower-left corner of the texture.
+		The uv-transform matrix for the texture. Used instead of [property:Vector2 offset] and [property:Vector2 repeat]
+		when the texture's [property:boolean matrixAutoUpdate] property is false.
+		Default is the indentity matrix.
 		</div>

 		<h3>[property:boolean generateMipmaps]</h3>

--- a/examples/webgl_materials_texture_rotation.html
+++ b/examples/webgl_materials_texture_rotation.html
@@ -87,13 +87,14 @@
 				var loader = new THREE.TextureLoader();
 				var texture = loader.load( 'textures/UV_Grid_Sm.jpg', render );
 				texture.wrapS = texture.wrapT = THREE.RepeatWrapping;
+				texture.matrixAutoUpdate = false;

 				var material = new THREE.MeshBasicMaterial( { map: texture } );

 				mesh = new THREE.Mesh( geometry, material );
 				scene.add( mesh );

-				updateTextureParams();
+				updateUvTransform();

 				initGui();

@@ -119,17 +120,11 @@

 			}

-			function updateTextureParams() {
+			function updateUvTransform() {

-				var map = mesh.material.map;
+				var matrix = mesh.material.map.matrix;

-				map.offset.x = API.translateX;
-				map.offset.y = API.translateY;
-				map.repeat.x = API.scaleX;
-				map.repeat.y = API.scaleY;
-				map.rotation = API.rotation;
-				map.center.x = API.centerX;
-				map.center.y = API.centerY;
+				matrix.setUvTransform( API.translateX, API.translateY, API.scaleX, API.scaleY, API.rotation, API.centerX, API.centerY );

 				render();

@@ -141,13 +136,13 @@

 				gui = new dat.GUI();

-				gui.add( API, 'translateX', 0.0, 1.0 ).name( 'offset.x' ).onChange( updateTextureParams );
-				gui.add( API, 'translateY', 0.0, 1.0 ).name( 'offset.y' ).onChange( updateTextureParams );
-				gui.add( API, 'scaleX', 0.25, 2.0 ).name( 'repeat.x' ).onChange( updateTextureParams );
-				gui.add( API, 'scaleY', 0.25, 2.0 ).name( 'repeat.y' ).onChange( updateTextureParams );
-				gui.add( API, 'rotation', - 2.0, 2.0 ).name( 'rotation' ).onChange( updateTextureParams );
-				gui.add( API, 'centerX', 0.0, 1.0 ).name( 'center.x' ).onChange( updateTextureParams );
-				gui.add( API, 'centerY', 0.0, 1.0 ).name( 'center.y' ).onChange( updateTextureParams );
+				gui.add( API, 'translateX', 0.0, 1.0 ).name( 'offset.x' ).onChange( updateUvTransform );
+				gui.add( API, 'translateY', 0.0, 1.0 ).name( 'offset.y' ).onChange( updateUvTransform );
+				gui.add( API, 'scaleX', 0.25, 2.0 ).name( 'repeat.x' ).onChange( updateUvTransform );
+				gui.add( API, 'scaleY', 0.25, 2.0 ).name( 'repeat.y' ).onChange( updateUvTransform );
+				gui.add( API, 'rotation', - 2.0, 2.0 ).name( 'rotation' ).onChange( updateUvTransform );
+				gui.add( API, 'centerX', 0.0, 1.0 ).name( 'center.x' ).onChange( updateUvTransform );
+				gui.add( API, 'centerY', 0.0, 1.0 ).name( 'center.y' ).onChange( updateUvTransform );

 			}


--- a/src/renderers/WebGLRenderer.js
+++ b/src/renderers/WebGLRenderer.js
@@ -1982,12 +1982,18 @@ function WebGLRenderer( parameters ) {

 			}

-			var offset = uvScaleMap.offset;
-			var repeat = uvScaleMap.repeat;
-			var rotation = uvScaleMap.rotation;
-			var center = uvScaleMap.center;
+			if ( uvScaleMap.matrixAutoUpdate === true ) {

-			uniforms.uvTransform.value.setUvTransform( offset.x, offset.y, repeat.x, repeat.y, rotation, center.x, center.y );
+				var offset = uvScaleMap.offset;
+				var repeat = uvScaleMap.repeat;
+
+				uniforms.uvTransform.value.setUvTransform( offset.x, offset.y, repeat.x, repeat.y, 0, 0, 0 );
+
+			} else {
+
+				uniforms.uvTransform.value.copy( uvScaleMap.matrix );
+
+			}

 		}

@@ -2019,12 +2025,18 @@ function WebGLRenderer( parameters ) {

 		if ( material.map !== null ) {

-			var offset = material.map.offset;
-			var repeat = material.map.repeat;
-			var rotation = material.map.rotation;
-			var center = material.map.center;
+			if ( material.map.matrixAutoUpdate === true ) {

-			uniforms.uvTransform.value.setUvTransform( offset.x, offset.y, repeat.x, repeat.y, rotation, center.x, center.y );
+				var offset = material.map.offset;
+				var repeat = material.map.repeat;
+
+				uniforms.uvTransform.value.setUvTransform( offset.x, offset.y, repeat.x, repeat.y, 0, 0, 0 );
+
+			} else {
+
+				uniforms.uvTransform.value.copy( material.map.matrix );
+
+			}

 		}


--- a/src/textures/Texture.js
+++ b/src/textures/Texture.js
@@ -3,6 +3,7 @@ import { UVMapping } from '../constants';
 import { MirroredRepeatWrapping, ClampToEdgeWrapping, RepeatWrapping, LinearEncoding, UnsignedByteType, RGBAFormat, LinearMipMapLinearFilter, LinearFilter } from '../constants';
 import { _Math } from '../math/Math';
 import { Vector2 } from '../math/Vector2';
+import { Matrix3 } from '../math/Matrix3';

 /**
 * @author mrdoob / http://mrdoob.com/
@@ -38,8 +39,9 @@ function Texture( image, mapping, wrapS, wrapT, magFilter, minFilter, format, ty

 	this.offset = new Vector2( 0, 0 );
 	this.repeat = new Vector2( 1, 1 );
-	this.rotation = 0;
-	this.center = new Vector2( 0, 0 );
+
+	this.matrixAutoUpdate = true;
+	this.matrix = new Matrix3();

 	this.generateMipmaps = true;
 	this.premultiplyAlpha = false;
@@ -104,8 +106,9 @@ Object.assign( Texture.prototype, EventDispatcher.prototype, {

 		this.offset.copy( source.offset );
 		this.repeat.copy( source.repeat );
-		this.rotation = source.rotation;
-		this.center.copy( source.center );
+
+		this.matrixAutoUpdate = source.matrixAutoUpdate;
+		this.matrix.copy( source.matrix );

 		this.generateMipmaps = source.generateMipmaps;
 		this.premultiplyAlpha = source.premultiplyAlpha;
@@ -179,8 +182,10 @@ Object.assign( Texture.prototype, EventDispatcher.prototype, {

 			repeat: [ this.repeat.x, this.repeat.y ],
 			offset: [ this.offset.x, this.offset.y ],
-			rotation: this.rotation,
-			center: [ this.center.x, this.center.y ],
+
+			matrixAutoUpdate: this.matrixAutoUpdate,
+			matrix: this.matrix.toArray(),
+
 			wrap: [ this.wrapS, this.wrapT ],

 			minFilter: this.minFilter,