@woosh/meep-engine 3.56.0 → 3.58.0

package/src/shade/renderer/water/query/GPUWaterQueries.js

@@ -0,0 +1,741 @@
+import { assert } from "../../../../core/assert.js";
+import { GPUDatabase } from "../../buffer/table/GPUDatabase.js";
+import { GPUDatabaseReadback } from "../../buffer/table/GPUDatabaseReadback.js";
+import { GPUReadbackStatus } from "../../buffer/table/GPUReadbackStatus.js";
+import { gpu_table_gather_shader } from "../../buffer/table/gpu_table_gather_shader.js";
+import { generate_record_writer } from "../../buffer/table/serde/generate_record_writer.js";
+import { decode_octahedral_u32_to_normal } from "../../geometry/normals/decode_octahedral_u32_to_normal.js";
+import { WEBGPU_GUARANTEED_MAX_COMPUTE_WORKGROUPS_PER_DIMENSION } from "../../gpu_primitive/indirect/WEBGPU_GUARANTEED_MAX_COMPUTE_WORKGROUPS_PER_DIMENSION.js";
+import { WATER_BAND_SAMPLER } from "../surface/GPUWaterSurface.js";
+import {
+    WATER_QUERY_DATABASE_INITIAL_SIZE,
+    WATER_QUERY_DATABASE_SPEC,
+    WATER_QUERY_SAMPLE_DESCRIPTOR,
+    WATER_QUERY_SAMPLE_STRUCT,
+    WATER_QUERY_SAMPLE_TABLE,
+    WATER_QUERY_STRUCT,
+    WATER_QUERY_TABLE
+} from "./WATER_QUERY_DATABASE_SPEC.js";
+import {
+    shader_water_surface_query,
+    WATER_QUERY_GATHER_ENTRY_WORDS,
+    WATER_QUERY_GATHER_WORKGROUP_SIZE
+} from "./shader_water_surface_query.js";
+
+/**
+ * @typedef {import("../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} FrameGraph
+ * @typedef {import("../surface/GPUWaterSurface.js").GPUWaterSurface} GPUWaterSurface
+ * @typedef {import("../../../device/pipeline/PipelineEnquiry.js").PipelineEnquiry} PipelineEnquiry
+ */
+
+/**
+ * Floats a query sample lands as in a request's target: the displaced world height `y`, followed by
+ * the unpacked world-space unit normal `(nx, ny, nz)`.
+ * @type {number}
+ */
+export const WATER_QUERY_SAMPLE_FLOATS = 4;
+
+const QUERY_WRITER = generate_record_writer(WATER_QUERY_STRUCT);
+const SAMPLE_WRITER = generate_record_writer(WATER_QUERY_SAMPLE_STRUCT);
+
+/** Bytes of a GPU sample row (8 bytes: f32 height + u32 octahedral normal). */
+const SAMPLE_BYTES = WATER_QUERY_SAMPLE_DESCRIPTOR.packed_element_size_bytes;
+
+/** 32-bit words of a GPU sample row in the staging slot. */
+const SAMPLE_WORDS = SAMPLE_BYTES >>> 2;
+
+/** Invocations a row of a gather dispatch holds along x. */
+const ROW_WIDTH = WEBGPU_GUARANTEED_MAX_COMPUTE_WORKGROUPS_PER_DIMENSION * WATER_QUERY_GATHER_WORKGROUP_SIZE;
+
+/** Entries every per-request list starts with, doubling. */
+const INITIAL_CAPACITY = 16;
+
+/*
+ Words of an in-flight request, FLIGHT_WORDS a request.
+*/
+const F_HANDLE = 0;
+const F_TAG = 1;
+const F_QUERY_ROW = 2;
+const F_FIRST_SAMPLE = 3;
+const F_SAMPLE_COUNT = 4;
+const F_SLOT = 5;
+const F_SLOT_OFFSET = 6;
+const F_TARGET_OFFSET = 7;
+const FLIGHT_WORDS = 8;
+
+/**
+ * A frame's packed 8-byte `(f32 height, u32 normal)` samples land here, back to back, before they
+ * are unpacked into the targets their requests named. Pooled, and in use until every request of its
+ * frame has settled.
+ */
+class StagingSlot {
+    /** @type {Float32Array} */
+    floats = new Float32Array(0);
+
+    /** @type {Uint32Array} */
+    u32s = new Uint32Array(0);
+
+    /** @type {Uint8Array} */
+    bytes = new Uint8Array(0);
+
+    /** Requests of the slot's frame not yet settled. */
+    live = 0;
+}
+
+/**
+ * @param {Uint32Array|Float32Array|Float64Array|Uint8Array} array
+ * @param {number} length
+ * @returns {any} `array`, or a copy of it at least `length` long
+ */
+function fit(array, length) {
+    if (array.length >= length) {
+        return array;
+    }
+
+    const grown = new array.constructor(Math.max(length, 2 * array.length));
+
+    grown.set(array);
+
+    return grown;
+}
+
+/**
+ * # The GPU water surface read API, on the device
+ *
+ * Evaluates displaced water height and world-space normal at batches of local `(x, z)` points on
+ * water bodies, reading the compact 8-byte `(f32 height, u32 octahedral_normal)` rows back to the
+ * CPU and unpacking them into the caller's `Float32Array` target as 4 floats per sample
+ * (`[world_height, nx, ny, nz]`).
+ */
+export class GPUWaterQueries {
+
+    /**
+     * Offer the pipelines the read API dispatches — see {@link PipelineEnquiry}.
+     *
+     * @param {PipelineEnquiry} enquiry
+     */
+    static enquirePipelines(enquiry) {
+        GPUDatabase.enquirePipelines(enquiry);
+        enquiry.compute.push(shader_water_surface_query.pipeline);
+        enquiry.compute.push(gpu_table_gather_shader.pipeline);
+    }
+
+    /** @type {GPUDatabase} */
+    #database;
+
+    /** @type {GPUDatabaseReadback} */
+    #readback;
+
+    /** The sample table's readback handle. */
+    #samples;
+
+    /** @type {import("../../buffer/table/GPUTypedTable.js").GPUTypedTable} */
+    #query_table;
+
+    /** @type {import("../../buffer/table/GPUTypedTable.js").GPUTypedTable} */
+    #sample_table;
+
+    /** The staging record a request's row is written from. */
+    #query_record = {
+        body: 0,
+        first_sample: 0,
+        sample_count: 0,
+        footprint: 0,
+    };
+
+    /** What a sample row holds until the gather writes it. */
+    #empty_sample = {
+        height: 0,
+        normal: 0,
+    };
+
+    /*
+     Requests asked for and not yet recorded.
+    */
+    #asked_bodies = new Uint32Array(INITIAL_CAPACITY);
+    #asked_counts = new Uint32Array(INITIAL_CAPACITY);
+    #asked_footprints = new Float32Array(INITIAL_CAPACITY);
+    #asked_offsets = new Uint32Array(INITIAL_CAPACITY);
+    #asked_tags = new Uint32Array(INITIAL_CAPACITY);
+    /** @type {(Float32Array|null)[]} */
+    #asked_targets = [];
+    #asked_points = new Float32Array(2 * INITIAL_CAPACITY);
+    #asked_point_count = 0;
+    #asked_count = 0;
+
+    /*
+     Requests recorded and not yet settled, in the order they were recorded: FLIGHT_WORDS words each,
+     and the target beside them.
+    */
+    #flight = new Uint32Array(FLIGHT_WORDS * INITIAL_CAPACITY);
+    /** @type {(Float32Array|null)[]} */
+    #flight_targets = [];
+    #flight_count = 0;
+
+    /*
+     What the last apply settled, in the order the requests were recorded.
+    */
+    #settled_tags = new Uint32Array(INITIAL_CAPACITY);
+    #settled_status = new Uint8Array(INITIAL_CAPACITY);
+    #settled_count = 0;
+
+    /** @type {StagingSlot[]} */
+    #slots = [];
+
+    /** Pass records not in a graph. */
+    #free_passes = [];
+
+    /** The gather's settings, rewritten for every dispatch. */
+    #settings = { query_count: 0, sample_count: 0, row_width: ROW_WIDTH };
+
+    /** Bindings of the gather, rebound for every dispatch. */
+    #dispatch = {
+        encoder: null,
+        thread_count_x: 0,
+        thread_count_y: 1,
+        thread_count_z: 1,
+        bindings: {
+            settings: null,
+            database: null,
+            list: null,
+            scene_database: null,
+            water_band_displacement: null,
+            water_band_derivatives: null,
+            water_band_sampler: null,
+            water_particle_offsets: null,
+            water_particle_entries: null,
+            geometries: null,
+            blas_lookup: null,
+            blas_data: null,
+            meshlet_metadata: null,
+            meshlet_data: null,
+        },
+    };
+
+    #destroyed = false;
+
+    /**
+     * @param {object} options
+     * @param {GPUDevice} options.device
+     */
+    constructor({ device }) {
+        assert.defined(device, 'device');
+
+        this.#database = new GPUDatabase({
+            device,
+            definition: WATER_QUERY_DATABASE_SPEC,
+            label: 'Water / query',
+            initial_data_size_bytes: WATER_QUERY_DATABASE_INITIAL_SIZE,
+        });
+
+        this.#readback = new GPUDatabaseReadback({
+            database: this.#database,
+            device,
+            label: 'Water / query / readback',
+        });
+
+        this.#samples = this.#readback.table(WATER_QUERY_SAMPLE_TABLE);
+
+        this.#query_table = this.#database.get(WATER_QUERY_TABLE);
+        this.#sample_table = this.#database.get(WATER_QUERY_SAMPLE_TABLE);
+
+        this.#query_table.occupancy.preventShrink();
+        this.#sample_table.occupancy.preventShrink();
+    }
+
+    /**
+     * The read API's database. For inspection.
+     * @returns {GPUDatabase}
+     */
+    get database() {
+        return this.#database;
+    }
+
+    /**
+     * The readback the samples travel through. For inspection.
+     * @returns {GPUDatabaseReadback}
+     */
+    get readback() {
+        return this.#readback;
+    }
+
+    /**
+     * Requests holding rows: recorded and not yet delivered or dropped.
+     * @returns {number}
+     */
+    get in_flight_count() {
+        return this.#flight_count;
+    }
+
+    /**
+     * Rows of `water_query`: one per request in flight.
+     * @returns {number}
+     */
+    get query_count() {
+        return this.#query_table.count;
+    }
+
+    /**
+     * Rows of `water_query_sample`: the sample points of every request in flight.
+     * @returns {number}
+     */
+    get sample_count() {
+        return this.#sample_table.count;
+    }
+
+    /**
+     * Requests the last {@link apply} (or {@link destroy}) settled.
+     * @returns {number}
+     */
+    get settled_count() {
+        return this.#settled_count;
+    }
+
+    /**
+     * @param {number} index below {@link settled_count}
+     * @returns {number} the tag the settled request was asked with
+     */
+    settled_tag(index) {
+        return this.#settled_tags[index];
+    }
+
+    /**
+     * @param {number} index below {@link settled_count}
+     * @returns {number} a {@link GPUReadbackStatus}: `Delivered`, its samples now unpacked into its
+     *   target, or `Dropped`
+     */
+    settled_status(index) {
+        return this.#settled_status[index];
+    }
+
+    /**
+     * Ask for `sample_count` water surface samples on `water_bodies` row `body`, at local `(x, z)`
+     * coordinates read from `local_xz` starting at `local_xz_offset`. When settled `Delivered`,
+     * each sample is unpacked into `target` from `target_offset` as {@link WATER_QUERY_SAMPLE_FLOATS}
+     * floats (`[world_height, nx, ny, nz]`).
+     *
+     * @param {number} body row in `water_bodies`
+     * @param {ArrayLike<number>} local_xz interleaved `[x0, z0, x1, z1, ...]`
+     * @param {number} local_xz_offset offset in `local_xz`
+     * @param {number} sample_count number of `(x, z)` points, at least 1
+     * @param {number} footprint spatial filter footprint in metres, at least 0
+     * @param {Float32Array} target
+     * @param {number} target_offset in floats
+     * @param {number} tag the caller's, a u32, reported back when the request settles
+     */
+    request(body, local_xz, local_xz_offset, sample_count, footprint, target, target_offset, tag) {
+        assert.notOk(this.#destroyed, 'destroyed');
+
+        const i = this.#asked_count;
+
+        if (i + 1 > this.#asked_bodies.length) {
+            this.#asked_bodies = fit(this.#asked_bodies, i + 1);
+            this.#asked_counts = fit(this.#asked_counts, i + 1);
+            this.#asked_footprints = fit(this.#asked_footprints, i + 1);
+            this.#asked_offsets = fit(this.#asked_offsets, i + 1);
+            this.#asked_tags = fit(this.#asked_tags, i + 1);
+        }
+
+        const point_start = this.#asked_point_count;
+        const next_point_count = point_start + sample_count;
+
+        if (2 * next_point_count > this.#asked_points.length) {
+            this.#asked_points = fit(this.#asked_points, 2 * next_point_count);
+        }
+
+        const points = this.#asked_points;
+
+        for (let k = 0; k < 2 * sample_count; k++) {
+            points[2 * point_start + k] = local_xz[local_xz_offset + k];
+        }
+
+        this.#asked_bodies[i] = body;
+        this.#asked_counts[i] = sample_count;
+        this.#asked_footprints[i] = footprint;
+        this.#asked_offsets[i] = target_offset;
+        this.#asked_tags[i] = tag;
+        this.#asked_targets[i] = target;
+
+        this.#asked_point_count = next_point_count;
+        this.#asked_count = i + 1;
+    }
+
+    /**
+     * A staging slot free to take `words` 32-bit words.
+     *
+     * @param {number} words
+     * @returns {number} its index
+     */
+    #take_slot(words) {
+        const slots = this.#slots;
+
+        let index = -1;
+
+        for (let i = 0; i < slots.length; i++) {
+            if (slots[i].live !== 0) {
+                continue;
+            }
+
+            if (slots[i].floats.length >= words) {
+                index = i;
+                break;
+            }
+
+            if (index === -1) {
+                index = i;
+            }
+        }
+
+        if (index === -1) {
+            index = slots.length;
+            slots.push(new StagingSlot());
+        }
+
+        const slot = slots[index];
+
+        if (slot.floats.length < words) {
+            slot.floats = new Float32Array(Math.max(words, 2 * slot.floats.length));
+            slot.u32s = new Uint32Array(slot.floats.buffer);
+            slot.bytes = new Uint8Array(slot.floats.buffer);
+        }
+
+        return index;
+    }
+
+    /**
+     * Make the frame's requests rows and record their pass into `graph`: the database's upload, the
+     * gather, and the readback's encode. Recorded after `GPUWaterSurface.record` so the frame's
+     * spectrum bands, wave particle hash, and body rows are ready.
+     *
+     * @param {object} options
+     * @param {FrameGraph} options.graph
+     * @param {object} options.scene GPU scene context
+     * @param {GPUWaterSurface} options.surface the water surface producer
+     * @returns {boolean} whether a pass was recorded
+     */
+    record({ graph, scene, surface }) {
+        assert.notOk(this.#destroyed, 'destroyed');
+        assert.defined(graph, 'graph');
+        assert.defined(scene, 'scene');
+        assert.defined(surface, 'surface');
+
+        const count = this.#asked_count;
+
+        if (count === 0) {
+            return false;
+        }
+
+        const total = this.#asked_point_count;
+        const slot_index = this.#take_slot(SAMPLE_WORDS * total);
+        const slot = this.#slots[slot_index];
+
+        const pass = this.#free_passes.pop() ?? {
+            queries: this,
+            scene: null,
+            surface: null,
+            list: new Uint32Array(0),
+            list_f32: new Float32Array(0),
+            query_count: 0,
+            sample_count: 0,
+        };
+
+        const list_words = WATER_QUERY_GATHER_ENTRY_WORDS * (count + total);
+
+        if (pass.list.length < list_words) {
+            pass.list = new Uint32Array(Math.max(list_words, 2 * pass.list.length));
+            pass.list_f32 = new Float32Array(pass.list.buffer);
+        }
+
+        const flight_end = this.#flight_count + count;
+
+        this.#flight = fit(this.#flight, FLIGHT_WORDS * flight_end);
+
+        const bodies = this.#asked_bodies;
+        const counts = this.#asked_counts;
+        const footprints = this.#asked_footprints;
+        const points = this.#asked_points;
+        const record = this.#query_record;
+        const empty_sample = this.#empty_sample;
+        const query_table = this.#query_table;
+        const sample_table = this.#sample_table;
+        const readback = this.#readback;
+        const list = pass.list;
+        const list_f32 = pass.list_f32;
+        const flight = this.#flight;
+
+        let first_of_frame = 0;
+
+        for (let i = 0; i < count; i++) {
+            const samples = counts[i];
+
+            const first_sample = sample_table.add_run_filled(samples, empty_sample, SAMPLE_WRITER);
+
+            record.body = bodies[i];
+            record.first_sample = first_sample;
+            record.sample_count = samples;
+            record.footprint = footprints[i];
+
+            const query_row = query_table.add_record(record, QUERY_WRITER);
+
+            const handle = readback.request_run(
+                this.#samples,
+                first_sample,
+                samples,
+                0,
+                SAMPLE_BYTES,
+                slot.bytes,
+                first_of_frame * SAMPLE_BYTES
+            );
+
+            const f = this.#flight_count * FLIGHT_WORDS;
+
+            flight[f + F_HANDLE] = handle;
+            flight[f + F_TAG] = this.#asked_tags[i];
+            flight[f + F_QUERY_ROW] = query_row;
+            flight[f + F_FIRST_SAMPLE] = first_sample;
+            flight[f + F_SAMPLE_COUNT] = samples;
+            flight[f + F_SLOT] = slot_index;
+            flight[f + F_SLOT_OFFSET] = SAMPLE_WORDS * first_of_frame;
+            flight[f + F_TARGET_OFFSET] = this.#asked_offsets[i];
+
+            this.#flight_targets[this.#flight_count] = this.#asked_targets[i];
+            this.#flight_count++;
+
+            this.#asked_targets[i] = null;
+
+            list[WATER_QUERY_GATHER_ENTRY_WORDS * i] = query_row;
+            list[WATER_QUERY_GATHER_ENTRY_WORDS * i + 1] = first_of_frame;
+
+            first_of_frame += samples;
+        }
+
+        const point_word_start = WATER_QUERY_GATHER_ENTRY_WORDS * count;
+
+        for (let k = 0; k < 2 * total; k++) {
+            list_f32[point_word_start + k] = points[k];
+        }
+
+        // Sample rows are written exclusively by shader_water_surface_query; discard queued dummy uploads.
+        sample_table.element_upload_buffer.position = 0;
+
+        slot.live += count;
+
+        this.#asked_point_count = 0;
+        this.#asked_count = 0;
+
+        pass.scene = scene;
+        pass.surface = surface;
+        pass.query_count = count;
+        pass.sample_count = total;
+
+        graph.add('Water / surface queries', pass, GPUWaterQueries.#execute).make_side_effect();
+
+        return true;
+    }
+
+    static #execute(pass, resources, context) {
+        const queries = pass.queries;
+
+        try {
+            if (!queries.#destroyed) {
+                queries.#encode(context.encoder, pass);
+            }
+        } finally {
+            pass.scene = null;
+            pass.surface = null;
+            queries.#free_passes.push(pass);
+        }
+    }
+
+    #encode(encoder, pass) {
+        const database = this.#database;
+
+        if (database.has_pending_upload) {
+            database.update(encoder);
+        }
+
+        const settings = this.#settings;
+        const sample_count = pass.sample_count;
+
+        settings.query_count = pass.query_count;
+        settings.sample_count = sample_count;
+
+        const scene = pass.scene;
+        const surface = pass.surface;
+        const geometries = scene.geometries;
+        const dispatch = this.#dispatch;
+        const b = dispatch.bindings;
+
+        b.settings = settings;
+        b.database = database.buffer;
+        b.list = encoder.allocateTransientBufferAndLoad(
+            pass.list.buffer,
+            GPUBufferUsage.STORAGE,
+            0,
+            4 * WATER_QUERY_GATHER_ENTRY_WORDS * (pass.query_count + sample_count)
+        );
+        b.scene_database = scene.scene_database_buffer;
+        b.water_band_displacement = surface.displacement;
+        b.water_band_derivatives = surface.derivatives;
+        b.water_band_sampler = WATER_BAND_SAMPLER;
+        b.water_particle_offsets = surface.particle_offsets;
+        b.water_particle_entries = surface.particle_entries;
+        b.geometries = geometries.buffer_metadata;
+        b.blas_lookup = geometries.blas.buffer_metadata;
+        b.blas_data = geometries.blas.buffer_data;
+        b.meshlet_metadata = geometries.meshlets.buffer_metadata;
+        b.meshlet_data = geometries.meshlets.buffer_data;
+
+        dispatch.encoder = encoder;
+        dispatch.thread_count_x = sample_count < ROW_WIDTH ? sample_count : ROW_WIDTH;
+        dispatch.thread_count_y = Math.ceil(sample_count / ROW_WIDTH);
+
+        shader_water_surface_query.dispatchThreads(dispatch);
+
+        dispatch.encoder = null;
+        b.settings = b.database = b.list = b.scene_database = null;
+        b.water_band_displacement = b.water_band_derivatives = b.water_band_sampler = null;
+        b.water_particle_offsets = b.water_particle_entries = null;
+        b.geometries = b.blas_lookup = b.blas_data = b.meshlet_metadata = b.meshlet_data = null;
+
+        this.#readback.encode(encoder);
+    }
+
+    /**
+     * The apply point, once a frame (`WaterSystem#update`): the readback delivers every batch whose
+     * mapping has landed, oldest first, and starts the maps of the frames submitted since.
+     * Delivered samples are unpacked from `{ height: f32, normal: u32 }` into the caller's target as
+     * 4 floats (`[world_height, nx, ny, nz]`); rows of settled requests are freed.
+     */
+    apply() {
+        this.#settled_count = 0;
+
+        if (this.#destroyed) {
+            return;
+        }
+
+        this.#settle();
+
+        this.#readback.apply();
+
+        this.#settle();
+    }
+
+    /**
+     * Settle every request in flight whose handle the readback has answered, keeping the rest in
+     * order.
+     */
+    #settle() {
+        const status = this.#readback.status;
+        const flight = this.#flight;
+        const targets = this.#flight_targets;
+        const slots = this.#slots;
+        const count = this.#flight_count;
+
+        let kept = 0;
+
+        for (let i = 0; i < count; i++) {
+            const f = i * FLIGHT_WORDS;
+            const outcome = status[flight[f + F_HANDLE]];
+
+            if (outcome !== GPUReadbackStatus.Delivered && outcome !== GPUReadbackStatus.Dropped) {
+                if (kept !== i) {
+                    flight.copyWithin(kept * FLIGHT_WORDS, f, f + FLIGHT_WORDS);
+                    targets[kept] = targets[i];
+                }
+
+                kept++;
+
+                continue;
+            }
+
+            const samples = flight[f + F_SAMPLE_COUNT];
+            const slot = slots[flight[f + F_SLOT]];
+
+            if (outcome === GPUReadbackStatus.Delivered) {
+                const source_f32 = slot.floats;
+                const source_u32 = slot.u32s;
+                const target = targets[i];
+                const from = flight[f + F_SLOT_OFFSET];
+                const to = flight[f + F_TARGET_OFFSET];
+
+                for (let k = 0; k < samples; k++) {
+                    const dst = to + WATER_QUERY_SAMPLE_FLOATS * k;
+                    target[dst] = source_f32[from + 2 * k];
+                    decode_octahedral_u32_to_normal(target, dst + 1, source_u32[from + 2 * k + 1]);
+                }
+            }
+
+            this.#push_settled(flight[f + F_TAG], outcome);
+
+            this.#query_table.remove(flight[f + F_QUERY_ROW]);
+
+            const first = flight[f + F_FIRST_SAMPLE];
+            const sample_table = this.#sample_table;
+
+            for (let k = 0; k < samples; k++) {
+                sample_table.remove(first + k);
+            }
+
+            sample_table.element_upload_buffer.position = 0;
+
+            slot.live--;
+        }
+
+        for (let i = kept; i < count; i++) {
+            targets[i] = null;
+        }
+
+        this.#flight_count = kept;
+    }
+
+    /**
+     * @param {number} tag
+     * @param {number} status
+     */
+    #push_settled(tag, status) {
+        const i = this.#settled_count;
+
+        if (i === this.#settled_tags.length) {
+            this.#settled_tags = fit(this.#settled_tags, i + 1);
+            this.#settled_status = fit(this.#settled_status, i + 1);
+        }
+
+        this.#settled_tags[i] = tag;
+        this.#settled_status[i] = status;
+
+        this.#settled_count = i + 1;
+    }
+
+    /**
+     * Release the database and the readback, discarding any mapping still out. Every request asked
+     * or in flight settles `Dropped`, reported in {@link settled_count} as an {@link apply} would.
+     */
+    destroy() {
+        if (this.#destroyed) {
+            return;
+        }
+
+        this.#destroyed = true;
+        this.#settled_count = 0;
+
+        const flight = this.#flight;
+
+        for (let i = 0; i < this.#flight_count; i++) {
+            this.#push_settled(flight[i * FLIGHT_WORDS + F_TAG], GPUReadbackStatus.Dropped);
+            this.#flight_targets[i] = null;
+        }
+
+        for (let i = 0; i < this.#asked_count; i++) {
+            this.#push_settled(this.#asked_tags[i], GPUReadbackStatus.Dropped);
+            this.#asked_targets[i] = null;
+        }
+
+        this.#flight_count = 0;
+        this.#asked_point_count = 0;
+        this.#asked_count = 0;
+
+        this.#readback.destroy();
+        this.#database.destroy();
+    }
+}