@woosh/meep-engine 3.0.0 → 3.0.2

package/src/core/geom/3d/frustum/frustum3_compute_closest_point.js

@@ -1,110 +1,117 @@
-import { v3_distance_above_plane } from "../../vec3/v3_distance_above_plane.js";
-import Vector3 from "../../Vector3.js";
-import { plane3_compute_intersection_objects } from "../plane/plane3_compute_intersection_objects.js";
-import { plane3_project_point } from "../plane/plane3_project_point.js";
-import { plane3_compute_3_plane_intersection_from_three } from "../plane/plane3_compute_3_plane_intersection_from_three.js";
-import { ray3_compute_closest_point } from "../ray/ray3_compute_closest_point.js";
-
-/**
- *
- * @type {Plane[]}
- */
-const scratch_outer_planes = [];
-
-const scratch_v3_0 = new Vector3();
-
-const scratch_v3_1 = new Vector3();
-
-/**
- *
- * @type {number[]}
- */
-const scratch_v3_array = [];
-
-/**
- *
- * @param {Vector3} result
- * @param {Plane[]} planes
- * @param {number} target_x
- * @param {number} target_y
- * @param {number} target_z
- * @returns {boolean} if point is inside the frustum - true, false otherwise
- */
-export function frustum3_compute_closest_point(result, planes, target_x, target_y, target_z) {
-    let j;
-
-    let outside_plane_count = 0;
-
-    const plane_count = planes.length;
-
-    for (j = 0; j < plane_count; j++) {
-
-        const plane = planes[j];
-
-        const plane_normal = plane.normal;
-
-        const distance = v3_distance_above_plane(
-            target_x, target_y, target_z,
-            plane_normal.x, plane_normal.y, plane_normal.z, plane.constant
-        );
-
-        if (distance < 0) {
-
-            scratch_outer_planes[outside_plane_count] = j;
-
-            outside_plane_count++;
-
-        }
-
-    }
-
-    if (outside_plane_count === 0) {
-        result.set(target_x, target_y, target_z);
-
-        return true;
-    }
-
-    // point is outside the frustum
-
-    if (outside_plane_count === 1) {
-        const plane_0_index = scratch_outer_planes[0];
-        const plane_0 = planes[plane_0_index];
-        // point lies outside exactly one plane
-        plane3_project_point(result, target_x, target_y, target_z, plane_0.normal.x, plane_0.normal.y, plane_0.normal.z, plane_0.constant);
-    } else if (outside_plane_count === 2) {
-        // outside two planes, nearest point lies on the intersection line of two planes
-
-        const plane_0_index = scratch_outer_planes[0];
-        const plane_1_index = scratch_outer_planes[1];
-
-        const plane_0 = planes[plane_0_index];
-        const plane_1 = planes[plane_1_index];
-
-        const intersection_exists = plane3_compute_intersection_objects(plane_0, plane_1, scratch_v3_0, scratch_v3_1);
-
-        if (!intersection_exists) {
-            throw new Error('Planes are parallel and do not intersect, likely an invalid frustum');
-        }
-
-        ray3_compute_closest_point(result,
-            scratch_v3_0.x, scratch_v3_0.y, scratch_v3_0.z,
-            scratch_v3_1.x, scratch_v3_1.y, scratch_v3_1.z,
-            target_x, target_y, target_z
-        );
-    } else if (outside_plane_count === 3) {
-        // outside 3 planes, nearest point is intersect of 3 planes
-        const plane_0_index = scratch_outer_planes[0];
-        const plane_1_index = scratch_outer_planes[1];
-        const plane_2_index = scratch_outer_planes[2];
-
-        const plane_0 = planes[plane_0_index];
-        const plane_1 = planes[plane_1_index];
-        const plane_2 = planes[plane_2_index];
-
-        plane3_compute_3_plane_intersection_from_three(scratch_v3_array, 0, plane_0, plane_1, plane_2);
-
-        result.fromArray(scratch_v3_array, 0)
-    }
-
-    return false;
-}
+import { v3_distance_above_plane } from "../../vec3/v3_distance_above_plane.js";
+import Vector3 from "../../Vector3.js";
+import { plane3_compute_3_plane_intersection } from "../plane/plane3_compute_3_plane_intersection.js";
+import { plane3_compute_intersection } from "../plane/plane3_compute_intersection.js";
+import { plane3_project_point } from "../plane/plane3_project_point.js";
+import { ray3_compute_closest_point } from "../ray/ray3_compute_closest_point.js";
+
+/**
+ * Indices into the caller's plane list, for the planes the target lies outside of.
+ * @type {number[]}
+ */
+const scratch_outer_planes = [];
+
+const scratch_v3_0 = new Vector3();
+
+const scratch_v3_1 = new Vector3();
+
+/**
+ *
+ * @type {number[]}
+ */
+const scratch_v3_array = [];
+
+/**
+ * The point inside a convex frustum nearest to a target point, and whether the target was already
+ * inside it.
+ *
+ * **A plane is a `Vector4`**: `x, y, z` its normal and `w` its constant, inside where
+ * `dot(normal, p) + w` is non-negative. That is the same four numbers every frustum query in the
+ * tree reads and what `camera_active_frustum` publishes; it used to be a three `Plane`, whose
+ * `normal`/`constant` pair is the same thing wearing an object (X15d).
+ *
+ * @param {Vector3} result
+ * @param {Vector4[]} planes
+ * @param {number} target_x
+ * @param {number} target_y
+ * @param {number} target_z
+ * @returns {boolean} if point is inside the frustum - true, false otherwise
+ */
+export function frustum3_compute_closest_point(result, planes, target_x, target_y, target_z) {
+    let j;
+
+    let outside_plane_count = 0;
+
+    const plane_count = planes.length;
+
+    for (j = 0; j < plane_count; j++) {
+
+        const plane = planes[j];
+
+        const distance = v3_distance_above_plane(
+            target_x, target_y, target_z,
+            plane.x, plane.y, plane.z, plane.w
+        );
+
+        if (distance < 0) {
+
+            scratch_outer_planes[outside_plane_count] = j;
+
+            outside_plane_count++;
+
+        }
+
+    }
+
+    if (outside_plane_count === 0) {
+        result.set(target_x, target_y, target_z);
+
+        return true;
+    }
+
+    // point is outside the frustum
+
+    if (outside_plane_count === 1) {
+        const plane_0 = planes[scratch_outer_planes[0]];
+
+        // point lies outside exactly one plane
+        plane3_project_point(result, target_x, target_y, target_z, plane_0.x, plane_0.y, plane_0.z, plane_0.w);
+    } else if (outside_plane_count === 2) {
+        // outside two planes, nearest point lies on the intersection line of two planes
+
+        const plane_0 = planes[scratch_outer_planes[0]];
+        const plane_1 = planes[scratch_outer_planes[1]];
+
+        const intersection_exists = plane3_compute_intersection(
+            scratch_v3_0, scratch_v3_1,
+            plane_0.x, plane_0.y, plane_0.z, plane_0.w,
+            plane_1.x, plane_1.y, plane_1.z, plane_1.w
+        );
+
+        if (!intersection_exists) {
+            throw new Error('Planes are parallel and do not intersect, likely an invalid frustum');
+        }
+
+        ray3_compute_closest_point(result,
+            scratch_v3_0.x, scratch_v3_0.y, scratch_v3_0.z,
+            scratch_v3_1.x, scratch_v3_1.y, scratch_v3_1.z,
+            target_x, target_y, target_z
+        );
+    } else if (outside_plane_count === 3) {
+        // outside 3 planes, nearest point is intersect of 3 planes
+        const plane_0 = planes[scratch_outer_planes[0]];
+        const plane_1 = planes[scratch_outer_planes[1]];
+        const plane_2 = planes[scratch_outer_planes[2]];
+
+        plane3_compute_3_plane_intersection(
+            scratch_v3_array, 0,
+            plane_0.x, plane_0.y, plane_0.z, plane_0.w,
+            plane_1.x, plane_1.y, plane_1.z, plane_1.w,
+            plane_2.x, plane_2.y, plane_2.z, plane_2.w
+        );
+
+        result.fromArray(scratch_v3_array, 0)
+    }
+
+    return false;
+}

