@forgeax/engine-render 0.1.21 → 0.1.23

package/src/record/mesh-ssbo.ts

@@ -325,6 +325,8 @@ export function isMeshSsboDevMode(): boolean {
  * @internal
  */
 let _meshSsboScratch = new Uint8Array(0);
+/** @internal */
+let _meshSsboScratchFloats = new Float32Array(0);
 
 /**
  * feat-20260704 M3/w21: per-renderable `entity_world` upload (batched). All N
@@ -358,60 +360,69 @@ export function uploadMeshSsboBatch(
   // Grow the module-scoped scratch monotonically; zero the used range.
   if (_meshSsboScratch.length < neededBytes) {
     _meshSsboScratch = new Uint8Array(neededBytes);
+    _meshSsboScratchFloats = new Float32Array(_meshSsboScratch.buffer);
   } else {
     _meshSsboScratch.fill(0, 0, neededBytes);
   }
   const normalMatrixScratch = mat3.create();
+  const strideFloats = MESH_PER_ENTITY_STRIDE / Float32Array.BYTES_PER_ELEMENT;
   for (let i = 0; i < slotCount; i++) {
     const entry = validatedOrdered[i];
     if (entry === undefined) continue;
-    // Float32Array view into this entity's 256-byte slot (current world,
-    // normal, previous world, and reactive metadata use 45 floats; the
-    // remaining padding stays zero). Byte offset i*256 is always
-    // 4-byte aligned since MESH_PER_ENTITY_STRIDE=256 is divisible by 4.
-    const slot = new Float32Array(_meshSsboScratch.buffer, i * MESH_PER_ENTITY_STRIDE, 48);
+    // Address the reusable flat view directly. Constructing one typed-array
+    // wrapper per visible entity made this otherwise contiguous upload create
+    // tens of thousands of short-lived JS objects every frame.
+    const slot = i * strideFloats;
     const isFoldHead = foldDispatchPlan?.headBuckets.has(i) === true;
     if (isFoldHead) {
       // identity mat4
-      slot[0] = 1;
-      slot[5] = 1;
-      slot[10] = 1;
-      slot[15] = 1;
+      _meshSsboScratchFloats[slot] = 1;
+      _meshSsboScratchFloats[slot + 5] = 1;
+      _meshSsboScratchFloats[slot + 10] = 1;
+      _meshSsboScratchFloats[slot + 15] = 1;
       // identity mat3 normal (cols at slot offsets 16/20/24)
-      slot[16] = 1;
-      slot[20] = 1;
-      slot[24] = 1;
+      _meshSsboScratchFloats[slot + 16] = 1;
+      _meshSsboScratchFloats[slot + 20] = 1;
+      _meshSsboScratchFloats[slot + 24] = 1;
       // Fold heads use the instance storage path; keep the mesh temporal
       // fields deterministic for shader variants that still read the slot.
-      slot[28] = 1;
-      slot[33] = 1;
-      slot[38] = 1;
-      slot[43] = 1;
-      slot[44] = 1;
+      _meshSsboScratchFloats[slot + 28] = 1;
+      _meshSsboScratchFloats[slot + 33] = 1;
+      _meshSsboScratchFloats[slot + 38] = 1;
+      _meshSsboScratchFloats[slot + 43] = 1;
+      _meshSsboScratchFloats[slot + 44] = 1;
     } else {
       const worldFromLocal = entry.source.transform.world;
-      for (let k = 0; k < 16; k++) slot[k] = worldFromLocal[k] ?? 0;
+      for (let k = 0; k < 16; k++) _meshSsboScratchFloats[slot + k] = worldFromLocal[k] ?? 0;
       const normal = mat3.normalMatrix(normalMatrixScratch, worldFromLocal);
-      slot[16] = normal[0] ?? 0;
-      slot[17] = normal[1] ?? 0;
-      slot[18] = normal[2] ?? 0;
-      slot[20] = normal[3] ?? 0;
-      slot[21] = normal[4] ?? 0;
-      slot[22] = normal[5] ?? 0;
-      slot[24] = normal[6] ?? 0;
-      slot[25] = normal[7] ?? 0;
-      slot[26] = normal[8] ?? 0;
+      _meshSsboScratchFloats[slot + 16] = normal[0] ?? 0;
+      _meshSsboScratchFloats[slot + 17] = normal[1] ?? 0;
+      _meshSsboScratchFloats[slot + 18] = normal[2] ?? 0;
+      _meshSsboScratchFloats[slot + 20] = normal[3] ?? 0;
+      _meshSsboScratchFloats[slot + 21] = normal[4] ?? 0;
+      _meshSsboScratchFloats[slot + 22] = normal[5] ?? 0;
+      _meshSsboScratchFloats[slot + 24] = normal[6] ?? 0;
+      _meshSsboScratchFloats[slot + 25] = normal[7] ?? 0;
+      _meshSsboScratchFloats[slot + 26] = normal[8] ?? 0;
       const previousWorld = entry.source.temporal?.previousTransform.world ?? worldFromLocal;
-      for (let k = 0; k < 16; k++) slot[28 + k] = previousWorld[k] ?? 0;
-      const reactiveMaterial = entry.source.materials.some(
-        (material) =>
+      for (let k = 0; k < 16; k++) {
+        _meshSsboScratchFloats[slot + 28 + k] = previousWorld[k] ?? 0;
+      }
+      let reactiveMaterial = false;
+      for (const material of entry.source.materials) {
+        const shader = material.materialShaderId;
+        if (
           material.transparent === true ||
-          material.materialShaderId === 'forgeax::sprite' ||
-          material.materialShaderId === 'forgeax::sprite-lit' ||
-          (material.materialShaderId !== undefined &&
-            !material.materialShaderId.startsWith('forgeax::')),
-      );
-      slot[44] = entry.source.temporal?.reactive === true || reactiveMaterial ? 1 : 0;
+          shader === 'forgeax::sprite' ||
+          shader === 'forgeax::sprite-lit' ||
+          (shader !== undefined && !shader.startsWith('forgeax::'))
+        ) {
+          reactiveMaterial = true;
+          break;
+        }
+      }
+      _meshSsboScratchFloats[slot + 44] =
+        entry.source.temporal?.reactive === true || reactiveMaterial ? 1 : 0;
     }
   }
   if (neededBytes > 0) {

package/src/record/render-context.ts

@@ -20,7 +20,7 @@ import type {
   TextureView,
 } from '@forgeax/engine-rhi';
 import { err, ok, RhiError } from '@forgeax/engine-rhi';
-import type { MaterialRuntimeArtifact } from '@forgeax/engine-shader';
+import type { MaterialRuntimeArtifact, MaterialShaderArtifact } from '@forgeax/engine-shader';
 import type {
   MaterialRenderState,
   ParamSchemaEntry,
@@ -50,6 +50,7 @@ import type { PointsLinesInspection } from '../points-lines/inspection';
 import type { PointsLinesRecordPlan } from '../points-lines/record';
 import type { ReflectionProbeTable } from '../reflection/gpu-table';
 import type { ReflectionProbeSelectionResult } from '../reflection/projection';
+import type { SsrAdmissionIdentity } from '../ssr/identity';
 import type { GpuPassTimingReason } from './gpu-pass-timing/errors';
 import type {
   GpuPassTimingCapture,
@@ -68,7 +69,33 @@ export interface ReflectionProbeRecordState {
   readonly table: ReflectionProbeTable;
   readonly selections: ReadonlyMap<string, ReflectionProbeSelectionResult>;
   readonly graph: import('./typed-frame-graph').ReflectionProbeGraphState;
-  readonly completeSubmission: (submitted: boolean, completed?: Promise<unknown>) => void;
+  /** Detached committed fallback projections joined by main-pass renderable key. */
+  readonly fallbackProjections?: ReadonlyMap<
+    string,
+    import('../inspection-types').ReflectionFallbackReceipt
+  >;
+  /** Demand is derived from this frame's renderable/source selection. */
+  readonly fallbackDemand?: boolean;
+  /** True when at least one selected row must prove a non-zero readback. */
+  readonly fallbackHasNonNeutral?: boolean;
+  readonly completeSubmission: (
+    submitted: boolean,
+    completed?: Promise<unknown>,
+    fallbackOutput?: {
+      readonly format: TextureFormat;
+      readonly size: { readonly width: number; readonly height: number };
+      readonly frameId: number;
+      readonly graphGeneration: number;
+      readonly textureIdentity: number;
+      readonly readback?: Promise<{
+        readonly linearHdr: readonly [number, number, number, number];
+        readonly hash: string;
+        readonly graphGeneration: number;
+        readonly textureIdentity: number;
+      }>;
+    },
+    fallbackRequested?: boolean,
+  ) => Promise<void>;
 }
 
 export interface MaterialShaderPipelineEntry {
@@ -103,12 +130,18 @@ import type { FoldDispatchPlan } from './mesh-ssbo';
 
 export interface RenderSystemRuntime {
   readonly device: RhiDevice;
+  /** Internal backend-fixture hook evaluated at the submit transaction edge. */
+  readonly beforeSubmit?: ((device: RhiDevice) => RhiError | undefined) | undefined;
   readonly deviceScope: DeviceScope;
   readonly errorRegistry: RhiErrorListenerRegistry;
   readonly debugOverlay?: RenderDebugOverlay | undefined;
   readonly healthRegistry: HealthListenerRegistry;
   readonly getMaterialProjection?: (materialGuid: string) => MaterialRenderProjection | undefined;
   readonly getMaterialArtifact?: (specializationKey: string) => MaterialRuntimeArtifact | undefined;
+  /** Producer-owned cooked Standard PBR artifact used by GPU-driven projection. */
+  readonly getMaterialShaderArtifact?: (
+    materialShaderId: string,
+  ) => MaterialShaderArtifact | undefined;
   readonly getMaterialShaderPipeline?: (
     materialShaderId: string,
     isHdr: boolean,
@@ -126,6 +159,7 @@ export interface RenderSystemRuntime {
     vertexLayoutProjection?: VertexLayoutProjection,
     shaderModuleMode?: RenderFeatureShaderModuleMode,
     layoutKindOverride?: 'pbr' | 'pbr-skin',
+    additionalColorFormats?: readonly GPUTextureFormat[],
   ) => RhiRenderPipeline | null;
   readonly getMaterialShaderPipelineEntry?: (
     materialShaderId: string,
@@ -143,6 +177,8 @@ export interface RenderSystemRuntime {
     vertexLayout?: string,
     vertexLayoutProjection?: VertexLayoutProjection,
     shaderModuleMode?: RenderFeatureShaderModuleMode,
+    layoutKindOverride?: 'pbr' | 'pbr-skin',
+    additionalColorFormats?: readonly GPUTextureFormat[],
   ) => MaterialShaderPipelineEntry | null;
   readonly getMaterialShaderBindingContract?: (
     materialShaderId: string,
@@ -295,9 +331,9 @@ export interface PipelineState {
   readonly shadowCasterCascadeBuffer: Buffer;
   readonly materialUniformBuffer: { readonly buffer: Buffer; readonly sizeInBytes: number };
   readonly meshStorageBuffer: { readonly buffer: Buffer; readonly sizeInBytes: number };
-  readonly pointLightsBuffer: Buffer;
-  readonly spotLightsBuffer: Buffer;
   readonly instancesBindGroupLayout: BindGroupLayout;
+  /** Probe-enabled slot-3 layout; omitted from no-probe bind groups. */
+  readonly probeInstancesBindGroupLayout?: BindGroupLayout;
   readonly identityInstanceBuffer: Buffer;
   readonly defaultSampler: Sampler;
   readonly nearestSampler: Sampler;
@@ -307,10 +343,13 @@ export interface PipelineState {
   readonly unlitPipelineMsaa: RhiRenderPipeline | null;
   readonly unlitPipelineHdrMsaa: RhiRenderPipeline | null;
   readonly pbrPipelineLayout: PipelineLayout | null;
+  readonly pbrProbePipelineLayout?: PipelineLayout | null;
   readonly hdrpPbrPipelineLayout: PipelineLayout | null;
+  readonly hdrpProbePbrPipelineLayout?: PipelineLayout | null;
   readonly hdrpClusterMembershipPipeline: ComputePipeline | null;
   readonly hdrpClusterMembershipBindGroupLayout: BindGroupLayout | null;
   readonly pbrSkinPipelineLayout: PipelineLayout | null;
+  readonly pbrSkinProbePipelineLayout?: PipelineLayout | null;
   readonly pbrSkinMeshBindGroupLayout: BindGroupLayout | null;
   readonly hdrpSkinPipelineLayout: PipelineLayout | null;
   readonly hdrpSkinMeshBindGroupLayout: BindGroupLayout | null;
@@ -320,6 +359,19 @@ export interface PipelineState {
   readonly unlitPipelineHdr: RhiRenderPipeline | null;
   readonly shadowFallbackTextureView: TextureView;
   readonly shadowAtlasFallbackTextureView: TextureView;
+  readonly extendedLightingAvailable?: boolean;
+  readonly iesProfileTexture?: Texture;
+  readonly cookieTexture?: Texture;
+  readonly cookieMatrixBuffer?: Buffer;
+  spotModifierUploadState?: {
+    readonly ies: Map<number, number>;
+    readonly cookie: Map<number, number>;
+    readonly cookieMatrix: Map<number, number>;
+  };
+  readonly iesProfileTextureView?: TextureView;
+  readonly cookieTextureView?: TextureView;
+  readonly ltcLambertTextureView?: TextureView;
+  readonly ltcGgxTextureView?: TextureView;
   readonly shadowParamsBuffer: Buffer;
   readonly skylightFallback: SkylightFallback | null;
   readonly perPassResources: PerPassResources;
@@ -327,6 +379,10 @@ export interface PipelineState {
 
 export interface RenderSystemInternals extends RenderSystemRuntime {
   readonly canvas: HTMLCanvasElement | OffscreenCanvas;
+  /** Build identity injected by the host's build-tool adapter. */
+  readonly build?: string | undefined;
+  /** Host identity binding for the renderer-owned SSR dependency seam. */
+  readonly ssrIdentity?: SsrAdmissionIdentity | undefined;
   readonly standardProfile?: StandardProfile | undefined;
   readonly standardPipeline: RenderFrameState['activePipeline'];
   readonly featureHost?: RenderFeatureHost | undefined;
@@ -398,6 +454,8 @@ export interface _StandardForwardSceneView {
   readonly directionalShadowCacheReuse: boolean;
   readonly world: World;
   readonly gpuDrivenEntityKeys: ReadonlySet<number>;
+  /** Renderer-local world namespace paired with gpuDrivenEntityKeys. */
+  readonly gpuDrivenWorldKeys?: readonly number[];
   readonly tonemapActive: boolean;
   readonly geometryColorView: TextureView | null;
   readonly geometryDepthView: TextureView | null;
@@ -406,6 +464,8 @@ export interface _StandardForwardSceneView {
   readonly splitLdrSprite: boolean;
   readonly ldrSpritePassView: TextureView | null;
   readonly transparentColorFormat?: GPUTextureFormat;
+  /** Second Standard main-pass attachment used by the fallback producer. */
+  readonly reflectionFallbackColorFormat?: GPUTextureFormat;
   readonly dispatch: readonly DispatchEntry[];
   readonly hdrpClusterBindGroup: BindGroup | null;
   readonly hdrpClusterMembershipBindGroup: BindGroup | null;
@@ -425,6 +485,7 @@ export interface _StandardForwardSceneView {
     readonly payload: Uint8Array;
   };
   hdrpSsaoBlurredView?: TextureView;
+  readonly occlusion?: import('../scene/visibility/occlusion-runtime').OcclusionFrameProjection;
 }
 
 export type _InternalRenderPipelineContext = RenderPipelineContext & _StandardForwardSceneView;

package/src/record/shadow-pass.ts

@@ -23,12 +23,13 @@ import {
   SHADOW_CASTER_SHADER_ID,
   shadowCasterVariantSet,
 } from '../pbr-pipeline';
+import { COOKIE_MATRIX_BYTES } from '../prepare/extended-lighting/resources';
 import type { DispatchEntry, ExtractedLights } from '../render-system-extract';
 import { matchPass } from '../systems/pass-selector';
 import { worldEntityKey } from './frame-snapshot';
+import { resolveGeometryInstancesBindGroup } from './main-pass-geometry';
 import {
   getOrCreateFromChain,
-  getOrCreatePerEntity,
   MAX_UNIFORM_INSTANCES,
   MESH_PER_ENTITY_STRIDE,
   MESH_SSBO_BYTES,
@@ -83,23 +84,79 @@ function ensureTypedShadowViewBg(
   const { runtime, frameState, pipelineState } = c;
   const shadowSampler = pipelineState.perPassResources.shadowSampler;
   if (shadowSampler === null) return null;
+  const extendedLighting = pipelineState.extendedLightingAvailable ?? false;
+  const iesProfileTextureView = pipelineState.iesProfileTextureView;
+  const cookieTextureView = pipelineState.cookieTextureView;
+  const cookieMatrixBuffer = pipelineState.cookieMatrixBuffer;
+  const ltcLambertTextureView = pipelineState.ltcLambertTextureView;
+  const ltcGgxTextureView = pipelineState.ltcGgxTextureView;
+  const extendedLightingCacheKeys: object[] = [];
+  const extendedLightingEntries: BindGroupEntry[] = [];
+  if (extendedLighting) {
+    if (
+      iesProfileTextureView === undefined ||
+      cookieTextureView === undefined ||
+      cookieMatrixBuffer === undefined ||
+      ltcLambertTextureView === undefined ||
+      ltcGgxTextureView === undefined
+    ) {
+      return null;
+    }
+    extendedLightingCacheKeys.push(
+      pipelineState.defaultSampler,
+      iesProfileTextureView,
+      cookieTextureView,
+      ltcLambertTextureView,
+      ltcGgxTextureView,
+      cookieMatrixBuffer,
+    );
+    extendedLightingEntries.push(
+      {
+        binding: 9,
+        resource: { kind: 'sampler', value: pipelineState.defaultSampler },
+      },
+      {
+        binding: 11,
+        resource: { kind: 'textureView', value: iesProfileTextureView },
+      },
+      {
+        binding: 12,
+        resource: { kind: 'textureView', value: cookieTextureView },
+      },
+      {
+        binding: 13,
+        resource: { kind: 'textureView', value: ltcLambertTextureView },
+      },
+      {
+        binding: 14,
+        resource: { kind: 'textureView', value: ltcGgxTextureView },
+      },
+      {
+        binding: 15,
+        resource: {
+          kind: 'buffer',
+          value: { buffer: cookieMatrixBuffer, size: COOKIE_MATRIX_BYTES },
+        },
+      },
+    );
+  }
   const projectorAvailable = pipelineState.projectorAvailable !== false;
   try {
     return getOrCreateFromChain(
       frameState.viewBindGroupCache,
       [
         pipelineState.viewUniformBuffer,
-        pipelineState.pointLightsBuffer,
-        pipelineState.spotLightsBuffer,
         pipelineState.shadowFallbackTextureView,
         shadowSampler,
         pipelineState.shadowAtlasFallbackTextureView,
         pipelineState.shadowParamsBuffer,
         pipelineState.shadowCasterCascadeBuffer,
         pipelineState.shadowFallbackTextureView,
-        ...(projectorAvailable
-          ? [pipelineState.defaultWhiteTextureView, pipelineState.defaultSampler]
-          : []),
+        ...(extendedLighting
+          ? extendedLightingCacheKeys
+          : projectorAvailable
+            ? [pipelineState.defaultWhiteTextureView, pipelineState.defaultSampler]
+            : []),
         pipelineState.pointsLinesViewBuffer ?? pipelineState.viewUniformBuffer,
       ],
       variant,
@@ -119,14 +176,6 @@ function ensureTypedShadowViewBg(
                 },
               },
             },
-            {
-              binding: 1,
-              resource: { kind: 'buffer', value: { buffer: pipelineState.pointLightsBuffer } },
-            },
-            {
-              binding: 2,
-              resource: { kind: 'buffer', value: { buffer: pipelineState.spotLightsBuffer } },
-            },
             {
               binding: 3,
               resource: { kind: 'textureView', value: pipelineState.shadowFallbackTextureView },
@@ -161,6 +210,7 @@ function ensureTypedShadowViewBg(
               binding: 8,
               resource: { kind: 'textureView', value: pipelineState.shadowFallbackTextureView },
             },
+            ...extendedLightingEntries,
             {
               binding: 10,
               resource: {
@@ -171,7 +221,7 @@ function ensureTypedShadowViewBg(
                 },
               },
             },
-            ...(projectorAvailable
+            ...(!extendedLighting && projectorAvailable
               ? [
                   {
                     binding: 11,
@@ -671,31 +721,7 @@ function recordShadowCasterDraws(
     // handle = shadowInstanceBuffer; the HDRP main pass read end (:3820 below)
     // must look up the same (compositeKey, instBuffer) leaf or the shadow
     // instances silently drop.
-    const shadowInstancesBg = getOrCreatePerEntity(
-      c.frameState.instancesBgPerEntity,
-      worldEntityKey(entry.source.worldId, entry.source.entityKey),
-      [shadowInstanceBuffer],
-      'shadow-instances',
-      () => {
-        const result = runtime.device.createBindGroup({
-          label: 'shadow-instances-bg',
-          layout: pipelineState.instancesBindGroupLayout,
-          entries: [
-            {
-              binding: 0,
-              resource: {
-                kind: 'buffer',
-                value: { buffer: shadowInstanceBuffer },
-              },
-            },
-          ],
-        });
-        if (!result.ok) throw result.error;
-        return result.value;
-      },
-      c.bindGroupCounts,
-    );
-
+    const shadowInstancesBg = resolveGeometryInstancesBindGroup(c, shadowInstanceBuffer);
     shadowPass.setBindGroup(3, shadowInstancesBg);
     // feat-20260608 M4 / w16: per-submesh shadow draw loop.
     // Only draw submeshes whose topology is triangle-list or triangle-strip