Merge pull request #78 from pmndrs/feat/perspective-reverse-z

feat(mat4): add perspectiveReverseZ

Author: isaac-mason

API.md

@@ -616,6 +616,7 @@ import { mat4 } from 'math';
 - `mat4.frustumZO(out: Mat4, left: number, right: number, bottom: number, top: number, near: number, far: number): Mat4` — Generates a frustum matrix with the given bounds, suitable for WebGPU.
 - `mat4.perspectiveNO(out: Mat4, fovy: number, aspect: number, near: number, far: number): Mat4` — Generates a perspective projection matrix with the given bounds.
 - `mat4.perspectiveZO(out: Mat4, fovy: number, aspect: number, near: number, far: number): Mat4` — Generates a perspective projection matrix suitable for WebGPU with the given bounds.
+- `mat4.perspectiveReverseZ(out: Mat4, fovy: number, aspect: number, near: number, far: number): Mat4` — Generates a reverse-Z perspective projection matrix with the given bounds.
 - `mat4.perspectiveFromFieldOfViewNO(out: Mat4, fov: { upDegrees: number; downDegrees: number; leftDegrees: number; rightDegrees: number; }, near: number, far: number): Mat4` — Generates a perspective projection matrix with the given field of view.
 - `mat4.perspectiveFromFieldOfViewZO(out: Mat4, fov: { upDegrees: number; downDegrees: number; leftDegrees: number; rightDegrees: number; }, near: number, far: number): Mat4` — Generates a perspective projection matrix with the given field of view, suitable for WebGPU.
 - `mat4.orthoNO(out: Mat4, left: number, right: number, bottom: number, top: number, near: number, far: number): Mat4` — Generates a orthogonal projection matrix with the given bounds.

src/core/mat4.ts

@@ -1869,6 +1869,49 @@ export function perspectiveZO(out: Mat4, fovy: number, aspect: number, near: num
     return out;
 }
 
+/**
+ * Generates a reverse-Z perspective projection matrix with the given bounds.
+ * The near plane maps to a normalized device coordinate Z of 1 and the far plane to 0,
+ * using WebGPU/Vulkan/DirectX/Metal's [0, 1] clip volume.
+ * Pair with a floating point depth buffer, a depth clear of 0 and a `greater` depth compare
+ * for much better depth precision than a standard projection.
+ * Passing Infinity for far will generate an infinite projection matrix,
+ * where depth approaches 0 as distance approaches infinity.
+ *
+ * @param out mat4 frustum matrix will be written into
+ * @param fovy Vertical field of view in radians
+ * @param aspect Aspect ratio. typically viewport width/height
+ * @param near Near bound of the frustum
+ * @param far Far bound of the frustum, can be Infinity
+ * @returns out
+ */
+export function perspectiveReverseZ(out: Mat4, fovy: number, aspect: number, near: number, far: number): Mat4 {
+    const f = 1.0 / Math.tan(fovy / 2);
+    out[0] = f / aspect;
+    out[1] = 0;
+    out[2] = 0;
+    out[3] = 0;
+    out[4] = 0;
+    out[5] = f;
+    out[6] = 0;
+    out[7] = 0;
+    out[8] = 0;
+    out[9] = 0;
+    out[11] = -1;
+    out[12] = 0;
+    out[13] = 0;
+    out[15] = 0;
+    if (far !== Number.POSITIVE_INFINITY) {
+        const fn = 1 / (far - near);
+        out[10] = near * fn;
+        out[14] = far * near * fn;
+    } else {
+        out[10] = 0;
+        out[14] = near;
+    }
+    return out;
+}
+
 /**
  * Generates a perspective projection matrix with the given field of view.
  * This is primarily useful for generating projection matrices to be used

tst/unit/core/mat4.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it } from 'vitest';
 import type { Mat4, Vec3 } from '../../../src';
-import { mat4, quat } from '../../../src';
+import { mat4, quat, vec3 } from '../../../src';
 
 describe('mat4', () => {
     describe('create', () => {
@@ -673,6 +673,25 @@ describe('mat4', () => {
             expect(result[10]).not.toBe(mat4.perspectiveNO(mat4.create(), Math.PI / 4, 16 / 9, 0.1, 100)[10]);
         });
 
+        it('perspectiveReverseZ should map near to depth 1 and far to depth 0', () => {
+            const projection = mat4.perspectiveReverseZ(mat4.create(), Math.PI / 3, 2, 0.1, 100);
+            const point: Vec3 = [0, 0, 0];
+
+            expect(projection).toEqual(mat4.perspectiveZO(mat4.create(), Math.PI / 3, 2, 100, 0.1));
+            expect(vec3.transformMat4(point, [0, 0, -0.1], projection)[2]).toBeCloseTo(1);
+            expect(vec3.transformMat4(point, [0, 0, -100], projection)[2]).toBeCloseTo(0);
+        });
+
+        it('perspectiveReverseZ should support an infinite far plane', () => {
+            const projection = mat4.perspectiveReverseZ(mat4.create(), Math.PI / 3, 2, 0.1, Infinity);
+            const point: Vec3 = [0, 0, 0];
+
+            expect(projection.every(Number.isFinite)).toBe(true);
+            expect(vec3.transformMat4(point, [0, 0, -0.1], projection)[2]).toBeCloseTo(1);
+            expect(vec3.transformMat4(point, [0, 0, -0.2], projection)[2]).toBeCloseTo(0.5);
+            expect(vec3.transformMat4(point, [0, 0, -1e9], projection)[2]).toBeCloseTo(0, 8);
+        });
+
         it('orthoZO should create zero-to-one depth range orthographic', () => {
             const result = mat4.create();
             mat4.orthoZO(result, -1, 1, -1, 1, 0.1, 100);