package/src/core/geom/3d/mat4/m4_look_at.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Build a view matrix that places the eye at `eye` and points it at `center`, with `up` naming
+ * which way is up.
+ *
+ * Right-handed, matching the camera basis the rest of the renderer uses: the eye looks down its own
+ * −Z, so `center` sits at a negative view-space z. The result is the inverse of the camera's world
+ * transform — it carries world space into view space, not the other way around.
+ *
+ * `up` only has to be non-parallel to the view direction; it is re-orthogonalized against it. When
+ * it *is* parallel the cross product collapses and the basis is degenerate — that is a caller error,
+ * and the assert below is what says so.
+ *
+ * Allocation-free.
+ *
+ * @param {number[]|Float32Array|Float64Array} out destination 4x4 matrix
+ * @param {ArrayLike<number>} eye position of the viewer, `[x, y, z]`
+ * @param {ArrayLike<number>} center point the viewer is looking at, `[x, y, z]`
+ * @param {ArrayLike<number>} up up direction, `[x, y, z]`, not parallel to `center - eye`
+ * @returns {number[]|Float32Array|Float64Array} `out`, for convenience
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function m4_look_at(out: number[] | Float32Array | Float64Array, eye: ArrayLike<number>, center: ArrayLike<number>, up: ArrayLike<number>): number[] | Float32Array | Float64Array;
+//# sourceMappingURL=m4_look_at.d.ts.map

