Transformations

We can now put shapes on the screen, colour them per vertex and wrap textures around them. They just sit there, though. To make something move we could rewrite its vertices every frame and upload the buffer again, but that is slow, and the buffers in our lessons are immutable anyway: the GPU got them once, at creation, and the CPU never touches them again. The usual answer, and the one every chapter from here on relies on, is to leave the vertices alone and hand the vertex shader a matrix that says how to move them.

Matrices are one of those subjects that look forbidding until you have used them a few times, after which they become an everyday tool. This chapter is the maths groundwork for the rest of the tutorial: vectors first, then matrices, then how the two combine into transformations. If some of it does not stick on the first read, that is normal; skim it, carry on, and come back when a later chapter leans on it. At the end we put it to work with math.asm, the small library that does for our lessons what GLM does for LearnOpenGL.

Vectors

A vector is a quantity with a direction and a magnitude (its length). Directions given to a hiker are vectors: "walk 300 metres north, then 100 metres east" is two of them, each a direction plus a distance. In graphics we mostly deal with vectors of two, three or four components. A 2D vector describes a direction in a plane, a 3D vector a direction in space.

Because a vector is only a direction and a length, it has no fixed starting point. In LearnOpenGL's picture below, \(\color{red}{\bar{v}}\) and \(\color{blue}{\bar{w}}\) start in different places but are the same vector, (3, 2): three to the right, two up.

