@forgeax/engine-render 0.1.7 → 0.1.20

package/src/record/__tests__/main-pass-geometry.unit.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, it } from 'vitest';
+import { geometryRenderStateForPass } from '../main-pass-geometry';
+
+describe('geometry pass render state', () => {
+  it('keeps the main depth authority while admitting equal temporal depth', () => {
+    const base = {
+      cullMode: 'back' as const,
+      depthCompare: 'less' as const,
+      depthWriteEnabled: true,
+    };
+
+    expect(geometryRenderStateForPass(base, 'temporal')).toMatchObject({
+      cullMode: 'back',
+      depthCompare: 'less-equal',
+      depthWriteEnabled: false,
+    });
+  });
+
+  it('does not rewrite the base state for colour passes', () => {
+    const base = {
+      cullMode: 'none' as const,
+      depthCompare: 'less-equal' as const,
+      depthWriteEnabled: false,
+    };
+
+    expect(geometryRenderStateForPass(base, 'forward')).toBe(base);
+  });
+
+  it.each([
+    ['far then near', [0.8, 0.2]],
+    ['near then far', [0.2, 0.8]],
+  ] as const)('keeps the near fragment visible for %s temporal overlap', (_order, depths) => {
+    const state = geometryRenderStateForPass(
+      { cullMode: 'back', depthCompare: 'less', depthWriteEnabled: true },
+      'temporal',
+    );
+    if (state === undefined) throw new Error('temporal render state is required');
+    const visibleDepth = 0.2;
+    const accepted = depths.filter((depth) => {
+      if (state.depthCompare === 'less-equal') return depth <= visibleDepth;
+      return depth < visibleDepth;
+    });
+
+    expect(state.depthWriteEnabled).toBe(false);
+    expect(accepted).toEqual([visibleDepth]);
+  });
+});

package/src/record/__tests__/material-bg-cache.unit.test.ts

@@ -1,4 +1,4 @@
-import type { BindGroup, BindGroupLayout, Buffer } from '@forgeax/engine-rhi';
+import type { BindGroup, BindGroupLayout, Buffer, TextureView } from '@forgeax/engine-rhi';
 import { describe, expect, it } from 'vitest';
 import type { MaterialSnapshot } from '../../render-system-extract';
 import type { MaterialBgAssemblyCacheEntry } from '../frame-snapshot';
@@ -37,5 +37,16 @@ describe('material bind-group assembly cache', () => {
     expect(
       isMaterialBgAssemblyCacheHit(cached, material, materialBgl, oldBuffer, skylightResources, 8),
     ).toBe(false);
+    expect(
+      isMaterialBgAssemblyCacheHit(
+        cached,
+        material,
+        materialBgl,
+        oldBuffer,
+        skylightResources,
+        7,
+        {} as TextureView,
+      ),
+    ).toBe(false);
   });
 });

package/src/record/__tests__/material-pipeline-pending-cache.unit.test.ts

@@ -0,0 +1,22 @@
+import { readFileSync } from 'node:fs';
+import { describe, expect, it } from 'vitest';
+
+const source = readFileSync(new URL('../main-pass-geometry.ts', import.meta.url), 'utf8');
+
+describe('main-pass material pipeline cache', () => {
+  it('keeps transient pending pipelines retryable across a tight frame loop', () => {
+    const resolverStart = source.indexOf('const resolveMaterialPipeline =');
+    const resolverEnd = source.indexOf(
+      'for (let i = 0; i < validatedOrdered.length;',
+      resolverStart,
+    );
+    const resolver = source.slice(resolverStart, resolverEnd);
+    const pendingGuard = resolver.indexOf('if (handle !== null) {');
+    const cachedInsert = resolver.indexOf('cachedLookups.push(nextLookup)', pendingGuard);
+    const guardEnd = resolver.indexOf('\n    }\n    return handle;', pendingGuard);
+
+    expect(pendingGuard).toBeGreaterThan(-1);
+    expect(cachedInsert).toBeGreaterThan(pendingGuard);
+    expect(guardEnd).toBeGreaterThan(cachedInsert);
+  });
+});

package/src/record/__tests__/sprite-material-abi.unit.test.ts

