@photivra/engine 1.5.0 → 2.1.0

package/dist/gpu/webgpu-runtime.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Internal WebGPU device handling for the image-kernel accelerator: getting the adapter and device,
+ * limits, tracking device loss, racing work against abort and loss, error scopes, banded buffers and
+ * cleanup. Not exported from the package root. WebGPU types never appear in the published type
+ * declarations, so consumers do not need WebGPU typings.
+ */
+import { ImageKernelExecutionError, type ImageKernelFallbackReason } from "./image-kernel-execution.js";
+/** WebGPU spec constants (GPUBufferUsage, GPUMapMode), defined here so no global is needed at import time. */
+export declare const BUFFER_USAGE: Readonly<{
+    MAP_READ: 1;
+    COPY_SRC: 4;
+    COPY_DST: 8;
+    UNIFORM: 64;
+    STORAGE: 128;
+}>;
+/** Minimum per-binding storage this backend requires (the WebGPU default is 128 MiB). */
+export declare const WEBGPU_MINIMUM_STORAGE_BINDING_BYTES: number;
+/** Upper limit requested from the adapter, so one band never asks for more than this per binding. */
+export declare const WEBGPU_REQUESTED_STORAGE_BINDING_BYTES: number;
+export interface WebGpuRuntime {
+    readonly device: GPUDevice;
+    readonly maximumStorageBindingBytes: number;
+    readonly maximumWorkgroupsPerDimension: number;
+    /** Set once `device.lost` settles; every later wait rejects with `device-lost`. */
+    isLost(): boolean;
+    /** Races a GPU promise with device loss and the operation's abort signal. */
+    guard<T>(promise: Promise<T>, signal: AbortSignal | undefined): Promise<T>;
+    destroy(): void;
+}
+export type WebGpuAcquisition = {
+    runtime: WebGpuRuntime;
+} | {
+    failure: ImageKernelFallbackReason;
+    message: string;
+};
+export declare function abortedError(): ImageKernelExecutionError;
+/**
+ * Requests a device with high limits from `gpu` (normally `navigator.gpu`). It does not throw when
+ * WebGPU is unavailable; the caller decides whether to fall back to the CPU or fail. An abort during
+ * acquisition does throw.
+ */
+export declare function acquireWebGpuRuntime(gpu: unknown, powerPreference: "low-power" | "high-performance" | undefined, signal: AbortSignal | undefined): Promise<WebGpuAcquisition>;
+/** Per-operation resource scope: every buffer is destroyed when the operation settles. */
+export declare class GpuResourceScope {
+    #private;
+    constructor(runtime: WebGpuRuntime);
+    buffer(label: string, size: number, usage: number): GPUBuffer;
+    /** Storage buffer initialised from host data (padded to a 16-byte multiple). */
+    upload(label: string, data: ArrayBufferView<ArrayBuffer>, usage: number): GPUBuffer;
+    release(): void;
+}
+/** Workgroup grid for a 1-D invocation count (2-D when it exceeds one dimension). */
+export declare function linearDispatch(invocations: number, workgroupSize: number, maximumPerDimension: number): [number, number];
+/**
+ * Submits one compute pass and copies `outputs` into mappable staging buffers, then maps them. Validation
+ * and out-of-memory errors are captured with error scopes and reported as domain errors.
+ */
+export declare function runComputePass(runtime: WebGpuRuntime, scope: GpuResourceScope, pipeline: GPUComputePipeline, bindGroup: GPUBindGroup, workgroups: readonly [number, number], outputs: readonly {
+    buffer: GPUBuffer;
+    bytes: number;
+}[], signal: AbortSignal | undefined): Promise<ArrayBuffer[]>;
+/** Compiles a compute pipeline; compilation/validation failures are domain errors. */
+export declare function createComputePipeline(runtime: WebGpuRuntime, label: string, code: string, signal: AbortSignal | undefined): Promise<GPUComputePipeline>;

package/dist/gpu/webgpu-runtime.js

