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.rasm, 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.rasm they are plain structures of 32-bit floats, declared as rasm declares any struct, one field per line:

vec3: struct = {
    x: f32
    y: f32
    z: f32
}

with vec2 and vec4 alongside, so z_axis: const 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.rasm 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.rasm:

; rcx: a -> xmm0: |a|
v3_length: proc(a: *const vec3) -> f32 = {
    v3load(xmm0, rcx)
    dpps xmm0, xmm0, 0x71
    sqrtss xmm0, xmm0
    ret
}

; rcx: out, rdx: a. A zero vector stays zero.
v3_normalize: proc(out: *vec3, a: *const vec3) = {
    v3load(xmm0, rdx)
    movaps xmm1, xmm0
    dpps xmm1, xmm1, 0x7F                  ; |a|^2 in every lane
    xorps xmm2, xmm2
    comiss xmm1, xmm2
    je done
    sqrtps xmm1, xmm1
    divps xmm0, xmm1
  done:
    v3store(rcx, xmm0)
    ret
}

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. Neither procedure calls anything, so neither has a frame: a leaf procedure touches the stack only through its ret, and Win64 asks nothing of it.

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.rasm that move a vec3's twelve bytes into lanes x, y and z of a register, with 0 in the fourth, and back (the first is shown below). A macro is text substitution, and it cannot add 8 to an operand it was handed, so it takes a register holding the address; a global goes through lea first, or through its twin v3load_var. 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.
; xmm = vec3 at [base], in lanes x, y, z (w is 0). base is a register: a
; macro cannot add 8 to an operand, so a global goes through lea first, or
; through v3load_var.
v3load: macro(reg, base) = {
    movsd reg, qword ptr [base]
    insertps reg, dword ptr [base + 8], 0x20
}

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
v3_dot: proc(a: *const vec3, b: *const vec3) -> f32 = {
    v3load(xmm0, rcx)
    v3load(xmm1, rdx)
    dpps xmm0, xmm1, 0x71                  ; multiply x, y, z; sum into lane 0
    ret
}

The 0x71 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 0x7F 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)
v3_cross: proc(out: *vec3, a: *const vec3, b: *const vec3) = {
    v3load(xmm0, rdx)
    v3load(xmm1, r8)
    movaps xmm2, xmm0
    movaps xmm3, xmm1
    shufps xmm0, xmm0, 0xC9                ; a.yzx
    shufps xmm1, xmm1, 0xD2                ; b.zxy
    mulps xmm0, xmm1
    shufps xmm2, xmm2, 0xD2                ; a.zxy
    shufps xmm3, xmm3, 0xC9                ; b.yzx
    mulps xmm2, xmm3
    subps xmm0, xmm2
    v3store(rcx, xmm0)
    ret
}

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:

m4_mul_row: macro(row) = {
    movss xmm0, [rdx].mat4.m[row * 4]
    splat(xmm0)
    mulps xmm0, xmm2
    movss xmm1, [rdx].mat4.m[row * 4 + 1]
    splat(xmm1)
    mulps xmm1, xmm3
    addps xmm0, xmm1
    movss xmm1, [rdx].mat4.m[row * 4 + 2]
    splat(xmm1)
    mulps xmm1, xmm4
    addps xmm0, xmm1
    movss xmm1, [rdx].mat4.m[row * 4 + 3]
    splat(xmm1)
    mulps xmm1, xmm5
    addps xmm0, xmm1
    ; the field is an f32, the store is sixteen bytes: the explicit size says so
    movups xmmword ptr [rcx + row * 16], xmm0
}

