@forgeax/engine-rhi-webgpu 0.1.4 → 0.1.7

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { err, RhiError, ok, resolveBufferWriteRange } from '@forgeax/engine-rhi';
+import { err, RhiError, ok } from '@forgeax/engine-rhi';
 export { RhiError as RhiErrorClass, err, ok } from '@forgeax/engine-rhi';
 
 // src/index.ts
@@ -6,8 +6,36 @@ function adapterUnavailable() {
   return err(
     new RhiError({
       code: "adapter-unavailable",
-      expected: "an available WebGPU adapter",
-      hint: "check whether the browser supports WebGPU or enable the relevant flag"
+      expected: "an available browser-native WebGPU adapter",
+      hint: "this only reports the browser-native WebGPU channel; ForgeaX may continue through its wgpu/WebGL2 fallback, so do not conclude that the browser or machine is unsupported unless both backend causes fail"
+    })
+  );
+}
+function requestAdapterFailed(cause) {
+  const record = cause !== null && typeof cause === "object" ? cause : void 0;
+  const name = typeof record?.name === "string" && record.name.length > 0 ? record.name : void 0;
+  let message = typeof record?.message === "string" && record.message.length > 0 ? record.message : typeof cause === "string" ? cause : "";
+  if (message.length === 0 && cause !== void 0) {
+    try {
+      const serialized = JSON.stringify(cause);
+      message = serialized && serialized !== "{}" ? serialized : "unknown thrown object";
+    } catch {
+      message = "unserializable thrown object";
+    }
+  }
+  if (message.length === 0) message = "unknown requestAdapter failure";
+  return err(
+    new RhiError({
+      code: "webgpu-runtime-error",
+      expected: "navigator.gpu.requestAdapter() resolves with an adapter or null",
+      hint: "inspect detail.error before assigning the failure to WebGPU capability; the ForgeaX runtime can still attempt its wgpu/WebGL2 fallback",
+      detail: {
+        error: {
+          code: "request-adapter-threw",
+          ...name === void 0 ? {} : { name },
+          message
+        }
+      }
     })
   );
 }
@@ -80,62 +108,7 @@ function queueWriteBufferOutOfBounds(args) {
     })
   );
 }