@@ -0,0 +1,75 @@
+import type { Buffer, Sampler, TextureView } from '@forgeax/engine-rhi';
+import { describe, expect, it } from 'vitest';
+import { assembleMaterialWithSkylightEntries } from '../../ibl/skylight-bind-group';
+import { buildSpritePassBaseMaterialEntries } from '../main-pass-sprite-draws';
+import type { PipelineState } from '../render-context';
+
+describe('sprite Standard material ABI', () => {
+  it('covers transmission and thickness before IBL injection', () => {
+    const sampler = {} as Sampler;
+    const white = {} as TextureView;
+    const pipelineState = {
+      materialUniformBuffer: { buffer: {} },
+      nearestSampler: sampler,
+      defaultSampler: sampler,
+      defaultWhiteTextureView: white,
+      defaultNormalTextureView: {} as TextureView,
+      fallbackTextureView: {} as TextureView,
+    } as PipelineState;
+    const spriteTexture = {} as TextureView;
+
+    const entries = buildSpritePassBaseMaterialEntries(pipelineState, spriteTexture);
+
+    expect(entries.map((entry) => entry.binding)).toEqual([
+      0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16,
+    ]);
+    expect(entries[13]).toMatchObject({ binding: 13, resource: { kind: 'sampler' } });
+    expect(entries[14]).toMatchObject({ binding: 14, resource: { kind: 'textureView' } });
+    expect(entries[15]).toMatchObject({ binding: 15, resource: { kind: 'sampler' } });
+    expect(entries[16]).toMatchObject({ binding: 16, resource: { kind: 'textureView' } });
+    expect(entries[2]?.resource).toMatchObject({ kind: 'textureView', value: spriteTexture });
+    expect(entries).toHaveLength(17);
+
+    const merged = assembleMaterialWithSkylightEntries(entries, {
+      irradianceView: {} as TextureView,
+      irradianceSampler: sampler,
+      prefilterView: {} as TextureView,
+      prefilterSampler: sampler,
+      brdfLutView: {} as TextureView,
+      brdfLutSampler: sampler,
+      intensityBuffer: {} as Buffer,
+    });
+    expect(merged[17]).toMatchObject({
+      binding: 17,
+      resource: { kind: 'textureView' },
+    });
+    expect(merged[24]).toMatchObject({
+      binding: 24,
+      resource: { kind: 'sampler', value: sampler },
+    });
+    expect(merged[25]).toMatchObject({
+      binding: 25,
+      resource: { kind: 'textureView' },
+    });
+    expect(merged).toHaveLength(26);
+
+    const backdrop = {} as TextureView;
+    const active = assembleMaterialWithSkylightEntries(
+      entries,
+      {
+        irradianceView: {} as TextureView,
+        irradianceSampler: sampler,
+        prefilterView: {} as TextureView,
+        prefilterSampler: sampler,
+        brdfLutView: {} as TextureView,
+        brdfLutSampler: sampler,
+        intensityBuffer: {} as Buffer,
+      },
+      { sampler, backdropView: backdrop },
+    );
+    expect(active[25]).toMatchObject({
+      binding: 25,
+      resource: { kind: 'textureView', value: backdrop },
+    });
+  });
+});

package/src/record/__tests__/standard-pbr-ubo-layout.unit.test.ts

