@forgeax/engine-render 0.1.29 → 0.1.31

package/src/render-contract.ts

@@ -23,15 +23,16 @@ import type {
 } from '@forgeax/engine-rhi';
 import type { SkinError } from '@forgeax/engine-skinning';
 import type { ImageError } from '@forgeax/engine-types';
-import type { RhiBackendInstrumentation } from './assembly/backend-contract';
-import type { Antialias, BloomEnabled, CameraExposure, Tonemap } from './components/camera';
-import type { ScreenSpaceReflectionData } from './components/screen-space-reflection';
-import type { EnvironmentInspection } from './environment/inspection';
-import type { GpuDrivenPreparationError } from './errors/gpu-driven';
-import type { RecoveryOutcome, RecoveryPhase } from './errors/recover';
-import type { RenderError } from './errors/render';
-import type { RenderFeature, RenderFeatureDiagnostics } from './features/types';
-import type { PostProcessShaderEntry } from './fullscreen-post-process-pass';
+import type { RhiBackendInstrumentation } from './assembly/backend-contract.js';
+import type { Antialias, BloomEnabled, CameraExposure, Tonemap } from './components/camera.js';
+import type { DynamicResolutionData } from './components/dynamic-resolution.js';
+import type { ScreenSpaceReflectionData } from './components/screen-space-reflection.js';
+import type { EnvironmentInspection } from './environment/inspection.js';
+import type { GpuDrivenPreparationError } from './errors/gpu-driven.js';
+import type { RecoveryOutcome, RecoveryPhase } from './errors/recover.js';
+import type { RenderError } from './errors/render.js';
+import type { RenderFeature, RenderFeatureDiagnostics } from './features/types.js';
+import type { PostProcessShaderEntry } from './fullscreen-post-process-pass.js';
 import type {
   BloomInspection,
   DirectionalShadowInspection,
@@ -46,10 +47,11 @@ import type {
   SsrSpatialInspection,
   TemporalTargetInspection,
   TransmissionInspection,
-} from './inspection-types';
-import type { InstanceCollectionInspection, InstanceCollectionStore } from './instances';
-import type { RenderSceneBounds } from './scene/render-scene-types';
-import type { SsrAdmissionIdentity } from './ssr/identity';
+} from './inspection-types.js';
+import type { InstanceCollectionInspection, InstanceCollectionStore } from './instances.js';
+import type { RenderExtent } from './pipeline/render-extent.js';
+import type { RenderSceneBounds } from './scene/render-scene-types.js';
+import type { SsrAdmissionIdentity } from './ssr/identity.js';
 import type {
   RenderTarget,
   RenderTargetDescriptor,
@@ -58,11 +60,11 @@ import type {
   RenderTargetReadbackTicket,
   RenderTargetTextureSource,
   RenderTargetTextureSourceOptions,
-} from './targets/contracts';
-import type { TemporalInspection } from './temporal/inspection';
+} from './targets/contracts.js';
+import type { TemporalInspection } from './temporal/inspection.js';
 
-export type { TransmissionInspection } from './inspection-types';
-export type { PointsLinesInspection } from './points-lines/inspection';
+export type { TransmissionInspection } from './inspection-types.js';
+export type { PointsLinesInspection } from './points-lines/inspection.js';
 
 import type {
   DynamicGeometryCandidate,
@@ -71,29 +73,29 @@ import type {
   DynamicGeometryOrdering,
   DynamicGeometryPrepareInput,
   DynamicGeometryReceipt,
-} from './dynamic-geometry';
+} from './dynamic-geometry.js';
 import type {
   IblBindingInspection,
   MeshMaterialBindingObservation,
-} from './mesh-material-bindings';
-import type { StandardLightingInspection } from './pipeline/standard-lighting/inspection';
-import type { AutoExposureInspection } from './pipeline/standard-output/auto-exposure/inspection';
-import type { StandardLutInspection } from './pipeline/standard-output/lut-state';
-import type { StandardProfile } from './pipeline/standard-profile';
-import type { PointShadowInspection } from './point-shadow-inspection';
-import type { PostProcessError } from './post-process-errors';
+} from './mesh-material-bindings.js';
+import type { StandardLightingInspection } from './pipeline/standard-lighting/inspection.js';
+import type { AutoExposureInspection } from './pipeline/standard-output/auto-exposure/inspection.js';
+import type { StandardLutInspection } from './pipeline/standard-output/lut-state.js';
+import type { StandardProfile } from './pipeline/standard-profile.js';
+import type { PointShadowInspection } from './point-shadow-inspection.js';
+import type { PostProcessError } from './post-process-errors.js';
 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';
