@woosh/meep-engine 3.49.0 → 3.50.0

package/src/shade/renderer/Renderer.js

@@ -19,13 +19,16 @@ import { ShadeGPUCommandContext } from "../device/ShadeGPUCommandContext.js";
 import { CameraManager } from "./camera/CameraManager.js";
 import { shader_background } from "./deferred/shader_background.js";
 import { shader_composite_volumetrics } from "./deferred/shader_composite_volumetrics.js";
-import { shader_deferred_main, shader_deferred_main_restir } from "./deferred/shader_deferred_main.js";
+import { shader_deferred_main } from "./deferred/shader_deferred_main.js";
+import { LOCAL_LIGHT_SHADING } from "./deferred/LOCAL_LIGHT_SHADING.js";
+import { LocalLightShading } from "./deferred/LocalLightShading.js";
 import { shader_tonemap_HDR } from "./deferred/shader_tonemap_HDR.js";
 import { shader_tonemap_HDR_none } from "./deferred/shader_tonemap_HDR_none.js";
 import { shader_tonemap_HDR_pbr_neutral } from "./deferred/shader_tonemap_HDR_pbr_neutral.js";
 import { shader_tonemap_LDR } from "./deferred/shader_tonemap_LDR.js";
 import { shader_tonemap_LDR_none } from "./deferred/shader_tonemap_LDR_none.js";
 import { shader_tonemap_LDR_pbr_neutral } from "./deferred/shader_tonemap_LDR_pbr_neutral.js";
+import { TonemapDisplaySettings } from "./deferred/TonemapDisplaySettings.js";
 import { FrameContext } from "./extension/FrameContext.js";
 import { FramePhase } from "./extension/FramePhase.js";
 import { GBufferTextures } from "./extension/GBufferTextures.js";
@@ -97,6 +100,7 @@ import { graph_import_texture } from "./shader/graph/graph_import_texture.js";
 import { ShadeUpscalerType } from "./ShadeUpscalerType.js";
 import { DEFAULT_SHADOWMAP_UPDATE_BUDGET } from "./shadow/map/DEFAULT_SHADOWMAP_UPDATE_BUDGET.js";
 import { SHADOW_DIRECTIONAL_TECHNIQUE } from "./shadow/map/shader/SHADOW_DIRECTIONAL_TECHNIQUE.js";
+import { INDIRECT_LIGHTING } from "./INDIRECT_LIGHTING.js";
 import { ShadowDirectionalTechnique } from "./shadow/map/ShadowDirectionalTechnique.js";
 import { SHADOWMAP_CSM_DEFAULT_CASCADE_COUNT } from "./shadow/map/csm/SHADOWMAP_CSM_DEFAULT_CASCADE_COUNT.js";
 import { DEFAULT_VSM_FIRST_TEXEL_SIZE } from "./shadow/vsm/DEFAULT_VSM_FIRST_TEXEL_SIZE.js";