-function timestampQueryHealth(input) {
-  if (!input.capability) {
-    return {
-      status: "fault",
-      code: "timestamp-query-unsupported",
-      expected: "device.caps.timestampQuery is true before timestamp queries are submitted",
-      hint: "use the CPU timing path or recreate the renderer with timestamp-query capability",
-      deviceGeneration: input.deviceGeneration,
-      expectedGeneration: input.expectedGeneration
-    };
-  }
-  if (input.expectedGeneration !== void 0 && input.deviceGeneration !== input.expectedGeneration) {
-    return {
-      status: "fault",
-      code: "timestamp-query-generation-mismatch",
-      expected: "timestamp encoder generation matches the live device generation",
-      hint: "discard the stale encoder and rebuild timestamp resources during device recovery",
-      deviceGeneration: input.deviceGeneration,
-      expectedGeneration: input.expectedGeneration
-    };
-  }
-  if (!input.encoderWriteTimestamp) {
-    return {
-      status: "fault",
-      code: "timestamp-query-encoder-missing",
-      expected: "underlying GPUCommandEncoder.writeTimestamp to be callable",
-      hint: "timestamp-query is advertised but the raw encoder has no writeTimestamp method",
-      deviceGeneration: input.deviceGeneration,
-      expectedGeneration: input.expectedGeneration
-    };
-  }
-  return {
-    status: "ready",
-    code: void 0,
-    expected: "timestamp-query capability and encoder are available for this device generation",
-    hint: "continue with the timestamp query operation",
-    deviceGeneration: input.deviceGeneration,
-    expectedGeneration: input.expectedGeneration
-  };
-}
 function resolveTimestampQueries(args) {
-  if (args.deviceGeneration !== void 0 && args.expectedGeneration !== void 0 && args.deviceGeneration !== args.expectedGeneration) {
-    const health = timestampQueryHealth({
-      capability: true,
-      encoderWriteTimestamp: true,
-      deviceGeneration: args.deviceGeneration,
-      expectedGeneration: args.expectedGeneration
-    });
-    return err(
-      new RhiError({
-        code: "webgpu-runtime-error",
-        expected: health.expected,
-        hint: `${health.code}: ${health.hint}`
-      })
-    );
-  }
   try {
     args.rawEncoder.resolveQuerySet(
       args.rawQuerySet,
@@ -158,21 +131,7 @@ function resolveTimestampQueries(args) {
 }
 function writeTimestamp(args) {
   const encoderWithTimestamp = args.rawEncoder;
-  const writeTimestamp2 = encoderWithTimestamp.writeTimestamp;
-  const health = timestampQueryHealth({
-    capability: true,
-    encoderWriteTimestamp: typeof writeTimestamp2 === "function",
-    deviceGeneration: args.deviceGeneration ?? 0,
-    expectedGeneration: args.expectedGeneration
-  });
-  if (health.status === "fault") {
-    throw new RhiError({
-      code: "webgpu-runtime-error",
-      expected: health.expected,
-      hint: health.code === "timestamp-query-encoder-missing" ? health.hint : `${health.code}: ${health.hint}`
-    });
-  }
-  if (typeof writeTimestamp2 !== "function") {
+  if (typeof encoderWithTimestamp.writeTimestamp !== "function") {
     throw new RhiError({
       code: "webgpu-runtime-error",
       expected: "underlying GPUCommandEncoder.writeTimestamp to be callable",
@@ -180,7 +139,7 @@ function writeTimestamp(args) {
     });
   }
   try {
-    writeTimestamp2(args.rawQuerySet, args.queryIndex);
+    encoderWithTimestamp.writeTimestamp(args.rawQuerySet, args.queryIndex);
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     throw new RhiError({
@@ -228,15 +187,6 @@ var SAMPLER_KEYS = [
 ];
 var BGL_KEYS = ["label", "entries"];
 var PL_KEYS = ["label", "bindGroupLayouts"];
-var RPP_KEYS = [
-  "label",
-  "layout",
-  "vertex",
-  "primitive",
-  "depthStencil",
-  "multisample",
-  "fragment"
-];
 var ENC_KEYS = ["label"];
 var TEXTURE_VIEW_KEYS = [
   "label",
@@ -254,6 +204,7 @@ var QS_KEYS = ["label", "type", "count"];
 var QUERY_SET_COUNT_LIMIT = 4096;
 var RAW_DEVICE_MAP = /* @__PURE__ */ new WeakMap();
 var BUFFER_RAW_MAP = /* @__PURE__ */ new WeakMap();
+var TEXTURE_VIEW_RAW_MAP = /* @__PURE__ */ new WeakMap();
 var ENCODER_STATE = /* @__PURE__ */ new WeakMap();
 var PASS_STATE = /* @__PURE__ */ new WeakMap();
 var COMMAND_BUFFER_RAW_MAP = /* @__PURE__ */ new WeakMap();
@@ -393,8 +344,7 @@ function makeRenderPassEncoder(rawPass, encoder, occlusionQuerySet) {
       rawPass.setViewport(x, y, w, h, minDepth, maxDepth);
     },
     setScissorRect(x, y, w, h) {
-      const setScissorRect = rawPass.setScissorRect;
-      setScissorRect?.call(rawPass, x, y, w, h);
+      rawPass.setScissorRect(x, y, w, h);
     },
     setBlendConstant(color) {
       rawPass.setBlendConstant(color);
@@ -554,6 +504,80 @@ function throwIfFinished(state) {
     throw new RhiError(ENCODER_FINISHED_ERROR_ARGS);
   }
 }
+function rawTextureView(view) {
+  return TEXTURE_VIEW_RAW_MAP.get(view) ?? view;
+}
+function mirrorRenderPassDescriptor(desc) {
+  const colorAttachments = [];
+  for (const attachment of desc.colorAttachments) {
+    if (attachment === null || attachment === void 0) {
+      colorAttachments.push(null);
+      continue;
+    }
+    if (attachment.loadOp === void 0 || attachment.storeOp === void 0) {
+      throw new TypeError("RHI render-pass color attachments require loadOp and storeOp");
+    }
+    colorAttachments.push({
+      view: rawTextureView(attachment.view),
+      ...attachment.depthSlice === void 0 ? {} : { depthSlice: attachment.depthSlice },
+      ...attachment.resolveTarget === void 0 ? {} : { resolveTarget: rawTextureView(attachment.resolveTarget) },
+      ...attachment.clearValue === void 0 ? {} : { clearValue: attachment.clearValue },
+      loadOp: attachment.loadOp,
+      storeOp: attachment.storeOp
+    });
+  }
+  return {
+    ...desc.label === void 0 ? {} : { label: desc.label },
+    colorAttachments,
+    ...desc.depthStencilAttachment === void 0 ? {} : {
+      depthStencilAttachment: {
+        view: rawTextureView(desc.depthStencilAttachment.view),
+        ...desc.depthStencilAttachment.depthClearValue === void 0 ? {} : { depthClearValue: desc.depthStencilAttachment.depthClearValue },
+        ...desc.depthStencilAttachment.depthLoadOp === void 0 ? {} : { depthLoadOp: desc.depthStencilAttachment.depthLoadOp },
+        ...desc.depthStencilAttachment.depthStoreOp === void 0 ? {} : { depthStoreOp: desc.depthStencilAttachment.depthStoreOp },
+        ...desc.depthStencilAttachment.depthReadOnly === void 0 ? {} : { depthReadOnly: desc.depthStencilAttachment.depthReadOnly },
+        ...desc.depthStencilAttachment.stencilClearValue === void 0 ? {} : { stencilClearValue: desc.depthStencilAttachment.stencilClearValue },
+        ...desc.depthStencilAttachment.stencilLoadOp === void 0 ? {} : { stencilLoadOp: desc.depthStencilAttachment.stencilLoadOp },
+        ...desc.depthStencilAttachment.stencilStoreOp === void 0 ? {} : { stencilStoreOp: desc.depthStencilAttachment.stencilStoreOp },
+        ...desc.depthStencilAttachment.stencilReadOnly === void 0 ? {} : { stencilReadOnly: desc.depthStencilAttachment.stencilReadOnly }
+      }
+    },
+    ...desc.occlusionQuerySet === void 0 ? {} : {
+      occlusionQuerySet: QUERY_SET_RAW_MAP.get(desc.occlusionQuerySet) ?? desc.occlusionQuerySet
+    },
+    ...desc.timestampWrites === void 0 ? {} : {
+      timestampWrites: {
+        querySet: QUERY_SET_RAW_MAP.get(desc.timestampWrites.querySet) ?? desc.timestampWrites.querySet,
+        ...desc.timestampWrites.beginningOfPassWriteIndex === void 0 ? {} : { beginningOfPassWriteIndex: desc.timestampWrites.beginningOfPassWriteIndex },
+        ...desc.timestampWrites.endOfPassWriteIndex === void 0 ? {} : { endOfPassWriteIndex: desc.timestampWrites.endOfPassWriteIndex }
+      }
+    },
+    ...desc.maxDrawCount === void 0 ? {} : { maxDrawCount: desc.maxDrawCount }
+  };
+}
+function mirrorRenderPipelineDescriptor(desc) {
+  const vertex = {
+    module: desc.vertex.module,
+    ...desc.vertex.buffers === void 0 ? {} : { buffers: Array.from(desc.vertex.buffers) },
+    ...desc.vertex.entryPoint === void 0 ? {} : { entryPoint: desc.vertex.entryPoint },
+    ...desc.vertex.constants === void 0 ? {} : { constants: desc.vertex.constants }
+  };
+  const fragment = desc.fragment === void 0 ? void 0 : {
+    module: desc.fragment.module,
+    targets: Array.from(desc.fragment.targets),
+    ...desc.fragment.entryPoint === void 0 ? {} : { entryPoint: desc.fragment.entryPoint },
+    ...desc.fragment.constants === void 0 ? {} : { constants: desc.fragment.constants }
+  };
+  return {
+    ...desc.label === void 0 ? {} : { label: desc.label },
+    layout: desc.layout === "auto" ? "auto" : desc.layout,
+    vertex,
+    ...desc.primitive === void 0 ? {} : { primitive: desc.primitive },
+    ...desc.depthStencil === void 0 ? {} : { depthStencil: desc.depthStencil },
+    ...desc.multisample === void 0 ? {} : { multisample: desc.multisample },
+    ...fragment === void 0 ? {} : { fragment }
+  };
+}
 function makeCommandEncoder(rawEncoder, caps, fireFeatureNotEnabled) {
   function mirrorComputePassDescriptor(desc) {
     if (desc === void 0) return void 0;
@@ -572,9 +596,8 @@ function makeCommandEncoder(rawEncoder, caps, fireFeatureNotEnabled) {
     beginRenderPass(desc) {
       const state = ENCODER_STATE.get(enc);
       throwIfFinished(state);
-      const rawPass = rawEncoder.beginRenderPass(desc);
-      const occQs = desc.occlusionQuerySet;
-      const occlusionQuerySet = occQs === void 0 || occQs === null ? null : occQs;
+      const rawPass = rawEncoder.beginRenderPass(mirrorRenderPassDescriptor(desc));
+      const occlusionQuerySet = desc.occlusionQuerySet ?? null;
       const pass = makeRenderPassEncoder(rawPass, enc, occlusionQuerySet);
       if (state !== void 0) state.activePass = pass;
       return pass;
@@ -895,17 +918,18 @@ function makeQueue(rawQueue) {
   return {
     writeBuffer(buffer, bufferOffset, data, dataOffset, size) {
       const rawBuffer = BUFFER_RAW_MAP.get(buffer) ?? buffer;
-      const range = resolveBufferWriteRange(data, dataOffset, size);
       const bufferSize = typeof rawBuffer.size === "number" ? rawBuffer.size : Number.MAX_SAFE_INTEGER;
       if (bufferOffset % 4 !== 0) {
         return queueWriteBufferOutOfBounds({
           offset: bufferOffset,
-          byteLength: range?.byteSize ?? 0,
+          byteLength: data instanceof ArrayBuffer ? data.byteLength : data.byteLength,
           bufferSize
         });
       }
-      const writeSize = range?.byteSize ?? 0;
-      if (range === void 0 || bufferOffset + writeSize > bufferSize) {
+      const dataByteLength = data instanceof ArrayBuffer ? data.byteLength : data.byteLength;
+      const writeStart = dataOffset ?? 0;
+      const writeSize = size ?? dataByteLength - writeStart;
+      if (bufferOffset + writeSize > bufferSize) {
         return queueWriteBufferOutOfBounds({
           offset: bufferOffset,
           byteLength: writeSize,
@@ -918,15 +942,15 @@ function makeQueue(rawQueue) {
             rawBuffer,
             bufferOffset,
             data,
-            range.sourceOffset,
-            range.sourceSize
+            writeStart,
+            size
           );
         } else if (dataOffset !== void 0) {
           rawQueue.writeBuffer(
             rawBuffer,
             bufferOffset,
             data,
-            range.sourceOffset
+            writeStart
           );
         } else {
           rawQueue.writeBuffer(rawBuffer, bufferOffset, data);
@@ -964,8 +988,14 @@ function makeQueue(rawQueue) {
     },
     writeTexture(destination, data, dataLayout, size) {
       try {
+        const rawDestination = {
+          texture: destination.texture
+        };
+        if (destination.mipLevel !== void 0) rawDestination.mipLevel = destination.mipLevel;
+        if (destination.origin !== void 0) rawDestination.origin = destination.origin;
+        if (destination.aspect !== void 0) rawDestination.aspect = destination.aspect;
         rawQueue.writeTexture(
-          destination,
+          rawDestination,
           data,
           dataLayout,
           size
@@ -984,7 +1014,18 @@ function makeQueue(rawQueue) {
     },
     copyExternalImageToTexture(source, destination, copySize) {
       try {
-        rawQueue.copyExternalImageToTexture(source, destination, copySize);
+        rawQueue.copyExternalImageToTexture(
+          source,
+          {
+            texture: destination.texture,
+            ...destination.mipLevel === void 0 ? {} : { mipLevel: destination.mipLevel },
+            ...destination.origin === void 0 ? {} : { origin: destination.origin },
+            ...destination.aspect === void 0 ? {} : { aspect: destination.aspect },
+            ...destination.colorSpace === void 0 ? {} : { colorSpace: destination.colorSpace },
+            ...destination.premultipliedAlpha === void 0 ? {} : { premultipliedAlpha: destination.premultipliedAlpha }
+          },
+          copySize
+        );
         return ok(void 0);
       } catch (e) {
         const message = e instanceof Error ? e.message : String(e);
@@ -1130,7 +1171,9 @@ function makeRhiDevice(rawDevice) {
         const rawView = rawTexture.createView(
           mirror(desc, TEXTURE_VIEW_KEYS)
         );
-        return ok(rawView);
+        const handle = rawView;
+        TEXTURE_VIEW_RAW_MAP.set(handle, rawView);
+        return ok(handle);
       } catch (e) {
         const message = e instanceof Error ? e.message : String(e);
         return err(
@@ -1213,9 +1256,7 @@ function makeRhiDevice(rawDevice) {
     },
     createRenderPipeline(desc) {
       try {
-        const out = rawDevice.createRenderPipeline(
-          mirror(desc, RPP_KEYS)
-        );
+        const out = rawDevice.createRenderPipeline(mirrorRenderPipelineDescriptor(desc));
         return ok(out);
       } catch (e) {
         const message = e instanceof Error ? e.message : String(e);
@@ -1663,8 +1704,8 @@ async function requestAdapter(opts, _compatibleSurface) {
   let adapter;
   try {
     adapter = await ambient.requestAdapter(opts);
-  } catch {
-    return adapterUnavailable();
+  } catch (cause) {
+    return requestAdapterFailed(cause);
   }
   if (adapter === null) {
     return adapterUnavailable();