@woosh/meep-engine 3.0.0 → 3.0.1

package/src/engine/graphics/ecs/camera/Camera.js

@@ -1,303 +1,165 @@
-import { Frustum } from 'three';
-import { assert } from "../../../../core/assert.js";
-import { plane3_compute_ray_intersection } from "../../../../core/geom/3d/plane/plane3_compute_ray_intersection.js";
-import { v3_distance_above_plane } from "../../../../core/geom/vec3/v3_distance_above_plane.js";
-import Vector1 from "../../../../core/geom/Vector1.js";
-import Vector3 from "../../../../core/geom/Vector3.js";
-import ObservedBoolean from "../../../../core/model/ObservedBoolean.js";
-import ObservedEnum from "../../../../core/model/ObservedEnum.js";
-import { frustum_from_camera } from "./frustum_from_camera.js";
-import { ProjectionType } from "./ProjectionType.js";
-import { quaternion_invert_orientation } from "./quaternion_invert_orientation.js";
-import { unprojectPoint } from "./unprojectPoint.js";
-
-/**
- * @class
- */
-export class Camera {
-    /**
-     * Whether clipping planes should be automatically calculated or not
-     * @type {boolean}
-     */
-    autoClip = false;
-
-    /**
-     * Tunable parameter to prevent clipping planes from thrashing. Clipping planes must move by a certain portion of the current span before frustum gets shrunken
-     * @type {number}
-     */
-    autoClipHysteresis = 0.33;
-
-    object = null;
-
-    /**
-     *
-     * @type {Vector1}
-     */
-    fov = new Vector1(45);
-
-    /**
-     *
-     * @type {ObservedEnum<ProjectionType>}
-     */
-    projectionType = new ObservedEnum(ProjectionType.Perspective, ProjectionType);
-
-    /**
-     *
-     * @type {ObservedBoolean}
-     */
-    active = new ObservedBoolean(true);
-
-    /**
-     * Near clipping plane
-     * @type {number}
-     * @private
-     */
-    __clip_far = 100;
-
-    /**
-     * Far clipping plane
-     * @type {number}
-     * @private
-     */
-    __clip_near = 0.1;
-
-    /**
-     *
-     * @param {Quaternion} output
-     * @param {Quaternion} input
-     */
-    getReciprocalRotation(output, input) {
-        quaternion_invert_orientation(output, input);
-    }
-
-    get clip_far() {
-        return this.__clip_far;
-    }
-
-    set clip_far(v) {
-        this.__clip_far = v;
-
-        if (this.object !== null) {
-            this.object.far = v;
-        }
-    }
-
-    get clip_near() {
-        return this.__clip_near;
-    }
-
-    set clip_near(v) {
-        this.__clip_near = v;
-
-        if (this.object !== null) {
-            this.object.near = v;
-        }
-    }
-
-    updateMatrices() {
-        const c = this.object;
-
-        if (c === null) {
-            return;
-        }
-
-        c.updateProjectionMatrix();
-        c.updateMatrixWorld(true);
-
-        //update world inverse matrix
-        c.matrixWorldInverse.copy(c.matrixWorld);
-        c.matrixWorldInverse.invert();
-    }
-
-    projectRay(x, y, source, target) {
-        Camera.projectRay(this.object, x, y, source, target);
-    }
-
-    /**
-     *
-     * @param {Camera} other
-     */
-    copy(other) {
-        this.active.copy(other.active);
-        this.projectionType.copy(other.projectionType);
-        this.autoClip = other.autoClip;
-        this.autoClipHysteresis = other.autoClipHysteresis;
-        this.fov.copy(other.fov);
-        this.clip_near = other.clip_near;
-        this.clip_far = other.clip_far;
-    }
-
-    /**
-     *
-     * @returns {Camera}
-     */
-    clone() {
-        const clone = new Camera();
-
-        clone.copy(this);
-
-        return clone;
-    }
-
-    toJSON() {
-        return {
-            autoClip: this.autoClip,
-            active: this.active.toJSON()
-        };
-    }
-
-    fromJSON(json) {
-        this.autoClip = json.autoClip;
-
-        if (typeof json.active === "boolean") {
-            this.active.fromJSON(json.active);
-        } else {
-            this.active.set(false);
-        }
-    }
-
-    /**
-     *
-     * @param {Camera|THREE.PerspectiveCamera|THREE.OrthographicCamera} camera
-     * @param {number} x
-     * @param {number} y
-     * @param {Vector3} out_source
-     * @param {Vector3} out_direction
-     */
-    static projectRay(
-        camera,
-        x, y,
-        out_source, out_direction
-    ) {
-        assert.defined(camera, "camera");
-        assert.defined(camera.position, "Camera.position");
-
-
-        assert.isNumber(x, 'x');
-        assert.isNumber(y, "y");
-
-        // assert.ok(x >= -1, `X(=${x}) must be greater than or equal to -1.0, not a clip-space coordinate`);
-        // assert.ok(x <= 1, `X(=${x}) must be less than or equal to 1.0, not a clip-space coordinate`);
-
-        // assert.ok(y >= -1, `Y(=${y}) must be greater than or equal to -1.0, not a clip-space coordinate`);
-        // assert.ok(y <= 1, `Y(=${y}) must be less than or equal to 1.0, not a clip-space coordinate`);
-
-        if (camera.isPerspectiveCamera || camera.isOrthographicCamera) {
-            const m4_world = camera.matrixWorld.elements;
-            const m4_projection_inverse = camera.projectionMatrixInverse.elements;
-
-            scratch_v3_1.setFromMatrixPosition(m4_world);
-
-            scratch_v3_0.set(x, y, 0.5);
-
-            // NOTE: projection inverse and world matrices are used in "unproject" operation, we update those to make things work as intended. This is handled by the camera system
-
-            unprojectPoint(
-                scratch_v3_0,
-                scratch_v3_0,
-                m4_projection_inverse,
-                m4_world
-            );
-
-            //get direction
-            scratch_v3_0.sub(scratch_v3_1);
-            scratch_v3_0.normalize();
-
-            out_source.copy(scratch_v3_1);
-            out_direction.copy(scratch_v3_0);
-
-        } else {
-            throw new Error('Unsupported camera type');
-        }
-    }
-
-    /**
-     *
-     * @param {Matrix4} result
-     */
-    computeProjectionMatrix(result) {
-        const camera = this.object;
-
-        if (camera === null) {
-            return false;
-        }
-
-        result.multiplyMatrices(camera.projectionMatrix, camera.matrixWorldInverse);
-
-        return true;
-    }
-
-    /**
-     *
-     * @param {Vector3} out
-     * @param {number} origin_x
-     * @param {number} origin_y
-     * @param {number} origin_z
-     * @param {number} direction_x
-     * @param {number} direction_y
-     * @param {number} direction_z
-     * @param {number} plane_index
-     */
-    rayPlaneIntersection(
-        out,
-        origin_x, origin_y, origin_z,
-        direction_x, direction_y, direction_z,
-        plane_index
-    ) {
-
-        assert.isNonNegativeInteger(plane_index, 'plane_index');
-        assert.lessThanOrEqual(plane_index, 5, `plane_index must be <= 5, was ${plane_index}`)
-
-        frustum_from_camera(this.object, scratch_frustum);
-
-        const plane = scratch_frustum.planes[plane_index];
-
-        assert.defined(plane, 'plane');
-
-        plane3_compute_ray_intersection(
-            out,
-            origin_x, origin_y, origin_z,
-            direction_x, direction_y, direction_z,
-            plane.normal.x, plane.normal.y, plane.normal.z,
-            plane.constant
-        );
-    }
-
-    /**
-     *
-     * @param {number} x
-     * @param {number} y
-     * @param {number} z
-     * @param {Vector3} result
-     */
-    projectWorldPointOntoNearPlane(x, y, z, result) {
-
-        frustum_from_camera(this.object, scratch_frustum);
-
-        const near = scratch_frustum.planes[0];
-
-        scratch_v3_0.set(x, y, z);
-
-        const normal = near.normal;
-
-        const distance_to_plane = v3_distance_above_plane(x, y, z, normal.x, normal.y, normal.z, near.constant);
-
-        const negative_distance_to_plane = -distance_to_plane;
-
-        result.set(
-            normal.x * negative_distance_to_plane + x,
-            normal.y * negative_distance_to_plane + y,
-            normal.z * negative_distance_to_plane + z,
-        );
-    }
-}
-
-Camera.typeName = "Camera";
-
-Camera.ProjectionType = ProjectionType;
-
-const scratch_v3_0 = new Vector3();
-const scratch_v3_1 = new Vector3();
-const scratch_frustum = new Frustum();
-
-
+import Vector1 from "../../../../core/geom/Vector1.js";
+import ObservedBoolean from "../../../../core/model/ObservedBoolean.js";
+import ObservedEnum from "../../../../core/model/ObservedEnum.js";
+import { ProjectionType } from "./ProjectionType.js";
+import { quaternion_invert_orientation } from "./quaternion_invert_orientation.js";
+
+/**
+ * @class
+ */
+export class Camera {
+    /**
+     * Whether clipping planes should be automatically calculated or not.
+     *
+     * **Nothing reads this.** The pass that tightened the planes measured the depth range of the
+     * renderer's own layers, which no renderer has offered since the three path was removed; the
+     * field stays because it is on the wire and a level carries it.
+     *
+     * @type {boolean}
+     */
+    autoClip = false;
+
+    /**
+     * Tunable parameter to prevent clipping planes from thrashing. Clipping planes must move by a certain portion of the current span before frustum gets shrunken
+     *
+     * Inert for the same reason as {@link autoClip}, and kept for the same one.
+     *
+     * @type {number}
+     */
+    autoClipHysteresis = 0.33;
+
+    /**
+     * @type {Float32Array}
+     */
+    #frustum = new Float32Array(24);
+
+    /**
+     * @type {boolean}
+     */
+    #has_frustum = false;
+
+    /**
+     *
+     * @type {Vector1}
+     */
+    fov = new Vector1(45);
+
+    /**
+     *
+     * @type {ObservedEnum<ProjectionType>}
+     */
+    projectionType = new ObservedEnum(ProjectionType.Perspective, ProjectionType);
+
+    /**
+     *
+     * @type {ObservedBoolean}
+     */
+    active = new ObservedBoolean(true);
+
+    /**
+     * Far clipping plane
+     * @type {number}
+     */
+    clip_far = 100;
+
+    /**
+     * Near clipping plane
+     * @type {number}
+     */
+    clip_near = 0.1;
+
+    /**
+     * The planes of the frame this camera last drew — six
+     * `[normal_x, normal_y, normal_z, constant]` tuples, the layout every frustum query in the tree
+     * reads — or `null` when it has not drawn one.
+     *
+     * A method rather than a property because it is not one: the inspector draws a row for every
+     * readable property a component has, and this is an answer the renderer gave, not a field
+     * anybody authors. The planes are rewritten under the caller every tick.
+     *
+     * @returns {Float32Array|null}
+     */
+    getFrustumPlanes() {
+        if (!this.#has_frustum) {
+            return null;
+        }
+
+        return this.#frustum;
+    }
+
+    /**
+     * Record the planes the frame was drawn with.
+     *
+     * The renderer's camera is what computes them, because the frustum a gameplay query wants is
+     * the one the picture was actually drawn with; deriving a second one from the field of view
+     * here would need the aspect ratio, which belongs to whatever surface the frame is going out at
+     * and not to a camera entity.
+     *
+     * @param {Float32Array|number[]} planes six `[normal_x, normal_y, normal_z, constant]` tuples
+     */
+    publishFrustum(planes) {
+        this.#frustum.set(planes);
+
+        this.#has_frustum = true;
+    }
+
+    /**
+     *
+     * @param {Quaternion} output
+     * @param {Quaternion} input
+     */
+    getReciprocalRotation(output, input) {
+        quaternion_invert_orientation(output, input);
+    }
+
+    /**
+     *
+     * @param {Camera} other
+     */
+    copy(other) {
+        this.active.copy(other.active);
+        this.projectionType.copy(other.projectionType);
+        this.autoClip = other.autoClip;
+        this.autoClipHysteresis = other.autoClipHysteresis;
+        this.fov.copy(other.fov);
+        this.clip_near = other.clip_near;
+        this.clip_far = other.clip_far;
+    }
+
+    /**
+     *
+     * @returns {Camera}
+     */
+    clone() {
+        const clone = new Camera();
+
+        clone.copy(this);
+
+        return clone;
+    }
+
+    toJSON() {
+        return {
+            autoClip: this.autoClip,
+            active: this.active.toJSON()
+        };
+    }
+
+    fromJSON(json) {
+        this.autoClip = json.autoClip;
+
+        if (typeof json.active === "boolean") {
+            this.active.fromJSON(json.active);
+        } else {
+            this.active.set(false);
+        }
+    }
+
+}
+
+Camera.typeName = "Camera";
+
+Camera.ProjectionType = ProjectionType;
+
+
+

