Most other 3D math libraries are designed for WebGL, not WebGPU
WebGPU uses clip space Z 0 to 1, vs WebGL -1 to 1. So ortho, perspective, frustum are different
WebGPU mat3s are 12 floats (padded), WebGL they're 9.
Many other 3D math libraries are overly verbose
compare
// wgpu-matrixconst t = mat4.translation([x, y, z]);const p = mat4.perspective(fov, aspect, near, far);const r = mat4.rotationX(rad);
// gl-matrixconst t = mat4.create();mat4.fromTranslation(t, [x, y, z]);const p = mat4.create();mat4.perspective(p, fov, aspect, near, far);const r = mat4.create();mat4.fromXRotation(r, rad);
note that if you want to pre-create matrices you can still do this in wgpu-matrix
const t = mat4.create();mat4.translation([x, y, z], t);const p = mat4.create();mat4.perspective(fov, aspect, near, far, p);const r = mat4.create();mat4.rotationX(rad, r);
Note: for translation, rotation, and scaling there are 2 versions
of each function. One generates a translation, rotation, or scaling matrix.
The other translates, rotates, or scales a matrix.
const t = mat4.translation([1, 2, 3]); // a translation matrixconst r = mat4.rotationX(Math.PI * 0.5); // a rotation matrixconst s = mat4.scaling([1, 2, 3]); // a scaling matrix
const m = mat4.identity();const t = mat4.translate(m, [1, 2, 3]); // m * translation([1, 2, 3])const r = mat4.rotateX(m, Math.PI * 0.5); // m * rotationX(Math.PI * 0.5)const s = mat4.scale(m, [1, 2, 3]); // m * scaling([1, 2, 3])
Functions take an optional destination to hold the result.
const m = mat4.create(); // m = new mat4mat4.identity(m); // m = identitymat4.translate(m, [1, 2, 3], m); // m *= translation([1, 2, 3])mat4.rotateX(m, Math.PI * 0.5, m); // m *= rotationX(Math.PI * 0.5)mat4.scale(m, [1, 2, 3], m); // m *= scaling([1, 2, 3])
There is also the minified version
import { vec3, mat4,} from 'https://wgpu-matrix.org/dist/3.x/wgpu-matrix.module.min.js';// ... etc ...
wgpu-matrix functions take any compatible type as input.
Examples:
const view = mat4.lookAt( // view is Float32Array [10, 20, 30], // position [0, 5, 0], // target [0, 1, 0], // up);const view2 = mat4.lookAt( // view2 is Float32Array new Float32Array([10, 20, 30]), // position new Float64Array([0, 5, 0], // target [0, 1, 0], // up);
wgpu-matrix functions return the type passed as the destination or their default
const a = vec2.add([1, 2], [3, 4]); // a is Float32Arrayconst b = vec2.add([1, 2], [3, 4], [0, 0]); // b is number[]const j = vec2d.add([1, 2], [3, 4]); // j is Float64Arrayconst k = vec2d.add([1, 2], [3, 4], [0, 0]); // b is number[]const f32 = new Float32Array(2);const x = vec2d.add([1, 2], [3, 4]); // x is number[]const y = vec2d.add([1, 2], [3, 4], f32); // y is Float32Array
etc...
Note: You're unlikely to need any thing except mat3, mat4, quat,
vec2, vec3, and vec4 but, there are 3 sets of functions,
each one returning a different default
The only difference between the sets of functions is what type they default to returning.
Notes
mat4.perspective,
mat4.ortho, and
mat4.frustum
all return matrices with Z clip space from 0 to 1 (unlike most WebGL matrix libraries which return -1 to 1)
mat4.create makes an all zero matrix if passed no parameters.
If you want an identity matrix call mat4.identity
This is because WebGPU requires mat3s to be in this format and since
this library is for WebGPU it makes sense to match so you can manipulate
mat3s in TypeArrays directly.
vec3 in this library uses 3 floats per but be aware that an array of
vec3 in a Uniform Block or other structure in WGSL, each vec3 is
padded to 4 floats! In other words, if you declare
struct Foo { bar: vec3<f32>[3];};
then bar[0] is at byte offset 0, bar[1] at byte offset 16, bar[2] at byte offset 32.
WebGPU follows the same conventions as OpenGL, Vulkan, Metal for matrices. Some people call this "column major". The issue is the columns of
a traditional "math" matrix are stored as rows when declaring a matrix in code.
// performant usage// at init timeconst persp = mat4.create();const camera = mat4.create();const view = mat4.create();// at usage timemat4.perspective(fov, aspect, near, far, persp);mat4.lookAt(eye, target, up, camera);mat4.inverse(camera, view);
For me, most of the stuff I do in WebGPU, the supposed performance I might lose
from using the convenient style is so small as to be unmeasurable. I'd prefer to
stay convenient and then, if and only if I find a performance issue, then I
might bother to switch to the performant style.
const a: Mat4 = ...; // a = Float32Arrayconst b: Mat4d = ...; // b = Float64Arrayconst c: Mat4n = ...; // c = number[]
This is means code like this
const position: Mat4 = [10, 20, 30];
No longer works because Mat4 is a Float32Array.
BUT, functions take any of the normal types as an argument just like they used to
const position = [10, 20, 30]; // number[]const target = vec3.create(1, 2, 3); // Float32Arrayconst up = new Float64Array([0, 1, 0]); // Float64Array// Works fine, even those types are different, just like 2.x didconst view = mat4.lookAt(position, target, up); // Float32Array
If you really want types for each concrete type there's
Note: that in general you're unlikely to need any of these. Just use the
same ones you were using in 2.x
1.x -> 2.x
mat4.lookAt
changed from a "camera matrix" to a "view matrix" (same as gluLookAt).
If you want a matrix that orients an something in world space see
mat4.aim.
Sorry about this change but people are used to lookAt making a a view matrix
and it seemed prudent to make this change now and save more people from
frustration going forward.
Development
git clone https://github.com/greggman/wgpu-matrix.gitcd wgpu-matrixnpm inpm run buildnpm test
You can run tests in the browser by starting a local server
npx servez
Now go to wherever your server serves pages. In the case of servez that's
probably http://localhost:8080/test/.