@forgeax/engine-rhi-webgpu 0.1.20 → 0.1.23

package/README.md

@@ -51,12 +51,20 @@ Real-GPU integration is in [`src/__tests__/dawn-real-gpu.dawn.test.ts`](./src/__
 
 ## Timestamp write contract
 
-When `device.caps.timestampQuery` is true, `RhiCommandEncoder.writeTimestamp`
-must find and successfully call the raw `GPUCommandEncoder.writeTimestamp`
-with the mapped query set and index. A missing or throwing raw method throws a
-structured `RhiError` with code `webgpu-runtime-error`; the shim never treats
-that write as a no-op or synthesizes timestamp ticks. Capability-disabled
-devices retain the existing `feature-not-enabled` diagnostic path.
+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.
 
 ## Query forwarding contract
 
@@ -68,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":"AA6BA,OAAO,KAAK,EAuBV,gBAAgB,EAIhB,SAAS,EAaV,MAAM,qBAAqB,CAAC;AA8L7B;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,SAAS,GAAG,SAAS,GAAG,SAAS,CAE/E;AAsrCD;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,SAAS,GAAG;IACnD,MAAM,EAAE,SAAS,CAAC;IAClB;6CACyC;IACzC,GAAG,EAAE,SAAS,CAAC;CAChB,CAicA;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(
@@ -129,26 +254,6 @@ function resolveTimestampQueries(args) {
     );
   }
 }
-function writeTimestamp(args) {
-  const encoderWithTimestamp = args.rawEncoder;
-  if (typeof encoderWithTimestamp.writeTimestamp !== "function") {
-    throw new RhiError({
-      code: "webgpu-runtime-error",
-      expected: "underlying GPUCommandEncoder.writeTimestamp to be callable",
-      hint: "timestamp-query is advertised but the raw encoder has no writeTimestamp method"
-    });
-  }
-  try {
-    encoderWithTimestamp.writeTimestamp(args.rawQuerySet, args.queryIndex);
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    throw new RhiError({
-      code: "webgpu-runtime-error",
-      expected: "underlying GPUCommandEncoder.writeTimestamp to succeed",
-      hint: `writeTimestamp raised: ${message}`
-    });
-  }
-}
 
 // src/device.ts
 function mirror(src, keys) {
@@ -203,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();
@@ -578,7 +686,7 @@ function mirrorRenderPipelineDescriptor(desc) {
     ...fragment === void 0 ? {} : { fragment }
   };
 }
-function makeCommandEncoder(rawEncoder, caps, fireFeatureNotEnabled) {
+function makeCommandEncoder(rawEncoder) {
   function mirrorComputePassDescriptor(desc) {
     if (desc === void 0) return void 0;
     const out = mirror(desc, ["label"]);
@@ -631,6 +739,12 @@ function makeCommandEncoder(rawEncoder, caps, fireFeatureNotEnabled) {
       };
       return pass;
     },
+    encodeEmptyComputePass(desc) {
+      const state = ENCODER_STATE.get(enc);
+      throwIfFinished(state);
+      const rawPass = rawEncoder.beginComputePass(mirrorComputePassDescriptor(desc));
+      rawPass.end();
+    },
     copyBufferToBuffer(source, arg2, arg3, arg4, arg5) {
       const state = ENCODER_STATE.get(enc);
       throwIfFinished(state);
@@ -657,11 +771,19 @@ function makeCommandEncoder(rawEncoder, caps, fireFeatureNotEnabled) {
     copyTextureToBuffer(source, destination, copySize) {
       const state = ENCODER_STATE.get(enc);
       throwIfFinished(state);
+      const rawSource = {
+        texture: source.texture
+      };
+      if (source.mipLevel !== void 0) rawSource.mipLevel = source.mipLevel;
+      if (source.origin !== void 0) rawSource.origin = source.origin;
+      if (source.aspect !== void 0) rawSource.aspect = source.aspect;
       const rawDst = {
-        ...destination,
         buffer: BUFFER_RAW_MAP.get(destination.buffer) ?? destination.buffer
       };
-      rawEncoder.copyTextureToBuffer(source, rawDst, copySize);
+      if (destination.offset !== void 0) rawDst.offset = destination.offset;
+      if (destination.bytesPerRow !== void 0) rawDst.bytesPerRow = destination.bytesPerRow;
+      if (destination.rowsPerImage !== void 0) rawDst.rowsPerImage = destination.rowsPerImage;
+      rawEncoder.copyTextureToBuffer(rawSource, rawDst, copySize);
     },
     copyTextureToTexture(source, destination, copySize) {
       const state = ENCODER_STATE.get(enc);
@@ -741,19 +863,6 @@ function makeCommandEncoder(rawEncoder, caps, fireFeatureNotEnabled) {
     insertDebugMarker(markerLabel) {
       rawEncoder.insertDebugMarker(markerLabel);
     },
-    writeTimestamp(querySet, queryIndex) {
-      const state = ENCODER_STATE.get(enc);
-      throwIfFinished(state);
-      if (caps.timestampQuery !== true) {
-        fireFeatureNotEnabled(
-          "timestamp-query",
-          "check device.caps.timestampQuery before calling writeTimestamp"
-        );
-        return;
-      }
-      const rawQs = QUERY_SET_RAW_MAP.get(querySet) ?? querySet;
-      writeTimestamp({ rawEncoder, rawQuerySet: rawQs, queryIndex });
-    },
     finish() {
       const state = ENCODER_STATE.get(enc);
       if (state === void 0) {
@@ -1049,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) {
@@ -1383,12 +1504,7 @@ function makeRhiDevice(rawDevice) {
       const rawEnc = desc === void 0 ? rawDevice.createCommandEncoder() : rawDevice.createCommandEncoder(
         mirror(desc, ENC_KEYS)
       );
-      const fireFeatureNotEnabled = (featureName, hint) => {
-        console.error(
-          `[RhiError feature-not-enabled] expected: device.features.has('${featureName}') === true; hint: ${hint}`
-        );
-      };
-      return ok(makeCommandEncoder(rawEnc, caps, fireFeatureNotEnabled));
+      return ok(makeCommandEncoder(rawEnc));
     }
     // fix-f3: synchronous createShaderModule placeholder removed; the
     // shader-compile-failed path lives in the top-level async factory