@forgeax/engine-render 0.1.4 → 0.1.6

package/src/record/main-pass-sprite-draws.ts

@@ -2,6 +2,7 @@
 // feat-20260704 M5/w31: further-split from main-pass.ts (AC-05 <=1500 lines/file).
 // recordSpritePass + sprite entity/transparent/instance-buffer helpers, moved verbatim.
 
+import type { World } from '@forgeax/engine-ecs';
 import {
   type BindGroup,
   type Buffer,
@@ -18,25 +19,107 @@ import {
 } from '../gpu-usage';
 import {
   assembleMaterialWithSkylightEntries,
+  type EmissiveAoBindGroupResources,
   type SkylightBindGroupResources,
 } from '../ibl/skylight-bind-group';
 import type { InstanceBufferCacheEntry } from '../instance-buffer-cache';
 import { SPRITE_PREMULTIPLIED_ALPHA_BLEND } from '../materials';
 import { SPRITE_PASS_PER_INSTANCE_REGION_VARIANT_SET } from '../pbr-pipeline';
-import { variantSetFromVertexLayoutProjection } from '../pipeline';
-import { buildBeginRenderPassDescriptor } from '../pipeline-spec';
-import type { _InternalRenderPipelineContext } from '../render-pipeline-context';
-import { MATERIAL_PER_ENTITY_STRIDE } from '../render-system';
+import {
+  buildBeginRenderPassDescriptor,
+  variantSetFromVertexLayoutProjection,
+} from '../pipeline-spec';
 import type { MaterialSnapshot, SpriteInstancesSnapshot } from '../render-system-extract';
 import { worldEntityKey } from './frame-snapshot';
 import { entityHasTransparentSubmesh, residentTextureView } from './main-pass-material';
-import { interleaveSpriteInstanceBuffer, spriteInstancesCacheHit } from './main-pass-sprite';
 import {
   extractEntryResourceHandle,
   getOrCreatePerEntity,
   MAX_UNIFORM_INSTANCES,
   MESH_PER_ENTITY_STRIDE,
+  packInstanceStorageBuffer,
 } from './mesh-ssbo';
+import type { _InternalRenderPipelineContext } from './render-context';
+import { MATERIAL_PER_ENTITY_STRIDE, STANDARD_PBR_UBO_SIZE } from './render-context';
+
+export type { SpriteInstancesSnapshot };
+
+/**
+ * Build the interleaved sprite instance payload consumed by this record owner.
+ * The extract stage validates the two packed arrays before they reach this
+ * function, so the record path has one source of count-mismatch errors.
+ */
+export function interleaveSpriteInstanceBuffer(
+  transforms: Float32Array,
+  regions: Float32Array,
+  includePrevious = false,
+): Float32Array {
+  const count = transforms.length / 16;
+  const stride = includePrevious ? 36 : 20;
+  const regionOffset = includePrevious ? 32 : 16;
+  const out = new Float32Array(count * stride);
+  for (let i = 0; i < count; i++) {
+    const dstBase = i * stride;
+    const transformBase = i * 16;
+    const regionBase = i * 4;
+    for (let k = 0; k < 16; k++) out[dstBase + k] = transforms[transformBase + k] ?? 0;
+    if (includePrevious) {
+      for (let k = 0; k < 16; k++) {
+        out[dstBase + 16 + k] = transforms[transformBase + k] ?? 0;
+      }
+    }
+    for (let k = 0; k < 4; k++) {
+      out[dstBase + regionOffset + k] = regions[regionBase + k] ?? 0;
+    }
+  }
+  return out;
+}
+
+/**
+ * Check whether the existing per-entity sprite buffer still matches the
+ * extract snapshot and interleaved byte count.
+ */
+export function spriteInstancesCacheHit(
+  entry: InstanceBufferCacheEntry | undefined,
+  snapshot: SpriteInstancesSnapshot,
+  requestedBytes: number,
+): boolean {
+  return (
+    entry !== undefined &&
+    entry.uploadedArchVersion === snapshot.archVersion &&
+    entry.uploadedByteLength === requestedBytes
+  );
+}
+
+/**
+ * Decide whether the LDR record needs the transparent sprite sub-pass. This
+ * remains beside the sprite record owner so the frame stage and draw stage
+ * share the same transparent-material rule.
+ */
+export function computeSplitLdrSprite(
+  validatedOrdered: readonly (
+    | {
+        readonly source: {
+          readonly material: MaterialSnapshot;
+          readonly materials?: readonly MaterialSnapshot[];
+        };
+      }
+    | undefined
+  )[],
+  tonemapActive: boolean,
+): boolean {
+  if (tonemapActive) return false;
+  for (const entry of validatedOrdered) {
+    if (entry === undefined) continue;
+    const materials = entry.source.materials;
+    if (materials !== undefined) {
+      if (materials.some((material) => material.transparent === true)) return true;
+    } else if (entry.source.material.transparent === true) {
+      return true;
+    }
+  }
+  return false;
+}
 
 /**
  * feat-20260704 M3/w19: LDR sprite split sub-pass, extracted verbatim from
@@ -60,6 +143,7 @@ export function recordSpritePass(
     materialSlot: number,
     submeshMaterial: MaterialSnapshot,
     entityKey: number,
+    materialWorld: World,
   ) => BindGroup,
   skylightResources: SkylightBindGroupResources,
   graphPass?: RhiRenderPassEncoder,
@@ -91,12 +175,6 @@ export function recordSpritePass(
     // The single-
     // sample path is byte-for-byte unchanged (writes the swap-chain view).
     const spriteColorView = msaaActive ? ldrSpriteColorView : ldrSpritePassView;
-    // A native-capability URP frame renders LDR scenes into the graph-owned
-    // rgba16float target before the final output OETF. Sprite shaders have
-    // separate entry points because their LDR entry performs that OETF
-    // itself for the raw swap-chain path; select the linear-target entry when
-    // the transparent attachment is the graph-owned float target.
-    const spriteUsesLinearAttachment = transparentPassColorFormat(c) === 'rgba16float';
     // sprite-split sub-pass: forward shape with both color and depth loaded
     // (preserves prior content from the main forward pass under the sprites).
     // Stencil ops auto-emitted by the helper because depthFormat carries
@@ -111,7 +189,7 @@ export function recordSpritePass(
             // (possibly rgba16float); swap-chain fallback frames use their raw
             // storage format. WebGPU requires the attachment format and PSO
             // target to match, so both are resolved by the same helper.
-            colorFormats: [transparentPassColorFormat(c) as unknown as GPUTextureFormat],
+            colorFormats: [transparentPassColorFormat(c) as GPUTextureFormat],
             depthFormat: 'depth24plus-stencil8',
             sampleCount: msaaActive ? 4 : 1,
           },
@@ -132,7 +210,7 @@ export function recordSpritePass(
     // fields (deleted) to the generic per-MaterialShader pipeline cache.
     // feat-20260626-collapse M2 / M2-T2: blend factor pair literal moved
     // to the public `SPRITE_PREMULTIPLIED_ALPHA_BLEND` named constant
-    // (re-exported from `@forgeax/engine-runtime`) so any AI user
+    // (re-exported from `@forgeax/engine-runtime`) so each AI user
     // building a transparent material declares the same blend by
     // reference; the previous implicit blend-state factory helper is
     // gone. Cache miss still surfaces as a structured
@@ -175,7 +253,7 @@ export function recordSpritePass(
     const spritePH =
       runtime.getMaterialShaderPipeline?.(
         'forgeax::sprite',
-        spriteUsesLinearAttachment,
+        /* isHdr */ false,
         spritePremulBlend,
         'triangle-list',
         undefined,
@@ -190,17 +268,12 @@ export function recordSpritePass(
         // storage format. `transparentPassColorFormat` is the single owner for
         // this format so lazy PSO construction cannot fall back to the geometry
         // sRGB view.
-        transparentPassColorFormat(c, pipelineState) as unknown as GPUTextureFormat,
-        undefined,
-        undefined,
-        undefined,
-        undefined,
-        spriteUsesLinearAttachment ? 'fs_main_hdr' : undefined,
+        transparentPassColorFormat(c, pipelineState) as GPUTextureFormat,
       ) ?? null;
     const spritePH_withRegion =
       runtime.getMaterialShaderPipeline?.(
         'forgeax::sprite',
-        spriteUsesLinearAttachment,
+        /* isHdr */ false,
         spritePremulBlend,
         'triangle-list',
         undefined,
@@ -208,12 +281,7 @@ export function recordSpritePass(
         'forward',
         undefined,
         msaaActive ? 4 : 1,
-        transparentPassColorFormat(c) as unknown as GPUTextureFormat,
-        undefined,
-        undefined,
-        undefined,
-        undefined,
-        spriteUsesLinearAttachment ? 'fs_main_hdr' : undefined,
+        transparentPassColorFormat(c) as GPUTextureFormat,
       ) ?? null;
 
     // bug-20260629: spritePH===null check moved OUTSIDE the entity loop so the
@@ -248,7 +316,7 @@ export function recordSpritePass(
     const spriteLitPH =
       runtime.getMaterialShaderPipeline?.(
         'forgeax::sprite-lit',
-        spriteUsesLinearAttachment,
+        /* isHdr */ false,
         spritePremulBlend,
         'triangle-list',
         undefined,
@@ -256,12 +324,7 @@ export function recordSpritePass(
         'forward',
         undefined,
         msaaActive ? 4 : 1,
-        transparentPassColorFormat(c) as unknown as GPUTextureFormat,
-        undefined,
-        undefined,
-        undefined,
-        undefined,
-        spriteUsesLinearAttachment ? 'fs_main_hdr' : undefined,
+        transparentPassColorFormat(c) as GPUTextureFormat,
       ) ?? null;
 
     recordSpriteEntityDraws(
@@ -329,6 +392,7 @@ function recordSpriteTransparentPbrDraws(
     materialSlot: number,
     submeshMaterial: MaterialSnapshot,
     entityKey: number,
+    materialWorld: World,
   ) => BindGroup,
 ): void {
   const { runtime, pipelineState, frameState, bindGroupCounts, validatedOrdered, meshBindGroup } =
@@ -404,6 +468,7 @@ function recordSpriteTransparentPbrDraws(
       continue;
     }
     const projectionVariantSet = projectionVariantSetResult.value;
+
     for (let smIdx = 0; smIdx < entry.mesh.submeshes.length; smIdx++) {
       const sm = entry.mesh.submeshes[smIdx];
       if (sm === undefined) continue;
@@ -419,7 +484,12 @@ function recordSpriteTransparentPbrDraws(
       // order), then resolve the PSO; a first-frame async-compile miss skips
       // only the draw, not the BG (one transient frame, PSO flows in next).
       const materialSlot = materialSlotIndices[i]?.[matSlotIdx] ?? materialSlotIndices[i]?.[0] ?? 0;
-      const subBg = resolveMaterialBindGroup(materialSlot, submeshMaterial, entry.source.entityKey);
+      const subBg = resolveMaterialBindGroup(
+        materialSlot,
+        submeshMaterial,
+        entry.source.entityKey,
+        entry.world ?? c.world,
+      );
       spritePass.setBindGroup(1, subBg, [materialSlot * MATERIAL_PER_ENTITY_STRIDE]);
 
       const subPipeline =
@@ -434,9 +504,7 @@ function recordSpriteTransparentPbrDraws(
           undefined,
           sampleCount,
           // Non-sRGB blend view (same override the sprite path uses).
-          transparentPassColorFormat(c) as unknown as GPUTextureFormat,
-          undefined,
-          undefined,
+          transparentPassColorFormat(c) as GPUTextureFormat,
           undefined,
           undefined,
           undefined,
@@ -445,8 +513,7 @@ function recordSpriteTransparentPbrDraws(
       if (subPipeline === null) continue;
 
       if (lastPbrSubPipelineHandle !== subPipeline) {
-        // biome-ignore lint/suspicious/noExplicitAny: opaque RHI pipeline handle
-        spritePass.setPipeline(subPipeline as any);
+        spritePass.setPipeline(subPipeline);
         lastPbrSubPipelineHandle = subPipeline;
       }
       if (entry.mesh.indexed) {
@@ -494,8 +561,7 @@ function recordSpriteEntityDraws(
     foldDispatchPlan,
     materialSlotIndices,
   } = c;
-  // biome-ignore lint/suspicious/noExplicitAny: opaque RHI pipeline handle
-  let lastSpritePipelineHandle: any = null;
+  let lastSpritePipelineHandle: RenderPipeline | null = null;
   let lastSpriteVertexBuffer: GpuBuffer | null = null;
   let lastSpriteIndexBuffer: GpuBuffer | null = null;
   for (let i = 0; i < validatedOrdered.length; i++) {
@@ -576,8 +642,7 @@ function recordSpriteEntityDraws(
       continue;
     }
     if (lastSpritePipelineHandle !== activeSpritePH) {
-      // biome-ignore lint/suspicious/noExplicitAny: opaque RHI pipeline handle
-      spritePass.setPipeline(activeSpritePH as any);
+      spritePass.setPipeline(activeSpritePH);
       lastSpritePipelineHandle = activeSpritePH;
     }
 
@@ -630,8 +695,11 @@ function recordSpriteEntityDraws(
       // bucketSize (a structural-shape signal) so static frames hit the
       // cache.
       const bucketCacheKey = -1 - (((foldHeadBucket.materialHandle & 0xffff) << 16) | (i & 0xffff));
-      const bucketBytes = foldHeadBucket.transforms.byteLength;
       const uniformFallback = runtime.device.caps.storageBuffer === false;
+      const bucketPayload = uniformFallback
+        ? foldHeadBucket.transforms
+        : packInstanceStorageBuffer(foldHeadBucket.transforms);
+      const bucketBytes = bucketPayload.byteLength;
       const bucketBufUsage = uniformFallback
         ? GPU_BUFFER_USAGE_UNIFORM | GPU_BUFFER_USAGE_COPY_DST
         : GPU_BUFFER_USAGE_STORAGE | GPU_BUFFER_USAGE_COPY_DST;
@@ -669,7 +737,7 @@ function recordSpriteEntityDraws(
         const writeRes = runtime.device.queue.writeBuffer(
           activeBucket.buffer.handle,
           0,
-          foldHeadBucket.transforms,
+          bucketPayload,
         );
         if (!writeRes.ok) {
           runtime.errorRegistry.fire(writeRes.error);
@@ -709,8 +777,7 @@ function recordSpriteEntityDraws(
                 },
               },
             ],
-            // biome-ignore lint/suspicious/noExplicitAny: opaque RHI descriptor
-          }) as any;
+          });
           if (!spriteInstBgResult.ok) throw spriteInstBgResult.error;
           spritePass.setBindGroup(3, spriteInstBgResult.value as BindGroup);
           spritePass.drawIndexed(spriteEntry.mesh.indexCount, spriteInstanceCount, 0, 0, 0);
@@ -720,7 +787,10 @@ function recordSpriteEntityDraws(
       }
 
       {
-        const requestedBytes = spriteInst.transforms.byteLength;
+        const instancePayload = uniformFallback
+          ? spriteInst.transforms
+          : packInstanceStorageBuffer(spriteInst.transforms);
+        const requestedBytes = instancePayload.byteLength;
         const cap = runtime.device.limits.maxStorageBufferBindingSize;
         if (typeof cap === 'number' && requestedBytes > cap) {
           runtime.errorRegistry.fire(
@@ -776,7 +846,7 @@ function recordSpriteEntityDraws(
             const writeRes = runtime.device.queue.writeBuffer(
               activeSprite.buffer.handle,
               0,
-              spriteInst.transforms,
+              instancePayload,
             );
             if (!writeRes.ok) {
               runtime.errorRegistry.fire(writeRes.error);
@@ -836,22 +906,17 @@ function recordSpriteEntityDraws(
 
     spritePass.setBindGroup(2, meshBindGroup as BindGroup, [i * MESH_PER_ENTITY_STRIDE]);
 
-    // Per-entity sprite material bind group: use the shader's schema-derived
-    // material layout when the renderer exposes it. The shared PBR layout is
-    // retained only for render-system contexts without that owner.
-    const spriteMaterialShaderId =
-      spriteEntry.source.material.materialShaderId ?? 'forgeax::sprite';
-    const spriteMaterialBgl =
-      runtime.getMaterialBindGroupLayout?.(spriteMaterialShaderId) ??
-      pipelineState.materialBindGroupLayout;
-    const spriteUsesDerivedMaterialLayout =
-      runtime.getMaterialBindGroupLayout?.(spriteMaterialShaderId) !== undefined;
+    // Per-entity sprite material bind group: same standard PBR user-region
+    // layout as in the geometry pass sprite branch + Skylight merged entries
+    // the geometry pass sprite branch + Skylight merged entries (same
+    // skylightResources in scope from above). Texture view is resolved
+    // from the sprite material's baseColorTexture handle.
     const spriteTexHandle = spriteEntry.source.material.baseColorTexture as
       | Handle<'TextureAsset', 'shared'>
       | undefined;
     let spriteTexView = pipelineState.defaultWhiteTextureView;
     if (spriteTexHandle !== undefined) {
-      const tv = residentTextureView(world, store, runtime, spriteTexHandle);
+      const tv = residentTextureView(spriteEntry.world ?? world, store, runtime, spriteTexHandle);
       if (tv !== undefined) spriteTexView = tv as never;
     }
     const spritePassBaseMaterialEntries = [
@@ -862,7 +927,7 @@ function recordSpriteEntityDraws(
           value: {
             buffer: pipelineState.materialUniformBuffer.buffer,
             offset: 0,
-            size: MATERIAL_PER_ENTITY_STRIDE,
+            size: STANDARD_PBR_UBO_SIZE,
           },
         },
       },
@@ -871,55 +936,72 @@ function recordSpriteEntityDraws(
         resource: { kind: 'sampler' as const, value: pipelineState.nearestSampler },
       },
       { binding: 2, resource: { kind: 'textureView' as const, value: spriteTexView } },
-    ];
-    if (!spriteUsesDerivedMaterialLayout) {
-      spritePassBaseMaterialEntries.push(
-        {
-          binding: 3,
-          resource: { kind: 'sampler' as const, value: pipelineState.defaultSampler },
-        },
-        {
-          binding: 4,
-          resource: {
-            kind: 'textureView' as const,
-            value: pipelineState.defaultWhiteTextureView,
-          },
+      {
+        binding: 3,
+        resource: { kind: 'sampler' as const, value: pipelineState.defaultSampler },
+      },
+      {
+        binding: 4,
+        resource: {
+          kind: 'textureView' as const,
+          value: pipelineState.defaultWhiteTextureView,
         },
-        {
-          binding: 5,
-          resource: { kind: 'sampler' as const, value: pipelineState.defaultSampler },
+      },
+      {
+        binding: 5,
+        resource: { kind: 'sampler' as const, value: pipelineState.defaultSampler },
+      },
+      {
+        binding: 6,
+        resource: {
+          kind: 'textureView' as const,
+          value: pipelineState.defaultNormalTextureView,
         },
-        {
-          binding: 6,
-          resource: {
-            kind: 'textureView' as const,
-            value: pipelineState.defaultNormalTextureView,
-          },
+      },
+      {
+        binding: 7,
+        resource: { kind: 'sampler' as const, value: pipelineState.defaultSampler },
+      },
+      {
+        binding: 8,
+        resource: {
+          kind: 'textureView' as const,
+          value: pipelineState.defaultWhiteTextureView,
         },
-        {
-          binding: 7,
-          resource: { kind: 'sampler' as const, value: pipelineState.defaultSampler },
+      },
+      {
+        binding: 9,
+        resource: { kind: 'sampler' as const, value: pipelineState.defaultSampler },
+      },
+      {
+        binding: 10,
+        resource: {
+          kind: 'textureView' as const,
+          value: pipelineState.defaultWhiteTextureView,
         },
-        {
-          binding: 8,
-          resource: {
-            kind: 'textureView' as const,
-            value: pipelineState.defaultWhiteTextureView,
-          },
+      },
+      {
+        binding: 11,
+        resource: { kind: 'sampler' as const, value: pipelineState.defaultSampler },
+      },
+      {
+        binding: 12,
+        resource: {
+          kind: 'textureView' as const,
+          value: pipelineState.defaultWhiteTextureView,
         },
-      );
-    }
+      },
+    ];
+    const spritePassEmissiveAo: EmissiveAoBindGroupResources = {
+      emissiveSampler: pipelineState.defaultSampler,
+      emissiveView: pipelineState.defaultWhiteTextureView,
+      occlusionSampler: pipelineState.defaultSampler,
+      occlusionView: pipelineState.defaultWhiteTextureView,
+    };
     const spritePassMergedEntries = assembleMaterialWithSkylightEntries(
       spritePassBaseMaterialEntries,
       skylightResources,
-      spriteUsesDerivedMaterialLayout
-        ? undefined
-        : {
-            emissiveSampler: pipelineState.defaultSampler,
-            emissiveView: pipelineState.defaultWhiteTextureView,
-            occlusionSampler: pipelineState.defaultSampler,
-            occlusionView: pipelineState.defaultWhiteTextureView,
-          },
+      spritePassEmissiveAo,
     );
 
     // Sprite-pass material BG cache: keyed on shader id (shared across all
@@ -929,13 +1011,13 @@ function recordSpriteEntityDraws(
     // entities with different atlases still get distinct BGs).
     const spritePassBg: BindGroup = getOrCreatePerEntity(
       frameState.materialBgShared,
-      spriteMaterialShaderId,
+      'forgeax::sprite',
       spritePassMergedEntries.map((e) => extractEntryResourceHandle(e)),
       'sprite-pass-material',
       () => {
         const result = runtime.device.createBindGroup({
           label: 'sprite-pass-material-bg',
-          layout: spriteMaterialBgl,
+          layout: pipelineState.materialBindGroupLayout,
           entries: spritePassMergedEntries,
         });
         if (!result.ok) throw result.error;
@@ -973,17 +1055,20 @@ function resolveSpriteInstancesBuffer(
   const spriteInstancesSnap: SpriteInstancesSnapshot | undefined =
     spriteEntry.source.spriteInstances;
   if (spriteInstancesSnap !== undefined) {
-    const includePrevious = runtime.device.caps.storageBuffer;
-    const requestedBytes =
-      spriteInstancesSnap.transforms.byteLength * (includePrevious ? 2 : 1) +
-      spriteInstancesSnap.regions.byteLength;
+    const uniformFallback = runtime.device.caps.storageBuffer === false;
+    const interleaved = interleaveSpriteInstanceBuffer(
+      spriteInstancesSnap.transforms,
+      spriteInstancesSnap.regions,
+      !uniformFallback,
+    );
+    const requestedBytes = interleaved.byteLength;
     const cap = runtime.device.limits.maxStorageBufferBindingSize;
     if (typeof cap === 'number' && requestedBytes > cap) {
       runtime.errorRegistry.fire(
         new RhiError({
           code: 'limit-exceeded',
           expected: `requestedBytes (${requestedBytes}) <= maxStorageBufferBindingSize (${cap})`,
-          hint: 'reduce SpriteInstances instance count to fit within device.limits.maxStorageBufferBindingSize (80 bytes per instance: mat4 64B + region 16B)',
+          hint: 'reduce SpriteInstances instance count to fit within device.limits.maxStorageBufferBindingSize (144 bytes per instance: current mat4 64B + previous mat4 64B + region 16B)',
           detail: {
             maxStorageBufferBindingSize: cap,
             requestedBytes,
@@ -1000,7 +1085,9 @@ function resolveSpriteInstancesBuffer(
       } else if (requestedBytes > 0) {
         const bufRes = runtime.device.createBuffer({
           size: requestedBytes,
-          usage: GPU_BUFFER_USAGE_STORAGE | GPU_BUFFER_USAGE_COPY_DST,
+          usage:
+            (uniformFallback ? GPU_BUFFER_USAGE_UNIFORM : GPU_BUFFER_USAGE_STORAGE) |
+            GPU_BUFFER_USAGE_COPY_DST,
           mappedAtCreation: false,
         });
         if (!bufRes.ok) {
@@ -1023,12 +1110,6 @@ function resolveSpriteInstancesBuffer(
         }
       }
       if (activeSpriteInst !== null && requestedBytes > 0) {
-        const interleaved = interleaveSpriteInstanceBuffer(
-          spriteInstancesSnap.transforms,
-          spriteInstancesSnap.regions,
-          undefined,
-          includePrevious,
-        );
         const writeRes = runtime.device.queue.writeBuffer(
           activeSpriteInst.buffer.handle,
           0,