@forgeax/engine-render 0.1.32 → 0.1.34

package/src/__tests__/main-pass-material-medium-selection.unit.test.ts

@@ -0,0 +1,146 @@
+import { World } from '@forgeax/engine-ecs';
+import { describe, expect, it } from 'vitest';
+import {
+  buildPerSubmeshMaterialBg,
+  type PerSubmeshMaterialBgDeps,
+} from '../record/main-pass-material';
+
+const SHA_MEDIUM_SHADER = 'sha256:464bbf-single-layer-medium';
+
+interface TestBindGroupEntry {
+  readonly binding: number;
+}
+
+interface TestDependencies extends PerSubmeshMaterialBgDeps {
+  readonly bindGroupEntries: Array<readonly TestBindGroupEntry[]>;
+}
+
+function dependencies(
+  options: { readonly selectedShader?: string; readonly surfaceResources?: boolean } = {},
+): TestDependencies {
+  const resource = () => ({}) as never;
+  const bindGroupEntries: Array<readonly TestBindGroupEntry[]> = [];
+  const runtime = {
+    device: {
+      caps: { storageBuffer: false },
+      limits: { maxSampledTexturesPerShaderStage: 16 },
+      createBindGroup: (descriptor: { readonly entries: readonly TestBindGroupEntry[] }) => {
+        bindGroupEntries.push(descriptor.entries);
+        return { ok: true, value: resource() };
+      },
+    },
+    ...(options.selectedShader === SHA_MEDIUM_SHADER
+      ? {
+          getMaterialShaderArtifact: (shaderId: string) =>
+            shaderId === SHA_MEDIUM_SHADER
+              ? ({ receipt: { surface: { model: 'single-layer-medium' } } } as never)
+              : undefined,
+        }
+      : {}),
+  };
+  const pipelineState = {
+    materialBindGroupLayout: resource(),
+    materialUniformBuffer: { buffer: resource() },
+    meshStorageBuffer: { buffer: resource() },
+    defaultSampler: resource(),
+    defaultWhiteTextureView: resource(),
+    defaultNormalTextureView: resource(),
+    fallbackTextureView: resource(),
+    defaultAnisotropyTextureView: resource(),
+    ...(options.surfaceResources ? { surfaceMediumDepthSampler: resource() } : {}),
+  };
+  const deps = {
+    runtime,
+    pipelineState,
+    world: new World(),
+    store: { materialResourceEpoch: 0 },
+    materialSlice: 256,
+    videoHighPerfAvailable: false,
+    skylightResources: {
+      irradianceView: resource(),
+      irradianceSampler: resource(),
+      prefilterView: resource(),
+      skylightPrefilterView: resource(),
+      prefilterSampler: resource(),
+      brdfLutView: resource(),
+      brdfLutSampler: resource(),
+      intensityBuffer: resource(),
+    },
+    materialBgShared: new Map(),
+    materialBgAssemblyCache: new Map(),
+    bindGroupCounts: { createBindGroup: 0, keys: [] },
+    frameState: {},
+    ...(options.surfaceResources
+      ? {
+          surfaceRawDepthView: resource(),
+          surfaceNearestLayerView: resource(),
+          surfaceNearestDepthView: resource(),
+        }
+      : {}),
+    bindGroupEntries,
+  };
+  return deps as unknown as TestDependencies;
+}
+
+function mediumSnapshot() {
+  return {
+    materialShaderId: 'forgeax::selected-shadow',
+    surfaceModel: 'single-layer-medium',
+  } as never;
+}
+
+describe('main-pass Surface material selection', () => {
+  it('does not request raw depth when a non-medium pass shader is selected', () => {
+    expect(() =>
+      buildPerSubmeshMaterialBg(
+        dependencies(),
+        mediumSnapshot(),
+        4,
+        undefined,
+        'forgeax::selected-shadow',
+      ),
+    ).not.toThrow();
+  });
+
+  it('requires raw depth for the selected single-layer-medium shader', () => {
+    expect(() =>
+      buildPerSubmeshMaterialBg(
+        dependencies(),
+        mediumSnapshot(),
+        4,
+        undefined,
+        'forgeax::single-layer-medium',
+      ),
+    ).toThrow('single-layer medium material bind group has producer-owned raw depth');
+  });
+
+  it('uses the selected SHA medium artifact ABI instead of authored metadata', () => {
+    const missingResources = dependencies({ selectedShader: SHA_MEDIUM_SHADER });
+    expect(() =>
+      buildPerSubmeshMaterialBg(
+        missingResources,
+        mediumSnapshot(),
+        4,
+        undefined,
+        SHA_MEDIUM_SHADER,
+      ),
+    ).toThrow('single-layer medium material bind group has producer-owned raw depth');
+
+    const completeResources = dependencies({
+      selectedShader: SHA_MEDIUM_SHADER,
+      surfaceResources: true,
+    });
+    expect(() =>
+      buildPerSubmeshMaterialBg(
+        completeResources,
+        mediumSnapshot(),
+        4,
+        undefined,
+        SHA_MEDIUM_SHADER,
+      ),
+    ).not.toThrow();
+    const entries = completeResources.bindGroupEntries[0] ?? [];
+    expect(entries.length).toBeGreaterThan(0);
+    expect(entries.some(({ binding }) => binding === 47)).toBe(false);
+  });
+});

