@forgeax/engine-render 0.1.33 → 0.1.35

package/src/record/fold-instance-buffer.ts

@@ -0,0 +1,51 @@
+import type { Buffer } 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 FoldBucket, packInstanceStorageBuffer } from './mesh-ssbo';
+import type { _InternalRenderPipelineContext } from './render-context';
+
+/** Both transparent draw owners consume one fold payload and resident cache. */
+export function resolveFoldInstanceBuffer(
+  c: _InternalRenderPipelineContext,
+  bucket: FoldBucket,
+  headIndex: number,
+): Buffer | null {
+  const { runtime, frameState } = c;
+  const key = -1 - (((bucket.materialHandle & 0xffff) << 16) | (headIndex & 0xffff));
+  const uniform = runtime.device.caps.storageBuffer === false;
+  const payload = uniform ? bucket.transforms : packInstanceStorageBuffer(bucket.transforms);
+  let resident = frameState.instanceBuffers.get(key);
+  if (resident === undefined || resident.uploadedByteLength !== payload.byteLength) {
+    const created = runtime.device.createBuffer({
+      size: payload.byteLength,
+      usage:
+        (uniform ? GPU_BUFFER_USAGE_UNIFORM : GPU_BUFFER_USAGE_STORAGE) | GPU_BUFFER_USAGE_COPY_DST,
+      mappedAtCreation: false,
+    });
+    if (!created.ok) {
+      runtime.errorRegistry.fire(created.error);
+      return null;
+    }
+    if (resident !== undefined && !resident.buffer.isDestroyed) {
+      const destroyed = resident.buffer.destroy();
+      if (!destroyed.ok) runtime.errorRegistry.fire(destroyed.error);
+    }
+    resident = {
+      buffer: new GpuBuffer(runtime.device, created.value),
+      uploadedArchVersion: bucket.bucketSize,
+      uploadedByteLength: payload.byteLength,
+    };
+    frameState.instanceBuffers.set(key, resident);
+  }
+  // Equal bucket size does not imply unchanged transforms (moving sprites).
+  const written = runtime.device.queue.writeBuffer(resident.buffer.handle, 0, payload);
+  if (!written.ok) {
+    runtime.errorRegistry.fire(written.error);
+    return null;
+  }
+  return resident.buffer.handle;
+}

package/src/record/frame-lighting.ts