+import type { VolumeTimingObservation } from './record/gpu-timing.js';
+import type { TemporalView } from './temporal/view.js';
+import type { VolumetricFogInspection } from './volume/inspection.js';
 
 export type {
   CubeCameraFace,
   CubeCameraUpdateIntent,
-} from './components/cube-camera';
+} from './components/cube-camera.js';
 
 export interface CubeCameraSnapshot {
   readonly entityKey?: number;
@@ -158,6 +160,8 @@ export interface CameraSnapshot {
   /** Camera schema output projection consumed by Standard prepare/inspection. */
   readonly output?: CameraOutputSnapshot;
   readonly antialias: Antialias;
+  /** Optional detached Camera companion for fixed or adaptive scaling. */
+  readonly dynamicResolution?: DynamicResolutionData;
   readonly bloom: BloomEnabled;
   readonly bloomThreshold: number;
   readonly bloomIntensity: number;
@@ -186,8 +190,8 @@ export type {
   EnvironmentSource,
   FogFrame,
   FramePlan,
-} from './extract/environment';
-export type { TemporalView } from './temporal/view';
+} from './extract/environment.js';
+export type { TemporalView } from './temporal/view.js';
 
 /**
  * Render-graph state exposed to pipeline declarations. Concrete pipeline
@@ -303,6 +307,8 @@ export interface RenderPipelineContext {
   readonly clear: readonly [number, number, number, number] | number[];
   readonly targetW: number;
   readonly targetH: number;
+  /** Renderer-owned output/internal dimensions shared by Standard consumers. */
+  readonly extent?: RenderExtent;
   readonly currentTexture: Texture;
   readonly camera: CameraSnapshot;
   /** Per-frame post-process parameter bytes keyed by shader id. */
@@ -341,6 +347,7 @@ export interface SsrShaderSources {
 
 /** Stable analytic-atmosphere entry-point sources emitted by the shader manifest. */
 export interface AtmosphereShaderSources {
+  readonly ibl: string;
   readonly cube: string;
   readonly background: string;
 }
@@ -400,6 +407,15 @@ export interface Renderer {
     candidate: DynamicGeometryCandidate,
     ordering: DynamicGeometryOrdering,
   ): Result<DynamicGeometryCandidate, DynamicGeometryError>;
+  /**
+   * Atomically swap distinct entities in one attached World. Returned failures
+   * retain old bindings; an uncertain rollback throws to require paired rebuild.
+   * Invoke inside PhysicsWorld.admitDerivedShapeCandidates commitGeometry.
+   */
+  acceptDynamicGeometryCandidates(
+    candidates: readonly DynamicGeometryCandidate[],
+    ordering: DynamicGeometryOrdering,
+  ): Result<readonly DynamicGeometryCandidate[], DynamicGeometryError>;
   dynamicGeometryReceipt(candidate: DynamicGeometryCandidate): DynamicGeometryReceipt | undefined;
   cancelDynamicGeometry(candidate: DynamicGeometryCandidate): Result<void, DynamicGeometryError>;
   retireDynamicGeometry(candidate: DynamicGeometryCandidate): Result<void, DynamicGeometryError>;
@@ -471,7 +487,7 @@ export type RendererEvent =
       readonly kind: 'frame-submitted';
       readonly frameId: number;
       readonly deviceGeneration: number;
-      /** The exact receipt returned by the renderer's submit boundary. */
+      /** The exact draw receipt, for observation when App owns the draw loop. */
       readonly receipt: FrameReceipt;
     };
 
@@ -980,6 +996,8 @@ export interface RendererOptions {
   readonly profiler?: Profiler | undefined;
   /** Explicitly request timestamp-query for receipt-bound GPU profiling. */
   readonly captureGpuTimings?: boolean | undefined;
+  /** Opt into full-frame reflection fallback pixel readback and hashing for diagnostics. */
+  readonly captureReflectionFallbackReadback?: 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. */

package/src/render-graph-primitives.ts

@@ -15,6 +15,7 @@ import type {
   TextureFormat,
   TextureView,
 } from '@forgeax/engine-rhi';
+import { RhiError } from '@forgeax/engine-rhi';
 import {
   buildFullscreenPostProcessPass,
   createFullscreenBindGroup,
@@ -28,7 +29,7 @@ import type { _InternalRenderPipelineContext } from './record/render-context';
 import { recordFxaaPass } from './record/skybox-post-pass';
 import type { RenderPipelineContext } from './render-contract';
 import { getOrCreateSsaoBuffers, getOrCreateSsaoFallbackTexture } from './ssao-buffers';
-import { getSsaoParameters } from './ssao-config';
+import { getSsaoParameters, SSAO_SAMPLE_COUNTS } from './ssao-config';
 
 type DepthResolutionContext = Pick<_InternalRenderPipelineContext, 'runtime'> & {
   readonly frameState: {
@@ -198,6 +199,12 @@ function ensureSsaoRecordCompanions(internals: _InternalRenderPipelineContext):
 function buildSsaoUniformPayload(internals: _InternalRenderPipelineContext): Float32Array {
   const { camera, frameState } = internals;
   const sProj = computeProjectionMatrix(camera);
+  if (camera.temporal?.currentJitterUv !== undefined) {
+    const jitter = mat4.identity(mat4.create());
+    jitter[12] = camera.temporal.currentJitterUv[0] * 2;
+    jitter[13] = camera.temporal.currentJitterUv[1] * -2;
+    mat4.multiply(sProj, jitter, sProj);
+  }
   const sView = computeViewMatrix(camera);
   const invProj = mat4.create();
   mat4.invert(invProj, sProj);
@@ -214,6 +221,7 @@ function buildSsaoUniformPayload(internals: _InternalRenderPipelineContext): Flo
   out[48] = parameters.intensity;
   out[49] = parameters.radius;
   out[50] = parameters.bias;
+  out[51] = SSAO_SAMPLE_COUNTS[parameters.quality];
   return out;
 }
 
@@ -256,7 +264,19 @@ export function recordSsaoCalcPass(
   const { runtime, pipelineState, encoder } = _c;
   const pp = pipelineState.perPassResources;
 
-  if (pp.ssaoCalcPipeline === null || pp.ssaoBgl === null) return;
+  if (runtime.device.caps.backendKind === 'wgpu-webgl2') {
+    throw new RhiError({
+      code: 'feature-not-enabled',
+      expected: 'SSAO raw depth sampling on a WebGPU-capable backend',
+      hint: 'use WebGPU for SSAO or disable StandardProfile.ssao on the GLES fallback',
+    });
+  }
+  if (pp.ssaoCalcPipeline === null || pp.ssaoBgl === null) {
+    throw new PostProcessError({
+      code: 'post-process-not-found',
+      detail: { id: 'forgeax::post::ssao-calc' },
+    });
+  }
   if (graphViews === undefined && (resolveCtx === undefined || ssaoRawKey === undefined)) return;
 
   const ssaoRawView =
@@ -392,7 +412,12 @@ export function recordSsaoBlurPass(
   const { runtime, pipelineState, encoder } = _c;
   const pp = pipelineState.perPassResources;
 
-  if (pp.ssaoBlurPipeline === null || pp.ssaoBgl === null) return;
+  if (pp.ssaoBlurPipeline === null || pp.ssaoBgl === null) {
+    throw new PostProcessError({
+      code: 'post-process-not-found',
+      detail: { id: 'forgeax::post::ssao-blur' },
+    });
+  }
   if (
     graphViews === undefined &&
     (resolveCtx === undefined || ssaoBlurredKey === undefined || ssaoRawKey === undefined)

package/src/render-pipeline.ts

@@ -45,6 +45,7 @@ import {
   GPU_TEXTURE_USAGE_COPY_SRC,
   GPU_TEXTURE_USAGE_RENDER_ATTACHMENT,
 } from './gpu-texture-usage';
+import type { RenderExtent } from './pipeline/render-extent';
 import type { StandardTopologyInputValue } from './pipeline/standard-lighting/topology';
 import { STANDARD_POST_STAGE_NAMES, type StandardProfile } from './pipeline/standard-profile';
 import type { SurfaceProfile } from './record/render-context';
@@ -231,6 +232,8 @@ export interface RenderPipelineTopology {
     readonly viewFormat: import('@forgeax/engine-rhi').TextureFormat;
     readonly profile?: SurfaceProfile | undefined;
   };
+  /** Renderer-owned immutable dimensions for Standard graph consumers. */
+  readonly extent?: RenderExtent;
   readonly camera: Pick<RenderPipelineContext['camera'], 'tonemap' | 'antialias' | 'bloom'>;
   /** Frame-stable Standard output policy; no raw RHI handles enter topology. */
   readonly output?: {
@@ -448,6 +451,13 @@ export interface RenderPipelineGpuDrivenProjection {
   ): void;
 }
 
+/** Exact scene rows selected by an indirect batch; palette offsets are global. */
+export interface GpuDrivenSceneMeshBinding {
+  readonly meshBuffer: Buffer;
+  readonly meshBytes: number;
+  readonly paletteBuffer?: Buffer;
+}
+
 /** Producer-owned Standard PBR resources resolved during graph execution. */
 export interface GpuDrivenStandardPbrFrameResources {
   readonly materialBindGroups: (BindGroup | undefined)[];
@@ -455,12 +465,18 @@ export interface GpuDrivenStandardPbrFrameResources {
   readonly materialSlotIndicesByEntity: Map<number, readonly number[]>;
   readonly instancesBindGroup: BindGroup;
   readonly materialStride: number;
+  /** The current pass selects material membership and attachment formats. */
+  selectedMaterialSlots?: ReadonlySet<number>;
+  colorFormats?: readonly TextureFormat[];
   /** Exact producer-owned numeric Material table consumed by scene-index PBR. */
   readonly sceneMaterialBuffer: Buffer;
+  resolveClusteredMeshBindGroup?: (binding: GpuDrivenSceneMeshBinding) => BindGroup;
 }
 
 export interface RenderPipelineBuildContext<FrameCtx extends RenderPipelineFrame> {
   readonly graph: RenderGraphBuilder<FrameCtx>;
+  /** Optional Standard-only output-domain coverage producer input. */
+  readonly targetCoverage?: import('./temporal/target-coverage-attachment').TargetCoverageAttachment;
   /** Explicit receipt-bound color domains requested for this frame. */
   readonly observationCaptureDomains?: readonly FrameObservationDomain[] | undefined;
   /**
@@ -526,6 +542,7 @@ export interface RenderPipelineBuildContext<FrameCtx extends RenderPipelineFrame
   projectGpuDriven(target: {
     readonly format: TextureFormat;
     readonly sampleCount: 1 | 4;
+    readonly additionalColorFormats?: readonly TextureFormat[];
   }): Result<RenderPipelineGpuDrivenProjection | undefined, RenderPipelineBuildError>;
   projectGpuDrivenShadow?(
     identity: ShadowViewIdentity,
@@ -542,7 +559,9 @@ export interface RenderPipelineBuildContext<FrameCtx extends RenderPipelineFrame
     RenderPipelineBuildError
   >;
   /** Add renderer-owned cube capture work to the active pipeline graph. */
-  contributeCubeCaptures?(): Result<void, RenderPipelineBuildError>;
+  contributeCubeCaptures?(
+    environmentCube?: import('./environment/ibl').GraphEnvironment,
+  ): Result<void, RenderPipelineBuildError>;
   /** Whether a producer-owned feature is installed for this graph build. */
   hasFeature?(identity: string): boolean;
 }

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

@@ -162,6 +162,7 @@ import {
   materialNormalScale,
   materialParamSchemaForMaterial,
   materialProgramKeysForMaterial,
+  materialSceneIndexProgramKeysForMaterial,
   materialStandardTextureMask,
   materialTextureFields,
   materialTextureRef,
@@ -209,7 +210,12 @@ export function extractFrames(
     readonly retainHidden?: boolean;
     readonly getMaterialShaderArtifact?: (
       materialShaderId: string,
-      vertexColorAvailable?: boolean,
+      request?: {
+        readonly vertexColorAvailable?: boolean;
+        readonly deformation?: 'rigid' | 'skin';
+        readonly pass?: 'forward' | 'shadow' | 'depth';
+        readonly address?: 'direct' | 'scene-index';
+      },
     ) => MaterialShaderArtifact | undefined;
     readonly instanceCollections?: InstanceCollectionStore;
   } = {},
@@ -683,8 +689,8 @@ function hasFiniteOrderedLocalAabb(aabb: Float32Array | undefined): aabb is Floa
   return minX <= maxX && minY <= maxY && minZ <= maxZ;
 }
 
-function morphSnapshotFor(
-  mesh: MeshAsset,
+export function morphSnapshotFor(
+  mesh: Pick<MeshAsset, 'vertices' | 'morphTargets'>,
   weights: ArrayLike<number> | undefined,
 ): MorphSnapshot | undefined {
   const targets = mesh.morphTargets;
@@ -710,6 +716,9 @@ function morphSnapshotFor(
     if (!Number.isFinite(weight)) return undefined;
     copied[index] = weight;
   }
+  // Zero weights are the source vertex stream exactly. An authored but idle
+  // morph target must not disable skin scene-index admission or dispatch work.
+  if (copied.every((weight) => weight === 0)) return undefined;
   return { weights: copied, targetCount: targets.length };
 }
 
@@ -2139,6 +2148,11 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
               assets,
               materialContext,
             );
+            const materialSceneIndexProgramKeys = materialSceneIndexProgramKeysForMaterial(
+              asset,
+              assets,
+              materialContext,
+            );
             const authoredFirstPassShader = runtimeMaterialShaderIdForMaterial(
               allPasses,
               undefined,
@@ -2484,6 +2498,7 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
               normalScale: normalScalePv,
               materialShaderId: firstPassShader,
               materialProgramKeys,
+              materialSceneIndexProgramKeys,
               materialHandle: handleRaw,
               renderState: pipelineRenderState(allPasses[0]?.renderState),
               paramSnapshot: paramSnap,
@@ -3180,8 +3195,13 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
                 ...(entry.materialShaderId === undefined
                   ? {}
                   : { materialShaderId: entry.materialShaderId }),
+                ...(entry.vertexEntry === undefined ? {} : { vertexEntry: entry.vertexEntry }),
+                ...(entry.fragmentEntry === undefined
+                  ? {}
+                  : { fragmentEntry: entry.fragmentEntry }),
                 ...(entry.renderState === undefined ? {} : { renderState: entry.renderState }),
                 ...(cpuReason === undefined ? {} : { cpuReason }),
+                gpuDrivenEligible: cpuReason === undefined,
               };
               shadowMembershipEntries.push(membership);
               localShadowMembershipEntries.push(membership);