@photivra/engine 2.21.0 → 2.23.0

package/dist/gpu/display-view-speed-gpu.d.ts

@@ -1,18 +1,4 @@
-/**
- * Host side of the display view's Speed path on the GPU (#478): the support check, the float64 tables (site table,
- * overlaps over the scale, axis sums over the squared scale, 1/Σw²), banded dispatch of
- * `DISPLAY_VIEW_SPEED_KERNEL_WGSL`, and the finishing the CPU reference does after its per-sample loop: the output
- * quantization term, the seeded noise draw, the Cholesky factor, the clipped-normal centre, the sRGB encode and the
- * rounding, all with the reference's own float64 functions. So the noise draw is bit-identical to the CPU's, and only
- * the expected value and the covariance carry the float32 bound.
- *
- * The float64 reference is `renderDisplayView` (facade/display-view.ts) on the exact-area-mean path without
- * diffraction, with the bilinear demosaic and chart materials. Internal: not exported from the package. The
- * material lookup per query point is a module the caller supplies (`DisplayViewGpuMaterialModule`, the seam of
- * #477); `display-view-chart-material-module.ts` provides one for the eight 2.0 chart presets and
- * `display-view-composite-material-module.ts` (#491) one for composite charts, the 2.3 elements and `material-layers` scenes.
- */
-import { type DisplayViewRenderResult, type DisplayViewSetup } from "../facade/display-view.js";
+import { type DisplayViewKernelTap, type DisplayViewRenderResult, type DisplayViewSetup } from "../facade/display-view.js";
 import { type DisplayViewExpectedSignalInput } from "../facade/expected-signal.js";
 import { resolvePortableChartScene } from "../facade/chart-scenes.js";
 import { type DisplayViewGpuConformanceCase, type DisplayViewGpuRenderer, type DisplayViewGpuRendererFactory, type DisplayViewGpuRequest } from "../facade/display-view-gpu.js";
