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
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
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.
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
Multiplication is the one we use most: it keeps the direction and changes the length. math.rasm calls it
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:
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.
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:
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 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 ret, and Win64 asks nothing of it.
xmm register holds four floats, called ps ("packed single") works on all four at once, where one ending in ss ("scalar single") works on the lowest lane only. 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 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 mulps), and we will use it for colours, but geometrically the two products that matter are the
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 (
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. 0x7F to get the sum in every lane, ready to divide all three components by.
HLSL has it built in as
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.
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
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:
- The left matrix must have as many columns as the right matrix has rows. Otherwise the product is not defined.
- The order matters: in general \(A \cdot B \neq B \cdot A\). Multiplication of matrices is not commutative.
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:
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 mulps. rasm's macros have no loops, so the row is a macro of its own, 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
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.
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
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 out, still in rcx. That works because we wrote 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 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
; 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\).
Rotation
Rotations take a little trigonometry. An angle can be measured in degrees, 360 to a full turn, or in math.rasm work in radians, so we convert with 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:
In 3D a rotation is an angle plus an
To rotate about some other axis you could chain these, x then y then z, but chained axis rotations suffer from
Set the axis to (0, 0, 1) and it reduces to \(R_z\) above.
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 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 eax), and its own procedures rely on it. The cosine and sine come from 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
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 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
; 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. 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
// 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 math.rasm stores them the same way.) HLSL, by default, expects a matrix in a constant buffer to be stored column by column (#pragma pack_matrix(row_major) tells the compiler our matrices are mul(transform, v) means exactly \(M \cdot \bar{v}\), as in our maths and as transform * v does in GLSL.
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 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 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)
xmm1, which 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 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.
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.
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
- Essence of Linear Algebra: Grant Sanderson's video series, the clearest visual explanation of what matrices do.
- Matrix Multiplication: an interactive animation of rows meeting columns.
- Per-component math operations: Microsoft's notes on HLSL matrices,
mul, and row- and column-major packing. - LearnOpenGL's Transformations: the OpenGL version of this chapter, with GLM.
Exercises
- 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.
- Delete
#pragma pack_matrix(row_major)fromtransformations.hlsland 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 throughm4_transpose (rcxthe result,rdxthe matrix, which may be the same) beforeupdate_buffer . - 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.