@forgeax/engine-rhi-webgpu 0.1.21 → 0.1.23

package/README.md

@@ -51,13 +51,20 @@ Real-GPU integration is in [`src/__tests__/dawn-real-gpu.dawn.test.ts`](./src/__
 
 ## Timestamp write contract
 
+Timestamp capture uses the WebGPU pass descriptor `timestampWrites` field on
+`beginRenderPass` / `beginComputePass`. The shim maps the opaque ForgeaX
+`QuerySet` to the native `GPUQuerySet` at the pass boundary. The obsolete
+command-encoder `writeTimestamp` entry is intentionally not exposed: current
+Dawn rejects that method even when `timestamp-query` is advertised. A device
+without a usable timestamp period remains capability-negative and produces no
+synthetic ticks.
 When `device.caps.timestampQuery` is true, render and compute pass descriptors
 carry the mapped query set and timestamp indices. The WebGPU adapter does not
 expose the removed command-encoder timestamp entry; callers that need an
 encoder-position marker use an empty timestamp-enabled compute pass on the same
-encoder. A marker failure is a structured `webgpu-runtime-error`; the
-shim never treats it as a no-op or synthesizes timestamp ticks. Capability-
-disabled devices retain the existing refusal path.
+encoder. A marker failure is a structured `webgpu-runtime-error`; the shim
+never treats it as a no-op or synthesizes timestamp ticks. Capability-disabled
+devices retain the existing refusal path.
 
 ## Query forwarding contract
 
@@ -69,7 +76,7 @@ The shim forwards the query surface from [`@forgeax/engine-rhi`](../rhi):
 | `occlusionQuerySet` + `beginOcclusionQuery` / `endOcclusionQuery` | The pass owns the query-set state; missing set, out-of-range index, nested begin, and unmatched end produce structured errors | [`device.ts`](./src/device.ts#L542), [Dawn state/round-trip coverage](./src/__tests__/dawn-real-gpu.dawn.test.ts#L619) |
 | `resolveQuerySet` | Validates 256-byte destination alignment, `QUERY_RESOLVE` usage, range, and destination size before raw forwarding | [`device.ts`](./src/device.ts#L966), [Dawn coverage](./src/__tests__/dawn-real-gpu.dawn.test.ts#L820) |
 | Timestamp pass writes | `timestampWrites` maps opaque `QuerySet` handles to raw `GPUQuerySet`; a capability-negative device refuses creation and does not synthesize ticks | [`device.ts`](./src/device.ts#L745), [Dawn admission/readback coverage](./src/__tests__/dawn-real-gpu.dawn.test.ts#L1233) |
-| Command-encoder `writeTimestamp` | Capability-positive devices require a callable raw method; missing/throwing raw methods surface `webgpu-runtime-error` | [`device.ts`](./src/device.ts#L1048), [unit coverage](./src/__tests__/rhi-webgpu.unit.test.ts#L394) |
+| Pass descriptor `timestampWrites` | Capability-positive devices map opaque query sets at the real render/compute pass boundary; unavailable periods remain fail-closed | [`device.ts`](./src/device.ts#L745), [unit coverage](./src/internal/__tests__/timestamp-query.unit.test.ts) |
 | `executeBundles` | Still unavailable: the public RHI has no constructible `RenderBundle` handle or creation path, so the shim returns `rhi-not-available` | [`device.ts`](./src/device.ts#L533) |
 
 > [!NOTE]

package/dist/__tests__/r32float-capability-generation.integration.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=r32float-capability-generation.integration.test.d.ts.map

package/dist/__tests__/r32float-capability-generation.integration.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"r32float-capability-generation.integration.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/r32float-capability-generation.integration.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/r32float-format-capability.browser.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=r32float-format-capability.browser.test.d.ts.map

package/dist/__tests__/r32float-format-capability.browser.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"r32float-format-capability.browser.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/r32float-format-capability.browser.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/r32float-format-capability.dawn.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=r32float-format-capability.dawn.test.d.ts.map

package/dist/__tests__/r32float-format-capability.dawn.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"r32float-format-capability.dawn.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/r32float-format-capability.dawn.test.ts"],"names":[],"mappings":""}

package/dist/device.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"device.d.ts","sourceRoot":"","sources":["../src/device.ts"],"names":[],"mappings":"AA8BA,OAAO,KAAK,EAwBV,gBAAgB,EAIhB,SAAS,EAcV,MAAM,qBAAqB,CAAC;AA8L7B;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,SAAS,GAAG,SAAS,GAAG,SAAS,CAE/E;AA6qCD;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,SAAS,GAAG;IACnD,MAAM,EAAE,SAAS,CAAC;IAClB;6CACyC;IACzC,GAAG,EAAE,SAAS,CAAC;CAChB,CA2aA;AA0BD;;iFAEiF;AACjF,MAAM,WAAW,oBAAoB;IACnC,SAAS,CAAC,aAAa,EAAE,sBAAsB,GAAG,IAAI,CAAC;IACvD,WAAW,IAAI,IAAI,CAAC;IACpB,gBAAgB,IAAI,sBAAsB,GAAG,IAAI,CAAC;IAClD,iBAAiB,IAAI,UAAU,CAAC;CACjC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,oBAAoB,GAAG,gBAAgB,CAqGpF"}
+{"version":3,"file":"device.d.ts","sourceRoot":"","sources":["../src/device.ts"],"names":[],"mappings":"AA8BA,OAAO,KAAK,EAwBV,gBAAgB,EAIhB,SAAS,EAcV,MAAM,qBAAqB,CAAC;AAqM7B;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,SAAS,GAAG,SAAS,GAAG,SAAS,CAE/E;AA6qCD;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,SAAS,GAAG;IACnD,MAAM,EAAE,SAAS,CAAC;IAClB;6CACyC;IACzC,GAAG,EAAE,SAAS,CAAC;CAChB,CA2bA;AA0BD;;iFAEiF;AACjF,MAAM,WAAW,oBAAoB;IACnC,SAAS,CAAC,aAAa,EAAE,sBAAsB,GAAG,IAAI,CAAC;IACvD,WAAW,IAAI,IAAI,CAAC;IACpB,gBAAgB,IAAI,sBAAsB,GAAG,IAAI,CAAC;IAClD,iBAAiB,IAAI,UAAU,CAAC;CACjC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,oBAAoB,GAAG,gBAAgB,CAqGpF"}

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { err, RhiError, ok } from '@forgeax/engine-rhi';
+import { err, RhiError, ok, R32FLOAT_PROBE_STAGES, validateR32FloatReceipt, createUnavailableR32FloatReceipt } from '@forgeax/engine-rhi';
 export { RhiError as RhiErrorClass, err, ok } from '@forgeax/engine-rhi';
 
 // src/index.ts
@@ -108,6 +108,131 @@ function queueWriteBufferOutOfBounds(args) {
     })
   );
 }
+var TEXTURE_BINDING = 4;
+var STORAGE_BINDING = 8;
+var COPY_SRC = 1;
+var COPY_DST = 2;
+var MAP_READ = 1;
+var BUFFER_COPY_DST = 8;
+async function probeR32FloatCapability(rawDevice, deviceGeneration) {
+  let stage = "texture-create";
+  let texture;
+  let readback;
+  rawDevice.pushErrorScope("validation");
+  try {
+    texture = rawDevice.createTexture({
+      size: { width: 2, height: 2, depthOrArrayLayers: 1 },
+      format: "r32float",
+      mipLevelCount: 2,
+      usage: TEXTURE_BINDING | STORAGE_BINDING | COPY_SRC | COPY_DST
+    });
+    stage = "mip-view";
+    const sourceView = texture.createView({ baseMipLevel: 0, mipLevelCount: 1 });
+    const destinationView = texture.createView({ baseMipLevel: 1, mipLevelCount: 1 });
+    stage = "sampled-storage-bind-group";
+    const layout = rawDevice.createBindGroupLayout({
+      entries: [
+        {
+          binding: 0,
+          visibility: 4,
+          texture: { sampleType: "unfilterable-float", viewDimension: "2d" }
+        },
+        {
+          binding: 1,
+          visibility: 4,
+          storageTexture: { access: "write-only", format: "r32float", viewDimension: "2d" }
+        }
+      ]
+    });
+    const bindGroup = rawDevice.createBindGroup({
+      layout,
+      entries: [
+        { binding: 0, resource: sourceView },
+        { binding: 1, resource: destinationView }
+      ]
+    });
+    stage = "pipeline-bind";
+    const shader = rawDevice.createShaderModule({
+      code: `
+        @group(0) @binding(0) var source: texture_2d<f32>;
+        @group(0) @binding(1) var destination: texture_storage_2d<r32float, write>;
+        @compute @workgroup_size(1) fn main() {
+          let value = textureLoad(source, vec2i(0, 0), 0).r;
+          textureStore(destination, vec2i(0, 0), vec4f(value));
+        }
+      `
+    });
+    const pipeline = rawDevice.createComputePipeline({
+      layout: rawDevice.createPipelineLayout({ bindGroupLayouts: [layout] }),
+      compute: { module: shader, entryPoint: "main" }
+    });
+    const encoder = rawDevice.createCommandEncoder({ label: "r32float-profile" });
+    const pass = encoder.beginComputePass();
+    pass.setPipeline(pipeline);
+    pass.setBindGroup(0, bindGroup);
+    pass.dispatchWorkgroups(1);
+    pass.end();
+    stage = "finish";
+    readback = rawDevice.createBuffer({ size: 256, usage: MAP_READ | BUFFER_COPY_DST });
+    encoder.copyTextureToBuffer(
+      { texture, mipLevel: 1 },
+      { buffer: readback, bytesPerRow: 256, rowsPerImage: 1 },
+      { width: 1, height: 1, depthOrArrayLayers: 1 }
+    );
+    const commandBuffer = encoder.finish();
+    stage = "submit";
+    rawDevice.queue.submit([commandBuffer]);
+    stage = "completion";
+    await rawDevice.queue.onSubmittedWorkDone();
+    const validationError = await rawDevice.popErrorScope();
+    if (validationError !== null) {
+      throw new Error(`WebGPU validation: ${validationError.message}`);
+    }
+    stage = "readback";
+    await readback.mapAsync(MAP_READ);
+    const values = Array.from(new Float32Array(readback.getMappedRange(0, 4).slice(0)));
+    readback.unmap();
+    const receipt = {
+      profile: "r32float-mip-sampled-storage",
+      verdict: "admitted",
+      evidence: "real",
+      deviceGeneration,
+      stages: R32FLOAT_PROBE_STAGES.map((entry) => ({
+        stage: entry,
+        verdict: "admitted",
+        evidence: "real"
+      })),
+      sampleType: "unfilterable-float",
+      usages: ["texture-binding", "storage-binding", "copy-src"],
+      readback: { byteLength: 4, values },
+      probeExecutions: 1
+    };
+    const validated = validateR32FloatReceipt(receipt);
+    return validated.ok ? ok(validated.value) : validated;
+  } catch (cause) {
+    const message = cause instanceof Error ? cause.message : String(cause);
+    createUnavailableR32FloatReceipt({
+      deviceGeneration,
+      failedStage: stage,
+      detail: message
+    });
+    return err(
+      new RhiError({
+        code: "rhi-texture-format-capability-unavailable",
+        expected: `r32float profile stage ${stage} to complete on the live WebGPU device`,
+        hint: "retain fallback-only rendering and inspect the device validation error",
+        detail: {
+          stage,
+          deviceGeneration,
+          reason: message
+        }
+      })
+    );
+  } finally {
+    texture?.destroy();
+    readback?.destroy();
+  }
+}
 function resolveTimestampQueries(args) {
   try {
     args.rawEncoder.resolveQuerySet(
@@ -183,6 +308,9 @@ var CP_KEYS = ["label", "layout", "compute"];
 var QS_KEYS = ["label", "type", "count"];
 var QUERY_SET_COUNT_LIMIT = 4096;
 var RAW_DEVICE_MAP = /* @__PURE__ */ new WeakMap();
+var RAW_DEVICE_GENERATION_MAP = /* @__PURE__ */ new WeakMap();
+var R32FLOAT_PROBE_CACHE = /* @__PURE__ */ new WeakMap();
+var NEXT_DEVICE_GENERATION = 1;
 var BUFFER_RAW_MAP = /* @__PURE__ */ new WeakMap();
 var TEXTURE_VIEW_RAW_MAP = /* @__PURE__ */ new WeakMap();
 var ENCODER_STATE = /* @__PURE__ */ new WeakMap();
@@ -1030,10 +1158,22 @@ function makeRhiDevice(rawDevice) {
   const features = rawDevice.features;
   const limits = rawDevice.limits;
   const queue = makeQueue(rawDevice.queue);
+  const deviceGeneration = RAW_DEVICE_GENERATION_MAP.get(rawDevice) ?? (() => {
+    const generation = NEXT_DEVICE_GENERATION++;
+    RAW_DEVICE_GENERATION_MAP.set(rawDevice, generation);
+    return generation;
+  })();
   const device = {
     caps,
     features,
     limits,
+    probeTextureFormatCapability() {
+      const cached = R32FLOAT_PROBE_CACHE.get(device);
+      if (cached !== void 0) return cached;
+      const probe = probeR32FloatCapability(rawDevice, deviceGeneration);
+      R32FLOAT_PROBE_CACHE.set(device, probe);
+      return probe;
+    },
     queue,
     lost: rawDevice.lost,
     createBuffer(desc) {