@@ -0,0 +1,215 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Internal WebGPU device handling for the image-kernel accelerator: getting the adapter and device,
+ * limits, tracking device loss, racing work against abort and loss, error scopes, banded buffers and
+ * cleanup. Not exported from the package root. WebGPU types never appear in the published type
+ * declarations, so consumers do not need WebGPU typings.
+ */
+import { ImageKernelExecutionError } from "./image-kernel-execution.js";
+/** WebGPU spec constants (GPUBufferUsage, GPUMapMode), defined here so no global is needed at import time. */
+export const BUFFER_USAGE = Object.freeze({ MAP_READ: 0x0001, COPY_SRC: 0x0004, COPY_DST: 0x0008, UNIFORM: 0x0040, STORAGE: 0x0080 });
+const MAP_MODE_READ = 0x0001;
+/** Minimum per-binding storage this backend requires (the WebGPU default is 128 MiB). */
+export const WEBGPU_MINIMUM_STORAGE_BINDING_BYTES = 16 * 1024 * 1024;
+/** Upper limit requested from the adapter, so one band never asks for more than this per binding. */
+export const WEBGPU_REQUESTED_STORAGE_BINDING_BYTES = 1024 * 1024 * 1024;
+function hostIsLittleEndian() {
+    return new Uint8Array(new Uint16Array([1]).buffer)[0] === 1;
+}
+export function abortedError() {
+    return new ImageKernelExecutionError("aborted", "Image-kernel execution was aborted; no output is available.");
+}
+/** Rejects when the signal aborts; the returned cleanup removes the listener. */
+function abortRace(signal) {
+    if (!signal)
+        return { promise: new Promise(() => undefined), cleanup: () => undefined };
+    let cleanup = () => undefined;
+    const promise = new Promise((_, reject) => {
+        if (signal.aborted) {
+            reject(abortedError());
+            return;
+        }
+        const listener = () => reject(abortedError());
+        signal.addEventListener("abort", listener, { once: true });
+        cleanup = () => signal.removeEventListener("abort", listener);
+    });
+    promise.catch(() => undefined);
+    return { promise, cleanup };
+}
+/**
+ * Requests a device with high limits from `gpu` (normally `navigator.gpu`). It does not throw when
+ * WebGPU is unavailable; the caller decides whether to fall back to the CPU or fail. An abort during
+ * acquisition does throw.
+ */
+export async function acquireWebGpuRuntime(gpu, powerPreference, signal) {
+    if (!hostIsLittleEndian())
+        return { failure: "unsupported-platform-endianness", message: "WebGPU buffers require a little-endian host." };
+    const api = gpu;
+    if (!api || typeof api !== "object" || typeof api.requestAdapter !== "function") {
+        return { failure: "webgpu-unavailable", message: "WebGPU is not available in this runtime." };
+    }
+    const abort = abortRace(signal);
+    try {
+        let adapter;
+        try {
+            adapter = await Promise.race([api.requestAdapter(powerPreference ? { powerPreference } : undefined), abort.promise]);
+        }
+        catch (error) {
+            if (error instanceof ImageKernelExecutionError)
+                throw error;
+            adapter = null;
+        }
+        if (!adapter)
+            return { failure: "adapter-unavailable", message: "No WebGPU adapter is available." };
+        const adapterStorage = adapter.limits.maxStorageBufferBindingSize, adapterBuffer = adapter.limits.maxBufferSize;
+        if (!(adapterStorage >= WEBGPU_MINIMUM_STORAGE_BINDING_BYTES && adapterBuffer >= WEBGPU_MINIMUM_STORAGE_BINDING_BYTES)) {
+            return { failure: "insufficient-limits", message: "The WebGPU adapter's storage-buffer limits are below the backend minimum." };
+        }
+        const storage = Math.min(adapterStorage, adapterBuffer, WEBGPU_REQUESTED_STORAGE_BINDING_BYTES);
+        let device, pending;
+        try {
+            pending = adapter.requestDevice({ label: "photivra-image-kernels",
+                requiredLimits: { maxStorageBufferBindingSize: storage, maxBufferSize: storage } });
+            device = await Promise.race([pending, abort.promise]);
+        }
+        catch (error) {
+            if (error instanceof ImageKernelExecutionError) {
+                // The abort won the race. A device that still arrives later is destroyed, so it never leaks.
+                if (pending)
+                    void Promise.resolve(pending).then(late => late.destroy(), () => undefined);
+                throw error;
+            }
+            return { failure: "device-request-failed", message: "The WebGPU device request failed." };
+        }
+        if (signal?.aborted) {
+            device.destroy();
+            throw abortedError();
+        }
+        return { runtime: createRuntime(device, storage) };
+    }
+    finally {
+        abort.cleanup();
+    }
+}
+function createRuntime(device, storage) {
+    let lost = false, destroyed = false;
+    let rejectLost = () => undefined;
+    const lostPromise = new Promise((_, reject) => { rejectLost = reject; });
+    lostPromise.catch(() => undefined);
+    void device.lost.then(() => {
+        lost = true;
+        rejectLost(new ImageKernelExecutionError("device-lost", "The WebGPU device was lost; no output is available."));
+    });
+    // Errors are collected through error scopes; this only keeps uncaptured errors out of the console.
+    device.onuncapturederror = (event) => { event.preventDefault(); };
+    const maximumWorkgroupsPerDimension = device.limits.maxComputeWorkgroupsPerDimension;
+    return {
+        device,
+        maximumStorageBindingBytes: Math.min(storage, device.limits.maxStorageBufferBindingSize, device.limits.maxBufferSize),
+        maximumWorkgroupsPerDimension,
+        isLost: () => lost,
+        async guard(promise, signal) {
+            promise.catch(() => undefined);
+            if (lost)
+                throw new ImageKernelExecutionError("device-lost", "The WebGPU device was lost; no output is available.");
+            const abort = abortRace(signal);
+            try {
+                return await Promise.race([promise, lostPromise, abort.promise]);
+            }
+            finally {
+                abort.cleanup();
+            }
+        },
+        destroy() { if (!destroyed) {
+            destroyed = true;
+            device.destroy();
+        } }
+    };
+}
+/** Per-operation resource scope: every buffer is destroyed when the operation settles. */
+export class GpuResourceScope {
+    #runtime;
+    #buffers = [];
+    constructor(runtime) { this.#runtime = runtime; }
+    buffer(label, size, usage) {
+        const buffer = this.#runtime.device.createBuffer({ label, size: Math.max(16, Math.ceil(size / 16) * 16), usage });
+        this.#buffers.push(buffer);
+        return buffer;
+    }
+    /** Storage buffer initialised from host data (padded to a 16-byte multiple). */
+    upload(label, data, usage) {
+        const buffer = this.buffer(label, data.byteLength, usage | BUFFER_USAGE.COPY_DST);
+        if (data.byteLength > 0)
+            this.#runtime.device.queue.writeBuffer(buffer, 0, data.buffer, data.byteOffset, data.byteLength);
+        return buffer;
+    }
+    release() {
+        for (const buffer of this.#buffers.splice(0))
+            buffer.destroy();
+    }
+}
+/** Workgroup grid for a 1-D invocation count (2-D when it exceeds one dimension). */
+export function linearDispatch(invocations, workgroupSize, maximumPerDimension) {
+    const groups = Math.max(1, Math.ceil(invocations / workgroupSize));
+    const x = Math.min(groups, maximumPerDimension), y = Math.ceil(groups / x);
+    if (y > maximumPerDimension) {
+        throw new ImageKernelExecutionError("insufficient-limits", "Band exceeds the adapter's dispatch limits.");
+    }
+    return [x, y];
+}
+/**
+ * Submits one compute pass and copies `outputs` into mappable staging buffers, then maps them. Validation
+ * and out-of-memory errors are captured with error scopes and reported as domain errors.
+ */
+export async function runComputePass(runtime, scope, pipeline, bindGroup, workgroups, outputs, signal) {
+    const device = runtime.device;
+    device.pushErrorScope("out-of-memory");
+    device.pushErrorScope("validation");
+    const staging = outputs.map(({ bytes }, i) => scope.buffer(`photivra-readback-${i}`, bytes, BUFFER_USAGE.MAP_READ | BUFFER_USAGE.COPY_DST));
+    const encoder = device.createCommandEncoder({ label: "photivra-image-kernel" });
+    const pass = encoder.beginComputePass();
+    pass.setPipeline(pipeline);
+    pass.setBindGroup(0, bindGroup);
+    pass.dispatchWorkgroups(workgroups[0], workgroups[1]);
+    pass.end();
+    outputs.forEach(({ buffer }, i) => encoder.copyBufferToBuffer(buffer, 0, staging[i], 0, staging[i].size));
+    device.queue.submit([encoder.finish()]);
+    // Pop both scopes before any await so an abort or loss never leaves the device's scope stack unbalanced.
+    const validationScope = device.popErrorScope(), memoryScope = device.popErrorScope();
+    const validation = await runtime.guard(validationScope, signal);
+    const memory = await runtime.guard(memoryScope, signal);
+    if (memory)
+        throw new ImageKernelExecutionError("out-of-memory", "The WebGPU device ran out of memory.");
+    if (validation)
+        throw new ImageKernelExecutionError("gpu-validation", "WebGPU rejected an image-kernel command.");
+    const results = [];
+    for (let i = 0; i < staging.length; i++) {
+        const buffer = staging[i];
+        await runtime.guard(buffer.mapAsync(MAP_MODE_READ), signal);
+        results.push(buffer.getMappedRange(0, Math.ceil(outputs[i].bytes / 4) * 4).slice(0));
+        buffer.unmap();
+    }
+    return results;
+}
+/** Compiles a compute pipeline; compilation/validation failures are domain errors. */
+export async function createComputePipeline(runtime, label, code, signal) {
+    const device = runtime.device;
+    device.pushErrorScope("validation");
+    const module = device.createShaderModule({ label, code });
+    const pending = device.createComputePipelineAsync({ label, layout: "auto", compute: { module, entryPoint: "main" } });
+    const scope = device.popErrorScope();
+    let pipeline;
+    try {
+        pipeline = await runtime.guard(pending, signal);
+    }
+    catch (error) {
+        if (error instanceof ImageKernelExecutionError)
+            throw error;
+        throw new ImageKernelExecutionError("gpu-validation", `WebGPU could not compile the ${label} kernel.`);
+    }
+    if (await runtime.guard(scope, signal)) {
+        throw new ImageKernelExecutionError("gpu-validation", `WebGPU could not compile the ${label} kernel.`);
+    }
+    return pipeline;
+}
+//# sourceMappingURL=webgpu-runtime.js.map

package/dist/gpu/webgpu-runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"webgpu-runtime.js","sourceRoot":"","sources":["../../src/gpu/webgpu-runtime.ts"],"names":[],"mappings":"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","sourcesContent":["// SPDX-License-Identifier: Apache-2.0\n\n/**\n * Internal WebGPU device handling for the image-kernel accelerator: getting the adapter and device,\n * limits, tracking device loss, racing work against abort and loss, error scopes, banded buffers and\n * cleanup. Not exported from the package root. WebGPU types never appear in the published type\n * declarations, so consumers do not need WebGPU typings.\n */\nimport { ImageKernelExecutionError, type ImageKernelFallbackReason } from \"./image-kernel-execution.js\";\n\n/** WebGPU spec constants (GPUBufferUsage, GPUMapMode), defined here so no global is needed at import time. */\nexport const BUFFER_USAGE = Object.freeze({ MAP_READ: 0x0001, COPY_SRC: 0x0004, COPY_DST: 0x0008, UNIFORM: 0x0040, STORAGE: 0x0080 });\nconst MAP_MODE_READ = 0x0001;\n\n/** Minimum per-binding storage this backend requires (the WebGPU default is 128 MiB). */\nexport const WEBGPU_MINIMUM_STORAGE_BINDING_BYTES = 16 * 1024 * 1024;\n/** Upper limit requested from the adapter, so one band never asks for more than this per binding. */\nexport const WEBGPU_REQUESTED_STORAGE_BINDING_BYTES = 1024 * 1024 * 1024;\n\nexport interface WebGpuRuntime {\n  readonly device: GPUDevice;\n  readonly maximumStorageBindingBytes: number;\n  readonly maximumWorkgroupsPerDimension: number;\n  /** Set once `device.lost` settles; every later wait rejects with `device-lost`. */\n  isLost(): boolean;\n  /** Races a GPU promise with device loss and the operation's abort signal. */\n  guard<T>(promise: Promise<T>, signal: AbortSignal | undefined): Promise<T>;\n  destroy(): void;\n}\n\nexport type WebGpuAcquisition = { runtime: WebGpuRuntime } | { failure: ImageKernelFallbackReason; message: string };\n\nfunction hostIsLittleEndian(): boolean {\n  return new Uint8Array(new Uint16Array([1]).buffer)[0] === 1;\n}\n\nexport function abortedError(): ImageKernelExecutionError {\n  return new ImageKernelExecutionError(\"aborted\", \"Image-kernel execution was aborted; no output is available.\");\n}\n\n/** Rejects when the signal aborts; the returned cleanup removes the listener. */\nfunction abortRace(signal: AbortSignal | undefined): { promise: Promise<never>; cleanup: () => void } {\n  if (!signal) return { promise: new Promise<never>(() => undefined), cleanup: () => undefined };\n  let cleanup = (): void => undefined;\n  const promise = new Promise<never>((_, reject) => {\n    if (signal.aborted) { reject(abortedError()); return; }\n    const listener = (): void => reject(abortedError());\n    signal.addEventListener(\"abort\", listener, { once: true });\n    cleanup = (): void => signal.removeEventListener(\"abort\", listener);\n  });\n  promise.catch(() => undefined);\n  return { promise, cleanup };\n}\n\n/**\n * Requests a device with high limits from `gpu` (normally `navigator.gpu`). It does not throw when\n * WebGPU is unavailable; the caller decides whether to fall back to the CPU or fail. An abort during\n * acquisition does throw.\n */\nexport async function acquireWebGpuRuntime(gpu: unknown, powerPreference: \"low-power\" | \"high-performance\" | undefined,\n  signal: AbortSignal | undefined): Promise<WebGpuAcquisition> {\n  if (!hostIsLittleEndian()) return { failure: \"unsupported-platform-endianness\", message: \"WebGPU buffers require a little-endian host.\" };\n  const api = gpu as Partial<GPU> | null | undefined;\n  if (!api || typeof api !== \"object\" || typeof api.requestAdapter !== \"function\") {\n    return { failure: \"webgpu-unavailable\", message: \"WebGPU is not available in this runtime.\" };\n  }\n  const abort = abortRace(signal);\n  try {\n    let adapter: GPUAdapter | null;\n    try {\n      adapter = await Promise.race([api.requestAdapter(powerPreference ? { powerPreference } : undefined), abort.promise]);\n    } catch (error) {\n      if (error instanceof ImageKernelExecutionError) throw error;\n      adapter = null;\n    }\n    if (!adapter) return { failure: \"adapter-unavailable\", message: \"No WebGPU adapter is available.\" };\n    const adapterStorage = adapter.limits.maxStorageBufferBindingSize, adapterBuffer = adapter.limits.maxBufferSize;\n    if (!(adapterStorage >= WEBGPU_MINIMUM_STORAGE_BINDING_BYTES && adapterBuffer >= WEBGPU_MINIMUM_STORAGE_BINDING_BYTES)) {\n      return { failure: \"insufficient-limits\", message: \"The WebGPU adapter's storage-buffer limits are below the backend minimum.\" };\n    }\n    const storage = Math.min(adapterStorage, adapterBuffer, WEBGPU_REQUESTED_STORAGE_BINDING_BYTES);\n    let device: GPUDevice, pending: Promise<GPUDevice> | undefined;\n    try {\n      pending = adapter.requestDevice({ label: \"photivra-image-kernels\",\n        requiredLimits: { maxStorageBufferBindingSize: storage, maxBufferSize: storage } });\n      device = await Promise.race([pending, abort.promise]);\n    } catch (error) {\n      if (error instanceof ImageKernelExecutionError) {\n        // The abort won the race. A device that still arrives later is destroyed, so it never leaks.\n        if (pending) void Promise.resolve(pending).then(late => late.destroy(), () => undefined);\n        throw error;\n      }\n      return { failure: \"device-request-failed\", message: \"The WebGPU device request failed.\" };\n    }\n    if (signal?.aborted) { device.destroy(); throw abortedError(); }\n    return { runtime: createRuntime(device, storage) };\n  } finally {\n    abort.cleanup();\n  }\n}\n\nfunction createRuntime(device: GPUDevice, storage: number): WebGpuRuntime {\n  let lost = false, destroyed = false;\n  let rejectLost: (error: ImageKernelExecutionError) => void = () => undefined;\n  const lostPromise = new Promise<never>((_, reject) => { rejectLost = reject; });\n  lostPromise.catch(() => undefined);\n  void device.lost.then(() => {\n    lost = true;\n    rejectLost(new ImageKernelExecutionError(\"device-lost\", \"The WebGPU device was lost; no output is available.\"));\n  });\n  // Errors are collected through error scopes; this only keeps uncaptured errors out of the console.\n  device.onuncapturederror = (event: GPUUncapturedErrorEvent): void => { event.preventDefault(); };\n  const maximumWorkgroupsPerDimension = device.limits.maxComputeWorkgroupsPerDimension;\n  return {\n    device,\n    maximumStorageBindingBytes: Math.min(storage, device.limits.maxStorageBufferBindingSize, device.limits.maxBufferSize),\n    maximumWorkgroupsPerDimension,\n    isLost: (): boolean => lost,\n    async guard<T>(promise: Promise<T>, signal: AbortSignal | undefined): Promise<T> {\n      promise.catch(() => undefined);\n      if (lost) throw new ImageKernelExecutionError(\"device-lost\", \"The WebGPU device was lost; no output is available.\");\n      const abort = abortRace(signal);\n      try { return await Promise.race([promise, lostPromise, abort.promise]); } finally { abort.cleanup(); }\n    },\n    destroy(): void { if (!destroyed) { destroyed = true; device.destroy(); } }\n  };\n}\n\n/** Per-operation resource scope: every buffer is destroyed when the operation settles. */\nexport class GpuResourceScope {\n  readonly #runtime: WebGpuRuntime;\n  readonly #buffers: GPUBuffer[] = [];\n\n  constructor(runtime: WebGpuRuntime) { this.#runtime = runtime; }\n\n  buffer(label: string, size: number, usage: number): GPUBuffer {\n    const buffer = this.#runtime.device.createBuffer({ label, size: Math.max(16, Math.ceil(size / 16) * 16), usage });\n    this.#buffers.push(buffer);\n    return buffer;\n  }\n\n  /** Storage buffer initialised from host data (padded to a 16-byte multiple). */\n  upload(label: string, data: ArrayBufferView<ArrayBuffer>, usage: number): GPUBuffer {\n    const buffer = this.buffer(label, data.byteLength, usage | BUFFER_USAGE.COPY_DST);\n    if (data.byteLength > 0) this.#runtime.device.queue.writeBuffer(buffer, 0, data.buffer, data.byteOffset, data.byteLength);\n    return buffer;\n  }\n\n  release(): void {\n    for (const buffer of this.#buffers.splice(0)) buffer.destroy();\n  }\n}\n\n/** Workgroup grid for a 1-D invocation count (2-D when it exceeds one dimension). */\nexport function linearDispatch(invocations: number, workgroupSize: number, maximumPerDimension: number): [number, number] {\n  const groups = Math.max(1, Math.ceil(invocations / workgroupSize));\n  const x = Math.min(groups, maximumPerDimension), y = Math.ceil(groups / x);\n  if (y > maximumPerDimension) {\n    throw new ImageKernelExecutionError(\"insufficient-limits\", \"Band exceeds the adapter's dispatch limits.\");\n  }\n  return [x, y];\n}\n\n/**\n * Submits one compute pass and copies `outputs` into mappable staging buffers, then maps them. Validation\n * and out-of-memory errors are captured with error scopes and reported as domain errors.\n */\nexport async function runComputePass(runtime: WebGpuRuntime, scope: GpuResourceScope, pipeline: GPUComputePipeline,\n  bindGroup: GPUBindGroup, workgroups: readonly [number, number], outputs: readonly { buffer: GPUBuffer; bytes: number }[],\n  signal: AbortSignal | undefined): Promise<ArrayBuffer[]> {\n  const device = runtime.device;\n  device.pushErrorScope(\"out-of-memory\");\n  device.pushErrorScope(\"validation\");\n  const staging = outputs.map(({ bytes }, i) =>\n    scope.buffer(`photivra-readback-${i}`, bytes, BUFFER_USAGE.MAP_READ | BUFFER_USAGE.COPY_DST));\n  const encoder = device.createCommandEncoder({ label: \"photivra-image-kernel\" });\n  const pass = encoder.beginComputePass();\n  pass.setPipeline(pipeline);\n  pass.setBindGroup(0, bindGroup);\n  pass.dispatchWorkgroups(workgroups[0], workgroups[1]);\n  pass.end();\n  outputs.forEach(({ buffer }, i) => encoder.copyBufferToBuffer(buffer, 0, staging[i]!, 0, staging[i]!.size));\n  device.queue.submit([encoder.finish()]);\n  // Pop both scopes before any await so an abort or loss never leaves the device's scope stack unbalanced.\n  const validationScope = device.popErrorScope(), memoryScope = device.popErrorScope();\n  const validation = await runtime.guard(validationScope, signal);\n  const memory = await runtime.guard(memoryScope, signal);\n  if (memory) throw new ImageKernelExecutionError(\"out-of-memory\", \"The WebGPU device ran out of memory.\");\n  if (validation) throw new ImageKernelExecutionError(\"gpu-validation\", \"WebGPU rejected an image-kernel command.\");\n  const results: ArrayBuffer[] = [];\n  for (let i = 0; i < staging.length; i++) {\n    const buffer = staging[i]!;\n    await runtime.guard(buffer.mapAsync(MAP_MODE_READ), signal);\n    results.push(buffer.getMappedRange(0, Math.ceil(outputs[i]!.bytes / 4) * 4).slice(0));\n    buffer.unmap();\n  }\n  return results;\n}\n\n/** Compiles a compute pipeline; compilation/validation failures are domain errors. */\nexport async function createComputePipeline(runtime: WebGpuRuntime, label: string, code: string,\n  signal: AbortSignal | undefined): Promise<GPUComputePipeline> {\n  const device = runtime.device;\n  device.pushErrorScope(\"validation\");\n  const module = device.createShaderModule({ label, code });\n  const pending = device.createComputePipelineAsync({ label, layout: \"auto\", compute: { module, entryPoint: \"main\" } });\n  const scope = device.popErrorScope();\n  let pipeline: GPUComputePipeline;\n  try {\n    pipeline = await runtime.guard(pending, signal);\n  } catch (error) {\n    if (error instanceof ImageKernelExecutionError) throw error;\n    throw new ImageKernelExecutionError(\"gpu-validation\", `WebGPU could not compile the ${label} kernel.`);\n  }\n  if (await runtime.guard(scope, signal)) {\n    throw new ImageKernelExecutionError(\"gpu-validation\", `WebGPU could not compile the ${label} kernel.`);\n  }\n  return pipeline;\n}\n"]}

package/dist/gpu/wgsl-chart-kernel.d.ts

@@ -0,0 +1,30 @@
+/**
+ * WGSL kernel for the `webgpu-f32` chart-radiance stage (#277), one invocation per query point. It
+ * evaluates the chart's material classification (`resolveChartScene().materialAt`) in float32 and looks up
+ * the material's value in a table the host computed in float64 with the reference's own operations.
+ *
+ * Every classification decision (half-plane, disk, sector, cell and gap boundaries) is evaluated with an
+ * a-priori bound on how far the float32 decision value can be from the float64 reference value: the
+ * point's float32 rounding, each float32 operation (u = 2^-24, correctly rounded + − ×), the float32
+ * rounding of the constants and the reference's own float64 rounding. A point whose decision value lies
+ * within four times its bound is flagged, and the host recomputes it with the reference. So every
+ * unflagged point has exactly the reference's material, and its value is the reference value rounded
+ * once to float32.
+ *
+ * Siemens-star sectors are found from a rough `atan2` (any accuracy) and then decided exactly by the
+ * signs of cross products with the sector boundary directions, so WGSL's 4096-ULP `atan2` bound does not
+ * enter. See docs/WEBGPU.md, "Scene radiance on the GPU".
+ */
+export declare const CHART_WORKGROUP_SIZE = 256;
+/** Preset codes of `Params.preset`, in `CHART_SCENE_PRESETS` order. */
+export declare const CHART_PRESET_CODE: Readonly<{
+    readonly uniform: 0;
+    readonly "slanted-edge": 1;
+    readonly "siemens-star": 2;
+    readonly "step-wedge": 3;
+    readonly "grey-ramp": 4;
+    readonly checkerboard: 5;
+    readonly "point-grid": 6;
+    readonly patches: 7;
+}>;
+export declare const CHART_RADIANCE_WGSL = "\nconst U: f32 = 5.9604644775390625e-8;\nconst SAFETY: f32 = 4.0;\nconst SLACK: f32 = 1e-14;\nconst PI: f32 = 3.14159265358979;\nstruct Params {\n  count: u32, columns: u32, preset: u32, na: u32,\n  nb: u32, nc: u32, wavelength_mode: u32, pad0: u32,\n  f0: f32, f1: f32, f2: f32, f3: f32,\n  f4: f32, f5: f32, f6: f32, f7: f32,\n};\n@group(0) @binding(0) var<uniform> params: Params;\n@group(0) @binding(1) var<storage, read> points: array<vec2<f32>>;\n@group(0) @binding(2) var<storage, read> table: array<f32>;\n@group(0) @binding(3) var<storage, read> aux: array<f32>;\n@group(0) @binding(4) var<storage, read> selectors: array<u32>;\n@group(0) @binding(5) var<storage, read_write> values: array<f32>;\n@group(0) @binding(6) var<storage, read_write> flags: array<u32>;\n\nvar<private> flagged: bool;\nfn check(distance: f32, bound: f32) { if (!(abs(distance) > SAFETY * bound)) { flagged = true; } }\n// Flags t when it lies within the bound of an integer n with lo <= n <= hi.\nfn check_integer(t: f32, bound: f32, lo: f32, hi: f32) {\n  let n = round(t);\n  if (SAFETY * bound >= 0.5) { flagged = true; return; }\n  if (n >= lo && n <= hi) { check(t - n, bound); }\n}\n// x = (a + b) * scale, with the bound of its distance from the float64 reference value.\nfn scaled_sum_bound(a: f32, b: f32, s: f32, scale: f32, x: f32, constant_rounding: f32) -> f32 {\n  return U * ((abs(a) + abs(b) + abs(s)) * abs(scale) + (1.0 + constant_rounding) * abs(x)) + SLACK * (abs(x) + 1.0);\n}\nfn cross_d(u: f32, v: f32, k: u32) -> f32 { return v * aux[2u * k] - u * aux[2u * k + 1u]; }\nfn cross_bound(u: f32, v: f32, k: u32, d: f32) -> f32 {\n  return U * (3.0 * abs(v * aux[2u * k]) + 3.0 * abs(u * aux[2u * k + 1u]) + abs(d)) + SLACK * (abs(u) + abs(v));\n}\nfn material(p: vec2<f32>) -> u32 {\n  let u = p.x;\n  let v = p.y;\n  switch (params.preset) {\n    case 0u: { return 0u; }\n    case 1u: {\n      // Light where u\u00B7cos t \u2212 v\u00B7sin t \u2265 0.\n      let a = u * params.f0;\n      let b = v * params.f1;\n      let d = a - b;\n      check(d, U * (3.0 * abs(a) + 3.0 * abs(b) + abs(d)) + SLACK * (abs(u) + abs(v)));\n      return select(0u, 1u, d >= 0.0);\n    }\n    case 2u: {\n      let uu = u * u;\n      let vv = v * v;\n      let q = uu + vv;\n      check(q - params.f0, U * (4.0 * q + 2.0 * params.f0) + SLACK * (q + params.f0));\n      if (q > params.f0) { return 2u; }\n      let sectors = 2u * params.na;\n      var k = u32(clamp(floor((atan2(v, u) + PI) * f32(params.na) / PI), 0.0, f32(sectors - 1u)));\n      for (var step = 0u; step < 4u; step++) {\n        if (cross_d(u, v, k) < 0.0 && k > 0u) { k = k - 1u; continue; }\n        if (cross_d(u, v, k + 1u) >= 0.0 && k + 1u < sectors) { k = k + 1u; continue; }\n        break;\n      }\n      let lo = cross_d(u, v, k);\n      let hi = cross_d(u, v, k + 1u);\n      if (lo < 0.0 || hi >= 0.0) { flagged = true; }\n      check(lo, cross_bound(u, v, k, lo));\n      check(hi, cross_bound(u, v, k + 1u, hi));\n      return select(0u, 1u, k % 2u == 0u);\n    }\n    case 3u, 4u: {\n      let s = u + 1.0;\n      let t = s * params.f0;\n      check_integer(t, scaled_sum_bound(u, 1.0, s, params.f0, t, 0.0), 1.0, f32(params.na - 1u));\n      return u32(clamp(floor(t), 0.0, f32(params.na - 1u)));\n    }\n    case 5u: {\n      let s = u + 1.0;\n      let x = s * params.f0;\n      let w = params.f1 - v;\n      let y = w * params.f0;\n      check_integer(x, scaled_sum_bound(u, 1.0, s, params.f0, x, 0.0), -3.0e38, 3.0e38);\n      check_integer(y, scaled_sum_bound(params.f1, v, w, params.f0, y, 0.0), -3.0e38, 3.0e38);\n      let i = i32(floor(x));\n      let j = i32(floor(y));\n      return select(0u, 1u, (i + j) % 2 == 0);\n    }\n    case 6u: {\n      let s = u + 1.0;\n      let x = s * params.f0;\n      let w = params.f1 - v;\n      let y = w * params.f2;\n      check_integer(x, scaled_sum_bound(u, 1.0, s, params.f0, x, 0.0), 1.0, f32(params.na - 1u));\n      check_integer(y, scaled_sum_bound(params.f1, v, w, params.f2, y, 1.0), 1.0, f32(params.nb - 1u));\n      let i = u32(clamp(floor(x), 0.0, f32(params.na - 1u)));\n      let j = u32(clamp(floor(y), 0.0, f32(params.nb - 1u)));\n      let c = j * params.na + i;\n      let dx = u - aux[2u * c];\n      let dy = v - aux[2u * c + 1u];\n      let ex = U * (abs(u) + abs(aux[2u * c]) + abs(dx));\n      let ey = U * (abs(v) + abs(aux[2u * c + 1u]) + abs(dy));\n      let d2 = dx * dx + dy * dy;\n      check(d2 - params.f3, 2.0 * (abs(dx) * ex + abs(dy) * ey) + ex * ex + ey * ey + U * (2.0 * d2 + params.f3) + SLACK * (d2 + params.f3));\n      return select(0u, 1u, d2 <= params.f3);\n    }\n    default: {\n      let s = u + 1.0;\n      let fx = s * params.f0;\n      let w = params.f1 - v;\n      let fy = w * params.f2;\n      let bx = scaled_sum_bound(u, 1.0, s, params.f0, fx, 0.0);\n      let by = scaled_sum_bound(params.f1, v, w, params.f2, fy, 1.0);\n      check_integer(fx, bx, -3.0e38, 3.0e38);\n      check_integer(fy, by, -3.0e38, 3.0e38);\n      let background = params.nc;\n      let ifx = floor(fx);\n      let ify = floor(fy);\n      if (ifx < 0.0 || ify < 0.0 || ifx >= f32(params.na) || ify >= f32(params.nb)) { return background; }\n      let index = u32(ify) * params.na + u32(ifx);\n      let x = fx - ifx;\n      let y = fy - ify;\n      check(x - params.f3, bx + U * params.f3);\n      check(x - params.f4, bx + U * params.f4);\n      check(y - params.f3, by + U * params.f3);\n      check(y - params.f4, by + U * params.f4);\n      if (index >= params.nc || x < params.f3 || x > params.f4 || y < params.f3 || y > params.f4) { return background; }\n      return index;\n    }\n  }\n}\n@compute @workgroup_size(256)\nfn main(@builtin(global_invocation_id) gid: vec3<u32>, @builtin(num_workgroups) groups: vec3<u32>) {\n  let i = gid.x + gid.y * groups.x * 256u;\n  if (i >= params.count) { return; }\n  flagged = false;\n  let m = material(points[i]);\n  if (params.wavelength_mode != 0u) {\n    values[i] = table[m * params.columns + selectors[i]];\n  } else {\n    for (var c = 0u; c < params.columns; c++) { values[i * params.columns + c] = table[m * params.columns + c]; }\n  }\n  flags[i] = select(0u, 1u, flagged);\n}\n";

package/dist/gpu/wgsl-chart-kernel.js

@@ -0,0 +1,165 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * WGSL kernel for the `webgpu-f32` chart-radiance stage (#277), one invocation per query point. It
+ * evaluates the chart's material classification (`resolveChartScene().materialAt`) in float32 and looks up
+ * the material's value in a table the host computed in float64 with the reference's own operations.
+ *
+ * Every classification decision (half-plane, disk, sector, cell and gap boundaries) is evaluated with an
+ * a-priori bound on how far the float32 decision value can be from the float64 reference value: the
+ * point's float32 rounding, each float32 operation (u = 2^-24, correctly rounded + − ×), the float32
+ * rounding of the constants and the reference's own float64 rounding. A point whose decision value lies
+ * within four times its bound is flagged, and the host recomputes it with the reference. So every
+ * unflagged point has exactly the reference's material, and its value is the reference value rounded
+ * once to float32.
+ *
+ * Siemens-star sectors are found from a rough `atan2` (any accuracy) and then decided exactly by the
+ * signs of cross products with the sector boundary directions, so WGSL's 4096-ULP `atan2` bound does not
+ * enter. See docs/WEBGPU.md, "Scene radiance on the GPU".
+ */
+export const CHART_WORKGROUP_SIZE = 256;
+/** Preset codes of `Params.preset`, in `CHART_SCENE_PRESETS` order. */
+export const CHART_PRESET_CODE = Object.freeze({ uniform: 0, "slanted-edge": 1, "siemens-star": 2, "step-wedge": 3, "grey-ramp": 4, checkerboard: 5,
+    "point-grid": 6, patches: 7 });
+export const CHART_RADIANCE_WGSL = /* wgsl */ `
+const U: f32 = 5.9604644775390625e-8;
+const SAFETY: f32 = 4.0;
+const SLACK: f32 = 1e-14;
+const PI: f32 = 3.14159265358979;
+struct Params {
+  count: u32, columns: u32, preset: u32, na: u32,
+  nb: u32, nc: u32, wavelength_mode: u32, pad0: u32,
+  f0: f32, f1: f32, f2: f32, f3: f32,
+  f4: f32, f5: f32, f6: f32, f7: f32,
+};
+@group(0) @binding(0) var<uniform> params: Params;
+@group(0) @binding(1) var<storage, read> points: array<vec2<f32>>;
+@group(0) @binding(2) var<storage, read> table: array<f32>;
+@group(0) @binding(3) var<storage, read> aux: array<f32>;
+@group(0) @binding(4) var<storage, read> selectors: array<u32>;
+@group(0) @binding(5) var<storage, read_write> values: array<f32>;
+@group(0) @binding(6) var<storage, read_write> flags: array<u32>;
+
+var<private> flagged: bool;
+fn check(distance: f32, bound: f32) { if (!(abs(distance) > SAFETY * bound)) { flagged = true; } }
+// Flags t when it lies within the bound of an integer n with lo <= n <= hi.
+fn check_integer(t: f32, bound: f32, lo: f32, hi: f32) {
+  let n = round(t);
+  if (SAFETY * bound >= 0.5) { flagged = true; return; }
+  if (n >= lo && n <= hi) { check(t - n, bound); }
+}
+// x = (a + b) * scale, with the bound of its distance from the float64 reference value.
+fn scaled_sum_bound(a: f32, b: f32, s: f32, scale: f32, x: f32, constant_rounding: f32) -> f32 {
+  return U * ((abs(a) + abs(b) + abs(s)) * abs(scale) + (1.0 + constant_rounding) * abs(x)) + SLACK * (abs(x) + 1.0);
+}
+fn cross_d(u: f32, v: f32, k: u32) -> f32 { return v * aux[2u * k] - u * aux[2u * k + 1u]; }
+fn cross_bound(u: f32, v: f32, k: u32, d: f32) -> f32 {
+  return U * (3.0 * abs(v * aux[2u * k]) + 3.0 * abs(u * aux[2u * k + 1u]) + abs(d)) + SLACK * (abs(u) + abs(v));
+}
+fn material(p: vec2<f32>) -> u32 {
+  let u = p.x;
+  let v = p.y;
+  switch (params.preset) {
+    case 0u: { return 0u; }
+    case 1u: {
+      // Light where u·cos t − v·sin t ≥ 0.
+      let a = u * params.f0;
+      let b = v * params.f1;
+      let d = a - b;
+      check(d, U * (3.0 * abs(a) + 3.0 * abs(b) + abs(d)) + SLACK * (abs(u) + abs(v)));
+      return select(0u, 1u, d >= 0.0);
+    }
+    case 2u: {
+      let uu = u * u;
+      let vv = v * v;
+      let q = uu + vv;
+      check(q - params.f0, U * (4.0 * q + 2.0 * params.f0) + SLACK * (q + params.f0));
+      if (q > params.f0) { return 2u; }
+      let sectors = 2u * params.na;
+      var k = u32(clamp(floor((atan2(v, u) + PI) * f32(params.na) / PI), 0.0, f32(sectors - 1u)));
+      for (var step = 0u; step < 4u; step++) {
+        if (cross_d(u, v, k) < 0.0 && k > 0u) { k = k - 1u; continue; }
+        if (cross_d(u, v, k + 1u) >= 0.0 && k + 1u < sectors) { k = k + 1u; continue; }
+        break;
+      }
+      let lo = cross_d(u, v, k);
+      let hi = cross_d(u, v, k + 1u);
+      if (lo < 0.0 || hi >= 0.0) { flagged = true; }
+      check(lo, cross_bound(u, v, k, lo));
+      check(hi, cross_bound(u, v, k + 1u, hi));
+      return select(0u, 1u, k % 2u == 0u);
+    }
+    case 3u, 4u: {
+      let s = u + 1.0;
+      let t = s * params.f0;
+      check_integer(t, scaled_sum_bound(u, 1.0, s, params.f0, t, 0.0), 1.0, f32(params.na - 1u));
+      return u32(clamp(floor(t), 0.0, f32(params.na - 1u)));
+    }
+    case 5u: {
+      let s = u + 1.0;
+      let x = s * params.f0;
+      let w = params.f1 - v;
+      let y = w * params.f0;
+      check_integer(x, scaled_sum_bound(u, 1.0, s, params.f0, x, 0.0), -3.0e38, 3.0e38);
+      check_integer(y, scaled_sum_bound(params.f1, v, w, params.f0, y, 0.0), -3.0e38, 3.0e38);
+      let i = i32(floor(x));
+      let j = i32(floor(y));
+      return select(0u, 1u, (i + j) % 2 == 0);
+    }
+    case 6u: {
+      let s = u + 1.0;
+      let x = s * params.f0;
+      let w = params.f1 - v;
+      let y = w * params.f2;
+      check_integer(x, scaled_sum_bound(u, 1.0, s, params.f0, x, 0.0), 1.0, f32(params.na - 1u));
+      check_integer(y, scaled_sum_bound(params.f1, v, w, params.f2, y, 1.0), 1.0, f32(params.nb - 1u));
+      let i = u32(clamp(floor(x), 0.0, f32(params.na - 1u)));
+      let j = u32(clamp(floor(y), 0.0, f32(params.nb - 1u)));
+      let c = j * params.na + i;
+      let dx = u - aux[2u * c];
+      let dy = v - aux[2u * c + 1u];
+      let ex = U * (abs(u) + abs(aux[2u * c]) + abs(dx));
+      let ey = U * (abs(v) + abs(aux[2u * c + 1u]) + abs(dy));
+      let d2 = dx * dx + dy * dy;
+      check(d2 - params.f3, 2.0 * (abs(dx) * ex + abs(dy) * ey) + ex * ex + ey * ey + U * (2.0 * d2 + params.f3) + SLACK * (d2 + params.f3));
+      return select(0u, 1u, d2 <= params.f3);
+    }
+    default: {
+      let s = u + 1.0;
+      let fx = s * params.f0;
+      let w = params.f1 - v;
+      let fy = w * params.f2;
+      let bx = scaled_sum_bound(u, 1.0, s, params.f0, fx, 0.0);
+      let by = scaled_sum_bound(params.f1, v, w, params.f2, fy, 1.0);
+      check_integer(fx, bx, -3.0e38, 3.0e38);
+      check_integer(fy, by, -3.0e38, 3.0e38);
+      let background = params.nc;
+      let ifx = floor(fx);
+      let ify = floor(fy);
+      if (ifx < 0.0 || ify < 0.0 || ifx >= f32(params.na) || ify >= f32(params.nb)) { return background; }
+      let index = u32(ify) * params.na + u32(ifx);
+      let x = fx - ifx;
+      let y = fy - ify;
+      check(x - params.f3, bx + U * params.f3);
+      check(x - params.f4, bx + U * params.f4);
+      check(y - params.f3, by + U * params.f3);
+      check(y - params.f4, by + U * params.f4);
+      if (index >= params.nc || x < params.f3 || x > params.f4 || y < params.f3 || y > params.f4) { return background; }
+      return index;
+    }
+  }
+}
+@compute @workgroup_size(${CHART_WORKGROUP_SIZE})
+fn main(@builtin(global_invocation_id) gid: vec3<u32>, @builtin(num_workgroups) groups: vec3<u32>) {
+  let i = gid.x + gid.y * groups.x * ${CHART_WORKGROUP_SIZE}u;
+  if (i >= params.count) { return; }
+  flagged = false;
+  let m = material(points[i]);
+  if (params.wavelength_mode != 0u) {
+    values[i] = table[m * params.columns + selectors[i]];
+  } else {
+    for (var c = 0u; c < params.columns; c++) { values[i * params.columns + c] = table[m * params.columns + c]; }
+  }
+  flags[i] = select(0u, 1u, flagged);
+}
+`;
+//# sourceMappingURL=wgsl-chart-kernel.js.map

package/dist/gpu/wgsl-chart-kernel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wgsl-chart-kernel.js","sourceRoot":"","sources":["../../src/gpu/wgsl-chart-kernel.ts"],"names":[],"mappings":"AAAA,sCAAsC;AAEtC;;;;;;;;;;;;;;;;GAgBG;AAEH,MAAM,CAAC,MAAM,oBAAoB,GAAG,GAAG,CAAC;AACxC,uEAAuE;AACvE,MAAM,CAAC,MAAM,iBAAiB,GAAG,MAAM,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,cAAc,EAAE,CAAC,EAAE,cAAc,EAAE,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,WAAW,EAAE,CAAC,EAAE,YAAY,EAAE,CAAC;IACjJ,YAAY,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAW,CAAC,CAAC;AAE1C,MAAM,CAAC,MAAM,mBAAmB,GAAG,UAAU,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;2BAgInB,oBAAoB;;uCAER,oBAAoB;;;;;;;;;;;CAW1D,CAAC","sourcesContent":["// SPDX-License-Identifier: Apache-2.0\n\n/**\n * WGSL kernel for the `webgpu-f32` chart-radiance stage (#277), one invocation per query point. It\n * evaluates the chart's material classification (`resolveChartScene().materialAt`) in float32 and looks up\n * the material's value in a table the host computed in float64 with the reference's own operations.\n *\n * Every classification decision (half-plane, disk, sector, cell and gap boundaries) is evaluated with an\n * a-priori bound on how far the float32 decision value can be from the float64 reference value: the\n * point's float32 rounding, each float32 operation (u = 2^-24, correctly rounded + − ×), the float32\n * rounding of the constants and the reference's own float64 rounding. A point whose decision value lies\n * within four times its bound is flagged, and the host recomputes it with the reference. So every\n * unflagged point has exactly the reference's material, and its value is the reference value rounded\n * once to float32.\n *\n * Siemens-star sectors are found from a rough `atan2` (any accuracy) and then decided exactly by the\n * signs of cross products with the sector boundary directions, so WGSL's 4096-ULP `atan2` bound does not\n * enter. See docs/WEBGPU.md, \"Scene radiance on the GPU\".\n */\n\nexport const CHART_WORKGROUP_SIZE = 256;\n/** Preset codes of `Params.preset`, in `CHART_SCENE_PRESETS` order. */\nexport const CHART_PRESET_CODE = Object.freeze({ uniform: 0, \"slanted-edge\": 1, \"siemens-star\": 2, \"step-wedge\": 3, \"grey-ramp\": 4, checkerboard: 5,\n  \"point-grid\": 6, patches: 7 } as const);\n\nexport const CHART_RADIANCE_WGSL = /* wgsl */ `\nconst U: f32 = 5.9604644775390625e-8;\nconst SAFETY: f32 = 4.0;\nconst SLACK: f32 = 1e-14;\nconst PI: f32 = 3.14159265358979;\nstruct Params {\n  count: u32, columns: u32, preset: u32, na: u32,\n  nb: u32, nc: u32, wavelength_mode: u32, pad0: u32,\n  f0: f32, f1: f32, f2: f32, f3: f32,\n  f4: f32, f5: f32, f6: f32, f7: f32,\n};\n@group(0) @binding(0) var<uniform> params: Params;\n@group(0) @binding(1) var<storage, read> points: array<vec2<f32>>;\n@group(0) @binding(2) var<storage, read> table: array<f32>;\n@group(0) @binding(3) var<storage, read> aux: array<f32>;\n@group(0) @binding(4) var<storage, read> selectors: array<u32>;\n@group(0) @binding(5) var<storage, read_write> values: array<f32>;\n@group(0) @binding(6) var<storage, read_write> flags: array<u32>;\n\nvar<private> flagged: bool;\nfn check(distance: f32, bound: f32) { if (!(abs(distance) > SAFETY * bound)) { flagged = true; } }\n// Flags t when it lies within the bound of an integer n with lo <= n <= hi.\nfn check_integer(t: f32, bound: f32, lo: f32, hi: f32) {\n  let n = round(t);\n  if (SAFETY * bound >= 0.5) { flagged = true; return; }\n  if (n >= lo && n <= hi) { check(t - n, bound); }\n}\n// x = (a + b) * scale, with the bound of its distance from the float64 reference value.\nfn scaled_sum_bound(a: f32, b: f32, s: f32, scale: f32, x: f32, constant_rounding: f32) -> f32 {\n  return U * ((abs(a) + abs(b) + abs(s)) * abs(scale) + (1.0 + constant_rounding) * abs(x)) + SLACK * (abs(x) + 1.0);\n}\nfn cross_d(u: f32, v: f32, k: u32) -> f32 { return v * aux[2u * k] - u * aux[2u * k + 1u]; }\nfn cross_bound(u: f32, v: f32, k: u32, d: f32) -> f32 {\n  return U * (3.0 * abs(v * aux[2u * k]) + 3.0 * abs(u * aux[2u * k + 1u]) + abs(d)) + SLACK * (abs(u) + abs(v));\n}\nfn material(p: vec2<f32>) -> u32 {\n  let u = p.x;\n  let v = p.y;\n  switch (params.preset) {\n    case 0u: { return 0u; }\n    case 1u: {\n      // Light where u·cos t − v·sin t ≥ 0.\n      let a = u * params.f0;\n      let b = v * params.f1;\n      let d = a - b;\n      check(d, U * (3.0 * abs(a) + 3.0 * abs(b) + abs(d)) + SLACK * (abs(u) + abs(v)));\n      return select(0u, 1u, d >= 0.0);\n    }\n    case 2u: {\n      let uu = u * u;\n      let vv = v * v;\n      let q = uu + vv;\n      check(q - params.f0, U * (4.0 * q + 2.0 * params.f0) + SLACK * (q + params.f0));\n      if (q > params.f0) { return 2u; }\n      let sectors = 2u * params.na;\n      var k = u32(clamp(floor((atan2(v, u) + PI) * f32(params.na) / PI), 0.0, f32(sectors - 1u)));\n      for (var step = 0u; step < 4u; step++) {\n        if (cross_d(u, v, k) < 0.0 && k > 0u) { k = k - 1u; continue; }\n        if (cross_d(u, v, k + 1u) >= 0.0 && k + 1u < sectors) { k = k + 1u; continue; }\n        break;\n      }\n      let lo = cross_d(u, v, k);\n      let hi = cross_d(u, v, k + 1u);\n      if (lo < 0.0 || hi >= 0.0) { flagged = true; }\n      check(lo, cross_bound(u, v, k, lo));\n      check(hi, cross_bound(u, v, k + 1u, hi));\n      return select(0u, 1u, k % 2u == 0u);\n    }\n    case 3u, 4u: {\n      let s = u + 1.0;\n      let t = s * params.f0;\n      check_integer(t, scaled_sum_bound(u, 1.0, s, params.f0, t, 0.0), 1.0, f32(params.na - 1u));\n      return u32(clamp(floor(t), 0.0, f32(params.na - 1u)));\n    }\n    case 5u: {\n      let s = u + 1.0;\n      let x = s * params.f0;\n      let w = params.f1 - v;\n      let y = w * params.f0;\n      check_integer(x, scaled_sum_bound(u, 1.0, s, params.f0, x, 0.0), -3.0e38, 3.0e38);\n      check_integer(y, scaled_sum_bound(params.f1, v, w, params.f0, y, 0.0), -3.0e38, 3.0e38);\n      let i = i32(floor(x));\n      let j = i32(floor(y));\n      return select(0u, 1u, (i + j) % 2 == 0);\n    }\n    case 6u: {\n      let s = u + 1.0;\n      let x = s * params.f0;\n      let w = params.f1 - v;\n      let y = w * params.f2;\n      check_integer(x, scaled_sum_bound(u, 1.0, s, params.f0, x, 0.0), 1.0, f32(params.na - 1u));\n      check_integer(y, scaled_sum_bound(params.f1, v, w, params.f2, y, 1.0), 1.0, f32(params.nb - 1u));\n      let i = u32(clamp(floor(x), 0.0, f32(params.na - 1u)));\n      let j = u32(clamp(floor(y), 0.0, f32(params.nb - 1u)));\n      let c = j * params.na + i;\n      let dx = u - aux[2u * c];\n      let dy = v - aux[2u * c + 1u];\n      let ex = U * (abs(u) + abs(aux[2u * c]) + abs(dx));\n      let ey = U * (abs(v) + abs(aux[2u * c + 1u]) + abs(dy));\n      let d2 = dx * dx + dy * dy;\n      check(d2 - params.f3, 2.0 * (abs(dx) * ex + abs(dy) * ey) + ex * ex + ey * ey + U * (2.0 * d2 + params.f3) + SLACK * (d2 + params.f3));\n      return select(0u, 1u, d2 <= params.f3);\n    }\n    default: {\n      let s = u + 1.0;\n      let fx = s * params.f0;\n      let w = params.f1 - v;\n      let fy = w * params.f2;\n      let bx = scaled_sum_bound(u, 1.0, s, params.f0, fx, 0.0);\n      let by = scaled_sum_bound(params.f1, v, w, params.f2, fy, 1.0);\n      check_integer(fx, bx, -3.0e38, 3.0e38);\n      check_integer(fy, by, -3.0e38, 3.0e38);\n      let background = params.nc;\n      let ifx = floor(fx);\n      let ify = floor(fy);\n      if (ifx < 0.0 || ify < 0.0 || ifx >= f32(params.na) || ify >= f32(params.nb)) { return background; }\n      let index = u32(ify) * params.na + u32(ifx);\n      let x = fx - ifx;\n      let y = fy - ify;\n      check(x - params.f3, bx + U * params.f3);\n      check(x - params.f4, bx + U * params.f4);\n      check(y - params.f3, by + U * params.f3);\n      check(y - params.f4, by + U * params.f4);\n      if (index >= params.nc || x < params.f3 || x > params.f4 || y < params.f3 || y > params.f4) { return background; }\n      return index;\n    }\n  }\n}\n@compute @workgroup_size(${CHART_WORKGROUP_SIZE})\nfn main(@builtin(global_invocation_id) gid: vec3<u32>, @builtin(num_workgroups) groups: vec3<u32>) {\n  let i = gid.x + gid.y * groups.x * ${CHART_WORKGROUP_SIZE}u;\n  if (i >= params.count) { return; }\n  flagged = false;\n  let m = material(points[i]);\n  if (params.wavelength_mode != 0u) {\n    values[i] = table[m * params.columns + selectors[i]];\n  } else {\n    for (var c = 0u; c < params.columns; c++) { values[i * params.columns + c] = table[m * params.columns + c]; }\n  }\n  flags[i] = select(0u, 1u, flagged);\n}\n`;\n"]}

package/dist/gpu/wgsl-kernels.d.ts

@@ -0,0 +1,53 @@
+/**
+ * The project's own WGSL (WebGPU shader language) compute kernels for the `webgpu-f32` image-kernel
+ * backend. Each kernel evaluates the same equations, in the same order, as its float64 CPU reference:
+ * - SDR: `calculateSdrRendering` / native capture SDR (exposure → tone → gamut → sRGB → nearest-ties-up);
+ * - RAW development: `createNativeRawDevelopmentTask` (CFA kernel sums → WB gains → camera→XYZ →
+ *   XYZ→linear sRGB → SDR);
+ * - irradiance convolution: `convolveIrradianceRows` (source-indexed isoplanatic-patch gather).
+ * The host packers in image-kernel-accelerator.ts use matching uniform layouts.
+ */
+/**
+ * Counter slots shared by the SDR-producing kernels. `linearBoundBits` holds the float32 bits of the
+ * largest per-sample linear bound of a luminance tone curve (a maximum, not a sum: non-negative float32
+ * bit patterns order like their values). `luminanceDomain` counts samples outside the float32 domain.
+ */
+export declare const SDR_COUNTER: Readonly<{
+    negative: 0;
+    above: 1;
+    changed: 2;
+    low: 3;
+    high: 4;
+    outOfGamut: 5;
+    uncertain: 6;
+    gamutUncertain: 7;
+    saturatedPixels: 8;
+    whiteBalanceClipped: 9;
+    reconstructedPixels: 10;
+    linearBoundBits: 11;
+    luminanceDomain: 12;
+}>;
+export declare const SDR_COUNTER_SLOTS = 16;
+/** Tone modes of the luminance kernels (`Params.tone_mode`); 0 is a per-channel curve. */
+export declare const SDR_TONE_MODE: Readonly<{
+    perChannel: 0;
+    extendedReinhard: 1;
+    nakaRushton: 2;
+}>;
+export declare const LINEAR_WORKGROUP_SIZE = 256;
+export declare const CONVOLUTION_WORKGROUP_EDGE = 16;
+/** Pointwise SDR over a packed float32 band; one invocation per sample. */
+export declare const SDR_WGSL: string;
+/** Pointwise SDR with a luminance tone curve over a packed float32 band; one invocation per pixel. */
+export declare const SDR_LUMINANCE_WGSL: string;
+/**
+ * Packed native RAW development of one band of output rows; one invocation per output pixel.
+ * `normalized` holds the host's float64 site values, rounded once to float32. A saturated site
+ * (flagged, or at or above its phase white level) is exactly 1. Any other site is
+ * (code − black)/(white − black) ≤ 1 − 1/65535. So a saturated contributing site is recognised exactly.
+ * Highlight handling matches `prepareSensorColorDevelopment` (clip at the smallest applied gain, or the
+ * declared neutral blend).
+ */
+export declare const RAW_DEVELOPMENT_WGSL: string;
+/** Source-indexed isoplanatic-patch convolution of one output-row band; one invocation per output site. */
+export declare const IRRADIANCE_CONVOLUTION_WGSL = "\nstruct Params {\n  width: u32, height: u32, radius: u32, size: u32,\n  patch_w: u32, patch_h: u32, cols: u32, rows: u32,\n  out_row0: u32, out_rows: u32, in_row0: u32, taps: u32,\n};\n@group(0) @binding(0) var<uniform> params: Params;\n@group(0) @binding(1) var<storage, read> source: array<f32>;\n@group(0) @binding(2) var<storage, read> kernels: array<f32>;\n@group(0) @binding(3) var<storage, read_write> result: array<f32>;\n@compute @workgroup_size(16, 16)\nfn main(@builtin(global_invocation_id) gid: vec3<u32>) {\n  let x = gid.x;\n  let local_y = gid.y;\n  if (x >= params.width || local_y >= params.out_rows) { return; }\n  let y = i32(params.out_row0 + local_y);\n  let r = i32(params.radius);\n  var sum = 0.0;\n  for (var v = -r; v <= r; v++) {\n    let sy = y - v;\n    if (sy < 0 || sy >= i32(params.height)) { continue; }\n    let patch_row = min(u32(sy) / params.patch_h, params.rows - 1u) * params.cols;\n    let kernel_row = (v + r) * i32(params.size) + r;\n    let source_row = (u32(sy) - params.in_row0) * params.width;\n    for (var u = -r; u <= r; u++) {\n      let sx = i32(x) - u;\n      if (sx < 0 || sx >= i32(params.width)) { continue; }\n      let patch_index = patch_row + min(u32(sx) / params.patch_w, params.cols - 1u);\n      sum = sum + source[source_row + u32(sx)] * kernels[patch_index * params.taps + u32(kernel_row + u)];\n    }\n  }\n  result[local_y * params.width + x] = sum;\n}\n";