Complex numbers and quaternions

[jordanhalase]

Motivation

Complex numbers (ℂ) and quaternions (ℍ) often show up in computer graphics for rotations, SLERP interpolation, skeletal animation, FFT ocean simulation, fractal visualization (e.g., Mandelbrot set), procedural textures via noise synthesis, abstract psychedelic visual effects, or GPU-accelerated complex analysis.

Historically, shading languages have not supported explicit complex number types, so computer graphics programmers use the native vec2 and vec4 types in lieu of them. This generally works because complex numbers and quaternions share the same rules as vectors for addition and scalar multiplication.

However, multiplication in ℂ and ℍ is different than for vectors. In shading languages, operators like * and / for vector-vector are defined component-wise, which is wrong for complex-complex or quaternion-quaternion multiplication. As a result, programmers typically implement their own functions, which we will call cmul() and qmul().

This presents immediate issues:

• The programmer must remember to call cmul() and qmul() instead of * and / to ensure proper multiplication for ℂ and ℍ, and use * and / for complex-scalar multiplications
• Mathematical expressions using function calls instead of infix * or / operators are difficult to follow and very quickly lead to "parentheses hell"
• The programmer must remember not to call component-wise exp(), sin() etc. mathematical functions for ℂ and ℍ
• The programmer must remember which active vector-type variables are actually a vector rather than a complex number

The programmer may consider aliasing complex = vec2 to help distinguish them in function signatures, but this offers no type safety. The programmer may consider creating a custom struct complex {...} type, but this is inefficient and loses all */+- operators, making expressions even more difficult to follow.

Proposal

I would like to introduce explicit complex<T> and quat<T> types to the WESL shading language, including their (complex|quat)(f|i|u) aliases, type safety with explicit casts between their vector counterparts, and lowers into plain WGSL vec2<T> and vec4<T> types.

Creating a complex type is exactly like creating a vector type.

let z = complex<f32>(3f, 4f); // Can also use complexf()
let q = quat<f32>(3f, 2f, 1f, 4f); // Can also use quatf()

Complex types can be swizzled just like their corresponding vector types. A swizzle on a complex type produces a vector type, or scalar type for a single swizzle.

let z = complexf(3f, 4f);
let v: vec2<f32> = z.xy; // z.xy is vec2<f32>

For complex<T> the x component is the real component and y is the imaginary component. For quat<T>, xyz are the ijk components and w is the real component.

Mathematically, the quaternions are a superset of the complex numbers, however, their layout in computer memory is usually different. A quaternion can be created from a complex number z via:

let q = quatf(z.y, 0, 0, z.x);

It is an error to use a complex<T> with a quat<T>. Likewise, it is an error to use a complex<T> with a vec2<T> or a quat<T> with a vec4<T>.

⚠️ Explicit non-goals

• No constants, so no PI, TWOPI, TAU, EULER, etc., which even means...
• ...no complex unit J. This proposal aims to be minimal and efficient. Zero-cost de-sugaring 3f + 4f*J would require multiple steps and intermediate abstract types for debatably minimal ergonomic gain, and the use of + and * only to be elided can be confusing. Please use complexf(3f, 4f).
• No algorithms, so no SLERP, no FFT, no quaternions from euler angles, no rotation matrices from quaternions, etc.

This extension would provide basic complex number support to WESL and WGSL to become the foundation for the algorithms above to be easier implemented and with more type safety.

TBD

Infix multiplication and division

My primary motivation for this outside of vec/complex type safety is to introduce infix * and / to the proposed complex<T> and quat<T>, because larger complex expressions become very un-ergonomic to type under a sea of cmul() calls.

I realize this may be controversial, but I hope to at least get you on-board with overloading * and / just for the proposed complex/quat types. In the meantime, we can treat complex * complex and quat * quat as an error to stop the programmer from accidentally performing component-wise multiplication/division.

Cast elision

Since complex<T> and quat<T> lower to vector types, casts like complexf(foo(vec2f(z))) should lower to foo(z) without the extra vec2f(foo(vec2f(z))) noise especially when z is already a vec2 after lowering.

Promoted built-ins