package/src/engine/graphics/ecs/camera/camera_active_frustum.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The world-space frustum of the frame, or `null` when nothing is drawing one.
+ *
+ * Six `[normal_x, normal_y, normal_z, constant]` tuples, the layout every frustum query in the tree
+ * reads — a point is inside when `normal · p + constant` is non-negative for all six.
+ *
+ * The planes belong to the camera component and are rewritten every tick, so a caller holds the
+ * answer for the length of its own call and no longer.
+ *
+ * @param {EntityComponentDataset} ecd
+ * @returns {Float32Array|null}
+ */
+export function camera_active_frustum(ecd: EntityComponentDataset): Float32Array | null;
+//# sourceMappingURL=camera_active_frustum.d.ts.map

package/src/engine/graphics/ecs/camera/camera_active_frustum.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"camera_active_frustum.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/ecs/camera/camera_active_frustum.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;GAWG;AACH,oEAFa,YAAY,GAAC,IAAI,CAY7B"}

package/src/engine/graphics/ecs/camera/camera_active_frustum.js

@@ -0,0 +1,25 @@
+import { camera_find_active } from "./camera_find_active.js";
+
+/**
+ * The world-space frustum of the frame, or `null` when nothing is drawing one.
+ *
+ * Six `[normal_x, normal_y, normal_z, constant]` tuples, the layout every frustum query in the tree
+ * reads — a point is inside when `normal · p + constant` is non-negative for all six.
+ *
+ * The planes belong to the camera component and are rewritten every tick, so a caller holds the
+ * answer for the length of its own call and no longer.
+ *
+ * @param {EntityComponentDataset} ecd
+ * @returns {Float32Array|null}
+ */
+export function camera_active_frustum(ecd) {
+    const { component } = camera_find_active(ecd);
+
+    if (component === undefined) {
+        return null;
+    }
+
+    // a camera that has not driven a frame yet answers `null`; zeroed planes would say "everything
+    // is visible", which is an answer rather than an admission
+    return component.getFrustumPlanes();
+}

