@forgeax/engine-render 0.1.29 → 0.1.31

package/src/gpu-resource.ts

@@ -52,6 +52,7 @@
 //     introduced in feat-20260612 M1 / w1).
 
 import type { Buffer, Result, RhiDevice, RhiError, Texture } from '@forgeax/engine-rhi';
+import type { DeviceScope } from './device/device-scope';
 
 /**
  * Runtime wrapper around an RHI `Buffer` opaque handle that exposes
@@ -81,10 +82,17 @@ export class GpuBuffer {
   // BUFFER_META_MAP. This local flag is a derived view written only on
   // the success branch of `device.destroyBuffer(...)`; charter §F1.
   private destroyed = false;
+  private releaseScope: (() => void) | undefined;
 
-  constructor(device: RhiDevice, handle: Buffer) {
+  constructor(device: RhiDevice, handle: Buffer, scope?: DeviceScope) {
     this.device = device;
     this.handle = handle;
+    if (scope !== undefined) {
+      const ref = scope._adopt('buffer', this, (value) => {
+        if (!value.isDestroyed) value.destroy();
+      });
+      this.releaseScope = () => scope._release(ref);
+    }
   }
 
   get isDestroyed(): boolean {
@@ -101,6 +109,8 @@ export class GpuBuffer {
     const r = this.device.destroyBuffer(this.handle);
     if (r.ok) {
       this.destroyed = true;
+      this.releaseScope?.();
+      this.releaseScope = undefined;
     }
     return r;
   }
@@ -126,10 +136,17 @@ export class GpuTexture {
   readonly device: RhiDevice;
   readonly handle: Texture;
   private destroyed = false;
+  private releaseScope: (() => void) | undefined;
 
-  constructor(device: RhiDevice, handle: Texture) {
+  constructor(device: RhiDevice, handle: Texture, scope?: DeviceScope) {
     this.device = device;
     this.handle = handle;
+    if (scope !== undefined) {
+      const ref = scope._adopt('texture', this, (value) => {
+        if (!value.isDestroyed) value.destroy();
+      });
+      this.releaseScope = () => scope._release(ref);
+    }
   }
 
   get isDestroyed(): boolean {
@@ -144,6 +161,8 @@ export class GpuTexture {
     const r = this.device.destroyTexture(this.handle);
     if (r.ok) {
       this.destroyed = true;
+      this.releaseScope?.();
+      this.releaseScope = undefined;
     }
     return r;
   }

package/src/gpu-scene-schema.ts

@@ -1,4 +1,7 @@
-import { STANDARD_PIPELINE_PARAM_SCHEMA } from '@forgeax/engine-shader';
+import {
+  GPU_DRIVEN_MATERIAL_ROW_BYTES,
+  STANDARD_PIPELINE_PARAM_SCHEMA,
+} from '@forgeax/engine-shader';
 import { derive, type NumericParamType } from '@forgeax/engine-types';
 
 export type GpuSceneScalar = 'u32' | 'i32' | 'f32';
@@ -109,7 +112,13 @@ function deriveStandardMaterialFields(): readonly GpuSceneField[] {
     ]),
   ];
   fields.sort((left, right) => left.offset - right.offset);
-  return fields.map(({ field }) => field);
+  return [
+    ...fields.map(({ field }) => field),
+    ...Array.from(
+      { length: (GPU_DRIVEN_MATERIAL_ROW_BYTES - derived.totalBytes) / 16 },
+      (_, index) => ({ name: `_gpuDrivenPadding${index}`, type: 'vec4<f32>' as const }),
+    ),
+  ];
 }
 
 export const GPU_SCENE_SCHEMAS = Object.freeze({

package/src/gpu-scene.ts

@@ -12,7 +12,7 @@ import {
   GPU_BUFFER_USAGE_STORAGE,
 } from './gpu-usage';
 import type { GpuSceneInspection } from './inspection-types';
-import { packStandardPbrMaterialRow } from './material-row';
+import { packMaterialProgramRow, packStandardPbrMaterialRow } from './material-row';
 import type { RenderSceneApplyResult, RenderSceneSlot } from './scene/render-scene-types';
 
 export type { GpuSceneInspection } from './inspection-types';
@@ -719,8 +719,19 @@ export class GpuScene {
       const materialIndex = allocation.materialStart + ordinal;
       const materialOffset = materialIndex * MATERIAL.stride;
       const snapshot = record.snapshot.materials[ordinal] ?? record.snapshot.material;
-      const row = packStandardPbrMaterialRow(STANDARD_PBR_RECEIPT, snapshot);
-      new Uint8Array(this.tableBytes.material, materialOffset, MATERIAL.stride).set(row);
+      const shaderId = snapshot.materialShaderId;
+      const schema = snapshot.materialParamSchema;
+      const row =
+        shaderId !== undefined &&
+        shaderId !== 'forgeax::default-standard-pbr' &&
+        shaderId !== 'forgeax::pbr-skin' &&
+        shaderId !== 'forgeax::default-standard-pbr-skin' &&
+        schema !== undefined
+          ? packMaterialProgramRow(schema, snapshot, MATERIAL.stride)
+          : packStandardPbrMaterialRow(STANDARD_PBR_RECEIPT, snapshot);
+      const destination = new Uint8Array(this.tableBytes.material, materialOffset, MATERIAL.stride);
+      destination.fill(0);
+      if (row !== undefined) destination.set(row.subarray(0, MATERIAL.stride));
       writes.material.push(materialIndex);
     }
   }

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';
@@ -459,6 +460,74 @@ function standardLightingEntries(
   ];
 }
 
+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,

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/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,22 +297,23 @@ 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 },
-    },
-  );
+  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.
@@ -330,6 +333,13 @@ export function assembleMaterialWithSkylightEntries(
       },
     );
   }
+  result.push({
+    binding: 47,
+    resource: {
+      kind: 'textureView',
+      value: skylight.skylightPrefilterView ?? skylight.prefilterView,
+    },
+  });
   return result;
 }
 
@@ -508,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;