A complex number and quaternion passed to component-wise exp() or sin() or log() without first casting to vec<T> is an error. However, we certainly want built-ins like length(), normalize() and dot() to work natively on complex and quaternions without casting, and also built-ins like round() and honestly most component-wise built-ins should be promoted and only exclude the ones where multiplication act differently (no exp, no log, no sin, etc).

New built-ins

If we do use infix * and /, we will need functions they will lower to, like cmulT(), qmulT(), cdivT(), qdivT() for T=f,i,u variants. We may also want to detect simple squares like z*z -> csquare(z) and 1 / z -> crecip(z) for efficiency.

An explicit conj() built-in to compute complex conjugates on complex<T> and quat<T> would be safer and less cryptic than quatf(-q.xyz, q.w). If the argument expression is a single variable (rather than a longer expression), or a single variable under a unary -, it could be lowered in-line without actually calling the conj() function. This shouldn't be difficult to implement. Thoughts?

An explicit cmulj() and cmulnegj() to rotate a complex<T> by +/- 90 degrees is also safer than swapping/negating components manually and can be done in-line as with conj(). This shouldn't be difficult to implement. Thoughts?

Perhaps we could reserve these proposed built-ins in the meantime.

[jordanhalase]

Constructors and Casting

The complex<T> and quat<T> types can be constructed from a scalar, a list of scalars, vectors, a list of vectors, or a mixed list of vectors and scalars, exaclty like vec2<T> and vec4<T>.

However, a quat cannot be constructed from any complex arguments, nor vice versa. The swizzles of complex or quat types are scalars or vectors, so a quat can be constructed from a complex via

let z = complex(/* ... */);
let q = quat(z.y, 0, 0, z.x);
let another_q = quat(z.xy, 0, 0);
let another_z = complex(q.wx);

The complex and quat types also have identity casts, even if redundant

let z = complex(/* ... */);
let q = quat(/* ... */);
let z2 = complex(z);    // Ok
let q2 = quat(q);       // Ok

The vecN constructors are augmented to cast from complex types, but only for complex to vec2 and quat to vec4.

let z = complex(/* ... */);
let q = quat(/* ... */);
let v0 = vec2(z);
let v1 = vec4(q);
let v2 = vec4(z.xy, 0, 0);

Unlike vectors, when the complex and quat constructors are passed a single scalar, they are not splatted. Scalars represent real values, so they construct the types with their real component populated and their imaginary components zeroed.

let z = complex(3); // same as complex(3, 0);
let q = quat(4); // same as quat(0, 0, 0, 4);

Arithmetic

Addition and Subtraction

A complex +- complex and quat +- quat are computed component-wise, exactly as they do for vec2 and vec4.

However, addition or subtraction by a scalar value is different than for vector types. For vector types, the scalar is splatted into a vector. For complex types, only the real component is populated.

let z = complex(/* ... */);
let q = quat(/* ... */);
let add_z = z + 3; // z + complex(3, 0)
let add_q = q + 4; // q + quat(0, 0, 0, 4)

Multiplication and Division

Multiplication by a scalar, and division by a scalar on the RHS is exactly like for vector types, where the scalar is splatted and the operation is performed component-wise.

let z = complex(/* ... */); // Lowers to vec2
let q = quat(/* ... */);    // Lowers to vec4
let z1 = z * 3; // same as vec2(z) * vec2(3, 3)
let z2 = z / 4; // same as vec2(z) / vec2(4, 4)
let q1 = q * 5; // same as vec4(q) * vec4(5, 5, 5, 5)
let q2 = q / 6; // same as vec4(q) / vec4(6, 6, 6, 6)

complex-complex and quaternion-quaternion multiplication and division, and LHS scalar division by a RHS complex or quaternion, require new built-in functions for lowering and syntactic sugar to replace * and / with these function calls. This is TBD.

[mighdoll]

@jordanhalase I suspect we're all sympathetic to the goal of writing math comfortably in WGSL/WESL. Finding the best way will take some figuring, of course. Your code examples will help. As you write more code that uses complex numbers and quaternions, please link to it here too if its public. Then we can see if future language ideas can help clean up your actual real code examples.