@photivra/engine 2.10.0 → 2.12.0

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

@@ -0,0 +1,146 @@
+import type { ChartCompositeProbeRecord, ImageKernelAdapterDescription, ImageKernelExecution, ImageKernelFallbackReason } from "../gpu/image-kernel-execution.js";
+import type { DisplayViewRenderResult, DisplayViewSetup } from "./display-view.js";
+import type { SimulateCaptureFastReport } from "./simulate-capture.js";
+/**
+ * 2.11 (#481): whether a prepared display view may render on the GPU. `"off"` (the default) is the CPU reference, today's
+ * behaviour byte for byte. `"auto"` renders on WebGPU when a conforming device is available and the request is supported, and
+ * otherwise runs the CPU reference and says why. `"require"` fails instead of falling back. In the accelerator's words: `"auto"`
+ * is `backend: "webgpu-f32"` with `fallback: "cpu-reference"`, `"require"` is `fallback: "fail"`, `"off"` is `backend: "cpu-reference"`.
+ */
+export type DisplayViewGpuMode = "off" | "auto" | "require";
+/** 2.11 (#481): the second argument of `prepareDisplayView`. */
+export interface PrepareDisplayViewOptions {
+    /** See {@link DisplayViewGpuMode}. Default `"off"`. */
+    gpu?: DisplayViewGpuMode;
+    /**
+     * Where the device comes from, with `gpu: "auto"` or `"require"`: a WebGPU entry point (a worker's `navigator.gpu`), or an
+     * `ImageKernelAccelerator` whose device the view shares (the accelerator keeps ownership; `dispose()` of the prepared view
+     * leaves it alone). Without it the engine acquires a device from `globalThis.navigator.gpu` and owns it until `dispose()`.
+     * Refused with `gpu: "off"`.
+     */
+    gpuDevice?: unknown;
+}
+/** The parsed form of {@link PrepareDisplayViewOptions}. @internal */
+export interface ParsedPrepareDisplayViewOptions {
+    gpu: DisplayViewGpuMode;
+    gpuDevice: unknown;
+}
+/** Internal: validates the second argument of `prepareDisplayView`. */
+export declare function parsePrepareDisplayViewOptions(value: unknown): ParsedPrepareDisplayViewOptions;
+/**
+ * 2.11 (#481): why a display view that asked for the GPU (`gpu: "auto"`) ran the CPU reference. The accelerator's acquisition
+ * reasons, plus: `unsupported-on-backend` (no GPU display-view renderer exists in this version, or it does not support the
+ * request), `conformance-failed` (the device failed the run-time self-check before the view's first GPU render), `device-lost`
+ * (the device was lost; the rest of the view runs on the CPU) and `disposed` (the prepared view was disposed).
+ */
+export type DisplayViewGpuFallbackReason = ImageKernelFallbackReason | "unsupported-on-backend" | "conformance-failed" | "device-lost" | "disposed";
+/** 2.11 (#481): the run-time conformance self-check of a device, run once before the view's first GPU render. */
+export interface DisplayViewGpuConformance {
+    /** The ids of the cases run, in order (the built-in image-kernel cases, then the renderer's own). */
+    cases: readonly string[];
+    passed: boolean;
+    /** The first case that failed, or null. */
+    failedCase: string | null;
+    /** What the failed case reported, or null. */
+    detail: string | null;
+}
+/**
+ * 2.11 (#481): where a display view's render ran, in the words of the image-kernel execution record (`ImageKernelExecution`):
+ * `backend` names the path that ran (`cpu-reference`, the float64 engine reference, or `webgpu-f32`, a float32 approximation
+ * within `errorBound`), `requestedBackend` what `gpu` asked for, and `fallbackReason` why a request for the GPU ran the CPU.
+ * `adapter` describes the device's adapter whenever one was involved, also when the view then fell back; `conformance` is
+ * the device's self-check once it has run. A CPU render keeps `assurance: "engine-reference"` and `fast: false`.
+ */
+export interface DisplayViewExecution extends Omit<ImageKernelExecution, "fallbackReason"> {
+    /** The `gpu` option the view was prepared with. */
+    gpu: DisplayViewGpuMode;
+    fallbackReason: DisplayViewGpuFallbackReason | null;
+    adapter: ImageKernelAdapterDescription | null;
+    conformance: DisplayViewGpuConformance | null;
+    /**
+     * 2.11: the composite chart kernel's device probe when this render needed it (composite charts, the 2.3 elements and
+     * `material-layers` scenes): the device class and the product path the kernel ran with, or, on a refusal (`fallbackReason`
+     * `unsupported-on-backend`), why. Null when the render did not run the probe (the 2.0 presets, `gpu: "off"`).
+     */
+    compositeProbe: ChartCompositeProbeRecord | null;
+}
+/** 2.11 (#481): `diagnostics.fast` of a display view: the capture's report plus where the render ran. */
+export interface DisplayViewFastReport extends SimulateCaptureFastReport {
+    /** Where this render ran (see {@link DisplayViewExecution}). `assurance` above follows it. */
+    execution: DisplayViewExecution;
+}
+/** Internal: the execution record of a display view rendered on the CPU reference. `requested` names what `gpu` asked for. */
+export declare function cpuDisplayViewExecution(gpu: DisplayViewGpuMode, fallbackReason: DisplayViewGpuFallbackReason | null, adapter: ImageKernelAdapterDescription | null, conformance: DisplayViewGpuConformance | null, detail?: string, compositeProbe?: ChartCompositeProbeRecord | null): DisplayViewExecution;
+/**
+ * Internal (#481): the device a renderer or conformance case runs on. It is the engine's `WebGpuRuntime` object
+ * (`src/gpu/webgpu-runtime.ts`: `device`, `guard`, `destroy` and the rest), seen here through its WebGPU-free members only so
+ * that no WebGPU type reaches the published declarations (docs/WEBGPU.md); a renderer in the engine casts it to `WebGpuRuntime`.
+ */
+export interface DisplayViewGpuRuntimeHandle {
+    readonly adapter: ImageKernelAdapterDescription | null;
+    readonly maximumStorageBindingBytes: number;
+    readonly maximumWorkgroupsPerDimension: number;
+    isLost(): boolean;
+}
+/** What a prepared request asks of a GPU renderer (`supports`): the options that shape a render. */
+export interface DisplayViewGpuRequest {
+    ahd: boolean;
+    diffraction: boolean;
+    antiAliasing: boolean;
+    /** Pixel-aperture samples per axis (1: centre sampling). */
+    boxSamples: number;
+    toneCurve: "identity" | "positive-reinhard-per-channel";
+    /**
+     * #492: true when `lens.defocus` needs the defocus disc (out of focus): the expected signal then carries the disc, or each
+     * node's diffraction kernel convolved with it, as site kernels (#492 step 2b), which the engine's renderer gathers in its
+     * Quality site pass (step 2c). Absent or false otherwise.
+     */
+    defocus?: boolean;
+    /** The scene's form: an engine chart, a declared `material-layers` scene (#491), or a caller function. */
+    scene: "chart" | "material-layers" | "material-function" | "reflectance-function" | "radiance-function";
+}
+/** One render of a region: the CPU renderer's own setup (tables, readout, demosaic, region, callbacks) and the render's signal. */
+export interface DisplayViewGpuPart {
+    setup: DisplayViewSetup;
+    signal: AbortSignal | undefined;
+}
+/** What a GPU render returns: the CPU renderer's result shape plus the a-priori bound of its values against the reference. */
+export interface DisplayViewGpuRenderOutput extends DisplayViewRenderResult {
+    errorBound: NonNullable<ImageKernelExecution["errorBound"]>;
+    /** Samples whose float32 classification fell inside its bound (0 when none). */
+    diagnosticUncertaintySampleCount?: number;
+    /** The composite chart kernel's device probe record, when the render used the composite material module. */
+    compositeProbe?: ChartCompositeProbeRecord;
+}
+/** A conformance case: returns `true` when the device agrees with the reference within the case's bound, or a sentence saying how it did not. */
+export interface DisplayViewGpuConformanceCase {
+    id: string;
+    run(runtime: DisplayViewGpuRuntimeHandle, signal: AbortSignal | undefined): Promise<true | string>;
+}
+/**
+ * Internal (#481): the contract a GPU display-view renderer fulfils (#478). One instance serves one device, created by the
+ * registered factory for each prepared view that acquires or shares a device. `supports` says whether the renderer covers a
+ * prepared request (`true`) or why not (a sentence; the view then runs the CPU reference labelled `unsupported-on-backend`).
+ * `render` renders one region on the device and must throw `ImageKernelExecutionError` with reason `device-lost` or `aborted`
+ * for those two events, as the accelerator's operations do; a render that throws `unsupported-on-backend` (a request the
+ * renderer finds it does not cover only when rendering) runs the CPU reference labelled with that reason, or fails with it under
+ * `"require"`. `conformanceCases` are run after the built-in image-kernel cases before the device's first render; a failure keeps
+ * the whole view on the CPU. `dispose` releases what the renderer holds on the device (#491: uploaded scene records); the session
+ * calls it when the prepared view is disposed.
+ */
+export interface DisplayViewGpuRenderer {
+    readonly id: string;
+    supports(request: DisplayViewGpuRequest): true | string;
+    render(part: DisplayViewGpuPart): Promise<DisplayViewGpuRenderOutput>;
+    readonly conformanceCases?: readonly DisplayViewGpuConformanceCase[];
+    dispose?(): void;
+}
+export type DisplayViewGpuRendererFactory = (runtime: DisplayViewGpuRuntimeHandle) => DisplayViewGpuRenderer;
+/**
+ * Internal (#481): registers the renderer that `prepareDisplayView` uses for `gpu: "auto" | "require"`, and returns the one
+ * registered before (null: none). #478's renderer registers itself here; tests register a fake. With none registered no device
+ * is requested and every GPU request falls back (or fails) with `unsupported-on-backend`.
+ */
+export declare function setDisplayViewGpuRendererFactory(factory: DisplayViewGpuRendererFactory | null): DisplayViewGpuRendererFactory | null;
+/** Internal: the registered factory. */
+export declare function displayViewGpuRendererFactory(): DisplayViewGpuRendererFactory | null;

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

