@forgeax/engine-runtime 0.0.0-dev.8d955ade1c79

package/src/__tests__/dawn/ibl-modules-compose.dawn.test.ts

@@ -0,0 +1,223 @@
+// ibl-modules-compose.dawn.test.ts -- feat-20260520-skylight-ibl-cubemap M3 / t41.
+//
+// Cross-file composition test for the 6-module ibl-* family. Each module
+// declares a unique #define_import_path; this test verifies that naga_oil
+// Composer can:
+//   (1) Register every module independently (no @group/@binding collision).
+//   (2) Compose ibl_shared + ibl_irradiance into a fragment entry that
+//       references ibl_irradiance helpers, exercising the texture_cube
+//       @group(1) binding path.
+//   (3) Compose ibl_shared + ibl_prefilter into a fragment entry, mirroring
+//       (2) but with the prefilter module's additional prefilterUniforms
+//       buffer to confirm dual-uniform @group(0) ordering.
+//   (4) Compose ibl_shared + ibl_sampling into a pbr-style entry that
+//       provides texture/sampler as function arguments (zero-binding
+//       runtime helper module).
+//
+// Red-phase: before t42..t47 land, the source files do not exist and every
+// it(...) below fails (readFileSync throws ENOENT). Green after the 6
+// modules exist + their imports compose cleanly.
+//
+// node:* are accessed via the established `await import(varId)` pattern
+// (renderer-draw-world.test.ts) so the runtime tsconfig does not need an
+// explicit `@types/node` types entry (which would regress brand-type
+// narrowing in createRenderer.ts).
+
+import { composeShader, parse } from '@forgeax/engine-naga';
+import { beforeAll, describe, expect, it } from 'vitest';
+
+interface NodeFs {
+  readFileSync: (p: string, enc: string) => string;
+}
+interface NodePath {
+  resolve: (...parts: string[]) => string;
+  dirname: (p: string) => string;
+}
+interface NodeModule {
+  createRequire: (filename: string | URL) => { resolve: (id: string) => string };
+}
+
+const dawnReady = typeof navigator !== 'undefined' && navigator.gpu !== undefined;
+
+let srcDir!: string;
+let readSourceSync!: (file: string) => string;
+
+beforeAll(async () => {
+  const fsId = 'node:fs';
+  const pathId = 'node:path';
+  const moduleId = 'node:module';
+  const fs = (await import(/* @vite-ignore */ fsId)) as NodeFs;
+  const path = (await import(/* @vite-ignore */ pathId)) as NodePath;
+  const mod = (await import(/* @vite-ignore */ moduleId)) as NodeModule;
+  const req = mod.createRequire(import.meta.url);
+  const pkg = req.resolve('@forgeax/engine-shader/package.json');
+  srcDir = path.resolve(path.dirname(pkg), 'src');
+  readSourceSync = (file: string) => fs.readFileSync(path.resolve(srcDir, file), 'utf8');
+});
+
+describe('t41 (b) -- 6-module ibl-* family naga_oil composition', () => {
+  it.skipIf(!dawnReady)(
+    '(b1) ibl_shared composes alone (zero binding pure-math module)',
+    async () => {
+      const shared = readSourceSync('ibl-shared.wgsl');
+      const entry = [
+        '#import forgeax_pbr::ibl_shared::{hammersley}',
+        '@vertex fn vs() -> @builtin(position) vec4<f32> { return vec4<f32>(0.0); }',
+        '@fragment fn fs() -> @location(0) vec4<f32> {',
+        '  let h = hammersley(3u, 16u);',
+        '  return vec4<f32>(h, 0.0, 1.0);',
+        '}',
+      ].join('\n');
+      const composed = await composeShader(entry, { 'forgeax_pbr::ibl_shared': shared }, {});
+      expect(composed).toContain('hammersley');
+      const parsed = await parse(composed);
+      expect(parsed).not.toBeNull();
+    },
+  );
+
+  it.skipIf(!dawnReady)(
+    '(b2) ibl_shared + ibl_irradiance compose (texture_cube @group(1))',
+    async () => {
+      const shared = readSourceSync('ibl-shared.wgsl');
+      const irradiance = readSourceSync('ibl-irradiance.wgsl');
+      // The irradiance module declares its own @group(0) faceUniforms +
+      // @group(1) envCube + sampler. Compose by importing irradianceConvolve_fs
+      // as the entry directly -- naga_oil inlines the module sources, the
+      // composed output exposes the entry. We call it via a thin re-entry.
+      const entry = [
+        '#import forgeax_pbr::ibl_shared::{radicalInverseVdC}',
+        '#import forgeax_pbr::ibl_irradiance',
+        '@vertex fn vs() -> @builtin(position) vec4<f32> { return vec4<f32>(0.0); }',
+        '@fragment fn fs() -> @location(0) vec4<f32> {',
+        '  _ = radicalInverseVdC(11u);',
+        '  return vec4<f32>(1.0);',
+        '}',
+      ].join('\n');
+      const composed = await composeShader(
+        entry,
+        {
+          'forgeax_pbr::ibl_shared': shared,
+          'forgeax_pbr::ibl_irradiance': irradiance,
+        },
+        {},
+      );
+      expect(composed.length).toBeGreaterThan(0);
+      const parsed = await parse(composed);
+      expect(parsed).not.toBeNull();
+    },
+  );
+
+  it.skipIf(!dawnReady)(
+    '(b3) ibl_shared + ibl_prefilter compose (dual-uniform @group(0))',
+    async () => {
+      const shared = readSourceSync('ibl-shared.wgsl');
+      const prefilter = readSourceSync('ibl-prefilter.wgsl');
+      const entry = [
+        '#import forgeax_pbr::ibl_shared::{hammersley}',
+        '#import forgeax_pbr::ibl_prefilter',
+        '@vertex fn vs() -> @builtin(position) vec4<f32> { return vec4<f32>(0.0); }',
+        '@fragment fn fs() -> @location(0) vec4<f32> {',
+        '  _ = hammersley(0u, 1024u);',
+        '  return vec4<f32>(1.0);',
+        '}',
+      ].join('\n');
+      const composed = await composeShader(
+        entry,
+        {
+          'forgeax_pbr::ibl_shared': shared,
+          'forgeax_pbr::ibl_prefilter': prefilter,
+        },
+        {},
+      );
+      const parsed = await parse(composed);
+      expect(parsed).not.toBeNull();
+    },
+  );
+
+  it.skipIf(!dawnReady)(
+    '(b4) ibl_shared + ibl_sampling compose (zero-binding runtime helper)',
+    async () => {
+      const shared = readSourceSync('ibl-shared.wgsl');
+      const sampling = readSourceSync('ibl-sampling.wgsl');
+      // ibl_sampling exports sampleIblDiffuse/sampleIblSpecular which take
+      // texture/sampler as function arguments. The entry provides them via
+      // its own @group(1) bindings, mirroring how pbr.wgsl consumes the
+      // helper through its skylight @group(4).
+      const entry = [
+        '#import forgeax_pbr::ibl_sampling::{sampleIblDiffuse}',
+        '@group(1) @binding(0) var irradianceMap: texture_cube<f32>;',
+        '@group(1) @binding(1) var irradianceSampler: sampler;',
+        '@vertex fn vs() -> @builtin(position) vec4<f32> { return vec4<f32>(0.0); }',
+        '@fragment fn fs() -> @location(0) vec4<f32> {',
+        '  let c = sampleIblDiffuse(vec3<f32>(0.0, 1.0, 0.0), vec4<f32>(0.0, 0.0, 0.0, 1.0), irradianceMap, irradianceSampler);',
+        '  return vec4<f32>(c, 1.0);',
+        '}',
+      ].join('\n');
+      const composed = await composeShader(
+        entry,
+        {
+          'forgeax_pbr::ibl_shared': shared,
+          'forgeax_pbr::ibl_sampling': sampling,
+        },
+        {},
+      );
+      expect(composed).toContain('sampleIblDiffuse');
+      const parsed = await parse(composed);
+      expect(parsed).not.toBeNull();
+    },
+  );
+
+  it.skipIf(!dawnReady)(
+    '(b5) ibl_brdf_lut composes alone (no @group(1) external texture)',
+    async () => {
+      const shared = readSourceSync('ibl-shared.wgsl');
+      const brdfLut = readSourceSync('ibl-brdf-lut.wgsl');
+      const entry = [
+        '#import forgeax_pbr::ibl_shared::{hammersley}',
+        '#import forgeax_pbr::ibl_brdf_lut',
+        '@vertex fn vs() -> @builtin(position) vec4<f32> { return vec4<f32>(0.0); }',
+        '@fragment fn fs() -> @location(0) vec4<f32> {',
+        '  _ = hammersley(1u, 16u);',
+        '  return vec4<f32>(1.0);',
+        '}',
+      ].join('\n');
+      const composed = await composeShader(
+        entry,
+        {
+          'forgeax_pbr::ibl_shared': shared,
+          'forgeax_pbr::ibl_brdf_lut': brdfLut,
+        },
+        {},
+      );
+      const parsed = await parse(composed);
+      expect(parsed).not.toBeNull();
+    },
+  );
+
+  it.skipIf(!dawnReady)(
+    '(b6) ibl_shared + ibl_equirect_to_cube compose (texture_2d @group(1))',
+    async () => {
+      const shared = readSourceSync('ibl-shared.wgsl');
+      const equirect = readSourceSync('ibl-equirect-to-cube.wgsl');
+      const entry = [
+        '#import forgeax_pbr::ibl_shared::{radicalInverseVdC}',
+        '#import forgeax_pbr::ibl_equirect_to_cube',
+        '@vertex fn vs() -> @builtin(position) vec4<f32> { return vec4<f32>(0.0); }',
+        '@fragment fn fs() -> @location(0) vec4<f32> {',
+        '  _ = radicalInverseVdC(5u);',
+        '  return vec4<f32>(1.0);',
+        '}',
+      ].join('\n');
+      const composed = await composeShader(
+        entry,
+        {
+          'forgeax_pbr::ibl_shared': shared,
+          'forgeax_pbr::ibl_equirect_to_cube': equirect,
+        },
+        {},
+      );
+      const parsed = await parse(composed);
+      expect(parsed).not.toBeNull();
+    },
+  );
+});

