@forgeax/engine-rhi 0.1.4 → 0.1.6

package/package.json

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

package/src/__tests__/descriptor-mirror.test-d.ts

@@ -34,13 +34,17 @@ import type {
   BindGroupLayoutDescriptor,
   BufferDescriptor,
   CommandEncoderDescriptor,
+  PipelineLayout,
   RenderPassColorAttachment,
   RenderPassDepthStencilAttachment,
   RenderPassDescriptor,
   RenderPassTimestampWrites,
   RenderPipelineDescriptor,
+  RenderPipelineFragmentState,
+  RenderPipelineVertexState,
   SamplerDescriptor,
   TextureDescriptor,
+  TextureFormat,
   TextureView,
 } from '../index';
 
@@ -140,18 +144,31 @@ describe('MVP-1.1 - 5 descriptors mirror @webgpu/types', () => {
       | 'multisample'
       | 'fragment';
     expectTypeOf<keyof RenderPipelineDescriptor>().toEqualTypeOf<RppKeys>();
-    expectTypeOf<ValueOf<RenderPipelineDescriptor, 'vertex'>>().toEqualTypeOf<
-      ValueOf<GPURenderPipelineDescriptor, 'vertex'>
-    >();
-    expectTypeOf<ValueOf<RenderPipelineDescriptor, 'fragment'>>().toEqualTypeOf<
-      ValueOf<GPURenderPipelineDescriptor, 'fragment'>
-    >();
+    expectTypeOf<
+      ValueOf<RenderPipelineDescriptor, 'vertex'>
+    >().toEqualTypeOf<RenderPipelineVertexState>();
+    expectTypeOf<
+      ValueOf<RenderPipelineDescriptor, 'fragment'>
+    >().toEqualTypeOf<RenderPipelineFragmentState>();
     expectTypeOf<ValueOf<RenderPipelineDescriptor, 'layout'>>().toEqualTypeOf<
-      ValueOf<GPURenderPipelineDescriptor, 'layout'>
+      'auto' | PipelineLayout
     >();
   });
 });
 
+describe('M4 RHI descriptor mirror', () => {
+  it('uses the spec TextureFormat union for texture descriptors', () => {
+    expectTypeOf<NonNullable<TextureDescriptor['format']>>().toEqualTypeOf<TextureFormat>();
+    const invalid: TextureDescriptor = {
+      // @ts-expect-error -- RHI descriptors reject arbitrary format strings.
+      format: 'not-a-texture-format',
+      size: { width: 1, height: 1 },
+      usage: 0,
+    };
+    void invalid;
+  });
+});
+
 // w8: 4 new descriptors (D-S5) - field NAMES align byte-for-byte with spec;
 // the `view` field TYPE is tightened to `Texture` (spec has
 // `GPUTexture | GPUTextureView`).

package/src/__tests__/queue-writes.test-d.ts

@@ -18,7 +18,7 @@
 //       dataLayout is Pick<GPUTexelCopyBufferLayout, ...>.
 //   (b) copyExternalImageToTexture(source, destination, copySize) where:
 //       source is Pick<GPUCopyExternalImageSourceInfo, ...> (spec rename);
-//       destination is Pick<GPUCopyExternalImageDestInfo, ...> (spec rename).
+//       destination is the opaque-handle ExternalImageTextureDestination.
 //   (c) r12-lint Pick<GPU*Descriptor count >= 20 follow-on (verified by w22
 //       gate, not this test-d).
 //
@@ -30,7 +30,16 @@
 /// <reference types="@webgpu/types" />
 
 import { describe, expectTypeOf, it } from 'vitest';
-import type { Buffer, Result, RhiError, RhiQueue, Texture, TextureView } from '../index';
+import type {
+  Buffer,
+  ExternalImageTextureDestination,
+  Result,
+  RhiError,
+  RhiQueue,
+  Texture,
+  TextureView,
+  TextureWriteDestination,
+} from '../index';
 
 /** Strict structural equality helper. */
 type Equals<X, Y> =
