@forgeax/engine-render 0.1.28 → 0.1.30

package/src/__tests__/volumetric-fog-stage-readback.dawn.test.ts

@@ -73,7 +73,13 @@ async function requestDevice(): Promise<RhiDevice> {
   return device.value;
 }
 
-async function runInjectReadback(sceneDepthClear = 1): Promise<VolumeStageReadbacks> {
+async function runInjectReadback(
+  sceneDepthClear = 1,
+  densitySource: number | 'height-gradient' | 'depth-gradient' = 255,
+  heightOffset = 0,
+  frameIndex = 0,
+  slopedShadow = false,
+): Promise<VolumeStageReadbacks> {
   const device = await requestDevice();
   const moduleResult = await createShaderModule(device, {
     code: manifestShader('fn volume_inject'),
@@ -227,22 +233,26 @@ async function runInjectReadback(sceneDepthClear = 1): Promise<VolumeStageReadba
   const viewData = new Float32Array(240);
   for (const offset of [0, 28, 44, 60, 76, 92, 196, 212]) identityMatrix(viewData, offset);
   viewData[24] = 0;
-  viewData[25] = 0;
+  viewData[25] = heightOffset;
+  viewData[44 + 13] = heightOffset;
   viewData[26] = -1;
-  viewData[124] = 0;
+  viewData[124] = slopedShadow ? 1 : 0;
+  viewData[108] = 10;
+  if (slopedShadow) viewData[28 + 2] = 0.5;
   viewData[228] = 0.1;
   viewData[229] = 10;
   viewData[230] = 0;
   viewData[235] = 1;
   const paramsData = new Float32Array(32);
-  paramsData.set([-1, -1, 0.1, 0], 0);
-  paramsData.set([1, 1, 0.9, 0], 4);
+  paramsData.set([-1, heightOffset - 1, 0.1, 0], 0);
+  paramsData.set([1, heightOffset + 1, 0.9, 0], 4);
   paramsData.set([1, 1, 1, 0], 8);
   paramsData.set([1, 1, 1, 0], 12);
   paramsData.set([0, 0, 0, 0], 16);
   paramsData.set([0, -1, 0, 0], 20);
   paramsData.set([1, 1, 1, 0], 24);
   paramsData.set([2, 0, 0, 0], 28);
+  paramsData[23] = frameIndex;
   const lightData = new Uint8Array(CLUSTER_LIGHT_DATA_BYTES);
   const clusterUniformData = new Float32Array(8);
   const clusterGrid = new Uint32Array(clusterUniformData.buffer);
@@ -261,7 +271,21 @@ async function runInjectReadback(sceneDepthClear = 1): Promise<VolumeStageReadba
   if (!viewWrite.ok || !paramsWrite.ok || !lightDataWrite.ok || !clusterUniformWrite.ok)
     throw new Error('Dawn volume stage readback unavailable: uniform upload failed');
   const densityData = new Uint8Array((BYTES_PER_PIXEL / 2) * SIZE * SIZE * SIZE);
-  densityData.fill(255);
+  for (let z = 0; z < SIZE; z++)
+    for (let y = 0; y < SIZE; y++)
+      for (let x = 0; x < SIZE; x++) {
+        const value =
+          densitySource === 'height-gradient'
+            ? Math.round((y / (SIZE - 1)) * 255)
+            : densitySource === 'depth-gradient'
+              ? Math.round((z / (SIZE - 1)) * 255)
+              : densitySource;
+        densityData.fill(
+          value,
+          ((z * SIZE + y) * SIZE + x) * 4,
+          ((z * SIZE + y) * SIZE + x + 1) * 4,
+        );
+      }
   const densityWrite = device.queue.writeTexture(
     { texture: densityTexture.value },
     densityData,
@@ -438,7 +462,7 @@ async function runInjectReadback(sceneDepthClear = 1): Promise<VolumeStageReadba
       colorAttachments: [],
       depthStencilAttachment: {
         view,
-        depthClearValue: index === 0 ? sceneDepthClear : 1,
+        depthClearValue: index === 0 ? sceneDepthClear : slopedShadow ? 0.5 : 1,
         depthLoadOp: 'clear',
         depthStoreOp: 'store',
       },
@@ -520,6 +544,22 @@ async function runInjectReadback(sceneDepthClear = 1): Promise<VolumeStageReadba
 }
 
 describe('volumetric fog production stage readback on Dawn', () => {
+  it('keeps static shadow visibility stable across renderer frame phases', async () => {
+    const first = await runInjectReadback(1, 255, 0, 0, true);
+    const next = await runInjectReadback(1, 255, 0, 1, true);
+    expect(first.inject.red.some((value) => value === 0)).toBe(true);
+    expect(first.inject.red.some((value) => value > 0.9)).toBe(true);
+    expect(next.inject).toEqual(first.inject);
+  });
+  it('keeps a static depth-density field stable across renderer frame phases', async () => {
+    const first = await runInjectReadback(1, 'depth-gradient', 0, 0);
+    for (const frameIndex of [1, 7]) {
+      const next = await runInjectReadback(1, 'depth-gradient', 0, frameIndex);
+      expect(next.integrate.alpha).toEqual(first.integrate.alpha);
+      expect(next.integrate.red).toEqual(first.integrate.red);
+    }
+    expect(first.integrate.alpha[0]).toBeCloseTo(Math.exp(-0.4), 2);
+  });
   it('injects raw density then resolves a 2d integrated volume', async () => {
     const values = await runInjectReadback();
     // biome-ignore lint/suspicious/noConsole: stage readback is machine evidence
@@ -542,12 +582,21 @@ describe('volumetric fog production stage readback on Dawn', () => {
   it('clips the final ray step to the scene-depth segment', async () => {
     const values = await runInjectReadback(0.57);
     const transmittance = values.integrate.alpha[0];
-    // The fixture uploads an all-white source texture. The authored Three
-    // smoke expression therefore evaluates to 2 * 1.5^3 - 1 = 5.75 before
-    // Beer-Lambert consumes it; only the final 0.47-unit segment is allowed
-    // to contribute after the scene-depth clip.
-    const sourceDensity = 2 * 1.5 ** 3 - 1;
-    expect(transmittance).toBeCloseTo(Math.exp(-0.47 * sourceDensity), 2);
+    // White encodes density one; integrate only the visible 0.47-unit segment.
+    expect(transmittance).toBeCloseTo(Math.exp(-0.47), 2);
     expect(values.integrate.red[0]).toBeGreaterThan(0);
   });
+  it.each([0, 64, 128])('preserves authored uniform density %s/255', async (densityByte) => {
+    const values = await runInjectReadback(0.57, densityByte);
+    expect(values.integrate.alpha[0]).toBeCloseTo(Math.exp((-0.47 * densityByte) / 255), 2);
+    if (densityByte === 0) expect(values.integrate.red.every((value) => value === 0)).toBe(true);
+  });
+
+  it.each([
+    0, 20,
+  ])('maps height density through world bounds translated by %s', async (heightOffset) => {
+    const values = await runInjectReadback(0.57, 'height-gradient', heightOffset);
+    expect(values.integrate.alpha[0]).toBeCloseTo(Math.exp(-0.47), 2);
+    expect(values.integrate.alpha[(SIZE - 1) * SIZE]).toBeCloseTo(1, 3);
+  });
 });

package/src/__tests__/volumetric-fog-topology.unit.test.ts

@@ -34,9 +34,9 @@ describe('volumetric fog RenderGraph topology', () => {
     expect(composite).toContain('abs(neighbor.a - center.a) * 6.0');
   });
 
-  it('uses the pinned twelve-step ray integration while retaining packed visibility depth', () => {
+  it('derives deterministic integration density from the authored froxel depth', () => {
     const integrate = shaderSource('volume-integrate.wgsl');
-    expect(integrate).toContain('let ray_step_count = 12u;');
+    expect(integrate).toContain('let ray_step_count = visibility_depth;');
     expect(integrate).toContain('for (var step = 0u; step < ray_step_count; step = step + 1u)');
     expect(integrate).toContain('let visibility_depth = max(textureNumLayers(froxel) * 4u, 1u);');
   });
@@ -44,7 +44,7 @@ describe('volumetric fog RenderGraph topology', () => {
   it('keeps the Beer-Lambert extinction input physically non-negative', () => {
     const integrate = shaderSource('volume-integrate.wgsl');
     expect(integrate).toContain(
-      'let density_value = max(volume_scattering_density(world_position, frame_index), 0.0);',
+      'let density_value = max(volume_scattering_density(world_position), 0.0);',
     );
   });
 
@@ -130,8 +130,8 @@ describe('volumetric fog RenderGraph topology', () => {
     expect(shaderSource('volume-inject.wgsl')).toContain('fn ray_box_interval');
     expect(shaderSource('volume-inject.wgsl')).toContain('view.inverseViewProj');
     expect(shaderSource('volume-inject.wgsl')).not.toContain('textureSampleLevel(density');
-    expect(shaderSource('volume-inject.wgsl')).toContain('stratified32');
-    expect(shaderSource('volume-inject.wgsl')).toContain('dither_unorm8');
+    expect(shaderSource('volume-inject.wgsl')).not.toContain('stratified32');
+    expect(shaderSource('volume-inject.wgsl')).not.toContain('dither_unorm8');
     expect(shaderSource('volume-integrate.wgsl')).toContain('exp(-sigma_scale');
     expect(shaderSource('volume-integrate.wgsl')).toContain('textureSampleLevel(froxel');
     expect(shaderSource('volume-integrate.wgsl')).toContain('textureStore(resolved');
@@ -159,8 +159,8 @@ describe('volumetric fog RenderGraph topology', () => {
     const integrate = shaderSource('volume-integrate.wgsl');
     expect(inject).toContain('(f32(logical_slice) + 0.5) / f32(logical_depth)');
     expect(inject).not.toContain('depth_phase');
-    expect(integrate).toContain('fn stratified32');
-    expect(integrate).toContain('segment_start + segment_length * depth_phase');
+    expect(integrate).not.toContain('fn stratified32');
+    expect(integrate).toContain('segment_start + segment_length * 0.5');
   });
 
   it('keeps temporal history graph-owned and slot-selectable', () => {

package/src/assembly/atmosphere-shader-prewarm.ts

@@ -0,0 +1,39 @@
+import { RhiError, type ShaderModule } from '@forgeax/engine-rhi';
+import type { ManifestEntry } from '@forgeax/engine-types';
+import type { AtmosphereShaderSources } from '../render-contract';
+
+/** Admit and compile the complete analytic-atmosphere shader programs atomically. */
+export async function prewarmAtmosphereShaders(
+  entries: readonly ManifestEntry[],
+  compile: (label: string, source: string) => Promise<ShaderModule>,
+  seed: (label: string, module: ShaderModule) => void,
+): Promise<AtmosphereShaderSources | undefined> {
+  const stages = [
+    ['cube', 'atmosphere_cube', 'atmosphere_cubemap_vs'],
+    ['background', 'atmosphere_background', 'atmosphere_background_vs'],
+    ['ibl', 'atmosphere_ibl', 'atmosphere_ibl_vs'],
+  ] as const;
+  const resolved = stages.map(([stage, label, entryPoint]) => ({
+    stage,
+    label,
+    entry: entries.find((entry) => entry.wgsl.includes(`fn ${entryPoint}(`)),
+  }));
+  if (resolved.every(({ entry }) => entry === undefined)) return undefined;
+  const missing = resolved.find(({ entry }) => entry === undefined);
+  if (missing !== undefined) {
+    throw new RhiError({
+      code: 'shader-compile-failed',
+      expected: 'shader manifest contains all analytic-atmosphere utility entries',
+      hint: `add the package-owned WGSL entry for '${missing.label}' to the engine shader manifest`,
+    });
+  }
+  const compiled: Array<{ label: string; module: ShaderModule }> = [];
+  const sources = {} as Record<keyof AtmosphereShaderSources, string>;
+  for (const { stage, label, entry } of resolved) {
+    if (entry === undefined) throw new Error(`missing atmosphere shader ${label}`);
+    compiled.push({ label, module: await compile(label, entry.wgsl) });
+    sources[stage] = entry.wgsl;
+  }
+  for (const { label, module } of compiled) seed(label, module);
+  return sources;
+}

package/src/assembly/device-feature-admission.ts

@@ -1,5 +1,6 @@
 import type { RhiAdapter, RhiDevice } from '@forgeax/engine-rhi';
 import { EXTENDED_LIGHTING_REQUIRED_SAMPLED_TEXTURES } from '../prepare/extended-lighting/resources';
+import { STANDARD_PBR_REQUIRED_SAMPLED_TEXTURES } from './shader-prewarm-policy';
 
 const COMPRESSION_FEATURES: GPUFeatureName[] = [
   'texture-compression-bc',
@@ -7,13 +8,17 @@ const COMPRESSION_FEATURES: GPUFeatureName[] = [
   'texture-compression-astc',
 ];
 
-// The Standard transmission fragment ABI needs 17 sampled textures across its
+// The Standard transmission fragment ABI needs 18 sampled textures across its
 // material, IBL, clustered-light, and SSAO bindings. Ordinary Standard draws
 // use the non-transmission variant and remain valid on the WebGPU minimum of
-// 16. The extended-lighting topology reserves 20, so a device descriptor must
+// 16. The extended-lighting topology reserves 21, so a device descriptor must
 // request that larger limit when the adapter can provide it; adapter limits are
 // not automatically inherited by requestDevice().
-export const STANDARD_PBR_REQUIRED_SAMPLED_TEXTURES = 17;
+export { STANDARD_PBR_REQUIRED_SAMPLED_TEXTURES };
+
+export function transmissionBackdropAvailable(limit: number | undefined): boolean {
+  return limit === undefined || limit >= STANDARD_PBR_REQUIRED_SAMPLED_TEXTURES;
+}
 /**
  * The complete Standard physical root can declare all optional texture slots.
  * Its material group therefore needs one more sampled-texture entry than the
@@ -21,7 +26,7 @@ export const STANDARD_PBR_REQUIRED_SAMPLED_TEXTURES = 17;
  * provide it; lower-capability devices remain fail-closed at material
  * pipeline admission instead of receiving an invalid WebGPU layout.
  */
-export const STANDARD_PHYSICAL_REQUIRED_SAMPLED_TEXTURES = 21;
+export const STANDARD_PHYSICAL_REQUIRED_SAMPLED_TEXTURES = 22;
 
 export interface DeviceFeatureAdmissionOptions {
   readonly gpuPassTiming?: object | undefined;