@forgeax/engine-render 0.1.33 → 0.1.34

package/src/render-system-extract.ts

@@ -78,18 +78,11 @@ import type { MaterialCookProgramContext } from '@forgeax/engine-pack/material-c
 //                               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 {
@@ -127,6 +120,7 @@ import type {
   MaterialPass,
   MaterialProgramAbi,
   MaterialRenderState,
+  MaterialSurfaceModel,
   MaterialTextureCoordinates,
   MaterialTextureValue,
   MeshLodLevel,
@@ -142,6 +136,7 @@ import {
 import { buildCubeCameraFaceViews } from './capture/cube-views';
 import {
   antialiasFromF32,
+  BarrelDistortion,
   CAMERA_EXPOSURE_MODE_MANUAL,
   Camera,
   CubeCamera,
@@ -159,6 +154,7 @@ import {
   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';
@@ -185,7 +181,7 @@ import type {
   RenderFeatureHiddenEntityReport,
   RenderFeatureWorldVisibilitySnapshot,
 } from './features/types';
-import type { InstanceCollectionId, InstanceCollectionStore } from './instances';
+import type { InstanceCollectionId, InstanceProjectionStore } from './instances';
 import type {
   MeshMaterialBindingDiagnostic,
   MeshMaterialBindingSource,
@@ -658,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'>;
@@ -857,8 +854,6 @@ export interface InstancesSnapshot {
   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;
@@ -944,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;
   /**
@@ -1243,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).
@@ -2459,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,
@@ -2981,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 = {
@@ -3004,13 +3013,20 @@ 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;
@@ -3051,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 }),
@@ -3105,6 +3123,7 @@ function collectCameraSnapshots(world: World): CameraSnapshot[] {
               targetFps: motionBlurParams.targetFps,
             },
           }),
+      ...(barrelDistortion === undefined ? {} : { barrelDistortion: barrelDistortionResult.value }),
       ...(screenSpaceReflection === undefined
         ? {}
         : {
@@ -3257,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';
@@ -3364,6 +3384,7 @@ export function extractVolumeSnapshot(
   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;
@@ -3372,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);
@@ -3457,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;
@@ -3469,56 +3505,18 @@ export function extractVolumeSnapshot(
       severity: Severity.Error,
       systemName: 'RenderSystem.extract (volumetric-fog)',
     });
-    return {
-      status: 'degraded',
-      worldTimeSeconds,
-      ...(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',
-    worldTimeSeconds,
-    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;
+}

package/src/render-system-residency.ts

@@ -0,0 +1,159 @@
+import { resolveAssetHandle } from '@forgeax/engine-assets-runtime';
+import type { World } from '@forgeax/engine-ecs';
+import {
+  deriveTextureLayout,
+  type MaterialAsset,
+  type SamplerAsset,
+  type TextureAsset,
+  toShared,
+} from '@forgeax/engine-types';
+import type {
+  MeshMaterialBindingPreparationFailure,
+  MeshMaterialBindingResidency,
+} from './mesh-material-bindings';
+import type { RenderSystemInternals } from './record/render-context';
+import { materialSamplerHandles, materialTextureHandles } from './recovery/render-system-candidate';
+import type { MaterialSnapshot } from './render-system-extract';
+
+function preparationFailureFrom(error: unknown): MeshMaterialBindingPreparationFailure | undefined {
+  if (typeof error !== 'object' || error === null) return undefined;
+  const value = error as {
+    readonly code?: unknown;
+    readonly expected?: unknown;
+    readonly hint?: unknown;
+    readonly detail?: unknown;
+  };
+  if (
+    typeof value.code !== 'string' ||
+    typeof value.expected !== 'string' ||
+    typeof value.hint !== 'string'
+  ) {
+    return undefined;
+  }
+  const detail =
+    typeof value.detail === 'object' && value.detail !== null
+      ? { ...(value.detail as Record<string, unknown>) }
+      : undefined;
+  return {
+    code: value.code,
+    expected: value.expected,
+    hint: value.hint,
+    ...(detail === undefined ? {} : { detail }),
+  };
+}
+
+/**
+ * Project producer-owned material and GPU-store state into the renderer's one
+ * observation surface. This is recomputed from detached frame snapshots; no
+ * readiness map is retained by RenderSystem. A producer failure with an
+ * already resident resource remains last-known-good.
+ */
+export function observeMaterialResidency(
+  world: World | undefined,
+  material: MaterialSnapshot,
+  internals: RenderSystemInternals,
+): MeshMaterialBindingResidency {
+  const textures: Array<{ readonly handle: number; readonly mipLevelCount: number }> = [];
+  const samplers: Array<{ readonly handle: number; readonly resident: boolean }> = [];
+  let pending = false;
+  let resident = false;
+  let failure: MeshMaterialBindingPreparationFailure | undefined;
+  const keepFailure = (error: unknown): void => {
+    if (failure === undefined) failure = preparationFailureFrom(error);
+  };
+
+  if (world === undefined) {
+    pending = true;
+  } else {
+    const materialHandle = material.materialHandle;
+    if (materialHandle !== undefined && materialHandle !== 0) {
+      const materialResult = resolveAssetHandle<MaterialAsset>(
+        world,
+        toShared<'MaterialAsset'>(materialHandle),
+      );
+      if (!materialResult.ok) {
+        keepFailure(materialResult.error);
+      } else {
+        const guid = internals.assets.guidOf(materialResult.value);
+        if (guid !== undefined) {
+          const readiness = internals.assets.getMaterialReadiness(guid);
+          if (readiness?.status === 'Error') keepFailure(readiness.error);
+          const load = internals.assets.loadState.get(guid);
+          if (load?.status === 'provisional') pending = true;
+        }
+      }
+    }
+
+    for (const handle of materialTextureHandles(material)) {
+      const existing = internals.gpuStore.getTextureGpuView(handle, world);
+      const pod = resolveAssetHandle<TextureAsset>(world, handle);
+      if (!pod.ok) {
+        keepFailure(pod.error);
+        continue;
+      }
+      let view = existing;
+      if (view === undefined) {
+        const prepared = internals.gpuStore.ensureResident(handle, pod.value, world);
+        if (!prepared.ok) keepFailure(prepared.error);
+        view = internals.gpuStore.getTextureGpuView(handle, world);
+      }
+      if (view === undefined) {
+        pending = failure === undefined;
+        continue;
+      }
+      const textureLayout = deriveTextureLayout({
+        shape: pod.value.shape,
+        format: pod.value.format,
+        mips: pod.value.mips,
+      });
+      if (!textureLayout.ok) {
+        keepFailure(textureLayout.error);
+        continue;
+      }
+      resident = true;
+      textures.push({
+        handle: Number(handle),
+        mipLevelCount: Math.max(1, textureLayout.value.levels.length),
+      });
+    }
+
+    for (const handle of materialSamplerHandles(material)) {
+      const pod = resolveAssetHandle<SamplerAsset>(world, handle);
+      if (!pod.ok) {
+        keepFailure(pod.error);
+        samplers.push({ handle: Number(handle), resident: false });
+        continue;
+      }
+      const prepared = internals.gpuStore.ensureSamplerResident(handle, pod.value, world);
+      if (!prepared.ok) {
+        keepFailure(prepared.error);
+        samplers.push({ handle: Number(handle), resident: false });
+      } else {
+        resident = true;
+        samplers.push({ handle: Number(handle), resident: true });
+      }
+    }
+    // Video views are supplied by the renderer-owned dynamic store at record
+    // time. A previously uploaded view is a producer-owned last-known-good
+    // fact; absence means the visible workset still needs a decodable frame.
+    for (const clip of material.videoTextureFields?.values() ?? []) {
+      if (internals.dynamicTextureStore?.getView(clip) === undefined) pending = true;
+      else resident = true;
+    }
+  }
+
+  const readiness =
+    failure === undefined
+      ? pending
+        ? 'pending'
+        : 'ready'
+      : resident
+        ? 'last-known-good'
+        : 'failed';
+  return {
+    readiness,
+    samplers,
+    textures,
+    ...(failure === undefined ? {} : { preparationFailure: failure }),
+  };
+}