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:

The Screen

The screen is used to refer to what the user 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 Coordinate is used to specify a point on the screen (In WoW the origin is in the bottom left hand corner).

Texture Frame Elements

In order to display all part of an image, we use a Texture frame element, which appears as a rectangular area on the screen with vertical and horizontal edges, just like any other Frame. A Texture frame element can have an arbitrary location, size, and scale. Within the rectangle of the Texture, we'll use the term Texture Frame Coordinate to refer to the location within that rectangle where (0,0) is the bottom left corner, (1,0) is the bottom right corner, (0,1) is the top left corner, and (1,1) is the top right corner. Texture will always have an initial capital, for consistency with the element name 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).

The Image

Texture frame elements display images, these are generally loaded from files and are specified with a path. The WoW UI engine handles various different sizes of images, as long as each side is a power of 2 (64x64, 256x256, 512x128, etc). Within an image, we'll use the term Image Coordinate to refer to the location within the contents of the image. 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 in a different corner from the screen origin.

While image coordinate box from (0,0) to (1,1) contains the whole image as it appears in its source file, the image logically extends to infinity in each direction, by repeating the edge pixel of the image file. So, if your image has a left edge which is entirely blue pixels, then there would be blue at (x, 0.5) for all x <= 0. Similarly, if the image has a top edge that is transparent, then you'll get transparency at (0.5, y) for all y >= 1.

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);