@forgeax/engine-render 0.1.3 → 0.1.6

package/src/render-pipeline-context.ts

@@ -1,332 +0,0 @@
-// @forgeax/engine-render - pass execution context for typed frame graphs.
-//
-// This type replaces the former full-field `RecordPassContext` (26 top-level fields,
-// one of which - `internals: RenderSystemInternals` - was itself a ~16-field
-// kitchen-sink). The whole point of M2 is that `internals` is GONE: a pipeline author
-// can no longer reach the entire `RenderSystemInternals` private surface through the
-// public pipeline ctx. `ctx.internals` is a compile error (the AC-08 oracle); the
-// genuine runtime dependencies are now named, narrow surfaces.
-//
-// UE mental model (requirements: anchor the clean ctx on Unreal vocabulary):
-//   - The per-VIEW input aggregate (camera + targets + the validated draw list + the
-//     per-frame bind groups + the per-frame flags) is the forgeax analogue of UE's
-//     `FSceneView` - the stable-per-view render inputs a pass reads.
-//   - The RESOURCE + RUNTIME carriers (`assets` / `store` / `pipelineState` / `runtime`)
-//     are the analogue of UE's `FRDGBuilder` handle - the substrate a pass uses to
-//     resolve resources and record GPU work. The #289 three-layer surface lands here:
-//     `assets` = CPU POD (AssetRegistry), `store` = GPU residency (GpuResourceStore),
-//     `pipelineState` = the prebuilt per-RenderSystem GPU layouts/buffers.
-//
-// Field grouping below is documented (FSceneView vs FRDGBuilder) with grep-able field
-// names so an AI user reading the type knows what each field is FOR, not just its type.
-
-import type { World } from '@forgeax/engine-ecs';
-import type { BindGroup, RhiCommandEncoder, Texture, TextureView } from '@forgeax/engine-rhi';
-import type { RenderAssetPort } from './assets/render-asset-port';
-import type { MultiViewProductionSubmission } from './gpu-driven/production-raster';
-import type { GpuResourceStore } from './gpu-resource-store';
-import type {
-  BindGroupCounts,
-  DispatchCounts,
-  MaterialBgAssemblyCacheEntry,
-  RasterItemKey,
-  RenderFrameState,
-  ValidatedRenderable,
-} from './record';
-import type { PipelineState, RenderSystemRuntime } from './render-system';
-import type {
-  CameraSnapshot,
-  DispatchEntry,
-  MaterialSnapshot,
-  SkyboxSnapshot,
-  SkylightSnapshot,
-} from './render-system-extract';
-import type { RenderRecordPhase } from './renderer';
-import type { TemporalFrameAttempt } from './temporal-frame-transaction';
-
-/**
- * Narrow runtime-services carrier handed to pipeline pass closures (UE `FRDGBuilder`
- * analogue, runtime half). The named, minimal replacement for the four
- * `RenderSystemInternals` members the 9 urp closures genuinely reach: the
- * GPU `device`, the `errorRegistry` structured-error sink, and the two per-MaterialShader
- * pipeline-cache / param-schema lookups. Deliberately NOT the full `RenderSystemInternals`
- * - a pipeline author sees exactly these four services and nothing else (charter P4: a
- * consistent narrow abstraction over the runtime, not the kitchen-sink).
- *
- * SSOT for the member types lives in `render-system.ts` `RenderSystemRuntime`; re-exported
- * here so a pipeline author importing the ctx type sees the runtime-services shape too.
- */
-export type { RenderSystemRuntime } from './render-system';
-
-/**
- * The clean dependency face each typed render-graph pass consumes. Strictly smaller and strictly named relative to
- * the former `RecordPassContext`: `internals: RenderSystemInternals` is gone (replaced by
- * the named `assets` / `store` / `pipelineState` / `runtime` surfaces) and the
- * 0-consumed `skyboxCount` residual is dropped.
- *
- * feat-20260604 M3 / w20 (D-7 breaking direct cut, no deprecation/shim/dual-path):
- * SIX urp-specific leakage fields are gone from the public surface
- * (`tonemapActive` / `geometryColorView` / `geometryDepthView` / `skyboxActive` /
- * `splitLdrSprite` / `ldrSpritePassView`). They were urp-private
- * post-process gating + RT view selection state that an AI-user-defined custom
- * pipeline must NOT see — topology branches use `RenderPipelineTopology` and
- * graph resources use typed handles. The fields persist as an internal extension consumed
- * by the urp record* closures only (see `_StandardForwardSceneView`
- * in `render-system-record.ts`).
- *
- * The 3 MSAA fields (`msaaActive` / `geometryColorResolveView` /
- * `ldrSpriteColorView`) are KEPT — MSAA renders are not urp-
- * specific; any pipeline using a multisampled typed target needs the
- * resolve targets in scope.
- *
- * Two documented groups (UE mental model):
- *
- * 1. PER-VIEW INPUTS (UE `FSceneView`) - the stable-per-view render inputs:
- *    `encoder` / `view` / `clear` / `targetW` / `targetH` / `currentTexture` / `camera`
- *    / `validated` / `validatedOrdered` / `viewBindGroup` / `meshBindGroup` /
- *    `frameState` / `dispatchCounts` / `bindGroupCounts` / `skylight` /
- *    `skylightCount` / `skybox` / `msaaActive` / `geometryColorResolveView` /
- *    `ldrSpriteColorView`.
- *
- * 2. RESOURCE + RUNTIME CARRIERS (UE `FRDGBuilder` + #289 three-layer):
- *    `assets` (CPU POD) / `store` (GPU residency) / `pipelineState` (prebuilt GPU
- *    layouts/buffers) / `runtime` (device + errorRegistry + shader-cache lookups).
- */
-export interface RenderPipelineContext {
-  // ── Resource + runtime carriers (FRDGBuilder + #289 three-layer) ──────────
-  /** CPU POD registry (#289 layer 1). Pipeline closures read `assets.get<T>(handle)`. */
-  readonly assets: RenderAssetPort;
-  /** GPU residency store (#289 layer 2). `store.ensureResident` + `store.getXxxGpuView`. */
-  readonly store: GpuResourceStore;
-  /** Prebuilt per-RenderSystem GPU layouts / buffers / pipelines (#289 layer 3). */
-  readonly pipelineState: PipelineState;
-  /** Narrow runtime services (device + errorRegistry + shader-cache lookups). */
-  readonly runtime: RenderSystemRuntime;
-
-  // ── Per-view inputs (FSceneView) ─────────────────────────────────────────
-  readonly encoder: RhiCommandEncoder;
-  readonly view: TextureView;
-  readonly clear: readonly [number, number, number, number] | number[];
-  readonly targetW: number;
-  readonly targetH: number;
-  readonly currentTexture: Texture;
-  readonly camera: CameraSnapshot;
-  readonly validated: readonly ValidatedRenderable[];
-  readonly validatedOrdered: readonly ValidatedRenderable[];
-  readonly viewBindGroup: BindGroup | null;
-  readonly meshBindGroup: BindGroup | null;
-  readonly frameState: RenderFrameState;
-  readonly dispatchCounts: DispatchCounts;
-  readonly bindGroupCounts: BindGroupCounts;
-  readonly skylight: SkylightSnapshot | undefined;
-  readonly skylightCount: number;
-  readonly skybox: SkyboxSnapshot | undefined;
-  /**
-   * Per-frame post-process params snapshot collected from PostProcessParams
-   * entities (D-1: data-driven params channel). Maps shader id to raw
-   * bytes (Uint8Array). dispatchFullscreenPass queries this map per-shader.
-   * Empty when no PostProcessParams entities exist.
-   */
-  readonly postProcessParams: ReadonlyMap<string, Uint8Array>;
-
-  // ── MSAA (feat-20260604-learn-render-4.10-anti-aliasing-msaa M2 / w9-w10) ──
-  /**
-   * True when the active camera requests MSAA and the RHI reports a compatible
-   * backend. Derived from `camera.antialias` plus the device capability, never
-   * stored separately (C-9 / D-6). When true the geometry pass writes a count=4
-   * multisample colour target and resolves to a single-sample output; when
-   * false every attachment / pipeline is single-sample (including the
-   * capability-accurate WebGL2 fallback route).
-   */
-  readonly msaaActive: boolean;
-  /**
-   * Single-sample resolve output for the main geometry colour pass when
-   * `msaaActive`. LDR path: the swap-chain srgb view; HDR path: the
-   * `hdrColorResolve` view the tonemap / bloom passes sample. `null` when
-   * `msaaActive` is false (no resolve target -- direct single-sample render).
-   */
-  readonly geometryColorResolveView: TextureView | null;
-  /**
-   * Count=4 multisample view the LDR sprite split sub-pass writes when
-   * `msaaActive && splitLdrSprite`; it resolves to the single-sample
-   * `ldrSpritePassView`. The single-sample view is graph-owned on native
-   * linear-LDR frames and uses raw swap-chain storage on the fallback path.
-   * `null` when `msaaActive` is false. (F-1)
-   */
-  readonly ldrSpriteColorView: TextureView | null;
-}
-
-/**
- * @internal — package-private extension consumed by urp record*
- * closures only. NOT exported from the runtime barrel; AI-user-defined custom
- * pipelines see the public `RenderPipelineContext` shape only (D-7).
- *
- * The six fields here used to live on the public `RenderPipelineContext` until
- * w20 narrowed it. They carry the urp post-process gating +
- * geometry RT view selection state the record* closures depend on:
- *
- * - `tonemapActive`: HDR -> LDR tonemap branch.
- * - `geometryColorView`/`geometryDepthView`: pre-resolved RT views the main
- *   pass writes (HDR-or-swap-chain colour, per-pass-or-HDR depth). After M3
- *   these come from the graph (resolve(name) in execute closure), so a
- *   future-pure addScenePass closure would receive them via resolve().
- * - `skyboxActive`: gates the recordSkyboxPass body.
- * - `splitLdrSprite`: gates the LDR sprite split sub-pass within recordMainPass
- *   / recordTonemapPass.
- * - `ldrSpritePassView`: the single-sample color view the sprite split writes;
- *   it is graph-owned on native linear-LDR and raw swap-chain storage on the
- *   fallback path. The MSAA view remains `ldrSpriteColorView`.
- *
- * Invariant: a public `RenderPipelineContext` cast to this type by
- * `_asInternalCtx` (in render-system-record.ts) MUST originate from
- * recordFrame's passCtx builder; downstream consumers (custom pipelines) MUST
- * NOT cast — these fields are not part of the public contract.
- */
-export interface _StandardForwardSceneView {
-  /** @internal Active successful-submit transaction facts for temporal graph resources. */
-  readonly temporalFrame: TemporalFrameAttempt | undefined;
-  /** @internal Opt-in nested CPU observer inherited from recordFrame. */
-  readonly profilePhase?: <T>(phase: RenderRecordPhase, action: () => T) => T;
-  /** @internal Skip directional caster recording when the atlas token is unchanged. */
-  readonly directionalShadowCacheReuse: boolean;
-  /** @internal Bounded cascade-local validity tokens used by semantic observation. */
-  readonly directionalShadowCacheTokens?: readonly string[];
-  /** @internal Bit i is set when cascade i matched the prior successful atlas token. */
-  readonly directionalShadowCacheHitMask?: number;
-  /** @internal Four-view visibility joined to the shared batch-aligned submission. */
-  readonly multiViewSubmissions: readonly MultiViewProductionSubmission[];
-  /** @internal Canonical CSM receiver/caster membership plan. */
-  readonly directionalCsmPlan: import('./extract/directional-csm').DirectionalCsmResult | undefined;
-  /** @internal Enables producer-owned CSM causal markers for debug capture. */
-  readonly shadowDebugObservation?: boolean | undefined;
-  /**
-   * @internal — feat-20260614 M8 (D-19): the live World the record stage
-   * resolves user-tier asset handles against. Asset payloads moved off the
-   * AssetRegistry onto `world.sharedRefs`, so `world.sharedRefs.resolve(handle)`
-   * is the only resolution entry point; the record stage threads the World here
-   * (it is not part of the public `RenderPipelineContext` — custom pipeline
-   * authors never see it).
-   */
-  readonly world: World;
-  /** @internal Raster items submitted by the GPU-driven Geometry lane this frame. */
-  readonly gpuDrivenItemKeys: ReadonlySet<RasterItemKey>;
-  /** @internal True when the GPU lane owns every forward Geometry item this frame. */
-  readonly gpuDrivenOwnsAllForwardItems: boolean;
-  /** @internal Candidate-index membership for the batch-aligned CPU shadow executor. */
-  readonly validatedByCandidateIndex?: ReadonlyMap<number, ValidatedRenderable>;
-  /** @internal ValidatedOrdered slot for the same candidate-index owner. */
-  readonly validatedIndexByCandidateIndex?: ReadonlyMap<number, number>;
-  /**
-   * @internal Main-view shadow geometry owner. The frame builder computes the
-   * stable validated slot once; point/spot compatibility passes reuse it
-   * instead of rescanning validatedOrdered for every face/tile.
-   */
-  readonly validatedShadowEntries?: readonly {
-    readonly entry: ValidatedRenderable;
-    readonly validatedIndex: number;
-  }[];
-  readonly tonemapActive: boolean;
-  readonly geometryColorView: TextureView | null;
-  readonly geometryDepthView: TextureView | null;
-  /**
-   * @internal — graph key owning the active geometry depth attachment. URP's
-   * MSAA route writes `hdrDepthMsaa` while depth post-process registrations
-   * retain the stable logical `depth` key; the dispatcher uses this fact to
-   * bind the matching sample-count texture.
-   */
-  readonly geometryDepthKey: string | null;
-  readonly skyboxActive: boolean;
-  readonly splitLdrSprite: boolean;
-  readonly ldrSpritePassView: TextureView | null;
-  /** @internal Attachment format selected by a typed graph-owned scene pass. */
-  readonly transparentColorFormat?: GPUTextureFormat;
-  /** feat-20260609 M2: per-frame dispatch entries for selector-based pass filtering. */
-  readonly dispatch: readonly DispatchEntry[];
-  /** @internal Complete union dispatch consumed by directional/point/spot shadow passes. */
-  readonly shadowDispatch: readonly DispatchEntry[];
-  /**
-   * @internal — feat-20260609-hdrp-cluster-fragment-ggx M4 / w15.
-   *
-   * The unified group(2) BindGroup the HDRP cluster-forward path binds at the
-   * mesh slot. Carries the mesh SSBO at binding 0 (with dynamic offset, same
-   * buffer as URP's `meshBindGroup`) plus the 4 HDRP cluster buffers at
-   * bindings 3..6 (light_data / cluster_grid / light_index_list /
-   * cluster_uniform). Non-null when `frameState.isHdrpActive` AND the HDRP
-   * buffers have been allocated for the runtime; `null` on URP frames or when
-   * HDRP buffer allocation failed.
-   *
-   * Plan D-4 (no `extraBindGroups` patch): the cluster bindings flow through
-   * an explicit field on the internal scene-view extension; AI-user-defined
-   * custom pipelines never see it (extension is `@internal`). recordMainPass
-   * destructures it and selects it instead of `meshBindGroup` at
-   * `setBindGroup(2, ...)` on HDRP frames; the single dynamic offset
-   * (`i * MESH_PER_ENTITY_STRIDE`) stays valid because binding 0 of the unified
-   * BGL is the same per-entity mesh SSBO.
-   */
-  readonly hdrpClusterBindGroup: BindGroup | null;
-  /** @internal Compute-only group for the optional HDRP membership producer. */
-  readonly hdrpClusterMembershipBindGroup: BindGroup | null;
-  /**
-   * @internal — feat-20260622-chunk-gpu-instancing-sprite-tilemap M1 /
-   * w4-record-swap (D-1).
-   *
-   * The per-frame fold dispatch plan keyed by validatedOrdered index.
-   * `null` when `transparentDispatch.length === 0` or when no fold-eligible
-   * (bucketSize > 1) bucket exists this frame — the dispatch loops fall
-   * through to the existing per-entity drawIndexed path byte-identically.
-   *
-   * Non-null carries:
-   * - `headBuckets[i]` — bucket descriptor for index `i` (head of an
-   *   instanced draw); the dispatch loop overrides @group(3) instances BG
-   *   and emits one `drawIndexed(idxCount, bucket.bucketSize)`.
-   * - `skipIndices[i]` — true when index `i` is a non-head member of
-   *   a fold bucket; the dispatch loop emits `continue`.
-   *
-   * Plan D-1 (record-stage transparent fold): the plan reuses the
-   * transparent-sort equivalence class as the bucket key, so no new
-   * BinKey type. Mode-gate (D-5): only mode 0 produces non-singleton
-   * buckets; modes 1/2/3 produce all-singleton plans which are byte-
-   * identical to no plan.
-   */
-  readonly foldDispatchPlan: import('./render-system-fold').FoldDispatchPlan | null;
-  /** @internal Per-renderable material-index to deduplicated UBO-slot mapping. */
-  readonly materialSlotIndices: readonly (readonly number[])[];
-  /** @internal Unique material snapshots stored by the frame-local UBO table. */
-  readonly materialSlots: readonly MaterialSnapshot[];
-  /** @internal First renderable index associated with each unique slot. */
-  readonly materialSlotOwners: readonly number[];
-  /** @internal Number of unique material slots in `materialSlots`. */
-  readonly materialSlotCount: number;
-  /** @internal Cross-frame material bind-group assembly cache shared by main passes. */
-  readonly materialBgAssemblyCache: Map<number, MaterialBgAssemblyCacheEntry>;
-  /** @internal Per-frame material UBO bytes shared by repeated main passes. */
-  materialUboPayloadCache?: {
-    readonly materialSlots: readonly MaterialSnapshot[];
-    readonly materialSlotCount: number;
-    readonly materialResourceEpoch: number;
-    readonly payload: Uint8Array;
-  };
-  /**
-   * @internal — feat-20260612-hdrp-ssao wiring fix.
-   *
-   * The compiled `ssaoBlurred` graph-transient TextureView, resolved inside the
-   * HDRP forward pass execute closure (the only place `resolveCtx` is live) and
-   * stashed here for recordMainPass to build the SSAO-enabled unified group(2)
-   * bind group. `undefined` when SSAO is disabled or on URP frames — then
-   * recordMainPass keeps the white-fallback bind group (identity AO=1.0).
-   *
-   * Mutable (not readonly): the forward pass closure assigns it per frame just
-   * before delegating to recordMainPass. The group(2) bind group cannot carry
-   * the view ahead of typed graph execution because the texture is graph-owned.
-   */
-  hdrpSsaoBlurredView?: import('@forgeax/engine-rhi').TextureView;
-}
-
-/**
- * @internal — the type passed to urp record* closures by
- * `recordFrame`. Public `RenderPipelineContext` plus the six urp
- * scene-view leakage fields under a flat structure (so existing destructures
- * like `c.tonemapActive` continue to work without churn). Custom pipelines
- * must NOT see this type.
- */
-export type _InternalRenderPipelineContext = RenderPipelineContext & _StandardForwardSceneView;