@@ -314,9 +318,10 @@ export class Renderer {
     /**
      * The values of the shader switches, for every pass this renderer records: what its feature flags
      * make of the switches its shaders decide ({@link SHADOW_DIRECTIONAL_TECHNIQUE} from
-     * {@link feature_virtual_shadow_maps}). A pass hands it to the shaders it draws with, which build
-     * their variant for it. Interned, so it stays the same object until a flag changes, and looking a
-     * variant up by it allocates nothing.
+     * {@link feature_virtual_shadow_maps}, {@link INDIRECT_LIGHTING} from {@link indirect_lighting_mode},
+     * {@link LOCAL_LIGHT_SHADING} from {@link feature_restir_di_enabled}).
+     * A pass hands it to the shaders it draws with, which build their variant for it. Interned, so it
+     * stays the same object until a flag changes, and looking a variant up by it allocates nothing.
      *
      * @type {ShaderSwitchSet}
      */
@@ -333,10 +338,16 @@ export class Renderer {
      * Bring {@link #shader_switches} up to the feature flags. Allocates nothing while they are unchanged.
      */
     #update_shader_switches() {
-        this.#shader_switches = this.#shader_switches.with(
-            SHADOW_DIRECTIONAL_TECHNIQUE,
-            this.feature_virtual_shadow_maps ? ShadowDirectionalTechnique.Virtual : ShadowDirectionalTechnique.Cascades
-        );
+        this.#shader_switches = this.#shader_switches
+            .with(
+                SHADOW_DIRECTIONAL_TECHNIQUE,
+                this.feature_virtual_shadow_maps ? ShadowDirectionalTechnique.Virtual : ShadowDirectionalTechnique.Cascades
+            )
+            .with(INDIRECT_LIGHTING, this.indirect_lighting_mode)
+            .with(
+                LOCAL_LIGHT_SHADING,
+                this.feature_restir_di_enabled ? LocalLightShading.ReSTIR : LocalLightShading.Clustered
+            );
     }
 
     /**
@@ -1069,13 +1080,14 @@ export class Renderer {
         const lpv = scene_ctx.light_probe_volume;
         let diffuse_pass;
         let specular_pass;
-        let ssr_inputs;
+        // the running mode's source, for SSR's resolve to fall back to; it is given no other mode's
+        let ssr_brick4;
+        let ssr_lpv;
 
         // Each mode owns its diffuse/specular pair and any fused implementation.
         // SSR overrides specular below using the same explicitly selected mode.
         switch (mode) {
             case ShadeIndirectLightingMode.IBL:
-                ssr_inputs = { input_environment: gr_texture_environment };
                 diffuse_pass = {
                     shader: shader_diffuse_IBL,
                     inputs: {
@@ -1122,7 +1134,7 @@ export class Renderer {
                     });
                     return current_color_out;
                 }
-                ssr_inputs = { brick4: scene_ctx.volumetric_light_map };
+                ssr_brick4 = scene_ctx.volumetric_light_map;
                 diffuse_pass = {
                     shader: shader_brick4_diffuse,
                     inputs: {
@@ -1150,7 +1162,7 @@ export class Renderer {
                 break;
 
             case ShadeIndirectLightingMode.LPV:
-                ssr_inputs = { lpv, input_environment: gr_texture_environment };
+                ssr_lpv = lpv;
                 diffuse_pass = {
                     shader: shader_diffuse_LPV,
                     inputs: {
@@ -1188,7 +1200,6 @@ export class Renderer {
         if (this.feature_ssr_enabled) {
             const ssr = this.#postprocess.ssr.graph_pass({
                 graph,
-                ...ssr_inputs,
                 view_ctx,
                 jitter: view_ctx.jitter,
                 input_depth_previous: gr_texture_depth_previous,
@@ -1202,7 +1213,10 @@ export class Renderer {
                 input_occlusion: gr_occlusion_clip,
                 camera_current: gr_buffer_camera_current,
                 camera_previous: gr_buffer_camera_previous,
-                indirect_lighting_mode: mode,
+                input_environment: gr_texture_environment,
+                brick4: ssr_brick4,
+                lpv: ssr_lpv,
+                shader_switches: this.#shader_switches,
                 resolution,
             });
 
@@ -1378,12 +1392,12 @@ export class Renderer {
     #hdr_supported = false;
 
     /**
-     * What's the peak brightness of the display?
-     * Only valid for HDR.
+     * What every tonemap pass is told about the display: the primaries the canvas was actually configured with, and
+     * the peak brightness, which only the HDR passes read.
      *
-     * @type {number}
+     * @type {TonemapDisplaySettings}
      */
-    #display_peak_brightness_nits = 1000;
+    #tonemap_settings = new TonemapDisplaySettings();
 
     #update_presentation_format() {
 
@@ -1413,10 +1427,10 @@ export class Renderer {
 
         if (isHDR) {
             // Currently, there is no way to interrogate this from the browser, so going with an assumption
-            this.#display_peak_brightness_nits = 1000;
+            this.#tonemap_settings.peak_nits = 1000;
         } else {
             // Assume SDR nits
-            this.#display_peak_brightness_nits = 80;
+            this.#tonemap_settings.peak_nits = 80;
         }
 
         if (isHDR === previous_value) {
@@ -1662,8 +1676,7 @@ export class Renderer {
         // workers than pipelines, the order they are asked for is roughly the order they start.
         this.#update_shader_switches();
 
-        const deferred_shader = (this.feature_restir_di_enabled ? shader_deferred_main_restir : shader_deferred_main)
-            .variant(this.#shader_switches);
+        const deferred_shader = shader_deferred_main.variant(this.#shader_switches);
 
         enquiry.render.push(deferred_shader.pipeline);
 
@@ -1913,16 +1926,29 @@ export class Renderer {
         };
 
 
+        let configured_color_space = preferred_color_space;
+
         try {
             context.configure(config);
         } catch (e) {
             // try fall-back colorspace
+            configured_color_space = 'srgb';
+
             context.configure({
                 ...config,
-                colorSpace: 'srgb'
+                colorSpace: configured_color_space
             });
         }
 
+        // The tonemap passes write in whatever primaries the canvas ended up with. Ask it rather than trust the
+        // request: a browser that does not know `colorSpace` ignores the member without throwing, and shows sRGB.
+        const configuration = context.getConfiguration?.();
+
+        if (configuration !== undefined && configuration !== null) {
+            configured_color_space = configuration.colorSpace ?? 'srgb';
+        }
+
+        this.#tonemap_settings.set_canvas_color_space(configured_color_space);
     }
 
     #apply_size() {
@@ -2677,6 +2703,7 @@ export class Renderer {
             camera: view_ctx.camera,
             hzb: gr_texture_hzb,
             resolution: view_ctx.resolution,
+            limits: graphics.collection_limits,
         });
 
         // The view's volumetrics: the fog every surface is seen through (participating media ->
@@ -2693,8 +2720,10 @@ export class Renderer {
             light_cluster_lookup: light_clusters.lookup,
             light_cluster_parameters: light_clusters.parameters,
             shadowmap_atlas: gr_shadowmap_atlas,
-            indirect_lighting_mode: this.indirect_lighting_mode,
             shader_switches: this.#shader_switches,
+            // the running mode's GI source, for froxel GI; it is given no other mode's
+            brick4: this.indirect_lighting_mode === ShadeIndirectLightingMode.Brick4 ? view_ctx.scene.volumetric_light_map : undefined,
+            lpv: this.indirect_lighting_mode === ShadeIndirectLightingMode.LPV ? view_ctx.scene.light_probe_volume : undefined,
         });
 
         /**
@@ -2704,12 +2733,8 @@ export class Renderer {
         let current_color_out = -1;
 
         // ReSTIR DI — stochastic direct lighting of local (point+spot) lights.
-        // When enabled, resolve per-pixel point+spot radiance and shade with the
-        // ReSTIR deferred variant (no brute-force cluster loop). The variant is a
-        // separate compiled shader, selected here at the JS level rather than via
-        // a runtime branch inside the shader.
-        let deferred_shader = shader_deferred_main;
-
+        // When enabled, resolve per-pixel point+spot radiance; the shader switches
+        // make the deferred pass read it in place of its cluster loop.
         const deferred_inputs = {
             gBufferDepth: gr_texture_depth_current,
             gBufferPBR: gr_texture_pbr,
@@ -2736,8 +2761,6 @@ export class Renderer {
         };
 
         if (this.feature_restir_di_enabled) {
-            deferred_shader = shader_deferred_main_restir;
-
             deferred_inputs.tRestirRadiance = this.#restir_di.execute({
                 graph,
                 view: view_ctx,
@@ -2758,7 +2781,7 @@ export class Renderer {
         // Main shading pass
         [current_color_out] = graph_image_pass({
             graph,
-            shader: deferred_shader.variant(this.#shader_switches),
+            shader: shader_deferred_main.variant(this.#shader_switches),
             input_depth: gr_texture_depth_current,
             inputs: deferred_inputs,
             output_resolution: view_ctx.resolution,
@@ -2956,7 +2979,6 @@ export class Renderer {
                 volumetrics_metadata: volumetrics.metadata,
                 volumetrics_irradiance: volumetrics.irradiance,
 
-                indirect_lighting_mode: this.indirect_lighting_mode,
                 shader_switches: this.#shader_switches,
                 avboit: this.avboit,
                 side_channels,
@@ -3155,33 +3177,18 @@ export class Renderer {
 
         current_color_out = record_scene_color.color;
 
-        const tonemap = this.#tonemap_shader();
-
-        if (tonemap === shader_tonemap_HDR || tonemap === shader_tonemap_HDR_pbr_neutral) {
-            // an operator on an HDR display is told the display's peak; the paper white is a constant
-            [current_color_out] = graph_image_pass({
-                graph,
-                shader: tonemap,
-                inputs: {
-                    input_color: current_color_out,
-                    settings: {
-                        peak_nits: this.#display_peak_brightness_nits,
-                    },
-                    exposure
-                },
-                output: [gr_texture_canvas]
-            });
-        } else {
-            [current_color_out] = graph_image_pass({
-                graph,
-                shader: tonemap,
-                inputs: {
-                    input_color: current_color_out,
-                    exposure
-                },
-                output: [gr_texture_canvas]
-            });
-        }
+        // every pass reads from the settings only the members its immediate struct names: the canvas's primaries
+        // from its working space, and, on an HDR display, the peak
+        [current_color_out] = graph_image_pass({
+            graph,
+            shader: this.#tonemap_shader(),
+            inputs: {
+                input_color: current_color_out,
+                settings: this.#tonemap_settings,
+                exposure
+            },
+            output: [gr_texture_canvas]
+        });
 
         /*
          The canvas is written here and cannot be read: a texture may not be a render attachment and

package/src/shade/renderer/STATIC_GRAPHICS_ENGINE_ASSET_RESOURCES.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Spatio-temporal blue noise, two channels (`STATIC_GRAPHICS_ENGINE_ASSETS.stbn_vec2`).
+ * @type {ShaderResourceDescriptor}
+ */
+export const STBN_VEC2_RESOURCE: ShaderResourceDescriptor;
+/**
+ * Spatio-temporal blue noise, three channels (`STATIC_GRAPHICS_ENGINE_ASSETS.stbn_vec3`).
+ * @type {ShaderResourceDescriptor}
+ */
+export const STBN_VEC3_RESOURCE: ShaderResourceDescriptor;
+/**
+ * The split-sum DFG lookup (`STATIC_GRAPHICS_ENGINE_ASSETS.split_sum`), sampled linearly.
+ * @type {ShaderResourceDescriptor}
+ */
+export const SPLIT_SUM_LUT_RESOURCE: ShaderResourceDescriptor;
+import { ShaderResourceDescriptor } from "./shader/resource/ShaderResourceDescriptor.js";
+//# sourceMappingURL=STATIC_GRAPHICS_ENGINE_ASSET_RESOURCES.d.ts.map

package/src/shade/renderer/STATIC_GRAPHICS_ENGINE_ASSET_RESOURCES.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"STATIC_GRAPHICS_ENGINE_ASSET_RESOURCES.d.ts","sourceRoot":"","sources":["../../../../src/shade/renderer/STATIC_GRAPHICS_ENGINE_ASSET_RESOURCES.js"],"names":[],"mappings":"AAEA;;;GAGG;AACH,iCAFU,wBAAwB,CAE2E;AAE7G;;;GAGG;AACH,iCAFU,wBAAwB,CAE2E;AAE7G;;;GAGG;AACH,qCAFU,wBAAwB,CAE2D;yCAlBpD,+CAA+C"}

package/src/shade/renderer/STATIC_GRAPHICS_ENGINE_ASSET_RESOURCES.js

@@ -0,0 +1,19 @@
+import { ShaderResourceDescriptor } from "./shader/resource/ShaderResourceDescriptor.js";
+
+/**
+ * Spatio-temporal blue noise, two channels (`STATIC_GRAPHICS_ENGINE_ASSETS.stbn_vec2`).
+ * @type {ShaderResourceDescriptor}
+ */
+export const STBN_VEC2_RESOURCE = ShaderResourceDescriptor.texture("tSTBN_vec2", "unfilterable-float", "3d");
+
+/**
+ * Spatio-temporal blue noise, three channels (`STATIC_GRAPHICS_ENGINE_ASSETS.stbn_vec3`).
+ * @type {ShaderResourceDescriptor}
+ */
+export const STBN_VEC3_RESOURCE = ShaderResourceDescriptor.texture("tSTBN_vec3", "unfilterable-float", "3d");
+
+/**
+ * The split-sum DFG lookup (`STATIC_GRAPHICS_ENGINE_ASSETS.split_sum`), sampled linearly.
+ * @type {ShaderResourceDescriptor}
+ */
+export const SPLIT_SUM_LUT_RESOURCE = ShaderResourceDescriptor.texture("tSplitSum", "float");

package/src/shade/renderer/buffer/table/GPUDatabase.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUDatabase.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/buffer/table/GPUDatabase.js"],"names":[],"mappings":"AA4CA;;;;;;;;;GASG;AACH;IAEI;;;;OAIG;IACH,iCAFW,eAAe,QAKzB;IA8FD;;;;;;OAMG;IACH;QAL0C,UAAU,EAAzC,qBAAqB;QACF,MAAM;QACR,KAAK,GAAtB,MAAM;QACW,uBAAuB,GAAxC,MAAM;OAkJhB;IAlPD;;;OAGG;IACH,YAFU,qBAAqB,CAEpB;IAEX;;;;OAIG;IACH,QAFU,oBAAe,CAElB;IASP;;;OAGG;IACH,kBAAO;IAmDP;;OAEG;IACH,8BAEC;IAED;;;;OAIG;IACH,oBAEC;IA2JD;;;;;OAKG;IACH,UAHW,MAAM,GACJ,qBAAc,SAAS,CAUnC;IAGD;;;;;;;;;;;OAWG;IACH,oCAcC;IAED;;;;;OAKG;IACH,gCAEC;IAoPD;;;;;;;;;;;OAWG;IACH,kCAeC;IAED;;;OAGG;IACH,gBAFW,sBAAsB,QA6FhC;IA+OD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACH,2BAJW,MAAM,GACJ,QAAQ,KAAG,CAAC,CA6HxB;IAED;;;;;;;OAOG;IACH,+BAJW,MAAM,iBACN,MAAM,GACJ,YAAU,CAkCtB;IAED;;;OAGG;IACH,+BAQC;IAED;;OAEG;IACH,gBASC;;CACJ;8BAppCY,OAAO,6CAA6C,EAAE,eAAe;qCACrE,OAAO,2CAA2C,EAAE,sBAAsB;oCAC1E,OAAO,4BAA4B,EAAE,qBAAqB;8BAPzC,oBAAoB;oCALd,0BAA0B"}
+{"version":3,"file":"GPUDatabase.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/buffer/table/GPUDatabase.js"],"names":[],"mappings":"AA4CA;;;;;;;;;GASG;AACH;IAEI;;;;OAIG;IACH,iCAFW,eAAe,QAKzB;IA8FD;;;;;;OAMG;IACH;QAL0C,UAAU,EAAzC,qBAAqB;QACF,MAAM;QACR,KAAK,GAAtB,MAAM;QACW,uBAAuB,GAAxC,MAAM;OAkJhB;IAlPD;;;OAGG;IACH,YAFU,qBAAqB,CAEpB;IAEX;;;;OAIG;IACH,QAFU,oBAAe,CAElB;IASP;;;OAGG;IACH,kBAAO;IAmDP;;OAEG;IACH,8BAEC;IAED;;;;OAIG;IACH,oBAEC;IA2JD;;;;;OAKG;IACH,UAHW,MAAM,GACJ,qBAAc,SAAS,CAUnC;IAGD;;;;;;;;;;;OAWG;IACH,oCAcC;IAED;;;;;OAKG;IACH,gCAEC;IAoPD;;;;;;;;;;;OAWG;IACH,kCAeC;IAED;;;OAGG;IACH,gBAFW,sBAAsB,QA6FhC;IAkPD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACH,2BAJW,MAAM,GACJ,QAAQ,KAAG,CAAC,CA6HxB;IAED;;;;;;;OAOG;IACH,+BAJW,MAAM,iBACN,MAAM,GACJ,YAAU,CAkCtB;IAED;;;OAGG;IACH,+BAQC;IAED;;OAEG;IACH,gBASC;;CACJ;8BAvpCY,OAAO,6CAA6C,EAAE,eAAe;qCACrE,OAAO,2CAA2C,EAAE,sBAAsB;oCAC1E,OAAO,4BAA4B,EAAE,qBAAqB;8BAPzC,oBAAoB;oCALd,0BAA0B"}

package/src/shade/renderer/buffer/table/GPUDatabase.js

@@ -834,7 +834,9 @@ export class GPUDatabase {
 
         assert.isNonNegativeInteger(total_descriptor_count, 'total_descriptor_count');
 
-        const descriptor_words = new Uint32Array(descriptors.data, 0, descriptor_cursor / word_size);
+        // read in place — the buffer already carries a view and the order its words were written in
+        const descriptor_view = descriptors.dataView;
+        const endianness = descriptors.endianness;
 
         const table_descriptor = table.descriptor;
 
@@ -843,7 +845,7 @@ export class GPUDatabase {
         let descriptors_uploaded = 0;
 
         while (descriptors_uploaded < total_descriptor_count) {
-            const chunk_data_start = descriptor_words[descriptors_uploaded * GPU_TABLE_PARTIAL_UPLOAD_DESCRIPTOR_WORDS + 3];
+            const chunk_data_start = descriptor_view.getUint32((descriptors_uploaded * GPU_TABLE_PARTIAL_UPLOAD_DESCRIPTOR_WORDS + 3) * word_size, endianness);
 
             let chunk_count = 0;
             let chunk_data_end = chunk_data_start;
@@ -852,8 +854,9 @@ export class GPUDatabase {
                 chunk_count < max_descriptors_per_chunk
                 && descriptors_uploaded + chunk_count < total_descriptor_count
                 ) {
-                const base = (descriptors_uploaded + chunk_count) * GPU_TABLE_PARTIAL_UPLOAD_DESCRIPTOR_WORDS;
-                const range_end = descriptor_words[base + 3] + descriptor_words[base + 2];
+                const base = (descriptors_uploaded + chunk_count) * descriptor_stride;
+                const range_end = descriptor_view.getUint32(base + 3 * word_size, endianness)
+                    + descriptor_view.getUint32(base + 2 * word_size, endianness);
                 const next_data_end = Math.max(chunk_data_end, range_end);
 
                 // Always take one descriptor, however big its range — a range can't exceed a

package/src/shade/renderer/buffer/table/GPUDatabaseReadback.d.ts

@@ -18,6 +18,14 @@
  * shader packs a batch contiguously in request order, so a consumer's run of rows lands in its
  * destination as one `set` — which a per-row function could never have done.
  *
+ * **A run is one request.** {@link request_run} asks for the same byte range of consecutive rows —
+ * the rows of an `add_run`, say — under one handle and one status. It is split at page boundaries
+ * here, never by the caller, and its ranges land back to back in the target. It is all or nothing:
+ * Delivered only when every row is, Dropped when any row is (not resident at encode, not occupied,
+ * or freed while in flight), and it counts once in {@link delivered_count}, {@link dropped_count}
+ * and {@link stalled_count}. A run of whole records is one copy per page it touches rather than one
+ * per row.
+ *
  * **Gather, then one copy.** Rows sit at scattered offsets across pages, so a compute shader packs
  * the requested ranges contiguously before a single copy into a readback buffer. Packing a *range*
  * rather than a record is what makes it worth doing: an entity's world matrix is 64 bytes of a
@@ -51,7 +59,7 @@ export class GPUDatabaseReadback {
      * @param {Object} options
      * @param {import("./GPUDatabase.js").GPUDatabase} options.database
      * @param {GPUDevice} options.device
-     * @param {number} [options.gather_threshold] requests at or above which a dispatch is used
+     * @param {number} [options.gather_threshold] copies at or above which a dispatch is used
      * @param {number} [options.max_in_flight] batches in flight before a frame's requests are dropped
      * @param {string} [options.label]
      */
@@ -63,7 +71,8 @@ export class GPUDatabaseReadback {
         label?: string;
     });
     /**
-     * Requests at or above which a batch is gathered rather than copied range by range.
+     * Copies at or above which a batch is gathered rather than copied range by range — see
+     * {@link DEFAULT_GATHER_THRESHOLD} for what counts as one.
      * @returns {number}
      */
     get gather_threshold(): number;
@@ -164,6 +173,27 @@ export class GPUDatabaseReadback {
      * @returns {number} a handle into {@link status}, valid until the frame after its result lands
      */
     request(table: number, row: number, byte_offset: number, byte_size: number, target: Uint8Array, target_byte_offset?: number): number;
+    /**
+     * Ask for the same byte range of `row_count` consecutive rows, landing back to back in `target`
+     * from `target_byte_offset` — row `first_row + i`'s range at `target_byte_offset + i * byte_size`
+     * — under one handle.
+     *
+     * The run may cross pages; it is split at their boundaries here. Its status is
+     * {@link GPUReadbackStatus.Delivered} only when every row was delivered, and
+     * {@link GPUReadbackStatus.Dropped} when any row was dropped — a page not resident or a row not
+     * occupied when the batch was encoded, a row freed while it was in flight, or the pipeline full
+     * — and then nothing of it is written.
+     *
+     * @param {number} table from {@link table}
+     * @param {number} first_row
+     * @param {number} row_count at least 1
+     * @param {number} byte_offset within each record, word-aligned
+     * @param {number} byte_size per row, a positive multiple of the word size
+     * @param {Uint8Array} target memory the caller owns and keeps, as for {@link request}
+     * @param {number} target_byte_offset where the first row's range lands
+     * @returns {number} a handle into {@link status}, valid until the frame after its result lands
+     */
+    request_run(table: number, first_row: number, row_count: number, byte_offset: number, byte_size: number, target: Uint8Array, target_byte_offset: number): number;
     /**
      * Deliver every batch whose bytes have arrived, oldest first and stopping at the first that has
      * not, then start the map for every batch whose frame has been submitted.

package/src/shade/renderer/buffer/table/GPUDatabaseReadback.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUDatabaseReadback.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/buffer/table/GPUDatabaseReadback.js"],"names":[],"mappings":"AA6LA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH;IA+II;;;;;;;OAOG;IACH;QAN2D,QAAQ,EAAxD,OAAO,kBAAkB,EAAE,WAAW;QACnB,MAAM;QACR,gBAAgB,GAAjC,MAAM;QACW,aAAa,GAA9B,MAAM;QACW,KAAK,GAAtB,MAAM;OAuBhB;IAED;;;OAGG;IACH,+BAEC;IAED;;;OAGG;IACH,4BAEC;IAED;;;;;;;;OAQG;IACH,yBAEC;IAED;;;;;OAKG;IACH,8BAEC;IAED;;;OAGG;IACH,4BAEC;IAED;;;OAGG;IACH,8BAEC;IAED;;;;;OAKG;IACH,6BAEC;IAED;;;OAGG;IACH,iCAEC;IAED;;;OAGG;IACH,8BAEC;IAED;;;;;;;;OAQG;IACH,4BAEC;IAED;;;;;;;OAOG;IACH,4BAEC;IAED;;;;;;;;;;OAUG;IACH,YAHW,MAAM,GACJ,MAAM,CAclB;IAED;;;;;;;;;;;;;;;OAeG;IACH,eAVW,MAAM,OACN,MAAM,eACN,MAAM,aACN,MAAM,UACN,UAAU,uBAGV,MAAM,GACJ,MAAM,CAgDlB;IAED;;;;;;;;;;;OAWG;IACH,SAFa,MAAM,CAiElB;IAED;;;;;OAKG;IACH,gBAHW,OAAO,2CAA2C,EAAE,sBAAsB,GACxE,OAAO,CAyDnB;IAijBD,gBAyBC;;CACJ"}
+{"version":3,"file":"GPUDatabaseReadback.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/buffer/table/GPUDatabaseReadback.js"],"names":[],"mappings":"AAoOA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AACH;IA+II;;;;;;;OAOG;IACH;QAN2D,QAAQ,EAAxD,OAAO,kBAAkB,EAAE,WAAW;QACnB,MAAM;QACR,gBAAgB,GAAjC,MAAM;QACW,aAAa,GAA9B,MAAM;QACW,KAAK,GAAtB,MAAM;OAuBhB;IAED;;;;OAIG;IACH,+BAEC;IAED;;;OAGG;IACH,4BAEC;IAED;;;;;;;;OAQG;IACH,yBAEC;IAED;;;;;OAKG;IACH,8BAEC;IAED;;;OAGG;IACH,4BAEC;IAED;;;OAGG;IACH,8BAEC;IAED;;;;;OAKG;IACH,6BAEC;IAED;;;OAGG;IACH,iCAEC;IAED;;;OAGG;IACH,8BAEC;IAED;;;;;;;;OAQG;IACH,4BAEC;IAED;;;;;;;OAOG;IACH,4BAEC;IAED;;;;;;;;;;OAUG;IACH,YAHW,MAAM,GACJ,MAAM,CAclB;IAED;;;;;;;;;;;;;;;OAeG;IACH,eAVW,MAAM,OACN,MAAM,eACN,MAAM,aACN,MAAM,UACN,UAAU,uBAGV,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACH,mBATW,MAAM,aACN,MAAM,aACN,MAAM,eACN,MAAM,aACN,MAAM,UACN,UAAU,sBACV,MAAM,GACJ,MAAM,CAkDlB;IAED;;;;;;;;;;;OAWG;IACH,SAFa,MAAM,CAiElB;IAED;;;;;OAKG;IACH,gBAHW,OAAO,2CAA2C,EAAE,sBAAsB,GACxE,OAAO,CAyDnB;IAgpBD,gBAyBC;;CACJ"}