@forgeax/engine-render 0.1.33 → 0.1.34

package/src/record/probe-blend-buffer.ts

@@ -0,0 +1,180 @@
+import type { Buffer, RhiDevice } from '@forgeax/engine-rhi';
+import { GpuBuffer } from '../gpu-resource';
+import {
+  GPU_BUFFER_USAGE_COPY_DST,
+  GPU_BUFFER_USAGE_STORAGE,
+  GPU_BUFFER_USAGE_UNIFORM,
+} from '../gpu-usage';
+import type { ProbeBlendBufferProjection } from '../scene/probe-blend';
+import {
+  PROBE_BLEND_RECORD_STRIDE,
+  type ProbeBlendRecord,
+  probeBlendRecordOffset,
+} from '../scene/probe-blend-record';
+import type { RenderFrameState } from './frame-snapshot';
+
+export interface ProbeBlendBufferRecord {
+  readonly cacheKey: number;
+  readonly record: ProbeBlendRecord;
+}
+
+function isProbeBlendProjection(
+  input: ProbeBlendBufferProjection | readonly ProbeBlendBufferRecord[],
+): input is ProbeBlendBufferProjection {
+  return !Array.isArray(input);
+}
+
+function retireProbeBlendRecordBuffer(buffer: GpuBuffer): void {
+  const destroy = (): void => {
+    if (!buffer.isDestroyed) void buffer.destroy();
+  };
+  void buffer.device.queue.onSubmittedWorkDone().then(destroy, destroy);
+}
+
+function createCompleteProbeBlendBuffer(
+  device: RhiDevice,
+  requiredCapacity: number,
+  records: readonly ProbeBlendBufferRecord[],
+): {
+  readonly buffer: GpuBuffer;
+  readonly cache: ReadonlyMap<number, { readonly generation: number; readonly bytes: Uint8Array }>;
+} {
+  const created = device.createBuffer({
+    label: 'probe-blend-records',
+    size: requiredCapacity * PROBE_BLEND_RECORD_STRIDE,
+    usage:
+      (device.caps.storageBuffer ? GPU_BUFFER_USAGE_STORAGE : GPU_BUFFER_USAGE_UNIFORM) |
+      GPU_BUFFER_USAGE_COPY_DST,
+    mappedAtCreation: false,
+  });
+  if (!created.ok) throw created.error;
+  const candidate = new GpuBuffer(device, created.value);
+  const cache = new Map<number, { readonly generation: number; readonly bytes: Uint8Array }>();
+  try {
+    for (const { cacheKey, record } of records) {
+      const uploaded = device.queue.writeBuffer(
+        candidate.handle,
+        probeBlendRecordOffset(record.objectKey),
+        record.bytes,
+      );
+      if (!uploaded.ok) throw uploaded.error;
+      cache.set(cacheKey, {
+        generation: record.generation,
+        bytes: new Uint8Array(record.bytes),
+      });
+    }
+  } catch (cause) {
+    void candidate.destroy();
+    throw cause;
+  }
+  return { buffer: candidate, cache };
+}
+
+/**
+ * Retain one device buffer for direct and scene-index ProbeBlend consumers.
+ * Capacity is settled before any upload so a growth cannot erase records
+ * written earlier in the same frame. Slot zero remains the producer sentinel;
+ * RenderScene object slot N occupies aligned record N+1.
+ */
+export function ensureProbeBlendRecordBuffer(
+  device: RhiDevice,
+  frameState: Pick<
+    RenderFrameState,
+    | 'probeBlendRecordBuffer'
+    | 'probeBlendRecordBufferCapacity'
+    | 'probeBlendBuffers'
+    | 'probeBlendRecordProjection'
+  >,
+  input: ProbeBlendBufferProjection | readonly ProbeBlendBufferRecord[] | undefined,
+): Buffer | undefined {
+  const projection = input !== undefined && isProbeBlendProjection(input) ? input : undefined;
+  const records: readonly ProbeBlendBufferRecord[] =
+    input === undefined
+      ? []
+      : (projection?.records ?? (input as readonly ProbeBlendBufferRecord[]));
+  let buffer = frameState.probeBlendRecordBuffer;
+  const accepted = frameState.probeBlendRecordProjection;
+  if (
+    projection !== undefined &&
+    accepted?.projection === projection &&
+    accepted.device === device
+  ) {
+    if (records.length === 0) return undefined;
+    if (accepted.buffer === buffer && buffer !== undefined && !buffer.isDestroyed) {
+      return buffer.handle;
+    }
+  }
+  if (records.length === 0) {
+    if (projection !== undefined) {
+      frameState.probeBlendBuffers.clear();
+      frameState.probeBlendRecordProjection = {
+        projection,
+        device,
+        buffer: undefined,
+      };
+    }
+    return undefined;
+  }
+  const requiredCapacity =
+    projection?.capacity ??
+    records.reduce((capacity, { record }) => Math.max(capacity, record.objectKey + 2), 1);
+  const grows =
+    buffer === undefined ||
+    buffer.isDestroyed ||
+    buffer.device !== device ||
+    frameState.probeBlendRecordBufferCapacity < requiredCapacity;
+  const hasAcceptedBaseline =
+    projection !== undefined &&
+    accepted !== undefined &&
+    accepted.device === device &&
+    accepted.buffer === buffer &&
+    buffer !== undefined &&
+    !buffer.isDestroyed &&
+    accepted.projection.sourceIdentity === projection.sourceIdentity &&
+    accepted.projection.revision === projection.baseRevision;
+  const requiresCompletePublish =
+    grows ||
+    (projection !== undefined && (!hasAcceptedBaseline || projection.dirtyRecords.length > 1));
+  if (requiresCompletePublish) {
+    const candidate = createCompleteProbeBlendBuffer(device, requiredCapacity, records);
+    const previous = buffer;
+    buffer = candidate.buffer;
+    frameState.probeBlendRecordBuffer = candidate.buffer;
+    frameState.probeBlendRecordBufferCapacity = requiredCapacity;
+    frameState.probeBlendBuffers.clear();
+    for (const [key, value] of candidate.cache) frameState.probeBlendBuffers.set(key, value);
+    if (projection === undefined) delete frameState.probeBlendRecordProjection;
+    else frameState.probeBlendRecordProjection = { projection, device, buffer: candidate.buffer };
+    if (previous !== undefined) retireProbeBlendRecordBuffer(previous);
+    return candidate.buffer.handle;
+  }
+  if (buffer === undefined) return undefined;
+  const changed = projection?.dirtyRecords ?? records;
+  const cacheUpdates: [number, { readonly generation: number; readonly bytes: Uint8Array }][] = [];
+  for (const { cacheKey, record } of changed) {
+    const cached = frameState.probeBlendBuffers.get(cacheKey);
+    const unchanged =
+      cached !== undefined &&
+      cached.generation === record.generation &&
+      cached.bytes.length === record.bytes.length &&
+      cached.bytes.every((value, index) => value === record.bytes[index]);
+    if (unchanged) continue;
+    const uploaded = device.queue.writeBuffer(
+      buffer.handle,
+      probeBlendRecordOffset(record.objectKey),
+      record.bytes,
+    );
+    if (!uploaded.ok) throw uploaded.error;
+    cacheUpdates.push([
+      cacheKey,
+      { generation: record.generation, bytes: new Uint8Array(record.bytes) },
+    ]);
+  }
+  for (const [cacheKey, value] of cacheUpdates) frameState.probeBlendBuffers.set(cacheKey, value);
+  for (const cacheKey of projection?.removedCacheKeys ?? []) {
+    frameState.probeBlendBuffers.delete(cacheKey);
+  }
+  if (projection === undefined) delete frameState.probeBlendRecordProjection;
+  else frameState.probeBlendRecordProjection = { projection, device, buffer };
+  return buffer.handle;
+}

