@forgeax/engine-render 0.1.7 → 0.1.19

package/src/record/shadow-pass.ts

@@ -16,7 +16,11 @@ import {
 } from '../gpu-usage';
 import { assembleMaterialWithSkylightEntries } from '../ibl/skylight-bind-group';
 import type { InstanceBufferCacheEntry } from '../instance-buffer-cache';
-import { buildPbrMaterialUserRegionEntries } from '../pbr-pipeline';
+import {
+  buildPbrMaterialUserRegionEntries,
+  SHADOW_CASTER_SHADER_ID,
+  shadowCasterVariantSet,
+} from '../pbr-pipeline';
 import type { DispatchEntry, ExtractedLights } from '../render-system-extract';
 import { matchPass } from '../systems/pass-selector';
 import { worldEntityKey } from './frame-snapshot';
@@ -25,6 +29,8 @@ import {
   getOrCreatePerEntity,
   MAX_UNIFORM_INSTANCES,
   MESH_PER_ENTITY_STRIDE,
+  MESH_SSBO_BYTES,
+  MESH_UBO_FULL_ARRAY_BYTES,
   packInstanceStorageBuffer,
 } from './mesh-ssbo';
 import type { _InternalRenderPipelineContext } from './render-context';
@@ -188,17 +194,97 @@ function shadowShaderMap(c: _InternalRenderPipelineContext): ReadonlyMap<number,
 function shadowPipeline(c: _InternalRenderPipelineContext): RenderPipeline | null {
   return (
     c.runtime.getMaterialShaderPipeline?.(
-      'forgeax::default-shadow-caster',
+      SHADOW_CASTER_SHADER_ID,
       false,
       undefined,
       'triangle-list',
       undefined,
+      shadowCasterVariantSet(c.runtime.device.caps.storageBuffer, false),
+      'shadow-caster',
+      undefined,
+      undefined,
+      undefined,
+      undefined,
       undefined,
+      undefined,
+      undefined,
+      undefined,
+      'pbr',
+    ) ?? null
+  );
+}
+
+function skinnedShadowPipeline(
+  c: _InternalRenderPipelineContext,
+  entry: _InternalRenderPipelineContext['validatedOrdered'][number],
+): RenderPipeline | null {
+  return (
+    c.runtime.getMaterialShaderPipeline?.(
+      SHADOW_CASTER_SHADER_ID,
+      false,
+      undefined,
+      entry.mesh.submeshes[0]?.topology ?? 'triangle-list',
+      entry.mesh.indexFormat,
+      shadowCasterVariantSet(c.runtime.device.caps.storageBuffer, true),
       'shadow-caster',
+      undefined,
+      1,
+      undefined,
+      undefined,
+      undefined,
+      undefined,
+      entry.mesh.layoutProjection,
+      undefined,
+      'pbr-skin',
     ) ?? null
   );
 }
 
