@forgeax/engine-render 0.1.32 → 0.1.34

package/src/render-system-extract.ts

@@ -27,7 +27,7 @@ import type { MaterialCookProgramContext } from '@forgeax/engine-pack/material-c
 //                                   fire; no renderable; no dispatch.
 //     - case B (material === 0)   : missing-spec sentinel; defaultMaterial
 //                                   Snapshot fills the slot. No fire.
-//     - case C (handle unresolved): assets.get(handle).err with the entity
+//     - case C (non-zero handle unresolved): assets.get(handle).err with the entity
 //                                   carrying the full T+MF+MR renderable
 //                                   archetype -> structured RhiError(
 //                                   `asset-not-registered`) routed through
@@ -61,8 +61,8 @@ import type { MaterialCookProgramContext } from '@forgeax/engine-pack/material-c
 //                               material; hint literal: `'pass
 //                               undefined or omit field to request
 //                               default material'` (AC-10).
-//   - case C dangling-ref     : `assets.get(handle).err` (strict path,
-//                               isRenderable === true) ->
+//   - case C dangling-ref     : `assets.get(handle).err` for a non-zero
+//                               handle (strict path, isRenderable === true) ->
 //                               `RhiError({ code: 'asset-not-
 //                               registered', detail: { assetHandle },
 //                               hint: 'register material via
@@ -73,21 +73,16 @@ import type { MaterialCookProgramContext } from '@forgeax/engine-pack/material-c
 //                               entity skipped from
 //                               RenderableSnapshot[] +
 //                               MaterialDispatchSnapshot[]; mirrors
-//                               `MeshFilter.assetHandle` dangling path
+//                               `MeshFilter.assetHandle` dangling path. A
+//                               scalar shared<T> slot 0 is the unbound,
+//                               non-renderable state and is skipped
 //                               (charter proposition 5; AC-11).
 //
