Dev:Source/Mathematics/Math Library

Math Library

There are various math libraries in Blender, the one used in all C code is located in:

source/blender/blenlib/BLI_math.h

Gotchas

Matrix Storage

Matrices are stored in column major order, following OpenGL. Note that this is different than the standard mathematical notation, which is row major. That means Blender matrices are indexed as follows:

element = M[column][row];

| M[0][0] M[1][0] M[2][0] M[3][0] | 
| M[0][1] M[1][1] M[2][1] M[3][1] |
| M[0][2] M[1][2] M[2][2] M[3][2] |
| M[0][3] M[1][3] M[2][3] M[3][3] |

And for example the translation component of a 4x4 transformation matrix is:

translation = M[3];

Note that some of the C++ math libraries use row major convention.

Matrix-Vector Multiplication

Spatial points and vectors are assumed to be column vectors, so that matrix-vector multiplication is written as:

mul_v3_m3v3(a, M, b); // a = M * b

There is also an implicit use of homogenous coordinates when multiplying 4x4 matrices with 3 dimensional vectors, we then assume there is w component with value 1.

mul_v3_m4v3(a, M, b); // a = M * b

| a[0] |   | M[0][0] M[1][0] M[2][0] M[3][0] |  | b[0] |
| a[1] |   | M[0][1] M[1][1] M[2][1] M[3][1] |  | b[1] |
| a[2] | = | M[0][2] M[1][2] M[2][2] M[3][2] |  | b[2] |
| 1.0  |   | M[0][3] M[1][3] M[2][3] M[3][3] |  | 1.0  |

Matrix-Matrix Multiplication

Matrix multiplication follows typical math notation:

mult_m4_m4m4(R, A, B); // R = A * B
mult_m3_m3m4(R, A, B); // R = A * B
mul_m3_m3m3(R, A, B); // R = A * B
mul_serie_m4(R, A, B, 0, 0, 0, 0, 0, 0); // R = A * B
mul_serie_m4(R, A, B, C, D, 0, 0, 0, 0); // R = A * B * C * D

So that:

(A * B) * v = A * (B * v)

There is some inconsistency in the naming (mult_ vs mul_), this is due to a fix for previously wrong argument order.

Quaternion Storage

Quaternions are stored in order (w, x, y, z), e.g.:

float sine = sin(angle);
float cosine = cos(angle);
float quat[4] = {sine, cosine*x, cosine*y, cosine*z};

Abbreviations

Types

• fl = float
• db = double
• v2 = vec2 = vector 2
• v3 = vec3 = vector 3
• v4 = vec4 = vector 4
• qt = quat = quaternion
• dq = dquat = dual quaternion
• m2 = mat2 = matrix 2x2
• m3 = mat3 = matrix 3x3
• m4 = mat4 = matrix 4x4
• eul = euler rotation
• eulO = euler with order

Operations

• sub = subtract
• mul = multiply
• madd = multiply & add
• div = divide
• len = length
• interp = interpolate
• mid = middle