@forgeax/engine-render 0.1.2

package/src/__tests__/gpu-scene.unit.test.ts

@@ -0,0 +1,161 @@
+import type { Buffer, Result, RhiError } from '@forgeax/engine-rhi';
+import { RhiNullCommandEncoder, RhiNullDevice, RhiNullQueue } from '@forgeax/engine-rhi-null';
+import { describe, expect, it } from 'vitest';
+import { GpuScene } from '../gpu-scene';
+import { GPU_SCENE_LAYOUTS, gpuSceneFieldOffset } from '../gpu-scene-schema';
+import { RenderSceneProjection } from '../render-scene-projection';
+import type { MaterialSnapshot, RenderableSnapshot } from '../render-system-extract';
+
+interface WriteRecord {
+  readonly offset: number;
+  readonly bytes: Uint8Array;
+}
+
+class RecordingQueue extends RhiNullQueue {
+  readonly writes: WriteRecord[] = [];
+
+  override writeBuffer(
+    buffer: Buffer,
+    bufferOffset: number,
+    data: ArrayBufferView | ArrayBuffer,
+    dataOffset?: number,
+    size?: number,
+  ): Result<void, RhiError> {
+    const source =
+      data instanceof ArrayBuffer
+        ? new Uint8Array(data)
+        : new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+    const start = dataOffset ?? 0;
+    const length = size ?? source.byteLength - start;
+    this.writes.push({ offset: bufferOffset, bytes: source.slice(start, start + length) });
+    return super.writeBuffer(buffer, bufferOffset, data, dataOffset, size);
+  }
+}
+
+const material = {
+  baseColor: new Float32Array([0.25, 0.5, 0.75]),
+  metallic: 0.2,
+  roughness: 0.8,
+  materialHandle: 17,
+} as MaterialSnapshot;
+
+function snapshot(entityKey: number, translationX = 0): RenderableSnapshot {
+  const world = new Float32Array(16);
+  world[0] = 1;
+  world[5] = 1;
+  world[10] = 1;
+  world[15] = 1;
+  world[12] = translationX;
+  return {
+    assetHandle: 9,
+    transform: { world },
+    localAabb: new Float32Array([-1, -1, -1, 1, 1, 1]),
+    material,
+    materials: [material],
+    materialBindingSources: ['engine-default'],
+    worldId: 0,
+    entityKey,
+  };
+}
+
+function createDevice(queue: RecordingQueue): RhiNullDevice {
+  return new RhiNullDevice(
+    queue,
+    (bookkeeper, device) => new RhiNullCommandEncoder(bookkeeper, device),
+  );
+}
+
+describe('GpuScene', () => {
+  it('uploads only coalesced dirty ranges and performs no upload on no-change', () => {
+    const queue = new RecordingQueue();
+    const created = GpuScene.create(createDevice(queue), 4).unwrap();
+    expect(created.status).toBe('available');
+    if (created.status !== 'available') return;
+    const projection = new RenderSceneProjection();
+
+    const initial = projection.apply([
+      { kind: 'create', snapshot: snapshot(0) },
+      { kind: 'create', snapshot: snapshot(1) },
+      { kind: 'create', snapshot: snapshot(2) },
+    ]);
+    expect(created.scene.sync(projection, initial).unwrap()).toMatchObject({
+      ranges: 5,
+      bytes: 1344,
+    });
+    const writesAfterInitial = queue.writes.length;
+
+    created.scene.sync(projection, projection.apply([])).unwrap();
+    expect(queue.writes).toHaveLength(writesAfterInitial);
+
+    const dirty = projection.apply([
+      { kind: 'update-transform', worldId: 0, entityKey: 0, world: snapshot(0, 4).transform.world },
+      { kind: 'update-transform', worldId: 0, entityKey: 2, world: snapshot(2, 8).transform.world },
+    ]);
+    // Transform-only Scene Fact deltas touch only the transform table; the
+    // primitive/instance/draw/material rows stay resident.
+    expect(created.scene.sync(projection, dirty).unwrap()).toMatchObject({
+      ranges: 2,
+      bytes: 256,
+    });
+    expect(queue.writes.length).toBeGreaterThan(writesAfterInitial);
+    expect(created.scene.inspect()).toMatchObject({ noChangeFrames: 1 });
+  });
+
+  it('clears removed slots, grows without losing the CPU mirror, and rebuilds a fresh table', () => {
+    const queue = new RecordingQueue();
+    const created = GpuScene.create(createDevice(queue), 2).unwrap();
+    if (created.status !== 'available') return;
+    const projection = new RenderSceneProjection();
+    created.scene
+      .sync(
+        projection,
+        projection.apply([
+          { kind: 'create', snapshot: snapshot(0) },
+          { kind: 'create', snapshot: snapshot(1) },
+          { kind: 'create', snapshot: snapshot(2) },
+        ]),
+      )
+      .unwrap();
+    expect(created.scene.inspect()).toMatchObject({ capacity: 8, capacityGrows: 1 });
+
+    const beforeRemove = queue.writes.length;
+    created.scene
+      .sync(projection, projection.apply([{ kind: 'remove', worldId: 0, entityKey: 1 }]))
+      .unwrap();
+    expect(queue.writes.slice(beforeRemove)).toHaveLength(5);
+    expect(queue.writes.at(-1)?.bytes.every((value) => value === 0)).toBe(true);
+    expect(created.scene.inspect().clearedSlots).toBe(1);
+
+    const rebuilt = GpuScene.create(createDevice(new RecordingQueue()), 1).unwrap();
+    if (rebuilt.status !== 'available') return;
+    expect(rebuilt.scene.rebuild(projection).unwrap()).toMatchObject({ ranges: 5 });
+    expect(rebuilt.scene.inspect()).toMatchObject({ capacity: 4, fullRebuilds: 1 });
+  });
+
+  it('resets previous transform when a slot generation is recreated', () => {
+    const queue = new RecordingQueue();
+    const created = GpuScene.create(createDevice(queue), 1).unwrap();
+    if (created.status !== 'available') return;
+    const projection = new RenderSceneProjection();
+    created.scene
+      .sync(projection, projection.apply([{ kind: 'create', snapshot: snapshot(1, 2) }]))
+      .unwrap();
+
+    created.scene
+      .sync(
+        projection,
+        projection.apply([
+          { kind: 'remove', worldId: 0, entityKey: 1 },
+          { kind: 'create', snapshot: snapshot(1, 9) },
+        ]),
+      )
+      .unwrap();
+
+    const transformWrite = queue.writes.at(-3);
+    expect(transformWrite).toBeDefined();
+    if (transformWrite === undefined) return;
+    const previousTranslation =
+      gpuSceneFieldOffset(GPU_SCENE_LAYOUTS.transform, 'previousWorld') + 12 * 4;
+    expect(new DataView(transformWrite.bytes.buffer).getFloat32(previousTranslation, true)).toBe(9);
+  });
+});

