Applying affine transformations using SetTexCoord

Main Menu
WoW API Lua API FrameXML util Widget API Widget scripts XML schema Events CVars Macro commands Combat Log Escape sequences Hyperlinks API changes HOWTOs wowuidev

→ UI Tech. Details

The SetTexCoord method in WoW's Texture API can be used for some fairly complex display tasks, including drawing bits of circles, rotating images on screen, etc. Unless one has experience in computer graphics programming, the way in which this can be used might not be evident, so this document hopes to explain how Textures work and how you can use them.

Basic Concepts

Before wading too far into the Texture waters, it's best to begin with some basic concepts:

Screen Coordinates

The screen refers to what the player sees. It may go by various different names in some graphics systems (canvas, surface, etc.) but here we'll just call it the screen. The term Screen Coordinates is used to specify a point in the screen. In World of Warcraft the origin of the coordinates is at the lower left corner.

Texture Coordinates

A Texture frame is used to display all or part of an image. It has an arbitrary location, size, and scale, and appears as a rectangular area on the screen with vertical and horizontal edges, just like any other frame. Within the rectangle of the Texture we'll use the term Texture Coordinates to refer to the location within that rectangle, where (0,0) is the lower left corner, (1,0) is the lower right corner, (0,1) is the upper left corner, and (1,1) is the upper right corner. "Texture" will always have an initial capital, for consistency with the name of the frame type in the API. Each screen coordinate within the bounds of the Texture on screen can be mapped into a Texture frame coordinate within the box from (0,0) to (1,1).

Image Coordinates

Texture frame elements contain images. These are generally loaded from image files located by a file path. The World of Warcraft user interface engine handles different sizes of images: the length of each side is always a power of two (64 x 64, 256 x 256, 512 x 128, etc.). We will use the term Image Coordinates to refer to locations within the contents of the image rectangle. The corners are (0,0) for the top left, (1,0) for the top right, (0,1) for the bottom left, and (1,1) for the bottom right. Notice that the image origin is at the top left, whereas the screen and texture frame origins are at the bottom left.

It is quite possible that a pixel logically outside the file image is visible in the texture frame. To allow for this, the coordinate box from (0,0) to (1,1) containing the entire image is logically extended over an infinite canvas by repeating indefinitely the first and last pixels on each row and column. This will usually give the desired effect, as the pixels at the edge are generally set to the image background colour.

An Analogy

Think of the image as a sheet of infinitely flexible rubber, with a faint set of grid lines rules on it. There's an origin, and coordinates, and the contents of the image file is printed onto the rubber between (0,0) an (1,1) and extends as far as you want in each direction.

Think of the Texture frame element as a rigid rectangular frame, with an attachment point at each of the four corners. The rubber image sheet is attached to each corner of the frame, and then stretches between these points. Anything outside the edge of the frame can be ignored, what's within the edges of the frame is what you see on screen.

The SetTexCoord method is used to provide the image coordinates of each of these four corner points.

Coordinate Transformations

Overview

The way in which the image coordinates map to Texture frame coordinates, and then onto Screen Coordinates (or vice versa) is through a series of Affine Transformations, these are transformations which preserve linearity (points which lay on a line before the transformation, continue to lay on a line after it), and distance ratios (the ratio of distance between two pairs of points on a line before the transformation remain the same afterwards). In the 2D world affine transformations are any combination of:

• Translation (Moving things relative to the origin)
• Rotation (Rotating around the origin)
• Scaling (Multiplying one or both axes by a constant factor)
• Shearing (Offsetting points parallel to a line, where the offset is proportional to the perpendicular distance from that line)

Textures and the Screen

For the Texture frame coordinate to Screen coordinate mapping there's a simple translation and scaling process, since we cannot shear or rotate on-screen frames, but for the mapping from image coordinates to the Texture frame, the full set are available.

