@forgeax/engine-rhi 0.1.20 → 0.1.21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgeax/engine-rhi",
-  "version": "0.1.20",
+  "version": "0.1.21",
   "private": false,
   "type": "module",
   "license": "Apache-2.0",
@@ -26,7 +26,7 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@forgeax/engine-types": "0.1.20",
+    "@forgeax/engine-types": "0.1.21",
     "@webgpu/types": "^0.1.71"
   },
   "forgeax": {

package/src/__tests__/command-encoder-spec-alignment.test-d.ts

@@ -2,7 +2,8 @@
 // `@webgpu/types` GPUCommandEncoder (research F-1 / plan-strategy D-S4).
 //
 // Asserts (will be RED until w3 lands the impl):
-// - 12 spec methods (9 direct + 3 GPUDebugCommandsMixin) exist on RhiCommandEncoder
+// - 12 spec methods (9 direct + 3 GPUDebugCommandsMixin) plus one ForgeaX
+//   compound operation exist on RhiCommandEncoder
 // - `copyBufferToBuffer` exposes both spec overloads (3-arg shorthand + 5-arg full form)
 // - `finish()` returns Result<CommandBuffer, RhiError>
 // - method NAMES align byte-for-byte with `@webgpu/types` GPUCommandEncoder
@@ -14,13 +15,14 @@ import { describe, expectTypeOf, it } from 'vitest';
 import type {
   Buffer,
   CommandBuffer,
+  ComputePassDescriptor,
   QuerySet,
   Result,
   RhiCommandEncoder,
   RhiError,
 } from '../index';
 
-describe('w2 - RhiCommandEncoder spec method set (12 methods)', () => {
+describe('w2 - RhiCommandEncoder spec method set (12 spec + 1 compound)', () => {
   it('exposes beginRenderPass(desc): RhiRenderPassEncoder', () => {
     expectTypeOf<RhiCommandEncoder['beginRenderPass']>().toBeFunction();
   });
@@ -29,6 +31,11 @@ describe('w2 - RhiCommandEncoder spec method set (12 methods)', () => {
     expectTypeOf<RhiCommandEncoder['beginComputePass']>().toBeFunction();
   });
 
+  it('exposes encodeEmptyComputePass(desc): void as a ForgeaX compound operation', () => {
+    type Expected = (desc: ComputePassDescriptor) => void;
+    expectTypeOf<RhiCommandEncoder['encodeEmptyComputePass']>().toMatchTypeOf<Expected>();
+  });
+
   it('exposes copyBufferToBuffer (5-arg full form per spec)', () => {
     // 5-arg overload must be callable (research F-1 finding):
     //   copyBufferToBuffer(src, srcOffset, dst, dstOffset, size): void
@@ -104,14 +111,4 @@ describe('w2 - RhiCommandEncoder spec method set (12 methods)', () => {
       Result<CommandBuffer, RhiError>
     >();
   });
-
-  // w38 (M5 / K-3): writeTimestamp on the CommandEncoder entry only.
-  // CPE/RPE inside-pass timestamp writes are deferred to
-  // feat-future-rhi-perf-timestamp-pass per K-3 decision.
-  it('exposes writeTimestamp(querySet, queryIndex): void (K-3 CommandEncoder-only)', () => {
-    type Method = RhiCommandEncoder['writeTimestamp'];
-    expectTypeOf<Method>().toBeFunction();
-    type Expected = (querySet: QuerySet, queryIndex: number) => void;
-    expectTypeOf<Expected>().toMatchTypeOf<Method>();
-  });
 });

package/src/index.ts

@@ -211,6 +211,22 @@ export interface Texture {
   readonly [RhiTextureBrand]: void;
 }
 
+/** RHI-safe source for a texture-to-buffer copy. */
+export interface TextureCopySource {
+  readonly texture: Texture;
+  readonly mipLevel?: number | undefined;
+  readonly origin?: GPUOrigin3D | undefined;
+  readonly aspect?: GPUTextureAspect | undefined;
+}
+
+/** RHI-safe destination for a texture-to-buffer copy. */
+export interface BufferCopyDestination {
+  readonly buffer: Buffer;
+  readonly offset?: number | undefined;
+  readonly bytesPerRow: number;
+  readonly rowsPerImage?: number | undefined;
+}
+
 /** RHI-owned destination for queue.writeTexture. The resource handle remains opaque. */
 export interface TextureWriteDestination {
   readonly texture: Texture;
@@ -1078,7 +1094,7 @@ export interface RhiCaps {
    *   spec minimum = 4, defaults to 8 on mainstream backends.
    *   HDRP deferred pipeline requires >= 4 (3 g-buffer RT + 1 depth);
    *   installPipeline checks this cap at install time and throws
-   *   `hdrp-deferred-caps-insufficient` on violation (charter P3).
+   *   a structured Standard transport refusal on violation (charter P3).
    * @note add-only minor (feat-20260612-hdrp-deferred-shading-learn-render-5-8
    *   M1 / w5); no existing field is modified.
    */
@@ -1755,7 +1771,8 @@ export interface RhiQueue {
 /** GPU command encoder - records render / compute passes + resource copies.
  *
  * Method NAMES align byte-for-byte with `@webgpu/types.GPUCommandEncoder` +
- * `GPUDebugCommandsMixin` (research F-1 / D-S4). 12 methods total:
+ * `GPUDebugCommandsMixin` (research F-1 / D-S4). 12 spec methods plus one
+ * ForgeaX compound operation:
  *   - 9 direct: beginRenderPass / beginComputePass / copyBufferToBuffer /
  *               copyBufferToTexture / copyTextureToBuffer / copyTextureToTexture /
  *               clearBuffer / resolveQuerySet / finish
@@ -1786,6 +1803,17 @@ export interface RhiCommandEncoder {
    *   const pass = encoder.beginComputePass();
    */
   beginComputePass(desc?: ComputePassDescriptor | undefined): RhiComputePassEncoder;
+  /**
+   * Record an empty timestamp-enabled compute pass and close it immediately.
+   *
+   * This is a ForgeaX compound recording operation equivalent to
+   * `const pass = encoder.beginComputePass(desc); pass.end()`; it is not a
+   * native `GPUCommandEncoder` method and does not write a timestamp directly.
+   *
+   * @throws RhiError code === 'command-encoder-finished' when invoked on a
+   *   finished encoder.
+   */
+  encodeEmptyComputePass(desc: ComputePassDescriptor): void;
   /** Copy a sub-region of a Buffer to another Buffer (5-arg full form).
    *
    * Spec anchor: [@webgpu/types.GPUCommandEncoder.copyBufferToBuffer].
@@ -1836,6 +1864,18 @@ export interface RhiCommandEncoder {
     destination: GPUTexelCopyBufferInfo,
     copySize: GPUExtent3DStrict,
   ): void;
+  /** Opaque RHI handle form for renderer-owned readback. */
+  copyTextureToBuffer(
+    source: TextureCopySource,
+    destination: BufferCopyDestination,
+    copySize: GPUExtent3DStrict,
+  ): void;
+  /** Union form for decorators that transparently forward either handle form. */
+  copyTextureToBuffer(
+    source: GPUTexelCopyTextureInfo | TextureCopySource,
+    destination: GPUTexelCopyBufferInfo | BufferCopyDestination,
+    copySize: GPUExtent3DStrict,
+  ): void;
   /** Copy a Texture sub-region to a Texture sub-region.
    *
    * Spec anchor: [@webgpu/types.GPUCommandEncoder.copyTextureToTexture].
@@ -1882,32 +1922,6 @@ export interface RhiCommandEncoder {
     destination: Buffer,
     destinationOffset: number,
   ): Result<void, RhiError>;
-  /**
-   * Write a u64 GPU timestamp into a timestamp QuerySet at queryIndex.
-   *
-   * Spec anchor: W3C WebGPU §queries / [@webgpu/types.GPUCommandEncoder].
-   * dawn `TimestampOnCommandEncoder` reference (research §2.4): the entry is
-   * gated on the `'timestamp-query'` device feature. K-3 decision
-   * (plan-strategy §2): the forgeax form ships ONLY this CommandEncoder
-   * entry; CPE/RPE inside-pass timestamp writes are deferred to
-   * `feat-future-rhi-perf-timestamp-pass` (additive minor evolution).
-   *
-   * Return shape: `void` per spec literal alignment. When
-   * `caps.timestampQuery === false` the shim fans out a structured
-   * `'feature-not-enabled'` RhiError through the engine `onError` channel
-   * (the forgeax form keeps the spec void return; AI users probe the gate
-   * via `device.caps.timestampQuery` BEFORE calling this entry, charter
-   * proposition 4 explicit failure forward-reachable).
-   *
-   * @throws RhiError code === 'command-encoder-finished' when invoked on a finished encoder (dual-channel; see beginRenderPass JSDoc for the recovery pattern).
-   * @example
-   *   if (device.caps.timestampQuery) {
-   *     encoder.writeTimestamp(qs, 0);
-   *     // ... draw / dispatch ...
-   *     encoder.writeTimestamp(qs, 1);
-   *   }
-   */
-  writeTimestamp(querySet: QuerySet, queryIndex: number): void;
   /** Push a labelled debug group (GPUDebugCommandsMixin).
    *
    * Spec anchor: [@webgpu/types.GPUDebugCommandsMixin.pushDebugGroup].