@photivra/engine 2.10.0 → 2.11.1

package/dist/gpu/chart-composite-gpu.d.ts

@@ -0,0 +1,119 @@
+import type { ChartRadianceBatchPlan } from "../facade/chart-radiance-batch.js";
+import { type ChartGeometry, type ResolvedChartScene } from "../facade/chart-scenes.js";
+import { ImageKernelExecutionError, type ChartCompositeProbeComponent, type ChartCompositeProbeRecord } from "./image-kernel-execution.js";
+import type { ChartRadianceResult } from "./image-kernel-accelerator.js";
+import { GpuResourceScope, type WebGpuRuntime } from "./webgpu-runtime.js";
+type PipelineSource = (label: string, code: string) => Promise<GPUComputePipeline>;
+type YieldControl = ((signal: AbortSignal) => Promise<void>) | undefined;
+export type Dw = readonly [hi: number, lo: number];
+export declare function dwSplit(x: number): Dw;
+export declare function twoSum(a: number, b: number): Dw;
+export declare function quickTwoSum(a: number, b: number): Dw;
+export declare function twoProd(a: number, b: number): Dw;
+export declare function dwAdd(a: Dw, b: Dw): Dw;
+export declare function dwSub(a: Dw, b: Dw): Dw;
+export declare function dwMul(a: Dw, b: Dw): Dw;
+/**
+ * fma on float32 operands with one rounding to nearest (ties to even), as a fused `fma` evaluates it: the product of two float32
+ * values is exact in float64 (48 significant bits), the float64 TwoSum gives the sum's exact error, and the one case where rounding
+ * the float64 sum to float32 differs from rounding the exact sum (the float64 sum lands on a float32 midpoint) is resolved by the error's sign.
+ */
+export declare function fmaF32(a: number, b: number, c: number): number;
+/** The fma TwoProduct: p = fl(a·b) and its exact error fma(a, b, −p) (exact for a fused fma; Joldes, Muller & Popescu 2017, Algorithm 2). */
+export declare function twoProdFma(a: number, b: number): Dw;
+/** The cross-term sum t = a.h·b.l + a.l·b.h of a double-word product: unfused (the default), or with one of the two products fused into the addition. */
+export declare function dwCrossTerm(a: Dw, b: Dw, contraction?: "none" | "first" | "second"): number;
+/**
+ * The fma path's double-word product (`d_mul_fma`): s = fma(a.h, b.h, t), lo = fl(fma(a.h, b.h, −s) + t), with t the cross-term
+ * sum. No rounded product is an operand of an addition, so a contraction cannot change it; see docs/WEBGPU.md for its error bound.
+ */
+export declare function dwMulFma(a: Dw, b: Dw, t?: number): Dw;
+/** The Dekker path's double-word product with a given cross-term sum (`dwMul` is it with the unfused one). */
+export declare function dwMulDekker(a: Dw, b: Dw, t?: number): Dw;
+/**
+ * Probe inputs (x, y, z, w): pairs whose TwoSum and TwoProduct low parts are non-zero, double words to add and multiply, and sums and
+ * products that a directed (truncating or upward) rounding would place on the other neighbour than round-to-nearest: 1 + 3·2^-26
+ * rounds up to 1 + 2^-23 (nearest) but down to 1 (truncation); −1 − 3·2^-26 the mirror; 1.25 · (1 + 2^-23) likewise. The last four
+ * (2.11.0, the M5 Pro finding) are normalized double words whose products have non-zero TwoProduct errors on both operand pairs, so
+ * a contraction of the Dekker path's final Fast2Sum (which then adds the product's error twice) shows in the double-word product.
+ */
+export declare const PROBE_INPUTS: readonly (readonly [number, number, number, number])[];
+/** The components of the probe in output order (see `CHART_COMPOSITE_PROBE_WGSL`). */
+export declare const PROBE_COMPONENTS: readonly ChartCompositeProbeComponent[];
+/**
+ * The probe's output per input on a device that evaluates as written, round to nearest, unfused, with a fused `fma`, in the shader's
+ * order: [TwoSum lo, Dekker TwoProduct lo, double-word sum lo, fma TwoProduct lo, Dekker product hi, lo, fma product hi, lo].
+ */
+export declare function probeExpectation(input: readonly [number, number, number, number]): [number, number, number, number, number, number, number, number];
+/**
+ * Classifies the probe's output (`CHART_COMPOSITE_PROBE_OUTPUTS` floats per input of `PROBE_INPUTS`). TwoSum, both TwoProducts and the
+ * double-word sum must equal their exact values bit for bit (each is error-free, or a fixed sequence of roundings to nearest); a
+ * double-word product must equal the written-order evaluation for the unfused cross-term sum t = a.h·b.l + a.l·b.h or for either
+ * product of t fused into its addition (a contraction WGSL permits, "Reassociation and Fusion", and harmless there: t is an ordinary
+ * bounded sum). Anything else is a mismatch, recorded with the float32 bits.
+ */
+export declare function classifyChartCompositeProbe(got: Float32Array): ChartCompositeProbeRecord;
+/**
+ * One log line for a probe record: the class, the chosen path, each differing component with its count and the probe input
+ * indices that differ, and the first difference with its float32 bits.
+ */
+export declare function describeChartCompositeProbe(probe: ChartCompositeProbeRecord): string;
+/** The probe's refusal: `unsupported-on-backend` with the probe record (`probe`) for the execution diagnostics. */
+export declare class ChartCompositeProbeError extends ImageKernelExecutionError {
+    readonly probe: ChartCompositeProbeRecord;
+    constructor(probe: ChartCompositeProbeRecord);
+}
+/** Packed records of one scene: the kernel's float and integer arrays and its material count. */
+export interface PackedChartScene {
+    af: Float32Array<ArrayBuffer>;
+    ai: Uint32Array<ArrayBuffer>;
+    materials: number;
+    elementCount: number;
+    layerCount: number;
+}
+/** Sector boundary table of a Siemens star (bar or sine profile): directions, per-sector levels from the reference, bucket index and search window. */
+export declare function starSectorTable(chart: ResolvedChartScene, g: Extract<ChartGeometry, {
+    kind: "siemens-star";
+}>): {
+    thetas: Float64Array;
+    levels: Uint32Array;
+    buckets: Uint32Array;
+    window: number;
+};
+/** Packs the plan's chart (a composite, an element preset, or the chart under layers) and its layers into the kernel's record arrays. */
+export declare function packChartScene(plan: ChartRadianceBatchPlan): PackedChartScene;
+/** Per-material values in float64 (the reference's operations), rounded once; a failing spectrum is NaN and its points are recomputed. */
+export declare function chartMaterialTable(plan: ChartRadianceBatchPlan): Float32Array<ArrayBuffer>;
+/** The scene key of a batch input: the scene's data and the aspect (every record derives from them). */
+export declare function chartSceneKey(scene: unknown, aspect: number): string;
+/**
+ * The device's double-float32 probe (`CHART_COMPOSITE_PROBE_WGSL`, classified by `classifyChartCompositeProbe`): resolves with the probe
+ * record (its `productPath` is the variant the composite kernel is compiled with), or rejects with `ChartCompositeProbeError`
+ * (`unsupported-on-backend`, the record in `probe`) on a device that neither product path holds on. Run once per accelerator by
+ * `ChartSceneUploads.probe`, and once per display-view renderer by the composite material module (#491).
+ */
+export declare function probeChartCompositeDevice(runtime: WebGpuRuntime, pipelines: PipelineSource, signal: AbortSignal): Promise<ChartCompositeProbeRecord>;
+interface UploadedScene {
+    key: string;
+    scope: GpuResourceScope;
+    af: GPUBuffer;
+    ai: GPUBuffer;
+    packed: PackedChartScene;
+}
+/** Per accelerator: the uploaded records of recent scenes (a prepared view's scene is uploaded once) and the device probe. */
+export declare class ChartSceneUploads {
+    #private;
+    private readonly runtime;
+    private readonly keep;
+    constructor(runtime: WebGpuRuntime, keep?: number);
+    /** The device's double-float32 probe, run once per accelerator (single flight; a refusal is retried on the next call): the record, or `ChartCompositeProbeError`. */
+    probe(pipelines: PipelineSource, signal: AbortSignal): Promise<ChartCompositeProbeRecord>;
+    get(plan: ChartRadianceBatchPlan, scene: unknown, aspect: number): UploadedScene;
+    /** Scenes currently uploaded (for tests). */
+    get size(): number;
+    release(): void;
+}
+/** Points as float32 pairs (hi, lo) per coordinate: the float64 point to 2^-48. */
+export declare function splitPoints(points: Float32Array | Float64Array): Float32Array<ArrayBuffer>;
+export declare function evaluateChartCompositeOnGpu(runtime: WebGpuRuntime, bandBytes: number, plan: ChartRadianceBatchPlan, scene: unknown, points: Float32Array | Float64Array, indices: Uint8Array | Uint16Array | undefined, abort: AbortController, yieldControl: YieldControl, pipelines: PipelineSource, uploads: ChartSceneUploads): Promise<ChartRadianceResult>;
+export {};