@@ -90,7 +76,7 @@ export interface DisplayViewSpeedGpuResult extends DisplayViewRenderResult {
 /**
  * Why the kernel does not cover a request, or null when it does. The kernel is the Speed path: the exact area mean
  * (views where a footprint holds at most 25 real pixels and at most K², and here at most 6 per axis), no diffraction
- * kernels, chart materials, the bilinear demosaic (no AHD candidates or correction), the identity or positive Reinhard
+ * kernels, chart materials, the bilinear demosaic (no AHD candidates), the identity or positive Reinhard
  * tone curve, and at most 16 query offsets.
  */
 export declare function displayViewSpeedGpuUnsupportedReason(setup: DisplayViewSetup, signalInput: DisplayViewExpectedSignalInput): string | null;
@@ -203,4 +189,18 @@ export declare const displayViewSpeedGpuRendererFactory: DisplayViewGpuRendererF
  * registered before. Nothing registers it on import: the integration of #481 decides where the engine registers it.
  */
 export declare function registerDisplayViewSpeedGpuRenderer(): DisplayViewGpuRendererFactory | null;
+/** #564: the GPU refusal of a defocus kernel above the direct radius (the CPU convolves it by runs). */
+export declare const LARGE_DEFOCUS_REASON = "a defocus kernel radius above 64 sites (convolved by runs on the CPU, #564) is not on the GPU";
+/** The footprint shape of a view: real pixels per display pixel along each axis, and whether the exact area mean applies. */
+export declare function footprintShape(setup: DisplayViewSetup): {
+    sx: number;
+    sy: number;
+    exact: boolean;
+    maximumColumns: number;
+    maximumRows: number;
+};
+/** The pixel-aperture samples per axis and anti-aliasing spots of a request. */
+export declare function offsetCount(request: DisplayViewGpuRequest): number;
+/** The bilinear RGGB demosaic kernels per phase (phaseY·2 + phaseX) and channel, as `bilinearPhaseProfiles` gives them. */
+export declare function bilinearKernels(): DisplayViewKernelTap[][][];
 export {};

package/dist/gpu/display-view-speed-gpu.js

@@ -13,7 +13,8 @@
  * #477); `display-view-chart-material-module.ts` provides one for the eight 2.0 chart presets and
  * `display-view-composite-material-module.ts` (#491) one for composite charts, the 2.3 elements and `material-layers` scenes.
  */
-import { DISPLAY_VIEW_NOISE_STREAM_ID, axisSums, clipCentre, createDisplayViewExpectedSignal, displayViewDecidedSaturation, overlaps, quantizationVariance, renderDisplayView } from "../facade/display-view.js";
+import { SDR_LUMINANCE_WEIGHTS } from "../output/sdr-rendering.js";
+import { DISPLAY_VIEW_NOISE_STREAM_ID, EXACT_AREA_MEAN_MAX_PIXELS, axisSums, clipCentre, createDisplayViewExpectedSignal, displayViewDecidedSaturation, overlaps, quantizationVariance, renderDisplayView } from "../facade/display-view.js";
 import { displayViewSignalTables } from "../facade/expected-signal.js";
 import { resolvePortableChartScene } from "../facade/chart-scenes.js";
 import { setDisplayViewGpuRendererFactory } from "../facade/display-view-gpu.js";
@@ -25,7 +26,6 @@ import { createHostYieldGate } from "../capture/host-yield-cadence.js";
 import { ImageKernelExecutionError, WEBGPU_F32_UNIT_ROUNDOFF, webGpuExecution } from "./image-kernel-execution.js";
 import { BUFFER_USAGE, GpuResourceScope, abortedError, createComputePipeline, linearDispatch, runComputePass, throwIfAborted as checkAbort } from "./webgpu-runtime.js";
 import { DISPLAY_VIEW_AUX, DISPLAY_VIEW_FLAG_WORDS, DISPLAY_VIEW_SPEED_MAXIMUM_NODES, DISPLAY_VIEW_GEOMETRY_STRIDE, DISPLAY_VIEW_GPU_MAXIMUM_OFFSETS, DISPLAY_VIEW_GPU_MAXIMUM_PIXELS_PER_AXIS, DISPLAY_VIEW_OUTPUT_FLOATS, DISPLAY_VIEW_PARAM_WORDS, DISPLAY_VIEW_REINHARD_MEAN_U, DISPLAY_VIEW_REINHARD_VARIANCE_U, DISPLAY_VIEW_WORKGROUP_SIZE, assembleDisplayViewSpeedWgsl } from "./wgsl-display-view-speed-kernel.js";
-import { footprintShape, bilinearKernels, offsetCount } from "./display-view-quality-gpu.js";
 /** One WGSL rounding of + − × in either direction (W3C WGSL "Floating Point Accuracy"; #471, #487): twice the binary32 unit roundoff. */
 const E = 2 * WEBGPU_F32_UNIT_ROUNDOFF;
 /** Higham's γ_k with E in place of u. */
@@ -53,7 +53,7 @@ const BYTES_PER_PIXEL = 4 * DISPLAY_VIEW_OUTPUT_FLOATS + 4 * DISPLAY_VIEW_FLAG_W
 /**
  * Why the kernel does not cover a request, or null when it does. The kernel is the Speed path: the exact area mean
  * (views where a footprint holds at most 25 real pixels and at most K², and here at most 6 per axis), no diffraction
- * kernels, chart materials, the bilinear demosaic (no AHD candidates or correction), the identity or positive Reinhard
+ * kernels, chart materials, the bilinear demosaic (no AHD candidates), the identity or positive Reinhard
  * tone curve, and at most 16 query offsets.
  */
 export function displayViewSpeedGpuUnsupportedReason(setup, signalInput) {
@@ -65,10 +65,12 @@ export function displayViewSpeedGpuUnsupportedReason(setup, signalInput) {
         return "radiance scenes (caller functions) are not on the GPU";
     if (!signalInput.queryPoint)
         return "the expected signal has no query points";
-    if (setup.candidates || setup.ahdCorrection || setup.ahdCollect)
-        return "AHD candidates and the low-signal correction are not on the GPU";
-    if (setup.toneCurve !== "identity" && setup.toneCurve !== "positive-reinhard-per-channel")
+    if (setup.candidates || setup.ahdChoice)
+        return "AHD candidates are not on the GPU";
+    if (!GPU_TONE_CURVES.includes(setup.toneCurve))
         return "unsupported tone curve " + String(setup.toneCurve);
+    if (setup.rendering && !setup.coupled)
+        return "the coupled rendering steps were not prepared";
     if (signalInput.offsets.length < 1 || signalInput.offsets.length > DISPLAY_VIEW_GPU_MAXIMUM_OFFSETS)
         return "the kernel holds 1 to " + DISPLAY_VIEW_GPU_MAXIMUM_OFFSETS + " query offsets";
     if (signalInput.wavelengthsNm.length < 1 || signalInput.wavelengthsNm.length > DISPLAY_VIEW_SPEED_MAXIMUM_NODES)
@@ -168,6 +170,8 @@ export function axisRecord(geometry, at, start, end, limit, margin, scale) {
     const order = ["bEven", "bOdd", "ppEven", "ppOdd", "qqEven", "qqOdd", "pqEven", "pqOdd", "ww"];
     order.forEach((key, i) => { geometry[at + 8 + i] = sums[key] / scale2; });
 }
+/** The kernel's tone code: identity 0, positive Reinhard 1, extended Reinhard (luminance) 2, Naka–Rushton (luminance) 3. */
+const TONE_CODE = { "identity": 0, "positive-reinhard-per-channel": 1, "extended-reinhard-luminance": 2, "naka-rushton-luminance": 3 };
 /** The uniform parameters and the aux table of a render. */
 function constants(setup, signalInput) {
     const params = new ArrayBuffer(4 * DISPLAY_VIEW_PARAM_WORDS), words = new Uint32Array(params), floats = new Float32Array(params);
@@ -178,7 +182,7 @@ function constants(setup, signalInput) {
     words[6] = setup.nativeWidth;
     words[7] = setup.nativeHeight;
     words[8] = setup.region.width;
-    words[9] = setup.toneCurve === "positive-reinhard-per-channel" ? 1 : 0;
+    words[9] = TONE_CODE[setup.toneCurve];
     words[10] = signalInput.offsets.length;
     words[11] = signalInput.wavelengthsNm.length;
     for (let c = 0; c < 3; c++) {
@@ -298,12 +302,21 @@ export async function renderDisplayViewSpeedOnGpu(runtime, bandBytes, input, abo
     const rows = Math.max(1, Math.min(region.height, Math.floor(bandBytes / (region.width * BYTES_PER_PIXEL)), material.bandRows?.(shape.sy) ?? Infinity));
     if (Math.max(rows * region.width * 4 * DISPLAY_VIEW_OUTPUT_FLOATS, geometry.byteLength, table.byteLength) > runtime.maximumStorageBindingBytes)
         throw new ImageKernelExecutionError("insufficient-limits", "One display-view band exceeds the device's storage binding limit.");
-    const pipeline = await pipelines("photivra-display-view-speed:" + material.id, assembleDisplayViewSpeedWgsl(material.wgsl));
+    // #593, #601: the coupled steps' shader text and constants, loaded on demand for a view that asks for them.
+    const coupled = setup.rendering ? await import("./wgsl-display-view-coupled.js") : null;
+    const coupledConstants = coupled ? coupled.displayViewCoupledConstants(setup, SDR_LUMINANCE_WEIGHTS, gaussLegendre16()) : new Float32Array(1);
+    // #605: the neighbor reconstruction's ratios from the host, in a second dispatch per band (wgsl-display-view-neighbors.ts).
+    const neighbors = setup.coupled?.neighbors && coupled;
+    const pipeline = await pipelines("photivra-display-view-speed:" + material.id + (coupled ? "+coupled" : "") + (neighbors ? "+neighbors" : ""), assembleDisplayViewSpeedWgsl(material.wgsl, coupled?.displayViewCoupledWgsl(!!neighbors)));
     const moments = new Float32Array(pixelCount * DISPLAY_VIEW_OUTPUT_FLOATS), flagged = [], flagWords = new Uint32Array(pixelCount * DISPLAY_VIEW_FLAG_WORDS);
     const words = new Uint32Array(params);
     const scope = new GpuResourceScope(runtime);
     try {
-        const auxBuffer = scope.upload("photivra-display-view-aux", aux, BUFFER_USAGE.STORAGE);
+        // #593, #601: the coupled steps' constants follow the aux table's own entries (one zero word without them).
+        const auxWithCoupled = new Float32Array(aux.length + coupledConstants.length);
+        auxWithCoupled.set(aux);
+        auxWithCoupled.set(coupledConstants, aux.length);
+        const auxBuffer = scope.upload("photivra-display-view-aux", auxWithCoupled, BUFFER_USAGE.STORAGE);
         const geometryBuffer = scope.upload("photivra-display-view-geometry", geometry, BUFFER_USAGE.STORAGE);
         const tableBuffer = scope.upload("photivra-display-view-table", table, BUFFER_USAGE.STORAGE);
         const materialGroup = material.band ? null : runtime.device.createBindGroup({ layout: pipeline.getBindGroupLayout(1), entries: material.bindings.map((b) => ({ binding: b.binding,
@@ -317,16 +330,21 @@ export async function renderDisplayViewSpeedOnGpu(runtime, bandBytes, input, abo
             const band = new GpuResourceScope(runtime);
             try {
                 const out = band.buffer("photivra-display-view-moments", count * 4 * DISPLAY_VIEW_OUTPUT_FLOATS, BUFFER_USAGE.STORAGE | BUFFER_USAGE.COPY_SRC);
-                const flagBuffer = band.buffer("photivra-display-view-flags", count * 4 * DISPLAY_VIEW_FLAG_WORDS, BUFFER_USAGE.STORAGE | BUFFER_USAGE.COPY_SRC);
                 const uniform = band.upload("photivra-display-view-params", new Uint8Array(params), BUFFER_USAGE.UNIFORM);
-                const bindGroup = runtime.device.createBindGroup({ layout: pipeline.getBindGroupLayout(0), entries: [
-                        { binding: 0, resource: { buffer: uniform } }, { binding: 1, resource: { buffer: auxBuffer } }, { binding: 2, resource: { buffer: geometryBuffer } },
-                        { binding: 3, resource: { buffer: tableBuffer } }, { binding: 4, resource: { buffer: out } }, { binding: 5, resource: { buffer: flagBuffer } }
-                    ] });
                 // #581: a module that bands its own data (a large photo) gives group 1 per band, for the native rows the band reads (with margin).
-                const [data, flagData] = await runComputePass(runtime, band, pipeline, [bindGroup, materialGroup ?? material.band(band, pipeline.getBindGroupLayout(1), Math.floor((region.y + row0) * shape.sy) + margin - 2, Math.ceil((region.y + row1) * shape.sy) + margin + 2)], linearDispatch(count, DISPLAY_VIEW_WORKGROUP_SIZE, runtime.maximumWorkgroupsPerDimension), [{ buffer: out, bytes: count * 4 * DISPLAY_VIEW_OUTPUT_FLOATS }, { buffer: flagBuffer, bytes: count * 4 * DISPLAY_VIEW_FLAG_WORDS }], abort.signal);
+                const group1 = materialGroup ?? material.band(band, pipeline.getBindGroupLayout(1), Math.floor((region.y + row0) * shape.sy) + margin - 2, Math.ceil((region.y + row1) * shape.sy) + margin + 2);
+                let data, flagData;
+                const run = async (contents = new Uint32Array(count * DISPLAY_VIEW_FLAG_WORDS)) => {
+                    const flagBuffer = band.upload("photivra-display-view-flags", contents, BUFFER_USAGE.STORAGE | BUFFER_USAGE.COPY_SRC);
+                    const bindGroup = runtime.device.createBindGroup({ layout: pipeline.getBindGroupLayout(0), entries: [
+                            { binding: 0, resource: { buffer: uniform } }, { binding: 1, resource: { buffer: auxBuffer } }, { binding: 2, resource: { buffer: geometryBuffer } },
+                            { binding: 3, resource: { buffer: tableBuffer } }, { binding: 4, resource: { buffer: out } }, { binding: 5, resource: { buffer: flagBuffer } }
+                        ] });
+                    [data, flagData] = await runComputePass(runtime, band, pipeline, [bindGroup, group1], linearDispatch(count, DISPLAY_VIEW_WORKGROUP_SIZE, runtime.maximumWorkgroupsPerDimension), [{ buffer: out, bytes: count * 4 * DISPLAY_VIEW_OUTPUT_FLOATS }, { buffer: flagBuffer, bytes: count * 4 * DISPLAY_VIEW_FLAG_WORDS }], abort.signal);
+                    return new Uint32Array(flagData, 0, count * DISPLAY_VIEW_FLAG_WORDS);
+                };
+                const bandFlags = neighbors ? await neighbors.dispatchWithNeighborRatios(setup, geometry, first, count, runtime.maximumStorageBindingBytes, run) : await run();
                 moments.set(new Float32Array(data, 0, count * DISPLAY_VIEW_OUTPUT_FLOATS), first * DISPLAY_VIEW_OUTPUT_FLOATS);
-                const bandFlags = new Uint32Array(flagData, 0, count * DISPLAY_VIEW_FLAG_WORDS);
                 flagWords.set(bandFlags, first * DISPLAY_VIEW_FLAG_WORDS);
                 for (let i = 0; i < count; i++) {
                     let flag = (bandFlags[DISPLAY_VIEW_FLAG_WORDS * i] & 1) !== 0;
@@ -409,7 +427,7 @@ export async function renderDisplayViewSpeedOnGpu(runtime, bandBytes, input, abo
         saturatedPixelCount += saturated[i];
     const expectedValueBound = { kind: "relative-to-reference", relative: relative.mean, absolute: largestMean };
     const uncertain = flagged.length - recomputed.length + undecided.length - highlights.length;
-    return { samples, expected, noiseStd, sampleCount, siteCount, detailPixelCount: pixelCount, uniformPixelCount: 0, ahdCorrectedPixelCount: 0, estimation: "exact-area-mean", saturated, saturatedPixelCount,
+    return { samples, expected, noiseStd, sampleCount, siteCount, detailPixelCount: pixelCount, uniformPixelCount: 0, estimation: "exact-area-mean", saturated, saturatedPixelCount,
         execution: webGpuExecution(expectedValueBound, uncertain), expectedValueBound,
         varianceBound: { kind: "relative-to-reference", relative: relative.variance, absolute: largestVariance },
         expectedValueAbsoluteBound: meanBound, varianceAbsoluteBound: varianceBound,
@@ -434,12 +452,15 @@ export function displayViewSpeedGpuSupports(request) {
 export function sceneToneAndOffsetsReason(request, maximumOffsets) {
     if (request.scene !== "chart" && request.scene !== "material-layers" && request.scene !== "image-plane")
         return "the scene is a caller " + request.scene + "; the GPU material lookup covers engine charts and declared material-layers scenes (describe the scene as material-layers)";
-    if (request.toneCurve !== "identity" && request.toneCurve !== "positive-reinhard-per-channel")
+    // #593: the identity, Reinhard and the two luminance tone curves (the luminance curves through the coupled steps).
+    if (!GPU_TONE_CURVES.includes(request.toneCurve))
         return "unsupported tone curve " + String(request.toneCurve);
     if (offsetCount(request) > maximumOffsets)
         return "more than " + maximumOffsets + " query offsets per site";
     return true;
 }
+/** The tone curves the GPU kernels render (#593 adds the luminance curves). */
+const GPU_TONE_CURVES = ["identity", "positive-reinhard-per-channel", "extended-reinhard-luminance", "naka-rushton-luminance"];
 /**
  * A self-check's verdict: every component of a GPU render inside its a-priori bounds against the reference, every sample within
  * one code, and (#533) the saturated-pixel count the reference's bit for bit; true, or a sentence saying where it failed.
@@ -548,7 +569,7 @@ export function createDisplayViewSpeedGpuRenderer(runtime, options = {}) {
                 const material = await modules.moduleFor(setup.gpu, abort.signal);
                 const result = await renderDisplayViewSpeedOnGpu(runtime, bandBytes, { setup, signalInput: setup.gpu.signalInput, material }, abort, options.yieldControl, source);
                 return { samples: result.samples, expected: result.expected, noiseStd: result.noiseStd, sampleCount: result.sampleCount, siteCount: result.siteCount, detailPixelCount: result.detailPixelCount,
-                    uniformPixelCount: result.uniformPixelCount, ahdCorrectedPixelCount: result.ahdCorrectedPixelCount, estimation: result.estimation, saturated: result.saturated,
+                    uniformPixelCount: result.uniformPixelCount, estimation: result.estimation, saturated: result.saturated,
                     saturatedPixelCount: result.saturatedPixelCount, errorBound: result.expectedValueBound,
                     diagnosticUncertaintySampleCount: result.execution.diagnosticUncertaintySampleCount, ...(material.compositeProbe ? { compositeProbe: material.compositeProbe } : {}) };
             }
@@ -568,4 +589,26 @@ export const displayViewSpeedGpuRendererFactory = (handle) => createDisplayViewS
 export function registerDisplayViewSpeedGpuRenderer() {
     return setDisplayViewGpuRendererFactory(displayViewSpeedGpuRendererFactory);
 }
+// #594: shared with the on-demand Quality host (display-view-quality-gpu.ts), so the Speed path does not import it.
+/** #564: the GPU refusal of a defocus kernel above the direct radius (the CPU convolves it by runs). */
+export const LARGE_DEFOCUS_REASON = "a defocus kernel radius above 64 sites (convolved by runs on the CPU, #564) is not on the GPU";
+/** The footprint shape of a view: real pixels per display pixel along each axis, and whether the exact area mean applies. */
+export function footprintShape(setup) {
+    const sx = setup.frameWidth / setup.viewWidth, sy = setup.frameHeight / setup.viewHeight, area = sx * sy;
+    const exact = area <= Math.min(EXACT_AREA_MEAN_MAX_PIXELS, setup.samplesPerAxis * setup.samplesPerAxis);
+    let maximumColumns = 0, maximumRows = 0;
+    for (let i = 0; i < setup.region.width; i++)
+        maximumColumns = Math.max(maximumColumns, overlaps((setup.region.x + i) * sx, (setup.region.x + i + 1) * sx, setup.frameWidth).w.length);
+    for (let j = 0; j < setup.region.height; j++)
+        maximumRows = Math.max(maximumRows, overlaps((setup.region.y + j) * sy, (setup.region.y + j + 1) * sy, setup.frameHeight).w.length);
+    return { sx, sy, exact, maximumColumns, maximumRows };
+}
+/** The pixel-aperture samples per axis and anti-aliasing spots of a request. */
+export function offsetCount(request) { return request.boxSamples * request.boxSamples * (request.antiAliasing ? 4 : 1); }
+/** The bilinear RGGB demosaic kernels per phase (phaseY·2 + phaseX) and channel, as `bilinearPhaseProfiles` gives them. */
+export function bilinearKernels() {
+    const cross = [[1, 0], [-1, 0], [0, 1], [0, -1]], diagonal = [[1, 1], [1, -1], [-1, 1], [-1, -1]], horizontal = [[1, 0], [-1, 0]], vertical = [[0, 1], [0, -1]];
+    const average = (offsets) => offsets.map(([dx, dy]) => ({ dx: dx, dy: dy, weight: 1 / offsets.length })), self = [{ dx: 0, dy: 0, weight: 1 }];
+    return [[self, average(cross), average(diagonal)], [average(horizontal), self, average(vertical)], [average(vertical), self, average(horizontal)], [average(diagonal), average(cross), self]];
+}
 //# sourceMappingURL=display-view-speed-gpu.js.map