@@ -0,0 +1,59 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * #481: how a prepared display view chooses between a WebGPU preview renderer and the CPU reference, and how a render labels
+ * which ran. This module holds the option, the label and the renderer contract and imports nothing from the GPU code, so a
+ * bundle that never asks for the GPU (`gpu: "off"`, the default) does not contain it; the device handling lives in
+ * `display-view-gpu-session.ts`, loaded on demand by `prepareDisplayView` when `gpu` is `"auto"` or `"require"`.
+ *
+ * The vocabulary is the image-kernel accelerator's (`createImageKernelAccelerator`, docs/WEBGPU.md): `"auto"` is
+ * `backend: "webgpu-f32"` with `fallback: "cpu-reference"`, `"require"` is `fallback: "fail"`, `"off"` is
+ * `backend: "cpu-reference"`. The render's `diagnostics.fast.execution` names the backend that ran, the fallback reason and the
+ * bound in the fields of `ImageKernelExecution`, plus the adapter and the run-time conformance check.
+ *
+ * No GPU display-view renderer exists yet (#478, #479): until one registers itself through {@link setDisplayViewGpuRendererFactory},
+ * `"auto"` runs the CPU reference labelled `unsupported-on-backend` without touching a device, and `"require"` fails with that reason.
+ */
+import { InvalidConfigurationError } from "../core/configuration-error.js";
+/** Internal: validates the second argument of `prepareDisplayView`. */
+export function parsePrepareDisplayViewOptions(value) {
+    if (value === undefined)
+        return { gpu: "off", gpuDevice: undefined };
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        throw new InvalidConfigurationError("prepareDisplayView options must be an object { gpu, gpuDevice }.");
+    for (const key of Object.keys(value))
+        if (key !== "gpu" && key !== "gpuDevice")
+            throw new InvalidConfigurationError("Unknown prepareDisplayView options field: " + key + ".");
+    const { gpu, gpuDevice } = value;
+    const mode = gpu === undefined ? "off" : gpu;
+    if (mode !== "off" && mode !== "auto" && mode !== "require")
+        throw new InvalidConfigurationError("prepareDisplayView options.gpu must be \"off\", \"auto\" or \"require\".");
+    if (gpuDevice !== undefined && (typeof gpuDevice !== "object" || gpuDevice === null))
+        throw new InvalidConfigurationError("prepareDisplayView options.gpuDevice must be a WebGPU entry point (navigator.gpu) or an ImageKernelAccelerator.");
+    if (gpuDevice !== undefined && mode === "off")
+        throw new InvalidConfigurationError("prepareDisplayView options.gpuDevice needs gpu \"auto\" or \"require\".");
+    return { gpu: mode, gpuDevice };
+}
+const CPU_LIMITATIONS = Object.freeze(["Float64 engine reference execution; results are the reference by definition"]);
+/** Internal: the execution record of a display view rendered on the CPU reference. `requested` names what `gpu` asked for. */
+export function cpuDisplayViewExecution(gpu, fallbackReason, adapter, conformance, detail, compositeProbe = null) {
+    const requestedBackend = gpu === "off" ? "cpu-reference" : "webgpu-f32";
+    const limitations = detail === undefined ? CPU_LIMITATIONS : Object.freeze([...CPU_LIMITATIONS, "WebGPU was requested (gpu: \"" + gpu + "\") and the CPU reference ran: " + detail]);
+    return Object.freeze({ gpu, backend: "cpu-reference", requestedBackend, fallbackReason, arithmetic: "float64", assurance: "engine-reference", fast: false,
+        bitIdenticalToReference: true, errorBound: null, diagnosticsExact: true, diagnosticUncertaintySampleCount: 0, limitations, adapter, conformance, compositeProbe });
+}
+let rendererFactory = null;
+/**
+ * Internal (#481): registers the renderer that `prepareDisplayView` uses for `gpu: "auto" | "require"`, and returns the one
+ * registered before (null: none). #478's renderer registers itself here; tests register a fake. With none registered no device
+ * is requested and every GPU request falls back (or fails) with `unsupported-on-backend`.
+ */
+export function setDisplayViewGpuRendererFactory(factory) {
+    if (factory !== null && typeof factory !== "function")
+        throw new InvalidConfigurationError("setDisplayViewGpuRendererFactory expects a function or null.");
+    const previous = rendererFactory;
+    rendererFactory = factory;
+    return previous;
+}
+/** Internal: the registered factory. */
+export function displayViewGpuRendererFactory() { return rendererFactory; }
+//# sourceMappingURL=display-view-gpu.js.map

package/dist/facade/display-view-gpu.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"display-view-gpu.js","sourceRoot":"","sources":["../../src/facade/display-view-gpu.ts"],"names":[],"mappings":"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","sourcesContent":["// SPDX-License-Identifier: Apache-2.0\n\n/**\n * #481: how a prepared display view chooses between a WebGPU preview renderer and the CPU reference, and how a render labels\n * which ran. This module holds the option, the label and the renderer contract and imports nothing from the GPU code, so a\n * bundle that never asks for the GPU (`gpu: \"off\"`, the default) does not contain it; the device handling lives in\n * `display-view-gpu-session.ts`, loaded on demand by `prepareDisplayView` when `gpu` is `\"auto\"` or `\"require\"`.\n *\n * The vocabulary is the image-kernel accelerator's (`createImageKernelAccelerator`, docs/WEBGPU.md): `\"auto\"` is\n * `backend: \"webgpu-f32\"` with `fallback: \"cpu-reference\"`, `\"require\"` is `fallback: \"fail\"`, `\"off\"` is\n * `backend: \"cpu-reference\"`. The render's `diagnostics.fast.execution` names the backend that ran, the fallback reason and the\n * bound in the fields of `ImageKernelExecution`, plus the adapter and the run-time conformance check.\n *\n * No GPU display-view renderer exists yet (#478, #479): until one registers itself through {@link setDisplayViewGpuRendererFactory},\n * `\"auto\"` runs the CPU reference labelled `unsupported-on-backend` without touching a device, and `\"require\"` fails with that reason.\n */\n\nimport { InvalidConfigurationError } from \"../core/configuration-error.js\";\nimport type { ChartCompositeProbeRecord, ImageKernelAdapterDescription, ImageKernelBackend, ImageKernelExecution, ImageKernelFallbackReason } from \"../gpu/image-kernel-execution.js\";\nimport type { DisplayViewRenderResult, DisplayViewSetup } from \"./display-view.js\";\nimport type { SimulateCaptureFastReport } from \"./simulate-capture.js\";\n\n/**\n * 2.11 (#481): whether a prepared display view may render on the GPU. `\"off\"` (the default) is the CPU reference, today's\n * behaviour byte for byte. `\"auto\"` renders on WebGPU when a conforming device is available and the request is supported, and\n * otherwise runs the CPU reference and says why. `\"require\"` fails instead of falling back. In the accelerator's words: `\"auto\"`\n * is `backend: \"webgpu-f32\"` with `fallback: \"cpu-reference\"`, `\"require\"` is `fallback: \"fail\"`, `\"off\"` is `backend: \"cpu-reference\"`.\n */\nexport type DisplayViewGpuMode = \"off\" | \"auto\" | \"require\";\n\n/** 2.11 (#481): the second argument of `prepareDisplayView`. */\nexport interface PrepareDisplayViewOptions {\n  /** See {@link DisplayViewGpuMode}. Default `\"off\"`. */\n  gpu?: DisplayViewGpuMode;\n  /**\n   * Where the device comes from, with `gpu: \"auto\"` or `\"require\"`: a WebGPU entry point (a worker's `navigator.gpu`), or an\n   * `ImageKernelAccelerator` whose device the view shares (the accelerator keeps ownership; `dispose()` of the prepared view\n   * leaves it alone). Without it the engine acquires a device from `globalThis.navigator.gpu` and owns it until `dispose()`.\n   * Refused with `gpu: \"off\"`.\n   */\n  gpuDevice?: unknown;\n}\n\n/** The parsed form of {@link PrepareDisplayViewOptions}. @internal */\nexport interface ParsedPrepareDisplayViewOptions { gpu: DisplayViewGpuMode; gpuDevice: unknown }\n\n/** Internal: validates the second argument of `prepareDisplayView`. */\nexport function parsePrepareDisplayViewOptions(value: unknown): ParsedPrepareDisplayViewOptions {\n  if (value === undefined) return { gpu: \"off\", gpuDevice: undefined };\n  if (typeof value !== \"object\" || value === null || Array.isArray(value)) throw new InvalidConfigurationError(\"prepareDisplayView options must be an object { gpu, gpuDevice }.\");\n  for (const key of Object.keys(value)) if (key !== \"gpu\" && key !== \"gpuDevice\") throw new InvalidConfigurationError(\"Unknown prepareDisplayView options field: \" + key + \".\");\n  const { gpu, gpuDevice } = value as Record<string, unknown>;\n  const mode: DisplayViewGpuMode = gpu === undefined ? \"off\" : gpu as DisplayViewGpuMode;\n  if (mode !== \"off\" && mode !== \"auto\" && mode !== \"require\") throw new InvalidConfigurationError(\"prepareDisplayView options.gpu must be \\\"off\\\", \\\"auto\\\" or \\\"require\\\".\");\n  if (gpuDevice !== undefined && (typeof gpuDevice !== \"object\" || gpuDevice === null)) throw new InvalidConfigurationError(\"prepareDisplayView options.gpuDevice must be a WebGPU entry point (navigator.gpu) or an ImageKernelAccelerator.\");\n  if (gpuDevice !== undefined && mode === \"off\") throw new InvalidConfigurationError(\"prepareDisplayView options.gpuDevice needs gpu \\\"auto\\\" or \\\"require\\\".\");\n  return { gpu: mode, gpuDevice };\n}\n\n/**\n * 2.11 (#481): why a display view that asked for the GPU (`gpu: \"auto\"`) ran the CPU reference. The accelerator's acquisition\n * reasons, plus: `unsupported-on-backend` (no GPU display-view renderer exists in this version, or it does not support the\n * request), `conformance-failed` (the device failed the run-time self-check before the view's first GPU render), `device-lost`\n * (the device was lost; the rest of the view runs on the CPU) and `disposed` (the prepared view was disposed).\n */\nexport type DisplayViewGpuFallbackReason = ImageKernelFallbackReason | \"unsupported-on-backend\" | \"conformance-failed\" | \"device-lost\" | \"disposed\";\n\n/** 2.11 (#481): the run-time conformance self-check of a device, run once before the view's first GPU render. */\nexport interface DisplayViewGpuConformance {\n  /** The ids of the cases run, in order (the built-in image-kernel cases, then the renderer's own). */\n  cases: readonly string[];\n  passed: boolean;\n  /** The first case that failed, or null. */\n  failedCase: string | null;\n  /** What the failed case reported, or null. */\n  detail: string | null;\n}\n\n/**\n * 2.11 (#481): where a display view's render ran, in the words of the image-kernel execution record (`ImageKernelExecution`):\n * `backend` names the path that ran (`cpu-reference`, the float64 engine reference, or `webgpu-f32`, a float32 approximation\n * within `errorBound`), `requestedBackend` what `gpu` asked for, and `fallbackReason` why a request for the GPU ran the CPU.\n * `adapter` describes the device's adapter whenever one was involved, also when the view then fell back; `conformance` is\n * the device's self-check once it has run. A CPU render keeps `assurance: \"engine-reference\"` and `fast: false`.\n */\nexport interface DisplayViewExecution extends Omit<ImageKernelExecution, \"fallbackReason\"> {\n  /** The `gpu` option the view was prepared with. */\n  gpu: DisplayViewGpuMode;\n  fallbackReason: DisplayViewGpuFallbackReason | null;\n  adapter: ImageKernelAdapterDescription | null;\n  conformance: DisplayViewGpuConformance | null;\n  /**\n   * 2.11: the composite chart kernel's device probe when this render needed it (composite charts, the 2.3 elements and\n   * `material-layers` scenes): the device class and the product path the kernel ran with, or, on a refusal (`fallbackReason`\n   * `unsupported-on-backend`), why. Null when the render did not run the probe (the 2.0 presets, `gpu: \"off\"`).\n   */\n  compositeProbe: ChartCompositeProbeRecord | null;\n}\n\n/** 2.11 (#481): `diagnostics.fast` of a display view: the capture's report plus where the render ran. */\nexport interface DisplayViewFastReport extends SimulateCaptureFastReport {\n  /** Where this render ran (see {@link DisplayViewExecution}). `assurance` above follows it. */\n  execution: DisplayViewExecution;\n}\n\nconst CPU_LIMITATIONS = Object.freeze([\"Float64 engine reference execution; results are the reference by definition\"]);\n\n/** Internal: the execution record of a display view rendered on the CPU reference. `requested` names what `gpu` asked for. */\nexport function cpuDisplayViewExecution(gpu: DisplayViewGpuMode, fallbackReason: DisplayViewGpuFallbackReason | null, adapter: ImageKernelAdapterDescription | null,\n  conformance: DisplayViewGpuConformance | null, detail?: string, compositeProbe: ChartCompositeProbeRecord | null = null): DisplayViewExecution {\n  const requestedBackend: ImageKernelBackend = gpu === \"off\" ? \"cpu-reference\" : \"webgpu-f32\";\n  const limitations = detail === undefined ? CPU_LIMITATIONS : Object.freeze([...CPU_LIMITATIONS, \"WebGPU was requested (gpu: \\\"\" + gpu + \"\\\") and the CPU reference ran: \" + detail]);\n  return Object.freeze({ gpu, backend: \"cpu-reference\", requestedBackend, fallbackReason, arithmetic: \"float64\", assurance: \"engine-reference\", fast: false,\n    bitIdenticalToReference: true, errorBound: null, diagnosticsExact: true, diagnosticUncertaintySampleCount: 0, limitations, adapter, conformance, compositeProbe });\n}\n\n// ---------------------------------------------------------------------------------------------------------------\n// The renderer contract (#478 implements it; until then the only implementation is a test fake).\n\n/**\n * Internal (#481): the device a renderer or conformance case runs on. It is the engine's `WebGpuRuntime` object\n * (`src/gpu/webgpu-runtime.ts`: `device`, `guard`, `destroy` and the rest), seen here through its WebGPU-free members only so\n * that no WebGPU type reaches the published declarations (docs/WEBGPU.md); a renderer in the engine casts it to `WebGpuRuntime`.\n */\nexport interface DisplayViewGpuRuntimeHandle {\n  readonly adapter: ImageKernelAdapterDescription | null;\n  readonly maximumStorageBindingBytes: number;\n  readonly maximumWorkgroupsPerDimension: number;\n  isLost(): boolean;\n}\n\n/** What a prepared request asks of a GPU renderer (`supports`): the options that shape a render. */\nexport interface DisplayViewGpuRequest {\n  ahd: boolean;\n  diffraction: boolean;\n  antiAliasing: boolean;\n  /** Pixel-aperture samples per axis (1: centre sampling). */\n  boxSamples: number;\n  toneCurve: \"identity\" | \"positive-reinhard-per-channel\";\n  /**\n   * #492: true when `lens.defocus` needs the defocus disc (out of focus): the expected signal then carries the disc, or each\n   * node's diffraction kernel convolved with it, as site kernels (#492 step 2b), which the engine's renderer gathers in its\n   * Quality site pass (step 2c). Absent or false otherwise.\n   */\n  defocus?: boolean;\n  /** The scene's form: an engine chart, a declared `material-layers` scene (#491), or a caller function. */\n  scene: \"chart\" | \"material-layers\" | \"material-function\" | \"reflectance-function\" | \"radiance-function\";\n}\n/** One render of a region: the CPU renderer's own setup (tables, readout, demosaic, region, callbacks) and the render's signal. */\nexport interface DisplayViewGpuPart { setup: DisplayViewSetup; signal: AbortSignal | undefined }\n/** What a GPU render returns: the CPU renderer's result shape plus the a-priori bound of its values against the reference. */\nexport interface DisplayViewGpuRenderOutput extends DisplayViewRenderResult {\n  errorBound: NonNullable<ImageKernelExecution[\"errorBound\"]>;\n  /** Samples whose float32 classification fell inside its bound (0 when none). */\n  diagnosticUncertaintySampleCount?: number;\n  /** The composite chart kernel's device probe record, when the render used the composite material module. */\n  compositeProbe?: ChartCompositeProbeRecord;\n}\n/** A conformance case: returns `true` when the device agrees with the reference within the case's bound, or a sentence saying how it did not. */\nexport interface DisplayViewGpuConformanceCase { id: string; run(runtime: DisplayViewGpuRuntimeHandle, signal: AbortSignal | undefined): Promise<true | string> }\n/**\n * Internal (#481): the contract a GPU display-view renderer fulfils (#478). One instance serves one device, created by the\n * registered factory for each prepared view that acquires or shares a device. `supports` says whether the renderer covers a\n * prepared request (`true`) or why not (a sentence; the view then runs the CPU reference labelled `unsupported-on-backend`).\n * `render` renders one region on the device and must throw `ImageKernelExecutionError` with reason `device-lost` or `aborted`\n * for those two events, as the accelerator's operations do; a render that throws `unsupported-on-backend` (a request the\n * renderer finds it does not cover only when rendering) runs the CPU reference labelled with that reason, or fails with it under\n * `\"require\"`. `conformanceCases` are run after the built-in image-kernel cases before the device's first render; a failure keeps\n * the whole view on the CPU. `dispose` releases what the renderer holds on the device (#491: uploaded scene records); the session\n * calls it when the prepared view is disposed.\n */\nexport interface DisplayViewGpuRenderer {\n  readonly id: string;\n  supports(request: DisplayViewGpuRequest): true | string;\n  render(part: DisplayViewGpuPart): Promise<DisplayViewGpuRenderOutput>;\n  readonly conformanceCases?: readonly DisplayViewGpuConformanceCase[];\n  dispose?(): void;\n}\nexport type DisplayViewGpuRendererFactory = (runtime: DisplayViewGpuRuntimeHandle) => DisplayViewGpuRenderer;\n\nlet rendererFactory: DisplayViewGpuRendererFactory | null = null;\n/**\n * Internal (#481): registers the renderer that `prepareDisplayView` uses for `gpu: \"auto\" | \"require\"`, and returns the one\n * registered before (null: none). #478's renderer registers itself here; tests register a fake. With none registered no device\n * is requested and every GPU request falls back (or fails) with `unsupported-on-backend`.\n */\nexport function setDisplayViewGpuRendererFactory(factory: DisplayViewGpuRendererFactory | null): DisplayViewGpuRendererFactory | null {\n  if (factory !== null && typeof factory !== \"function\") throw new InvalidConfigurationError(\"setDisplayViewGpuRendererFactory expects a function or null.\");\n  const previous = rendererFactory;\n  rendererFactory = factory;\n  return previous;\n}\n/** Internal: the registered factory. */\nexport function displayViewGpuRendererFactory(): DisplayViewGpuRendererFactory | null { return rendererFactory; }\n"]}