package/src/__tests__/hdrp-pipeline.unit.test.ts

@@ -0,0 +1,100 @@
+import { readFileSync } from 'node:fs';
+import type { RhiDevice } from '@forgeax/engine-rhi';
+import { describe, expect, it } from 'vitest';
+import { isGpuMembershipProducerAvailable } from '../hdrp-pipeline';
+import { createMembershipTiming } from '../record/membership-timing';
+import { resolvePostColorDomainContract } from '../render-pipeline';
+
+const hdrpSource = readFileSync(new URL('../hdrp-pipeline.ts', import.meta.url), 'utf8');
+const frameSource = readFileSync(new URL('../record/frame.ts', import.meta.url), 'utf8');
+const lightingSource = readFileSync(
+  new URL('../record/frame-lighting.ts', import.meta.url),
+  'utf8',
+);
+const graphOwnerSource = readFileSync(
+  new URL('../record/typed-frame-graph.ts', import.meta.url),
+  'utf8',
+);
+const timingSource = readFileSync(
+  new URL('../record/membership-timing.ts', import.meta.url),
+  'utf8',
+);
+
+describe('HDRP post color-domain order', () => {
+  it('selects the GPU membership producer only for a complete compute carrier', () => {
+    expect(isGpuMembershipProducerAvailable(undefined, {}, {})).toBe(false);
+    expect(isGpuMembershipProducerAvailable({ compute: false }, {}, {})).toBe(false);
+    expect(isGpuMembershipProducerAvailable({ compute: true }, null, {})).toBe(false);
+    expect(isGpuMembershipProducerAvailable({ compute: true }, {}, null)).toBe(false);
+    expect(isGpuMembershipProducerAvailable({ compute: true }, {}, {})).toBe(true);
+  });
+
+  it('keeps transparent and bloom work in linear HDR before tone output', () => {
+    const stages = resolvePostColorDomainContract('hdrp');
+    expect(stages).toContainEqual(['transparent-blend', 'linear-hdr', 'linear-hdr']);
+    expect(stages).toContainEqual(['bloom', 'linear-hdr', 'linear-hdr']);
+    expect(stages).toContainEqual(['tone', 'linear-hdr', 'linear-ldr']);
+    expect(stages).toContainEqual(['output', 'linear-ldr', 'display-encoded']);
+    expect(stages.findIndex(([name]) => name === 'tone')).toBeGreaterThan(
+      stages.findIndex(([name]) => name === 'bloom'),
+    );
+  });
+
+  it('keeps the real HDRP producer and record owner as one provenance chain', () => {
+    expect(hdrpSource).toContain("graph.addComputePass('cluster-membership-producer'");
+    expect(hdrpSource).toContain('isGpuMembershipProducerAvailable(');
+    expect(frameSource).toContain('internals.device.caps?.compute === true &&');
+    expect(hdrpSource).toContain(
+      'begin: (frame) => frame.runtime.membershipTiming?.beforeMembership() ?? {}',
+    );
+    expect(hdrpSource).toContain('frame.runtime.membershipTiming?.markTimestampPassFailed(');
+    expect(hdrpSource).toContain(
+      'after: (frame) => frame.runtime.membershipTiming?.afterMembership(frame.encoder)',
+    );
+    expect(hdrpSource).toContain('pass.dispatchWorkgroups(');
+    expect(lightingSource).toContain('recordGpuMembershipSource({');
+    expect(lightingSource).toContain('lightCount: effectiveLightCount');
+    expect(lightingSource).toContain('grid: { x: gridX, y: gridY, z: gridZ }');
+    expect(lightingSource).toContain('overflow,');
+    expect(graphOwnerSource).toContain('markEncodeFinished()');
+    expect(graphOwnerSource).toContain('markSubmitStarted()');
+    expect(graphOwnerSource).toContain('markSubmitted(command)');
+    expect(timingSource).toContain("actualProducer: 'gpu'");
+    expect(timingSource).toContain('beginningOfPassWriteIndex: 0');
+    expect(timingSource).toContain('endOfPassWriteIndex: 1');
+    expect(timingSource).not.toContain('encoder.writeTimestamp');
+    expect(timingSource).toContain('membership: {');
+    expect(timingSource).toContain('dispatchId: capture.dispatchId ?? null');
+  });
+
+  it('keeps the null/refusal route out of the accepted GPU contract', () => {
+    const timing = createMembershipTiming(
+      {
+        caps: {
+          backendKind: 'null',
+          compute: true,
+          timestampQuery: false,
+          timestampPeriodNanoseconds: null,
+        },
+      } as unknown as RhiDevice,
+      { mode: 'gpu' },
+    );
+    const result = timing.start();
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.code).toBe('timestamp-query-unsupported');
+      expect(result.error.expected).toContain('timestampQuery');
+      expect(result.error.hint).toEqual(expect.any(String));
+      expect(result.error.detail).toEqual(expect.any(String));
+    }
+  });
+
+  it('requires the report contract to carry finite positive GPU provenance', () => {
+    expect(timingSource).toContain("rawUnit: 'ticks'");
+    expect(timingSource).toContain('end <= begin');
+    expect(timingSource).toContain('Number.isFinite(durationNanoseconds)');
+    expect(timingSource).toContain('source === undefined');
+    expect(timingSource).toContain("'membership-output-mismatch'");
+    expect(timingSource).toContain("'timestamp-range-invalid'");
+  });
+});