+function skinnedShadowMeshBindGroup(
+  c: _InternalRenderPipelineContext,
+  entry: _InternalRenderPipelineContext['validatedOrdered'][number],
+): BindGroup | null {
+  const skin = entry.source.skin;
+  const layout = c.pipelineState.pbrSkinMeshBindGroupLayout;
+  const allocator = c.pipelineState.skinPaletteAllocator;
+  if (skin === undefined || layout === null || allocator === null) return null;
+  return getOrCreateFromChain(
+    c.frameState.meshBindGroupCache,
+    [c.pipelineState.meshStorageBuffer.buffer, skin.buffer],
+    'shadow-pbr-skin-mesh',
+    () => {
+      const created = c.runtime.device.createBindGroup({
+        label: 'shadow-pbr-skin-mesh-bg',
+        layout,
+        entries: [
+          {
+            binding: 0,
+            resource: {
+              kind: 'buffer',
+              value: {
+                buffer: c.pipelineState.meshStorageBuffer.buffer,
+                size: c.runtime.device.caps.storageBuffer
+                  ? MESH_SSBO_BYTES
+                  : MESH_UBO_FULL_ARRAY_BYTES,
+              },
+            },
+          },
+          {
+            binding: 1,
+            resource: {
+              kind: 'buffer',
+              value: { buffer: skin.buffer, size: allocator.bindingWindowBytes },
+            },
+          },
+        ],
+      });
+      if (!created.ok) throw created.error;
+      return created.value;
+    },
+    c.bindGroupCounts,
+  );
+}
+
 export function encodeDirectionalShadowPass(
   c: _InternalRenderPipelineContext,
   pass: RhiRenderPassEncoder,
@@ -441,9 +527,13 @@ function recordShadowCasterDraws(
     // its own fragment-carrying PSO so `discard` runs in the depth pass.
     const entryShadowShaderId = shadowShaderByRenderableIdx.get(entry.renderableIndex);
     let entryShadowPipeline = shadowPipeline;
-    if (
+    if (entry.source.skin !== undefined) {
+      const skinPipeline = skinnedShadowPipeline(c, entry);
+      if (skinPipeline === null) continue;
+      entryShadowPipeline = skinPipeline;
+    } else if (
       entryShadowShaderId !== undefined &&
-      entryShadowShaderId !== 'forgeax::default-shadow-caster'
+      entryShadowShaderId !== SHADOW_CASTER_SHADER_ID
     ) {
       // Custom ShadowCaster PSO; same cache path as the default above
       // (passKind 'shadow-caster'). On a cache miss (async build in
@@ -494,7 +584,16 @@ function recordShadowCasterDraws(
       }
     }
 
-    shadowPass.setBindGroup(2, shadowMeshBindGroup, [i * MESH_PER_ENTITY_STRIDE]);
+    if (entry.source.skin !== undefined) {
+      const skinMeshBindGroup = skinnedShadowMeshBindGroup(c, entry);
+      if (skinMeshBindGroup === null) continue;
+      shadowPass.setBindGroup(2, skinMeshBindGroup, [
+        i * MESH_PER_ENTITY_STRIDE,
+        entry.source.skin.byteOffset,
+      ]);
+    } else {
+      shadowPass.setBindGroup(2, shadowMeshBindGroup, [i * MESH_PER_ENTITY_STRIDE]);
+    }
 
     // C1 + C2 (w12): per-entity instance buffer + instanceCount
     let shadowInstanceBuffer: Buffer = pipelineState.identityInstanceBuffer;
@@ -663,24 +762,15 @@ function ensureSpotShadowMaterialBg(c: _InternalRenderPipelineContext): BindGrou
   });
   const merged =
     fb !== null
-      ? assembleMaterialWithSkylightEntries(
-          fallbackEntries,
-          {
-            irradianceView: fb.irradianceView,
-            irradianceSampler: fb.sampler,
-            prefilterView: fb.prefilterView,
-            prefilterSampler: fb.sampler,
-            brdfLutView: fb.brdfLutView,
-            brdfLutSampler: fb.sampler,
-            intensityBuffer: fb.intensityBuffer,
-          },
-          {
-            emissiveSampler: pipelineState.defaultSampler,
-            emissiveView: pipelineState.defaultWhiteTextureView,
-            occlusionSampler: pipelineState.defaultSampler,
-            occlusionView: pipelineState.defaultWhiteTextureView,
-          },
-        )
+      ? assembleMaterialWithSkylightEntries(fallbackEntries, {
+          irradianceView: fb.irradianceView,
+          irradianceSampler: fb.sampler,
+          prefilterView: fb.prefilterView,
+          prefilterSampler: fb.sampler,
+          brdfLutView: fb.brdfLutView,
+          brdfLutSampler: fb.sampler,
+          intensityBuffer: fb.intensityBuffer,
+        })
       : fallbackEntries;
   const r = runtime.device.createBindGroup({
     label: 'shadow-material-bg',

package/src/record/skybox-post-pass.ts

@@ -1,7 +1,8 @@
 import type { ResolveContext } from '@forgeax/engine-render-graph';
-import type { RhiRenderPassEncoder, TextureView } from '@forgeax/engine-rhi';
+import { RhiError, type RhiRenderPassEncoder, type TextureView } from '@forgeax/engine-rhi';
 import { toShared } from '@forgeax/engine-types';
 import { buildBeginRenderPassDescriptor } from '../pipeline-spec';
+import type { BloomFrameReceipts } from './frame-snapshot';
 import { getOrCreateFromChain } from './mesh-ssbo';
 import type { _InternalRenderPipelineContext } from './render-context';
 import { VIEW_UNIFORM_BYTES } from './view-ubo';
@@ -177,30 +178,72 @@ export function encodeSkyboxPass(
 // Gate: bloom === 'off' || !tonemapActive => early-return (AC-04/AC-05).
 // The closures receive RenderPipelineContext and route to w15 record functions.
 
+const EMPTY_BLOOM_RECEIPTS: BloomFrameReceipts = {
+  uploadCount: 0,
+  bindGroupCount: 0,
+  encodeCount: 0,
+};
+
+function updateBloomReceipts(
+  c: _InternalRenderPipelineContext,
+  field: keyof BloomFrameReceipts,
+): void {
+  const current = c.frameState.bloomFrameReceipts ?? EMPTY_BLOOM_RECEIPTS;
+  c.frameState.bloomFrameReceipts = {
+    ...current,
+    [field]: current[field] + 1,
+  };
+}
+
+function stageBloomUpload(c: _InternalRenderPipelineContext): void {
+  updateBloomReceipts(c, 'uploadCount');
+}
+
+function stageBloomBindGroup(c: _InternalRenderPipelineContext): void {
+  updateBloomReceipts(c, 'bindGroupCount');
+}
+
+function stageBloomEncode(c: _InternalRenderPipelineContext): void {
+  updateBloomReceipts(c, 'encodeCount');
+}
+
+function throwBloomRecordFailure(expected: string): never {
+  throw new RhiError({
+    code: 'webgpu-runtime-error',
+    expected,
+    hint: 'repair the Bloom candidate resources before retrying the frame',
+  });
+}
+
 export function recordBloomBrightPass(
   _c: _InternalRenderPipelineContext,
   resolve?: ResolveContext,
   graphPass?: RhiRenderPassEncoder,
 ): void {
-  const { runtime, pipelineState, encoder, camera, tonemapActive, frameState, bindGroupCounts } =
-    _c;
-  const pp = pipelineState.perPassResources;
+  const { runtime, encoder, camera, tonemapActive, frameState, bindGroupCounts } = _c;
+  const pp = _c.bloomResources;
 
   // Double gate: bloom=off => zero-overhead; tonemap=none => no HDR domain
   if (camera.bloom !== 'on' || !tonemapActive) return;
+  if (pp === null || pp === undefined) {
+    throwBloomRecordFailure('Bloom persistent resources are ready before bright-pass encoding');
+  }
   if (
     pp.bloomBrightPipeline === null ||
     pp.bloomBrightBindGroupLayout === null ||
     pp.bloomSampler === null ||
     pp.bloomBrightParamsBuffer === null
-  )
-    return;
+  ) {
+    throwBloomRecordFailure('Bloom bright pass has pipeline, layout, sampler, and params buffer');
+  }
 
   // M1 / w7: bloom intermediate textures owned by render-graph. Resolve
   // the GPU TextureView via the resolve context passed by graph.execute().
   const bloomBrightView = resolve?.resolve('bloomBright') as TextureView | undefined;
   const hdrColorView = resolve?.resolve('hdrColor') as TextureView | undefined;
-  if (!bloomBrightView || !hdrColorView) return;
+  if (!bloomBrightView || !hdrColorView) {
+    throwBloomRecordFailure('Bloom bright pass resolves its source and target views');
+  }
   const bglBright = pp.bloomBrightBindGroupLayout;
   const bloomSampler = pp.bloomSampler;
   const paramsBuffer = pp.bloomBrightParamsBuffer;
@@ -213,6 +256,7 @@ export function recordBloomBrightPass(
   brightParams[3] = 0;
   const paramsWrite = runtime.device.queue.writeBuffer(paramsBuffer, 0, brightParams);
   if (!paramsWrite.ok) throw paramsWrite.error;
+  stageBloomUpload(_c);
 
   // 3. Identity-cached BindGroup (1 tex + 1 sampler + 1 UBO). Keyed on the
   // graph-resolved hdrColor TextureView: resize retires hdrColor and the new
@@ -249,7 +293,9 @@ export function recordBloomBrightPass(
     );
   pass.setPipeline(pp.bloomBrightPipeline);
   pass.setBindGroup(0, bindGroup);
+  stageBloomBindGroup(_c);
   pass.draw(3, 1, 0, 0);
+  stageBloomEncode(_c);
   if (graphPass === undefined) pass.end();
 }
 
@@ -258,32 +304,29 @@ export function recordBloomBlurHPass(
   resolve?: ResolveContext,
   graphPass?: RhiRenderPassEncoder,
 ): void {
-  const {
-    runtime,
-    pipelineState,
-    encoder,
-    camera,
-    targetW,
-    tonemapActive,
-    frameState,
-    bindGroupCounts,
-  } = _c;
-  const pp = pipelineState.perPassResources;
+  const { runtime, encoder, camera, targetW, tonemapActive, frameState, bindGroupCounts } = _c;
+  const pp = _c.bloomResources;
 
   if (camera.bloom !== 'on' || !tonemapActive) return;
+  if (pp === null || pp === undefined) {
+    throwBloomRecordFailure('Bloom persistent resources are ready before blur-H encoding');
+  }
   if (
     pp.bloomBlurHPipeline === null ||
     pp.bloomBlurBindGroupLayout === null ||
     pp.bloomSampler === null ||
     pp.bloomBlurHParamsBuffer === null
-  )
-    return;
+  ) {
+    throwBloomRecordFailure('Bloom blur-H pass has pipeline, layout, sampler, and params buffer');
+  }
 
   // M1 / w7: bloom intermediate textures owned by render-graph. Resolve
   // via the resolve context passed by graph.execute().
   const bloomBlurHView = resolve?.resolve('bloomBlurH') as TextureView | undefined;
   const bloomBrightView = resolve?.resolve('bloomBright') as TextureView | undefined;
-  if (!bloomBlurHView || !bloomBrightView) return;
+  if (!bloomBlurHView || !bloomBrightView) {
+    throwBloomRecordFailure('Bloom blur-H pass resolves its source and target views');
+  }
   const bglBlur = pp.bloomBlurBindGroupLayout;
   const bloomSampler = pp.bloomSampler;
   const paramsBuffer = pp.bloomBlurHParamsBuffer;
@@ -299,6 +342,7 @@ export function recordBloomBlurHPass(
   blurParams[3] = 0;
   const paramsWrite = runtime.device.queue.writeBuffer(paramsBuffer, 0, blurParams);
   if (!paramsWrite.ok) throw paramsWrite.error;
+  stageBloomUpload(_c);
 
   // 3. Identity-cached BindGroup (reads bloomBright from graph). Keyed on the
   // graph-resolved bloomBright view so resize rebuilds against the new texture.
@@ -334,7 +378,9 @@ export function recordBloomBlurHPass(
     );
   pass.setPipeline(pp.bloomBlurHPipeline);
   pass.setBindGroup(0, bindGroup);
+  stageBloomBindGroup(_c);
   pass.draw(3, 1, 0, 0);
+  stageBloomEncode(_c);
   if (graphPass === undefined) pass.end();
 }
 
@@ -343,32 +389,29 @@ export function recordBloomBlurVPass(
   resolve?: ResolveContext,
   graphPass?: RhiRenderPassEncoder,
 ): void {
-  const {
-    runtime,
-    pipelineState,
-    encoder,
-    camera,
-    targetH,
-    tonemapActive,
-    frameState,
-    bindGroupCounts,
-  } = _c;
-  const pp = pipelineState.perPassResources;
+  const { runtime, encoder, camera, targetH, tonemapActive, frameState, bindGroupCounts } = _c;
+  const pp = _c.bloomResources;
 
   if (camera.bloom !== 'on' || !tonemapActive) return;
+  if (pp === null || pp === undefined) {
+    throwBloomRecordFailure('Bloom persistent resources are ready before blur-V encoding');
+  }
   if (
     pp.bloomBlurVPipeline === null ||
     pp.bloomBlurBindGroupLayout === null ||
     pp.bloomSampler === null ||
     pp.bloomBlurVParamsBuffer === null
-  )
-    return;
+  ) {
+    throwBloomRecordFailure('Bloom blur-V pass has pipeline, layout, sampler, and params buffer');
+  }
 
   // M1 / w7: bloom intermediate textures owned by render-graph. Resolve
   // via the resolve context passed by graph.execute().
   const bloomBlurVView = resolve?.resolve('bloomBlurV') as TextureView | undefined;
   const bloomBlurHView = resolve?.resolve('bloomBlurH') as TextureView | undefined;
-  if (!bloomBlurVView || !bloomBlurHView) return;
+  if (!bloomBlurVView || !bloomBlurHView) {
+    throwBloomRecordFailure('Bloom blur-V pass resolves its source and target views');
+  }
   const bglBlur = pp.bloomBlurBindGroupLayout;
   const bloomSampler = pp.bloomSampler;
   const paramsBuffer = pp.bloomBlurVParamsBuffer;
@@ -384,6 +427,7 @@ export function recordBloomBlurVPass(
   blurParams[3] = 0;
   const paramsWrite = runtime.device.queue.writeBuffer(paramsBuffer, 0, blurParams);
   if (!paramsWrite.ok) throw paramsWrite.error;
+  stageBloomUpload(_c);
 
   // 3. Identity-cached BindGroup (reads bloomBlurH from graph). Keyed on the
   // graph-resolved bloomBlurH view so resize rebuilds against the new texture.
@@ -419,7 +463,9 @@ export function recordBloomBlurVPass(
     );
   pass.setPipeline(pp.bloomBlurVPipeline);
   pass.setBindGroup(0, bindGroup);
+  stageBloomBindGroup(_c);
   pass.draw(3, 1, 0, 0);
+  stageBloomEncode(_c);
   if (graphPass === undefined) pass.end();
 }
 
@@ -428,18 +474,23 @@ export function recordBloomCompositePass(
   resolve?: ResolveContext,
   graphPass?: RhiRenderPassEncoder,
 ): void {
-  const { runtime, pipelineState, encoder, camera, tonemapActive, frameState, bindGroupCounts } =
-    _c;
-  const pp = pipelineState.perPassResources;
+  const { runtime, encoder, camera, tonemapActive, frameState, bindGroupCounts } = _c;
+  const pp = _c.bloomResources;
 
   if (camera.bloom !== 'on' || !tonemapActive) return;
+  if (pp === null || pp === undefined) {
+    throwBloomRecordFailure('Bloom persistent resources are ready before composite encoding');
+  }
   if (
     pp.bloomCompositePipeline === null ||
     pp.bloomCompositeBindGroupLayout === null ||
     pp.bloomSampler === null ||
     pp.bloomCompositeParamsBuffer === null
-  )
-    return;
+  ) {
+    throwBloomRecordFailure(
+      'Bloom composite pass has pipeline, layout, sampler, and params buffer',
+    );
+  }
 
   // M1 / w7: hdrColor + bloomBlurV textures owned by render-graph.
   // bug-20260625: composite READS hdrColor (scene, binding 0) and WRITES the
@@ -447,7 +498,9 @@ export function recordBloomCompositePass(
   const hdrColorView = resolve?.resolve('hdrColor') as TextureView | undefined;
   const bloomBlurVView = resolve?.resolve('bloomBlurV') as TextureView | undefined;
   const hdrCompositedView = resolve?.resolve('hdrComposited') as TextureView | undefined;
-  if (!hdrColorView || !bloomBlurVView || !hdrCompositedView) return;
+  if (!hdrColorView || !bloomBlurVView || !hdrCompositedView) {
+    throwBloomRecordFailure('Bloom composite pass resolves its source and target views');
+  }
   const bglComposite = pp.bloomCompositeBindGroupLayout;
   const bloomSampler = pp.bloomSampler;
   const paramsBuffer = pp.bloomCompositeParamsBuffer;
@@ -460,6 +513,7 @@ export function recordBloomCompositePass(
   compositeParams[3] = 0;
   const paramsWrite = runtime.device.queue.writeBuffer(paramsBuffer, 0, compositeParams);
   if (!paramsWrite.ok) throw paramsWrite.error;
+  stageBloomUpload(_c);
 
   // 2. Identity-cached BindGroup (2 tex: hdrColor + bloomBlurV, 1 sampler,
   // 1 UBO). Keys on both sampled views: resize retires both hdrColor and
@@ -505,7 +559,9 @@ export function recordBloomCompositePass(
     );
   pass.setPipeline(pp.bloomCompositePipeline);
   pass.setBindGroup(0, bindGroup);
+  stageBloomBindGroup(_c);
   pass.draw(3, 1, 0, 0);
+  stageBloomEncode(_c);
   if (graphPass === undefined) pass.end();
 }