package/src/record/recovery-pipeline.ts

@@ -173,7 +173,11 @@ function addRequest(input: {
   readonly vertexLayoutProjection?: VertexLayoutProjection;
   readonly vertexEntry?: string;
   readonly fragmentEntry?: string;
-  readonly layoutKindOverride?: 'pbr' | 'pbr-skin';
+  readonly layoutKindOverride?:
+    | 'pbr'
+    | 'pbr-skin'
+    | 'surface-direct-pbr'
+    | 'surface-direct-cluster-pbr';
   readonly preserveUndefinedVariant?: boolean;
   readonly variantAlreadyResolved?: boolean;
 }): void {
@@ -244,7 +248,7 @@ function addRequest(input: {
       undefined,
       undefined,
       projection,
-      undefined,
+      'immediate',
       input.layoutKindOverride,
       undefined,
       input.additionalColorFormats,
@@ -260,6 +264,7 @@ function addStandardMaterialRequests(input: {
   readonly internals: RenderSystemInternals;
   readonly pipelineState: PipelineState;
   readonly validated: readonly ValidatedRenderable[];
+  readonly dispatch: readonly DispatchEntry[];
   readonly standardLighting: StandardTopologyInputValue | undefined;
   readonly sampleCount: number;
   readonly isHdrTarget: boolean;
@@ -267,6 +272,13 @@ function addStandardMaterialRequests(input: {
   readonly reflectionFallbackAvailable: boolean;
 }): void {
   const pointsLinesProjection = deriveVertexLayoutProjection(DEFAULT_VERTEX_ATTRIBUTE_MAP);
+  const forwardPrograms = new Map<string, DispatchEntry>();
+  for (const candidate of input.dispatch) {
+    if (candidate.tags.LightMode !== 'Forward' || candidate.materialShaderId === undefined)
+      continue;
+    const key = `${candidate.renderableIndex}:${candidate.materialHandle}`;
+    if (!forwardPrograms.has(key)) forwardPrograms.set(key, candidate);
+  }
   for (const entry of input.validated) {
     if (entry.source.pointsLines !== undefined) {
       const pointsLinesMaterial = entry.source.material;
@@ -312,9 +324,14 @@ function addStandardMaterialRequests(input: {
     const unlitHasColor = unlitProjection === 'VERTEX_COLOR_AVAILABLE=true';
     for (const submesh of entry.mesh.submeshes) {
       const material = entry.source.materials[submesh.materialSlot] ?? entry.source.material;
+      const forwardProgram = forwardPrograms.get(
+        `${entry.renderableIndex}:${material.materialHandle ?? -1}`,
+      );
       const materialShaderId =
         entry.source.skin === undefined
-          ? (material.materialShaderId ?? 'forgeax::default-unlit')
+          ? (forwardProgram?.materialShaderId ??
+            material.materialShaderId ??
+            'forgeax::default-unlit')
           : SKIN_MATERIAL_SHADER_ID;
       const renderState = geometryRenderStateForPass(
         recoveryRenderState(materialShaderId, material, submesh.topology) as ReturnType<
@@ -370,6 +387,13 @@ function addStandardMaterialRequests(input: {
       const materialCapabilityVariantSet = isStandardPbrMaterialShader(materialShaderId)
         ? standardPbrCapabilityVariantSet
         : capabilityVariantSet;
+      const surfaceLayoutKind =
+        material.surfaceModel === 'single-layer-medium'
+          ? input.standardLighting?.kind === 'clustered' &&
+            input.internals.device.caps.storageBuffer
+            ? ('surface-direct-cluster-pbr' as const)
+            : ('surface-direct-pbr' as const)
+          : undefined;
       const requestedVariant = isSprite
         ? materialShaderId === 'forgeax::sprite' && entry.source.spriteInstances !== undefined
           ? SPRITE_PASS_PER_INSTANCE_REGION_VARIANT_SET
@@ -398,6 +422,12 @@ function addStandardMaterialRequests(input: {
         indexFormat: entry.mesh.indexFormat,
         ...optionalVariant(reflectionFallbackVariant),
         passKind: 'forward',
+        ...(forwardProgram?.vertexEntry === undefined
+          ? {}
+          : { vertexEntry: forwardProgram.vertexEntry }),
+        ...(forwardProgram?.fragmentEntry === undefined
+          ? {}
+          : { fragmentEntry: forwardProgram.fragmentEntry }),
         sampleCount: input.sampleCount,
         ...optionalColorFormat(input.colorFormatOverride),
         ...(input.reflectionFallbackAvailable &&
@@ -405,6 +435,7 @@ function addStandardMaterialRequests(input: {
           ? { additionalColorFormats: ['rgba16float'] as const }
           : {}),
         vertexLayoutProjection: meshProjection,
+        ...(surfaceLayoutKind === undefined ? {} : { layoutKindOverride: surfaceLayoutKind }),
         preserveUndefinedVariant: isSprite && requestedVariant === undefined,
         variantAlreadyResolved:
           isSprite ||
@@ -610,6 +641,7 @@ export function prepareRecoveryPipelineReadiness(input: {
     internals: input.internals,
     pipelineState: input.pipelineState,
     validated: input.validated,
+    dispatch: input.dispatch,
     standardLighting: input.standardLighting,
     sampleCount,
     isHdrTarget,

package/src/record/render-context.ts

@@ -113,6 +113,11 @@ export interface ReflectionProbeRecordState {
 export interface MaterialShaderPipelineEntry {
   readonly pipeline: RhiRenderPipeline;
   readonly group2Contract: PipelineGroup2Contract;
+  /** Producer receipt for the exact artifact selected with this pipeline. */
+  readonly receipt?: {
+    readonly identity: string;
+    readonly generation: number;
+  };
 }
 
 import type {
@@ -198,6 +203,7 @@ export interface RenderSystemRuntime {
       | {
           readonly vertexColorAvailable?: boolean;
           readonly deformation?: 'rigid' | 'skin';
+          readonly variantSet?: string;
           readonly clustered?: boolean;
           readonly reflectionFallback?: boolean;
           readonly pass?: 'forward' | 'shadow' | 'depth';
@@ -221,7 +227,15 @@ export interface RenderSystemRuntime {
     vertexLayout?: string,
     vertexLayoutProjection?: VertexLayoutProjection,
     shaderModuleMode?: RenderFeatureShaderModuleMode,
-    layoutKindOverride?: 'pbr' | 'pbr-skin' | 'gpu-driven-pbr' | 'gpu-driven-skin',
+    layoutKindOverride?:
+      | 'pbr'
+      | 'pbr-skin'
+      | 'gpu-driven-pbr'
+      | 'gpu-driven-skin'
+      | 'gpu-driven-cluster-pbr'
+      | 'gpu-driven-cluster-skin'
+      | 'surface-direct-pbr'
+      | 'surface-direct-cluster-pbr',
     /** Optional vertex entry override for receipt-owned scene-index passes. */
     vertexEntryPoint?: string,
     additionalColorFormats?: readonly GPUTextureFormat[],
@@ -246,7 +260,15 @@ export interface RenderSystemRuntime {
     vertexLayout?: string,
     vertexLayoutProjection?: VertexLayoutProjection,
     shaderModuleMode?: RenderFeatureShaderModuleMode,
-    layoutKindOverride?: 'pbr' | 'pbr-skin' | 'gpu-driven-pbr' | 'gpu-driven-skin',
+    layoutKindOverride?:
+      | 'pbr'
+      | 'pbr-skin'
+      | 'gpu-driven-pbr'
+      | 'gpu-driven-skin'
+      | 'gpu-driven-cluster-pbr'
+      | 'gpu-driven-cluster-skin'
+      | 'surface-direct-pbr'
+      | 'surface-direct-cluster-pbr',
     /** Optional vertex entry override for receipt-owned scene-index passes. */
     vertexEntryPoint?: string,
     additionalColorFormats?: readonly GPUTextureFormat[],
@@ -413,6 +435,8 @@ export interface PipelineState {
   readonly probeInstancesBindGroupLayout?: BindGroupLayout;
   readonly identityInstanceBuffer: Buffer;
   readonly defaultSampler: Sampler;
+  /** Nearest/clamp sampler required by r32float Surface depth input. */
+  readonly surfaceMediumDepthSampler?: Sampler;
   readonly fallbackTextureView: TextureView;
   readonly unlitPipeline: RhiRenderPipeline | null;
   readonly standardPipeline: RhiRenderPipeline | null;
@@ -427,10 +451,16 @@ export interface PipelineState {
   readonly pbrPipelineLayout: PipelineLayout | null;
   /** Dedicated slot-3 layout for scene-index GPU-driven Standard PBR draws. */
   readonly gpuDrivenInstancesBindGroupLayout?: BindGroupLayout | null;
+  /** Direct Surface slot-3 ABI: instances + retained medium frame resources. */
+  readonly surfaceDirectInstancesBindGroupLayout?: BindGroupLayout | null;
   readonly gpuDrivenPbrPipelineLayout?: PipelineLayout | null;
   /** Device-owned shader modules paired with their exact Standard PBR receipts. */
   readonly gpuDrivenPbrPrograms?: ReadonlyMap<string, GpuDrivenPbrProgram>;
   readonly gpuDrivenPbrSkinPipelineLayout?: PipelineLayout | null;
+  /** Clustered group(2) layouts paired with the scene-index slot(3). */
+  readonly gpuDrivenClusterPbrPipelineLayout?: PipelineLayout | null;
+  readonly gpuDrivenClusterPbrSkinPipelineLayout?: PipelineLayout | null;
+  readonly gpuDrivenClusterMeshBindGroupLayout?: BindGroupLayout | null;
   readonly pbrProbePipelineLayout?: PipelineLayout | null;
   readonly hdrpPbrPipelineLayout: PipelineLayout | null;
   readonly hdrpMeshBindGroupLayout?: BindGroupLayout | null;
@@ -579,6 +609,8 @@ export interface _StandardForwardSceneView {
   readonly gpuDrivenSceneMaterialBuffer?: Buffer;
   /** Concrete main-pass draw identities already claimed by the capable GPU lane. */
   readonly gpuDrivenDrawKeys?: ReadonlySet<string>;
+  /** Stable world identities used to construct the claimed draw keys. */
+  readonly gpuDrivenWorldKeys?: readonly number[];
   readonly gpuDrivenShadowViews?: ShadowViewStatePool;
   readonly gpuDrivenShadowBatchProjections?: ReadonlyMap<
     string,
@@ -601,7 +633,11 @@ export interface _StandardForwardSceneView {
   readonly pointsLines: PointsLinesRecordOwner | undefined;
   readonly materialBgAssemblyCache: Map<string, MaterialBgAssemblyCacheEntry>;
   /** Record-stage proof callback; invoked only after a real draw command is encoded. */
-  readonly onRenderableDraw?: (entry: ValidatedRenderable) => void;
+  readonly onRenderableDraw?: (
+    entry: ValidatedRenderable,
+    submeshIndex?: number,
+    receipt?: { readonly lane: 'cpu' | 'gpu'; readonly ready: boolean },
+  ) => void;
   readonly reflectionProbes?: ReflectionProbeRecordState;
   materialUboPayloadCache?: {
     readonly materialSlots: readonly MaterialSnapshot[];

package/src/record/shadow-pass.ts

@@ -82,6 +82,8 @@ export interface GpuDrivenShadowBatch {
   readonly deformation: 'rigid' | 'skin';
   /** Complete binding for this batch, including opaque batches after custom casters. */
   readonly materialGroup: BindGroup;
+  /** Receipt-derived material BG for alpha-mask batches; opaque uses the pass singleton. */
+  readonly alphaMaskMaterialGroup?: BindGroup | undefined;
   readonly vertexBuffer: Buffer;
   readonly indexBuffer?: Buffer | undefined;
   readonly indexFormat?: 'uint16' | 'uint32' | undefined;
@@ -192,6 +194,7 @@ function ensureTypedShadowViewBg(
     );
   }
   const projectorAvailable = pipelineState.projectorAvailable !== false;
+  const lowLimitCloudBindings = !extendedLighting && !projectorAvailable;
   try {
     return getOrCreateFromChain(
       frameState.viewBindGroupCache,
@@ -209,6 +212,9 @@ function ensureTypedShadowViewBg(
             ? [pipelineState.defaultWhiteTextureView, pipelineState.defaultSampler]
             : []),
         pipelineState.pointsLinesViewBuffer ?? pipelineState.viewUniformBuffer,
+        ...(lowLimitCloudBindings
+          ? []
+          : [pipelineState.defaultWhiteTextureView, pipelineState.defaultSampler]),
       ],
       variant,
       () => {
@@ -287,6 +293,24 @@ function ensureTypedShadowViewBg(
                   },
                 ]
               : []),
+            ...(lowLimitCloudBindings
+              ? []
+              : [
+                  {
+                    binding: 16,
+                    resource: {
+                      kind: 'textureView' as const,
+                      value: pipelineState.defaultWhiteTextureView,
+                    },
+                  },
+                  {
+                    binding: 17,
+                    resource: {
+                      kind: 'sampler' as const,
+                      value: pipelineState.defaultSampler,
+                    },
+                  },
+                ]),
           ],
         });
         if (!created.ok) throw created.error;
@@ -786,6 +810,7 @@ function recordGpuDrivenShadowIfPublished(
       visibleBindGroup: projection.visibleBindGroup,
       deformation: projection.deformation,
       materialGroup,
+      ...(batch.key.admission === 'alpha-mask' ? { alphaMaskMaterialGroup: materialGroup } : {}),
       vertexBuffer: projection.mesh.vertexBuffer.handle,
       ...(batch.key.drawKind === 'indexed' && projection.mesh.indexBuffer !== null
         ? {
@@ -1970,7 +1995,11 @@ function ensureGpuDrivenCustomShadowMaterialBg(
   c: _InternalRenderPipelineContext,
   projection: GpuDrivenShadowBatchProjection,
 ): BindGroup {
-  const shaderId = projection.shadowArtifact.material;
+  const shaderId =
+    projection.shadowArtifact.specializationKey ?? projection.shadowArtifact.material;
+  const materialKey = `shadow-material-custom:${shaderId}:${projection.materialEntityKey}:${projection.material.materialHandle ?? -1}:${c.store.materialResourceEpoch}`;
+  const cached = c.materialBgAssemblyCache.get(materialKey);
+  if (cached !== undefined) return cached.bindGroup;
   const fallback = c.pipelineState.skylightFallback;
   if (fallback === null) {
     throw new RhiError({

package/src/record/skybox-post-pass.ts

@@ -498,6 +498,7 @@ export function recordFxaaPass(
   resolve: ResolveContext,
   graphPass?: RhiRenderPassEncoder,
   paramsOverride?: Uint8Array,
+  graphOutputFormat?: GPUTextureFormat,
 ): void {
   const { runtime, pipelineState, encoder, camera, currentTexture } = c;
   // FXAA samples the graph-owned LDR target and writes the current surface.
@@ -570,9 +571,17 @@ export function recordFxaaPass(
       c.bindGroupCounts,
     );
 
-    const fxaaColorFormat = runtime.device.caps.storageBuffer
-      ? pipelineState.format
-      : pipelineState.colorAttachmentFormat;
+    // Typed graph passes own their attachment format.  In particular, the
+    // barrel/LUT split keeps FXAA in the graph-owned rgba16float domain before
+    // the final output encoding; falling back to the swapchain format here
+    // builds a BGRA pipeline against an RGBA16F attachment and invalidates the
+    // command buffer on WebGPU.
+    const fxaaColorFormat =
+      graphPass !== undefined && graphOutputFormat !== undefined
+        ? graphOutputFormat
+        : runtime.device.caps.storageBuffer
+          ? pipelineState.format
+          : pipelineState.colorAttachmentFormat;
     let fxaaPass = graphPass;
     if (fxaaPass === undefined) {
       const fxaaOutputView = runtime.device.createTextureView(currentTexture, {
@@ -594,7 +603,22 @@ export function recordFxaaPass(
         ) as never,
       );
     }
-    fxaaPass.setPipeline(pipelineState.perPassResources.fxaaPipeline);
+    let fxaaPipeline = pipelineState.perPassResources.fxaaPipeline;
+    if (graphPass !== undefined && graphOutputFormat !== undefined) {
+      const entry = runtime.lookupPostProcess?.(FXAA_POST_PROCESS_ID);
+      const rebuilt =
+        entry === undefined || runtime.getPostProcessPipeline === undefined
+          ? null
+          : runtime.getPostProcessPipeline(
+              FXAA_POST_PROCESS_ID,
+              fxaaBglLayout,
+              [graphOutputFormat],
+              entry,
+            );
+      if (rebuilt !== null) fxaaPipeline = rebuilt;
+    }
+    if (fxaaPipeline === null) return;
+    fxaaPass.setPipeline(fxaaPipeline);
     fxaaPass.setBindGroup(0, fxaaBg);
     fxaaPass.draw(3, 1, 0, 0);
     if (graphPass === undefined) fxaaPass.end();