; rcx: out, rdx: a, r8: b -> out = a * b
;
; 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.
m4_mul: proc(out: *mat4, a: *const mat4, b: *const mat4) = {
    movups xmm2, xmmword ptr [r8]
    movups xmm3, xmmword ptr [r8 + 16]
    movups xmm4, xmmword ptr [r8 + 32]
    movups xmm5, xmmword ptr [r8 + 48]
    m4_mul_row(0)
    m4_mul_row(1)
    m4_mul_row(2)
    m4_mul_row(3)
    ret
}

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, xmm2 to xmm5, and splat copies one element of a into all four lanes, so each of the four terms is a single mulps. rasm's macros have no loops, so the row is a macro of its own, m4_mul_row, written out four times with row standing for 0, 1, 2 and 3; once it is substituted, row * 4 + 1 is a plain number. [rdx].mat4.m[5] is a typed operand through a register: the address in rdx is read as a mat4, and m[5] is its sixth float, the index counting elements, so rasm writes [rdx + 20] and a 4-byte size. 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. Touches xmm0 and eax only.
m4_identity: proc(out: *mat4) = {
    xorps xmm0, xmm0
    movups xmmword ptr [rcx], xmm0
    movups xmmword ptr [rcx + 16], xmm0
    movups xmmword ptr [rcx + 32], xmm0
    movups xmmword ptr [rcx + 48], xmm0
    ; 1.0 as an immediate is its bits. `mov eax, 1.0` would also assemble, but
    ; as a load from the constant pool: a float literal is memory.
    mov eax, 0x3F800000                    ; 1.0
    mov [rcx].mat4.m[0], eax
    mov [rcx].mat4.m[5], eax
    mov [rcx].mat4.m[10], eax
    mov [rcx].mat4.m[15], eax
    ret
}

Four 16-byte stores of zero clear the matrix, and then the diagonal gets 1.0, written by its bits, 0x3F800000. 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.

The comment in the middle points at a rasm rule that matters from here on. A float literal such as 1.0 in an instruction is not an immediate: x64 has no float immediates, so rasm puts the constant in read-only data, once per value, and the operand reads it from there. movss xmm5, 1.0 and mulss xmm0, 0.5 are loads from that pool. When a float has to be an immediate, as in a store of 1.0 into memory, it is written as its bits.

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
m4_scale: proc(out: *mat4, s: *const vec3) = {
    mov r8, rdx
    call m4_identity
    mov eax, [r8].vec3.x
    mov [rcx].mat4.m[0], eax
    mov eax, [r8].vec3.y
    mov [rcx].mat4.m[5], eax
    mov eax, [r8].vec3.z
    mov [rcx].mat4.m[10], eax
    ret
}

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 call is made with no frame at all, no shadow space and rsp 8 off alignment, which Win64 would not allow for a function of anyone else's: it is legal here only because the callee is a leaf of the same file that touches neither the stack nor any aligned memory, and math.rasm says so at m4_translate, since nothing checks it. 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
;
; `call m4_identity` with rsp 8 off alignment and no shadow space: legal
; here, because the callee is a leaf of this file that touches neither the
; stack nor any aligned memory. The same holds for every call to it below.
m4_translate: proc(out: *mat4, t: *const vec3) = {
    mov r8, rdx
    call m4_identity
    mov eax, [r8].vec3.x
    mov [rcx].mat4.m[3], eax
    mov eax, [r8].vec3.y
    mov [rcx].mat4.m[7], eax
    mov eax, [r8].vec3.z
    mov [rcx].mat4.m[11], eax
    ret
}

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.rasm work in radians, so we convert with radians, which multiplies by \(\pi / 180\), kept as a named constant, math_degrees_to_radians: const f32 = 0.0174532925199433:

; xmm0: degrees -> xmm0: radians
radians: proc(degrees: f32) -> f32 = {
    mulss xmm0, math_degrees_to_radians
    ret
}

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\). Here is its start and the first two elements; the other seven follow the same pattern:

rotate_axis: vec3 = {}                     ; m4_rotate's normalised axis