package/src/render-pipeline-target.ts

@@ -1,96 +0,0 @@
-import type {
-  GraphTexture,
-  GraphTextureDescriptor,
-  GraphTextureView,
-  GraphTextureViewDescriptor,
-  RenderGraphBuilder,
-  RenderGraphError,
-} from '@forgeax/engine-render-graph';
-import { ok, type Result } from '@forgeax/engine-types';
-import {
-  GPU_TEXTURE_USAGE_COPY_SRC,
-  GPU_TEXTURE_USAGE_RENDER_ATTACHMENT,
-} from './gpu-texture-usage';
-import type { RenderPipelineFrame, RenderPipelineTopology } from './render-pipeline';
-
-export interface RenderPipelineTarget {
-  readonly texture: GraphTexture;
-  readonly view: GraphTextureView;
-  readonly format: string;
-  readonly sampleCount: 1 | 4;
-  readonly resolveTarget?: GraphTextureView | undefined;
-}
-
-export function createRenderPipelineTarget(
-  graph: RenderGraphBuilder<RenderPipelineFrame>,
-  label: string,
-  descriptor: GraphTextureDescriptor,
-  viewDescriptor: GraphTextureViewDescriptor = {},
-): Result<RenderPipelineTarget, RenderGraphError> {
-  const texture = graph.createTexture(label, descriptor);
-  if (!texture.ok) return texture;
-  const view = graph.view(texture.value, { label: `${label}.view`, ...viewDescriptor });
-  if (!view.ok) return view;
-  return ok({
-    texture: texture.value,
-    view: view.value,
-    format: viewDescriptor.format ?? descriptor.format,
-    sampleCount: descriptor.sampleCount === 4 ? 4 : 1,
-  });
-}
-
-export function importRenderPipelineSurface(
-  graph: RenderGraphBuilder<RenderPipelineFrame>,
-  topology: RenderPipelineTopology,
-): Result<
-  { readonly display: RenderPipelineTarget; readonly storage: RenderPipelineTarget },
-  RenderGraphError
-> {
-  const texture = graph.importTexture(
-    'surface',
-    {
-      format: topology.surface.storageFormat,
-      size: 'surface',
-      usage: GPU_TEXTURE_USAGE_RENDER_ATTACHMENT | GPU_TEXTURE_USAGE_COPY_SRC,
-      viewFormats:
-        topology.surface.storageFormat === topology.surface.viewFormat
-          ? []
-          : [topology.surface.viewFormat],
-    },
-    (frame) => frame.currentTexture,
-  );
-  if (!texture.ok) return texture;
-  const display = graph.importView(
-    texture.value,
-    { label: 'surface.display', format: topology.surface.viewFormat },
-    (frame) => frame.view,
-  );
-  if (!display.ok) return display;
-  const storage = graph.importView(
-    texture.value,
-    { label: 'surface.storage', format: topology.surface.storageFormat },
-    (frame) => {
-      if (topology.surface.storageFormat === topology.surface.viewFormat) return frame.view;
-      const resolved = frame.runtime.device.createTextureView(frame.currentTexture, {
-        format: topology.surface.storageFormat,
-      });
-      if (!resolved.ok) throw resolved.error;
-      return resolved.value;
-    },
-  );
-  if (!storage.ok) return storage;
-  return ok({
-    display: {
-      texture: texture.value,
-      view: display.value,
-      format: topology.surface.viewFormat,
-      sampleCount: 1,
-    },
-    storage: {
-      texture: texture.value,
-      view: storage.value,
-      format: topology.surface.storageFormat,
-      sampleCount: 1,
-    },
-  });
-}