package/src/__tests__/dawn/ibl-precompute-readback.dawn.test.ts

@@ -0,0 +1,250 @@
+// t51 (M3.5) -- dawn 4-pass IBL precompute readback (red-phase).
+//
+// Real GPU (dawn-node / webgpu native binding) test: feeds a 4x2 rgba16float
+// all-ones equirect into uploadCubemapFromEquirect, then reads back one
+// pixel from each of the 4 produced textures. All 4 pixels must be
+// non-zero -- a zero readback means the GPU pass never ran (round-1
+// counter-as-dispatch-proxy regression).
+//
+// Red phase: before t52/t53 wire real createIblPipelines + runIblPrecompute,
+// the cubemap / irradiance / prefilter / brdfLut textures are created but
+// never drawn into, so every readback pixel is vec4(0).
+//
+// Green phase: t52/t53 land 4 real render passes + queue.submit; readback
+// pixels carry non-zero values (white equirect -> bright cube -> non-zero
+// irradiance / prefilter / brdfLut).
+
+import { World } from '@forgeax/engine-ecs';
+import { composeShader } from '@forgeax/engine-naga';
+import { ok, type RhiDevice, type Texture } from '@forgeax/engine-rhi';
+import { _internal_getRawDevice, createShaderModule, rhi } from '@forgeax/engine-rhi-webgpu';
+import type { EquirectAsset, TextureFormat } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { DeviceScope } from '../../../../render/src/device/device-scope';
+import { GpuResidencyCache } from '../../../../render/src/device/gpu-residency';
+import {
+  getOrCreateIblCache,
+  setIblComposedShaders,
+} from '../../../../render/src/ibl/IblPipelineCache';
+
+const mockCaps = {
+  backendKind: 'webgpu' as const,
+  compute: true,
+  timestampQuery: false,
+  timestampPeriodNanoseconds: null,
+  indirectDrawing: false,
+  textureCompressionBc: false,
+  textureCompressionEtc2: false,
+  textureCompressionAstc: false,
+  multiDrawIndirect: false,
+  pushConstants: false,
+  textureBindingArray: false,
+  samplerAliasing: false,
+  firstInstanceIndirect: false,
+  storageBuffer: true,
+  storageTexture: false,
+  rgba16floatRenderable: true,
+  rg11b10ufloatRenderable: false,
+  float32Filterable: false,
+  maxColorAttachments: 8,
+};
+
+// feat-20260601-device/gpu-residency-extraction M1 (D-3 falsifiable anchor): a
+// single store._uploadCubemapFromEquirect(world, srcHandle, srcPod) returns the
+// cube handle, and store.getCubemapGpuTexture(cubeHandle) reads it back -- the
+// single-call contract is preserved. The cube POD register-relay is injected
+// at configureGpuDevice and mints via world.allocSharedRef (the store holds no
+// registry reference, D-3).
+
+// Load + compose the 6 ibl-* WGSL modules into the 4 composed entry shaders
+// that createIblPipelines consumes. Mirrors what vite-plugin-shader does at
+// build-time for the browser/runtime path; the dawn test stands in for
+// vite-plugin-shader so the readback receives non-placeholder pipelines.
+async function composeIblShadersForDawn(): Promise<void> {
+  const fsId = 'node:fs';
+  const pathId = 'node:path';
+  const urlId = 'node:url';
+  const fs = (await import(/* @vite-ignore */ fsId)) as {
+    readFileSync: (p: string, enc: string) => string;
+  };
+  const pathMod = (await import(/* @vite-ignore */ pathId)) as {
+    resolve: (...parts: string[]) => string;
+    dirname: (p: string) => string;
+  };
+  const url = (await import(/* @vite-ignore */ urlId)) as {
+    fileURLToPath: (u: string) => string;
+  };
+  const here = url.fileURLToPath(import.meta.url);
+  // Resolve packages/shader/src/ relative to this test file
+  // (packages/runtime/src/__tests__/dawn/).
+  const shaderSrc = pathMod.resolve(pathMod.dirname(here), '..', '..', '..', '..', 'shader', 'src');
+  const read = (name: string) => fs.readFileSync(pathMod.resolve(shaderSrc, name), 'utf8');
+  const sharedSrc = read('ibl-shared.wgsl');
+  const equirectSrc = read('ibl-equirect-to-cube.wgsl');
+  const irradianceSrc = read('ibl-irradiance.wgsl');
+  const prefilterSrc = read('ibl-prefilter.wgsl');
+  const brdfLutSrc = read('ibl-brdf-lut.wgsl');
+  // ibl-shared is the only #import the per-pass modules reference.
+  const imports = { 'forgeax_pbr::ibl_shared': sharedSrc };
+  const [equirectToCube, irradiance, prefilter, brdfLut] = await Promise.all([
+    composeShader(equirectSrc, imports, {}),
+    composeShader(irradianceSrc, imports, {}),
+    composeShader(prefilterSrc, imports, {}),
+    composeShader(brdfLutSrc, imports, {}),
+  ]);
+  setIblComposedShaders({ equirectToCube, irradiance, prefilter, brdfLut });
+}
+
+const dawnReady = typeof navigator !== 'undefined' && navigator.gpu !== undefined;
+
+function makeWhiteEquirect(): EquirectAsset {
+  // 4x2 rgba16float, all 1.0 (HDR white). 16-bit float 1.0 = 0x3C00 = 15360.
+  const w = 4;
+  const h = 2;
+  const data = new Uint8Array(w * h * 8);
+  const dv = new DataView(data.buffer);
+  for (let i = 0; i < w * h * 4; i++) {
+    dv.setUint16(i * 2, 0x3c00, true);
+  }
+  return {
+    kind: 'equirect',
+    width: w,
+    height: h,
+    format: 'rgba16float' as TextureFormat,
+    data,
+    colorSpace: 'linear',
+  };
+}
+
+/** Raw resource conversion is confined to this Dawn readback boundary. */
+function rawTexture(texture: Texture): GPUTexture {
+  return texture as unknown as GPUTexture;
+}
+
+async function readbackRgba16f(
+  device: GPUDevice,
+  texture: GPUTexture,
+  arrayLayer: number,
+  mipLevel: number,
+): Promise<number[]> {
+  // Read one pixel from (0,0) of (face=arrayLayer, mip=mipLevel).
+  const bytesPerRow = 256;
+  const buffer = device.createBuffer({
+    size: bytesPerRow,
+    usage: 0x0001 | 0x0008, // MAP_READ | COPY_DST
+  });
+  const encoder = device.createCommandEncoder({ label: 'ibl-readback' });
+  encoder.copyTextureToBuffer(
+    { texture, mipLevel, origin: { x: 0, y: 0, z: arrayLayer } },
+    { buffer, bytesPerRow },
+    { width: 1, height: 1, depthOrArrayLayers: 1 },
+  );
+  device.queue.submit([encoder.finish()]);
+  await buffer.mapAsync(0x0001 /* MAP_READ */);
+  const range = buffer.getMappedRange();
+  const dv = new DataView(range.slice(0));
+  buffer.unmap();
+  const f16ToF32 = (u16: number) => {
+    const sign = (u16 & 0x8000) >> 15;
+    const exp = (u16 & 0x7c00) >> 10;
+    const frac = u16 & 0x03ff;
+    if (exp === 0) return (sign ? -1 : 1) * 2 ** -14 * (frac / 1024);
+    if (exp === 0x1f) return frac ? Number.NaN : (sign ? -1 : 1) * Number.POSITIVE_INFINITY;
+    return (sign ? -1 : 1) * 2 ** (exp - 15) * (1 + frac / 1024);
+  };
+  return [
+    f16ToF32(dv.getUint16(0, true)),
+    f16ToF32(dv.getUint16(2, true)),
+    f16ToF32(dv.getUint16(4, true)),
+    f16ToF32(dv.getUint16(6, true)),
+  ];
+}
+
+describe('t51 (M3.5) -- dawn IBL 4-pass non-zero readback', () => {
+  it.skipIf(!dawnReady)(
+    'AC-04/05/06: equirect / irradiance / prefilter / brdfLut readback pixels are non-zero',
+    async () => {
+      // Compose ibl-* WGSL into 4 entry shaders before the upload. In
+      // production this happens at vite-plugin-shader build-time and the
+      // runtime calls setIblComposedShaders with the composed bundle;
+      // dawn-node tests stand in for vite-plugin-shader by composing on
+      // demand via @forgeax/engine-naga.
+      await composeIblShadersForDawn();
+      const adapterResult = await rhi.requestAdapter();
+      if (!adapterResult.ok) throw adapterResult.error;
+      const deviceResult = await adapterResult.value.requestDevice();
+      if (!deviceResult.ok) throw deviceResult.error;
+      const rhiDevice: RhiDevice = deviceResult.value;
+      const rawDevice = _internal_getRawDevice(rhiDevice);
+      if (rawDevice === undefined) {
+        throw new Error('Dawn IBL readback requires the RHI WebGPU raw-device test boundary');
+      }
+
+      const store = new GpuResidencyCache();
+      const scope = DeviceScope.create(0, 'ibl-dawn-test');
+      store.bindDeviceScope(scope);
+      const world = new World();
+      const equirect = makeWhiteEquirect();
+      const equirectHandle = world.allocSharedRef('EquirectAsset', equirect);
+
+      // The production path receives the opaque RhiDevice and the same
+      // Result-returning shader factory used by the WebGPU backend. Raw GPU
+      // access remains confined to readback below.
+      store.configureGpuDevice(
+        rhiDevice,
+        undefined,
+        (w: World, pod: EquirectAsset) => ok(w.allocSharedRef('EquirectAsset', pod)),
+        mockCaps,
+      );
+      store.configureIblDevice(rhiDevice, createShaderModule);
+
+      // Single call returns the cube handle (D-3 single-call contract). The
+      // projection method is @internal (private) after feat-20260630 M2 / w11;
+      // the dawn test reaches it through the store internals.
+      const result = await store._uploadCubemapFromEquirect(world, equirectHandle, equirect);
+      expect(result.ok).toBe(true);
+      if (!result.ok) return;
+
+      const cubeHandle = result.value;
+      const cubeTexture = store.getCubemapGpuTexture(cubeHandle);
+      expect(cubeTexture).toBeDefined();
+      if (cubeTexture === undefined) return;
+
+      // feat-20260612 M3 / w11 (1c76c1b9): GpuResidencyCache handle maps now
+      // hold the GpuTexture wrapper (`{handle, isDestroyed, destroy()}`).
+      // dawn-node `copyTextureToBuffer` consumes the raw GPUTexture handle,
+      // so the wrapper unwrap goes via `.handle` here. The IBL cache slots
+      // below still hold raw textures (the ibl/IblPipelineCache wrapping is
+      // OOS for this feat -- D-8 / OOS-10).
+      const cubeRaw = rawTexture(cubeTexture.handle);
+
+      // (a) equirect-to-cube face 0 center pixel != 0
+      const cubePx = await readbackRgba16f(rawDevice, cubeRaw, 0, 0);
+      expect(cubePx.some((c) => c !== 0)).toBe(true);
+
+      // (b) irradiance, (c) prefilter, (d) brdfLut: the textures live on
+      // IblPipelineCache after t52/t53. Read opaque cache slots through the
+      // test-only raw texture boundary.
+      const cache = getOrCreateIblCache(scope);
+      const {
+        irradianceTexture: irrTex,
+        prefilterTexture: prefTex,
+        brdfLutTexture: brdfTex,
+      } = cache;
+      expect(irrTex).toBeDefined();
+      expect(prefTex).toBeDefined();
+      expect(brdfTex).toBeDefined();
+      if (irrTex === undefined || prefTex === undefined || brdfTex === undefined) return;
+
+      const irrPx = await readbackRgba16f(rawDevice, rawTexture(irrTex), 0, 0);
+      expect(irrPx.some((c) => c !== 0)).toBe(true);
+
+      const prefPx = await readbackRgba16f(rawDevice, rawTexture(prefTex), 0, 0);
+      expect(prefPx.some((c) => c !== 0)).toBe(true);
+
+      const brdfPx = await readbackRgba16f(rawDevice, rawTexture(brdfTex), 0, 0);
+      expect(brdfPx.some((c) => c !== 0)).toBe(true);
+    },
+    60_000,
+  );
+});