@forgeax/engine-render 0.1.28 → 0.1.30

package/src/hdrp-buffers.ts

@@ -58,6 +58,7 @@ import {
 import { createHdrpBindGroupLayoutDescriptor } from './pipeline-spec';
 import { MESH_PER_ENTITY_STRIDE } from './record/mesh-ssbo';
 import type { RenderSystemRuntime } from './record/render-context';
+import type { GpuDrivenSceneMeshBinding } from './render-pipeline';
 import { getOrCreateSsaoFallbackTexture } from './ssao-buffers';
 
 export { getOrCreateSsaoFallbackTexture } from './ssao-buffers';
@@ -414,6 +415,145 @@ export type SsaoBindOptions =
     }
   | { readonly enabled: false };
 
+function standardLightingEntries(
+  hdrpBuffers: HdrpBuffers,
+  ssaoTexView: TextureView,
+  ssaoSampler: Sampler,
+): import('@forgeax/engine-rhi').BindGroupEntry[] {
+  return [
+    {
+      binding: 3,
+      resource: {
+        kind: 'buffer',
+        value: { buffer: hdrpBuffers.lightDataBuffer },
+      },
+    },
+    {
+      binding: 4,
+      resource: {
+        kind: 'buffer',
+        value: { buffer: hdrpBuffers.clusterGridBuffer },
+      },
+    },
+    {
+      binding: 5,
+      resource: {
+        kind: 'buffer',
+        value: { buffer: hdrpBuffers.lightIndexListBuffer },
+      },
+    },
+    {
+      binding: 6,
+      resource: {
+        kind: 'buffer',
+        value: { buffer: hdrpBuffers.clusterUniformBuffer },
+      },
+    },
+    {
+      binding: 7,
+      resource: { kind: 'textureView', value: ssaoTexView },
+    },
+    {
+      binding: 8,
+      resource: { kind: 'sampler', value: ssaoSampler },
+    },
+  ];
+}
+
+const sceneLightingBindings = new WeakMap<
+  HdrpBuffers,
+  WeakMap<
+    Buffer,
+    {
+      readonly layout: BindGroupLayout;
+      readonly palette: Buffer | undefined;
+      readonly ssao: TextureView;
+      readonly bindGroup: BindGroup;
+    }
+  >
+>();
+
+/** Bind a complete GPU scene-row projection alongside the current lighting/AO resources. */
+export function createGpuDrivenLightingBindGroup(
+  runtime: RenderSystemRuntime,
+  buffers: HdrpBuffers,
+  layout: BindGroupLayout,
+  binding: GpuDrivenSceneMeshBinding,
+  ssaoView?: TextureView,
+): BindGroup | null {
+  const fallback = getOrCreateSsaoFallbackTexture(runtime);
+  if (fallback === null) return null;
+  const ssao = ssaoView ?? fallback.view;
+  let cache = sceneLightingBindings.get(buffers);
+  if (cache === undefined) {
+    cache = new WeakMap();
+    sceneLightingBindings.set(buffers, cache);
+  }
+  const cached = cache.get(binding.meshBuffer);
+  if (cached?.layout === layout && cached.palette === binding.paletteBuffer && cached.ssao === ssao)
+    return cached.bindGroup;
+  const result = runtime.device.createBindGroup({
+    label: 'gpu-driven-scene-lighting',
+    layout,
+    entries: [
+      {
+        binding: 0,
+        resource: {
+          kind: 'buffer',
+          value: { buffer: binding.meshBuffer, size: binding.meshBytes },
+        },
+      },
+      ...(binding.paletteBuffer === undefined
+        ? []
+        : [1, 2].map((index) => ({
+            binding: index,
+            resource: {
+              kind: 'buffer' as const,
+              value: { buffer: binding.paletteBuffer as Buffer },
+            },
+          }))),
+      ...standardLightingEntries(buffers, ssao, fallback.sampler),
+    ],
+  });
+  if (!result.ok) {
+    runtime.errorRegistry.fire(result.error);
+    return null;
+  }
+  cache.set(binding.meshBuffer, {
+    layout,
+    palette: binding.paletteBuffer,
+    ssao,
+    bindGroup: result.value,
+  });
+  return result.value;
+}
+
+/** Standard surface resources without scene geometry tables. */
+export function createStandardSurfaceLightingBindGroup(
+  runtime: RenderSystemRuntime,
+  layout: BindGroupLayout,
+  grid: { readonly x: number; readonly y: number; readonly z: number },
+  ssaoOptions: SsaoBindOptions = { enabled: false },
+): BindGroup | null {
+  const buffers = getOrCreateHdrpBuffers(runtime, grid);
+  const fallback = getOrCreateSsaoFallbackTexture(runtime);
+  if (buffers === null || fallback === null) return null;
+  const result = runtime.device.createBindGroup({
+    label: 'standard-surface-lighting',
+    layout,
+    entries: standardLightingEntries(
+      buffers,
+      ssaoOptions.enabled ? ssaoOptions.ssaoBlurredView : fallback.view,
+      fallback.sampler,
+    ),
+  });
+  if (!result.ok) {
+    runtime.errorRegistry.fire(result.error);
+    return null;
+  }
+  return result.value;
+}
+
 export function createHdrpUnifiedBindGroup(
   runtime: RenderSystemRuntime,
   hdrpBuffers: HdrpBuffers,
@@ -443,42 +583,7 @@ export function createHdrpUnifiedBindGroup(
           },
         },
       },
