@forgeax/engine-render 0.1.33 → 0.1.34

package/src/render-pipeline.ts

@@ -41,6 +41,7 @@ import type { DepthOfFieldSide } from './components/depth-of-field';
 import type { DirectionalShadowFilterLabel } from './components/directional-shadow-filter';
 import type { RenderError } from './errors/render';
 import type { RenderFeatureTargetKind } from './features/targets';
+import type { RenderFeaturePlacement } from './features/types';
 import type { ShadowViewIdentity, ShadowViewProjection } from './gpu-driven/shadow-views';
 import {
   GPU_TEXTURE_USAGE_COPY_SRC,
@@ -249,6 +250,8 @@ export interface RenderPipelineTopology {
           readonly useFar: boolean;
         }
       | undefined;
+    /** Shape-only barrel admission; numeric mapping stays per-frame data. */
+    readonly barrelDistortion?: boolean | undefined;
   };
   /** Frame-stable Standard output policy; no raw RHI handles enter topology. */
   readonly output?: {
@@ -285,6 +288,10 @@ export interface RenderPipelineTopology {
    */
   readonly volumetricFog?: {
     readonly enabled: boolean;
+    readonly additional?: readonly {
+      readonly format: TextureFormat;
+      readonly extent: { readonly width: number; readonly height: number; readonly depth: number };
+    }[];
     readonly lightKind?: 'directional' | 'point' | 'spot' | undefined;
     readonly lightEntity?: number | undefined;
     readonly pointLightEntity?: number | undefined;
@@ -333,6 +340,8 @@ export interface RenderPipelineTopology {
   readonly standardLightingTopologySignature?: string | undefined;
   /** Internal graph fact; renderer callers do not configure transmission demand. */
   readonly transmissionDemand?: TransmissionDemand | undefined;
+  /** Whether the extracted frame contains a single-layer medium Surface. */
+  readonly singleLayerMedium?: boolean | undefined;
 }
 
 /** Resolve the built-in final-output dither policy from the pipeline asset. */
@@ -463,9 +472,30 @@ export interface RenderPipelineGpuDrivenProjection {
     pass: RhiRenderPassEncoder,
     resources: GraphResourceResolver,
     frameResources: GpuDrivenStandardPbrFrameResources,
+    filter?: RenderPipelineGpuDrivenFilter,
+    fragmentEntryPoint?: string,
   ): void;
 }
 
+/** Material family selected by a typed scene pass for GPU-driven encoding. */
+export type RenderPipelineGpuDrivenFilter =
+  | 'opaque'
+  | 'deferred-opaque'
+  | 'forward-only-opaque'
+  | 'single-layer-medium';
+
+/** Graph-paired inputs available to a single-layer medium Surface pass. */
+export interface RenderPipelineSurfaceMediumPair {
+  /** The resolved opaque scene color produced by the shared Standard owner. */
+  readonly opaqueColor: GraphTextureView;
+  /** Raw depth copy is backend-dependent and remains explicit when unavailable. */
+  readonly rawDepth:
+    | { readonly status: 'available'; readonly view: GraphTextureView }
+    | {
+        readonly status: 'unavailable';
+        readonly reason: 'depth-copy-unavailable';
+      };
+}
 /** Exact scene rows selected by an indirect batch; palette offsets are global. */
 export interface GpuDrivenSceneMeshBinding {
   readonly meshBuffer: Buffer;
@@ -475,6 +505,8 @@ export interface GpuDrivenSceneMeshBinding {
 
 /** Producer-owned Standard PBR resources resolved during graph execution. */
 export interface GpuDrivenStandardPbrFrameResources {
+  /** Resource generation of the actual scene-index/indirect producer. */
+  readonly resourceGeneration?: number;
   readonly materialBindGroups: (BindGroup | undefined)[];
   /** Frame-global material slots keyed by the retained scene entity identity. */
   readonly materialSlotIndicesByEntity: Map<number, readonly number[]>;
@@ -485,6 +517,56 @@ export interface GpuDrivenStandardPbrFrameResources {
   colorFormats?: readonly TextureFormat[];
   /** Exact producer-owned numeric Material table consumed by scene-index PBR. */
   readonly sceneMaterialBuffer: Buffer;
+  /** Renderer-owned generic Surface page and frame/range metadata. */
+  readonly surfaceDynamicInput?: {
+    readonly page: Buffer;
+    readonly frame: Buffer;
+    readonly sharedFrame: Buffer;
+    readonly pageBytes: number;
+    readonly frameBytes: number;
+    readonly sharedFrameBytes: number;
+  };
+  /**
+   * Resolve the complete direct Surface slot-3 closure for one retained draw.
+   * The producer validates the stable draw identity and instance count before
+   * publishing a bind group; record never derives a frame-row address.
+   */
+  readonly surfaceDirectInstances?: (input: {
+    readonly worldId: number;
+    readonly entityKey: number;
+    readonly drawItemIndex: number;
+    readonly instanceCount: number;
+    readonly firstInstanceOrdinal?: number;
+    readonly instanceBuffer: Buffer;
+    readonly probeBuffer?: Buffer;
+    readonly probeOffset?: number;
+  }) => Result<
+    {
+      readonly bindGroup: BindGroup;
+      readonly dynamicOffsets: readonly number[];
+      readonly frameBase: number;
+      /** Public Surface member identities covered by the recorded command. */
+      readonly memberIds: readonly string[];
+    },
+    RhiError
+  >;
+  /** Frame-local sink fed only by actual Surface draw commands. */
+  readonly surfaceSubmissionObservation?: import('./surface/submission-observation').SurfaceSubmissionCandidate;
+  /** Existing Standard clustered group(2), supplied by the main-pass owner. */
+  clusterBindGroup?: BindGroup | undefined;
+  /** Rebind the same cluster resources around one batch-local mesh row page. */
+  clusterBindGroupForMesh?:
+    | ((meshBuffer: Buffer, bindingBytes: number) => BindGroup | undefined)
+    | undefined;
+  /** Rebind clustered lighting around the scene-index Mesh/Palette/Morph page. */
+  clusterBindGroupForSkin?:
+    | ((
+        meshBuffer: Buffer,
+        meshBindingBytes: number,
+        paletteBuffer: Buffer,
+        paletteBindingWindowBytes: number,
+      ) => BindGroup | undefined)
+    | undefined;
   resolveClusteredMeshBindGroup?: (binding: GpuDrivenSceneMeshBinding) => BindGroup;
 }
 
@@ -512,6 +594,8 @@ export interface RenderPipelineBuildContext<FrameCtx extends RenderPipelineFrame
    * inferring rgba16float support from the selected surface format.
    */
   readonly capabilities?: Pick<RhiCaps, 'rgba16floatRenderable'>;
+  /** Renderer-derived cloud shadow size shared by graph allocation and projection. */
+  readonly cloudShadowResolution?: number;
   /** Prepared typed graph resources owned by RenderSystem/RenderFrameState. */
   readonly standardOutput?: {
     readonly autoExposure?: {
@@ -541,6 +625,19 @@ export interface RenderPipelineBuildContext<FrameCtx extends RenderPipelineFrame
     readonly currentStability: RenderPipelineTarget;
     readonly previousStability: RenderPipelineTarget;
   };
+  /**
+   * Renderer-owned CloudLayer transport history.  Each pair is backed by the
+   * same submit-fenced temporal owner as TAA, while the three attachments keep
+   * radiance, transmittance and representative depth in separate typed lanes.
+   */
+  readonly cloudHistory?: {
+    readonly currentRadiance: RenderPipelineTarget;
+    readonly previousRadiance: RenderPipelineTarget;
+    readonly currentTransmittance: RenderPipelineTarget;
+    readonly previousTransmittance: RenderPipelineTarget;
+    readonly currentDepth: RenderPipelineTarget;
+    readonly previousDepth: RenderPipelineTarget;
+  };
   /** Renderer-owned SSR temporal history targets for the admitted spatial chain. */
   readonly ssrHistory?: {
     readonly previous: RenderPipelineTarget;
@@ -573,6 +670,15 @@ export interface RenderPipelineBuildContext<FrameCtx extends RenderPipelineFrame
     semanticTargets?: readonly RenderPipelineTarget[],
     namedTargets?: Readonly<Record<string, RenderPipelineTarget>>,
     standardSurfaceAccesses?: readonly GraphAccess[],
+    featureSelectionOrPlacement?:
+      | {
+          /** Project only these identities at this ordered stage. */
+          readonly include?: readonly string[];
+          /** Keep these identities for a later ordered stage. */
+          readonly exclude?: readonly string[];
+        }
+      | RenderFeaturePlacement,
+    passNames?: readonly string[],
   ): Result<void, RenderPipelineBuildError>;
   /** Prepare feature-owned shadow draws and their early compute producers once. */
   contributeShadowFeatures?(): Result<
@@ -585,6 +691,30 @@ export interface RenderPipelineBuildContext<FrameCtx extends RenderPipelineFrame
   ): Result<void, RenderPipelineBuildError>;
   /** Whether a producer-owned feature is installed for this graph build. */
   hasFeature?(identity: string): boolean;
+  /** Whether a producer-owned feature has executable work at this graph build. */
+  hasFeatureWork?(identity: string, placement?: RenderFeaturePlacement): boolean;
+  /** Whether a producer-owned feature has a resolved raster pass this frame. */
+  hasFeatureRasterWork?(identity: string, placement?: RenderFeaturePlacement): boolean;
+}
+
+/** Project the six CloudLayer history attachments into feature target aliases. */
+export function renderPipelineCloudHistoryTargets(input: {
+  readonly currentRadiance: RenderPipelineTarget;
+  readonly previousRadiance: RenderPipelineTarget;
+  readonly currentTransmittance: RenderPipelineTarget;
+  readonly previousTransmittance: RenderPipelineTarget;
+  readonly currentDepth: RenderPipelineTarget;
+  readonly previousDepth: RenderPipelineTarget;
+}): readonly RenderPipelineFeatureTarget[] {
+  const entries: readonly (readonly [string, RenderPipelineTarget])[] = [
+    ['cloud-history-radiance-previous', input.previousRadiance],
+    ['cloud-history-radiance-current', input.currentRadiance],
+    ['cloud-history-transmittance-previous', input.previousTransmittance],
+    ['cloud-history-transmittance-current', input.currentTransmittance],
+    ['cloud-history-depth-previous', input.previousDepth],
+    ['cloud-history-depth-current', input.currentDepth],
+  ];
+  return entries.map(([name, target]) => ({ name, kind: 'scene-color' as const, ...target }));
 }
 
 export type RenderPipelineBuildError = RenderGraphError | RenderError | RhiError;

package/src/render-system-extract-tail.ts

@@ -37,11 +37,11 @@ import {
   ASSET_ERROR_HINTS,
   AssetError,
   derive,
-  err,
   handleSlot,
   materialValuesToLinearRuntime,
   toShared,
 } from '@forgeax/engine-types';
+import { type ExtractedCloudLayer, extractCloudLayer } from './cloud/extract';
 import {
   Atmosphere,
   DirectionalLight,
@@ -92,11 +92,7 @@ import type {
   RenderFeatureWorldVisibilitySnapshot,
 } from './features/types';
 import { ensureGlyphMeshMaterialSlots } from './glyph-text-layout-system';
-import {
-  InstanceCollectionError,
-  type InstanceCollectionId,
-  type InstanceCollectionStore,
-} from './instances';
+import { type InstanceProjectionStore, validateInstanceTransforms } from './instances';
 import { deriveInstancesUnionBounds } from './instances-derived-bounds';
 import {
   type MeshMaterialBindingDiagnostic,
@@ -234,11 +230,12 @@ export function extractFrames(
       request?: {
         readonly vertexColorAvailable?: boolean;
         readonly deformation?: 'rigid' | 'skin';
+        readonly variantSet?: string;
         readonly pass?: 'forward' | 'shadow' | 'depth';
         readonly address?: 'direct' | 'scene-index';
       },
     ) => MaterialShaderArtifact | undefined;
-    readonly instanceCollections?: InstanceCollectionStore;
+    readonly instanceCollections?: InstanceProjectionStore;
   } = {},
 ): ExtractedFrame {
   // w4: normalize the owner argument. A bare number is the legacy single-owner
@@ -569,6 +566,7 @@ export function extractFrames(
   };
 
   const volumetricFog = resourceOwnerFrame?.volumetricFog;
+  const cloudLayer = resourceOwnerFrame?.cloudLayer;
   const skylight = resourceOwnerFrame?.skylight;
   const skylightCount = resourceOwnerFrame?.skylightCount ?? 0;
   const skybox = resourceOwnerFrame?.skybox;
@@ -651,6 +649,7 @@ export function extractFrames(
     ...(volumetricFog === undefined
       ? {}
       : { volumetricFog: { ...volumetricFog, worldId: resourceOwner } }),
+    ...(cloudLayer === undefined ? {} : { cloudLayer }),
     renderables,
     dispatch: dispatchEntries,
     shadowCasterEntityKeys,
@@ -795,6 +794,16 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
   // calls survive untouched, only the entity source changes).
   const worldInternal = createWorldInternalView(world);
   let volumetricFog = extractVolumeSnapshot(world, assets, worldInternal);
+  let cloudLayer: ExtractedCloudLayer | undefined;
+  const extractedCloudLayer = extractCloudLayer(world);
+  if (extractedCloudLayer.ok) {
+    cloudLayer = extractedCloudLayer.value;
+  } else {
+    worldInternal._routeError(extractedCloudLayer.error, {
+      severity: Severity.Error,
+      systemName: 'RenderSystem.extract (cloud-layer)',
+    });
+  }
 
   const cameraRoles = selectCameraRoles(world, context.cameraEntityKey);
   const cameras = [...cameraRoles.display];
@@ -1708,13 +1717,6 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
   // extraction. Shared handles are immutable inputs for the frame, while
   // dispatch entries still need to be rebuilt for each entity.
   const materialSnapshotCache: MaterialSnapshotCache = new Map();
-  // A collection can be associated with more than one entity. Snapshot its
-  // renderer-owned bytes once per extracted frame so culling and every
-  // submission lane consume the same detached revision without repeat copies.
-  const instanceSnapshotCache = new Map<
-    InstanceCollectionId,
-    ReturnType<InstanceCollectionStore['snapshot']>
-  >();
   const skinnedMaterialSnapshotCache: MaterialSnapshotCache = new Map();
   // tweak-20260611 M1: MeshRenderer renderable archetype walk routes
   // through one World-owned Query. K-2 sniffing scheme B
@@ -1779,22 +1781,25 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
   const flushPendingDispatch = (pending: readonly DispatchEntry[]): void => {
     for (const entry of pending) dispatch.push(entry);
   };
-  for (const row of meshRendererQuery) {
-    if (
-      context.renderables === 'full' &&
-      renderableEntities !== undefined &&
-      !renderableEntities.has(row.entity)
-    ) {
-      continue;
-    }
+  const requestedRows =
+    renderableEntities === undefined
+      ? meshRendererQuery
+      : {
+          *[Symbol.iterator]() {
+            for (const entity of renderableEntities) {
+              const row = meshRendererQuery.at(entity as EntityHandle);
+              if (row !== undefined) yield row;
+            }
+          },
+        };
+  for (const row of requestedRows) {
     // K-2 archetype-edge sniff (scheme B): a missing optional component
     // surfaces as an absent bundle key, not a row-internal optional chain.
     // Presence-only checks use QueryRow.has so large array-bearing components
     // are not materialised merely to answer a boolean question.
     const hasTransform = row.has(Transform);
     const meshFilter = row.get(MeshFilter);
-    const instancesData = row.get(Instances);
-    const hasInstances = instancesData !== undefined;
+    const hasInstances = row.has(Instances);
     const skin = row.get(Skin);
     const morphWeightsView = worldInternal._getArrayView(row.entity, MorphWeights, 'weights');
     const hasMeshFilter = meshFilter !== undefined;
@@ -2574,6 +2579,16 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
               baseColor,
               metallic: metallicPv,
               roughness: roughnessPv,
+              ...(resolved.surface?.model === undefined
+                ? {}
+                : { surfaceModel: resolved.surface.model }),
+              deferredPass: allPasses.some(
+                (pass) =>
+                  String(
+                    (pass.renderState?.tags as Record<string, unknown> | undefined)?.LightMode ??
+                      pass.name,
+                  ) === 'Deferred',
+              ),
               ...(specularColorPv !== undefined && {
                 specularColor: [
                   specularColorPv[0] ?? 1,
@@ -3073,49 +3088,29 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
         // make the cull and draw disagree within one frame).
         let instancesSnap: InstancesSnapshot | undefined;
         if (hasInstances) {
-          const collectionId = instancesData?.collectionId as InstanceCollectionId | undefined;
-          let collectionResult =
-            collectionId !== undefined ? instanceSnapshotCache.get(collectionId) : undefined;
-          if (collectionResult === undefined) {
-            collectionResult =
-              collectionId !== undefined && collectionId > 0 && instanceCollections !== undefined
-                ? instanceCollections.snapshot(collectionId)
-                : err(
-                    new InstanceCollectionError(
-                      'instance-collection-invalid',
-                      'Instances.collectionId references a live renderer-owned collection',
-                      'create the collection through renderer.instances before attaching Instances',
-                      {
-                        operation: 'inspect',
-                        expected: 'a positive collectionId with a live renderer owner',
-                        actual: Number(collectionId ?? 0),
-                        ...(collectionId === undefined ? {} : { collectionId }),
-                      },
-                    ),
-                  );
-            if (collectionId !== undefined)
-              instanceSnapshotCache.set(collectionId, collectionResult);
-          }
-          if (collectionResult === undefined) continue;
-          if (!collectionResult.ok) {
-            worldInternal._routeError(collectionResult.error, {
+          const transforms =
+            worldInternal._getArrayView(entity, Instances, 'transforms') ?? new Float32Array();
+          const invalid = validateInstanceTransforms(transforms);
+          if (invalid !== undefined) {
+            worldInternal._routeError(invalid, {
               severity: Severity.Error,
-              systemName: 'RenderSystem.extract (Instances collection)',
+              systemName: 'RenderSystem.extract (Instances transforms)',
             });
             continue;
           }
+          const projected = instanceCollections?.project(world, entity, transforms);
           instancesSnap = {
-            transforms: collectionResult.value.transforms,
-            generations: collectionResult.value.generations,
-            instanceCount: collectionResult.value.count,
-            collectionId: collectionResult.value.collectionId,
-            revision: collectionResult.value.revision,
-            capacity: collectionResult.value.capacity,
-            dirtyRanges: collectionResult.value.dirtyRanges,
+            transforms: projected?.transforms ?? new Float32Array(transforms),
+            instanceCount: transforms.length / 16,
             cacheKey: entity,
-            // Explicit collection revisions supersede ECS archetype content
-            // hashes; retain zero as the legacy sprite-only field value.
-            archVersion: 0,
+            archVersion: projected === undefined ? archVersion : 0,
+            ...(projected === undefined
+              ? {}
+              : {
+                  collectionId: projected.collectionId,
+                  revision: projected.revision,
+                  generations: projected.generations,
+                }),
           };
         }
 
@@ -3391,6 +3386,7 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
     environment,
     environmentReady: true,
     ...(volumetricFog === undefined ? {} : { volumetricFog }),
+    ...(cloudLayer === undefined ? {} : { cloudLayer }),
     renderables,
     dispatch,
     shadowCasterEntityKeys,