; 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.
; ...
m4_rotate: proc(out: *mat4, angle: f32, axis: *const vec3) = {
    sub rsp, 40                            ; 32 shadow for our calls, and rsp back on 16
    mov [rsp + 48], rcx                    ; out
    movss dword ptr [rsp + 56], xmm1       ; angle
    lea rcx, rotate_axis
    mov rdx, r8
    call v3_normalize
    movss xmm0, dword ptr [rsp + 56]
    call cosf
    movaps xmm4, xmm0                      ; c
    movss xmm5, 1.0
    subss xmm5, xmm0                       ; t = 1 - c
    movss xmm0, dword ptr [rsp + 56]
    call sinf
    movaps xmm3, xmm0                      ; s
    mov rcx, [rsp + 48]
    call m4_identity
    ; r.m[0] = c + a.x * a.x * t
    movss xmm0, rotate_axis.x
    mulss xmm0, rotate_axis.x
    mulss xmm0, xmm5
    addss xmm0, xmm4
    movss [rcx].mat4.m[0], xmm0
    ; r.m[1] = a.x * a.y * t - a.z * s
    movss xmm0, rotate_axis.x
    mulss xmm0, rotate_axis.y
    mulss xmm0, xmm5
    movss xmm1, rotate_axis.z
    mulss xmm1, xmm3
    subss xmm0, xmm1
    movss [rcx].mat4.m[1], xmm0
    ; ...
    add rsp, 40
    ret
}