-      {
-        binding: 3,
-        resource: {
-          kind: 'buffer',
-          value: { buffer: hdrpBuffers.lightDataBuffer },
-        },
-      },
-      {
-        binding: 4,
-        resource: {
-          kind: 'buffer',
-          value: { buffer: hdrpBuffers.clusterGridBuffer },
-        },
-      },
-      {
-        binding: 5,
-        resource: {
-          kind: 'buffer',
-          value: { buffer: hdrpBuffers.lightIndexListBuffer },
-        },
-      },
-      {
-        binding: 6,
-        resource: {
-          kind: 'buffer',
-          value: { buffer: hdrpBuffers.clusterUniformBuffer },
-        },
-      },
-      {
-        binding: 7,
-        resource: { kind: 'textureView', value: ssaoTexView },
-      },
-      {
-        binding: 8,
-        resource: { kind: 'sampler', value: ssaoSampler },
-      },
+      ...standardLightingEntries(hdrpBuffers, ssaoTexView, ssaoSampler),
     ],
   });
   if (!result.ok) {

package/src/ibl/IblPipelineCache.ts

@@ -192,10 +192,15 @@ export interface IblComposedShaders {
   readonly prefilter: string;
   /** ibl-brdf-lut composed (fullscreen_vs + brdfLutBake_fs). */
   readonly brdfLut: string;
+  readonly probeBackground?: string;
 }
 
 let iblComposedShadersCache: IblComposedShaders | undefined;
 
+export function getIblProbeBackgroundSource(): string | undefined {
+  return iblComposedShadersCache?.probeBackground;
+}
+
 /**
  * Inject the composed ibl-* shader sources used by createIblPipelines.
  * Called once by the engine bootstrap (createRenderer step "shader-load")

package/src/ibl/frame-resources.ts

@@ -0,0 +1,38 @@
+import type { RhiError } from '@forgeax/engine-rhi';
+import { ok, type Result } from '@forgeax/engine-types';
+import type { RenderSystemRuntime } from '../record/render-context';
+import type { SkylightSnapshot } from '../render-system-extract';
+import { getOrCreateIblCache } from './IblPipelineCache';
+import type { SkylightBindGroupResources, SkylightFallback } from './skylight-bind-group';
+
+const EMPTY_SKYLIGHT = new Float32Array([0, 0, 0, 0, 0, 0, 0, 1]);
+
+/** Standard and feature materials consume the same generation-owned environment. */
+export function resolveFrameSkylightResources(
+  runtime: Pick<RenderSystemRuntime, 'device' | 'deviceScope'>,
+  fallback: SkylightFallback,
+  skylight: SkylightSnapshot | undefined,
+): Result<SkylightBindGroupResources, RhiError> {
+  const payload =
+    skylight === undefined
+      ? EMPTY_SKYLIGHT
+      : new Float32Array([skylight.intensity, ...skylight.color, ...skylight.rotation]);
+  const uploaded = runtime.device.queue.writeBuffer(fallback.intensityBuffer, 0, payload);
+  if (!uploaded.ok) return uploaded;
+  const cache = skylight === undefined ? undefined : getOrCreateIblCache(runtime.deviceScope);
+  const resident =
+    cache?.irradianceView !== undefined &&
+    cache.prefilterView !== undefined &&
+    cache.brdfLutView !== undefined
+      ? cache
+      : undefined;
+  return ok({
+    irradianceView: resident?.irradianceView ?? fallback.irradianceView,
+    irradianceSampler: fallback.sampler,
+    prefilterView: resident?.prefilterView ?? fallback.prefilterView,
+    prefilterSampler: fallback.sampler,
+    brdfLutView: resident?.brdfLutView ?? fallback.brdfLutView,
+    brdfLutSampler: fallback.sampler,
+    intensityBuffer: fallback.intensityBuffer,
+  });
+}

package/src/ibl/skylight-bind-group.ts

@@ -126,6 +126,8 @@ export interface SkylightBindGroupResources {
   readonly irradianceView: TextureView;
   readonly irradianceSampler: Sampler;
   readonly prefilterView: TextureView;
+  /** Present only when the per-draw prefilter slot was replaced by a local probe. */
+  readonly skylightPrefilterView?: TextureView;
   readonly prefilterSampler: Sampler;
   readonly brdfLutView: TextureView;
   readonly brdfLutSampler: Sampler;
@@ -254,7 +256,7 @@ export interface TextureInjectionResource {
 export function assembleMaterialWithSkylightEntries(
   materialEntries: readonly BindGroupEntry[],
   skylight: SkylightBindGroupResources,
-  transmission?: TransmissionBindGroupResources | undefined,
+  transmission?: TransmissionBindGroupResources | null | undefined,
   textureInjections: readonly TextureInjectionResource[] = [],
 ): BindGroupEntry[] {
   // IBL injection start = end of the user-region. The user-region IS
@@ -295,29 +297,31 @@ export function assembleMaterialWithSkylightEntries(
       resource: { kind: 'buffer', value: { buffer: skylight.intensityBuffer } },
     },
   ];
-  // Transmission injection is always present after IBL. Non-transmission
-  // variants bind the existing Skylight resources as layout-only placeholders;
-  // they are not a functional fallback and are never sampled by those shaders.
+  // A null transmission omits the unavailable backdrop slots. Otherwise the
+  // existing Skylight resources fill unused slots without changing their ABI.
+  // Physical injections below keep their fixed binding numbers in either case.
   const transmissionSampler = transmission?.sampler ?? skylight.irradianceSampler;
   const transmissionView = transmission?.backdropView ?? skylight.brdfLutView;
   const transmissionStart = result.length;
-  result.push(
-    {
-      binding: transmissionStart,
-      resource: { kind: 'sampler', value: transmissionSampler },
-    },
-    {
-      binding: transmissionStart + 1,
-      resource: { kind: 'textureView', value: transmissionView },
-    },
-  );
-  const clearcoatStart = result.length;
+  if (transmission !== null)
+    result.push(
+      {
+        binding: transmissionStart,
+        resource: { kind: 'sampler', value: transmissionSampler },
+      },
+      {
+        binding: transmissionStart + 1,
+        resource: { kind: 'textureView', value: transmissionView },
+      },
+    );
+  // Standard physical maps occupy fixed bindings 26..45.  The `slot` value
+  // is the canonical index from STANDARD_PHYSICAL_TEXTURE_FIELDS; preserve
+  // gaps for omitted authored maps instead of compacting this tail.
+  const physicalStart = 26;
   for (let index = 0; index < textureInjections.length; index += 1) {
     const resource = textureInjections[index];
     if (resource === undefined) continue;
-    // Slots are offsets from one stable injection base. Using the growing
-    // result length here made slot 1/2 drift past their BGL bindings.
-    const binding = clearcoatStart + resource.slot * 2;
+    const binding = physicalStart + resource.slot * 2;
     result.push(
       {
         binding,
@@ -329,6 +333,13 @@ export function assembleMaterialWithSkylightEntries(
       },
     );
   }
+  result.push({
+    binding: 47,
+    resource: {
+      kind: 'textureView',
+      value: skylight.skylightPrefilterView ?? skylight.prefilterView,
+    },
+  });
   return result;
 }
 
@@ -507,11 +518,11 @@ export function createSkylightFallback(
   if (!brdfLutViewResult.ok) throw brdfLutViewResult.error;
   const brdfLutView = brdfLutViewResult.value;
 
-  // intensity=0 uniform. The WGSL struct is two vec4-aligned lanes:
-  // [intensity, colorR, colorG, colorB] + [rotation quaternion].
+  // The 64-byte Standard environment payload reserves two extra vec4 lanes
+  // for probe-mode diffuse color and rotation. Ordinary Skylight leaves them zero.
   const intensityBufResult = device.createBuffer({
     label: 'skylight-fallback-intensity',
-    size: 32,
+    size: 64,
     usage: GPU_BUFFER_USAGE_UNIFORM | GPU_BUFFER_USAGE_COPY_DST,
   });
   if (!intensityBufResult.ok) throw intensityBufResult.error;