@@ -0,0 +1,67 @@
+import { World } from '@forgeax/engine-ecs';
+import { vec3 } from '@forgeax/engine-math';
+import { DEFAULT_STANDARD_PBR_PARAM_SCHEMA } from '@forgeax/engine-shader';
+import { derive } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import type { MaterialSnapshot } from '../../render-system-extract';
+import { applyMaterialTextureUvScales, buildPbrMaterialUboPayload } from '../main-pass-material';
+
+describe('Standard PBR UBO layout', () => {
+  it('keeps shader, derived schema, and record offsets aligned', () => {
+    const derived = derive(DEFAULT_STANDARD_PBR_PARAM_SCHEMA);
+    const numeric = new Map(derived.numericMembers.map((member) => [member.name, member.offset]));
+    const coordinates = new Map(
+      derived.coordinateRecords.map((record) => [record.parameter, record.offset]),
+    );
+
+    expect(derived.totalBytes).toBe(384);
+    expect(numeric.get('normalScale')).toBe(92);
+    expect(numeric.get('transmission')).toBe(96);
+    expect(numeric.get('ior')).toBe(100);
+    expect(numeric.get('thickness')).toBe(104);
+    expect(numeric.get('attenuationColor')).toBe(112);
+    expect(numeric.get('attenuationDistance')).toBe(124);
+    expect(coordinates.get('baseColorTexture')).toBe(128);
+    expect(coordinates.get('transmissionTexture')).toBe(320);
+    expect(coordinates.get('thicknessTexture')).toBe(352);
+  });
+
+  it('writes transmission scalars and defaults at the reflected offsets', () => {
+    const material = {
+      baseColor: vec3.create(0.7, 0.7, 0.7),
+      metallic: 0,
+      roughness: 0.4,
+      normalScale: 0.25,
+      materialShaderId: 'forgeax::default-standard-pbr',
+      paramSnapshot: {
+        transmission: 0.75,
+        ior: 1.6,
+        thickness: 0.2,
+        attenuationColor: [0.2, 0.4, 0.6],
+        attenuationDistance: 3,
+      },
+    } satisfies MaterialSnapshot;
+    const f32 = new Float32Array(buildPbrMaterialUboPayload(material).buffer);
+
+    expect(f32.slice(23, 32)).toEqual(
+      new Float32Array([0.25, 0.75, 1.6, 0.2, 0, 0.2, 0.4, 0.6, 3]),
+    );
+  });
+
+  it('uses all eight identity coordinate records in the no-snapshot fallback', () => {
+    const material = {
+      baseColor: vec3.create(0.7, 0.7, 0.7),
+      metallic: 0,
+      roughness: 0.4,
+      materialShaderId: 'forgeax::default-standard-pbr',
+    } satisfies MaterialSnapshot;
+    const payload = buildPbrMaterialUboPayload(material);
+
+    applyMaterialTextureUvScales(payload, material, new World());
+
+    const f32 = new Float32Array(payload.buffer);
+    expect(f32.slice(32, 96)).toEqual(
+      new Float32Array(Array(8).fill([0, 0, 1, 1, 0, 0, 1, 1]).flat()),
+    );
+  });
+});

package/src/record/__tests__/temporal-payload.unit.test.ts