package/dist/facade/display-view.d.ts

@@ -3,7 +3,34 @@ export declare const DISPLAY_VIEW_JITTER_STREAM_ID: 32;
 export declare const DISPLAY_VIEW_NOISE_STREAM_ID: 33;
 export declare const DISPLAY_VIEW_AHD_STREAM_ID: 34;
 export { createDisplayViewExpectedSignal, type DisplayViewExpectedSignal, type DisplayViewExpectedSignalInput, type DisplayViewQueryOffset, type DisplayViewScene } from "./expected-signal.js";
-import type { DisplayViewExpectedSignal } from "./expected-signal.js";
+import type { DisplayViewExpectedSignal, DisplayViewExpectedSignalInput } from "./expected-signal.js";
+import type { ResolvedChartScene } from "./chart-scenes.js";
+import type { ResolvedChartMaterialLayers } from "./chart-material-layers.js";
+/**
+ * #478: what a GPU renderer needs beyond the CPU setup, which reads the scene only through `signal`: the expected signal's
+ * input (query offsets and points, the materials table, the channel responses) and the resolved chart (null for caller
+ * scenes), from which it builds its material lookup. The CPU renderer ignores it.
+ */
+export interface DisplayViewGpuSetup {
+    signalInput: DisplayViewExpectedSignalInput;
+    /** The resolved chart (portable), or null for a caller scene or a declared `material-layers` scene. */
+    chart: ResolvedChartScene | null;
+    /** #491: the declared `material-layers` scene (its `chart` is the chart under the layers), or null. */
+    layers?: ResolvedChartMaterialLayers | null;
+    /**
+     * #491: a fixed-size chart's placement (`chartSize`): chart-local frame units per frame unit (the metres per frame unit over the
+     * chart's half width) and the chart's aspect; outside |cu| ≤ 1, |cv| ≤ aspect the material is the surround, the materials' last entry.
+     */
+    placement?: {
+        chartUnitsPerFrameUnit: number;
+        aspect: number;
+    } | null;
+    /**
+     * #492: the defocus disc's radius in sites when the expected signal's kernels carry it (`lens.defocus` out of focus); absent in
+     * focus. The GPU Quality site pass then sums each site's taps in blocks (src/gpu/display-view-quality-gpu.ts).
+     */
+    defocusRadius?: number;
+}
 /**
  * Internal (exported for tests). Moments of min(Y, top) for Y ~ N(m, v): mean, variance and the slope d E/d m = P(Y < top). Exact for a normal Y:
  * E[min(Y,t)] = m − s·(φ(z) − z·(1 − Φ(z))), z = (t − m)/s.
@@ -81,6 +108,8 @@ export interface DisplayViewSetup {
     ahdCollect?: Set<number>;
     yieldControl(): Promise<void>;
     checkAbort(): void;
+    /** #478: the inputs a GPU renderer builds its scene lookup from (see {@link DisplayViewGpuSetup}); not read by `renderDisplayView`. */
+    gpu?: DisplayViewGpuSetup;
 }
 export interface DisplayViewRenderResult {
     samples: Uint8Array | Uint16Array;
@@ -115,6 +144,11 @@ export interface DisplayViewKernelTap {
  * by homogeneity, which is the only non-linear step. Returns [horizontal, vertical], each [red, green, blue] kernels.
  */
 export declare function ahdCandidateKernels(phaseX: number, phaseY: number): DisplayViewKernelTap[][][];
+/** 1-D overlaps of real output columns with one display column: first column index and the overlaps. */
+export declare function overlaps(start: number, end: number, limit: number): {
+    first: number;
+    w: Float64Array;
+};
 /**
  * Internal (exported for tests). Footprint sums along one axis, for the closed-form B_c (docs/DISPLAY_VIEW.md, "Demosaic correlation"). Native
  * coordinate parity decides the CFA: red columns/rows are even, blue odd. With w(k) the overlap of real column k:
@@ -136,6 +170,12 @@ export interface AxisSums {
 export declare function axisSums(start: number, end: number, limit: number, margin: number): AxisSums;
 /** Internal (exported for tests). B for red, green and blue (Σ β² over the channel's sites, β normalized to unit sum) and Σ (w/A)². */
 export declare function footprintWeights(x: AxisSums, y: AxisSums, area: number, out: Float64Array): void;
+/** Grid of flat-neighbourhood states for the AHD correction: steps per octave of the normalized channel mean, octaves below white (exported for the GPU display view, #479). */
+export declare const AHD_KEY_STEPS = 8, AHD_KEY_OCTAVES = 12;
+/** Lowest grid level, 2^-AHD_KEY_OCTAVES of white (exact). */
+export declare const AHD_KEY_FLOOR: number;
+/** Grid levels per channel (indices 0 to AHD_KEY_OCTAVES·AHD_KEY_STEPS). */
+export declare const AHD_KEY_LEVELS: number;
 /**
  * Internal (exported for tests, #442): the window offset of each slot, slot (dy + reach)·(2·reach + 1) + dx + reach, as
  * two integer tables: dx[slot] = (slot mod side) − reach and dy[slot] = ⌊slot / side⌋ − reach. The render loop reads them
@@ -217,3 +257,10 @@ export declare function computeDisplayViewCorrectionStates(setup: DisplayViewCor
 export declare const EXACT_AREA_MEAN_MAX_PIXELS = 25;
 /** Renders the display view (docs/DISPLAY_VIEW.md). */
 export declare function renderDisplayView(setup: DisplayViewSetup): Promise<DisplayViewRenderResult>;
+/**
+ * The centre c of a normal of variance v whose clip to [0, 1] has mean `target` (bisection; c = target when the noise does
+ * not reach a bound, or when the target lies outside (0, 1)).
+ */
+export declare function clipCentre(target: number, v: number): number;
+/** Variance in linear light of rounding an sRGB-encoded value to steps of `step`: (dEOTF/de)²·step²/12 at the encoded mean. */
+export declare function quantizationVariance(linear: number, step: number): number;

package/dist/facade/display-view.js

@@ -220,7 +220,7 @@ export function ahdCandidateKernels(phaseX, phaseY) {
     });
 }
 /** 1-D overlaps of real output columns with one display column: first column index and the overlaps. */