package/src/__tests__/material-shader-prewarm.unit.test.ts

@@ -0,0 +1,59 @@
+import type { RhiDevice, ShaderModule } from '@forgeax/engine-rhi';
+import { ok } from '@forgeax/engine-rhi';
+import type { ShaderCatalog } from '@forgeax/engine-shader';
+import { describe, expect, it, vi } from 'vitest';
+import { prepareLowLimitMaterialShaderEntry } from '../assembly/material-shader-policy';
+import { prewarmRequiredMaterialShaders } from '../assembly/material-shader-prewarm';
+
+const source = `
+@group(0) @binding(16) var cloud: texture_2d<f32>;
+@group(0) @binding(17) var cloudSampler: sampler;
+fn sampleCloud() -> f32 {
+  return textureSampleLevel(cloud, cloudSampler, vec2<f32>(0.5), 0.0).x;
+}`;
+
+describe('material module prewarm and lazy pipeline agreement', () => {
+  it.each([16, 32])('seeds the same source on a %i-texture device', async (limit) => {
+    const entry = { source, paramSchema: [] };
+    const variantSource = `${source}\n// published variant`;
+    const registry = {
+      findMaterialArtifact: () => ok(entry),
+      materialShaderManifestEntries: () =>
+        [
+          {
+            identifier: 'game::surface',
+            variants: [{ definesKey: 'STYLE=true', composedWgsl: variantSource }],
+          },
+        ][Symbol.iterator](),
+    } as unknown as ShaderCatalog;
+    const device = { limits: { maxSampledTexturesPerShaderStage: limit } } as RhiDevice;
+    const compiled = new Map<ShaderModule, string>();
+    const seeded = new Map<string, ShaderModule>();
+    const compile = vi.fn(async (_device: RhiDevice, descriptor: { code: string }) => {
+      const module = {} as ShaderModule;
+      compiled.set(module, descriptor.code);
+      return ok(module);
+    });
+    await prewarmRequiredMaterialShaders({
+      rhiDevice: device,
+      registry,
+      requiredMaterialShaders: ['game::surface'],
+      asyncCreateShaderModule: compile,
+      seedShaderModule: (label, module) => {
+        seeded.set(label, module);
+      },
+    });
+    for (const [label, authored] of [
+      ['module-game::surface', source],
+      ['module-game::surface#STYLE=true', variantSource],
+    ] as const) {
+      const module = seeded.get(label);
+      expect(module).toBeDefined();
+      if (module === undefined) throw new Error(`Missing prewarmed module ${label}`);
+      expect(compiled.get(module)).toBe(
+        prepareLowLimitMaterialShaderEntry({ source: authored, paramSchema: [] }, limit).source,
+      );
+    }
+    expect(entry.source).toBe(source);
+  });
+});