Vectors v and w with different origins but the same direction and length, and a third vector n (LearnOpenGL's diagram)

On paper a vector is written as a letter with a bar, \(\bar{v}\), and its components are stacked in a column:

\[\bar{v} = \begin{pmatrix} \color{red}x \\ \color{green}y \\ \color{blue}z \end{pmatrix}\]

We also use vectors for positions. The trick is to fix the start of the vector at the origin, (0, 0, 0): the vector then points at exactly one spot, and that spot is the position. The vertex positions we have been writing into buffers are vectors read this way, and so are the colours and texture coordinates, which are just "a few numbers that belong together". In math.asm they are plain structures of 32-bit floats:

vec3 struct
    x real4 ?
    y real4 ?
    z real4 ?
vec3 ends

with vec2 and vec4 alongside, so z_axis vec3 <0.0, 0.0, 1.0> in a lesson's data is the unit z direction. In HLSL the same things are called float2, float3 and float4, which we have been using since the first triangle.

Scalar vector operations

A scalar is a single number. Adding a scalar to a vector, or subtracting, multiplying or dividing by one, applies the operation to every component:

\[\begin{pmatrix} \color{red}2 \\ \color{green}4 \\ \color{blue}6 \end{pmatrix} \div 2 = \begin{pmatrix} \color{red}2 \div 2 \\ \color{green}4 \div 2 \\ \color{blue}6 \div 2 \end{pmatrix} = \begin{pmatrix} \color{red}1 \\ \color{green}2 \\ \color{blue}3 \end{pmatrix}\]

Multiplication is the one we use most: it keeps the direction and changes the length. math.asm calls it v3_scale.

Vector negation

Negating a vector flips it around: same length, opposite direction. Every component gets a minus sign, which is the same as scaling by -1:

\[-\bar{v} = -\begin{pmatrix} \color{red}{v_x} \\ \color{green}{v_y} \\ \color{blue}{v_z} \end{pmatrix} = \begin{pmatrix} -\color{red}{v_x} \\ -\color{green}{v_y} \\ -\color{blue}{v_z} \end{pmatrix}\]

Addition and subtraction

Two vectors are added component by component:

\[\bar{v} = \begin{pmatrix} \color{red}4 \\ \color{green}2 \\ \color{blue}0 \end{pmatrix}, \bar{k} = \begin{pmatrix} \color{red}1 \\ \color{green}2 \\ \color{blue}0 \end{pmatrix} \rightarrow \bar{v} + \bar{k} = \begin{pmatrix} \color{red}{4 + 1} \\ \color{green}{2 + 2} \\ \color{blue}{0 + 0} \end{pmatrix} = \begin{pmatrix} \color{red}5 \\ \color{green}4 \\ \color{blue}0 \end{pmatrix}\]

Drawn as arrows, addition means walking the first vector and then the second from where the first ended. The sum is the arrow from the very start to the very end:

Adding v = (4, 2) and k = (1, 2) head to tail gives (5, 4) (LearnOpenGL's diagram)

Subtraction is adding the negated vector. Its useful property is geometric: \(\bar{w} - \bar{v}\) is the vector that leads from the point \(\bar{v}\) to the point \(\bar{w}\). Whenever we need "the direction from here to there", from a surface to a light or from the camera to its target, it is a subtraction of two positions.

The difference w - v points from the tip of v to the tip of w (LearnOpenGL's diagram)

Length

The components of a 2D vector are the two short sides of a right-angled triangle, and the vector itself is the long side:

Vector (4, 2) as the hypotenuse of a triangle with sides x = 4 and y = 2 (LearnOpenGL's diagram)

So Pythagoras gives its length, written \(||\bar{v}||\), and in 3D we simply add the third square:

\[||\bar{v}|| = \sqrt{{\color{red}x}^2 + {\color{green}y}^2 + {\color{blue}z}^2}, \qquad ||(4, 2, 0)|| = \sqrt{16 + 4 + 0} = \sqrt{20} \approx 4.47\]

A vector of length exactly 1 is a unit vector. Any vector except zero can be turned into one by dividing it by its own length, which is called normalizing it, and the result is written with a hat:

\[\hat{n} = \frac{\bar{v}}{||\bar{v}||}\]

Unit vectors are what we use whenever only the direction matters, as it will for surface normals and light directions. In math.asm:

; rcx: a -> xmm0: |a|
align 16
v3_length proc
    v3load xmm0, [rcx]
    dpps xmm0, xmm0, 71h
    sqrtss xmm0, xmm0
    ret
v3_length endp

; rcx: out, rdx: a. A zero vector stays zero.
align 16
v3_normalize proc
    v3load xmm0, [rdx]
    movaps xmm1, xmm0
    dpps xmm1, xmm1, 7Fh        ; |a|^2 in every lane
    xorps xmm2, xmm2
    comiss xmm1, xmm2
    je done
    sqrtps xmm1, xmm1
    divps xmm0, xmm1
    done:
    v3store [rcx], xmm0
    ret
v3_normalize endp

The length is computed through the dot product, which is coming next (dpps), and a zero vector, which has no direction to keep, is handed back unchanged rather than divided by zero.

The maths is SSE: an xmm register holds four floats, called lanes, and an instruction ending in ps ("packed single") works on all four at once, where one ending in ss ("scalar single") works on the lowest lane only. v3load and v3store are macros from math.asm that move a vec3's twelve bytes into lanes x, y and z of a register, with 0 in the fourth, and back. So divps divides x, y and z by the length in one instruction. The procedures take vectors and matrices by address, in the usual rcx, rdx, r8, and write their results through an out address; a float result comes back in xmm0.

Vector-vector multiplication

There is no single obvious way to multiply two vectors. Multiplying them component by component exists (HLSL's * on two float3s does that, and v3_mul is ours, a single mulps), and we will use it for colours, but geometrically the two products that matter are the dot product, written \(\bar{v} \cdot \bar{k}\), and the cross product, written \(\bar{v} \times \bar{k}\).

Dot product

The dot product of two vectors is a single number: their two lengths multiplied together, times the cosine of the angle \(\theta\) between them.

\[\bar{v} \cdot \bar{k} = ||\bar{v}|| \cdot ||\bar{k}|| \cdot \cos \theta\]

For unit vectors both lengths are 1 and the formula collapses to \(\hat{v} \cdot \hat{k} = \cos \theta\). That is what makes it so handy. The cosine is 1 when the vectors point the same way, 0 when they are at right angles (orthogonal), and -1 when they point in opposite directions, so one dot product tells us how much two directions agree. Diffuse lighting, in a few chapters, is exactly this number.

Computing it is cheap: multiply matching components and add the results. Two unit vectors in the xy plane, for example:

\[\begin{pmatrix} \color{red}{0.6} \\ \color{green}{0.8} \\ \color{blue}0 \end{pmatrix} \cdot \begin{pmatrix} \color{red}{0.8} \\ \color{green}{0.6} \\ \color{blue}0 \end{pmatrix} = ({\color{red}{0.6 \cdot 0.8}}) + ({\color{green}{0.8 \cdot 0.6}}) + ({\color{blue}{0 \cdot 0}}) = 0.96\]

and the inverse cosine, \(\cos^{-1}(0.96)\), says they are about 16.3 degrees apart. For vectors that are not unit length we would first divide by both lengths. SSE4.1 has the dot product as one instruction, dpps, so ours is short:

; rcx: a, rdx: b -> xmm0: a . b
align 16
v3_dot proc
    v3load xmm0, [rcx]
    v3load xmm1, [rdx]
    dpps xmm0, xmm1, 71h        ; multiply x, y, z; sum into lane 0
    ret
v3_dot endp

The 71h is a mask: its high four bits (7) choose which lanes are multiplied, x, y and z, and its low four (1) which lanes receive the sum, only the first, which is where a float result belongs. v3_normalize above uses 7Fh to get the sum in every lane, ready to divide all three components by.

HLSL has it built in as dot.

Cross product

The cross product only exists in three dimensions. It takes two vectors that are not parallel and returns a third that is perpendicular to both. If the two inputs are already perpendicular to each other, the three together form a set of axes, which is exactly how we will build the camera's frame in a later chapter.

Two orthogonal vectors and their cross product, perpendicular to both (LearnOpenGL's diagram)

The formula has no obvious picture behind it without some linear algebra, so it is fine to treat it as a recipe:

\[\begin{pmatrix} \color{red}{A_x} \\ \color{green}{A_y} \\ \color{blue}{A_z} \end{pmatrix} \times \begin{pmatrix} \color{red}{B_x} \\ \color{green}{B_y} \\ \color{blue}{B_z} \end{pmatrix} = \begin{pmatrix} \color{green}{A_y} \color{blue}{B_z} - \color{blue}{A_z} \color{green}{B_y} \\ \color{blue}{A_z} \color{red}{B_x} - \color{red}{A_x} \color{blue}{B_z} \\ \color{red}{A_x} \color{green}{B_y} - \color{green}{A_y} \color{red}{B_x} \end{pmatrix}\]
; rcx: out, rdx: a, r8: b. (a.y b.z - a.z b.y, a.z b.x - a.x b.z, a.x b.y - a.y b.x)
align 16
v3_cross proc
    v3load xmm0, [rdx]
    v3load xmm1, [r8]
    movaps xmm2, xmm0
    movaps xmm3, xmm1
    shufps xmm0, xmm0, 0C9h     ; a.yzx
    shufps xmm1, xmm1, 0D2h     ; b.zxy
    mulps xmm0, xmm1
    shufps xmm2, xmm2, 0D2h     ; a.zxy
    shufps xmm3, xmm3, 0C9h     ; b.yzx
    mulps xmm2, xmm3
    subps xmm0, xmm2
    v3store [rcx], xmm0
    ret
v3_cross endp

The formula's left-hand products all pair a component of \(A\) with a different one of \(B\), in a rotating pattern, and so do the right-hand ones. shufps reorders the lanes of a register, so two shuffles line up \((A_y, A_z, A_x)\) against \((B_z, B_x, B_y)\), one mulps makes all three left-hand products, two more shuffles and a mulps make the right-hand ones, and a subps finishes all three components together.

Try it on the x and y axes: \((1, 0, 0) \times (0, 1, 0) = (0, 0, 1)\), the z axis. The order matters: \(\bar{B} \times \bar{A}\) points the opposite way. Which way "x cross y" points is what makes a coordinate system right-handed, and ours is: +x to the right, +y up, +z out of the screen towards us. We come back to that in Coordinate Systems.

Matrices

A matrix is a rectangular grid of numbers. Each number is an element, found by its row and its column, in that order. This one has two rows and three columns, so it is a 2x3 matrix:

\[\begin{bmatrix} 7 & 0 & 2 \\ 1 & 3 & 5 \end{bmatrix}\]

Element (2, 3), second row and third column, is 5. Note the order: row first, the opposite of the (x, y) habit from graphs. Matrices themselves are nothing more than this grid. What makes them interesting is a handful of operations defined on them.

Addition and subtraction

Two matrices of the same size are added or subtracted element by element, each with its counterpart in the same row and column. Matrices of different sizes cannot be added at all.

\[\begin{bmatrix} \color{red}3 & \color{red}1 \\ \color{green}0 & \color{green}5 \end{bmatrix} + \begin{bmatrix} \color{red}2 & \color{red}2 \\ \color{green}4 & \color{green}1 \end{bmatrix} = \begin{bmatrix} \color{red}5 & \color{red}3 \\ \color{green}4 & \color{green}6 \end{bmatrix}, \qquad \begin{bmatrix} \color{red}3 & \color{red}1 \\ \color{green}0 & \color{green}5 \end{bmatrix} - \begin{bmatrix} \color{red}2 & \color{red}2 \\ \color{green}4 & \color{green}1 \end{bmatrix} = \begin{bmatrix} \color{red}1 & -\color{red}1 \\ -\color{green}4 & \color{green}4 \end{bmatrix}\]

Matrix-scalar products

Multiplying a matrix by a scalar multiplies every element by it, which is where the word "scalar" comes from: it scales everything by the same amount.

\[{\color{green}3} \cdot \begin{bmatrix} 1 & 0 \\ 2 & 4 \end{bmatrix} = \begin{bmatrix} 3 & 0 \\ 6 & 12 \end{bmatrix}\]

Matrix-matrix multiplication

Multiplying two matrices is the operation everything else depends on, and the one that takes a little practice. Two rules come first:

Each element of the result pairs one row of the left matrix with one column of the right matrix. Walk along the row and down the column together, multiply the pairs of numbers you meet, and add them up. The row you used is the row of the result element, and the column you used is its column. LearnOpenGL's diagram colours the pairings:

A 2x2 matrix product with the row and column used for two result elements highlighted (LearnOpenGL's diagram)

Written out:

\[\begin{bmatrix} \color{red}1 & \color{red}2 \\ \color{green}3 & \color{green}4 \end{bmatrix} \cdot \begin{bmatrix} \color{blue}5 & \color{purple}6 \\ \color{blue}7 & \color{purple}8 \end{bmatrix} = \begin{bmatrix} \color{red}1 \cdot \color{blue}5 + \color{red}2 \cdot \color{blue}7 & \color{red}1 \cdot \color{purple}6 + \color{red}2 \cdot \color{purple}8 \\ \color{green}3 \cdot \color{blue}5 + \color{green}4 \cdot \color{blue}7 & \color{green}3 \cdot \color{purple}6 + \color{green}4 \cdot \color{purple}8 \end{bmatrix} = \begin{bmatrix} 19 & 22 \\ 43 & 50 \end{bmatrix}\]

The result has as many rows as the left matrix and as many columns as the right one. Every element is a dot product, of a row with a column, which is one more reason the dot product keeps turning up. Here is the same thing for 4x4 matrices, the only size our lessons use, in the form SSE likes best:

; rcx: out, rdx: a, r8: b -> out = a * b
;
; Row i of the product is a[i][0] * b.row0 + a[i][1] * b.row1 + a[i][2] * b.row2 + a[i][3] * b.row3.
; b is read into registers first and each row of a is read before its row of out is written, so
; out may be a or b.
align 16
m4_mul proc
    movups xmm2, [r8]
    movups xmm3, [r8 + 16]
    movups xmm4, [r8 + 32]
    movups xmm5, [r8 + 48]
    for row, <0, 16, 32, 48>
        movss xmm0, dword ptr [rdx + row]
        splat xmm0
        mulps xmm0, xmm2
        movss xmm1, dword ptr [rdx + row + 4]
        splat xmm1
        mulps xmm1, xmm3
        addps xmm0, xmm1
        movss xmm1, dword ptr [rdx + row + 8]
        splat xmm1
        mulps xmm1, xmm4
        addps xmm0, xmm1
        movss xmm1, dword ptr [rdx + row + 12]
        splat xmm1
        mulps xmm1, xmm5
        addps xmm0, xmm1
        movups [rcx + row], xmm0
    endm
    ret
m4_mul endp

It is the same sum, grouped differently. Rather than one dot product per element, it builds a whole row of the result at once: row \(i\) of the product is row 0 of b times \(a_{i0}\), plus row 1 of b times \(a_{i1}\), and so on, which you can check against the formula above. Each row of b is four floats, one movups into one register, and splat copies one element of a into all four lanes, so each of the four terms is a single mulps. The for ... endm is not a loop at run time: it is MASM's repeat block, which writes its body out four times, with row standing for 0, 16, 32 and 48, the byte offsets of the four rows. Doing a couple of products by hand is still the fastest way to make the pattern stick; after that, let the computer do it.

Matrix-vector multiplication

A vector with N components is really an Nx1 matrix: N rows, one column. So a matrix with N columns can multiply it, and the result is another vector. That is the whole point of this chapter. A great many useful operations, moving, turning, stretching, and later projecting, can be packed into a matrix, and multiplying a vector by that matrix applies the operation to it.

Identity matrix

The plainest 4x4 matrix is the identity matrix: ones on the diagonal, zeros everywhere else. Multiplying by it changes nothing:

\[\begin{bmatrix} \color{red}1 & \color{red}0 & \color{red}0 & \color{red}0 \\ \color{green}0 & \color{green}1 & \color{green}0 & \color{green}0 \\ \color{blue}0 & \color{blue}0 & \color{blue}1 & \color{blue}0 \\ \color{purple}0 & \color{purple}0 & \color{purple}0 & \color{purple}1 \end{bmatrix} \cdot \begin{bmatrix} 5 \\ 6 \\ 7 \\ 1 \end{bmatrix} = \begin{bmatrix} \color{red}1 \cdot 5 \\ \color{green}1 \cdot 6 \\ \color{blue}1 \cdot 7 \\ \color{purple}1 \cdot 1 \end{bmatrix} = \begin{bmatrix} 5 \\ 6 \\ 7 \\ 1 \end{bmatrix}\]

Each result element is a row of the matrix dotted with the vector, and each row has a single 1 that picks out one component. A transformation that does nothing sounds pointless, but it is where every other transformation starts: take the identity and change a few elements.

; rcx: out
align 16
m4_identity proc
    xorps xmm0, xmm0
    movups [rcx], xmm0
    movups [rcx + 16], xmm0
    movups [rcx + 32], xmm0
    movups [rcx + 48], xmm0
    mov eax, 3F800000h          ; 1.0
    mov [rcx + 0], eax
    mov [rcx + 20], eax
    mov [rcx + 40], eax
    mov [rcx + 60], eax
    ret
m4_identity endp

Four 16-byte stores of zero clear the matrix, and then the diagonal gets 1.0, written by its bits, 3F800000h. Elements 0, 5, 10 and 15 are the diagonal, at byte offsets 0, 20, 40 and 60, because a mat4 keeps its 16 floats in m, row after row: element (row, column) is m[row * 4 + col], four bytes each. We will see why that matters once the matrix travels to a shader.

Scaling

Scaling a vector changes its length while keeping its direction. We can scale each axis by its own factor: scaling (3, 2) by 0.5 along x and by 2 along y gives (1.5, 4), narrower and taller. When the factors differ, as here, it is a non-uniform scale; when they are all the same it is a uniform scale.

Vector (3, 2) scaled by (0.5, 2) becomes (1.5, 4) (LearnOpenGL's diagram)

The identity matrix already multiplies each component by the 1 on its row. Replace those ones with other factors and each component is multiplied by those instead:

\[\begin{bmatrix} \color{red}{S_x} & \color{red}0 & \color{red}0 & \color{red}0 \\ \color{green}0 & \color{green}{S_y} & \color{green}0 & \color{green}0 \\ \color{blue}0 & \color{blue}0 & \color{blue}{S_z} & \color{blue}0 \\ \color{purple}0 & \color{purple}0 & \color{purple}0 & \color{purple}1 \end{bmatrix} \cdot \begin{pmatrix} x \\ y \\ z \\ 1 \end{pmatrix} = \begin{pmatrix} \color{red}{S_x} \cdot x \\ \color{green}{S_y} \cdot y \\ \color{blue}{S_z} \cdot z \\ 1 \end{pmatrix}\]
; rcx: out, rdx: s (vec3) -> a scale by s
align 16
m4_scale proc
    mov r8, rdx
    call m4_identity
    mov eax, [r8].vec3.x
    mov [rcx + 0], eax
    mov eax, [r8].vec3.y
    mov [rcx + 20], eax
    mov eax, [r8].vec3.z
    mov [rcx + 40], eax
    ret
m4_scale endp

It starts from the identity, by calling m4_identity on the same out, still in rcx. That works because we wrote m4_identity and know it touches only xmm0, eax and memory; the scale vector's address is moved to r8 first all the same, since rdx is not ours to keep across a call. The factors are copied as four-byte patterns through eax: moving a float needs no floating-point instruction.

The fourth diagonal element stays 1. The fourth component of the vector, w, has a job of its own, which the next transformation explains.

Translation

Translation means moving: adding an offset vector to a position. A 3x3 matrix cannot do that, because each of its result components is only a weighted sum of x, y and z; there is no room for a constant. This is the reason our vectors have a fourth component. Give every position a w of 1, put the offset in the last column of the matrix, and the last column gets multiplied by that 1 and added on:

\[\begin{bmatrix} \color{red}1 & \color{red}0 & \color{red}0 & \color{red}{T_x} \\ \color{green}0 & \color{green}1 & \color{green}0 & \color{green}{T_y} \\ \color{blue}0 & \color{blue}0 & \color{blue}1 & \color{blue}{T_z} \\ \color{purple}0 & \color{purple}0 & \color{purple}0 & \color{purple}1 \end{bmatrix} \cdot \begin{pmatrix} x \\ y \\ z \\ 1 \end{pmatrix} = \begin{pmatrix} x + \color{red}{T_x} \\ y + \color{green}{T_y} \\ z + \color{blue}{T_z} \\ 1 \end{pmatrix}\]
; rcx: out, rdx: t (vec3) -> a translation by t
align 16
m4_translate proc
    mov r8, rdx
    call m4_identity
    mov eax, [r8].vec3.x
    mov [rcx + 12], eax
    mov eax, [r8].vec3.y
    mov [rcx + 28], eax
    mov eax, [r8].vec3.z
    mov [rcx + 44], eax
    ret
m4_translate endp

Elements 3, 7 and 11, at byte offsets 12, 28 and 44, are the last column of rows 0, 1 and 2, exactly where the formula puts \(T_x\), \(T_y\) and \(T_z\).

Homogeneous coordinates. The w component makes our vectors homogeneous coordinates. To turn one back into an ordinary 3D point we divide x, y and z by w. While w is 1 that changes nothing, which is why we rarely notice it. It earns its keep twice: it lets a matrix translate, and in the next chapter it carries the depth that perspective divides by. A vector with w = 0 is unaffected by the last column, so it can be rotated and scaled but never moved: that is exactly right for a direction vector, which has no position to move.

Rotation

Rotations take a little trigonometry. An angle can be measured in degrees, 360 to a full turn, or in radians, \(2\pi\) to a full turn. People think in degrees, but sinf, cosf and every rotation function in math.asm work in radians, so we convert with radians, which multiplies by \(\pi / 180\), kept as a constant:

; xmm0: degrees -> xmm0: radians
align 16
radians proc
    mulss xmm0, math_degrees_to_radians
    ret
radians endp

A quarter turn is 90 degrees, or \(\pi/2\) radians; a fifth of a turn is 72 degrees, as between \(\bar{k}\) and \(\bar{v}\) here:

Vector v rotated 72 degrees from k about the axis (0, 0, 1) (LearnOpenGL's diagram)

In 3D a rotation is an angle plus an axis to turn around. A flat shape in the xy plane, like our textured square, spins on the screen when rotated about the z axis. Following the right-hand rule, a positive angle turns counter-clockwise when the axis points at you. The rotations about the three main axes, with \(\theta\) the angle, are:

\[R_x = \begin{bmatrix} 1 & 0 & 0 & 0 \\ 0 & \cos \theta & -\sin \theta & 0 \\ 0 & \sin \theta & \cos \theta & 0 \\ 0 & 0 & 0 & 1 \end{bmatrix} \quad R_y = \begin{bmatrix} \cos \theta & 0 & \sin \theta & 0 \\ 0 & 1 & 0 & 0 \\ -\sin \theta & 0 & \cos \theta & 0 \\ 0 & 0 & 0 & 1 \end{bmatrix} \quad R_z = \begin{bmatrix} \cos \theta & -\sin \theta & 0 & 0 \\ \sin \theta & \cos \theta & 0 & 0 \\ 0 & 0 & 1 & 0 \\ 0 & 0 & 0 & 1 \end{bmatrix}\]

To rotate about some other axis you could chain these, x then y then z, but chained axis rotations suffer from gimbal lock: at certain angles two of the axes line up and one degree of freedom is lost. It is better to rotate about the axis we actually want in one step. For a unit axis \((\color{red}{R_x}, \color{green}{R_y}, \color{blue}{R_z})\) that matrix is:

\[\begin{bmatrix} \cos \theta + \color{red}{R_x}^2(1 - \cos \theta) & \color{red}{R_x}\color{green}{R_y}(1 - \cos \theta) - \color{blue}{R_z} \sin \theta & \color{red}{R_x}\color{blue}{R_z}(1 - \cos \theta) + \color{green}{R_y} \sin \theta & 0 \\ \color{green}{R_y}\color{red}{R_x} (1 - \cos \theta) + \color{blue}{R_z} \sin \theta & \cos \theta + \color{green}{R_y}^2(1 - \cos \theta) & \color{green}{R_y}\color{blue}{R_z}(1 - \cos \theta) - \color{red}{R_x} \sin \theta & 0 \\ \color{blue}{R_z}\color{red}{R_x}(1 - \cos \theta) - \color{green}{R_y} \sin \theta & \color{blue}{R_z}\color{green}{R_y}(1 - \cos \theta) + \color{red}{R_x} \sin \theta & \cos \theta + \color{blue}{R_z}^2(1 - \cos \theta) & 0 \\ 0 & 0 & 0 & 1 \end{bmatrix}\]

Set the axis to (0, 0, 1) and it reduces to \(R_z\) above. m4_rotate writes this matrix element by element, with c the cosine, s the sine and t for \(1 - \cos \theta\), all three kept in locals. Here is its start and the first two elements; the other seven follow the same pattern:

; rcx: out, xmm1: angle in radians, r8: axis (vec3)
;
; A rotation of `angle` about `axis`, counter-clockwise when looking down the axis towards the
; origin.
align 16
m4_rotate proc out_ref:qword, angle:qword, axis_ref:qword
    local a:vec3, c:real4, s:real4, t:real4

    movss real4 ptr angle, xmm1 ; the prologue homed rdx here, not xmm1
    lea rcx, a
    mov rdx, axis_ref
    call v3_normalize
    movss xmm0, real4 ptr angle
    call cosf
    movss c, xmm0
    movss xmm1, math_one
    subss xmm1, xmm0
    movss t, xmm1
    movss xmm0, real4 ptr angle
    call sinf
    movss s, xmm0

    mov rcx, out_ref
    call m4_identity
    ; r.m[0] = c + a.x * a.x * t
    movss xmm0, a.x
    mulss xmm0, a.x
    mulss xmm0, t
    addss xmm0, c
    movss real4 ptr [rcx + 0], xmm0
    ; r.m[1] = a.x * a.y * t - a.z * s
    movss xmm0, a.x
    mulss xmm0, a.y
    mulss xmm0, t
    movss xmm1, a.z
    mulss xmm1, s
    subss xmm0, xmm1
    movss real4 ptr [rcx + 4], xmm0
    ; ...
    ret
m4_rotate endp

The formula needs a unit axis, so the function normalizes whatever it is given, into the local a.

Look at where the angle arrives. It is the second argument, so by the Win64 rule it comes in xmm1, the xmm register of the second position, even though the first argument, out, is an integer in rcx. Each argument position owns one integer and one xmm register, and an argument uses whichever suits its type. MASM's proc doesn't know which arguments are floats, and the prologue stores rdx into the angle's slot on the stack, as it would for any second argument, so the procedure's first instruction overwrites that slot with xmm1, and from then on angle means the float. Then the cosine and sine come from math.asm's cosf and sinf, which hand the angle to the x87 unit's fcos and fsin instructions: there is no C library to call.

Even this form can be driven into gimbal lock if the angles come from three separate Euler angles; the cure for that is quaternions, a different representation of rotations that we will not need in these lessons.

Combining matrices

Here is the real reason to use matrices: several transformations multiply together into one matrix, and that single matrix then does all of them at once, for every vertex, for the price of one. Suppose we want to halve a shape's size and then move it by (2, 1, 0). The translation matrix times the scale matrix is:

\[T \cdot S = \begin{bmatrix} \color{red}1 & \color{red}0 & \color{red}0 & \color{red}2 \\ \color{green}0 & \color{green}1 & \color{green}0 & \color{green}1 \\ \color{blue}0 & \color{blue}0 & \color{blue}1 & \color{blue}0 \\ \color{purple}0 & \color{purple}0 & \color{purple}0 & \color{purple}1 \end{bmatrix} \cdot \begin{bmatrix} \color{red}{0.5} & \color{red}0 & \color{red}0 & \color{red}0 \\ \color{green}0 & \color{green}{0.5} & \color{green}0 & \color{green}0 \\ \color{blue}0 & \color{blue}0 & \color{blue}{0.5} & \color{blue}0 \\ \color{purple}0 & \color{purple}0 & \color{purple}0 & \color{purple}1 \end{bmatrix} = \begin{bmatrix} \color{red}{0.5} & \color{red}0 & \color{red}0 & \color{red}2 \\ \color{green}0 & \color{green}{0.5} & \color{green}0 & \color{green}1 \\ \color{blue}0 & \color{blue}0 & \color{blue}{0.5} & \color{blue}0 \\ \color{purple}0 & \color{purple}0 & \color{purple}0 & \color{purple}1 \end{bmatrix}\]

and applied to a position:

\[\begin{bmatrix} \color{red}{0.5} & \color{red}0 & \color{red}0 & \color{red}2 \\ \color{green}0 & \color{green}{0.5} & \color{green}0 & \color{green}1 \\ \color{blue}0 & \color{blue}0 & \color{blue}{0.5} & \color{blue}0 \\ \color{purple}0 & \color{purple}0 & \color{purple}0 & \color{purple}1 \end{bmatrix} \cdot \begin{pmatrix} x \\ y \\ z \\ 1 \end{pmatrix} = \begin{pmatrix} \color{red}{0.5x + 2} \\ \color{green}{0.5y + 1} \\ \color{blue}{0.5z} \\ 1 \end{pmatrix}\]

Halved, then moved, as we wanted. Notice which way round that is. In \(T \cdot S \cdot \bar{v}\) the matrix nearest the vector, \(S\), touches it first, so a product of transformations is read right to left. Multiply them the other way, \(S \cdot T\), and the translation happens first and then gets halved along with everything else: the shape lands at (1, 0.5, 0) instead. Because of this, the usual order is scale first, then rotate, then translate, which in a product reads \(T \cdot R \cdot S\): scaling and rotating then happen around the shape's own centre, before it is moved away from the origin.

In practice

Neither Direct3D nor HLSL gives the CPU side any vector or matrix types, so the program needs its own. LearnOpenGL uses GLM. The usual choice for Direct3D in C++ is Microsoft's DirectXMath, but it is a C++ library built around SIMD types, and it treats vectors as rows, multiplying \(\bar{v} \cdot M\), so every product in LearnOpenGL would have to be written the other way round. Our lessons instead use includes/math.asm, SSE procedures that keep LearnOpenGL's conventions, as its opening comment says:

;   * right-handed world: +x right, +y up, the camera looks down -z
;   * column vectors: a point is transformed as `M * p`, so `T * R * S` scales first and
;     translates last
;   * clip-space depth runs 0..1, which is D3D's range (GL's is -1..1)

The first and last points belong to the next two chapters. The second is what we just worked through: a matrix times a column vector, read right to left. Everything in this chapter is a procedure in math.asm. Where GLM writes a + b we call v3_add with three addresses, the result's and the two operands', and A * B is invoke m4_mul, ADDR result, ADDR A, ADDR B.

One difference from GLM is worth knowing before reading LearnOpenGL's code side by side with ours. GLM's glm::translate(trans, v) takes an existing matrix and returns it multiplied by a translation, so LearnOpenGL builds a transformation in steps:

glm::mat4 trans = glm::mat4(1.0f);
trans = glm::translate(trans, glm::vec3(0.5f, -0.5f, 0.0f));
trans = glm::rotate(trans, (float)glfwGetTime(), glm::vec3(0.0f, 0.0f, 1.0f));

Our m4_translate and m4_rotate just write the matrix, and the products are separate calls: the same transformation is a translation matrix, a rotation matrix, and m4_mul of the two. Both mean \(T \cdot R\); ours just puts the multiplication where you can see it. As a quick check, a translation by (1, 1, 0) from m4_translate, applied to the point (1, 0, 0, 1) with m4_mul_v4, gives (2, 1, 0, 1):

; rcx: out, rdx: m, r8: v -> out = m * v
align 16
m4_mul_v4 proc
    movups xmm4, [r8]
    movups xmm0, [rdx]
    mulps xmm0, xmm4
    movups xmm1, [rdx + 16]
    mulps xmm1, xmm4
    movups xmm2, [rdx + 32]
    mulps xmm2, xmm4
    movups xmm3, [rdx + 48]
    mulps xmm3, xmm4
    haddps xmm0, xmm1           ; row sums, two lanes at a time
    haddps xmm2, xmm3
    haddps xmm0, xmm2
    movups [rcx], xmm0
    ret
m4_mul_v4 endp

(2, 1, 0), with w still 1. m4_mul_v4 is matrix-times-vector: each component of the result is one row of the matrix dotted with the vector. Each row is multiplied by the vector lane by lane, and three rounds of haddps, which adds neighbouring lanes, sum the four rows' products into one register, a component in each lane.

Getting the matrix to the shader

The vertex shader needs the matrix, and per-draw values reach shaders through a constant buffer, as the tint did in Shaders. HLSL's matrix type is float4x4, and mul multiplies a matrix by a vector:

// Read matrices row by row, as rin stores them; mul(M, v) is then M * v.
#pragma pack_matrix(row_major)

cbuffer object : register(b0)
{
    float4x4 transform;
};
...
vs_out vs_main(float3 position : POSITION, float2 uv : TEXCOORD)
{
    vs_out o;
    o.position = mul(transform, float4(position, 1.0));
    o.uv = uv;
    return o;
}

The position arrives as a float3 and we give it a w of 1 before multiplying, since it is a point that should be translated. The result is what the shader returns as SV_Position, so the rasterizer sees the moved square. The pixel shader is unchanged from Textures: the crate with 20% of the face mixed in.

The first line, the #pragma, is the one Direct3D detail in this chapter, and forgetting it is a classic. A mat4 is 16 floats, and the CPU and the shader have to agree on what order they are in. We store them row by row, as we saw with m4_identity. (The shaders are shared with the rin edition, hence the comment's "as rin stores them"; math.asm stores them the same way.) HLSL, by default, expects a matrix in a constant buffer to be stored column by column (column-major), and would read our first row as its first column: it would see the transpose of our matrix, every element mirrored across the diagonal. The translation in the last column would land in the bottom row, where it feeds into w instead of moving anything, and the square would come out warped and turning the wrong way. #pragma pack_matrix(row_major) tells the compiler our matrices are row-major, after which mul(transform, v) means exactly \(M \cdot \bar{v}\), as in our maths and as transform * v does in GLSL.

OpenGL has the same question in another form. GLM stores matrices column by column and GLSL reads them that way, so LearnOpenGL passes GL_FALSE for the transpose argument of glUniformMatrix4fv. Either convention works as long as both sides agree; every shader in our lessons that reads a matrix starts with this pragma. You may also see mul(v, M) in Direct3D code elsewhere: that treats the vector as a row and expects matrices built the transposed way, the DirectXMath convention. We never use that form.

On the CPU side, a structure mirrors the constant buffer:

object_constants struct
    transform mat4 <>
object_constants ends

A mat4 is 64 bytes, four of HLSL's 16-byte registers, so the buffer's size is already a multiple of 16 as constant buffers require. The buffer is made once with create_constant_buffer (D3D11_USAGE_DYNAMIC, CPU-writable) and bound to register b0 every frame with invoke bind_constants, 0, constants, which binds it for the vertex, geometry and pixel stages alike:

; rcx: register (b0, b1, ...), rdx: buffer
;
; The same buffer in the same register for the vertex, geometry and pixel stages.
align 16
bind_constants proc slot:qword, buffer:qword
    vcall context, ID3D11DeviceContext_VSSetConstantBuffers, slot, 1, ADDR buffer
    vcall context, ID3D11DeviceContext_GSSetConstantBuffers, slot, 1, ADDR buffer
    vcall context, ID3D11DeviceContext_PSSetConstantBuffers, slot, 1, ADDR buffer
    ret
bind_constants endp

ADDR buffer works because the prologue stored the argument in its stack slot: the methods want an array of buffers, and that slot is an array of one.

Putting it together

The lesson draws the textured square twice, from the same vertex and index buffers, each time with its own matrix. Because the matrices change with time, they are rebuilt every frame inside the render loop. The matrices and vectors are globals in the data section: translation, rotation, scale_ and aspect are mat4s, bottom_right, top_left and z_axis are vec3 constants such as bottom_right vec3 <0.5, -0.5, 0.0>, and c is the object_constants that is copied into the buffer:

; transform = aspect * translate(0.5, -0.5, 0) * rotate(time, z)
invoke m4_translate, ADDR translation, ADDR bottom_right
lea rcx, rotation
movss xmm1, current_frame
lea r8, z_axis
call m4_rotate
invoke m4_mul, ADDR c.transform, ADDR translation, ADDR rotation
invoke m4_mul, ADDR c.transform, ADDR aspect, ADDR c.transform
invoke update_buffer, constants, ADDR c, sizeof object_constants
vcall context, ID3D11DeviceContext_DrawIndexed, 6, 0, 0

; transform = aspect * translate(-0.5, 0.5, 0) * scale(|sin(time)|)
movss xmm0, current_frame
call sinf
andps xmm0, math_abs_mask
movss pulse.x, xmm0
movss pulse.y, xmm0
movss pulse.z, xmm0
invoke m4_translate, ADDR translation, ADDR top_left
invoke m4_scale, ADDR scale_, ADDR pulse
invoke m4_mul, ADDR c.transform, ADDR translation, ADDR scale_
invoke m4_mul, ADDR c.transform, ADDR aspect, ADDR c.transform
invoke update_buffer, constants, ADDR c, sizeof object_constants
vcall context, ID3D11DeviceContext_DrawIndexed, 6, 0, 0

m4_rotate is called without invoke: its angle has to be in xmm1, which invoke knows nothing about, so the three arguments are put in place by hand, rcx, xmm1 and r8, and the procedure is simply called. Since m4_mul may write over one of its inputs, the second product reuses c.transform in place. And \(|\sin t|\) costs one instruction: andps with math_abs_mask clears the sign bit of every lane.

Read each one from the right. The first square is rotated about z by current_frame radians, the seconds since start, so it turns about once every six seconds; only then is it translated to the bottom right. It spins in place, around its own centre, because it is rotated while that centre is still at the origin. The second square is scaled by \(|\sin t|\), shrinking to nothing and growing back, and then moved to the top left. LearnOpenGL leaves that second square as an exercise; our lesson draws both. The absolute value keeps the scale positive; a plain sine would also work but would flip the square through itself every other cycle.

Between the two draws we write the constant buffer again. update_buffer maps it with D3D11_MAP_WRITE_DISCARD, which hands us fresh memory each time, so the first draw still sees the first matrix even though the GPU has not drawn it yet when we write the second.

Then there is aspect, applied last, after everything else. LearnOpenGL does not have it:

; aspect = scale(height / width, 1, 1)
cvtsi2ss xmm1, scr_height
cvtsi2ss xmm0, scr_width
divss xmm1, xmm0
movss pulse.x, xmm1
storef pulse.y, 1.0
storef pulse.z, 1.0
invoke m4_scale, ADDR aspect, ADDR pulse

It doesn't change, so it is made once, before the render loop, borrowing the pulse vector to hold the scale factors.

Clip space runs from -1 to 1 in both x and y, but our window is 1280 by 720 pixels, so one unit of x covers more pixels than one unit of y. Scaling x by 720/1280 makes a unit the same size on screen in both directions, and the squares stay square while they spin. Because it is the leftmost matrix, it also squeezes the translations: the first square's centre ends up at x = 0.28 rather than 0.5. In the next chapter a projection matrix takes over this job.

One container spinning at the bottom right, another scaling at the top left

That is two moving objects without touching a single vertex. A matrix can hold as many transformations as we like, and the vertex shader applies them all with one multiplication; all the CPU uploads each frame is 64 bytes. The full program is here, its shaders here, and the maths library here.

Next we use matrices to set up several coordinate spaces, and take the step into 3D.

Additional resources

Exercises

  1. Swap the order of the first square's matrices so it is translated first and rotated second. Work out on paper what should happen before you run it, then check.
  2. Delete #pragma pack_matrix(row_major) from transformations.hlsl and run the lesson. Explain what you see in terms of the transposed matrix, then put the pragma back and get the same broken picture by passing the matrix through m4_transpose (rcx the result, rdx the matrix, which may be the same) before update_buffer.
  3. Add a third square in the top right that both spins and pulses. Mind the order of the scale and the rotation (does it matter here?) and of the translation.
Credit: this chapter follows LearnOpenGL's Transformations by Joey de Vries, rewritten for Direct3D 11 and x64 assembly. LearnOpenGL's text and code are licensed CC BY-NC 4.0, and so is this page; the wording, code and screenshots here are new, and diagrams marked as LearnOpenGL's are its own.