@@ -0,0 +1,164 @@
+import { vec3 } from '@forgeax/engine-math';
+import type { Buffer, RhiQueue } from '@forgeax/engine-rhi';
+import { describe, expect, it } from 'vitest';
+import type { CameraSnapshot } from '../../render-contract';
+import type { RenderableSnapshot } from '../../render-system-extract';
+import type { TemporalView } from '../../temporal/temporal-view';
+import type { ValidatedRenderable } from '../frame-snapshot';
+import { uploadMeshSsboBatch } from '../mesh-ssbo';
+import { writeViewUbo } from '../view-ubo';
+
+function identityMatrix(): Float32Array {
+  const matrix = new Float32Array(16);
+  matrix[0] = 1;
+  matrix[5] = 1;
+  matrix[10] = 1;
+  matrix[15] = 1;
+  return matrix;
+}
+
+function translatedMatrix(x: number): Float32Array {
+  const matrix = identityMatrix();
+  matrix[12] = x;
+  return matrix;
+}
+
+function recordingQueue(): {
+  readonly queue: RhiQueue;
+  readonly uploads: readonly Uint8Array[];
+} {
+  const uploads: Uint8Array[] = [];
+  const queue = {
+    writeBuffer: (
+      _buffer: Buffer,
+      _bufferOffset: number,
+      data: ArrayBufferView | ArrayBuffer,
+      _dataOffset?: number,
+      size?: number,
+    ) => {
+      const bytes =
+        data instanceof ArrayBuffer
+          ? new Uint8Array(data, 0, size ?? data.byteLength)
+          : new Uint8Array(data.buffer, data.byteOffset, size ?? data.byteLength);
+      uploads.push(new Uint8Array(bytes));
+      return { ok: true, value: undefined } as const;
+    },
+  } as unknown as RhiQueue;
+  return { queue, uploads };
+}
+
+function camera(): CameraSnapshot {
+  return {
+    entityKey: 1,
+    worldId: 0,
+    historyVersion: 0,
+    position: vec3.create(0, 0, 5),
+    world: identityMatrix(),
+    fov: Math.PI / 3,
+    aspect: 1,
+    near: 0.1,
+    far: 100,
+    projection: 'perspective',
+    orthoLeft: -1,
+    orthoRight: 1,
+    orthoBottom: -1,
+    orthoTop: 1,
+    tonemap: 'none',
+    exposure: 1,
+    whitePoint: 4,
+    antialias: 'none',
+    bloom: 'off',
+    bloomThreshold: 1,
+    bloomIntensity: 1,
+    bloomBlurRadius: 4,
+    clearColor: [0, 0, 0, 1],
+  };
+}
+
+function temporalView(): TemporalView {
+  const current = identityMatrix();
+  current[0] = 2;
+  const previous = identityMatrix();
+  previous[0] = 3;
+  return {
+    viewId: '0:1:0',
+    historyVersion: 0,
+    temporalFrameIndex: 1,
+    historyValid: true,
+    resetReason: undefined,
+    currentJitterUv: [0, 0],
+    previousJitterUv: [0, 0],
+    currentJitteredViewProjection: current,
+    currentUnjitteredViewProjection: current,
+    previousUnjitteredViewProjection: previous,
+    projection: 'perspective',
+    near: 0.1,
+    far: 100,
+  };
+}
+
+describe('temporal GPU payloads', () => {
+  it('writes temporal current/previous projection after the spot-light lanes', () => {
+    const { queue, uploads } = recordingQueue();
+    writeViewUbo(
+      queue,
+      {} as Buffer,
+      camera(),
+      {
+        kind: 'directional',
+        direction: vec3.create(0, -1, 0),
+        color: vec3.create(1, 1, 1),
+        intensity: 1,
+      },
+      { point: [], spot: [] } as never,
+      [],
+      temporalView(),
+    );
+
+    const payload = new Float32Array(uploads[0]?.buffer ?? new ArrayBuffer(0));
+    expect(payload.length).toBe(240);
+    expect(payload[196]).toBeCloseTo(Math.sqrt(3));
+    expect(payload[212]).toBe(3);
+    expect(payload[228]).toBeCloseTo(0.1);
+    expect(payload[229]).toBe(100);
+    expect(payload[230]).toBe(0);
+  });
+
+  it('seeds previousWorld on the first frame and uses the submitted snapshot later', () => {
+    const first = translatedMatrix(4);
+    const previous = translatedMatrix(2);
+    const second = translatedMatrix(6);
+    const makeEntry = (world: Float32Array, temporal?: object) =>
+      ({
+        source: {
+          transform: { world },
+          materials: [{ transparent: false }],
+          ...(temporal === undefined ? {} : { temporal }),
+        } as unknown as RenderableSnapshot,
+      }) as unknown as ValidatedRenderable;
+    const firstRecording = recordingQueue();
+    uploadMeshSsboBatch(firstRecording.queue, { buffer: {} as Buffer }, [makeEntry(first)], null);
+    const firstPayload = new Float32Array(firstRecording.uploads[0]?.buffer ?? new ArrayBuffer(0));
+    expect(firstPayload[12]).toBe(4);
+    expect(firstPayload[28 + 12]).toBe(4);
+
+    const secondRecording = recordingQueue();
+    uploadMeshSsboBatch(
+      secondRecording.queue,
+      { buffer: {} as Buffer },
+      [
+        makeEntry(second, {
+          previousTransform: { world: previous },
+          reactive: false,
+        }),
+      ],
+      null,
+    );
+    const secondPayload = new Float32Array(
+      secondRecording.uploads[0]?.buffer ?? new ArrayBuffer(0),
+    );
+    expect(secondPayload[12]).toBe(6);
+    expect(secondPayload[28 + 12]).toBe(2);
+    expect(secondPayload[44]).toBe(0);
+  });
+});

package/src/record/__tests__/typed-frame-graph-plan.unit.test.ts

@@ -1,10 +1,88 @@
+import { ok } from '@forgeax/engine-types';
 import { describe, expect, it } from 'vitest';
 import type { RenderFeaturePlannedFrame } from '../../features/plan';
+import { GPU_TEXTURE_USAGE_COPY_SRC } from '../../gpu-texture-usage';
+import { getTextureIdentity, validateGraphTargetCaptureReadback } from '../frame-snapshot';
 import {
+  executeCompiledFrameGraph,
   type RenderFeatureGraphCandidate,
   renderFeatureGraphPlanSignature,
 } from '../typed-frame-graph';
 
