@photivra/engine 2.16.0 → 2.18.0

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

@@ -1 +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 = /* @__PURE__ */ 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"]}
+{"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 = /* @__PURE__ */ 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  /**\n   * #564: true when the defocus kernel's radius is above 64 sites, so the expected signal convolves it by runs on the CPU\n   * (`largeKernel`); no GPU renderer takes it. Absent or false otherwise.\n   */\n  largeDefocus?: boolean;\n  /**\n   * #563: true when the request has `lens.projection`, `lens.distortion`, `lens.vignetting` or camera rotation: the CPU reference\n   * renders it (display-view-lens-signal.ts) and no GPU renderer is asked or device requested (`unsupported-on-backend`).\n   */\n  lens?: 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-lens-signal.d.ts

@@ -0,0 +1,61 @@
+import type { PreparedDefocusImageSpaceGeometry } from "./defocus-image-space-provider.js";
+import { type ResolveLensSampledPsfInput } from "../optics/lens-psf-profile.js";
+import { type DisplayViewExpectedSignal, type DisplayViewExpectedSignalInput, type GroupTables } from "./expected-signal.js";
+/** #569: field zones along the native raster's longer side. */
+export declare const DISPLAY_VIEW_LENS_PSF_ZONES = 64;
+/** #569: a field-dependent PSF for the display view (see the module comment). */
+export interface DisplayViewLensPsf {
+    /** Kernel radius and zone side, in sites. */
+    readonly radius: number;
+    readonly zoneSites: number;
+    /** The kernels at the frame centre's zone, for the expected-signal input's lattice groups and reach. */
+    axisKernels(wavelengthsNm: readonly number[]): {
+        radius: number;
+        perNode: Float64Array[];
+    };
+    /** The combined kernels of the zone of native site (x, y), for an input whose kernels are the axis kernels. */
+    tables(input: DisplayViewExpectedSignalInput): (x: number, y: number) => readonly GroupTables[];
+}
+/**
+ * #569: the field-dependent PSF of a display view from the sampled PSF the capture resolves (everything but the field point and wavelength),
+ * of kernel radius R, on the W × H native raster of `pitch` µm.
+ */
+export declare function createDisplayViewLensPsf(psf: Omit<ResolveLensSampledPsfInput, "fieldPointMm" | "wavelengthNm">, R: number, W: number, H: number, pitch: number): DisplayViewLensPsf;
+/** What the lens signal needs from the resolved request. */
+export interface DisplayViewLensSetup {
+    geometry: PreparedDefocusImageSpaceGeometry;
+    /** Temporal midpoints, seconds from exposure start: (i + 0.5)·shutter/T with camera rotation, [0] without. */
+    times: readonly number[];
+    /** The planar provider's plane distance and frame-unit scale. */
+    distanceM: number;
+    metresPerFrameUnit: number;
+    pitch: number;
+    imagingArea: {
+        widthMm: number;
+        heightMm: number;
+    };
+    boxSamples: number;
+    /** Anti-aliasing split spots (or one zero spot), in the order of the expected signal's offsets within each aperture node. */
+    spots: readonly {
+        offsetMicrometers: {
+            x: number;
+            y: number;
+        };
+    }[];
+    /**
+     * #569: a field-dependent lens PSF (`lens.catalogue`, {@link createDisplayViewLensPsf}): each site reads its field zone's kernels
+     * instead of the input's. The input's kernels (the axis zone's) set the lattice groups and the reach; absent, every site reads them.
+     */
+    psf?: DisplayViewLensPsf | undefined;
+    /**
+     * #569 (catalogue fisheyes): a ray that does not point toward the scene plane sees no scene (zero radiance), as the capture's provider
+     * with `zeroBeyondHorizon` gives it, instead of failing.
+     */
+    zeroBeyondHorizon?: boolean | undefined;
+}
+/**
+ * Checks that the mapping and the vignetting profile cover the farthest source point the view reads, (W/2 + reachSites, H/2 + reachSites)
+ * sites from the axis at each corner (reachSites: the kernel radius plus the largest query offset, less the half site to the outer site
+ * centre), and returns the factory of the view's expected signal for this request.
+ */
+export declare function prepareDisplayViewLensSignal(lens: DisplayViewLensSetup, nativeWidth: number, nativeHeight: number, reachSites: number, options: string): (input: DisplayViewExpectedSignalInput, spanColumns?: number) => DisplayViewExpectedSignal;

package/dist/facade/display-view-lens-signal.js

@@ -0,0 +1,502 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * The display view's expected signal with a lens field mapping (`lens.projection`, `lens.distortion`), `lens.vignetting` or
+ * camera rotation (#563), in focus and with `lens.defocus` out of focus. Loaded on demand (a dynamic import in `runCapture`),
+ * so a display view without these options, and a bundle that never asks for them, does not load it.
+ *
+ * What it computes. The capture's environment chain forms, for site (i, j) of CFA channel c,
+ *   μ_c(i, j) = Σ_o w_o · (1/T) Σ_t Σ_λ A_c(λ) Σ_k K_λ(k) · F(s) · L(D_t(s), λ),   s = q_o(i, j) − k·p,
+ * with q_o the query point of offset o (pixel-aperture node minus anti-aliasing split), K_λ the site kernel (diffraction, the
+ * defocus disc or both; a single unit tap without them), D_t the scene ray of sensor point s at temporal midpoint t (inverse
+ * distortion, the declared projection, the camera rotation at t), F = T·A its field factor (vignetting throughput × distortion
+ * area factor) and A_c(λ) the electrons per unit spectral radiance on the axis (the display view's channel response, ideal
+ * optics). In focus with a kernel this is the environment PSF quadrature (the field factor applied once at the source point,
+ * before the PSF spreads the light); out of focus it is #548's image-space disc, the same sum in another order
+ * (`defocus-image-space-provider.ts`); without a kernel it is the environment's own per-query sum. Only the scene access changes:
+ * the readout, the estimators, the demosaic and the development run unchanged on these site values.
+ *
+ * Scene points. Without a kernel each query point is formed with the environment's own arithmetic (the site centre, aperture node
+ * and split offset of `native-environment-lean.ts`), then `lookOf` (the environment's mapping, rotation and field factor,
+ * #548) and the planar provider's plane-point arithmetic, so a point exactly on a chart boundary resolves as in the capture.
+ * With a kernel the sources are the site lattice of each fractional offset, with #548's lattice formula. Kernels, materials and
+ * per-material sums are the display view's own tables (`displayViewSignalTables`), shared with the rectilinear path.
+ *
+ * Caches (memory only, never values): site values in a ring of native rows across windows, and with a kernel each lattice
+ * point's material (or radiance at each node) and field factor per lattice group and temporal midpoint, in a two-dimensional
+ * ring tagged with the point, sized from the window and capped at LATTICE_CACHE_LIMIT entries (beyond it, points are
+ * evaluated as they are read).
+ *
+ * Field-dependent PSF (#569, `lens.catalogue`; {@link createDisplayViewLensPsf}). The capture's environment PSF quadrature resolves the
+ * catalogue lens's sampled PSF at each query point's own field position. The view cuts the native raster into square zones of
+ * Z = ⌈max(W, H) / DISPLAY_VIEW_LENS_PSF_ZONES⌉ sites (one site on frames of at most that many sites a side) and every site of a zone
+ * takes the PSF the capture's own resolver gives at the zone's centre, at each spectral node (an approximation: the PSF's change
+ * across half a zone). A profile kernel's rows run with image +Y (up) and its tap (i, j) reads (x − (i − c)·p, y + (j − c)·p) in
+ * native coordinates (`sensorPsfSourcePoint`), so the view's kernel (reading in(x − t)) is the profile kernel flipped vertically.
+ * Each zone's combined kernels are the expected signal's own tables (`buildTables`) with the zone's kernels, built when a site of
+ * the zone is first read and kept per input in a least-recently-used cache of at most 64 MB (at least four zones).
+ *
+ * Large defocus kernels (#564, `input.largeKernel`, radius above 64 sites). The image-space disc D is the same at every lattice
+ * group, spectral node and temporal midpoint, so it commutes with those sums as in the rectilinear signal (`expected-signal.ts`):
+ * μ_c(x) = Σ_s D(s)·E_c(x − s), with E_c(x) the sum above through the in-focus kernels (each node's diffraction kernel, or a unit
+ * tap) at site position x for channel c, whatever x's own channel. E is computed in fixed 64-site tiles (all three channels, each
+ * group's lattice points mapped once per tile and midpoint), and D ⊛ E_c by runs (`site-kernel-runs.ts`) in fixed 128-site tiles,
+ * each site taking its own channel: every value depends only on its site, so regions and parts equal the whole view.
+ */
+import { InvalidConfigurationError } from "../core/configuration-error.js";
+import { createSiteKernelRunsLattice } from "../optics/site-kernel-runs.js";
+import { resolveLensSampledPsfKernel } from "../optics/lens-psf-profile.js";
+import { buildTables, displayViewSignalTables } from "./expected-signal.js";
+/** #569: field zones along the native raster's longer side. */
+export const DISPLAY_VIEW_LENS_PSF_ZONES = 64;
+/**
+ * #569: the field-dependent PSF of a display view from the sampled PSF the capture resolves (everything but the field point and wavelength),
+ * of kernel radius R, on the W × H native raster of `pitch` µm.
+ */
+export function createDisplayViewLensPsf(psf, R, W, H, pitch) {
+    const Z = Math.ceil(Math.max(W, H) / DISPLAY_VIEW_LENS_PSF_ZONES), zonesX = Math.ceil(W / Z), w = 2 * R + 1;
+    const zoneOf = (x, y) => Math.floor(y / Z) * zonesX + Math.floor(x / Z);
+    const kernelsOf = (zone, wavelengthsNm) => {
+        // The zone's centre in sites from the top-left corner (an edge zone may be narrower), in image millimetres (+Y up).
+        const zx = zone % zonesX, zy = (zone - zx) / zonesX, fieldPointMm = { x: ((zx * Z + Math.min(W, zx * Z + Z)) / 2 - W / 2) * pitch / 1000,
+            y: (H / 2 - (zy * Z + Math.min(H, zy * Z + Z)) / 2) * pitch / 1000 };
+        return wavelengthsNm.map((wavelengthNm) => {
+            // Every node of the engine-built profile has the same (2R + 1)² window, so every resolved kernel has it too.
+            const values = resolveLensSampledPsfKernel({ ...psf, fieldPointMm, wavelengthNm }).normalizedIntensity, out = new Float64Array(w * w);
+            for (let j = 0; j < w; j++)
+                for (let i = 0; i < w; i++)
+                    out[(w - 1 - j) * w + i] = values[j * w + i];
+            return out;
+        });
+    };
+    const caches = new WeakMap();
+    return { radius: R, zoneSites: Z,
+        axisKernels: (wavelengthsNm) => ({ radius: R, perNode: kernelsOf(zoneOf(W >> 1, H >> 1), wavelengthsNm) }),
+        tables(input) {
+            let read = caches.get(input);
+            if (read)
+                return read;
+            const cache = new Map();
+            let kept = 0, last = -1, lastTables = [];
+            read = (x, y) => {
+                const zone = zoneOf(x, y);
+                if (zone === last)
+                    return lastTables;
+                let tables = cache.get(zone);
+                if (tables)
+                    cache.delete(zone);
+                else {
+                    tables = buildTables({ ...input, kernels: { radius: R, perNode: kernelsOf(zone, input.wavelengthsNm) } }).groups;
+                    // Zones kept: at least 4, and at most 64 MB of them (every zone's tables have the same size).
+                    kept ||= Math.max(4, (1 << 23) / tables.reduce((n, g) => n + g.cw * g.ch * (g.neutral.length + g.spectral.flat().length + g.perNode.flat().length), 0));
+                    if (cache.size >= kept)
+                        cache.delete(cache.keys().next().value);
+                }
+                cache.set(zone, tables);
+                last = zone;
+                lastTables = tables;
+                return tables;
+            };
+            caches.set(input, read);
+            return read;
+        } };
+}
+/** Largest lattice cache, in entries over all lattice groups and temporal midpoints (times the spectral nodes for radiance scenes). */
+const LATTICE_CACHE_LIMIT = 1 << 22;
+const pow2 = (n) => { let p = 1; while (p < n)
+    p *= 2; return p; };
+/**
+ * Checks that the mapping and the vignetting profile cover the farthest source point the view reads, (W/2 + reachSites, H/2 + reachSites)
+ * sites from the axis at each corner (reachSites: the kernel radius plus the largest query offset, less the half site to the outer site
+ * centre), and returns the factory of the view's expected signal for this request.
+ */
+export function prepareDisplayViewLensSignal(lens, nativeWidth, nativeHeight, reachSites, options) {
+    const xMm = (nativeWidth / 2 + reachSites) * lens.pitch / 1000, yMm = (nativeHeight / 2 + reachSites) * lens.pitch / 1000;
+    for (const t of lens.times)
+        for (const [x, y] of [[-xMm, -yMm], [xMm, -yMm], [-xMm, yMm], [xMm, yMm]]) {
+            try {
+                if (!(lens.geometry.lookOf(x, y, t).z > 0) && !lens.zeroBeyondHorizon)
+                    throw new InvalidConfigurationError("its ray does not point toward the scene plane.");
+            }
+            catch (error) {
+                throw new InvalidConfigurationError("simulateDisplayView with " + options + " reads the scene through the lens up to " + (reachSites + 0.5) + " sites beyond the native " +
+                    "raster's outer site centres (the kernel radius and the query offsets), and there (" + Math.hypot(x, y).toFixed(3) + " mm from the axis) " + error.message);
+            }
+        }
+    return (input, spanColumns = Infinity) => createLensSignal(lens, input, spanColumns);
+}
+function createLensSignal(lens, input, spanColumns) {
+    const W = input.nativeWidth, H = input.nativeHeight, nodes = input.wavelengthsNm.length, T = lens.times.length, times = lens.times;
+    const { geometry, distanceM: distance, metresPerFrameUnit: scale, pitch, imagingArea } = lens;
+    const mmPerSite = pitch / 1000, scene = input.scene, offsets = input.offsets, A = input.electronsPerRadiance, channelAt = input.channelAt;
+    const materials = scene.kind === "materials" ? scene : undefined, radianceAt = scene.kind === "radiance" ? scene.radianceAt : undefined;
+    const { reflectance, spectralIndex, neutralDirect, spectralDirect, groups } = displayViewSignalTables(input);
+    const kernels = input.kernels, R = kernels ? kernels.radius : 0;
+    /** #569: the combined kernels of the zone of site (x, y), or the input's own without a field-dependent PSF. */
+    const zoneTables = lens.psf ? lens.psf.tables(input) : () => groups;
+    let lookups = 0;
+    // The plane point (frame units) and field factor of native sensor point (x, y) mm at time t: the environment's mapping (lookOf) and
+    // the planar provider's own arithmetic for the outgoing direction −look.
+    // #569: with zeroBeyondHorizon, a ray at or beyond 90° reads the plane's origin with a zero factor (zero radiance; `beyond` is set).
+    let pu = 0, pv = 0, pf = 0, beyond = false;
+    const zeroBeyond = lens.zeroBeyondHorizon === true;
+    const map = (xMm, yMm, t) => {
+        const look = geometry.lookOf(xMm, yMm, t);
+        beyond = !(look.z > 0);
+        if (beyond) {
+            if (!zeroBeyond || !Number.isFinite(look.z))
+                throw new InvalidConfigurationError("simulateDisplayView: a query ray does not point toward the scene plane.");
+            pu = 0;
+            pv = 0;
+            pf = 0;
+            return;
+        }
+        const s = distance / look.z;
+        pu = look.x * s / scale;
+        pv = look.y * s / scale;
+        pf = look.factor;
+    };
+    const materialOf = (m) => { if (spectralIndex[m] === undefined)
+        throw new InvalidConfigurationError("Unknown chart material."); return m; };
+    // Without a kernel: the environment's query point of offset o of site (x, y) (native-environment-lean.ts, as buildExpectedSignalInput's queryPoint).
+    const box = lens.boxSamples, siteWidthMm = pitch / 1000;
+    const phases = offsets.map((_, o) => {
+        const node = Math.floor(o / lens.spots.length), spot = lens.spots[o % lens.spots.length].offsetMicrometers;
+        return { xPhase: (node % box + 0.5) / box, yPhase: (Math.floor(node / box) + 0.5) / box, aaX: spot.x / 1000, aaY: spot.y / 1000 };
+    });
+    function directSite(x, y) {
+        const c = channelAt(x, y), centerX = -imagingArea.widthMm / 2 + (pitch / 2 + x * pitch + 0) / 1000, centerY = -imagingArea.heightMm / 2 + (pitch / 2 + y * pitch + 0) / 1000;
+        let total = 0;
+        for (let ti = 0; ti < T; ti++) {
+            let sum = 0;
+            for (let o = 0; o < offsets.length; o++) {
+                const node = phases[o];
+                map((centerX - siteWidthMm / 2 + node.xPhase * siteWidthMm) - node.aaX, (centerY - siteWidthMm / 2 + node.yPhase * siteWidthMm) - node.aaY, times[ti]);
+                let value;
+                if (materials) {
+                    const m = materialOf(materials.materialAt(pu, pv)), si = spectralIndex[m];
+                    value = si < 0 ? reflectance[m] * neutralDirect[c] : spectralDirect[c][si];
+                    lookups++;
+                }
+                else {
+                    value = 0;
+                    for (let n = 0; n < nodes; n++)
+                        value += A[c][n] * radianceAt(pu, pv, input.wavelengthsNm[n]);
+                    lookups += nodes;
+                }
+                sum += offsets[o].weight * (pf * value);
+            }
+            total += sum;
+        }
+        return total / T;
+    }
+    // With a kernel: lattice point (p, q) of group g at time t, #548's lattice formula, cached in a ring tagged with (p, q).
+    const G = groups.length, slots = G * T, per = materials ? 1 : nodes;
+    let cacheRows = 0, cacheCols = 0, tagQ = new Int32Array(0), tagP = new Int32Array(0), cacheMaterial = new Int32Array(0), cacheFactor = new Float64Array(0), cacheRadiance = new Float64Array(0);
+    const radiance = new Float64Array(nodes);
+    let lm = 0, lf = 0;
+    function lattice(g, ti, p, q) {
+        let k = -1;
+        if (cacheRows > 0) {
+            k = ((g * T + ti) * cacheRows + (q & (cacheRows - 1))) * cacheCols + (p & (cacheCols - 1));
+            if (tagQ[k] === q && tagP[k] === p) {
+                lf = cacheFactor[k];
+                if (materials)
+                    lm = cacheMaterial[k];
+                else
+                    for (let n = 0; n < nodes; n++)
+                        radiance[n] = cacheRadiance[k * nodes + n];
+                return;
+            }
+        }
+        const group = groups[g];
+        map((p + 0.5 + group.fx - W / 2) * mmPerSite, (q + 0.5 + group.fy - H / 2) * mmPerSite, times[ti]);
+        lf = pf;
+        if (materials) {
+            lm = materialOf(materials.materialAt(pu, pv));
+            lookups++;
+        }
+        else {
+            for (let n = 0; n < nodes; n++)
+                radiance[n] = radianceAt(pu, pv, input.wavelengthsNm[n]);
+            lookups += nodes;
+        }
+        if (k >= 0) {
+            tagQ[k] = q;
+            tagP[k] = p;
+            cacheFactor[k] = lf;
+            if (materials)
+                cacheMaterial[k] = lm;
+            else
+                for (let n = 0; n < nodes; n++)
+                    cacheRadiance[k * nodes + n] = radiance[n];
+        }
+    }
+    function kernelSite(x, y) {
+        const c = channelAt(x, y), rowMask = cacheRows - 1, colMask = cacheCols - 1, zone = zoneTables(x, y);
+        let total = 0;
+        for (let ti = 0; ti < T; ti++) {
+            let sum = 0;
+            for (let g = 0; g < G; g++) {
+                const group = groups[g], p0 = x + group.minIx - R, q0 = y + group.minIy - R, cw = group.cw, ch = group.ch, weights = zone[g];
+                if (materials) {
+                    const nk = weights.neutral[c], sk = weights.spectral[c];
+                    for (let dy = 0, t = 0; dy < ch; dy++) {
+                        // The cache row of lattice row q (read inline: the common case is a hit).
+                        const q = q0 + dy, row = cacheRows > 0 ? ((g * T + ti) * cacheRows + (q & rowMask)) * cacheCols : -1;
+                        for (let dx = 0; dx < cw; dx++, t++) {
+                            const p = p0 + dx, k = row + (p & colMask);
+                            if (row >= 0 && tagQ[k] === q && tagP[k] === p) {
+                                lm = cacheMaterial[k];
+                                lf = cacheFactor[k];
+                            }
+                            else
+                                lattice(g, ti, p, q);
+                            const si = spectralIndex[lm];
+                            sum += lf * (si < 0 ? reflectance[lm] * nk[t] : sk[si][t]);
+                        }
+                    }
+                }
+                else
+                    for (let dy = 0, t = 0; dy < ch; dy++)
+                        for (let dx = 0; dx < cw; dx++, t++) {
+                            lattice(g, ti, p0 + dx, q0 + dy);
+                            let value = 0;
+                            for (let n = 0; n < nodes; n++)
+                                value += weights.perNode[n][c][t] * radiance[n];
+                            sum += lf * value;
+                        }
+            }
+            total += sum;
+        }
+        return total / T;
+    }
+    const pilotNode = input.wavelengthsNm[Math.floor(nodes / 2)];
+    if (input.largeKernel)
+        return createLargeLensSignal(input, inFocusLensTile, () => lookups, pilot);
+    /** E_c (#564) of the native site positions [x0, x0 + T) × [y0, y0 + T) for the three channels: kernelSite's sum for each channel. */
+    function inFocusLensTile(x0, y0, TS) {
+        const out = [0, 1, 2].map(() => new Float64Array(TS * TS));
+        // A fixed tile reaches past the raster: positions more than the disc's radius beyond it feed no site, so they stay 0 and are never
+        // mapped (the lens profiles are checked only up to the view's reach).
+        const D = input.largeKernel.radius;
+        if (x0 + TS <= -D || x0 >= W + D || y0 + TS <= -D || y0 >= H + D)
+            return out;
+        if (x0 < -D || x0 + TS > W + D || y0 < -D || y0 + TS > H + D) {
+            const xa = Math.max(x0, -D), xb = Math.min(x0 + TS, W + D), ya = Math.max(y0, -D), yb = Math.min(y0 + TS, H + D);
+            const part = inFocusLensRect(xa, ya, xb - xa, yb - ya);
+            for (let c = 0; c < 3; c++)
+                for (let y = ya; y < yb; y++)
+                    out[c].set(part[c].subarray((y - ya) * (xb - xa), (y - ya + 1) * (xb - xa)), (y - y0) * TS + xa - x0);
+            return out;
+        }
+        return inFocusLensRect(x0, y0, TS, TS);
+    }
+    /** E_c of the native site positions [x0, x0 + w) × [y0, y0 + h), row-major, for the three channels. */
+    function inFocusLensRect(x0, y0, TW, TH) {
+        const out = [0, 1, 2].map(() => new Float64Array(TW * TH)), sum = [0, 1, 2].map(() => new Float64Array(TW * TH));
+        for (let ti = 0; ti < T; ti++) {
+            for (const e of sum)
+                e.fill(0);
+            for (const group of groups) {
+                const cw = group.cw, ch = group.ch, gw = TW + cw - 1, gh = TH + ch - 1, p0 = x0 + group.minIx - R, q0 = y0 + group.minIy - R;
+                const factor = new Float64Array(gw * gh), material = materials ? new Int32Array(gw * gh) : undefined, values = materials ? undefined : new Float64Array(gw * gh * nodes);
+                for (let j = 0; j < gh; j++)
+                    for (let i = 0; i < gw; i++) {
+                        const k = j * gw + i;
+                        map((p0 + i + 0.5 + group.fx - W / 2) * mmPerSite, (q0 + j + 0.5 + group.fy - H / 2) * mmPerSite, times[ti]);
+                        factor[k] = pf;
+                        if (material)
+                            material[k] = materialOf(materials.materialAt(pu, pv));
+                        else
+                            for (let n = 0; n < nodes; n++)
+                                values[k * nodes + n] = radianceAt(pu, pv, input.wavelengthsNm[n]);
+                    }
+                lookups += material ? gw * gh : gw * gh * nodes;
+                for (let c = 0; c < 3; c++) {
+                    const e = sum[c], nk = group.neutral[c], sk = group.spectral[c];
+                    for (let y = 0; y < TH; y++)
+                        for (let x = 0; x < TW; x++) {
+                            let v = 0;
+                            for (let dy = 0, t = 0; dy < ch; dy++)
+                                for (let dx = 0; dx < cw; dx++, t++) {
+                                    const k = (y + dy) * gw + x + dx;
+                                    if (material) {
+                                        const m = material[k], si = spectralIndex[m];
+                                        v += factor[k] * (si < 0 ? reflectance[m] * nk[t] : sk[si][t]);
+                                    }
+                                    else {
+                                        let r = 0;
+                                        for (let n = 0; n < nodes; n++)
+                                            r += group.perNode[n][c][t] * values[k * nodes + n];
+                                        v += factor[k] * r;
+                                    }
+                                }
+                            e[y * TW + x] = e[y * TW + x] + v;
+                        }
+                }
+            }
+            for (let c = 0; c < 3; c++) {
+                const o = out[c], e = sum[c];
+                for (let k = 0; k < o.length; k++)
+                    o[k] = o[k] + e[k];
+            }
+        }
+        for (const o of out)
+            for (let k = 0; k < o.length; k++)
+                o[k] = o[k] / T;
+        return out;
+    }
+    // Site values persist across windows in a ring of native rows (a site's value does not depend on the window).
+    let ringRows = 0, ring = new Float64Array(0), ringRowId = new Int32Array(0), ringOn = false;
+    const compute = kernels ? kernelSite : directSite;
+    return {
+        get lookups() { return lookups; },
+        uniformMaterial: -1,
+        tracksMaterial: false,
+        get cachesSites() { return ringOn; },
+        marksReads: false,
+        markReads() { },
+        window(x0, y0, x1, y1) {
+            const sw = Math.max(0, x1 - x0), sh = Math.max(0, y1 - y0);
+            if (sh > 0 && ringRows < 2 * sh) {
+                const rows = pow2(2 * sh);
+                if (rows * W <= LATTICE_CACHE_LIMIT) {
+                    ringRows = rows;
+                    ring = new Float64Array(rows * W).fill(NaN);
+                    ringRowId = new Int32Array(rows).fill(-1);
+                }
+            }
+            ringOn = sh > 0 && ringRows >= 2 * sh;
+            if (!kernels || sw === 0)
+                return;
+            // The lattice rectangle the window's sites read, per group; the cache keeps two such heights and the columns the render's windows span.
+            let cw = 0, ch = 0;
+            for (const group of groups) {
+                cw = Math.max(cw, group.cw);
+                ch = Math.max(ch, group.ch);
+            }
+            const height = sh + ch - 1, width = sw + cw - 1;
+            let rows = pow2(2 * height), cols = pow2(Math.min(W + 2 * (R + cw), Math.max(width, (Number.isFinite(spanColumns) ? spanColumns : W) + width)));
+            if (slots * per * rows * cols > LATTICE_CACHE_LIMIT)
+                rows = pow2(height);
+            if (slots * per * rows * cols > LATTICE_CACHE_LIMIT)
+                cols = pow2(width);
+            if (slots * per * rows * cols > LATTICE_CACHE_LIMIT) {
+                cacheRows = 0;
+                return;
+            }
+            if (rows > cacheRows || cols > cacheCols) {
+                rows = Math.max(rows, cacheRows);
+                cols = Math.max(cols, cacheCols);
+                if (slots * per * rows * cols > LATTICE_CACHE_LIMIT) {
+                    rows = pow2(height);
+                    cols = pow2(width);
+                }
+                cacheRows = rows;
+                cacheCols = cols;
+                const size = slots * rows * cols;
+                tagQ = new Int32Array(size).fill(-2147483648);
+                tagP = new Int32Array(size);
+                cacheFactor = new Float64Array(size);
+                if (materials)
+                    cacheMaterial = new Int32Array(size);
+                else
+                    cacheRadiance = new Float64Array(size * nodes);
+            }
+        },
+        site(x, y) {
+            if (!ringOn)
+                return compute(x, y);
+            const slot = y & (ringRows - 1), k = slot * W + x;
+            if (ringRowId[slot] === y) {
+                const v = ring[k];
+                if (v === v)
+                    return v;
+            }
+            else {
+                ringRowId[slot] = y;
+                ring.fill(NaN, slot * W, (slot + 1) * W);
+            }
+            const v = compute(x, y);
+            ring[k] = v;
+            return v;
+        },
+        pilot
+    };
+    /**
+     * The renderer's pilot point is a rectilinear plane point of the native raster: back to the sensor point, then through the lens at
+     * every temporal midpoint. A point whose scene value differs between the instants (motion) counts as detail (NaN equals nothing).
+     */
+    function pilot(u, v) {
+        const g = 2 / input.outputWidth, xMm = u / g * mmPerSite, yMm = -v / g * mmPerSite;
+        let first = NaN;
+        try {
+            for (let ti = 0; ti < T; ti++) {
+                map(xMm, yMm, times[ti]);
+                const value = beyond ? -1 : materials ? materials.materialAt(pu, pv) : radianceAt(pu, pv, pilotNode);
+                lookups++;
+                if (ti === 0)
+                    first = value;
+                else if (value !== first)
+                    return NaN;
+            }
+        }
+        catch {
+            return NaN;
+        }
+        return first;
+    }
+}
+/** #564: tile sides of the large-kernel lens signal (the in-focus E and the convolved sites) and the bytes each tile cache keeps. */
+const LARGE_E_TILE = 64, LARGE_OUTPUT_TILE = 128, LARGE_CACHE_BYTES = 32 * 1048576;
+/** #564: the lens signal with a defocus kernel above 64 sites: D ⊛ E_c by runs over the in-focus tiles (see the module comment). */
+function createLargeLensSignal(input, inFocusTile, lookups, pilot) {
+    const runs = input.largeKernel, channelAt = input.channelAt, TE = LARGE_E_TILE;
+    // At least the in-focus tiles one output tile's source spans plus one more row of them, so the next output tile of a row reuses them.
+    const span = Math.ceil((LARGE_OUTPUT_TILE + 2 * runs.radius) / TE) + 1;
+    const inFocus = new Map(), capacity = Math.max(span * (span + 1), Math.floor(LARGE_CACHE_BYTES / (3 * TE * TE * 8)));
+    const tileAt = (tx, ty) => {
+        const key = (ty + 1048576) * 2097152 + tx + 1048576;
+        let tile = inFocus.get(key);
+        if (tile) {
+            inFocus.delete(key);
+            inFocus.set(key, tile);
+        }
+        else {
+            tile = inFocusTile(tx * TE, ty * TE, TE);
+            inFocus.set(key, tile);
+            if (inFocus.size > capacity)
+                inFocus.delete(inFocus.keys().next().value);
+        }
+        return tile;
+    };
+    // Which sites of a tile row hold channel c: the CFA's 2 × 2 period (tile origins are even).
+    const phase = [0, 1].map((py) => [0, 1].map((px) => channelAt(px, py)));
+    const patterns = [0, 1, 2].map((c) => (row) => {
+        const p = phase[row & 1], even = p[0] === c, odd = p[1] === c;
+        return even && odd ? { start: 0, step: 1 } : even ? { start: 0, step: 2 } : odd ? { start: 1, step: 2 } : null;
+    });
+    const lattice = createSiteKernelRunsLattice({ runs, tile: LARGE_OUTPUT_TILE, fields: 3, capacityBytes: LARGE_CACHE_BYTES, pattern: (c) => patterns[c],
+        source: (x0, y0, width, height) => (c) => {
+            const samples = new Float64Array(width * height);
+            for (let ty = Math.floor(y0 / TE); ty * TE < y0 + height; ty++)
+                for (let tx = Math.floor(x0 / TE); tx * TE < x0 + width; tx++) {
+                    const tile = tileAt(tx, ty)[c], ax = Math.max(x0, tx * TE), bx = Math.min(x0 + width, (tx + 1) * TE), ay = Math.max(y0, ty * TE), by = Math.min(y0 + height, (ty + 1) * TE);
+                    for (let y = ay; y < by; y++)
+                        samples.set(tile.subarray((y - ty * TE) * TE + ax - tx * TE, (y - ty * TE) * TE + bx - tx * TE), (y - y0) * width + ax - x0);
+                }
+            return samples;
+        } });
+    return {
+        get lookups() { return lookups(); },
+        uniformMaterial: -1,
+        tracksMaterial: false,
+        cachesSites: false,
+        marksReads: false,
+        markReads() { },
+        window() { },
+        site(x, y) { return lattice.valueAt(channelAt(x, y), x, y); },
+        pilot
+    };
+}
+//# sourceMappingURL=display-view-lens-signal.js.map