@woosh/meep-engine 3.61.2 → 3.62.0

package/src/engine/graphics3/PickingSystem.js

@@ -1,413 +1,415 @@
-import { assert } from "../../core/assert.js";
-import { m4_invert } from "../../core/geom/3d/mat4/m4_invert.js";
-import { BufferResourceDescriptor } from "../../shade/device/graph/BufferResourceDescriptor.js";
-import { graph_read_buffer } from "../../shade/renderer/buffer/graph_read_buffer.js";
-import { FramePhase } from "../../shade/renderer/extension/FramePhase.js";
-import { RenderExtension } from "../../shade/renderer/extension/RenderExtension.js";
-import { ViewTextures } from "../../shade/renderer/extension/ViewTextures.js";
-import { VIZ_BUFFER_INVALID_MESH_VALUE } from "../../shade/renderer/rasterize/native/viz/VIZ_BUFFER_INVALID_MESH_VALUE.js";
-import { entity_of_row } from "../../shade/renderer/scene/rows/GPUSceneRows.js";
-import { ParentEntity } from "../ecs/parent/ParentEntity.js";
-import { System } from "../ecs/System.js";
-import { Pickable } from "./Pickable.js";
-import { PickingResult } from "./PickingResult.js";
-import {
-    PICKING_GATHER_STRIDE_WORDS,
-    PICKING_QUERY_OFF_VIEW,
-    shader_picking_gather
-} from "./shader_picking_gather.js";
-
-/**
- * Bytes a query occupies in the gather buffer: the mesh row and the depth, one word each.
- *
- * @type {number}
- */
-const QUERY_STRIDE = PICKING_GATHER_STRIDE_WORDS * 4;
-
-/**
- * Answers "what is under this pixel" for entities that asked to be pickable.
- *
- * **Off the visibility buffer.** The rasterizer writes every pixel's `meshes` row — an entity's
- * row, one on — and its depth; a pick reads those two texels out of the frame that drew them and
- * resolves the row to the entity that drew it, then up its parents to the one that opted in. What
- * was drawn is what is picked: at triangle precision, under skinning, with nothing kept on the CPU
- * for it — no bounds, no tree, no per-frame refresh.
- *
- * **Asynchronous and batched, of necessity.** The texels are gathered by the frame after the query
- * was asked and read back when the device has finished it, so an answer is a frame or two late and
- * arrives for the whole batch at once. A result is a promise for that reason, and nothing this
- * tick can come to depend on it.
- *
- * Terrain picking, which is where the game's precision matters, does not come through here at all:
- * it is an exact raycast against the terrain's own representation and is untouched by any of this.
- */
-export class PickingSystem extends System {
-    /**
-     * @type {GraphicsEngine}
-     */
-    #graphics;
-
-    /**
-     * @type {PickingExtension|null}
-     */
-    #extension = null;
-
-    /**
-     * Entities that have opted in.
-     *
-     * @type {Set<number>}
-     */
-    #pickable = new Set();
-
-    /**
-     * Queries asked since the last frame took a batch, with the promise each batch answers.
-     *
-     * @type {{queries: PickingQuery[], resolve: function(PickingResult[]): void, reject: function(Error): void}[]}
-     */
-    #waiting = [];
-
-    /**
-     * @param {GraphicsEngine} graphics whose frames draw the view the picks read
-     */
-    constructor(graphics) {
-        super();
-
-        assert.defined(graphics, 'graphics');
-
-        this.#graphics = graphics;
-
-        this.dependencies = [Pickable];
-    }
-
-    async startup(entityManager) {
-        this.entityManager = entityManager;
-
-        this.#extension = this.#graphics.add_extension(new PickingExtension(this));
-    }
-
-    async shutdown(entityManager) {
-        if (this.#extension !== null) {
-            this.#graphics.remove_extension(this.#extension);
-            this.#extension = null;
-        }
-
-        this.#pickable.clear();
-
-        // nothing will draw a frame for them
-        for (const batch of this.#waiting.splice(0)) {
-            batch.reject(new Error('the picking system shut down before a frame answered'));
-        }
-    }
-
-    /**
-     * @param {Pickable} pickable
-     * @param {number} entity
-     */
-    link(pickable, entity) {
-        this.#pickable.add(entity);
-    }
-
-    /**
-     * @param {Pickable} pickable
-     * @param {number} entity
-     */
-    unlink(pickable, entity) {
-        this.#pickable.delete(entity);
-    }
-
-    /**
-     * How many entities have opted in.
-     *
-     * @returns {number}
-     */
-    get pickable_count() {
-        return this.#pickable.size;
-    }
-
-    /**
-     * Batches asked and not yet answered by a frame.
-     *
-     * @returns {number}
-     */
-    get waiting_count() {
-        return this.#waiting.length;
-    }
-
-    /**
-     * What is drawn under each of these pixels.
-     *
-     * One result per query, in the order the queries were given. A pixel over nothing pickable
-     * still gets a result — `entity` is {@link PickingResult.NOTHING} — so the two arrays line up
-     * by position and a caller never has to search for the answer to its own question.
-     *
-     * Answered by the next frame that draws the view, when the device has finished it.
-     *
-     * @param {PickingQuery[]} queries
-     * @returns {Promise<PickingResult[]>}
-     */
-    pick(queries) {
-        assert.isArray(queries, 'queries');
-
-        if (queries.length === 0) {
-            return Promise.resolve([]);
-        }
-
-        return new Promise((resolve, reject) => {
-            this.#waiting.push({ queries: queries.slice(), resolve, reject });
-        });
-    }
-
-    /**
-     * Take everything asked since the last frame, to be answered by this one.
-     *
-     * @returns {{queries: PickingQuery[], resolve: function(PickingResult[]): void, reject: function(Error): void}[]}
-     */
-    take_waiting() {
-        return this.#waiting.splice(0);
-    }
-
-    /**
-     * The entity a drawn mesh row picks: the one that drew it, or the nearest of its ancestors,
-     * that opted in.
-     *
-     * @param {number} row a `meshes` row, as the visibility buffer holds it
-     * @returns {number} the entity, or {@link PickingResult.NOTHING}
-     */
-    resolve_row(row) {
-        if (row >= VIZ_BUFFER_INVALID_MESH_VALUE) {
-            return PickingResult.NOTHING;
-        }
-
-        const dataset = this.entityManager.dataset;
-        const pickable = this.#pickable;
-
-        let entity = entity_of_row(row);
-
-        while (entity >= 0 && dataset.entityExists(entity)) {
-            if (pickable.has(entity)) {
-                return entity;
-            }
-
-            const parent = dataset.getComponent(entity, ParentEntity);
-
-            entity = parent === undefined || parent === null ? -1 : parent.entity;
-        }
-
-        return PickingResult.NOTHING;
-    }
-}
-
-/**
- * Gathers the queried texels out of the frame that drew them, after the G-buffer is written and
- * before anything overwrites the visibility buffer, and answers the batch when they land.
- */
-export class PickingExtension extends RenderExtension {
-    name = "picking";
-    phase = FramePhase.AfterGBuffer;
-
-    /**
-     * @type {PickingSystem}
-     */
-    #system;
-
-    /**
-     * @param {PickingSystem} system
-     */
-    constructor(system) {
-        super();
-
-        this.#system = system;
-    }
-
-    /**
-     * @param {import("../../shade/renderer/extension/FrameContext.js").FrameContext} frame
-     */
-    record(frame) {
-        const batches = this.#system.take_waiting();
-
-        if (batches.length === 0) {
-            return;
-        }
-
-        // the view's own resolution: what the visibility buffer is sized to, whatever the frame's
-        // target at this phase is
-        const resolution = frame.view.resolution;
-        const width = resolution[0];
-        const height = resolution[1];
-
-        // what the frame projected with, kept for when the answer comes: the frame's camera has
-        // moved on by then
-        const view_projection = new Float32Array(frame.view.camera.view_projection_matrix);
-        const camera = frame.view.camera.camera.transform;
-        const eye = [camera.translation_x, camera.translation_y, camera.translation_z];
-
-        /** @type {PickingQuery[]} every query of every batch, in order */
-        const queries = [];
-
-        for (const batch of batches) {
-            for (const query of batch.queries) {
-                queries.push(query);
-            }
-        }
-
-        /*
-         The pixel each query names, resolved here rather than in the shader: the fraction is the
-         caller's unit and the resolution is the frame's, and neither is the gather's business. A
-         query that is not on the view at all carries `PICKING_QUERY_OFF_VIEW` instead of a pixel.
-        */
-        const pixels = new Uint32Array(queries.length * PICKING_GATHER_STRIDE_WORDS);
-
-        for (let i = 0; i < queries.length; i++) {
-            const query = queries[i];
-            const base = i * PICKING_GATHER_STRIDE_WORDS;
-
-            if (on_view(query)) {
-                pixels[base] = texel(query.u, width);
-                pixels[base + 1] = texel(query.v, height);
-            } else {
-                pixels[base] = PICKING_QUERY_OFF_VIEW;
-            }
-        }
-
-        const textures = frame.get(ViewTextures);
-        const graph = frame.graph;
-
-        const data = {};
-        const pass = graph.add("Picking / gather texels", data, (data, resources, context) => {
-            const encoder = context.encoder;
-
-            shader_picking_gather.dispatchThreads({
-                encoder,
-                bindings: {
-                    query_count: queries.length,
-                    viz_mesh: resources.get(data.mesh),
-                    viz_depth: resources.get(data.depth),
-                    queries: encoder.allocateTransientBufferAndLoad(
-                        pixels.buffer, GPUBufferUsage.STORAGE
-                    ),
-                    results: resources.get(data.results),
-                },
-                thread_count_x: queries.length,
-            });
-        });
-
-        data.mesh = pass.read(textures.visibility_mesh);
-        data.depth = pass.read(textures.depth);
-        data.results = pass.create("picking/results", BufferResourceDescriptor.from(
-            queries.length * QUERY_STRIDE,
-            GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC
-        ));
-
-        const system = this.#system;
-
-        graph_read_buffer({ graph, buffer: data.results })
-            .then(ref => {
-                try {
-                    const words = new Uint32Array(ref.getValue());
-                    const floats = new Float32Array(words.buffer);
-
-                    let index = 0;
-
-                    for (const batch of batches) {
-                        const results = [];
-
-                        for (let i = 0; i < batch.queries.length; i++, index++) {
-                            const query = batch.queries[i];
-                            const result = new PickingResult();
-
-                            results.push(result);
-
-                            if (!on_view(query)) {
-                                // the gather writes an invalid row here too; this is the same
-                                // answer without depending on a dispatch having run
-                                continue;
-                            }
-
-                            const base = index * PICKING_GATHER_STRIDE_WORDS;
-                            const entity = system.resolve_row(words[base]);
-
-                            if (entity === PickingResult.NOTHING) {
-                                continue;
-                            }
-
-                            result.entity = entity;
-
-                            unproject(
-                                result.position, view_projection,
-                                texel(query.u, width), texel(query.v, height), width, height,
-                                floats[base + 1]
-                            );
-
-                            result.distance = Math.hypot(
-                                result.position.x - eye[0],
-                                result.position.y - eye[1],
-                                result.position.z - eye[2]
-                            );
-                        }
-
-                        batch.resolve(results);
-                    }
-                } finally {
-                    ref.release();
-                }
-            })
-            .catch(error => {
-                for (const batch of batches) {
-                    batch.reject(error instanceof Error ? error : new Error('the picking readback failed'));
-                }
-            });
-    }
-}
-
-/**
- * @param {PickingQuery} query
- * @returns {boolean} whether the point is on the view at all
- */
-function on_view(query) {
-    return query.u >= 0 && query.u < 1 && query.v >= 0 && query.v < 1;
-}
-
-/**
- * The texel a fraction of the view falls in.
- *
- * @param {number} fraction in [0, 1)
- * @param {number} extent texels
- * @returns {number}
- */
-function texel(fraction, extent) {
-    return Math.min(extent - 1, Math.floor(fraction * extent));
-}
-
-const SCRATCH_INVERSE = new Float32Array(16);
-
-/**
- * The world point a pixel's depth stands for, through the inverse of what the frame projected
- * with. Depth is what the buffer holds — reverse-Z, `1` at the near plane — and WebGPU's clip z
- * is that same `[0, 1]`, so it goes straight in.
- *
- * @param {Vector3} target
- * @param {Float32Array} view_projection
- * @param {number} x pixel
- * @param {number} y pixel
- * @param {number} width
- * @param {number} height
- * @param {number} depth
- */
-function unproject(target, view_projection, x, y, width, height, depth) {
-    const m = SCRATCH_INVERSE;
-
-    m4_invert(m, view_projection);
-
-    // the pixel's centre, in NDC: x to the right, y up
-    const nx = ((x + 0.5) / width) * 2 - 1;
-    const ny = 1 - ((y + 0.5) / height) * 2;
-    const nz = depth;
-
-    // column-major: column c is m[c * 4 .. c * 4 + 3]
-    const wx = m[0] * nx + m[4] * ny + m[8] * nz + m[12];
-    const wy = m[1] * nx + m[5] * ny + m[9] * nz + m[13];
-    const wz = m[2] * nx + m[6] * ny + m[10] * nz + m[14];
-    const ww = m[3] * nx + m[7] * ny + m[11] * nz + m[15];
-
-    target.set(wx / ww, wy / ww, wz / ww);
-}
+import { assert } from "../../core/assert.js";
+import { m4_invert } from "../../core/geom/3d/mat4/m4_invert.js";
+import { BufferResourceDescriptor } from "../../shade/device/graph/BufferResourceDescriptor.js";
+import { graph_read_buffer } from "../../shade/renderer/buffer/graph_read_buffer.js";
+import { FramePhase } from "../../shade/renderer/extension/FramePhase.js";
+import { RenderExtension } from "../../shade/renderer/extension/RenderExtension.js";
+import { ViewTextures } from "../../shade/renderer/extension/ViewTextures.js";
+import { VIZ_BUFFER_INVALID_MESH_VALUE } from "../../shade/renderer/rasterize/native/viz/VIZ_BUFFER_INVALID_MESH_VALUE.js";
+import { entity_of_row } from "../../shade/renderer/scene/rows/GPUSceneRows.js";
+import { ParentEntity } from "../ecs/parent/ParentEntity.js";
+import { System } from "../ecs/System.js";
+import { Pickable } from "./Pickable.js";
+import { PickingResult } from "./PickingResult.js";
+import {
+    PICKING_GATHER_STRIDE_WORDS,
+    PICKING_QUERY_OFF_VIEW,
+    shader_picking_gather
+} from "./shader_picking_gather.js";
+
+/**
+ * Bytes a query occupies in the gather buffer: the mesh row and the depth, one word each.
+ *
+ * @type {number}
+ */
+const QUERY_STRIDE = PICKING_GATHER_STRIDE_WORDS * 4;
+
+/**
+ * Answers "what is under this pixel" for entities that asked to be pickable.
+ *
+ * **Off the visibility buffer.** The rasterizer writes every pixel's `meshes` row — an entity's
+ * row, one on — and its depth; a pick reads those two texels out of the frame that drew them and
+ * resolves the row to the entity that drew it, then up its parents to the one that opted in. What
+ * was drawn is what is picked: at triangle precision, under skinning, with nothing kept on the CPU
+ * for it — no bounds, no tree, no per-frame refresh.
+ *
+ * **Asynchronous and batched, of necessity.** The texels are gathered by the frame after the query
+ * was asked and read back when the device has finished it, so an answer is a frame or two late and
+ * arrives for the whole batch at once. A result is a promise for that reason, and nothing this
+ * tick can come to depend on it.
+ *
+ * Terrain picking, which is where the game's precision matters, does not come through here at all:
+ * it is an exact raycast against the terrain's own representation and is untouched by any of this.
+ */
+export class PickingSystem extends System {
+    /**
+     * @type {GraphicsEngine}
+     */
+    #graphics;
+
+    /**
+     * @type {PickingExtension|null}
+     */
+    #extension = null;
+
+    /**
+     * Entities that have opted in.
+     *
+     * @type {Set<number>}
+     */
+    #pickable = new Set();
+
+    /**
+     * Queries asked since the last frame took a batch, with the promise each batch answers.
+     *
+     * @type {{queries: PickingQuery[], resolve: function(PickingResult[]): void, reject: function(Error): void}[]}
+     */
+    #waiting = [];
+
+    /**
+     * @param {GraphicsEngine} graphics whose frames draw the view the picks read
+     */
+    constructor(graphics) {
+        super();
+
+        assert.defined(graphics, 'graphics');
+
+        this.#graphics = graphics;
+
+        this.dependencies = [Pickable];
+    }
+
+    async startup(entityManager) {
+        this.entityManager = entityManager;
+
+        this.#extension = this.#graphics.add_extension(new PickingExtension(this));
+    }
+
+    async shutdown(entityManager) {
+        if (this.#extension !== null) {
+            this.#graphics.remove_extension(this.#extension);
+            this.#extension = null;
+        }
+
+        this.#pickable.clear();
+
+        // nothing will draw a frame for them
+        for (const batch of this.#waiting.splice(0)) {
+            batch.reject(new Error('the picking system shut down before a frame answered'));
+        }
+    }
+
+    /**
+     * @param {Pickable} pickable
+     * @param {number} entity
+     */
+    link(pickable, entity) {
+        this.#pickable.add(entity);
+    }
+
+    /**
+     * @param {Pickable} pickable
+     * @param {number} entity
+     */
+    unlink(pickable, entity) {
+        this.#pickable.delete(entity);
+    }
+
+    /**
+     * How many entities have opted in.
+     *
+     * @returns {number}
+     */
+    get pickable_count() {
+        return this.#pickable.size;
+    }
+
+    /**
+     * Batches asked and not yet answered by a frame.
+     *
+     * @returns {number}
+     */
+    get waiting_count() {
+        return this.#waiting.length;
+    }
+
+    /**
+     * What is drawn under each of these pixels.
+     *
+     * One result per query, in the order the queries were given. A pixel over nothing pickable
+     * still gets a result — `entity` is {@link PickingResult.NOTHING} — so the two arrays line up
+     * by position and a caller never has to search for the answer to its own question.
+     *
+     * Answered by the next frame that draws the view, when the device has finished it.
+     *
+     * @param {PickingQuery[]} queries
+     * @returns {Promise<PickingResult[]>}
+     */
+    pick(queries) {
+        assert.isArray(queries, 'queries');
+
+        if (queries.length === 0) {
+            return Promise.resolve([]);
+        }
+
+        return new Promise((resolve, reject) => {
+            this.#waiting.push({ queries: queries.slice(), resolve, reject });
+        });
+    }
+
+    /**
+     * Take everything asked since the last frame, to be answered by this one.
+     *
+     * @returns {{queries: PickingQuery[], resolve: function(PickingResult[]): void, reject: function(Error): void}[]}
+     */
+    take_waiting() {
+        return this.#waiting.splice(0);
+    }
+
+    /**
+     * The entity a drawn mesh row picks: the one that drew it, or the nearest of its ancestors,
+     * that opted in.
+     *
+     * @param {number} row a `meshes` row, as the visibility buffer holds it
+     * @returns {number} the entity, or {@link PickingResult.NOTHING}
+     */
+    resolve_row(row) {
+        if (row >= VIZ_BUFFER_INVALID_MESH_VALUE) {
+            return PickingResult.NOTHING;
+        }
+
+        const dataset = this.entityManager.dataset;
+        const pickable = this.#pickable;
+
+        let entity = entity_of_row(row);
+
+        while (entity >= 0 && dataset.entityExists(entity)) {
+            if (pickable.has(entity)) {
+                return entity;
+            }
+
+            const parent = dataset.getComponent(entity, ParentEntity);
+
+            entity = parent === undefined || parent === null ? -1 : parent.entity;
+        }
+
+        return PickingResult.NOTHING;
+    }
+}
+
+/**
+ * Gathers the queried texels out of the frame that drew them, after the G-buffer is written and
+ * before anything overwrites the visibility buffer, and answers the batch when they land.
+ */
+export class PickingExtension extends RenderExtension {
+    name = "picking";
+    phase = FramePhase.AfterGBuffer;
+
+    /**
+     * @type {PickingSystem}
+     */
+    #system;
+
+    /**
+     * @param {PickingSystem} system
+     */
+    constructor(system) {
+        super();
+
+        this.#system = system;
+    }
+
+    /**
+     * @param {import("../../shade/renderer/extension/FrameContext.js").FrameContext} frame
+     */
+    record(frame) {
+        const batches = this.#system.take_waiting();
+
+        if (batches.length === 0) {
+            return;
+        }
+
+        // the view's own resolution: what the visibility buffer is sized to, whatever the frame's
+        // target at this phase is
+        const resolution = frame.view.resolution;
+        const width = resolution[0];
+        const height = resolution[1];
+
+        // what the frame projected with, kept for when the answer comes: the frame's camera has
+        // moved on by then
+        const view_projection = new Float32Array(frame.view.camera.view_projection_matrix);
+        const camera = frame.view.camera.camera.transform;
+        const eye = [camera.translation_x, camera.translation_y, camera.translation_z];
+
+        /** @type {PickingQuery[]} every query of every batch, in order */
+        const queries = [];
+
+        for (const batch of batches) {
+            for (const query of batch.queries) {
+                queries.push(query);
+            }
+        }
+
+        /*
+         The pixel each query names, resolved here rather than in the shader: the fraction is the
+         caller's unit and the resolution is the frame's, and neither is the gather's business. A
+         query that is not on the view at all carries `PICKING_QUERY_OFF_VIEW` instead of a pixel.
+        */
+        const pixels = new Uint32Array(queries.length * PICKING_GATHER_STRIDE_WORDS);
+
+        for (let i = 0; i < queries.length; i++) {
+            const query = queries[i];
+            const base = i * PICKING_GATHER_STRIDE_WORDS;
+
+            if (on_view(query)) {
+                pixels[base] = texel(query.u, width);
+                pixels[base + 1] = texel(query.v, height);
+            } else {
+                pixels[base] = PICKING_QUERY_OFF_VIEW;
+            }
+        }
+
+        const textures = frame.get(ViewTextures);
+        const graph = frame.graph;
+
+        const data = {};
+        const pass = graph.add("Picking / gather texels", data, (data, resources, context) => {
+            const encoder = context.encoder;
+
+            shader_picking_gather.dispatchThreads({
+                encoder,
+                bindings: {
+                    query_count: queries.length,
+                    visibility: resources.get(data.visibility),
+                    visible_meshlets: resources.get(data.visible_meshlets),
+                    viz_depth: resources.get(data.depth),
+                    queries: encoder.allocateTransientBufferAndLoad(
+                        pixels.buffer, GPUBufferUsage.STORAGE
+                    ),
+                    results: resources.get(data.results),
+                },
+                thread_count_x: queries.length,
+            });
+        });
+
+        data.visibility = pass.read(textures.visibility);
+        data.visible_meshlets = pass.read(textures.visible_meshlets);
+        data.depth = pass.read(textures.depth);
+        data.results = pass.create("picking/results", BufferResourceDescriptor.from(
+            queries.length * QUERY_STRIDE,
+            GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC
+        ));
+
+        const system = this.#system;
+
+        graph_read_buffer({ graph, buffer: data.results })
+            .then(ref => {
+                try {
+                    const words = new Uint32Array(ref.getValue());
+                    const floats = new Float32Array(words.buffer);
+
+                    let index = 0;
+
+                    for (const batch of batches) {
+                        const results = [];
+
+                        for (let i = 0; i < batch.queries.length; i++, index++) {
+                            const query = batch.queries[i];
+                            const result = new PickingResult();
+
+                            results.push(result);
+
+                            if (!on_view(query)) {
+                                // the gather writes an invalid row here too; this is the same
+                                // answer without depending on a dispatch having run
+                                continue;
+                            }
+
+                            const base = index * PICKING_GATHER_STRIDE_WORDS;
+                            const entity = system.resolve_row(words[base]);
+
+                            if (entity === PickingResult.NOTHING) {
+                                continue;
+                            }
+
+                            result.entity = entity;
+
+                            unproject(
+                                result.position, view_projection,
+                                texel(query.u, width), texel(query.v, height), width, height,
+                                floats[base + 1]
+                            );
+
+                            result.distance = Math.hypot(
+                                result.position.x - eye[0],
+                                result.position.y - eye[1],
+                                result.position.z - eye[2]
+                            );
+                        }
+
+                        batch.resolve(results);
+                    }
+                } finally {
+                    ref.release();
+                }
+            })
+            .catch(error => {
+                for (const batch of batches) {
+                    batch.reject(error instanceof Error ? error : new Error('the picking readback failed'));
+                }
+            });
+    }
+}
+
+/**
+ * @param {PickingQuery} query
+ * @returns {boolean} whether the point is on the view at all
+ */
+function on_view(query) {
+    return query.u >= 0 && query.u < 1 && query.v >= 0 && query.v < 1;
+}
+
+/**
+ * The texel a fraction of the view falls in.
+ *
+ * @param {number} fraction in [0, 1)
+ * @param {number} extent texels
+ * @returns {number}
+ */
+function texel(fraction, extent) {
+    return Math.min(extent - 1, Math.floor(fraction * extent));
+}
+
+const SCRATCH_INVERSE = new Float32Array(16);
+
+/**
+ * The world point a pixel's depth stands for, through the inverse of what the frame projected
+ * with. Depth is what the buffer holds — reverse-Z, `1` at the near plane — and WebGPU's clip z
+ * is that same `[0, 1]`, so it goes straight in.
+ *
+ * @param {Vector3} target
+ * @param {Float32Array} view_projection
+ * @param {number} x pixel
+ * @param {number} y pixel
+ * @param {number} width
+ * @param {number} height
+ * @param {number} depth
+ */
+function unproject(target, view_projection, x, y, width, height, depth) {
+    const m = SCRATCH_INVERSE;
+
+    m4_invert(m, view_projection);
+
+    // the pixel's centre, in NDC: x to the right, y up
+    const nx = ((x + 0.5) / width) * 2 - 1;
+    const ny = 1 - ((y + 0.5) / height) * 2;
+    const nz = depth;
+
+    // column-major: column c is m[c * 4 .. c * 4 + 3]
+    const wx = m[0] * nx + m[4] * ny + m[8] * nz + m[12];
+    const wy = m[1] * nx + m[5] * ny + m[9] * nz + m[13];
+    const wz = m[2] * nx + m[6] * ny + m[10] * nz + m[14];
+    const ww = m[3] * nx + m[7] * ny + m[11] * nz + m[15];
+
+    target.set(wx / ww, wy / ww, wz / ww);
+}