@forgeax/engine-render 0.1.24 → 0.1.26

package/src/record/main-pass-material.ts

@@ -1,3 +1,5 @@
+import { getOrCreateIblCache } from '../ibl/IblPipelineCache';
+import type { _InternalRenderPipelineContext } from './render-context';
 // @forgeax/engine-runtime - RenderSystem record stage: main-pass-material.
 // Extracted from render-system-record.ts (feat-20260704 M3/w17, pure move).
 
@@ -976,6 +978,7 @@ export function buildPerSubmeshMaterialBg(
   submeshMaterial: MaterialSnapshot,
   entityKey: number,
   materialWorld: World = deps.world,
+  materialShaderId: string | undefined = submeshMaterial.materialShaderId,
 ): BindGroup {
   const {
     runtime,
@@ -996,9 +999,11 @@ export function buildPerSubmeshMaterialBg(
     resolveReflectionProbeResources?.(materialWorld, entityKey) ?? skylightResources;
   const smMaterialHandle = submeshMaterial.materialHandle;
   const materialCacheKey =
-    smMaterialHandle === undefined ? undefined : `${materialWorld.identity}:${smMaterialHandle}`;
+    smMaterialHandle === undefined
+      ? undefined
+      : `${materialWorld.identity}:${smMaterialHandle}:${materialShaderId ?? ''}`;
   const smHasVideoFields = (submeshMaterial.videoTextureFields?.size ?? 0) > 0;
-  const smShaderId = submeshMaterial.materialShaderId;
+  const smShaderId = materialShaderId;
   // The cooked shader schema owns the resource ABI. A material snapshot may
   // carry only the authored values (for example a clearcoat-only root omits
   // the standard emissive/occlusion maps), while the Standard template still
@@ -1293,3 +1298,83 @@ export function buildPerSubmeshMaterialBg(
   }
   return smBindGroup;
 }
+
+const ZERO_SKYLIGHT_PAYLOAD = new Float32Array([0, 0, 0, 0, 0, 0, 0, 1]);
+
+/** The same scene resources back material bindings in depth and color passes. */
+export function prepareMaterialSkylight(c: _InternalRenderPipelineContext) {
+  const { runtime, pipelineState, skylight, skylightCount } = c;
+  const skylightFallback = pipelineState.skylightFallback;
+  if (skylightFallback === null) {
+    throw new RhiError({
+      code: 'webgpu-runtime-error',
+      expected: 'pipelineState.skylightFallback != null when PBR pipeline is active',
+      hint: 'createRenderer must allocate skylightFallback alongside the PBR pipeline (D-5 round-4)',
+    });
+  }
+  // feat-20260520-skylight-ibl-cubemap M4 round-4 / t60 (D-5 round-4):
+  // select active vs fallback Skylight resources by `skylightCount` from
+  // the extract stage. Active path reaches into the per-device
+  // `IblPipelineCache` slots (irradianceView / prefilterView / brdfLutView)
+  // populated by the internal equirect-to-cubemap projection; fallback uses the
+  // 1x1-zero identity bundle that converges ambient to 0 (D-4 physical
+  // convergence -- no `if (hasSkylight)` shader branch).
+  // The samplers are reused from `skylightFallback.sampler` for both
+  // paths (linear / clamp-to-edge is correct for IBL cube + 2D LUT
+  // sampling either way). The intensity uniform is rewritten per-frame
+  // when active so `sampleIblSpecular * intensity` carries the user's
+  // Skylight.intensity value; fallback keeps intensity=0 (createSkylightFallback
+  // seed) so ambient = 0 even when the same buffer is shared.
+  let activeViews: { irr: TextureView; pref: TextureView; brdf: TextureView } | undefined;
+  // Per-frame Skylight uniform: std140 32 B = [intensity, colorR, colorG,
+  // colorB, rotation quaternion]. Default to all-zero so a transition from "has Skylight" ->
+  // "no Skylight" does not leak the prior frame's ambient (intensity 0
+  // muzzles everything, including the white fallback irradiance cube).
+  runtime.device.queue.writeBuffer(skylightFallback.intensityBuffer, 0, ZERO_SKYLIGHT_PAYLOAD);
+  if (skylight !== undefined && skylightCount >= 1) {
+    // A Skylight exists. Write its intensity + color regardless of whether
+    // a cubemap is bound: with a cubemap the IBL views below light the
+    // ambient; WITHOUT one, the white fallback irradiance cube + this color
+    // give an instant solid-color ambient (downstream integration #4) with
+    // no async precompute. The white fallback only contributes when a
+    // Skylight is present because the zero-payload above sets intensity 0
+    // when no Skylight exists.
+    const [cr, cg, cb] = skylight.color;
+    const [qx, qy, qz, qw] = skylight.rotation;
+    const uniformPayload = new Float32Array([skylight.intensity, cr, cg, cb, qx, qy, qz, qw]);
+    runtime.device.queue.writeBuffer(skylightFallback.intensityBuffer, 0, uniformPayload);
+    const cache = getOrCreateIblCache(runtime.deviceScope);
+    if (
+      cache.irradianceView !== undefined &&
+      cache.prefilterView !== undefined &&
+      cache.brdfLutView !== undefined
+    ) {
+      activeViews = {
+        irr: cache.irradianceView,
+        pref: cache.prefilterView,
+        brdf: cache.brdfLutView,
+      };
+    }
+  }
+  const skylightResources =
+    activeViews !== undefined
+      ? {
+          irradianceView: activeViews.irr,
+          irradianceSampler: skylightFallback.sampler,
+          prefilterView: activeViews.pref,
+          prefilterSampler: skylightFallback.sampler,
+          brdfLutView: activeViews.brdf,
+          brdfLutSampler: skylightFallback.sampler,
+          intensityBuffer: skylightFallback.intensityBuffer,
+        }
+      : {
+          irradianceView: skylightFallback.irradianceView,
+          irradianceSampler: skylightFallback.sampler,
+          prefilterView: skylightFallback.prefilterView,
+          prefilterSampler: skylightFallback.sampler,
+          brdfLutView: skylightFallback.brdfLutView,
+          brdfLutSampler: skylightFallback.sampler,
+          intensityBuffer: skylightFallback.intensityBuffer,
+        };
+  return { skylightResources, activeViews };
+}

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

@@ -25,24 +25,19 @@ import {
 } from '../ibl/skylight-bind-group';
 import type { InstanceBufferCacheEntry } from '../instance-buffer-cache';
 import { SPRITE_PREMULTIPLIED_ALPHA_BLEND } from '../materials';
-import {
-  isStandardPbrMaterialShader,
-  SPRITE_PASS_PER_INSTANCE_REGION_VARIANT_SET,
-} from '../pbr-pipeline';
-import {
-  buildBeginRenderPassDescriptor,
-  standardTopologyVariantSet,
-  variantSetFromVertexLayoutProjection,
-} from '../pipeline-spec';
-import type { MaterialSnapshot, SpriteInstancesSnapshot } from '../render-system-extract';
+import { SPRITE_PASS_PER_INSTANCE_REGION_VARIANT_SET } from '../pbr-pipeline';
+import { buildBeginRenderPassDescriptor, standardTopologyVariantSet } from '../pipeline-spec';
+import type {
+  DispatchEntry,
+  MaterialSnapshot,
+  SpriteInstancesSnapshot,
+} from '../render-system-extract';
 import { worldEntityKey } from './frame-snapshot';
-import { resolveGeometryInstancesBindGroup, resolveProbeBlendBuffer } from './main-pass-geometry';
+import { recordGeometryDraws, resolveGeometryInstancesBindGroup } from './main-pass-geometry';
 import {
   BUILTIN_USER_REGION_TEXTURE_FIELDS,
   defaultViewForUserRegionField,
-  entityHasTransparentSubmesh,
   residentTextureView,
-  selectMaterialGroup2,
 } from './main-pass-material';
 import {
   extractEntryResourceHandle,
@@ -164,8 +159,14 @@ export function computeSplitLdrSprite(
     | undefined
   )[],
   tonemapActive: boolean,
+  dispatch?: readonly DispatchEntry[],
 ): boolean {
   if (tonemapActive) return false;
+  if (dispatch !== undefined && dispatch.length > 0) {
+    return dispatch.some(
+      (pass) => pass.tags.LightMode === 'Forward' && pass.renderState?.blend !== undefined,
+    );
+  }
   for (const entry of validatedOrdered) {
     if (entry === undefined) continue;
     const materials = entry.source.materials;
@@ -201,9 +202,11 @@ export function recordSpritePass(
     submeshMaterial: MaterialSnapshot,
     entityKey: number,
     materialWorld: World,
+    materialShaderId?: string,
   ) => BindGroup,
   skylightResources: SkylightBindGroupResources,
   graphPass?: RhiRenderPassEncoder,
+  selectedDispatch?: readonly DispatchEntry[],
 ): boolean {
   const {
     runtime,
@@ -409,22 +412,7 @@ export function recordSpritePass(
       reportSpriteUnavailable,
     );
 
-    // feat-city-glb Bug 5 (per-submesh transparency): generic per-submesh PBR
-    // draws in the LDR blend sub-pass. The sprite loop above handles only true
-    // sprite / sprite-lit entities (whole-mesh sprite PSO). EVERY non-sprite
-    // transparent material — built-in PBR, single- or multi-submesh, incl.
-    // glTF alphaMode=BLEND (the crosswalk decal submesh AND the 4.3-blending
-    // window quad) — is drawn here with its real shader + per-submesh
-    // geometry, reusing the geometry pass's PBR machinery but rendering into
-    // the resolved transparent attachment (colorFormatOverride =
-    // transparentPassColorFormat(c)).
-    // Opaque submeshes of a mixed mesh were already drawn in the geometry pass
-    // (per-submesh skip there).
-    //
-    // Non-skinned, non-instanced (glTF static meshes): group 2 = the shared
-    // frame meshBindGroup with the per-entity dynamic offset; group 3 = the
-    // identity instance BG (drawIndexed instanceCount=1). Skinned / instanced
-    // transparent submeshes are OOS here (no such content) and fall through.
+    // Keep program, geometry, bindings and dynamic offsets on the common draw path.
     recordSpriteTransparentPbrDraws(
       c,
       spritePass,
@@ -433,6 +421,7 @@ export function recordSpritePass(
       sampleCount,
       resolveMaterialBindGroup,
       meshGroup2,
+      selectedDispatch,
     );
 
     if (graphPass === undefined) spritePass.end();
@@ -440,159 +429,67 @@ export function recordSpritePass(
   return geometryPassEnded;
 }
 
-/**
- * feat-20260704 M3/w19: generic per-submesh transparent PBR draws in the LDR
- * blend sub-pass, extracted verbatim from the sprite split pass. Every
- * non-sprite transparent material (built-in PBR, single- or multi-submesh, incl.
- * glTF alphaMode=BLEND) draws here with its real shader + per-submesh geometry,
- * reusing the geometry pass's PBR machinery but rendering into the resolved
- * transparent attachment (colorFormatOverride = transparentPassColorFormat(c)). Opaque submeshes of a
- * mixed mesh were already drawn in the geometry pass (per-submesh skip there).
- * Sprites are handled by the sprite loop; skinned / instanced transparent
- * submeshes are OOS here and fall through.
- *
- * @internal
- */
+/** Non-sprite transparent Passes use the same geometry and binding owner as opaque draws. */
 function recordSpriteTransparentPbrDraws(
   c: _InternalRenderPipelineContext,
-  spritePass: RhiRenderPassEncoder,
+  pass: RhiRenderPassEncoder,
   matchedIndices: Set<number> | null,
   materialSlotIndices: readonly (readonly number[])[],
   sampleCount: number,
   resolveMaterialBindGroup: (
-    materialSlot: number,
-    submeshMaterial: MaterialSnapshot,
+    slot: number,
+    material: MaterialSnapshot,
     entityKey: number,
-    materialWorld: World,
+    world: World,
+    shader?: string,
   ) => BindGroup,
   meshGroup2: BindGroup | null,
+  selectedDispatch?: readonly DispatchEntry[],
 ): void {
-  const { runtime, pipelineState, validatedOrdered } = c;
-  const isHdrTarget =
-    c.tonemapActive || transparentPassColorFormat(c, pipelineState) === 'rgba16float';
-  let lastPbrSubPipelineHandle: typeof pipelineState.unlitPipeline = null;
-  let lastPbrSubVertexBuffer: GpuBuffer | null = null;
-  let lastPbrSubIndexBuffer: GpuBuffer | null = null;
-  for (let i = 0; i < validatedOrdered.length; i++) {
-    const entry = validatedOrdered[i];
-    if (entry === undefined) continue;
-    if (matchedIndices !== null && !matchedIndices.has(entry.renderableIndex)) continue;
-    // Sprites are handled by the sprite loop above; skip them here.
-    const entShaderId = entry.source.material.materialShaderId;
-    const entIsSprite = entShaderId === 'forgeax::sprite' || entShaderId === 'forgeax::sprite-lit';
-    if (entIsSprite) continue;
-    // Only entities that carry at least one transparent submesh reach a draw
-    // (single-submesh transparent PBR and mixed opaque+transparent meshes).
-    if (!entityHasTransparentSubmesh(entry.source)) continue;
-    // Skinned / instanced transparent submeshes are not supported in this
-    // sub-pass path (no such content today); skip to avoid mis-binding.
-    if (entry.source.skin !== undefined || entry.source.instances !== undefined) continue;
-
-    const matsForRebind = entry.source.materials;
-    if (entry.mesh.vertexBuffer !== lastPbrSubVertexBuffer) {
-      spritePass.setVertexBuffer(0, entry.mesh.vertexBuffer.handle);
-      lastPbrSubVertexBuffer = entry.mesh.vertexBuffer;
-    }
-    if (
-      entry.mesh.indexed &&
-      entry.mesh.indexBuffer !== null &&
-      entry.mesh.indexBuffer !== lastPbrSubIndexBuffer
-    ) {
-      spritePass.setIndexBuffer(entry.mesh.indexBuffer.handle, entry.mesh.indexFormat);
-      lastPbrSubIndexBuffer = entry.mesh.indexBuffer;
+  const isSprite = (shader: string | undefined) =>
+    shader === 'forgeax::sprite' || shader === 'forgeax::sprite-lit';
+  const passes = selectedDispatch?.filter(
+    (entry) =>
+      entry.renderState?.blend !== undefined &&
+      !isSprite(entry.materialShaderId) &&
+      (matchedIndices === null || matchedIndices.has(entry.renderableIndex)),
+  );
+  const matched = new Map<number, Set<number>>();
+  const add = (index: number, handle: number) => {
+    let handles = matched.get(index);
+    if (handles === undefined) {
+      handles = new Set();
+      matched.set(index, handles);
     }
-    for (let smIdx = 0; smIdx < entry.mesh.submeshes.length; smIdx++) {
-      const sm = entry.mesh.submeshes[smIdx];
-      if (sm === undefined) continue;
-      const matSlotIdx = sm.materialSlot;
-      const submeshMaterial = matsForRebind[matSlotIdx] ?? entry.source.material;
-      // Only transparent submeshes belong in this blend sub-pass; opaque
-      // submeshes were drawn in the geometry pass.
-      if (submeshMaterial.transparent !== true) continue;
-      const smShaderId = submeshMaterial.materialShaderId;
-      if (smShaderId === undefined) continue;
-      const probeBlendAvailable =
-        runtime.device.caps.storageBuffer &&
-        entry.source.probeBlendRecord !== undefined &&
-        isStandardPbrMaterialShader(smShaderId);
-      const probeBinding = probeBlendAvailable
-        ? resolveProbeBlendBuffer(
-            c,
-            entry.source.probeBlendRecord,
-            worldEntityKey(entry.source.worldId, entry.source.entityKey),
-          )
-        : undefined;
-      const identityInstBg = resolveGeometryInstancesBindGroup(
-        c,
-        pipelineState.identityInstanceBuffer,
-        probeBinding?.buffer,
-      );
-      if (probeBinding === undefined) spritePass.setBindGroup(3, identityInstBg);
-      else spritePass.setBindGroup(3, identityInstBg, [probeBinding.offset]);
-      const subVariantSet = standardTopologyVariantSet(
-        c.standardLighting,
-        runtime.device.caps.storageBuffer,
-        entry.mesh.layoutProjection.attributes.some((attribute) => attribute.key === 'color'),
-        probeBlendAvailable,
-      );
-      const projectionVariantSetResult = variantSetFromVertexLayoutProjection(
-        entry.mesh.layoutProjection,
-        subVariantSet,
-      );
-      if (!projectionVariantSetResult.ok) {
-        runtime.errorRegistry.fire(projectionVariantSetResult.error);
-        continue;
-      }
-      const projectionVariantSet = projectionVariantSetResult.value;
-      const subPipelineEntry =
-        c.runtime.getMaterialShaderPipelineEntry?.(
-          smShaderId,
-          isHdrTarget,
-          submeshMaterial.renderState,
-          sm.topology,
-          entry.mesh.indexFormat,
-          projectionVariantSet,
-          'forward',
-          undefined,
-          sampleCount,
-          // Non-sRGB blend view (same override the sprite path uses).
-          transparentPassColorFormat(c) as GPUTextureFormat,
-          undefined,
-          undefined,
-          undefined,
-          entry.mesh.layoutProjection,
-        ) ?? null;
-      if (subPipelineEntry === null) continue;
-      const submeshContract = subPipelineEntry.group2Contract;
-      const submeshGroup2 = selectMaterialGroup2(meshGroup2, c.meshBindGroup, submeshContract);
-      if (submeshGroup2 === null) continue;
-      spritePass.setBindGroup(2, submeshGroup2, [i * MESH_PER_ENTITY_STRIDE]);
-
-      // Bind the per-submesh material BG first (mirrors the geometry pass
-      // 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,
-        entry.world ?? c.world,
-      );
-      spritePass.setBindGroup(1, subBg, [materialSlot * MATERIAL_PER_ENTITY_STRIDE]);
-
-      const subPipeline = subPipelineEntry.pipeline;
-
-      if (lastPbrSubPipelineHandle !== subPipeline) {
-        spritePass.setPipeline(subPipeline);
-        lastPbrSubPipelineHandle = subPipeline;
-      }
-      if (entry.mesh.indexed) {
-        spritePass.drawIndexed(sm.indexCount, 1, sm.indexOffset, 0, 0);
-      } else {
-        spritePass.draw(sm.vertexCount, 1, 0, 0);
+    handles.add(handle);
+  };
+  if (passes !== undefined) {
+    for (const entry of passes) add(entry.renderableIndex, entry.materialHandle);
+  } else {
+    for (const entry of c.validatedOrdered) {
+      if (matchedIndices !== null && !matchedIndices.has(entry.renderableIndex)) continue;
+      if (isSprite(entry.source.material.materialShaderId)) continue;
+      for (const material of entry.source.materials) {
+        if (material.transparent === true) add(entry.renderableIndex, material.materialHandle ?? 0);
       }
     }
   }
+  recordGeometryDraws(
+    {
+      ...c,
+      splitLdrSprite: false,
+      transparentColorFormat: transparentPassColorFormat(c) as GPUTextureFormat,
+    },
+    pass,
+    matched,
+    materialSlotIndices,
+    sampleCount,
+    meshGroup2,
+    c.meshBindGroup,
+    resolveMaterialBindGroup,
+    'forward',
+    passes,
+  );
 }
 
 /**
@@ -856,7 +753,7 @@ function recordSpriteEntityDraws(
             new RhiError({
               code: 'limit-exceeded',
               expected: `requestedBytes (${requestedBytes}) <= maxStorageBufferBindingSize (${cap})`,
-              hint: 'reduce instance count to fit within device.limits.maxStorageBufferBindingSize, or split transforms across multiple Instances entries',
+              hint: 'reduce the sprite batch to fit within device.limits.maxStorageBufferBindingSize or use a storage-capable backend',
               detail: {
                 maxStorageBufferBindingSize: cap,
                 requestedBytes,