package/src/__tests__/ibl/ibl-fallback.unit.test.ts

@@ -0,0 +1,23 @@
+import { describe, expect, it } from 'vitest';
+import { describeIblCapability } from '../../ibl/cubemap-projection';
+
+describe('IBL capability fallback contract', () => {
+  it.each([
+    [true, 'supported', 'complete', 'passed'],
+    [false, 'degraded', 'notExecuted', 'failed'],
+  ] as const)('keeps capability=%s separate from execution and verdict', (supported, capabilityStatus, executionStatus, verdict) => {
+    const report = describeIblCapability({ rgba16floatRenderable: supported });
+
+    expect(report.capabilityStatus).toBe(capabilityStatus);
+    expect(report.executionStatus).toBe(executionStatus);
+    expect(report.verdict).toBe(verdict);
+  });
+
+  it('does not classify rgba8 as a silent HDR substitute', () => {
+    const report = describeIblCapability({ rgba16floatRenderable: false });
+
+    expect(report.outputFormat).not.toBe('rgba8unorm');
+    expect(report.fallbackArtifact).toBe('white-cube');
+    expect(report.expectedImpact).toContain('HDR');
+  });
+});

package/src/__tests__/infinite-grid-no-vertex-probe.unit.test.ts

@@ -0,0 +1,124 @@
+import { ok } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { createRenderFeatureHost, runRenderFeatureFrame } from '../features/host';
+import { createRenderFeatureTarget } from '../features/targets';
+import type { RenderFeature } from '../features/types';
+
+const caps = {
+  backendKind: 'null',
+  compute: true,
+  timestampQuery: false,
+  timestampPeriodNanoseconds: null,
+  indirectDrawing: false,
+  textureCompressionBc: false,
+  textureCompressionEtc2: false,
+  textureCompressionAstc: false,
+  multiDrawIndirect: false,
+  pushConstants: false,
+  textureBindingArray: false,
+  samplerAliasing: true,
+  firstInstanceIndirect: false,
+  storageBuffer: true,
+  storageTexture: true,
+  rgba16floatRenderable: true,
+  rg11b10ufloatRenderable: true,
+  float32Filterable: true,
+  maxColorAttachments: 8,
+} as const;
+
+const colorTarget = createRenderFeatureTarget({
+  kind: 'scene-color',
+  format: 'rgba8unorm',
+  sampleCount: 1,
+});
+const depthTarget = createRenderFeatureTarget({
+  kind: 'scene-depth',
+  format: 'depth24plus',
+  sampleCount: 1,
+});
+
+function noVertexFeature(): RenderFeature<{ readonly drawCount: number }> {
+  let pipeline: import('../features/prepared-graphics').RenderFeaturePreparedRef<'pipeline'>;
+  let bindings: import('../features/prepared-graphics').RenderFeaturePreparedRef<'bindings'>;
+
+  return {
+    identity: 'editor.infinite-grid.probe',
+    extract: () => ok({ drawCount: 1 }),
+    prepare: (_data, context) => {
+      const preparedPipeline = context.graphics.preparePipeline('fullscreen', {
+        shader: 'editor.infinite-grid.probe',
+        vertexLayout: 'none',
+        colorFormats: [colorTarget.format],
+        depthFormat: depthTarget.format,
+        sampleCount: colorTarget.sampleCount,
+        topology: 'triangle-list',
+      });
+      if (!preparedPipeline.ok) return preparedPipeline;
+      const preparedBindings = context.graphics.prepareBindings('view', {
+        pipeline: preparedPipeline.value,
+        values: { vertexShaderUsesVertexIndex: true },
+      });
+      if (!preparedBindings.ok) return preparedBindings;
+      pipeline = preparedPipeline.value;
+      bindings = preparedBindings.value;
+      return ok(undefined);
+    },
+    contribute: (_data, context) => {
+      if (pipeline === undefined || bindings === undefined) return ok(undefined);
+      return context.staging.addGraphicsPass('infinite-grid', {
+        attachments: {
+          colors: [
+            { resource: colorTarget, format: colorTarget.format, loadOp: 'load', storeOp: 'store' },
+          ],
+          depthStencil: {
+            resource: depthTarget,
+            format: depthTarget.format,
+            depthLoadOp: 'load',
+            depthStoreOp: 'store',
+          },
+        },
+        draws: [
+          {
+            kind: 'draw',
+            pipeline,
+            bindings: [bindings],
+            vertexData: [],
+            vertexLayout: 'none',
+            command: { vertexCount: 3, instanceCount: 1 },
+          },
+        ],
+      });
+    },
+  };
+}
+
+describe('public no-vertex RenderFeature seam probe', () => {
+  it('accepts the explicit public no-vertex producer contract', () => {
+    const host = createRenderFeatureHost([noVertexFeature()]).unwrap();
+    const result = runRenderFeatureFrame(host, {
+      worlds: [],
+      owner: 0,
+      frameNumber: 1,
+      caps,
+    });
+
+    expect(result.errors).toEqual([]);
+    expect(result.contributions).toHaveLength(1);
+    expect(result.contributions[0]?.passes[0]?.graphics?.draws[0]).toMatchObject({
+      kind: 'draw',
+      vertexLayout: 'none',
+      vertexData: [],
+      command: { vertexCount: 3, instanceCount: 1 },
+    });
+    expect(host.diagnostics()[0]).toMatchObject({
+      identity: 'editor.infinite-grid.probe',
+      status: 'active',
+      latestError: undefined,
+    });
+    expect(result.stageEvents.map((event) => event.stage)).toEqual([
+      'extract',
+      'prepare',
+      'contribute',
+    ]);
+  });
+});

package/src/__tests__/injection-kind-owner.test-d.ts

@@ -0,0 +1,14 @@
+import { expectTypeOf, it } from 'vitest';
+
+import { appendInjection, INJECTION_KIND_LENGTHS, type InjectionKind } from '../pbr-pipeline';
+
+it('derives InjectionKind from the public length-map keys', () => {
+  expectTypeOf<InjectionKind>().toEqualTypeOf<keyof typeof INJECTION_KIND_LENGTHS>();
+  expectTypeOf<InjectionKind>().toEqualTypeOf<'shadow' | 'ibl' | 'lightmap'>();
+  expectTypeOf<'unknown'>().not.toExtend<InjectionKind>();
+});
+
+it('keeps the public map assignability and appendInjection narrowing', () => {
+  expectTypeOf(INJECTION_KIND_LENGTHS).toMatchTypeOf<Readonly<Record<InjectionKind, number>>>();
+  expectTypeOf(appendInjection).parameter(1).toEqualTypeOf<InjectionKind>();
+});