package/src/engine/graphics/ecs/camera/camera_find_active.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The camera entity the frame is drawn from, or an entity of `-1` when the dataset has none.
+ *
+ * **The first active one wins**, which is the rule `CameraSystem3` settles on when it elects the
+ * camera it copies onto the renderer's. Two entities both claiming to be active therefore resolve
+ * the same way here as they do there; the predecessor of this function took the last one and could
+ * name a camera nothing was drawing from.
+ *
+ * @param {EntityComponentDataset} ecd
+ * @returns {{component: (Camera|undefined), entity: number}}
+ */
+export function camera_find_active(ecd: EntityComponentDataset): {
+    component: (Camera | undefined);
+    entity: number;
+};
+//# sourceMappingURL=camera_find_active.d.ts.map

package/src/engine/graphics/ecs/camera/camera_find_active.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"camera_find_active.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/ecs/camera/camera_find_active.js"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AACH,iEAFa;IAAC,SAAS,EAAE,CAAC,SAAO,SAAS,CAAC,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAC,CAgB3D"}

package/src/engine/graphics/ecs/camera/camera_find_active.js

@@ -0,0 +1,28 @@
+import { camera_traverse_active } from "./camera_traverse_active.js";
+
+/**
+ * The camera entity the frame is drawn from, or an entity of `-1` when the dataset has none.
+ *
+ * **The first active one wins**, which is the rule `CameraSystem3` settles on when it elects the
+ * camera it copies onto the renderer's. Two entities both claiming to be active therefore resolve
+ * the same way here as they do there; the predecessor of this function took the last one and could
+ * name a camera nothing was drawing from.
+ *
+ * @param {EntityComponentDataset} ecd
+ * @returns {{component: (Camera|undefined), entity: number}}
+ */
+export function camera_find_active(ecd) {
+    const result = {
+        entity: -1,
+        component: undefined
+    };
+
+    camera_traverse_active(ecd, (camera, entity) => {
+        if (result.entity === -1) {
+            result.entity = entity;
+            result.component = camera;
+        }
+    });
+
+    return result;
+}