package/src/core/geom/3d/mat4/m4_look_at.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"m4_look_at.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/mat4/m4_look_at.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,gCATW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,OAClC,UAAU,MAAM,CAAC,UACjB,UAAU,MAAM,CAAC,MACjB,UAAU,MAAM,CAAC,GACf,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,CA2E9C"}

package/src/core/geom/3d/mat4/m4_look_at.js

@@ -0,0 +1,96 @@
+import { assert } from "../../../assert.js";
+
+/**
+ * Build a view matrix that places the eye at `eye` and points it at `center`, with `up` naming
+ * which way is up.
+ *
+ * Right-handed, matching the camera basis the rest of the renderer uses: the eye looks down its own
+ * −Z, so `center` sits at a negative view-space z. The result is the inverse of the camera's world
+ * transform — it carries world space into view space, not the other way around.
+ *
+ * `up` only has to be non-parallel to the view direction; it is re-orthogonalized against it. When
+ * it *is* parallel the cross product collapses and the basis is degenerate — that is a caller error,
+ * and the assert below is what says so.
+ *
+ * Allocation-free.
+ *
+ * @param {number[]|Float32Array|Float64Array} out destination 4x4 matrix
+ * @param {ArrayLike<number>} eye position of the viewer, `[x, y, z]`
+ * @param {ArrayLike<number>} center point the viewer is looking at, `[x, y, z]`
+ * @param {ArrayLike<number>} up up direction, `[x, y, z]`, not parallel to `center - eye`
+ * @returns {number[]|Float32Array|Float64Array} `out`, for convenience
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function m4_look_at(out, eye, center, up) {
+    assert.isArrayLike(eye, 'eye');
+    assert.isArrayLike(center, 'center');
+    assert.isArrayLike(up, 'up');
+
+    const eye_x = eye[0];
+    const eye_y = eye[1];
+    const eye_z = eye[2];
+
+    // backward = normalize(eye - center); the view direction is its negation
+    let z0 = eye_x - center[0];
+    let z1 = eye_y - center[1];
+    let z2 = eye_z - center[2];
+
+    const z_length = Math.sqrt(z0 * z0 + z1 * z1 + z2 * z2);
+
+    assert.greaterThan(z_length, 0, 'distance between eye and center');
+
+    const z_scale = 1 / z_length;
+
+    z0 *= z_scale;
+    z1 *= z_scale;
+    z2 *= z_scale;
+
+    const up_x = up[0];
+    const up_y = up[1];
+    const up_z = up[2];
+
+    // right = normalize(cross(up, backward))
+    let x0 = up_y * z2 - up_z * z1;
+    let x1 = up_z * z0 - up_x * z2;
+    let x2 = up_x * z1 - up_y * z0;
+
+    const x_length = Math.sqrt(x0 * x0 + x1 * x1 + x2 * x2);
+
+    assert.greaterThan(x_length, 0, 'length of cross(up, eye - center), up must not be parallel to the view direction');
+
+    const x_scale = 1 / x_length;
+
+    x0 *= x_scale;
+    x1 *= x_scale;
+    x2 *= x_scale;
+
+    // up = cross(backward, right); both operands are unit and orthogonal, so this one already is
+    const y0 = z1 * x2 - z2 * x1;
+    const y1 = z2 * x0 - z0 * x2;
+    const y2 = z0 * x1 - z1 * x0;
+
+    // rotation is the transpose of the basis, translation is the eye in that rotated frame
+    out[0] = x0;
+    out[1] = y0;
+    out[2] = z0;
+    out[3] = 0;
+
+    out[4] = x1;
+    out[5] = y1;
+    out[6] = z1;
+    out[7] = 0;
+
+    out[8] = x2;
+    out[9] = y2;
+    out[10] = z2;
+    out[11] = 0;
+
+    out[12] = -(x0 * eye_x + x1 * eye_y + x2 * eye_z);
+    out[13] = -(y0 * eye_x + y1 * eye_y + y2 * eye_z);
+    out[14] = -(z0 * eye_x + z1 * eye_y + z2 * eye_z);
+    out[15] = 1;
+
+    return out;
+}

package/src/core/geom/3d/mat4/m4_make_rotation_x.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Create a 4x4 matrix that corresponds to a rotation around the X axis.
+ *
+ * Right-handed: a positive angle carries +Y towards +Z. The rotation-around-Y and
+ * rotation-around-Z companions are {@link m4_make_rotation_y} and {@link m4_make_rotation_z}; to
+ * compose several, build each one and chain them with {@link m4_multiply}.
+ *
+ * Allocation-free.
+ *
+ * @param {number[]|Float32Array|Float64Array} output 4x4 matrix output will be written here
+ * @param {number} angle rotation, in radians
+ * @returns {number[]|Float32Array|Float64Array} `output` parameter, returned for convenience
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function m4_make_rotation_x(output: number[] | Float32Array | Float64Array, angle: number): number[] | Float32Array | Float64Array;
+//# sourceMappingURL=m4_make_rotation_x.d.ts.map

package/src/core/geom/3d/mat4/m4_make_rotation_x.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"m4_make_rotation_x.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/mat4/m4_make_rotation_x.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;GAeG;AACH,2CAPW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,SAClC,MAAM,GACJ,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,CAiC9C"}

package/src/core/geom/3d/mat4/m4_make_rotation_x.js

@@ -0,0 +1,47 @@
+import { assert } from "../../../assert.js";
+
+/**
+ * Create a 4x4 matrix that corresponds to a rotation around the X axis.
+ *
+ * Right-handed: a positive angle carries +Y towards +Z. The rotation-around-Y and
+ * rotation-around-Z companions are {@link m4_make_rotation_y} and {@link m4_make_rotation_z}; to
+ * compose several, build each one and chain them with {@link m4_multiply}.
+ *
+ * Allocation-free.
+ *
+ * @param {number[]|Float32Array|Float64Array} output 4x4 matrix output will be written here
+ * @param {number} angle rotation, in radians
+ * @returns {number[]|Float32Array|Float64Array} `output` parameter, returned for convenience
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function m4_make_rotation_x(output, angle) {
+    assert.isNumber(angle, 'angle');
+    assert.notNaN(angle, 'angle');
+
+    const s = Math.sin(angle);
+    const c = Math.cos(angle);
+
+    output[0] = 1;
+    output[1] = 0;
+    output[2] = 0;
+    output[3] = 0;
+
+    output[4] = 0;
+    output[5] = c;
+    output[6] = s;
+    output[7] = 0;
+
+    output[8] = 0;
+    output[9] = -s;
+    output[10] = c;
+    output[11] = 0;
+
+    output[12] = 0;
+    output[13] = 0;
+    output[14] = 0;
+    output[15] = 1;
+
+    return output;
+}

package/src/core/geom/3d/mat4/m4_make_rotation_y.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Create a 4x4 matrix that corresponds to a rotation around the Y axis.
+ *
+ * Right-handed: a positive angle carries +Z towards +X. The rotation-around-X and
+ * rotation-around-Z companions are {@link m4_make_rotation_x} and {@link m4_make_rotation_z}; to
+ * compose several, build each one and chain them with {@link m4_multiply}.
+ *
+ * Allocation-free.
+ *
+ * @param {number[]|Float32Array|Float64Array} output 4x4 matrix output will be written here
+ * @param {number} angle rotation, in radians
+ * @returns {number[]|Float32Array|Float64Array} `output` parameter, returned for convenience
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function m4_make_rotation_y(output: number[] | Float32Array | Float64Array, angle: number): number[] | Float32Array | Float64Array;
+//# sourceMappingURL=m4_make_rotation_y.d.ts.map

package/src/core/geom/3d/mat4/m4_make_rotation_y.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"m4_make_rotation_y.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/mat4/m4_make_rotation_y.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;GAeG;AACH,2CAPW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,SAClC,MAAM,GACJ,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,CAiC9C"}

package/src/core/geom/3d/mat4/m4_make_rotation_y.js

@@ -0,0 +1,47 @@
+import { assert } from "../../../assert.js";
+
+/**
+ * Create a 4x4 matrix that corresponds to a rotation around the Y axis.
+ *
+ * Right-handed: a positive angle carries +Z towards +X. The rotation-around-X and
+ * rotation-around-Z companions are {@link m4_make_rotation_x} and {@link m4_make_rotation_z}; to
+ * compose several, build each one and chain them with {@link m4_multiply}.
+ *
+ * Allocation-free.
+ *
+ * @param {number[]|Float32Array|Float64Array} output 4x4 matrix output will be written here
+ * @param {number} angle rotation, in radians
+ * @returns {number[]|Float32Array|Float64Array} `output` parameter, returned for convenience
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function m4_make_rotation_y(output, angle) {
+    assert.isNumber(angle, 'angle');
+    assert.notNaN(angle, 'angle');
+
+    const s = Math.sin(angle);
+    const c = Math.cos(angle);
+
+    output[0] = c;
+    output[1] = 0;
+    output[2] = -s;
+    output[3] = 0;
+
+    output[4] = 0;
+    output[5] = 1;
+    output[6] = 0;
+    output[7] = 0;
+
+    output[8] = s;
+    output[9] = 0;
+    output[10] = c;
+    output[11] = 0;
+
+    output[12] = 0;
+    output[13] = 0;
+    output[14] = 0;
+    output[15] = 1;
+
+    return output;
+}

package/src/core/geom/3d/mat4/m4_make_rotation_z.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Create a 4x4 matrix that corresponds to a rotation around the Z axis.
+ *
+ * Right-handed: a positive angle carries +X towards +Y. The rotation-around-X and
+ * rotation-around-Y companions are {@link m4_make_rotation_x} and {@link m4_make_rotation_y}; to
+ * compose several, build each one and chain them with {@link m4_multiply}.
+ *
+ * Allocation-free.
+ *
+ * @param {number[]|Float32Array|Float64Array} output 4x4 matrix output will be written here
+ * @param {number} angle rotation, in radians
+ * @returns {number[]|Float32Array|Float64Array} `output` parameter, returned for convenience
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function m4_make_rotation_z(output: number[] | Float32Array | Float64Array, angle: number): number[] | Float32Array | Float64Array;
+//# sourceMappingURL=m4_make_rotation_z.d.ts.map

package/src/core/geom/3d/mat4/m4_make_rotation_z.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"m4_make_rotation_z.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/mat4/m4_make_rotation_z.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;GAeG;AACH,2CAPW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,SAClC,MAAM,GACJ,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,CAiC9C"}

package/src/core/geom/3d/mat4/m4_make_rotation_z.js

@@ -0,0 +1,47 @@
+import { assert } from "../../../assert.js";
+
+/**
+ * Create a 4x4 matrix that corresponds to a rotation around the Z axis.
+ *
+ * Right-handed: a positive angle carries +X towards +Y. The rotation-around-X and
+ * rotation-around-Y companions are {@link m4_make_rotation_x} and {@link m4_make_rotation_y}; to
+ * compose several, build each one and chain them with {@link m4_multiply}.
+ *
+ * Allocation-free.
+ *
+ * @param {number[]|Float32Array|Float64Array} output 4x4 matrix output will be written here
+ * @param {number} angle rotation, in radians
+ * @returns {number[]|Float32Array|Float64Array} `output` parameter, returned for convenience
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function m4_make_rotation_z(output, angle) {
+    assert.isNumber(angle, 'angle');
+    assert.notNaN(angle, 'angle');
+
+    const s = Math.sin(angle);
+    const c = Math.cos(angle);
+
+    output[0] = c;
+    output[1] = s;
+    output[2] = 0;
+    output[3] = 0;
+
+    output[4] = -s;
+    output[5] = c;
+    output[6] = 0;
+    output[7] = 0;
+
+    output[8] = 0;
+    output[9] = 0;
+    output[10] = 1;
+    output[11] = 0;
+
+    output[12] = 0;
+    output[13] = 0;
+    output[14] = 0;
+    output[15] = 1;
+
+    return output;
+}

package/src/core/geom/3d/mat4/m4_perspective.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Build a conventional perspective projection matrix: right-handed, with clip depth spanning the
+ * full −1…1 that OpenGL and three.js use.
+ *
+ * This is *not* the projection the renderer draws with — Shade's cameras use an infinite reverse-Z
+ * with a 0…1 depth range, which is what WebGPU wants. This one exists for the arithmetic that has to
+ * hold under either shape, and for reading geometry produced against the OpenGL convention.
+ *
+ * `far` is finite here on purpose: an infinite far plane is a different matrix, not a special value
+ * of this one.
+ *
+ * Allocation-free.
+ *
+ * @param {number[]|Float32Array|Float64Array} out destination 4x4 matrix
+ * @param {number} fov_y vertical field of view, in radians
+ * @param {number} aspect viewport width divided by its height
+ * @param {number} near distance to the near clipping plane, greater than 0
+ * @param {number} far distance to the far clipping plane, greater than `near`
+ * @returns {number[]|Float32Array|Float64Array} `out`, for convenience
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function m4_perspective(out: number[] | Float32Array | Float64Array, fov_y: number, aspect: number, near: number, far: number): number[] | Float32Array | Float64Array;
+//# sourceMappingURL=m4_perspective.d.ts.map

package/src/core/geom/3d/mat4/m4_perspective.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"m4_perspective.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/mat4/m4_perspective.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,oCAVW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,SAClC,MAAM,UACN,MAAM,QACN,MAAM,OACN,MAAM,GACJ,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,CA6C9C"}

package/src/core/geom/3d/mat4/m4_perspective.js

@@ -0,0 +1,66 @@
+import { assert } from "../../../assert.js";
+
+/**
+ * Build a conventional perspective projection matrix: right-handed, with clip depth spanning the
+ * full −1…1 that OpenGL and three.js use.
+ *
+ * This is *not* the projection the renderer draws with — Shade's cameras use an infinite reverse-Z
+ * with a 0…1 depth range, which is what WebGPU wants. This one exists for the arithmetic that has to
+ * hold under either shape, and for reading geometry produced against the OpenGL convention.
+ *
+ * `far` is finite here on purpose: an infinite far plane is a different matrix, not a special value
+ * of this one.
+ *
+ * Allocation-free.
+ *
+ * @param {number[]|Float32Array|Float64Array} out destination 4x4 matrix
+ * @param {number} fov_y vertical field of view, in radians
+ * @param {number} aspect viewport width divided by its height
+ * @param {number} near distance to the near clipping plane, greater than 0
+ * @param {number} far distance to the far clipping plane, greater than `near`
+ * @returns {number[]|Float32Array|Float64Array} `out`, for convenience
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function m4_perspective(out, fov_y, aspect, near, far) {
+    assert.isNumber(fov_y, 'fov_y');
+    assert.greaterThan(fov_y, 0, 'fov_y');
+    assert.lessThan(fov_y, Math.PI, 'fov_y');
+
+    assert.isNumber(aspect, 'aspect');
+    assert.greaterThan(aspect, 0, 'aspect');
+
+    assert.isNumber(near, 'near');
+    assert.greaterThan(near, 0, 'near');
+
+    assert.isFinite(far, 'far');
+    assert.greaterThan(far, near, 'far');
+
+    const f = 1 / Math.tan(fov_y * 0.5);
+
+    // 1 / (near - far), negative, and the shared factor of both depth terms
+    const nf = 1 / (near - far);
+
+    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[10] = (far + near) * nf;
+    out[11] = -1;
+
+    out[12] = 0;
+    out[13] = 0;
+    out[14] = 2 * far * near * nf;
+    out[15] = 0;
+
+    return out;
+}