@forgeax/engine-render 0.1.33 → 0.1.35

package/src/fullscreen-post-process-pass.ts

@@ -48,14 +48,14 @@ const FULLSCREEN_DEFAULT_SPEC: PipelineSpec = Object.freeze({
 /**
  * Declared sample type for a post-process read entry.
  *
- * Closed union (plan-strategy D-7): only `'depth'` is an explicit sampleType
- * discriminant; color inputs are the default (bare `string` or un-suffixed
- * `{ key }`).  Future texture types (`r32float`, etc.) are add-only.
+ * Closed union (plan-strategy D-7): `'depth'` identifies a depth input and
+ * `'multisampled-float'` identifies the explicit 4x paired-resolve color
+ * input. Color inputs otherwise use the default bare string / `{ key }` form.
  *
  * AI-user affordance: IDE autocomplete exposes `'depth'` at the register call
  * site; misspellings are caught by the type system (AC-08).
  */
-export type PostProcessReadSampleType = 'depth';
+export type PostProcessReadSampleType = 'depth' | 'multisampled-float';
 
 // ─── Post-process shader entry (owned by the fullscreen feature host) ──────
 
@@ -105,6 +105,10 @@ export interface PostProcessShaderEntry {
    * represent a color input (plan-strategy D-1 / D-7).
    */
   readonly reads?: readonly (string | PostProcessReadEntry)[] | undefined;
+  /** Use the renderer-owned View bind group at group(0). */
+  readonly usesView?: boolean | undefined;
+  /** Read-only storage buffers appended to the fullscreen bind group. */
+  readonly storageBindings?: readonly number[] | undefined;
 }
 
 function postProcessSourceDigest(source: string): string {
@@ -124,8 +128,10 @@ export function postProcessShaderPipelineLabel(identity: string, source: string)
 }
 
 /** Content-addressed shader-module label shared by prewarm and lazy paths. */
-export function postProcessShaderModuleLabel(identity: string, source: string): string {
-  return `${postProcessShaderPipelineLabel(identity, source)}-module`;
+export function postProcessShaderModuleLabel(source: string): string {
+  // Graph-local names and public feature identities may alias the same source.
+  // Share the prewarmed module, while pipelines retain their own layouts/targets.
+  return `post-process-module-${postProcessSourceDigest(source)}`;
 }
 
 /**
@@ -145,6 +151,8 @@ export function postProcessShaderEntrySignature(entry: PostProcessShaderEntry):
             defaultValue: Array.from(entry.params.defaultValue),
           },
     reads: entry.reads,
+    usesView: entry.usesView,
+    storageBindings: entry.storageBindings,
   });
 }
 
@@ -161,8 +169,8 @@ export function isTemporalFullscreenBinding(values: Readonly<Record<string, unkn
  * Structured read entry for a post-process shader.
  *
  * `key` is the graph resource key (matching a graph color target).
- * `sampleType` is an optional type discriminant (D-1 SSOT); when omitted
- * the entry is treated as a color input (same as a bare string).
+ * `sampleType` is an optional type discriminant (D-1 SSOT); when omitted the
+ * entry is treated as a single-sample color input (same as a bare string).
  */
 export interface PostProcessReadEntry {
   readonly key: string;
@@ -307,6 +315,7 @@ export function buildFullscreenPostProcessPass(
   sampler: Sampler | null;
   depthSampler: Sampler | null;
   extraColorBindings: readonly number[];
+  extraStorageBindings: readonly number[];
   createHandle: (
     name: string,
     pipeline: unknown,
@@ -327,9 +336,14 @@ export function buildFullscreenPostProcessPass(
   // texture variant for a 4-sample scene target. params@2 is always present to
   // avoid 2x2 kind explosion.
   const hasDepth = entryHasDepthRead(entry);
+  const hasMultisampledColor = (entry.reads ?? []).some(
+    (read) => typeof read !== 'string' && read.sampleType === 'multisampled-float',
+  );
   const bglKind: BglKind = hasDepth
     ? depthMultisampled
-      ? 'fullscreen-post-with-scene-depth-msaa'
+      ? hasMultisampledColor
+        ? 'fullscreen-post-with-paired-msaa'
+        : 'fullscreen-post-with-scene-depth-msaa'
       : 'fullscreen-post-with-scene-depth'
     : entry.params !== undefined
       ? 'fullscreen-post-with-params'
@@ -347,6 +361,14 @@ export function buildFullscreenPostProcessPass(
       texture: { sampleType: 'float', viewDimension: '2d' },
     });
   }
+  const firstStorageBinding = firstExtraBinding + extraColorCount;
+  for (const [index, binding] of (entry.storageBindings ?? []).entries()) {
+    descriptor.entries.push({
+      binding: binding ?? firstStorageBinding + index,
+      visibility: GPU_SHADER_STAGE_FRAGMENT,
+      buffer: { type: 'read-only-storage' },
+    });
+  }
   const bglRes = device.createBindGroupLayout(descriptor);
   if (!bglRes.ok) {
     ctx.errorRegistry.fire(bglRes.error);
@@ -364,6 +386,9 @@ export function buildFullscreenPostProcessPass(
     extraColorBindings: Object.freeze(
       Array.from({ length: extraColorCount }, (_, index) => firstExtraBinding + index),
     ),
+    extraStorageBindings: Object.freeze(
+      (entry.storageBindings ?? []).map((binding, index) => binding ?? firstStorageBinding + index),
+    ),
     createHandle: (name, pipeline, paramsBuffer) => ({
       name,
       paramsBuffer,
@@ -402,6 +427,7 @@ export function createFullscreenBindGroup(
   depthTexView?: TextureView | null,
   depthSampler?: Sampler | null,
   additionalViews: readonly { readonly binding: number; readonly view: TextureView }[] = [],
+  additionalBuffers: readonly { readonly binding: number; readonly buffer: Buffer }[] = [],
 ): BindGroup | null {
   const entries: { binding: number; resource: { kind: string; value: unknown } }[] = [
     { binding: 0, resource: { kind: 'textureView', value: inputView } },
@@ -427,6 +453,12 @@ export function createFullscreenBindGroup(
       resource: { kind: 'textureView', value: additional.view },
     });
   }
+  for (const additional of additionalBuffers) {
+    entries.push({
+      binding: additional.binding,
+      resource: { kind: 'buffer', value: { buffer: additional.buffer } },
+    });
+  }
   const res = device.createBindGroup({
     label: 'fullscreen-post-process-bg',
     layout: bgl,

package/src/glyph-text-layout-system.ts

@@ -158,7 +158,7 @@ interface GlyphTextData {
  */
 export function glyphTextLayoutSystem(
   world: World,
-  gpuStore: GpuResidencyCache,
+  gpuStore: Pick<GpuResidencyCache, 'updateMesh'>,
 ): Result<void, TextError> {
   resetFontConcurrency();
 
@@ -200,7 +200,7 @@ function collectGlyphEntities(world: World): EntityHandle[] {
  */
 function processEntity(
   world: World,
-  gpuStore: GpuResidencyCache,
+  gpuStore: Pick<GpuResidencyCache, 'updateMesh'>,
   entity: EntityHandle,
 ): TextError | null {
   const gtRes = world.get(entity, GlyphText);

package/src/gpu-dirty-ranges.ts

@@ -0,0 +1,48 @@
+/** Renderer-local linear ordering of fixed-width GPU row addresses. */
+export class GpuDirtyRanges {
+  private first = new Uint32Array(0);
+  private second = new Uint32Array(0);
+  private readonly counts = new Uint32Array(256);
+
+  coalesce(slots: readonly number[]): readonly { readonly start: number; readonly end: number }[] {
+    if (slots.length === 0) return [];
+    if (slots.length > this.first.length) {
+      const capacity = 2 ** Math.ceil(Math.log2(slots.length));
+      this.first = new Uint32Array(capacity);
+      this.second = new Uint32Array(capacity);
+    }
+    this.first.set(slots);
+    let source = this.first;
+    let target = this.second;
+    for (let shift = 0; shift < 32; shift += 8) {
+      this.counts.fill(0);
+      for (let i = 0; i < slots.length; i++) {
+        const bucket = ((source[i] ?? 0) >>> shift) & 255;
+        this.counts[bucket] = (this.counts[bucket] ?? 0) + 1;
+      }
+      let offset = 0;
+      for (let i = 0; i < 256; i++) {
+        const count = this.counts[i] ?? 0;
+        this.counts[i] = offset;
+        offset += count;
+      }
+      for (let i = 0; i < slots.length; i++) {
+        const value = source[i] ?? 0;
+        const bucket = (value >>> shift) & 255;
+        const index = this.counts[bucket] ?? 0;
+        target[index] = value;
+        this.counts[bucket] = index + 1;
+      }
+      [source, target] = [target, source];
+    }
+    const ranges: { start: number; end: number }[] = [];
+    for (let i = 0; i < slots.length; i++) {
+      const slot = source[i] ?? 0;
+      const previous = ranges.at(-1);
+      if (previous !== undefined && slot <= previous.end)
+        previous.end = Math.max(previous.end, slot + 1);
+      else ranges.push({ start: slot, end: slot + 1 });
+    }
+    return ranges;
+  }
+}

package/src/gpu-driven/batch-topology.ts

@@ -28,6 +28,8 @@ export interface GpuDrivenBatchKey {
   readonly resourceIdentity?: string;
   /** Closed admission lane for the prepared Standard PBR draw. */
   readonly admission?: 'opaque' | 'alpha-mask';
+  /** Graph lane that owns this material after the G-buffer projection. */
+  readonly materialPass?: 'deferred' | 'forward-only';
 }
 
 export interface GpuDrivenCandidate {
@@ -66,6 +68,52 @@ export interface SubmissionPlan {
   readonly visibleCapacity: number;
 }
 
+export interface ResourceClassSplitInspection {
+  readonly resourceClassCount: number;
+  readonly resourceClassSplits: readonly {
+    readonly resourceIdentity: string;
+    readonly batchIds: readonly number[];
+    readonly candidateCount: number;
+  }[];
+  readonly resourceClassSplitReasons: readonly string[];
+}
+
+/**
+ * Attribute batch splits to the prepared resource identity. Draw ranges and
+ * dynamic page ranges are deliberately absent from this grouping, so they can
+ * never be reported as a resource-class split.
+ */
+export function inspectResourceClassSplits(
+  plan: Pick<SubmissionPlan, 'batches'>,
+): ResourceClassSplitInspection {
+  const groups = new Map<string, { readonly batchIds: number[]; candidateCount: number }>();
+  for (const batch of plan.batches) {
+    const resourceIdentity = batch.key.resourceIdentity ?? batch.key.materialResourceClass;
+    const group = groups.get(resourceIdentity) ?? { batchIds: [], candidateCount: 0 };
+    group.batchIds.push(batch.batchId);
+    group.candidateCount += batch.candidates.length;
+    groups.set(resourceIdentity, group);
+  }
+  const resourceClassSplits = [...groups.entries()]
+    .sort(([left], [right]) => left.localeCompare(right))
+    .map(([resourceIdentity, group]) =>
+      Object.freeze({
+        resourceIdentity,
+        batchIds: Object.freeze([...group.batchIds].sort((left, right) => left - right)),
+        candidateCount: group.candidateCount,
+      }),
+    );
+  const resourceClassSplitReasons =
+    resourceClassSplits.length <= 1
+      ? []
+      : resourceClassSplits.map(({ resourceIdentity }) => `resource-class:${resourceIdentity}`);
+  return Object.freeze({
+    resourceClassCount: resourceClassSplits.length,
+    resourceClassSplits: Object.freeze(resourceClassSplits),
+    resourceClassSplitReasons: Object.freeze(resourceClassSplitReasons),
+  });
+}
+
 export interface GpuLodCandidateInput {
   readonly candidate: GpuDrivenCandidate;
   readonly rows: readonly GpuLodRow[];
@@ -298,6 +346,7 @@ function eligibleDraws(slot: RenderSceneSlot): readonly EligibleGpuDrivenDraw[]
           preparedIdentity,
           resourceIdentity: draw.materialResourceClass,
           admission,
+          materialPass: material.deferredPass === true ? 'deferred' : 'forward-only',
         },
         prepared,
         ...candidatePayload(draw, snapshot),
@@ -657,6 +706,7 @@ export class BatchTopology {
   inspect(): BatchTopologyInspection {
     let candidateCount = 0;
     for (const batch of this.batches.values()) candidateCount += batch.candidates.size;
+    const resourceClasses = inspectResourceClassSplits(this.plan());
     return {
       revision: this.revision,
       batchCount: this.batches.size,
@@ -669,6 +719,9 @@ export class BatchTopology {
       membershipAllocations: this.membershipAllocations,
       candidateAdds: this.candidateAdds,
       candidateRemoves: this.candidateRemoves,
+      resourceClassCount: resourceClasses.resourceClassCount,
+      resourceClassSplits: resourceClasses.resourceClassSplits,
+      resourceClassSplitReasons: resourceClasses.resourceClassSplitReasons,
     };
   }
 

package/src/gpu-driven/material-artifacts.ts

@@ -6,6 +6,18 @@ import { hasRequiredVertexInputs } from './prepared-draw';
 
 type ArtifactRow = { readonly source: RenderableSnapshot; readonly renderableIndex: number };
 
+/**
+ * Resolve the producer fact that group(3) binding(1) needs a ProbeBlend page.
+ * Single-layer medium artifacts are compiled with the ProbeBlend ABI even
+ * when their runtime artifact variantSet is intentionally absent.
+ */
+export function requiresProbeBlendRecord(artifact: MaterialShaderArtifact): boolean {
+  return (
+    artifact.variantSet?.includes('PROBE_BLEND_AVAILABLE=true') === true ||
+    artifact.receipt?.surface?.model === 'single-layer-medium'
+  );
+}
+
 /** Resolve the same producer programs for normal frames and replacement devices. */
 export function collectGpuDrivenMaterialArtifacts({
   rows,
@@ -26,7 +38,7 @@ export function collectGpuDrivenMaterialArtifacts({
 }) {
   const materialArtifacts = new Map<string, MaterialShaderArtifact>();
   const shadowMaterialArtifacts = new Map<string, MaterialShaderArtifact>();
-  const shadowProgramIds = new Map<string, string>();
+  const shadowProgramEntries = new Map<string, DispatchEntry>();
   const forwardProgramEntries = new Map<
     string,
     { readonly vertexEntry?: string; readonly fragmentEntry?: string }
@@ -42,10 +54,7 @@ export function collectGpuDrivenMaterialArtifacts({
   }
   for (const entry of shadowDispatch) {
     if (entry.tags.LightMode !== 'ShadowCaster' || entry.materialShaderId === undefined) continue;
-    shadowProgramIds.set(
-      `${entry.renderableIndex}:${entry.materialHandle}`,
-      entry.materialShaderId,
-    );
+    shadowProgramEntries.set(`${entry.renderableIndex}:${entry.materialHandle}`, entry);
   }
   const collectArtifacts = (
     rows: readonly ArtifactRow[],
@@ -58,20 +67,26 @@ export function collectGpuDrivenMaterialArtifacts({
         const prepared = draw.prepared;
         if (prepared === undefined) continue;
         const material = row.source.materials[draw.materialSlot] ?? row.source.material;
+        const programKey = `${row.renderableIndex}:${material.materialHandle ?? -1}`;
+        // Keep program identity and entry points on the same selected dispatch.
+        // Looking this up per draw must not scan the scene's dispatch roster.
+        const shadowProgramEntry = shadowProgramEntries.get(programKey);
         const logicalMaterialShaderId = material.materialShaderId ?? prepared.identity.material;
         const sceneIndexProgramKeys = material.materialSceneIndexProgramKeys;
         const directMaterialShaderId =
-          pass === 'shadow'
-            ? shadowProgramIds.get(`${row.renderableIndex}:${material.materialHandle ?? -1}`)
-            : logicalMaterialShaderId;
-        const directPassNames = new Set(
-          Object.entries(material.materialProgramKeys ?? {})
-            .filter(([, key]) => key === directMaterialShaderId)
-            .map(([passName]) => passName),
-        );
-        const sceneIndexProgramKey = Object.entries(sceneIndexProgramKeys ?? {}).find(
-          ([passName, program]) => program.pass === pass && directPassNames.has(passName),
-        )?.[1]?.specializationKey;
+          pass === 'shadow' ? shadowProgramEntry?.materialShaderId : logicalMaterialShaderId;
+        let sceneIndexProgramKey: string | undefined;
+        for (const passName in sceneIndexProgramKeys) {
+          const program = sceneIndexProgramKeys[passName];
+          if (
+            program?.pass === pass &&
+            directMaterialShaderId !== undefined &&
+            material.materialProgramKeys?.[passName] === directMaterialShaderId
+          ) {
+            sceneIndexProgramKey = program.specializationKey;
+            break;
+          }
+        }
         // A modern publication may expose a scene-index pair for its
         // forward Pass but omit ShadowCaster. Keep that material on its
         // explicit CPU shadow lane; do not reinterpret its direct WGSL
@@ -82,7 +97,7 @@ export function collectGpuDrivenMaterialArtifacts({
         const materialShaderId =
           pass === 'shadow'
             ? (sceneIndexProgramKey ??
-              shadowProgramIds.get(`${row.renderableIndex}:${material.materialHandle ?? -1}`) ??
+              shadowProgramEntry?.materialShaderId ??
               logicalMaterialShaderId)
             : (sceneIndexProgramKey ?? logicalMaterialShaderId);
         const artifact = resolve(materialShaderId, {
@@ -98,14 +113,7 @@ export function collectGpuDrivenMaterialArtifacts({
             : {}),
         });
         const programEntry =
-          pass === 'shadow'
-            ? shadowDispatch.find(
-                (entry) =>
-                  entry.tags.LightMode === 'ShadowCaster' &&
-                  entry.renderableIndex === row.renderableIndex &&
-                  entry.materialHandle === (material.materialHandle ?? -1),
-              )
-            : forwardProgramEntries.get(`${row.renderableIndex}:${material.materialHandle ?? -1}`);
+          pass === 'shadow' ? shadowProgramEntry : forwardProgramEntries.get(programKey);
         const selectedArtifact =
           artifact === undefined
             ? undefined

package/src/gpu-driven/prepared-draw.ts

@@ -118,10 +118,18 @@ function hasMaterialResources(
   // is a readiness requirement; this keeps numeric-only PBR on the same GPU
   // lane while still rejecting an authored handle that failed to resolve.
   return receipt.resourceSlots.every((slot) => {
-    // Storage-buffer resources have no MaterialSnapshot handle surface yet;
-    // admitting them as samplers would silently turn an authored resource
-    // failure into a prepared draw with an unrelated binding.
-    if (slot.kind === 'storage-buffer') return false;
+    // The renderer-owned Surface page is the one storage resource that is
+    // intentionally available to a scene-index draw. Its address is
+    // published in the Surface ABI; every other storage declaration still
+    // fails closed because MaterialSnapshot has no generic storage handle.
+    if (slot.kind === 'storage-buffer') {
+      return (
+        receipt.surface?.dynamicInput?.group === slot.group &&
+        receipt.surface.dynamicInput.binding === slot.binding &&
+        slot.group === 3 &&
+        slot.binding === 3
+      );
+    }
     if (slot.kind === 'texture') {
       if (!authoredTextures?.has(slot.parameter)) return true;
       return (