@forgeax/engine-render 0.1.19 → 0.1.21

package/src/render-contract.ts

@@ -16,6 +16,7 @@ import type {
   RhiInstance,
   RhiRenderPassEncoder,
   RenderPipeline as RhiRenderPipeline,
+  Sampler,
   Texture,
   TextureFormat,
   TextureView,
@@ -30,20 +31,55 @@ import type { RenderFeature, RenderFeatureDiagnostics } from './features/types';
 import type { PostProcessShaderEntry } from './fullscreen-post-process-pass';
 import type {
   BloomInspection,
+  DirectionalShadowInspection,
   MotionBlurInspection,
+  ReflectionProbeInspection,
   RenderSceneInspection,
   TemporalTargetInspection,
   TransmissionInspection,
 } from './inspection-types';
+import type {
+  RenderTarget,
+  RenderTargetDescriptor,
+  RenderTargetReadbackData,
+  RenderTargetReadbackRequest,
+  RenderTargetReadbackTicket,
+  RenderTargetTextureSource,
+  RenderTargetTextureSourceOptions,
+} from './targets/contracts';
 import type { TemporalInspection } from './temporal/inspection';
 
 export type { TransmissionInspection } from './inspection-types';
 export type { PointsLinesInspection } from './points-lines/inspection';
 
 import type { MeshMaterialBindingObservation } from './mesh-material-bindings';
+import type { StandardLightingInspection } from './pipeline/standard-lighting/inspection';
 import type { StandardProfile } from './pipeline/standard-profile';
+import type { PointShadowInspection } from './point-shadow-inspection';
 import type { PostProcessError } from './post-process-errors';
+import type {
+  GpuPassTimingObservation,
+  GpuPassTimingOptions,
+} from './record/gpu-pass-timing/index.js';
+import type { VolumeTimingObservation } from './record/gpu-timing';
 import type { TemporalView } from './temporal/view';
+import type { VolumetricFogInspection } from './volume/inspection';
+
+export type {
+  CubeCameraFace,
+  CubeCameraUpdateIntent,
+} from './components/cube-camera';
+
+export interface CubeCameraSnapshot {
+  readonly entityKey?: number;
+  readonly target: RenderTarget;
+  readonly position: readonly [number, number, number];
+  readonly near: number;
+  readonly far: number;
+  readonly updateIntent: import('./components/cube-camera').CubeCameraUpdateIntent;
+  readonly requestVersion: number;
+  readonly faceBudget: number;
+}
 
 export type RenderResult<T, E> =
   | { readonly ok: true; readonly value: T }
@@ -62,6 +98,8 @@ export type RenderWorldLease = RenderReadLease;
 export interface CameraSnapshot {
   /** Stable ECS identity used by the frame plan's camera authority fact. */
   readonly entityKey?: number;
+  /** Auxiliary logical target; physical views remain renderer-owned. */
+  readonly target?: RenderTarget;
   /** World index supplied by the multi-world extract merge. */
   readonly worldId?: number;
   /** Camera-owned history generation forwarded into the frame plan. */
@@ -102,6 +140,9 @@ export interface CameraSnapshot {
 /** Stable identity owned by the Standard feature host for output transform. */
 export const STANDARD_OUTPUT_TRANSFORM_FEATURE_ID = 'forgeax::standard::output-transform';
 
+/** Stable identity for the special FXAA pass' per-frame output policy UBO. */
+export const FXAA_POST_PROCESS_ID = 'forgeax::post::fxaa';
+
 export type {
   EnvironmentFrame,
   EnvironmentSource,
@@ -118,6 +159,14 @@ export type { TemporalView } from './temporal/view';
 interface RenderPipelineStateView {
   readonly format: TextureFormat;
   readonly colorAttachmentFormat: TextureFormat;
+  /** Renderer-owned View UBO shared by Standard lighting, shadows, and fog. */
+  readonly viewUniformBuffer: Buffer;
+  /** Renderer-owned SpotLight std430 buffer shared by Standard and volume. */
+  readonly pointLightsBuffer: Buffer;
+  readonly spotLightsBuffer: Buffer;
+  /** Fallback resources keep the shared view layout valid when no projector is authored. */
+  readonly defaultWhiteTextureView: TextureView;
+  readonly defaultSampler: Sampler;
 }
 
 /**
@@ -127,6 +176,16 @@ interface RenderPipelineStateView {
  */
 interface RenderPipelineRuntime {
   readonly device: RhiDevice;
+  /** Runtime-owned shader module factory used by built-in graph producers. */
+  readonly shaderModuleFactory?: {
+    createShaderModule(input: {
+      readonly code: string;
+      readonly label?: string | undefined;
+    }): import('@forgeax/engine-types').Result<
+      import('@forgeax/engine-rhi').ShaderModule,
+      RhiError
+    >;
+  };
   readonly errorRegistry: { fire(error: RendererError): void };
   readonly debugOverlay?: RenderDebugOverlay | undefined;
   readonly lookupPostProcess?: (id: string) => PostProcessShaderEntry | undefined;
@@ -135,6 +194,7 @@ interface RenderPipelineRuntime {
     id: string,
     bgl: BindGroupLayout,
     colorFormat: GPUTextureFormat,
+    entry?: PostProcessShaderEntry,
   ) => RhiRenderPipeline | null;
 }
 
@@ -170,6 +230,56 @@ export interface RenderPipelineContext {
   readonly msaaActive: boolean;
   readonly geometryColorResolveView: TextureView | null;
   readonly ldrSpriteColorView: TextureView | null;
+  /** Renderer-owned volume resources prepared from the authored ECS snapshot. */
+  readonly volumetricFog?: VolumetricFogFrameContext;
+  /** Renderer-owned SpotLight projector resources, independent of fog. */
+  readonly spotLightProjector?: SpotLightProjectorFrameContext;
+  /** Build-time composed utility sources for the renderer-owned volume passes. */
+  readonly volumetricFogShaders?: VolumetricFogShaderSources;
+}
+
+/** Stable utility entry-point sources emitted by the shader manifest. */
+export interface VolumetricFogShaderSources {
+  readonly inject: string;
+  readonly temporal: string;
+  readonly integrate: string;
+  readonly composite: string;
+}
+
+/**
+ * GPU resources for one validated volumetric-fog candidate.  The record stage
+ * owns residency and parameter uploads; graph passes consume this narrow view
+ * and never reach into AssetRegistry or World.
+ */
+export interface VolumetricFogFrameContext {
+  readonly densityTexture: Texture;
+  readonly densityView: TextureView;
+  readonly paramsBuffer: Buffer;
+  readonly densityGeneration: number;
+  /** Accepted graph-owned history slot; null means first frame/reset. */
+  readonly historyReadSlot: 0 | 1 | null;
+  /** Pending graph-owned history slot; promoted only after queue.submit succeeds. */
+  readonly historyWriteSlot: 0 | 1;
+  readonly historyValid: boolean;
+  /** Accepted SpotLight projector resources resolved by the GPU residency owner. */
+  readonly projectorTexture?: Texture;
+  readonly projectorView?: TextureView;
+  readonly projectorSampler?: Sampler;
+}
+
+/**
+ * GPU resources for the single surface SpotLight projector binding. The
+ * projector is a SpotLight-owned cookie and therefore remains available when
+ * volumetric fog is disabled; volume integration may reuse the same tuple.
+ */
+export interface SpotLightProjectorFrameContext {
+  readonly texture: Texture;
+  readonly view: TextureView;
+  readonly sampler: Sampler;
+  /** Spot-light index in ExtractedLights.spot for the accepted texture. */
+  readonly spotIndex?: number;
+  /** Unified Standard Cluster slot index (points precede spots). */
+  readonly lightSlotIndex?: number;
 }
 
 /**
@@ -179,6 +289,20 @@ export interface RenderPipelineContext {
 export interface Renderer {
   attach(world: World): RenderResult<RenderWorldLease, RenderError>;
   draw(input: RenderFrameInput): RenderResult<FrameReceipt, RenderError>;
+  createRenderTarget(descriptor: RenderTargetDescriptor): RenderResult<RenderTarget, RenderError>;
+  resizeRenderTarget(
+    target: RenderTarget,
+    descriptor: RenderTargetDescriptor,
+  ): RenderResult<void, RenderError>;
+  createRenderTargetTextureSource(
+    target: RenderTarget,
+    options: RenderTargetTextureSourceOptions,
+  ): RenderResult<RenderTargetTextureSource, RenderError>;
+  requestTargetReadback(
+    target: RenderTarget,
+    request: RenderTargetReadbackRequest,
+  ): RenderResult<RenderTargetReadbackTicket, RenderError>;
+  destroyRenderTarget(target: RenderTarget): RenderResult<void, RenderError>;
   setProfile(profile: RenderProfile): RenderResult<void, RenderError>;
   state(): RendererState;
   inspect(): RenderInspection;
@@ -189,6 +313,7 @@ export interface Renderer {
   subscribe(listener: (event: RendererEvent) => void): () => void;
   releaseSurface(): RenderResult<void, RenderError>;
   restoreSurface(): RenderResult<void, RenderError>;
+  /** Recover only from device-lost; a healthy renderer returns a guard error. */
   recover(): Promise<RenderResult<void, RenderError>>;
   dispose(): Promise<RenderResult<void, RenderError>>;
 }
@@ -238,11 +363,12 @@ export interface FrameEnvironment {
 
 /**
  * Receipt-bound observation selection. The request is consumed by `observe`
- * only with the matching FrameReceipt and returns a structured Result error
- * when the generation or frame identity is stale.
+ * only with the matching FrameReceipt after `receipt.completed` and returns a
+ * structured Result error when the generation or frame identity is stale.
  */
 export interface FrameObservationRequest {
-  readonly include: readonly ('timings' | 'draws' | 'bindings')[];
+  readonly include: readonly ('timings' | 'draws' | 'bindings' | 'target-readbacks')[];
+  readonly targetReadbacks?: readonly RenderTargetReadbackTicket[];
 }
 
 /**
@@ -273,7 +399,12 @@ export interface RenderFrameInput {
 export interface FrameReceiptObservation {
   readonly frameId: number;
   readonly deviceGeneration: number;
-  readonly include: readonly ('timings' | 'draws' | 'bindings')[];
+  readonly include: readonly ('timings' | 'draws' | 'bindings' | 'target-readbacks')[];
+  /** Receipt-bound Render-owned GPU pass facts; absent when not requested. */
+  readonly timings?: GpuPassTimingObservation | undefined;
+  /** Receipt-bound volume GPU timing facts; absent when not requested. */
+  readonly volumeTimings?: VolumeTimingObservation | undefined;
+  readonly targetReadbacks?: readonly RenderTargetReadbackData[];
 }
 
 /** Stable backend facts for the Standard output transform projection. */
@@ -342,14 +473,21 @@ export interface RenderInspection {
     readonly frameId: number;
     readonly deviceGeneration: number;
   };
+  /** Renderer-owned authored volume projection and submit/LKG state. */
+  readonly volumetricFog?: VolumetricFogInspection;
   readonly features: readonly string[];
   /** Truthful lifecycle facts for every registered declarative feature. */
   readonly featureDiagnostics: readonly RenderFeatureDiagnostics[];
   readonly frustumStats: { readonly culled: number; readonly total: number };
   readonly visibilityStats: { readonly explicitlyHidden: number };
   readonly renderScene: RenderSceneInspection;
+  readonly reflectionProbes: ReflectionProbeInspection;
   /** Last completed transmission candidate facts, detached from GPU handles. */
   readonly transmission?: TransmissionInspection;
+  /** Last prepared Standard transport facts, detached from GPU handles. */
+  readonly standardLighting?: StandardLightingInspection;
+  /** Renderer-owned point-shadow atlas budget facts from the last frame. */
+  readonly pointShadow?: PointShadowInspection;
   readonly meshMaterialBindings: readonly MeshMaterialBindingObservation[];
   readonly perFramePassNames: readonly string[];
   readonly bindGroupCounts: {
@@ -370,6 +508,7 @@ export interface RenderInspection {
   readonly environment: EnvironmentInspection;
   readonly temporal: TemporalInspection;
   readonly bloom: BloomInspection;
+  readonly directionalShadow: DirectionalShadowInspection;
   /** Semantic Standard temporal target metadata; no graph or RHI handles. */
   readonly temporalTarget?: TemporalTargetInspection;
   /** Renderer-owned Motion Blur facts; absent when no component is active. */
@@ -577,8 +716,12 @@ export interface RendererOptions {
   readonly standardProfile?: RenderProfile | undefined;
   /** Explicit profiler capability shared by App and Render. */
   readonly profiler?: Profiler | undefined;
+  /** Explicitly request timestamp-query for receipt-bound GPU profiling. */
+  readonly captureGpuTimings?: boolean | undefined;
   /** Optional host-owned RHI lifecycle instrumentation, such as recording. */
   readonly rhiInstrumentation?: RhiBackendInstrumentation | undefined;
+  /** Optional bounded GPU pass timing facts; this is not frame latency. */
+  readonly gpuPassTiming?: GpuPassTimingOptions | undefined;
   // feat-20260608-create-app-param-surface-trim / M1 / AC-02: `clearColor`
   // was deleted as a one-cut breaking change (AGENTS.md Change stance +
   // requirements constraint #1: no deprecation window, no shim). Scene

package/src/render-data.ts

@@ -15,7 +15,6 @@
 // GPU-resource kind would surface as a `tsc -b` exhaustiveness error at the
 // switch rather than a silent fallthrough (AC-06).
 
-import { numMipLevels } from '@forgeax/engine-assets-runtime';
 import {
   bytesPerRow as blockBytesPerRow,
   blockParamsForFormat,
@@ -29,9 +28,11 @@ import { err, ok, type Result } from '@forgeax/engine-rhi';
 import {
   ASSET_ERROR_HINTS,
   type AssetError,
+  deriveTextureLayout,
   type MeshAsset,
   type Submesh,
   type TextureAsset,
+  type TextureShape,
 } from '@forgeax/engine-types';
 import {
   GPU_TEXTURE_USAGE_COPY_DST,
@@ -88,12 +89,16 @@ export interface MeshRenderData {
   readonly submeshes: readonly Submesh[];
 }
 
-/** Descriptor for a 2D texture's GPU resource (projected from POD). */
+/** Descriptor for a sampled texture's GPU resource (projected from POD). */
 export interface TextureRenderData {
   /** Logical width retained for existing projection consumers. */
   readonly width: number;
   /** Logical height retained for existing projection consumers. */
   readonly height: number;
+  /** Authored shape; the residency layer must preserve this view dimension. */
+  readonly shape: TextureShape;
+  /** Array layers for `2d-array`, depth slices for `3d`, otherwise one. */
+  readonly depthOrArrayLayers: number;
   /** Authored content extent; TextureAsset remains the logical asset SSOT. */
   readonly logicalExtent: TextureExtent;
   /** GPU allocation extent, derived from format + logicalExtent. */
@@ -105,10 +110,10 @@ export interface TextureRenderData {
   readonly usage: number;
   /**
    * Row pitch for the BASE mip (level 0) the store passes to `writeTexture`.
-   * Uncompressed: `width * 4` (RGBA8). Block-compressed: the block-padded
-   * `ceil(width / blockW) * bytesPerBlock` (feat-20260707 M5 / w35, AC-08).
-   * The per-mip layout for a multi-level compressed upload comes from
-   * {@link deriveMipUploadLayout}.
+   * Derived from the canonical texture layout, so format-specific uncompressed
+   * widths (for example R8 density) and block-compressed widths stay aligned
+   * with the upload contract. The per-mip layout for a multi-level compressed
+   * upload comes from {@link deriveMipUploadLayout}.
    */
   readonly bytesPerRow: number;
   /** True iff `format` is a block-compressed format (drives the store's upload arm). */
@@ -262,6 +267,8 @@ export function deriveRenderDataMesh(mesh: MeshAsset): Result<MeshRenderData, As
  * inconsistent (a `-srgb` format requires an `srgb` colorSpace and vice versa).
  */
 export function deriveRenderDataTexture(tex: TextureAsset): Result<TextureRenderData, AssetError> {
+  const width = tex.shape.extent.width;
+  const height = tex.shape.extent.height;
   const isSrgbFormat = tex.format.endsWith('-srgb');
   const expectedColorSpace: 'srgb' | 'linear' = isSrgbFormat ? 'srgb' : 'linear';
   if (tex.colorSpace !== expectedColorSpace) {
@@ -275,14 +282,23 @@ export function deriveRenderDataTexture(tex: TextureAsset): Result<TextureRender
   }
 
   const compressed = isCompressedFormat(tex.format);
+  const layout = deriveTextureLayout({ shape: tex.shape, format: tex.format, mips: tex.mips });
+  if (!layout.ok) {
+    return err(
+      projectionError({
+        code: 'invalid-source-format',
+        expected: layout.error.expected,
+        hint: layout.error.hint,
+      }),
+    );
+  }
   // feat-20260707 M5 / w35 (AC-09, D-9): a block-compressed texture cannot have
   // its mips GPU-generated (F-7). An OFFLINE chain baked into `data`
   // (mipLevelCount > 1, e.g. a KTX2 level chain) is the normal compressed path
   // and passes; requesting RUNTIME mip generation (`mipmap:true` with no offline
   // chain) fails fast with a self-recovery hint (fail-fast at the projection
   // layer -- producer self-validate).
-  const hasOfflineMipChain = (tex.mipLevelCount ?? 1) > 1;
-  if (compressed && tex.mipmap === true && !hasOfflineMipChain) {
+  if (compressed && tex.mips.kind === 'generate') {
     return err(
       projectionError({
         code: 'mipgen-unsupported-compressed-format',
@@ -296,15 +312,19 @@ export function deriveRenderDataTexture(tex: TextureAsset): Result<TextureRender
   // Uncompressed: runtime mip-gen count from the pixel size. Compressed: the
   // level count is authored (offline chain) -- honour the POD's mipLevelCount,
   // never re-derive it from the size (a compressed chain may stop early).
-  const mipLevelCount = compressed
-    ? Math.max(1, tex.mipLevelCount ?? 1)
-    : tex.mipmap
-      ? numMipLevels(tex)
-      : 1;
+  const mipLevelCount = layout.value.levels.length;
 
-  const uncompressedBytesPerTexel =
-    tex.format === 'rgba32float' ? 16 : tex.format === 'rgba16float' ? 8 : 4;
-  if (!compressed && tex.data.byteLength < tex.width * tex.height * uncompressedBytesPerTexel) {
+  const baseLevel = layout.value.levels[0];
+  if (baseLevel === undefined) {
+    return err(
+      projectionError({
+        code: 'invalid-source-format',
+        expected: 'texture layout contains a base mip level',
+        hint: ASSET_ERROR_HINTS['invalid-source-format'],
+      }),
+    );
+  }
+  if (!compressed && tex.data.byteLength < baseLevel.byteLength) {
     return err(
       projectionError({
         code: 'invalid-source-format',
@@ -318,8 +338,8 @@ export function deriveRenderDataTexture(tex: TextureAsset): Result<TextureRender
   // from the format, not aggregate payload length: imported images may retain
   // trailing decoder bytes and offline mip chains contain more than the base mip.
   const bytesPerRow = compressed
-    ? (blockBytesPerRow(tex.format, tex.width) ?? tex.width * 4)
-    : tex.width * uncompressedBytesPerTexel;
+    ? (blockBytesPerRow(tex.format, width) ?? baseLevel.bytesPerRow)
+    : baseLevel.bytesPerRow;
 
   // Compressed formats are not renderable -- RENDER_ATTACHMENT would fail
   // createTexture validation, and the runtime mipmap blit (which needs it) never
@@ -333,9 +353,16 @@ export function deriveRenderDataTexture(tex: TextureAsset): Result<TextureRender
       GPU_TEXTURE_USAGE_COPY_SRC;
 
   return ok({
-    width: tex.width,
-    height: tex.height,
-    ...deriveTextureExtent(tex.format, tex.width, tex.height),
+    width,
+    height,
+    shape: tex.shape,
+    depthOrArrayLayers:
+      tex.shape.viewDimension === '2d'
+        ? 1
+        : tex.shape.viewDimension === '2d-array'
+          ? tex.shape.extent.layers
+          : tex.shape.extent.depth,
+    ...deriveTextureExtent(tex.format, width, height),
     format: tex.format,
     mipLevelCount,
     usage,
@@ -373,8 +400,9 @@ export function deriveRenderDataCubemap(source: TextureAsset): Result<CubeRender
       }),
     );
   }
+  const sourceHeight = source.shape.viewDimension === '2d' ? source.shape.extent.height : 0;
   return ok({
-    cubeFaceSize: source.height,
+    cubeFaceSize: sourceHeight,
     outputFormat: 'rgba16float',
     needsHalfConversion: source.format === 'rgba32float',
     cubeUsage:

package/src/render-graph-primitives.ts

@@ -550,6 +550,7 @@ function dispatchFullscreenPass(
   graphPass?: RhiRenderPassEncoder,
   graphOutputFormat?: GPUTextureFormat,
   graphDepthView?: TextureView,
+  paramsOverride?: Uint8Array,
 ): void {
   if (shader === 'fxaa') {
     if (resolveCtx === undefined) {
@@ -705,7 +706,11 @@ function dispatchFullscreenPass(
   if (entry.params !== undefined) {
     const ubo = ctx.runtime.getPostProcessParamsBuffer?.(shader);
     if (ubo !== undefined) {
-      const data = ctx.postProcessParams.get(shader);
+      // Typed graph passes may make a narrow, per-pass copy of the payload
+      // (for example enabling final-surface dither without changing the
+      // camera-owned SSOT).  Use it when present, while preserving the normal
+      // frame snapshot for legacy callers.
+      const data = paramsOverride ?? ctx.postProcessParams.get(shader);
       if (data !== undefined) {
         if (data.byteLength !== entry.params.byteSize) {
           throw new PostProcessError({
@@ -769,9 +774,7 @@ function dispatchFullscreenPass(
   if (lookupPipeline === undefined) return;
   const postColorFormat = writeFormat;
   const pipeline = lookupPipeline(shader, built.bindGroupLayout, postColorFormat);
-  if (pipeline === null) {
-    return;
-  }
+  if (pipeline === null) return;
   const handle = built.createHandle(name, pipeline, paramsBuffer);
 
   // Open a render pass writing into the resolved color target. Fullscreen
@@ -810,6 +813,7 @@ export function encodeFullscreenPass(
     readonly outputFormat: GPUTextureFormat;
     readonly rawSwapchainOutput?: boolean | undefined;
     readonly depthView?: TextureView | undefined;
+    readonly paramsOverride?: Uint8Array | undefined;
   },
 ): void {
   dispatchFullscreenPass(
@@ -824,5 +828,6 @@ export function encodeFullscreenPass(
     pass,
     input.outputFormat,
     input.depthView,
+    input.paramsOverride,
   );
 }