@@ -42,15 +51,11 @@ describe('AC-08 — RhiQueue.writeTexture Pick<spec> narrow', () => {
     expectTypeOf<Method>().toBeFunction();
   });
 
-  it('writeTexture destination param strictly equals Pick<GPUTexelCopyTextureInfo, ...> (no extra fields)', () => {
+  it('writeTexture destination keeps the opaque Texture resource boundary', () => {
     type DestParam = Parameters<RhiQueue['writeTexture']>[0];
-    type ExpectedShape = Pick<
-      GPUTexelCopyTextureInfo,
-      'texture' | 'mipLevel' | 'origin' | 'aspect'
-    >;
-    // Strict equality — DestParam has EXACTLY the four spec fields. AI users
-    // passing extra forgeax-invented fields trip TS2375 at call site;
-    // missing required `texture` field trips TS2741.
+    type ExpectedShape = TextureWriteDestination;
+    // Strict equality — the descriptor has exactly the four spec fields, but
+    // its resource is the RHI-opaque Texture rather than GPUTexture.
     type IsExact = Equals<DestParam, ExpectedShape>;
     expectTypeOf<IsExact>().toEqualTypeOf<true>();
   });
@@ -82,13 +87,9 @@ describe('AC-08 — RhiQueue.copyExternalImageToTexture Pick<spec> narrow + spec
     expectTypeOf<IsExact>().toEqualTypeOf<true>();
   });
 
-  it('destination param strictly equals Pick<GPUCopyExternalImageDestInfo, ...> (spec rename D-P5)', () => {
+  it('destination param keeps the RHI Texture opaque (D-P5)', () => {
     type DestParam = Parameters<RhiQueue['copyExternalImageToTexture']>[1];
-    type ExpectedShape = Pick<
-      GPUCopyExternalImageDestInfo,
-      'texture' | 'mipLevel' | 'origin' | 'aspect' | 'colorSpace' | 'premultipliedAlpha'
-    >;
-    type IsExact = Equals<DestParam, ExpectedShape>;
+    type IsExact = Equals<DestParam, ExternalImageTextureDestination>;
     expectTypeOf<IsExact>().toEqualTypeOf<true>();
   });
 

package/src/index.ts

@@ -56,7 +56,7 @@ import type {
   FilterMode,
   TextureFormat,
 } from '@forgeax/engine-types';
-import { err, ok, type Result, RhiError } from './errors';
+import type { Result, RhiError } from './errors';
 
 // ============================================================================
 // 14 opaque handles (MVP-1.3)
@@ -211,6 +211,25 @@ export interface Texture {
   readonly [RhiTextureBrand]: void;
 }
 
+/** RHI-owned destination for queue.writeTexture. The resource handle remains opaque. */
+export interface TextureWriteDestination {
+  readonly texture: Texture;
+  readonly mipLevel?: number | undefined;
+  readonly origin?: GPUOrigin3D | undefined;
+  readonly aspect?: GPUTextureAspect | undefined;
+}
+
+/** RHI-owned destination for queue.copyExternalImageToTexture. */
+export type ExternalImageTextureDestination = Omit<
+  Pick<
+    GPUCopyExternalImageDestInfo,
+    'texture' | 'mipLevel' | 'origin' | 'aspect' | 'colorSpace' | 'premultipliedAlpha'
+  >,
+  'texture'
+> & {
+  readonly texture: Texture;
+};
+
 declare const RhiTextureViewBrand: unique symbol;
 /** GPU texture view opaque handle. */
 export interface TextureView {
@@ -588,14 +607,36 @@ export type PipelineLayoutDescriptor = ExplicitUndefined<
   bindGroupLayouts: Iterable<BindGroupLayout>;
 };
 
-/** GPU render pipeline descriptor. Field set strictly matches
- *  GPURenderPipelineDescriptor. */
+/** GPU render pipeline vertex stage with an opaque forgeax shader module. */
+export type RenderPipelineVertexState = ExplicitUndefined<
+  Omit<GPUVertexState, 'module' | 'buffers'>
+> & {
+  module: ShaderModule;
+  buffers: NonNullable<GPUVertexState['buffers']>;
+};
+
+/** GPU render pipeline fragment stage with an opaque forgeax shader module. */
+export type RenderPipelineFragmentState = ExplicitUndefined<
+  Omit<GPUFragmentState, 'module' | 'targets'>
+> & {
+  module: ShaderModule;
+  targets: NonNullable<GPUFragmentState['targets']>;
+};
+
+/** GPU render pipeline descriptor with opaque forgeax layout and shader handles. */
 export type RenderPipelineDescriptor = ExplicitUndefined<
-  Pick<
-    GPURenderPipelineDescriptor,
-    'label' | 'layout' | 'vertex' | 'primitive' | 'depthStencil' | 'multisample' | 'fragment'
+  Omit<
+    Pick<
+      GPURenderPipelineDescriptor,
+      'label' | 'layout' | 'vertex' | 'primitive' | 'depthStencil' | 'multisample' | 'fragment'
+    >,
+    'layout' | 'vertex' | 'fragment'
   >
->;
+> & {
+  layout: 'auto' | PipelineLayout;
+  vertex: RenderPipelineVertexState;
+  fragment?: RenderPipelineFragmentState | undefined;
+};
 
 // ============================================================================
 // 4 new descriptors (feat-20260508-rhi-surface-completion w8 / D-S5,
@@ -1606,14 +1647,7 @@ export interface RhiDevice {
 /** GPU command queue - writeBuffer / submit + M5 writeTexture /
  *  copyExternalImageToTexture / onSubmittedWorkDone. */
 export interface RhiQueue {
-  /**
-   * Direct write to a buffer (POD + ArrayBufferView, math-free).
-   *
-   * For typed-array sources, dataOffset and size are element counts, matching
-   * GPUQueue.writeBuffer. For ArrayBuffer and DataView sources they are byte
-   * counts. Every backend and the debug tape normalize the selected source
-   * bytes through resolveBufferWriteRange before validation or recording.
-   */
+  /** Direct write to a buffer (POD + ArrayBufferView, math-free). */
   writeBuffer(
     buffer: Buffer,
     bufferOffset: number,
@@ -1643,7 +1677,7 @@ export interface RhiQueue {
    *   }
    */
   writeTexture(
-    destination: Pick<GPUTexelCopyTextureInfo, 'texture' | 'mipLevel' | 'origin' | 'aspect'>,
+    destination: TextureWriteDestination,
     data: ArrayBufferView | ArrayBuffer,
     dataLayout: Pick<GPUTexelCopyBufferLayout, 'offset' | 'bytesPerRow' | 'rowsPerImage'>,
     size: GPUExtent3DStrict,
@@ -1662,10 +1696,7 @@ export interface RhiQueue {
    */
   copyExternalImageToTexture(
     source: Pick<GPUCopyExternalImageSourceInfo, 'source' | 'origin' | 'flipY'>,
-    destination: Pick<
-      GPUCopyExternalImageDestInfo,
-      'texture' | 'mipLevel' | 'origin' | 'aspect' | 'colorSpace' | 'premultipliedAlpha'
-    >,
+    destination: ExternalImageTextureDestination,
     copySize: GPUExtent3DStrict,
   ): Result<void, RhiError>;
   /** Submit command buffers (single-use). */
@@ -1721,7 +1752,7 @@ export interface RhiCommandEncoder {
    * @example
    *   const pass = encoder.beginRenderPass({ colorAttachments: [{ ... }] });
    */
-  beginRenderPass(desc: GPURenderPassDescriptor): RhiRenderPassEncoder;
+  beginRenderPass(desc: RenderPassDescriptor): RhiRenderPassEncoder;
   /** Begin compute pass.
    *
    * Spec anchor: [@webgpu/types.GPUCommandEncoder.beginComputePass].
@@ -2156,157 +2187,6 @@ export { err, ok, RhiError, validateDrawArgs } from './errors';
 // re-export common descriptor-related aliases for single-entry consumption.
 export type { AddressMode, CompareFunction, FilterMode, TextureFormat };
 
-export interface Rgba16floatRenderTargetProbe {
-  readonly format: 'rgba16float';
-  readonly pixel: readonly [number, number, number, number];
-  readonly timestampQuery: boolean;
-}
-
-function halfToFloat(value: number): number {
-  const sign = (value & 0x8000) === 0 ? 1 : -1;
-  const exponent = (value >>> 10) & 0x1f;
-  const mantissa = value & 0x03ff;
-  if (exponent === 0) return sign * 2 ** -14 * (mantissa / 1024);
-  if (exponent === 0x1f) return mantissa === 0 ? sign * Number.POSITIVE_INFINITY : Number.NaN;
-  return sign * 2 ** (exponent - 15) * (1 + mantissa / 1024);
-}
-
-/** Execute an rgba16float attachment clear and texture-to-buffer readback on a live device. */
-export async function probeRgba16floatRenderTarget(
-  device: RhiDevice,
-): Promise<Result<Rgba16floatRenderTargetProbe, RhiError>> {
-  if (!device.caps.rgba16floatRenderable) {
-    return err(
-      new RhiError({
-        code: 'feature-not-enabled',
-        expected: 'device.caps.rgba16floatRenderable is true',
-        hint: 'select a device that can render rgba16float attachments',
-      }),
-    );
-  }
-  const texture = device.createTexture({
-    label: 'rgba16float-render-target-probe',
-    size: { width: 1, height: 1, depthOrArrayLayers: 1 },
-    mipLevelCount: 1,
-    sampleCount: 1,
-    dimension: '2d',
-    format: 'rgba16float',
-    usage: 0x10 | 0x01,
-    textureBindingViewDimension: undefined,
-    viewFormats: [],
-  });
-  if (!texture.ok) return texture;
-  const readback = device.createBuffer({
-    label: 'rgba16float-render-target-probe-readback',
-    size: 256,
-    usage: 0x01 | 0x08,
-    mappedAtCreation: false,
-  });
-  if (!readback.ok) {
-    device.destroyTexture(texture.value);
-    return readback;
-  }
-  const view = device.createTextureView(texture.value, {});
-  if (!view.ok) {
-    device.destroyBuffer(readback.value);
-    device.destroyTexture(texture.value);
-    return view;
-  }
-  const encoder = device.createCommandEncoder({ label: 'rgba16float-render-target-probe' });
-  if (!encoder.ok) {
-    device.destroyBuffer(readback.value);
-    device.destroyTexture(texture.value);
-    return encoder;
-  }
-  try {
-    const pass = encoder.value.beginRenderPass({
-      label: 'rgba16float-render-target-probe',
-      colorAttachments: [
-        {
-          view: view.value as unknown as GPUTextureView,
-          clearValue: { r: 0.25, g: 0.5, b: 0.75, a: 1 },
-          loadOp: 'clear',
-          storeOp: 'store',
-        },
-      ],
-    });
-    pass.end();
-    encoder.value.copyTextureToBuffer(
-      {
-        texture: texture.value as unknown as GPUTexture,
-        mipLevel: 0,
-        origin: { x: 0, y: 0, z: 0 },
-      },
-      {
-        buffer: readback.value as unknown as GPUBuffer,
-        offset: 0,
-        bytesPerRow: 256,
-        rowsPerImage: 1,
-      },
-      { width: 1, height: 1, depthOrArrayLayers: 1 },
-    );
-  } catch (cause) {
-    device.destroyBuffer(readback.value);
-    device.destroyTexture(texture.value);
-    return err(
-      new RhiError({
-        code: 'webgpu-runtime-error',
-        expected: 'rgba16float render pass and texture-to-buffer copy encode successfully',
-        hint: cause instanceof Error ? cause.message : String(cause),
-      }),
-    );
-  }
-  const command = encoder.value.finish();
-  if (!command.ok) {
-    device.destroyBuffer(readback.value);
-    device.destroyTexture(texture.value);
-    return command;
-  }
-  const submitted = device.queue.submit([command.value]);
-  if (!submitted.ok) {
-    device.destroyBuffer(readback.value);
-    device.destroyTexture(texture.value);
-    return submitted;
-  }
-  try {
-    await device.queue.onSubmittedWorkDone();
-  } catch (cause) {
-    device.destroyBuffer(readback.value);
-    device.destroyTexture(texture.value);
-    return err(
-      new RhiError({
-        code: 'webgpu-runtime-error',
-        expected: 'rgba16float probe submission completes',
-        hint: cause instanceof Error ? cause.message : String(cause),
-      }),
-    );
-  }
-  const mapped = await readback.value.mapAsync(0x01);
-  if (!mapped.ok) {
-    device.destroyBuffer(readback.value);
-    device.destroyTexture(texture.value);
-    return mapped;
-  }
-  const range = mapped.value.getMappedRange(0, 8);
-  if (!range.ok) {
-    mapped.value.unmap();
-    device.destroyBuffer(readback.value);
-    device.destroyTexture(texture.value);
-    return range;
-  }
-  const words = new Uint16Array(range.value.slice(0));
-  const pixel = [
-    halfToFloat(words[0] ?? 0),
-    halfToFloat(words[1] ?? 0),
-    halfToFloat(words[2] ?? 0),
-    halfToFloat(words[3] ?? 0),
-  ] as const;
-  mapped.value.unmap();
-  device.destroyBuffer(readback.value);
-  device.destroyTexture(texture.value);
-  return ok({ format: 'rgba16float', pixel, timestampQuery: device.caps.timestampQuery });
-}
-
 // ============================================================================
 // Descriptor builder helpers (feat-20260612-point-light-shadows-urp-hdrp M0)
 // ============================================================================
@@ -2361,8 +2241,6 @@ export function comparisonSamplerDescriptor(): SamplerDescriptor {
   };
 }
 
-export { type BufferWriteRange, resolveBufferWriteRange } from './queue-writes';
-
 /**
  * Build a TextureViewDescriptor to view a single cube layer + face as a 2D
  * depth attachment during shadow-caster rendering.

package/dist/__tests__/queue-writes.unit.test.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=queue-writes.unit.test.d.ts.map

package/dist/__tests__/queue-writes.unit.test.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"queue-writes.unit.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/queue-writes.unit.test.ts"],"names":[],"mappings":""}

package/dist/queue-writes.d.ts

@@ -1,20 +0,0 @@
-/**
- * Resolve the source range of a queue.writeBuffer call.
- *
- * WebGPU defines dataOffset and size in elements for typed-array sources, but
- * in bytes for ArrayBuffer and DataView sources. Keeping that conversion in
- * the shared RHI package makes the browser, native, and debug paths agree.
- */
-export interface BufferWriteRange {
-    readonly sourceOffset: number;
-    readonly sourceSize: number;
-    readonly byteOffset: number;
-    readonly byteSize: number;
-    readonly bytes: Uint8Array;
-}
-/**
- * Return the exact source bytes selected by a queue.writeBuffer range.
- * Undefined means the supplied element range is invalid.
- */
-export declare function resolveBufferWriteRange(data: ArrayBufferView | ArrayBuffer, dataOffset?: number, size?: number): BufferWriteRange | undefined;
-//# sourceMappingURL=queue-writes.d.ts.map

package/dist/queue-writes.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"queue-writes.d.ts","sourceRoot":"","sources":["../src/queue-writes.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;CAC5B;AAeD;;;GAGG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,eAAe,GAAG,WAAW,EACnC,UAAU,CAAC,EAAE,MAAM,EACnB,IAAI,CAAC,EAAE,MAAM,GACZ,gBAAgB,GAAG,SAAS,CAyB9B"}

package/src/__tests__/queue-writes.unit.test.ts

@@ -1,30 +0,0 @@
-import { describe, expect, it } from 'vitest';
-
-import { resolveBufferWriteRange } from '../queue-writes';
-
-describe('resolveBufferWriteRange', () => {
-  it('uses typed-array elements and preserves a non-zero view byteOffset', () => {
-    const source = new Float32Array([10, 20, 30, 40, 50]);
-    const view = source.subarray(1);
-    const range = resolveBufferWriteRange(view, 1, 2);
-
-    expect(range).toBeDefined();
-    expect(range?.byteOffset).toBe(4);
-    expect(range?.byteSize).toBe(8);
-    expect([...((range?.bytes ?? new Uint8Array()) as Uint8Array)]).toEqual([
-      ...new Uint8Array(view.buffer, view.byteOffset + 4, 8),
-    ]);
-  });
-
-  it('uses bytes for ArrayBuffer and DataView sources', () => {
-    const source = new ArrayBuffer(8);
-    const view = new DataView(source, 2, 4);
-    expect(resolveBufferWriteRange(source, 2, 3)?.byteSize).toBe(3);
-    expect(resolveBufferWriteRange(view, 1, 2)?.byteOffset).toBe(1);
-    expect(resolveBufferWriteRange(view, 1, 2)?.byteSize).toBe(2);
-  });
-
-  it('rejects an element range outside the source view', () => {
-    expect(resolveBufferWriteRange(new Float32Array(2), 1, 2)).toBeUndefined();
-  });
-});

package/src/queue-writes.ts

@@ -1,62 +0,0 @@
-/**
- * Resolve the source range of a queue.writeBuffer call.
- *
- * WebGPU defines dataOffset and size in elements for typed-array sources, but
- * in bytes for ArrayBuffer and DataView sources. Keeping that conversion in
- * the shared RHI package makes the browser, native, and debug paths agree.
- */
-export interface BufferWriteRange {
-  readonly sourceOffset: number;
-  readonly sourceSize: number;
-  readonly byteOffset: number;
-  readonly byteSize: number;
-  readonly bytes: Uint8Array;
-}
-
-function elementSize(data: ArrayBufferView | ArrayBuffer): number {
-  if (data instanceof ArrayBuffer) return 1;
-  const bytesPerElement = (data as ArrayBufferView & { BYTES_PER_ELEMENT?: number })
-    .BYTES_PER_ELEMENT;
-  return typeof bytesPerElement === 'number' && bytesPerElement > 0 ? bytesPerElement : 1;
-}
-
-function sourceByteView(data: ArrayBufferView | ArrayBuffer): Uint8Array {
-  return data instanceof ArrayBuffer
-    ? new Uint8Array(data)
-    : new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
-}
-
-/**
- * Return the exact source bytes selected by a queue.writeBuffer range.
- * Undefined means the supplied element range is invalid.
- */
-export function resolveBufferWriteRange(
-  data: ArrayBufferView | ArrayBuffer,
-  dataOffset?: number,
-  size?: number,
-): BufferWriteRange | undefined {
-  const bytes = sourceByteView(data);
-  const bytesPerElement = elementSize(data);
-  const elementCount = bytes.byteLength / bytesPerElement;
-  const sourceOffset = dataOffset ?? 0;
-  const sourceSize = size ?? elementCount - sourceOffset;
-  if (
-    !Number.isInteger(sourceOffset) ||
-    !Number.isInteger(sourceSize) ||
-    sourceOffset < 0 ||
-    sourceSize < 0 ||
-    sourceOffset > elementCount ||
-    sourceSize > elementCount - sourceOffset
-  ) {
-    return undefined;
-  }
-  const byteOffset = sourceOffset * bytesPerElement;
-  const byteSize = sourceSize * bytesPerElement;
-  return {
-    sourceOffset,
-    sourceSize,
-    byteOffset,
-    byteSize,
-    bytes: bytes.subarray(byteOffset, byteOffset + byteSize),
-  };
-}