-// Renderer-owned Large Instances:
-//   `Instances { collectionId }` is an ECS association to the renderer's
-//   `InstanceCollectionStore`, not an ECS transform-array column. The extract
-//   tail resolves the identity against that store and snapshots canonical
-//   transforms together with collection revision, capacity, dirty ranges,
-//   and residency facts. Invalid or stale associations route the existing
-//   typed `InstanceCollectionError` through the World error boundary; the
-//   record stage owns GPU residency and upload decisions.
-//
-// `SpriteInstances` remains the separate ECS-owned array-view path. Its
-// snapshot is intentionally independent from renderer-owned Large Instances,
-// so the extract stage does not duplicate collection storage or GPU policy.
+// World owns Instances.transforms. Extraction borrows the managed array during
+// the read phase and retains a detached projection only when its values change.
+// RenderScene accepts that projection with the source publication; recording
+// owns device residency, upload revisions and backend-specific chunking.
+// SpriteInstances remains the independent 2D component and snapshot contract.
 
 import type { AssetRegistry } from '@forgeax/engine-assets-runtime';
 import {
@@ -96,7 +91,14 @@ import {
   selectMaterialPassProgram,
   walkMaterialPassesOverSharedRefs,
 } from '@forgeax/engine-assets-runtime';
-import type { Component, ComponentSchema, EntityHandle, Query, World } from '@forgeax/engine-ecs';
+import {
+  type Component,
+  type ComponentSchema,
+  type EntityHandle,
+  type Query,
+  Time,
+  type World,
+} from '@forgeax/engine-ecs';
 import { readRenderArrayView, routeWorldError } from '@forgeax/engine-ecs/projection';
 import { type Mat4, mat4, type Vec3, vec3 } from '@forgeax/engine-math';
 import { AssetGuid, type AssetGuid as AssetGuidBytes } from '@forgeax/engine-pack/guid';
@@ -118,6 +120,7 @@ import type {
   MaterialPass,
   MaterialProgramAbi,
   MaterialRenderState,
+  MaterialSurfaceModel,
   MaterialTextureCoordinates,
   MaterialTextureValue,
   MeshLodLevel,
@@ -133,7 +136,7 @@ import {
 import { buildCubeCameraFaceViews } from './capture/cube-views';
 import {
   antialiasFromF32,
-  bloomEnabledFromF32,
+  BarrelDistortion,
   CAMERA_EXPOSURE_MODE_MANUAL,
   Camera,
   CubeCamera,
@@ -148,8 +151,10 @@ import {
   ScreenSpaceReflection,
   tonemapFromF32,
   tonemapToU32,
+  validateCameraBloom,
   validateDynamicResolutionCamera,
 } from './components';
+import { validateBarrelDistortionParameters } from './components/barrel-distortion';
 import { DepthOfField } from './components/depth-of-field';
 import type { DirectionalShadowQuality } from './components/directional-shadow-filter';
 import type { LightValidationError } from './components/light-helpers';
@@ -171,11 +176,12 @@ import {
   depthOfFieldRequestFailure,
   resolveDepthOfFieldParams,
 } from './features/depth-of-field/depth-of-field-params';
+import { resolveMotionBlurParams } from './features/motion-blur/motion-blur-params';
 import type {
   RenderFeatureHiddenEntityReport,
   RenderFeatureWorldVisibilitySnapshot,
 } from './features/types';
-import type { InstanceCollectionId, InstanceCollectionStore } from './instances';
+import type { InstanceCollectionId, InstanceProjectionStore } from './instances';
 import type {
   MeshMaterialBindingDiagnostic,
   MeshMaterialBindingSource,
@@ -648,15 +654,16 @@ export interface SkyboxSnapshot {
 }
 
 /**
- * Resource-owner projection for the single ECS VolumetricFog singleton.
+ * Resource-owner projection for an ECS VolumetricFog collection.
  *
  * The renderer carries the validated authoring facts and the source POD all
  * the way to the record stage.  No profile flag or source/catalog byte is
  * allowed to enable the graph: `status: 'available'` is produced only after
  * the ECS component, its shared TextureAsset, and the volume validator all
- * agree on one linear 3D density owner.
+ * agree on every linear 3D density owner.
  */
 export interface ExtractedVolumetricFog {
+  readonly additional?: readonly ExtractedVolumetricFog[];
   readonly status: 'off' | 'available' | 'degraded';
   readonly fog?: ValidatedVolumetricFog;
   readonly densityHandle?: Handle<'TextureAsset', 'shared'>;
@@ -665,6 +672,8 @@ export interface ExtractedVolumetricFog {
   readonly generation?: number;
   readonly digest?: string;
   readonly worldId?: number;
+  /** Canonical simulation time projected from this World for authored medium motion. */
+  readonly worldTimeSeconds?: number;
   /** Required same-World light selected by the authoring component. */
   readonly lightEntity?: EntityHandle;
   readonly lightKind?: 'directional' | 'point' | 'spot';
@@ -816,6 +825,9 @@ export type RenderableReactiveReason =
 export interface RenderableTemporalSnapshot {
   readonly previousEpoch: number | undefined;
   readonly previousSource: RenderablePreviousSource;
+  /** True only when current and previous geometry belong to one stable source identity. */
+  readonly motionValid: boolean;
+  /** Color-history invalidation is independent from motion validity. */
   readonly reactive: boolean;
   readonly reactiveReasons: readonly RenderableReactiveReason[];
   readonly previousTransform: TransformSnapshot;
@@ -836,12 +848,12 @@ export interface InstancesSnapshot {
   readonly collectionId?: InstanceCollectionId;
   /** Packed column-major mat4 transforms (16 f32 per instance). */
   readonly transforms: Float32Array;
+  /** Monotonic per-ordinal identity generations, when the collection owns them. */
+  readonly generations?: Uint32Array;
   /** Number of instances (transforms.length / 16). */
   readonly instanceCount: number;
   /** Collection revision captured by this detached frame snapshot. */
   readonly revision?: number;
-  /** Logical collection capacity at snapshot time. */
-  readonly capacity?: number;
   /** Coalesced matrix ordinals dirtied since the previous authoring update. */
   readonly dirtyRanges?: readonly {
     readonly start: number;
@@ -927,6 +939,10 @@ export interface MaterialSnapshot {
   readonly baseColor: Vec3;
   readonly metallic: number;
   readonly roughness: number;
+  /** Root-owned Surface model used only for typed pass routing. */
+  readonly surfaceModel?: MaterialSurfaceModel | undefined;
+  /** Whether this material publishes a Deferred pass consumed before the forward-only lane. */
+  readonly deferredPass?: boolean | undefined;
   /** Authored Standard PBR specular color in linear runtime color space. */
   readonly specularColor?: readonly [number, number, number] | undefined;
   /**
@@ -1226,6 +1242,8 @@ export interface ExtractedFrame {
   readonly environmentReady: boolean;
   /** One resource-owner volume projection; absent means no authored fog. */
   readonly volumetricFog?: ExtractedVolumetricFog;
+  /** Resource-owner CloudLayer facts selected once at the extract boundary. */
+  readonly cloudLayer?: import('./cloud/extract').ExtractedCloudLayer;
   readonly renderables: RenderableSnapshot[];
   /**
    * Single dispatch list sorted by queue value (ascending, stable sort).
@@ -2442,6 +2460,13 @@ export function resolveMaterialSnapshot(
     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,
@@ -2964,13 +2989,14 @@ export interface PreparedExtractContext {
         request?: {
           readonly vertexColorAvailable?: boolean;
           readonly deformation?: 'rigid' | 'skin';
+          readonly variantSet?: string;
           readonly pass?: 'forward' | 'shadow' | 'depth';
           readonly address?: 'direct' | 'scene-index';
         },
       ) => MaterialShaderArtifact | undefined)
     | undefined;
-  /** Renderer-owned canonical source for explicit large instance collections. */
-  readonly instanceCollections: InstanceCollectionStore | undefined;
+  /** Renderer-private projection of World-authored instance matrices. */
+  readonly instanceCollections: InstanceProjectionStore | undefined;
 }
 
 const ALL_VISIBLE: VisibilitySnapshot = {
@@ -2987,13 +3013,23 @@ function collectCameraSnapshots(world: World): CameraSnapshot[] {
   const cameraQuery = world
     .query({
       read: [Camera],
-      optional: [MotionBlur, DynamicResolution, ScreenSpaceReflection, DepthOfField],
+      optional: [
+        MotionBlur,
+        DynamicResolution,
+        ScreenSpaceReflection,
+        DepthOfField,
+        BarrelDistortion,
+      ],
       with: [Transform, GlobalTransform],
     })
     .unwrap();
   for (const row of cameraQuery) {
     const cam = row.get(Camera);
     const motionBlur = row.get(MotionBlur);
+    const barrelDistortion = row.get(BarrelDistortion);
+    const motionBlurResult = resolveMotionBlurParams(motionBlur);
+    if (!motionBlurResult.ok) throw motionBlurResult.error;
+    const motionBlurParams = motionBlurResult.value;
     const depthOfField = row.get(DepthOfField);
     const dynamicResolution = row.get(DynamicResolution);
     const screenSpaceReflection = row.get(ScreenSpaceReflection);
@@ -3031,6 +3067,8 @@ function collectCameraSnapshots(world: World): CameraSnapshot[] {
     const antialias = antialiasFromF32(cam.antialias);
     const dynamicResolutionResult = validateDynamicResolutionCamera(dynamicResolution, antialias);
     if (!dynamicResolutionResult.ok) throw dynamicResolutionResult.error;
+    const barrelDistortionResult = validateBarrelDistortionParameters(barrelDistortion);
+    if (!barrelDistortionResult.ok) throw barrelDistortionResult.error;
     cameras.push({
       entityKey: entity as number,
       ...(target === undefined ? {} : { target }),
@@ -3054,10 +3092,17 @@ function collectCameraSnapshots(world: World): CameraSnapshot[] {
       ...(dynamicResolutionResult.value === undefined
         ? {}
         : { dynamicResolution: dynamicResolutionResult.value }),
-      bloom: bloomEnabledFromF32(cam.bloom),
+      bloom: validateCameraBloom(
+        cam.bloom,
+        cam.bloomThreshold,
+        cam.bloomIntensity,
+        cam.bloomSoftKnee,
+        cam.bloomScatter,
+      ),
       bloomThreshold: cam.bloomThreshold,
       bloomIntensity: cam.bloomIntensity,
-      bloomBlurRadius: cam.bloomBlurRadius,
+      bloomSoftKnee: cam.bloomSoftKnee,
+      bloomScatter: cam.bloomScatter,
       clearColor: [
         cam.clearColor[0] ?? 0,
         cam.clearColor[1] ?? 0,
@@ -3068,15 +3113,17 @@ function collectCameraSnapshots(world: World): CameraSnapshot[] {
         ? { depthOfField: depthOfFieldResult.value }
         : {}),
       ...(depthOfFieldError === undefined ? {} : { depthOfFieldError }),
-      ...(motionBlur === undefined
+      ...(motionBlurParams === undefined
         ? {}
         : {
             motionBlur: {
-              shutterAngle: motionBlur.shutterAngle,
-              maxRadiusPixels: motionBlur.maxRadiusPixels,
-              sampleCount: motionBlur.sampleCount,
+              shutterAngle: motionBlurParams.shutterAngle,
+              maxRadiusPixels: motionBlurParams.maxRadiusPixels,
+              sampleCount: motionBlurParams.sampleCount,
+              targetFps: motionBlurParams.targetFps,
             },
           }),
+      ...(barrelDistortion === undefined ? {} : { barrelDistortion: barrelDistortionResult.value }),
       ...(screenSpaceReflection === undefined
         ? {}
         : {
@@ -3229,11 +3276,12 @@ export function prepareExtractContext(
       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;
   } = {},
 ): PreparedExtractContext {
   const renderables = options.renderables ?? 'full';
@@ -3332,8 +3380,11 @@ export function extractVolumeSnapshot(
   assets: AssetRegistry | null | undefined,
   worldInternal: WorldInternalView,
 ): ExtractedVolumetricFog | undefined {
+  const elapsed = world.getResource(Time).elapsed;
+  const worldTimeSeconds = Number.isFinite(elapsed) ? Math.max(0, elapsed) : 0;
   const query = world.query({ read: [VolumetricFog] }).unwrap();
   const authorings: VolumetricFogAuthoring[] = [];
+  const members: ExtractedVolumetricFog[] = [];
   let selectedLight:
     | {
         readonly entity: EntityHandle;
@@ -3342,15 +3393,9 @@ export function extractVolumeSnapshot(
         readonly spotLightEntity?: EntityHandle;
       }
     | undefined;
-  let first:
-    | {
-        readonly densityHandle: Handle<'TextureAsset', 'shared'>;
-        readonly densityAsset: TextureAsset;
-        readonly guid: string;
-      }
-    | undefined;
 
   for (const row of query) {
+    selectedLight = undefined;
     const source = row.get(VolumetricFog);
     if (source.light === null) continue;
     const selected = resolveSelectedVolumetricLight(world, source.light);
@@ -3377,7 +3422,7 @@ export function extractVolumeSnapshot(
           : resolved.error,
         { severity: Severity.Error, systemName: 'RenderSystem.extract (volumetric-density)' },
       );
-      return { status: 'degraded' };
+      return { status: 'degraded', worldTimeSeconds };
     }
     const densityAsset = resolved.value;
     const guid = assets?.guidOf(densityAsset) ?? `handle:${Number(densityHandle)}`;
@@ -3427,9 +3472,30 @@ export function extractVolumeSnapshot(
       emission: [source.emission[0] ?? 0, source.emission[1] ?? 0, source.emission[2] ?? 0],
       anisotropy: source.anisotropy,
       maxDistance: source.maxDistance,
+      sampling: source.sampling === 1 ? 'density' : 'noise',
     };
     authorings.push(authoring);
-    first ??= { densityHandle, densityAsset, guid };
+    members.push({
+      status: 'available',
+      worldTimeSeconds,
+      densityHandle,
+      densityAsset,
+      guid,
+      generation: 1,
+      digest: textureDigest(densityAsset),
+      ...(selectedLight === undefined
+        ? {}
+        : {
+            lightEntity: selectedLight.entity,
+            lightKind: selectedLight.kind,
+            ...(selectedLight.pointLightEntity === undefined
+              ? {}
+              : { pointLightEntity: selectedLight.pointLightEntity }),
+            ...(selectedLight.spotLightEntity === undefined
+              ? {}
+              : { spotLightEntity: selectedLight.spotLightEntity }),
+          }),
+    });
   }
 
   if (authorings.length === 0) return undefined;
@@ -3439,54 +3505,18 @@ export function extractVolumeSnapshot(
       severity: Severity.Error,
       systemName: 'RenderSystem.extract (volumetric-fog)',
     });
-    return {
-      status: 'degraded',
-      ...(first === undefined
-        ? {}
-        : {
-            densityHandle: first.densityHandle,
-            densityAsset: first.densityAsset,
-            guid: first.guid,
-            generation: 1,
-            digest: textureDigest(first.densityAsset),
-            ...(selectedLight === undefined
-              ? {}
-              : {
-                  lightEntity: selectedLight.entity,
-                  lightKind: selectedLight.kind,
-                  ...(selectedLight.pointLightEntity === undefined
-                    ? {}
-                    : { pointLightEntity: selectedLight.pointLightEntity }),
-                  ...(selectedLight.spotLightEntity === undefined
-                    ? {}
-                    : { spotLightEntity: selectedLight.spotLightEntity }),
-                }),
-          }),
-    };
+    return { ...members[0], status: 'degraded' };
   }
-  if (extracted.value.status === 'off' || first === undefined) return { status: 'off' };
-  const selectedLightFields =
-    selectedLight === undefined
-      ? {}
-      : {
-          lightEntity: selectedLight.entity,
-          lightKind: selectedLight.kind,
-          ...(selectedLight.pointLightEntity === undefined
-            ? {}
-            : { pointLightEntity: selectedLight.pointLightEntity }),
-          ...(selectedLight.spotLightEntity === undefined
-            ? {}
-            : { spotLightEntity: selectedLight.spotLightEntity }),
-        };
+  if (extracted.value.status === 'off') return { status: 'off' };
+  const validatedMembers = extracted.value.fogs.map((fog, index) => ({
+    ...members[index],
+    status: 'available' as const,
+    fog,
+  }));
   return {
     status: 'available',
-    fog: extracted.value.fog,
-    densityHandle: first.densityHandle,
-    densityAsset: first.densityAsset,
-    guid: first.guid,
-    generation: 1,
-    digest: textureDigest(first.densityAsset),
-    ...selectedLightFields,
+    ...validatedMembers[0],
+    additional: validatedMembers.slice(1),
   };
 }
 

package/src/render-system-presentation.ts

@@ -0,0 +1,56 @@
+import type { World } from '@forgeax/engine-ecs';
+import type { RenderSystemInternals } from './record/render-context';
+import type { FramePresentation } from './render-contract';
+import type { DispatchEntry, RenderableSnapshot } from './render-system-extract';
+import { observeMaterialResidency } from './render-system-residency';
+
+export interface FramePresentationProjection {
+  readonly renderables: readonly RenderableSnapshot[];
+  readonly presentation: FramePresentation;
+}
+
+/**
+ * Derive the startup presentation candidate from the current display workset.
+ * Shadow-only retained rows are deliberately excluded, while material facts
+ * still come from the producer-owned residency projection.
+ */
+export function projectFramePresentation(input: {
+  readonly hasCamera: boolean;
+  readonly environmentReady: boolean;
+  readonly hasEnvironment: boolean;
+  readonly submissionRenderables: readonly RenderableSnapshot[];
+  readonly submissionDispatch: readonly DispatchEntry[];
+  readonly preparedWorlds: readonly World[];
+  readonly internals: RenderSystemInternals;
+}): FramePresentationProjection {
+  const displayRenderableIndices = new Set<number>();
+  for (const entry of input.submissionDispatch) {
+    if (entry.renderableIndex === undefined) continue;
+    if (entry.tags.LightMode !== 'ShadowCaster')
+      displayRenderableIndices.add(entry.renderableIndex);
+  }
+  const renderables = input.submissionRenderables.filter(
+    (_, index) =>
+      displayRenderableIndices.has(index) &&
+      input.submissionRenderables[index]?.authorVisible !== false,
+  );
+
+  let presentation: FramePresentation = 'ready';
+  if (input.hasCamera && (!input.environmentReady || !input.hasEnvironment)) {
+    presentation = 'pending';
+  } else if (input.hasCamera) {
+    for (const renderable of renderables) {
+      const materialWorld = input.preparedWorlds[renderable.worldId];
+      for (const material of renderable.materials) {
+        if (
+          observeMaterialResidency(materialWorld, material, input.internals).readiness === 'pending'
+        ) {
+          presentation = 'pending';
+          break;
+        }
+      }
+      if (presentation === 'pending') break;
+    }
+  }
+  return { renderables, presentation };
+}

package/src/render-system-producer-roots.ts

@@ -0,0 +1,96 @@
+export type RendererProducerRootKind =
+  | 'backend-surface'
+  | 'shader-material-pipeline'
+  | 'mesh-texture-sampler'
+  | 'render-scene'
+  | 'gpu-driven'
+  | 'feature'
+  | 'external-source'
+  | 'render-graph'
+  | 'target-history'
+  | 'observation-lease';
+
+export interface RendererProducerRoot {
+  readonly kind: RendererProducerRootKind;
+  readonly owner: string;
+  readonly candidateScope: 'device-scope';
+  readonly visibility: 'visible-workset' | 'non-visible-lazy';
+  readonly disabledWork: 'zero' | 'lazy';
+}
+
+const PRODUCER_ROOT_MATRIX: readonly RendererProducerRoot[] = Object.freeze([
+  {
+    kind: 'backend-surface',
+    owner: 'backend-surface-owner',
+    candidateScope: 'device-scope',
+    visibility: 'visible-workset',
+    disabledWork: 'zero',
+  },
+  {
+    kind: 'shader-material-pipeline',
+    owner: 'shader-material-pipeline-owner',
+    candidateScope: 'device-scope',
+    visibility: 'visible-workset',
+    disabledWork: 'zero',
+  },
+  {
+    kind: 'mesh-texture-sampler',
+    owner: 'gpu-residency',
+    candidateScope: 'device-scope',
+    visibility: 'visible-workset',
+    disabledWork: 'lazy',
+  },
+  {
+    kind: 'render-scene',
+    owner: 'persistent-render-scene',
+    candidateScope: 'device-scope',
+    visibility: 'visible-workset',
+    disabledWork: 'zero',
+  },
+  {
+    kind: 'gpu-driven',
+    owner: 'gpu-driven-production',
+    candidateScope: 'device-scope',
+    visibility: 'visible-workset',
+    disabledWork: 'zero',
+  },
+  {
+    kind: 'feature',
+    owner: 'render-feature-host',
+    candidateScope: 'device-scope',
+    visibility: 'visible-workset',
+    disabledWork: 'lazy',
+  },
+  {
+    kind: 'external-source',
+    owner: 'external-source-owner',
+    candidateScope: 'device-scope',
+    visibility: 'non-visible-lazy',
+    disabledWork: 'zero',
+  },
+  {
+    kind: 'render-graph',
+    owner: 'typed-frame-graph',
+    candidateScope: 'device-scope',
+    visibility: 'visible-workset',
+    disabledWork: 'zero',
+  },
+  {
+    kind: 'target-history',
+    owner: 'temporal-target-owner',
+    candidateScope: 'device-scope',
+    visibility: 'visible-workset',
+    disabledWork: 'zero',
+  },
+  {
+    kind: 'observation-lease',
+    owner: 'render-observation-owner',
+    candidateScope: 'device-scope',
+    visibility: 'non-visible-lazy',
+    disabledWork: 'zero',
+  },
+]);
+
+export function createRendererProducerRootMatrix(): readonly RendererProducerRoot[] {
+  return PRODUCER_ROOT_MATRIX;
+}