-function overlaps(start, end, limit) {
+export function overlaps(start, end, limit) {
     const first = Math.floor(start), last = Math.min(limit - 1, Math.ceil(end) - 1), w = new Float64Array(last - first + 1);
     for (let k = first; k <= last; k++)
         w[k - first] = Math.min(end, k + 1) - Math.max(start, k);
@@ -260,8 +260,8 @@ export function footprintWeights(x, y, area, out) {
 }
 /** AHD's dependence reach in sites (directional green ±2, colour differences ±1, homogeneity 4-neighbours and 3 × 3 sum). */
 const AHD_REACH = 5, AHD_SIDE = 2 * AHD_REACH + 1;
-/** Grid of flat-neighbourhood states for the AHD correction: steps per octave of the normalized channel mean, octaves below white. */
-const AHD_KEY_STEPS = 8, AHD_KEY_OCTAVES = 12;
+/** Grid of flat-neighbourhood states for the AHD correction: steps per octave of the normalized channel mean, octaves below white (exported for the GPU display view, #479). */
+export const AHD_KEY_STEPS = 8, AHD_KEY_OCTAVES = 12;
 /** CFA role (0 red, 1 green, 2 blue) of each patch site (dy + 5)·11 + dx + 5, per phase (phaseY·2 + phaseX) of the centre. */
 const AHD_ROLES = [0, 1, 2, 3].map((phase) => {
     const roles = new Uint8Array(AHD_SIDE * AHD_SIDE), px = phase & 1, py = phase >> 1;
@@ -287,9 +287,9 @@ const LAB_EPSILON = 216 / 24389, LAB_KAPPA = 24389 / 27;
 /** A 32-bit hash of a correction key (MurmurHash3 finalizer of the three quantized means). */
 function fmixKey(a, b, c) { return fmix32((Math.imul(a + 1, 0x9e3779b1) ^ Math.imul(b + 1, 0x85ebca77) ^ Math.imul(c + 1, 0xc2b2ae3d)) >>> 0); }
 /** Lowest grid level, 2^-AHD_KEY_OCTAVES of white (exact). */
-const AHD_KEY_FLOOR = 1 / 4096;
+export const AHD_KEY_FLOOR = 1 / 4096;
 /** Grid levels per channel (indices 0 to AHD_KEY_OCTAVES·AHD_KEY_STEPS). */
-const AHD_KEY_LEVELS = AHD_KEY_OCTAVES * AHD_KEY_STEPS + 1;
+export const AHD_KEY_LEVELS = AHD_KEY_OCTAVES * AHD_KEY_STEPS + 1;
 /** Correction states kept per setup, and setups kept (least recently used first out); about 50 bytes per state. */
 const AHD_STATE_LIMIT = 1 << 16, AHD_SETUP_LIMIT = 4;
 const ahdStateCache = new Map();
@@ -1364,7 +1364,7 @@ export async function renderDisplayView(setup) {
  * The centre c of a normal of variance v whose clip to [0, 1] has mean `target` (bisection; c = target when the noise does
  * not reach a bound, or when the target lies outside (0, 1)).
  */
-function clipCentre(target, v) {
+export function clipCentre(target, v) {
     if (!(v > 0) || !(target > 0 && target < 1))
         return target;
     const s = Math.sqrt(v);
@@ -1383,7 +1383,7 @@ function clipCentre(target, v) {
     return (lo + hi) / 2;
 }
 /** Variance in linear light of rounding an sRGB-encoded value to steps of `step`: (dEOTF/de)²·step²/12 at the encoded mean. */
-function quantizationVariance(linear, step) {
+export function quantizationVariance(linear, step) {
     const e = encodeSrgbComponentPortable(linear < 0 ? 0 : linear > 1 ? 1 : linear), slope = e <= 0.04045 ? 1 / 12.92 : 2.4 / 1.055 * portablePow((e + 0.055) / 1.055, 1.4);
     return slope * slope * step * step / 12;
 }