package/src/engine/graphics/ecs/camera/camera_traverse_active.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Visit every camera entity that claims to be active.
+ *
+ * More than one may claim it; only one of them drives the frame, and which one that is belongs to
+ * {@link camera_find_active}.
+ *
+ * @param {EntityComponentDataset} ecd
+ * @param {(camera: Camera, entity: number) => void} visitor
+ */
+export function camera_traverse_active(ecd: EntityComponentDataset, visitor: (camera: Camera, entity: number) => void): void;
+import { Camera } from "./Camera.js";
+//# sourceMappingURL=camera_traverse_active.d.ts.map

package/src/engine/graphics/ecs/camera/camera_traverse_active.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"camera_traverse_active.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/ecs/camera/camera_traverse_active.js"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AACH,sFAFoB,MAAM,UAAU,MAAM,KAAK,IAAI,QAQlD;uBAjBsB,aAAa"}

package/src/engine/graphics/ecs/camera/camera_traverse_active.js

@@ -0,0 +1,18 @@
+import { Camera } from "./Camera.js";
+
+/**
+ * Visit every camera entity that claims to be active.
+ *
+ * More than one may claim it; only one of them drives the frame, and which one that is belongs to
+ * {@link camera_find_active}.
+ *
+ * @param {EntityComponentDataset} ecd
+ * @param {(camera: Camera, entity: number) => void} visitor
+ */
+export function camera_traverse_active(ecd, visitor) {
+    ecd.traverseComponents(Camera, function (camera, entity) {
+        if (camera.active.getValue()) {
+            visitor(camera, entity);
+        }
+    });
+}