import { Node, StorageInstancedBufferAttribute, TypedArray, WebGPURenderer } from "three/webgpu"; import { BufferAttribute } from "three"; //#region src/context.d.ts type BackendName = "webgpu" | "webgl"; /** Probe whether a backend can initialize in this environment. */ declare function isBackendAvailable(backend: BackendName): Promise; declare function disposeRenderer(backend?: BackendName): Promise; //#endregion //#region src/assert/runner.d.ts /** Anything an assertion can compare against: a TSL node or a CPU-side constant. */ type ExpectedValue = Node | number | number[] | TypedArray; interface GPUAssert { /** Assert `actual` strictly equals `expected` component-wise; NaN never equals anything, including itself. */ eq: (actual: Node, expected: ExpectedValue, message?: string) => void; /** Assert `actual` is within `tolerance` (absolute) of `expected` component-wise: |a - e| <= tolerance. */ closeAbs: (actual: Node, expected: ExpectedValue, tolerance?: number, message?: string) => void; /** Assert `actual` is within `tolerance` (relative) of `expected` component-wise: |a - e| <= tolerance * max(|a|, |e|, 1e-12). */ closeRel: (actual: Node, expected: ExpectedValue, tolerance?: number, message?: string) => void; /** Assert each component of `actual` is greater than the corresponding component of `expected`. */ greaterThan: (actual: Node, expected: ExpectedValue, message?: string) => void; /** Assert each component of `actual` is greater than or equal to the corresponding component of `expected`. */ greaterThanOrEqual: (actual: Node, expected: ExpectedValue, message?: string) => void; /** Assert each component of `actual` is less than the corresponding component of `expected`. */ lessThan: (actual: Node, expected: ExpectedValue, message?: string) => void; /** Assert each component of `actual` is less than or equal to the corresponding component of `expected`. */ lessThanOrEqual: (actual: Node, expected: ExpectedValue, message?: string) => void; } declare const DEFAULT_TOLERANCE = 0.000001; interface GPURunOptions { /** * Upper bound on assertions per gpuTest call. Buffers are sized * `maxAssertions * MAX_COLUMNS` rows. The last row is reserved for the canary * value, so the maximum number of actual assertions is `maxAssertions - 1`. * Default 64 (i.e., up to 63 assertions). */ maxAssertions?: number; /** * Backends to run this suite against. Defaults to the harness default, * or `['webgpu', 'webgl']`. Unavailable backends are soft-skipped with a * warning; if none are available the test fails. */ backends?: readonly BackendName[]; } /** * Run TSL assertions on the GPU, batching them into one compute dispatch * per requested backend. * * Supports scalars, vecN, mat3 and mat4. `fn` is called during graph build * and must be idempotent (it may run more than once). Unavailable backends * are soft-skipped; if none are available, the test fails. * * @param name - Test name used in error messages. * @param fn - Callback receiving the assertion API. May be invoked multiple * times; do not rely on call count or mutate external state. * @param options - Optional configuration. See {@link GPURunOptions}. * @returns Resolves after all assertions pass on every available backend; * rejects on first failure. * * @example * ```ts * await gpuTest('vec4 add', ({ eq, closeAbs }) => { * eq(vec4(1, 2, 3, 4).add(vec4(10, 20, 30, 40)), vec4(11, 22, 33, 44)); * closeAbs(vec2(1, 2).mul(3), vec2(3, 6), 1e-6); * }); * ``` */ declare function gpuTest(name: string, fn: (assert: GPUAssert) => void, options?: GPURunOptions): Promise; //#endregion //#region src/fuzz.d.ts /** * How to interpret a tolerance value for fuzz comparison. * * A bare `number` is shorthand for `{ kind: "relative", value: n }` — the * default relative comparison. An object makes the mode explicit and leaves * room for further kinds (e.g. `ulps`) without breaking existing call sites. */ type Tolerance = number | { kind: "relative" | "absolute"; value: number; }; /** * Deterministic fuzz-test spec: every instance gets one scalar input derived * from its index, one GPU expression evaluated on that input, and one CPU-side * reference value. All instances run in a single compute pass. */ interface FuzzSpec { /** Number of instances to test. */ instances: number; /** Deterministic input generator (pure function of the instance index). */ input: (instance: number) => number; /** Build the actual GPU expression from the input node. */ test: (x: Node<"float">) => Node; /** CPU-side reference value(s) for each instance. */ expected: (x: number, instance: number) => number | number[]; /** * Tolerance for comparisons. A bare number means relative tolerance * (`|a - e| <= tolerance * max(|a|, |e|, 1e-12)`); this is the default and * covers the overwhelming majority of cases. * * Pass `{ kind: "absolute", value }` for absolute tolerance * (`|a - e| <= value`) for periodic functions like sin/cos, where f32 and * f64 precision differences cause relative tolerance to fail near zero * crossings (e.g. sin(π) differs between f32 and f64). */ tolerance?: Tolerance; /** * Backends to run this suite against. Defaults to the harness default, * or `['webgpu', 'webgl']`. Unavailable backends are soft-skipped. */ backends?: readonly BackendName[]; } /** * Run a deterministic fuzz test across many instances on each requested backend. * * Inputs are generated on the CPU with `spec.input(i)`, uploaded as floats, * and compared against `spec.expected` after GPU readback. Unavailable * backends are soft-skipped; if none are available, the test fails. * * @param name - Test name used in error messages. * @param spec - Fuzz specification. See {@link FuzzSpec}. * @returns Resolves after all instances pass on every available backend; * rejects on first failure. * * @example * ```ts * await gpuFuzzTest('sin²x + cos²x ≈ 1', { * instances: 1024, * input: (i) => (i / 1024) * Math.PI * 2, * test: (x) => sin(x).pow(2).add(cos(x).pow(2)), * expected: () => 1, * tolerance: 1e-6, * }); * ``` */ declare function gpuFuzzTest(name: string, spec: FuzzSpec): Promise; //#endregion //#region src/config.d.ts /** * Default backend configuration. * * The default backend list used when no harness-level or per-call * `backends` option is provided. Frozen — the array itself is readonly, * and its contents are not mutated by any library code. */ declare const DEFAULT_BACKENDS: readonly BackendName[]; //#endregion //#region src/raw.d.ts interface RawComputeTestOptions { /** * GPU backend to use. Defaults to 'webgpu'. */ backend?: BackendName; /** * WebGPU feature required by this test (e.g. 'subgroups'). * If the renderer doesn't report the feature, the test is soft-skipped. */ requiredFeature?: string; } /** * Context passed to the test callback with the ready-to-use renderer. */ interface RawComputeTestContext { renderer: WebGPURenderer; } /** * Run a raw GPU compute test with full control over dispatch. * * Unlike `gpuTest` which batches assertions into a single dispatch, this * primitive lets the caller: * - Build and dispatch compute kernels that **cannot be expressed as `gpuTest` * assertions** (e.g., multiple invocations cooperating through shared/atomic * memory) * - Read back the integer-typed buffers that such kernels typically produce * (`Uint32Array`, `Int32Array`) * - Check workgroup/subgroup identity values * * For float assertions, use `gpuTest` / `gpuFuzzTest` — they handle readback, * tolerance, and diagnostics end-to-end. * * The renderer is obtained from the shared cache (same as `gpuTest`). * * If the backend is unavailable or the required feature is not supported, * the test is soft-skipped with a warning (test passes, not fails). * * **TSL compute dispatch note**: Use `kernel.compute(totalInvocations, [workgroupSize])` * inside the callback. The first argument is the **total number of invocations** * (not workgroup count). `instanceIndex` ranges from `0` to `totalInvocations - 1`. * The optional second argument groups threads into workgroups; omit it or use `[1]` * for single-thread-per-workgroup dispatch. * * @param name - Test name used in skip/failure messages. * @param options - Backend and required feature. See {@link RawComputeTestOptions}. * @param fn - Callback receiving the ready renderer; may be async. * @returns Resolves after the callback completes, or after a soft-skip. * * @example * ```ts * it('atomic counter', async () => { * await rawComputeTest('atomic add', { backend: 'webgpu' }, async ({ renderer }) => { * // Build your own TSL kernel and dispatch * await renderer.computeAsync(kernel); * const data = await readUintBuffer(renderer, buffer.value); * expect(data[0]).toBe(42); * }); * }); * ``` */ declare function rawComputeTest(name: string, options: RawComputeTestOptions, fn: (ctx: RawComputeTestContext) => Promise | void): Promise; /** * Read back a storage buffer as Uint32Array. * * Use this for buffers declared with `uint` type in TSL storage definitions. * Unlike `readStorage` which returns Float32Array, this preserves integer * values exactly. * * **Important**: Pass `buffer.value` (the `StorageInstancedBufferAttribute`), * not the TSL node returned by `storage()` or `instancedArray().toAtomic()`. * * **Type note**: The parameter type is intentionally broad (`BufferAttribute` * | `StorageInstancedBufferAttribute`) because three.js's `storage()` node * declares `.value` as the base class. A runtime `instanceof` check rejects * non-storage attributes with a clear error, so callers do not need to cast. * * @param renderer - The WebGPURenderer instance * @param buffer - Storage buffer attribute whose data is read back. * @returns Promise resolving to Uint32Array containing the buffer data * * @example * ```ts * const buffer = storage(new Uint32Array([0]), 'uint', 0); * // ... dispatch compute kernel that modifies buffer ... * const data = await readUintBuffer(renderer, buffer.value); * expect(data[0]).toBe(123); * ``` */ declare function readUintBuffer(renderer: WebGPURenderer, buffer: StorageInstancedBufferAttribute | BufferAttribute): Promise; /** * Read back a storage buffer as Int32Array. * * Use this for buffers declared with `int` type in TSL storage definitions. * Unlike `readStorage` which returns Float32Array, this preserves signed * integer values exactly. * * **Important**: Pass `buffer.value` (the `StorageInstancedBufferAttribute`), * not the TSL node returned by `storage()` or `instancedArray().toAtomic()`. * * **Type note**: The parameter type is intentionally broad (`BufferAttribute` * | `StorageInstancedBufferAttribute`) because three.js's `storage()` node * declares `.value` as the base class. A runtime `instanceof` check rejects * non-storage attributes with a clear error, so callers do not need to cast. * * @param renderer - The WebGPURenderer instance * @param buffer - Storage buffer attribute whose data is read back. * @returns Promise resolving to Int32Array containing the buffer data * * @example * ```ts * const buffer = storage(new Int32Array([0]), 'int', 0); * // ... dispatch compute kernel that modifies buffer ... * const data = await readIntBuffer(renderer, buffer.value); * expect(data[0]).toBe(-1); * ``` */ declare function readIntBuffer(renderer: WebGPURenderer, buffer: StorageInstancedBufferAttribute | BufferAttribute): Promise; //#endregion export { readUintBuffer as a, gpuFuzzTest as c, GPUAssert as d, GPURunOptions as f, isBackendAvailable as g, disposeRenderer as h, readIntBuffer as i, DEFAULT_TOLERANCE as l, BackendName as m, RawComputeTestOptions as n, DEFAULT_BACKENDS as o, gpuTest as p, rawComputeTest as r, FuzzSpec as s, RawComputeTestContext as t, ExpectedValue as u };