Logically the process by which a point is transformed from image space to a point on screen can be represented by two transformations T, the transformation from the image to the Texture, and then S, the transformation from the Texture to the screen (I'll go into the math later):

Texture coordinate from image coordinate: t = T * i Screen coordinate from Texture coordinate: s = S * t

The S transformation is implied by the anchors, size, and scale of the Texture frame element (and the Frame it's contained within).

T, and its inverse

Most of the time you are most readily able to provide T, the transformation between the image and the Texture, because you want to achieve a specific thing (Say, rotate the image 30 degrees and move it to the left). However SetTexCoord wants image coordinates as its parameters, for the four corner Texture coordinates. In order to do this, we need to create T', the inverse of T, such that given t = T * i, the inverse can be applied to get i = T' * t.

With the inverse in hand, we can determine what the image coordinates are going to be by passing in the four corner Texture coordinate values (0,1) (0,0) (1,1) (1,0) in turn and passing the resulting set of coordinates into SetTexCoord as the UL, LL, UR, and LR image coordinates.

The Math

Overview of Matrix Multiplication

(Forgive the somewhat lame formatting)

Matrix multiplication is written as follows, for the expression b = T * a, where b is (X,Y,Z) and a is (x,y,z) you'd have;

(X)		(A	B	C)		(x)
(Y)	=	(D	E	F)	*	(y)
(Z)		(G	H	I)		(z)

Which is then calculated as follows:

X = Ax + By + Cz
Y = Dx + Ey + Fz
Z = Gx + Hy + Iz

Affine Transformations as Matrices

You'll note my matrix example was a 3 dimensional coordinate, and a 3 by 3 matrix, this is because a 2 dimensional matrix isn't enough to represent an affine transformation by itself, because it cannot represent translation. The trick is to add a 'dummy' z coordinate, which ALWAYS has the value 1, and then use the following matrices:

(X)		(A	B	C)		(x)
(Y)	=	(D	E	F)	*	(y)
(1)		(0	0	1)	*	(1)

Which then yields:

X = Ax + By + C
Y = Dx + Ey + F
1 = 1

In this case, A,B,D,E represent scaling, shearing, and rotation, and C,F represent translation. Matrices of this form also multiply together properly, preserving the last row in the correct format.

SetTexCoord Math with Matrices

T as a Matrix

The first step in figuring out your SetTexCoord parameters is to represent your transformation as a matrix. This wont be covered here, but there are plenty of tutorials online concerning the mathematics of matrix transformations. You'll end up with a matrix with 6 variables, in the form shown above, and we'll use those for this example.

Inverting T

Not all matrices can be inverted, but for this case with the affine restricted 3x3 matrix, any matrix for which (AE-BD) is not zero has an inverse (This value is the 'determinant' of the matrix, and represents the change in area that a shape undergoes when transformed, you cannot reverse a matrix with a zero determinant because it represents a collapse into a single point or line)

det = AE - BD
x   = ( EX - BY + (BF-CE)) / det
y   = (-DX + AY - (AF-CD)) / det

Thus, if we were to make a new matrix for T' it'd be as follows

(	E/det	-B/det	(BF-CE)/det	)
(	-D/det	A/det	-(AF-CD)/det	)
(	0	0	1	)

Final SetTexCoord Results

To calculate the final image coordinates, we apply T' to each of the corner Texture coordinates:

UL Texture Coordinates (X,Y) = (0,0)

ULx = ( BF - CE) / det
ULy = (-AF + CD) / det

LL Texture Coordinates (X,Y) = (0,1)

LLx = (-B + BF - CE) / det = (-(1-F)B - CE) / det
LLy = ( A - AF + CD) / det = ( (1-F)A + CD) / det

UR Texture Coordinates (X,Y) = (1,0)

URx = ( E + BF - CE) / det = ( BF + (1-C)E ) / det
URy = (-D - AF + CD) / det = ( AF - (1-C)D ) / det

LR Texture Coordinates (X,Y) = (1,1)

LRx = ( E - B + BF - CE) / det = ( (1-C)E - (1-F)B ) / det
LRy = (-D + A - AF + CD) / det = (-(1-C)D + (1-F)A ) / det

Example Function

The function below will take a texture t, and a matrix with 6 variables as its arguments, and apply the transformation to the texture using the SetTexCoord calculations above.

function setCoords(t, A, B, C, D, E, F)
	local det = A*E - B*D;
	local ULx, ULy, LLx, LLy, URx, URy, LRx, LRy;
	
	ULx, ULy = ( B*F - C*E ) / det, ( -(A*F) + C*D ) / det;
	LLx, LLy = ( -B + B*F - C*E ) / det, ( A - A*F + C*D ) / det;
	URx, URy = ( E + B*F - C*E ) / det, ( -D - A*F + C*D ) / det;
	LRx, LRy = ( E - B + B*F - C*E ) / det, ( -D + A -(A*F) + C*D ) / det;
	
	t:SetTexCoord(ULx, ULy, LLx, LLy, URx, URy, LRx, LRy);
end

Applying transformations is then rather simple. To apply a rotation to the texture, we can use the rotation matrix below (assuming angle a):

(	cos(a)	sin(a)	1	)
(	-sin(a)	cos(a)	1	)

Applying a rotation of 90 degrees can then be done by using:

local cos, sin = math.cos, math.sin;
local angle = math.rad(90);
setCoords(texture, cos(angle), sin(angle), 1, -sin(angle), cos(angle), 1);

Simple rotation of square textures around the center

While the above section about matrix manipulation gives a lot of flexibility, most often much simpler math suffice. Here's an example of rotating a square texture around its center with an arbitrary angle:

local s2 = sqrt(2);
local cos, sin, rad = math.cos, math.sin, math.rad;
local function CalculateCorner(angle)
	local r = rad(angle);
	return 0.5 + cos(r) / s2, 0.5 + sin(r) / s2;
end
local function RotateTexture(texture, angle)
	local LRx, LRy = CalculateCorner(angle + 45);
	local LLx, LLy = CalculateCorner(angle + 135);
	local ULx, ULy = CalculateCorner(angle + 225);
	local URx, URy = CalculateCorner(angle - 45);
	
	texture:SetTexCoord(ULx, ULy, LLx, LLy, URx, URy, LRx, LRy);
end

Even simpler rotation of textures about the center

function RotateTexture(self, degrees)
	local angle = math.rad(degrees)
	local cos, sin = math.cos(angle), math.sin(angle)
	self:SetTexCoord((sin - cos), -(cos + sin), -cos, -sin, sin, -cos, 0, 0)
end

Simple Rotation of Textures about their Own Center

It may just have been a lack of understanding on my part but the above methods did not work for me; Or at least did not meet my needs.

To be explicit, I wanted to be able to rotate a texture about its own center.

In other words, I wanted the texture to spin in place, and not rotate or move the texture about the center of the UI, or its parent's center.

The following code gives a rough idea of how to animate a texture to make it spin.

But the basic method can be seen in the :SetTexCoord method :

local angleInc = 0.25
function myOnUpdate(self, elapsed)
 	self.timer = self.timer + elapsed;
 	if ( self.timer > 0.05 ) then
  		self.hAngle = self.hAngle - angleInc;
  		self.s = sin(self.hAngle);
  		self.c = cos(self.hAngle);
  		miniNote:SetTexCoord(	0.5-self.s, 0.5+self.c,
  					0.5+self.c, 0.5+self.s,
  					0.5-self.c, 0.5-self.s,
  					0.5+self.s, 0.5-self.c);
  		self.timer = 0;
 	end
end

angleInc has been precalculated as a Radians value - the larger it is, the faster the spin.

Or reduce the self.timer threshold to make a smoother rotation.

radians = (pi/180) * degrees

Rotation of Textures about Any Point with Any Aspect

This function caters to all your rotation needs.

function RotateCoordPair (x,y,ox,oy,a,asp)
	y=y/asp
	oy=oy/asp
	return ox + (x-ox)*math.cos(a) - (y-oy)*math.sin(a),
		(oy + (y-oy)*math.cos(a) + (x-ox)*math.sin(a))*asp
end

And use it like this:

	coords={tl={x=0,y=0},
		bl={x=0,y=1},
		tr={x=1,y=0},
		br={x=1,y=1}}
	origin={x=0.5,y=1.0}
	aspect=image_width/image_height
	angle=3.14159/2
	texture:SetTexCoord(
		RotateCoordPair(coords.tl.x,coords.tl.y,origin.x,origin.y,angle,aspect),
		RotateCoordPair(coords.bl.x,coords.bl.y,origin.x,origin.y,angle,aspect),
		RotateCoordPair(coords.tr.x,coords.tr.y,origin.x,origin.y,angle,aspect),
		RotateCoordPair(coords.br.x,coords.br.y,origin.x,origin.y,angle,aspect)
	)

SinusPi (talk) 15:17, September 10, 2009 (UTC)