The formula needs a unit axis, so the function normalizes whatever it is given, into the global rotate_axis, named after its owner as every procedure's data is; its fields are then ordinary operands, rotate_axis.x.

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. The procedure has two values to keep across its calls, out and the angle, and it keeps them in the stack slots its caller reserved for it: after sub rsp, 40, the shadow space above the return address is at [rsp + 48] (the first argument's slot) and [rsp + 56] (the second's, the angle's, although the angle came in xmm1). The cosine, the sine and \(t\) stay in xmm4, xmm3 and xmm5 across the calls to sinf, cosf and m4_identity. Win64 would not promise that, since xmm0 to xmm5 may be changed by any call, but math.rasm states a private convention at its top: those procedures touch only xmm0 (and m4_identity eax), and its own procedures rely on it. The cosine and sine come from cosf and sinf, which hand the angle to the x87 unit's fcos and fsin instructions, through the caller's shadow space, with no frame of their own: 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.rasm, 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.rasm. 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, result&, A&, 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 (vec4), rdx: m, r8: v (vec4) -> out = m * v
m4_mul_v4: proc(out: *vec4, m: *const mat4, v: *const vec4) = {
    movups xmm4, xmmword ptr [r8]
    movups xmm0, xmmword ptr [rdx]
    mulps xmm0, xmm4
    movups xmm1, xmmword ptr [rdx + 16]
    mulps xmm1, xmm4
    movups xmm2, xmmword ptr [rdx + 32]
    mulps xmm2, xmm4
    movups xmm3, xmmword ptr [rdx + 48]
    mulps xmm3, xmm4
    haddps xmm0, xmm1                      ; row sums, two lanes at a time
    haddps xmm2, xmm3
    haddps xmm0, xmm2
    movups xmmword ptr [rcx], xmm0
    ret
}

(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.rasm 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, and the lesson keeps one of it as a global:

object_constants: struct = {
    transform: mat4
}
; ...
c: object_constants[align(16)] = {}

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:

bind_constants_buffer: *ID3D11Buffer = {}  ; the array of one that the Set calls take

; ecx: register (b0, b1, ...), rdx: buffer
;
; The same buffer in the same register for the vertex, geometry and pixel stages.
bind_constants: proc(slot: u32, buffer: *ID3D11Buffer) = {
    push rbx
    sub rsp, 32                            ; 32 shadow; entry 8 + push 8 + 32 lands on 16
    mov ebx, ecx
    mov bind_constants_buffer, rdx
    vcall(context, ID3D11DeviceContextVtbl.VSSetConstantBuffers, rbx, 1, bind_constants_buffer&)
    vcall(context, ID3D11DeviceContextVtbl.GSSetConstantBuffers, rbx, 1, bind_constants_buffer&)
    vcall(context, ID3D11DeviceContextVtbl.PSSetConstantBuffers, rbx, 1, bind_constants_buffer&)
    add rsp, 32
    pop rbx
    ret
}

The methods want an array of buffers, so the buffer is stored into a global that is that array of one, and its address is passed. The slot is moved to rbx because every vcall writes rcx with this before anything else, so rcx cannot carry an argument into one; rbx survives the calls, and the push keeps it for our caller.

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: translation, rotation, scale and aspect are mat4s, bottom_right, top_left and z_axis are constant vec3s initialised where they are declared, and c is the object_constants that is copied into the buffer:

z_axis: const vec3 = { 0.0, 0.0, 1.0 }
bottom_right: const vec3 = { 0.5, -0.5, 0.0 }
top_left: const vec3 = { -0.5, 0.5, 0.0 }

c: object_constants[align(16)] = {}
aspect: mat4 = {}                      ; squeezes x so a square stays square in a wide window
translation: mat4 = {}
rotation: mat4 = {}
; ...
scale: mat4 = {}
pulse: vec3 = {}
; transform = aspect * translate(0.5, -0.5, 0) * rotate(time, z)
invoke(m4_translate, translation&, bottom_right&)
; m4_rotate's angle is its second argument, so Win64 puts
; it in xmm1, the register of its position, and rdx goes unused.
; invoke only knows integer registers, so this call is written out.
; (`invoke(m4_rotate, rotation&, 0, z_axis&)` after the movss would
; also work, at the cost of a pointless `mov rdx, 0`.)
lea rcx, rotation
movss xmm1, current_frame
lea r8, z_axis
call m4_rotate
; c.transform& is the address of a field of a global: c + 0, still a
; link-time constant.
invoke(m4_mul, c.transform&, translation&, rotation&)
invoke(m4_mul, c.transform&, aspect&, c.transform&)
invoke(update_buffer, constants, c&, sizeof(object_constants))
vcall(context, ID3D11DeviceContextVtbl.DrawIndexed, 6, 0, 0)

; transform = aspect * translate(-0.5, 0.5, 0) * scale(|sin(time)|)
movss xmm0, current_frame
call sinf
; |x| is clearing the sign bit. The mask is a typed
; 16-byte const, so this is `andps xmm0, xmmword ptr [rip + math_abs_mask]`
; without the reader seeing `xmmword` anywhere.
andps xmm0, math_abs_mask
movss pulse.x, xmm0
movss pulse.y, xmm0
movss pulse.z, xmm0
invoke(m4_translate, translation&, top_left&)
invoke(m4_scale, scale&, pulse&)
invoke(m4_mul, c.transform&, translation&, scale&)
invoke(m4_mul, c.transform&, aspect&, c.transform&)
invoke(update_buffer, constants, c&, sizeof(object_constants))
vcall(context, ID3D11DeviceContextVtbl.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. That is the rule for every float argument in these lessons: it is set in its xmm register before the call, by hand. 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. The mask is declared [4]const u32[align(16)]: andps with a memory operand faults on an address that is not a multiple of 16, so the alignment is part of its type.

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. Its scale factors are a vec3 of their own, and only x depends on the window, so y and z are written in its initialiser:

aspect_scale: vec3 = { .y = 1.0, .z = 1.0 }
cvtsi2ss xmm1, scr_height
cvtsi2ss xmm0, scr_width
divss xmm1, xmm0
movss aspect_scale.x, xmm1
invoke(m4_scale, aspect&, aspect_scale&)

It doesn't change, so it is made once, before the render loop. scr_width and scr_height are const u32 globals in learn/window.rasm, with storage in read-only data, which is what cvtsi2ss needs: it converts an integer register or memory operand, never an immediate, so the #defines SCR_WIDTH and SCR_HEIGHT would not do here.

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 in rasm. 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.