+const captureDescriptor = {
+  texture: {} as never,
+  format: 'rgba16float' as const,
+  size: { width: 4, height: 2 },
+  usage: GPU_TEXTURE_USAGE_COPY_SRC,
+  sample: 1,
+};
+
+type CaptureOverrides = {
+  readonly target?: boolean;
+  readonly descriptor?: {
+    readonly format?: 'rgba16float' | 'rgba8unorm';
+    readonly size?: { readonly width: number; readonly height: number };
+    readonly usage?: number;
+  };
+  readonly identity?: { graphGeneration: number; frameId: number; textureIdentity: number };
+};
+
+function executeCapture(overrides: CaptureOverrides = {}) {
+  const errors: unknown[] = [];
+  const copies: unknown[] = [];
+  const texture = {} as never;
+  const descriptor = { ...captureDescriptor, ...overrides.descriptor, texture };
+  const graph = {
+    execute: () => ok(undefined),
+  };
+  const frameState = {
+    compiledFrameGraph: graph,
+    frameNumber: 13,
+    graphTargetCapture: {
+      name: 'standard-output-color',
+      buffer: {} as never,
+      bytesPerRow: 256,
+      width: 4,
+      height: 2,
+      expected: {
+        format: 'rgba16float' as const,
+        width: 4,
+        height: 2,
+        usage: GPU_TEXTURE_USAGE_COPY_SRC,
+        identity: overrides.identity ?? {
+          graphGeneration: 7,
+          frameId: 12,
+          textureIdentity: getTextureIdentity(texture),
+        },
+      },
+    },
+    perFrameGraph:
+      overrides.target === false
+        ? undefined
+        : {
+            graphGeneration: 7,
+            getColorTargetTexture: () => (overrides.target === false ? undefined : texture),
+            getColorTargetDescriptor: () => (overrides.target === false ? undefined : descriptor),
+            getColorTargetView: () => undefined,
+          },
+  } as never;
+  const encoder = {
+    copyTextureToBuffer: (...args: unknown[]) => copies.push(args),
+    finish: () => ok({} as never),
+  } as never;
+  const internals = {
+    errorRegistry: { fire: (error: unknown) => errors.push(error) },
+    device: { queue: { submit: () => ok(undefined) } },
+  } as never;
+  const submitted = executeCompiledFrameGraph(internals, frameState, {} as never, encoder);
+  return { submitted, errors, copies };
+}
+
+function failureReason(errors: readonly unknown[]): string {
+  const error = errors[0] as { detail?: { error?: { message?: string } } } | undefined;
+  return error?.detail?.error?.message ?? '';
+}
+
 function planned(generation: number, signature: string): RenderFeaturePlannedFrame {
   return {
     featureIdentity: 'synthetic.feature',
@@ -38,4 +116,53 @@ describe('typed frame graph feature plan authority', () => {
     };
     void invalid;
   });
+
+  it.each([
+    ['missing target', { target: false }, 'target-not-present-in-current-graph'],
+    ['format mismatch', { descriptor: { format: 'rgba8unorm' as const } }, 'descriptor-mismatch'],
+    ['extent mismatch', { descriptor: { size: { width: 2, height: 2 } } }, 'extent-mismatch'],
+    ['COPY_SRC missing', { descriptor: { usage: 0 } }, 'copy-src-usage-missing'],
+    [
+      'identity mismatch',
+      { identity: { graphGeneration: 8, frameId: 12, textureIdentity: 999 } },
+      'identity-mismatch',
+    ],
+  ])('fails closed for capture %s', (_name, overrides, expectedReason) => {
+    const result = executeCapture(overrides);
+    expect(result.submitted).toBe(true);
+    expect(result.copies).toHaveLength(0);
+    expect(result.errors).toHaveLength(1);
+    expect(failureReason(result.errors)).toContain(`"reason":"${expectedReason}"`);
+  });
+
+  it('copies the exact target only after all capture identity and descriptor checks pass', () => {
+    const result = executeCapture();
+    expect(result.submitted).toBe(true);
+    expect(result.errors).toHaveLength(0);
+    expect(result.copies).toHaveLength(1);
+  });
+
+  it.each([
+    [
+      'missing same-submit copy / untouched sentinel',
+      new Uint8Array([0xa5, 0xa5, 0xa5, 0xa5]),
+      new Uint8Array([0xa5, 0xa5]),
+      'capture-readback-untouched-sentinel',
+    ],
+    ['all-empty readback', new Uint8Array(4), undefined, 'capture-readback-empty'],
+    [
+      'non-finite float16',
+      new Uint8Array([0x01, 0x7c, 0, 0]),
+      undefined,
+      'capture-readback-non-finite',
+    ],
+  ])('returns a structured failure for %s readback', (_name, bytes, sentinel, expectedCode) => {
+    const result = validateGraphTargetCaptureReadback({
+      bytes,
+      expectedByteLength: 4,
+      ...(sentinel === undefined ? {} : { sentinel }),
+    });
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.code).toBe(expectedCode);
+  });
 });