package/src/__tests__/material-snapshot-mutation.integration.test.ts

@@ -8,9 +8,47 @@ import { describe, expect, it } from 'vitest';
 import { projectStandardSurfacePasses } from '../assembly/material/surface-projection';
 import { MeshFilter } from '../components/mesh-filter';
 import { MeshRenderer } from '../components/mesh-renderer';
-import { extractFrames, type MaterialSnapshotCachesByWorld } from '../render-system-extract';
+import {
+  extractFrames,
+  type MaterialSnapshotCachesByWorld,
+  resolveMaterialSnapshot,
+} from '../render-system-extract';
 
 describe('material snapshot mutation', () => {
+  it('projects the same Surface model for primary and reusable submesh snapshots', () => {
+    const world = new World();
+    const assets = new AssetRegistry({
+      findMaterialArtifact: () => ({ ok: false, error: new Error('not registered') }),
+    } as unknown as ShaderRegistry);
+    const material: MaterialAsset = {
+      kind: 'material',
+      surface: {
+        model: 'single-layer-medium',
+        module: 'game::water-surface',
+      },
+      passes: [
+        {
+          name: 'color',
+          program: { module: 'forgeax::single-layer-medium' },
+          renderState: { tags: { LightMode: 'Forward' }, queue: 3000 },
+        },
+      ],
+      values: {},
+    };
+    const materialHandle = world.allocSharedRef('MaterialAsset', material);
+    world.spawn(
+      { component: Transform, data: {} },
+      { component: MeshFilter, data: { assetHandle: HANDLE_CUBE } },
+      { component: MeshRenderer, data: { materials: [materialHandle] } },
+    );
+
+    const primary = extractFrames([world], 0, assets).renderables[0]?.material;
+    const reusable = resolveMaterialSnapshot(materialHandle, world, assets);
+
+    expect(primary?.surfaceModel).toBe('single-layer-medium');
+    expect(reusable.surfaceModel).toBe('single-layer-medium');
+  });
+
   it('projects in-place material value updates into the next extracted frame', () => {
     const world = new World();
     const assets = new AssetRegistry({

package/src/__tests__/mesh-submission-lifetime.unit.test.ts

@@ -59,3 +59,34 @@ it('fences ordinary mesh submissions independently of candidates, including reve
   expect(replacement.vertexBuffer.isDestroyed).toBe(true);
   expect(scope.resourceDelta()).toBe(0);
 });
+
+it('separates recycled shared mesh generations while old GPU work is still retained', async () => {
+  const device = (await (await rhi.requestAdapter()).unwrap().requestDevice()).unwrap();
+  const store = new GpuResidencyCache();
+  store.configureGpuDevice(
+    device,
+    undefined,
+    () => {
+      throw new Error('no cubemap');
+    },
+    device.caps,
+  );
+  const world = new World();
+  const first = createBoxGeometry(1, 1, 1).unwrap();
+  const oldHandle = world.allocSharedRef('MeshAsset', first);
+  const oldMesh = store.ensureResident(oldHandle, first, world).unwrap();
+  const lease = store.retainMeshResidency(oldHandle, world);
+  if (lease === undefined) throw new Error('mesh residency missing');
+  world.sharedRefs.release(oldHandle).unwrap();
+  const next = createBoxGeometry(8, 8, 8).unwrap();
+  const newHandle = world.allocSharedRef('MeshAsset', next);
+  expect(Number(newHandle) & 0xffffff).toBe(Number(oldHandle) & 0xffffff);
+  expect(newHandle).not.toBe(oldHandle);
+  const newMesh = store.ensureResident(newHandle, next, world).unwrap();
+  expect(newMesh).not.toBe(oldMesh);
+  store.invalidateMesh(oldHandle, world);
+  lease.release(true);
+  expect(store.getMeshGpuHandles(newHandle, world)).toBe(newMesh);
+  expect(newMesh.vertexBuffer.isDestroyed).toBe(false);
+  store.destroyAll();
+});

package/src/__tests__/morph-culling-reentry.dawn.test.ts

@@ -70,7 +70,7 @@ describe('Morph GPU culling and re-entry', () => {
     ).toMatchObject({ reentered: true, clearStale: true, weights: [0.75] });
   });
 
-  it('declares compute and storage capability ownership and records 300 frame phases', () => {
+  it('declares compute and storage capability ownership and records 60 frame phases', () => {
     let frameNumber = 0;
     const feature = createBuiltinMorphFeature({
       collect: () => [
@@ -79,8 +79,8 @@ describe('Morph GPU culling and re-entry', () => {
           vertexCount: 3,
           targetBounds: [{ min: [-2, 0, 0], max: [3, 0, 0] }],
           baseBounds,
-          weights: new Float32Array([frameNumber >= 200 ? 1 : 0]),
-          baseAabbIntersectsFrustum: frameNumber < 100 || frameNumber >= 200,
+          weights: new Float32Array([frameNumber >= 40 ? 1 : 0]),
+          baseAabbIntersectsFrustum: frameNumber < 20 || frameNumber >= 40,
         },
       ],
     });
@@ -88,7 +88,7 @@ describe('Morph GPU culling and re-entry', () => {
     expect(feature.requiredCapabilities).toEqual(['compute', 'storageBuffer']);
     let culledFrames = 0;
     let reentries = 0;
-    for (frameNumber = 0; frameNumber < 300; frameNumber++) {
+    for (frameNumber = 0; frameNumber < 60; frameNumber++) {
       const extracted = feature.extract({ worlds: [], owner: 0, frameNumber });
       expect(extracted.ok).toBe(true);
       if (!extracted.ok) continue;
@@ -96,7 +96,7 @@ describe('Morph GPU culling and re-entry', () => {
       reentries += extracted.value.reentryCount;
     }
 
-    expect(culledFrames).toBe(100);
+    expect(culledFrames).toBe(20);
     expect(reentries).toBe(1);
   });
 

package/src/__tests__/morph-visual-evidence.integration.test.ts

@@ -11,7 +11,7 @@ const evidencePath = resolve(
 const matrixPath = resolve(repoRoot, 'apps/hello/format-tier1/evidence/format-support-matrix.json');
 
 describe('Morph Dawn evidence contract', () => {
-  it('binds the 300-frame GPU result to the immutable source and readback', async () => {
+  it('binds a complete GPU result of at least 60 frames to the immutable source and readback', async () => {
     const [evidence, matrix] = await Promise.all([
       readFile(evidencePath, 'utf8').then(
         (source) =>
@@ -54,13 +54,14 @@ describe('Morph Dawn evidence contract', () => {
     expect(matrix.source?.firstTierRows).toEqual([8, 18, 26]);
     expect(evidence.source?.sourceCodeSha).toMatch(/^[a-f0-9]{40,64}$/);
     expect(evidence.environment?.backend).toBe('dawn');
-    expect(evidence.requiredFrames).toBe(300);
-    expect(evidence.framesObserved).toBe(300);
+    expect(evidence.requiredFrames).toBeGreaterThanOrEqual(60);
+    expect(evidence.framesObserved).toBe(evidence.requiredFrames);
+    const phaseFrames = (evidence.requiredFrames ?? 0) / 3;
     expect(evidence.phases).toEqual({
-      standardFrames: 300,
-      baseWeightFrames: 100,
-      zeroWeightFrames: 100,
-      animatedFrames: 100,
+      standardFrames: evidence.requiredFrames,
+      baseWeightFrames: phaseFrames,
+      zeroWeightFrames: phaseFrames,
+      animatedFrames: phaseFrames,
     });
     expect(evidence.readback?.status).toBe('pass');
     expect(evidence.readback?.path).toContain('observe(FrameReceipt)');