@@ -152,6 +152,7 @@ export function buildPerFrameBindGroups(
   graphTargets?: {
     readonly directionalShadow?: TextureView | undefined;
     readonly spotShadow?: TextureView | undefined;
+    readonly cloudShadow?: TextureView | undefined;
     readonly projector?: TextureView | undefined;
     readonly projectorSampler?: import('@forgeax/engine-rhi').Sampler | undefined;
   },
@@ -239,6 +240,7 @@ export function buildPerFrameBindGroups(
         graphSpotShadowView !== undefined
           ? graphSpotShadowView
           : pipelineState.shadowFallbackTextureView;
+      const cloudShadowView = graphTargets?.cloudShadow ?? pipelineState.defaultWhiteTextureView;
       const extendedLighting = pipelineState.extendedLightingAvailable ?? true;
       const iesProfileTextureView = pipelineState.iesProfileTextureView;
       const cookieTextureView = pipelineState.cookieTextureView;
@@ -281,6 +283,7 @@ export function buildPerFrameBindGroups(
             ]
           : [];
       const projectorAvailable = pipelineState.projectorAvailable !== false;
+      const lowLimitCloudBindings = !extendedLighting && !projectorAvailable;
       const b11View = graphTargets?.projector ?? pipelineState.defaultWhiteTextureView;
       const b12Sampler = graphTargets?.projectorSampler ?? pipelineState.defaultSampler;
       viewBindGroup = getOrCreateFromChain(
@@ -297,6 +300,7 @@ export function buildPerFrameBindGroups(
             ? [b11View, b12Sampler]
             : []),
           pipelineState.pointsLinesViewBuffer ?? pipelineState.viewUniformBuffer,
+          ...(lowLimitCloudBindings ? [] : [cloudShadowView, pipelineState.defaultSampler]),
         ],
         'view-main',
         () => {
@@ -379,8 +383,20 @@ export function buildPerFrameBindGroups(
             },
             ...(extendedLightingResources === undefined && projectorAvailable
               ? [
-                  { binding: 11, resource: { kind: 'textureView' as const, value: b11View } },
-                  { binding: 12, resource: { kind: 'sampler' as const, value: b12Sampler } },
+                  {
+                    binding: 11,
+                    resource: {
+                      kind: 'textureView' as const,
+                      value: b11View,
+                    },
+                  },
+                  {
+                    binding: 12,
+                    resource: {
+                      kind: 'sampler' as const,
+                      value: b12Sampler,
+                    },
+                  },
                 ]
               : []),
             ...(extendedLightingResources !== undefined
@@ -432,6 +448,24 @@ export function buildPerFrameBindGroups(
                   },
                 ]
               : []),
+            ...(lowLimitCloudBindings
+              ? []
+              : [
+                  {
+                    binding: 16,
+                    resource: {
+                      kind: 'textureView' as const,
+                      value: cloudShadowView,
+                    },
+                  },
+                  {
+                    binding: 17,
+                    resource: {
+                      kind: 'sampler' as const,
+                      value: pipelineState.defaultSampler,
+                    },
+                  },
+                ]),
             // feat-20260625-spot-light-shadow-mapping w25: the per-spot
             // fragment-read lightViewProj matrices fold into the View UBO
             // (binding 0, `view.spotLightViewProj`) — no standalone binding 9

package/src/record/frame-snapshot.ts

@@ -1,7 +1,7 @@
+import type { RenderResourceScope } from '../publication/resource-scope';
 // @forgeax/engine-runtime - RenderSystem record stage: frame-snapshot.
 // Extracted from render-system-record.ts (feat-20260704 M3/w17, pure move).
 
-import type { World } from '@forgeax/engine-ecs';
 import type { RenderReadVersion } from '@forgeax/engine-ecs/projection';
 import { vec3 } from '@forgeax/engine-math';
 import type {
@@ -16,6 +16,8 @@ import type {
   Texture,
   TextureView,
 } from '@forgeax/engine-rhi';
+import type { MaterialShaderArtifact } from '@forgeax/engine-shader';
+import type { BarrelDistortionMapping } from '../barrel-distortion';
 import type { ClusterBinScratch } from '../cluster-binner';
 import type { DirectionalShadowQuality } from '../components/directional-shadow-filter';
 import type { EnvironmentGeneration } from '../environment/generation';
@@ -23,7 +25,7 @@ import type { EnvironmentLifecycle } from '../environment/lifecycle';
 import type { DepthOfFieldParams } from '../features/depth-of-field/depth-of-field-params';
 import type { GpuBuffer } from '../gpu-resource';
 import type { MotionBlurExecutionReceipt } from '../inspection-types';
-import type { InstanceCollectionStore } from '../instances';
+import type { InstanceProjectionStore } from '../instances';
 import type { IblBindingInspection } from '../mesh-material-bindings';
 import type { StandardLightingInspection } from '../pipeline/standard-lighting/inspection';
 import type { AutoExposureGpuResources } from '../pipeline/standard-output/auto-exposure/gpu';
@@ -409,6 +411,14 @@ export function makeZeroCameraFallbackSnapshot(): CameraSnapshot {
  */
 export interface RenderFrameState {
   frameNumber: number;
+  /** Actual Surface commands staged for the renderer-owned submission fence. */
+  surfaceSubmissionObservation:
+    | import('../surface/submission-observation').SurfaceSubmissionCandidate
+    | undefined;
+  /** Exact producer artifacts accepted by the last submitted GPU frame. */
+  recoveryMaterialArtifacts?: ReadonlyMap<string, MaterialShaderArtifact> | undefined;
+  /** Exact ShadowCaster artifacts accepted by the last submitted GPU frame. */
+  recoveryShadowMaterialArtifacts?: ReadonlyMap<string, MaterialShaderArtifact> | undefined;
   /** Last successful Motion Blur compute execution; failed submits retain the prior receipt. */
   motionBlurExecution?: MotionBlurExecutionReceipt;
   /** Final-submit Standard IBL binding-chain receipt for this frame. */
@@ -481,6 +491,18 @@ export interface RenderFrameState {
     | undefined;
   /** A DoF candidate was present when the frame failed to submit. */
   depthOfFieldLastSubmitFailed?: boolean | undefined;
+  /**
+   * General graph replacement staged by the barrel/output path. The candidate
+   * is promoted only after the surrounding command buffer submits; failed
+   * encode/finish/submit restores the complete graph projection as one unit.
+   */
+  barrelDistortionPreviousGraph?: CompiledRenderGraph<RenderPipelineFrame> | null;
+  barrelDistortionPreviousGraphKey?: string | null;
+  barrelDistortionPreviousPerFrameGraph?: RenderFrameState['perFrameGraph'];
+  barrelDistortionPreviousGraphGeneration?: number;
+  barrelDistortionPreviousCompiledGraphGeneration?: number;
+  barrelDistortionPreviousStandardLightingGraphSignature?: string;
+  barrelDistortionCandidateGraph?: CompiledRenderGraph<RenderPipelineFrame> | null;
   /**
    * Last-known-good graph held while a volume topology candidate is tested.
    * The candidate is promoted only after its command buffer is submitted;
@@ -517,6 +539,10 @@ export interface RenderFrameState {
   reflectionFallbackCompletion?: Promise<void> | undefined;
   /** Camera antialias mode for the last successfully submitted graph. */
   lastSuccessfulCameraAntialias: CameraSnapshot['antialias'] | undefined;
+  /** Last accepted output-space barrel mapping, promoted with the picture. */
+  lastSuccessfulBarrelDistortion: BarrelDistortionMapping | undefined;
+  /** Whether the current frame graph was retained from an accepted LKG. */
+  barrelDistortionGraphResolution?: 'accepted' | 'retained';
   /** Staged TAA GPU state is promoted only after queue.submit succeeds. */
   temporalGpuState: TemporalGpuState | undefined;
   /** Device-scoped auto-exposure buffers imported by the Standard graph. */
@@ -539,6 +565,10 @@ export interface RenderFrameState {
   activeTemporalGpuState: TemporalGpuState | undefined;
   /** Submitted temporal generations retained until their queue fence resolves. */
   readonly retiringTemporalGpuStates: Set<TemporalGpuState>;
+  /** The accepted graph currently owns CloudLayer ping-pong history. */
+  cloudHistoryActive?: boolean;
+  /** Candidate CloudLayer history ownership, promoted only after submit. */
+  pendingCloudHistoryActive?: boolean;
   /** Last successful projection; candidate frames never overwrite it. */
   lastSuccessfulTemporalView: TemporalView | undefined;
   pendingTemporalCommit: TemporalCommitOutcome;
@@ -550,8 +580,8 @@ export interface RenderFrameState {
   currentDirectionalShadowView: TextureView | null;
   currentSpotShadowView: TextureView | null;
   readonly instanceBuffers: Map<number, InstanceBufferCacheEntry>;
-  /** Renderer-owned collection owner used for record-stage residency facts. */
-  readonly instanceCollections?: InstanceCollectionStore;
+  /** Renderer-private World projection receiving record-stage residency facts. */
+  readonly instanceCollections?: InstanceProjectionStore;
   /** Stable buffers for renderer-owned collections split by device cap. */
   readonly instanceBufferChunks?: Map<string, InstanceBufferCacheEntry>;
   /** Per-object ProbeBlendRecord buffers; upload is one atomic 160B write. */
@@ -559,6 +589,12 @@ export interface RenderFrameState {
   /** One renderer-owned record array; each object selects its 256B-aligned lane. */
   probeBlendRecordBuffer?: GpuBuffer;
   probeBlendRecordBufferCapacity: number;
+  /** Last producer revision fully uploaded to the current device buffer. */
+  probeBlendRecordProjection?: {
+    readonly projection: import('../scene/probe-blend').ProbeBlendBufferProjection;
+    readonly device: RhiDevice;
+    readonly buffer: GpuBuffer | undefined;
+  };
   /** Per-entity vertex buffers for the Standard CPU morph lane. */
   readonly morphBuffers?: Map<number, MorphBufferCacheEntry>;
   readonly hdrpClusterBinScratch: ClusterBinScratch;
@@ -831,8 +867,8 @@ export interface BloomFrameReceipts {
  */
 export interface ValidatedRenderable {
   readonly source: RenderableSnapshot;
-  /** World that owns the renderable's asset handles and material snapshots. */
-  readonly world?: World;
+  /** RenderResourceScope that owns the renderable's asset handles and material snapshots. */
+  readonly world?: RenderResourceScope;
   readonly mesh: MeshGpuHandles;
   readonly renderableIndex: number;
   readonly renderState: MaterialRenderState | undefined;
@@ -864,7 +900,7 @@ export interface ValidatedRenderable {
  * @internal
  */
 export interface DirectionalShadowCache {
-  readonly worlds: readonly World[];
+  readonly worlds: readonly RenderResourceScope[];
   readonly worldStateTokens: readonly DirectionalShadowWorldState[];
   readonly assetCatalogEpoch: number;
   readonly pipelineHandle: number;
@@ -880,8 +916,8 @@ export interface DirectionalShadowCache {
  * ECS state that can change the contents of a directional shadow map.
  *
  * The ECS-owned RenderReadLease is the only render-facing mutation boundary.
- * Its version is intentionally conservative: any published World change
- * invalidates the cached atlas, while render never reaches through World for
+ * Its version is intentionally conservative: any published RenderResourceScope change
+ * invalidates the cached atlas, while render never reaches through RenderResourceScope for
  * component-clock storage.
  */
 export interface DirectionalShadowWorldState {