@forgeax/engine-render 0.1.7 → 0.1.19

package/src/render-system-extract.ts

@@ -102,7 +102,7 @@ import {
   resolveAssetHandle,
   walkMaterialPassesOverSharedRefs,
 } from '@forgeax/engine-assets-runtime';
-import type { Component, ComponentSchema, EntityHandle, World } from '@forgeax/engine-ecs';
+import type { Component, ComponentSchema, EntityHandle, Query, World } from '@forgeax/engine-ecs';
 import {
   InstanceTransformsStrideMismatchError,
   readRenderArrayView,
@@ -152,11 +152,9 @@ import {
   toShared,
 } from '@forgeax/engine-types';
 import {
-  antialiasFromF32,
-  bloomEnabledFromF32,
-  Camera,
-  cameraProjectionFromF32,
+  Atmosphere,
   DirectionalLight,
+  Fog,
   Instances,
   Layer,
   Lines,
@@ -173,16 +171,23 @@ import {
   SpotLight,
   SpriteInstances,
   SpriteRegionOverride,
-  tonemapFromF32,
   tonemapToU32,
 } from './components';
 import { GlyphText } from './components/glyph-text';
 import { computeInvRangeSquared, degToCos } from './components/light-helpers';
+import { selectEnvironment } from './environment/frame';
 import {
   MaterialSkinAttrMissingError,
   ShadowInvalidConfigError,
   SkinMaterialMismatchError,
 } from './errors/render';
+import { extractCameraSnapshots } from './extract/camera';
+import type {
+  EnvironmentCandidate,
+  EnvironmentFrame,
+  FogCandidate,
+  FogFrame,
+} from './extract/environment';
 import { resolveVisibility, type VisibilitySnapshot } from './extract/visibility';
 import type {
   RenderFeatureHiddenEntityReport,
@@ -197,9 +202,11 @@ import {
 import { isStandardPbrMaterialShader } from './pbr-pipeline';
 import { expandPointsLinesBounds } from './points-lines/bounds';
 import type { PointsLinesRetainedSnapshot, PointsLinesStyle } from './points-lines/snapshot';
-import { type CameraSnapshot, STANDARD_TONEMAP_FEATURE_ID } from './render-contract';
-import { getActiveCamera, selectActiveCameraIndex } from './systems/active-camera';
+import { type CameraSnapshot, STANDARD_OUTPUT_TRANSFORM_FEATURE_ID } from './render-contract';
 import { selectPasses } from './systems/pass-selector';
+
+export { extractCameraSnapshots } from './extract/camera';
+
 import type { SkinPaletteAllocator } from './systems/skin-palette-allocator';
 import type { SkinPaletteSlice } from './systems/skin-palette-types';
 
@@ -604,10 +611,32 @@ export interface RenderableSnapshot {
    * deltas and the record stage only receives this frozen POD snapshot.
    */
   readonly morph?: MorphSnapshot;
+  /** Renderer-owned previous-frame facts attached during temporal projection. */
+  readonly temporal?: RenderableTemporalSnapshot;
   /** Detached M2 authoring facts for the optional Points/Lines projection. */
   readonly pointsLines?: PointsLinesRetainedSnapshot;
 }
 
+export type RenderablePreviousSource = 'last-submitted' | 'current-seed';
+export type RenderableReactiveReason =
+  | 'new-slot'
+  | 'generation-reuse'
+  | 'reentered'
+  | 'geometry-revision'
+  | 'material-revision'
+  | 'skinning-deformation'
+  | 'morph-deformation';
+export interface RenderableTemporalSnapshot {
+  readonly previousEpoch: number | undefined;
+  readonly previousSource: RenderablePreviousSource;
+  readonly reactive: boolean;
+  readonly reactiveReasons: readonly RenderableReactiveReason[];
+  readonly previousTransform: TransformSnapshot;
+  readonly previousInstances: InstancesSnapshot | undefined;
+  readonly previousSkin: SkinPaletteSlice | undefined;
+  readonly previousMorphWeights: Float32Array | undefined;
+}
+
 export interface MorphSnapshot {
   readonly weights: Float32Array;
   readonly targetCount: number;
@@ -758,9 +787,9 @@ export interface MaterialSnapshot {
    *
    * Populated by iterating `textureFieldNames`; absent keys mean the
    * paramValue was missing / mis-typed (record falls back to default white).
-   * `emissiveTexture` / `occlusionTexture` are NOT here — they live in the
-   * engine-injection lightmap region (their named fields below feed
-   * `appendInjection('lightmap')`, not the user-region).
+   * `emissiveTexture` / `occlusionTexture` are included here as ordinary
+   * Standard user-region fields; the production layout does not duplicate
+   * them in a lightmap injection region.
    */
   readonly textureHandles?: ReadonlyMap<string, Handle<'TextureAsset', 'shared'>> | undefined;
   /**
@@ -973,6 +1002,10 @@ function appendMaterialDispatchEntries(
 export interface ExtractedFrame {
   readonly cameras: CameraSnapshot[];
   readonly lights: ExtractedLights;
+  /** Resource-owner environment facts selected once at the extract boundary. */
+  readonly environment: EnvironmentFrame | undefined;
+  /** False when the resource-owner world failed environment/fog selection. */
+  readonly environmentReady: boolean;
   readonly renderables: RenderableSnapshot[];
   /**
    * Single dispatch list sorted by queue value (ascending, stable sort).
@@ -984,6 +1017,8 @@ export interface ExtractedFrame {
   readonly skylightCount: number;
   readonly skybox: SkyboxSnapshot | undefined;
   readonly skyboxCount: number;
+  /** Resource-owner Fog facts selected once at the frame boundary. */
+  readonly fog: FogFrame | undefined;
   /**
    * feat-20260528-frustum-culling M3 / w11: frustum culling statistics
    * collected during the extract phase. `total` is the count of entities
@@ -1062,6 +1097,10 @@ const BUILTIN_USER_REGION_TEXTURE_FIELDS: readonly string[] = [
   'metallicRoughnessTexture',
   'normalTexture',
   'specularTintTexture',
+  'emissiveTexture',
+  'occlusionTexture',
+  'transmissionTexture',
+  'thicknessTexture',
 ];
 const BUILTIN_USER_REGION_TEXTURE_FIELD_SET = new Set(BUILTIN_USER_REGION_TEXTURE_FIELDS);
 const BUILTIN_BASE_COLOR_TEXTURE_FIELD_SET = new Set(['baseColorTexture']);
@@ -1350,11 +1389,11 @@ function collectMaterialTextureSamplers(
  * `AssetRegistry.materialShaderTextureFieldNames`). Each declared texture
  * field whose paramValue resolves to a handle lands in the returned map keyed
  * by field name; this is the single path through which an arbitrary number of user-region
- * textures (4 standard or 5+ custom, e.g. parallax `heightTexture`) flow.
+ * textures (8 Standard or 9+ custom, e.g. parallax `heightTexture`) flow.
  *
- * When the shader is not registered the built-in 4-field set is used so
- * standard materials still resolve. `emissiveTexture` / `occlusionTexture`
- * are engine-injection (lightmap) textures and are NOT part of this set.
+ * When the shader is not registered the built-in Standard field set is used
+ * so standard materials still resolve. Emissive and occlusion are ordinary
+ * schema-driven user-region textures in that set.
  *
  * feat-20260623-world-space-video-asset M4 / w14 (D-5): a field whose paramValue
  * catalogues to a VideoAsset is routed into `videoOut` (a VideoAsset-branded
@@ -1665,8 +1704,7 @@ export function resolveMaterialSnapshot(
   // feat-20260621-learn-render-5-5-parallax M2 / w7 (D-3): iterate the
   // shader's derive(paramSchema).textureFieldNames SSOT instead of a hardcoded
   // user-region field list, so an Nth texture (e.g. parallax heightTexture)
-  // resolves through the same path. emissive/occlusion are engine-injection
-  // (lightmap) textures, NOT in textureFieldNames, so they keep named reads.
+  // resolves through the same path, including emissive/occlusion fields.
   const videoTextureFields = new Map<string, Handle<'VideoAsset', 'shared'>>();
   const textureHandles = collectUserRegionTextureHandles(
     pv,
@@ -2192,59 +2230,15 @@ export interface PreparedExtractContext {
   readonly assets: AssetRegistry | null | undefined;
   readonly pipelineState: ExtractPipelineSurface | null | undefined;
   readonly materialSnapshotCache: MaterialSnapshotCache | undefined;
+  /** `undefined` keeps direct extractFrame's local Fog semantics; `null` means
+   * the frame owner already selected that no Fog is present for this world. */
+  readonly resourceOwnerFog: FogFrame | null | undefined;
   readonly cull: 'self' | 'none' | 'external';
   readonly cullCameras: readonly CameraSnapshot[] | undefined;
   readonly hierarchy: SceneHierarchySnapshot;
   readonly visibility: VisibilitySnapshot;
 }
 
-export function extractCameraSnapshots(world: World): CameraSnapshot[] {
-  const worldInternal = createWorldInternalView(world);
-  const cameras: CameraSnapshot[] = [];
-  const cameraEntities: number[] = [];
-  const cameraQuery = world.query({ read: [Camera], with: [Transform] }).unwrap();
-  for (const row of cameraQuery) {
-    const cam = row.get(Camera);
-    const entity = row.entity;
-    const view = worldInternal._getArrayView(entity, Transform, 'world');
-    if (view === undefined) continue;
-    const worldMat = new Float32Array(view);
-    cameras.push({
-      entityKey: entity as number,
-      position: mat4.getTranslation(vec3.create(), worldMat),
-      world: worldMat,
-      fov: cam.fov,
-      aspect: cam.aspect,
-      near: cam.near,
-      far: cam.far,
-      projection: cameraProjectionFromF32(cam.projection),
-      orthoLeft: cam.left,
-      orthoRight: cam.right,
-      orthoBottom: cam.bottom,
-      orthoTop: cam.top,
-      tonemap: tonemapFromF32(cam.tonemap),
-      exposure: cam.exposure,
-      whitePoint: cam.whitePoint,
-      antialias: antialiasFromF32(cam.antialias),
-      bloom: bloomEnabledFromF32(cam.bloom),
-      bloomThreshold: cam.bloomThreshold,
-      bloomIntensity: cam.bloomIntensity,
-      bloomBlurRadius: cam.bloomBlurRadius,
-      clearColor: [
-        cam.clearColor[0] ?? 0,
-        cam.clearColor[1] ?? 0,
-        cam.clearColor[2] ?? 0,
-        cam.clearColor[3] ?? 1,
-      ],
-    });
-    cameraEntities.push(entity as number);
-  }
-  const activeCameraIndex = selectActiveCameraIndex(cameraEntities, getActiveCamera(world)?.entity);
-  if (activeCameraIndex < 0) return cameras;
-  const selected = cameras[activeCameraIndex];
-  return selected === undefined ? cameras : [selected];
-}
-
 function tonemapParams(camera: CameraSnapshot): Uint8Array {
   const bytes = new ArrayBuffer(16);
   const floats = new Float32Array(bytes);
@@ -2261,6 +2255,7 @@ export function prepareExtractContext(
     readonly assets?: AssetRegistry | null;
     readonly pipelineState?: ExtractPipelineSurface | null;
     readonly materialSnapshotCache?: MaterialSnapshotCache;
+    readonly resourceOwnerFog?: FogFrame | null;
     readonly cull?: 'self' | 'none' | 'external';
     readonly cullCameras?: readonly CameraSnapshot[];
   } = {},
@@ -2270,6 +2265,7 @@ export function prepareExtractContext(
     assets: options.assets,
     pipelineState: options.pipelineState,
     materialSnapshotCache: options.materialSnapshotCache,
+    resourceOwnerFog: options.resourceOwnerFog,
     cull: options.cull ?? 'self',
     cullCameras: options.cullCameras,
     hierarchy,
@@ -2277,6 +2273,41 @@ export function prepareExtractContext(
   };
 }
 
+const fogQueries = new WeakMap<World, Query<readonly [typeof Fog]>>();
+
+function selectFogFrame(world: World): FogFrame | undefined {
+  // Query compilation is owned once per World; Query refreshes its matched
+  // tables when the ECS structure changes, while iteration reads current Fog
+  // values. This keeps the frame boundary free of repeated descriptor work.
+  const fogCandidates: FogCandidate[] = [];
+  let fogQuery = fogQueries.get(world);
+  if (fogQuery === undefined) {
+    fogQuery = world.query({ read: [Fog] }).unwrap();
+    fogQueries.set(world, fogQuery);
+  }
+  for (const row of fogQuery) {
+    const value = row.get(Fog);
+    fogCandidates.push({
+      entityKey: row.entity,
+      color: [value.color[0] ?? 0, value.color[1] ?? 0, value.color[2] ?? 0],
+      density: value.density,
+      heightFalloff: value.heightFalloff,
+      maxOpacity: value.maxOpacity,
+    });
+  }
+  const fogSelection = selectEnvironment({
+    environments: [],
+    fogs: fogCandidates,
+    suns: [],
+    lane: 'direct',
+  });
+  if (fogSelection.ok) return fogSelection.value.fog;
+  routeWorldError(world, fogSelection.error, {
+    systemName: 'RenderSystem.extract (fog-selection)',
+  });
+  throw fogSelection.error;
+}
+
 export function extractFrames(
   worlds: readonly World[],
   owner: number | ExtractFramesOwner,
@@ -2304,6 +2335,12 @@ export function extractFrames(
   }
 
   const failedWorlds = new Set<World>();
+  // Resource-owner selection is a frame-level concern. Select Fog once before
+  // per-world extraction so non-owner worlds do not scan their ECS tables for
+  // a value that the merge layer will discard.
+  const resourceOwnerWorld = worlds[resourceOwner];
+  const resourceOwnerFog =
+    resourceOwnerWorld === undefined ? null : (selectFogFrame(resourceOwnerWorld) ?? null);
   // ── D-2: per-world extract with error isolation ────────────────────────
   //
   // Each world runs extractFrame over the final state published by
@@ -2334,6 +2371,7 @@ export function extractFrames(
       const prepared = prepareExtractContext(world, {
         ...(assets !== undefined ? { assets } : {}),
         ...(pipelineState !== undefined ? { pipelineState } : {}),
+        resourceOwnerFog: wi === resourceOwner ? resourceOwnerFog : null,
         ...(materialSnapshotCachesByWorld === undefined
           ? {}
           : {
@@ -2531,6 +2569,8 @@ export function extractFrames(
   const skylightCount = resourceOwnerFrame?.skylightCount ?? 0;
   const skybox = resourceOwnerFrame?.skybox;
   const skyboxCount = resourceOwnerFrame?.skyboxCount ?? 0;
+  const fog = resourceOwnerFrame?.fog;
+  const environment = resourceOwnerFrame?.environment;
   // User-authored PostProcessParams entities are singleton scene resources, so
   // they come from the resourceOwner world (holistic snapshot selection).
   const postProcessParams = new Map(resourceOwnerFrame?.postProcessParams);
@@ -2549,16 +2589,16 @@ export function extractFrames(
   // cameraOwner === resourceOwner this is a no-op (identical entry). The 'na'
   // Standard tonemap identity mirrors the engine provider key set at the
   // bottom of extractFrame (SSOT: same identity, same 16B layout).
-  const TONEMAP_PARAM_KEY = STANDARD_TONEMAP_FEATURE_ID;
-  const cameraTonemapParam = cameraOwnerFrame?.postProcessParams.get(TONEMAP_PARAM_KEY);
+  const OUTPUT_TRANSFORM_PARAM_KEY = STANDARD_OUTPUT_TRANSFORM_FEATURE_ID;
+  const cameraTonemapParam = cameraOwnerFrame?.postProcessParams.get(OUTPUT_TRANSFORM_PARAM_KEY);
   if (cameraTonemapParam !== undefined) {
-    postProcessParams.set(TONEMAP_PARAM_KEY, cameraTonemapParam);
+    postProcessParams.set(OUTPUT_TRANSFORM_PARAM_KEY, cameraTonemapParam);
   } else {
     // The camera-owner world produced no tonemap param (no Camera surfaced
     // there this frame); do not leave a stale resource-owner entry that would
     // apply a foreign camera's exposure. Removing it lets the tonemap pass fall
     // back to its param-less zero path only when genuinely no camera exists.
-    postProcessParams.delete(TONEMAP_PARAM_KEY);
+    postProcessParams.delete(OUTPUT_TRANSFORM_PARAM_KEY);
   }
 
   // D-3: frustumStats — culled/total summed across worlds.
@@ -2579,6 +2619,9 @@ export function extractFrames(
     skylightCount,
     skybox,
     skyboxCount,
+    fog,
+    environment,
+    environmentReady: resourceOwnerFrame !== undefined && environment !== undefined,
     frustumStats,
     visibilityStats,
     postProcessParams,
@@ -2666,7 +2709,12 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
     pipelineState,
     materialSnapshotCache: persistentMaterialSnapshotCache,
     cull: cullMode,
+    resourceOwnerFog,
   } = context;
+  // Environment reads are owned by the retained resource projection and are
+  // established at the frame boundary; record never revisits World state.
+  const fog =
+    resourceOwnerFog === undefined ? selectFogFrame(world) : (resourceOwnerFog ?? undefined);
   const visibility = context.visibility.hasAnyHiddenIntent ? context.visibility : undefined;
   const skinPaletteAllocator = pipelineState?.skinPaletteAllocator ?? null;
 
@@ -3144,6 +3192,79 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
     }
   }
 
+  const environmentCandidates: EnvironmentCandidate[] = [];
+  const imageEnvironment =
+    skylight?.equirectHandle !== undefined && skylight.equirectHandle > 0
+      ? skylight
+      : skybox?.equirectHandle !== undefined && skybox.equirectHandle > 0
+        ? skybox
+        : undefined;
+  if (imageEnvironment !== undefined) {
+    environmentCandidates.push({
+      kind: 'image',
+      entityKey: imageEnvironment.entityHandle,
+      sourceKey: `equirect:${imageEnvironment.equirectHandle}`,
+    });
+  }
+  const atmosphereQuery = world.query({ read: [Atmosphere] }).unwrap();
+  for (const row of atmosphereQuery) {
+    const value = row.get(Atmosphere);
+    const atmosphere = {
+      turbidity: value.turbidity,
+      rayleigh: value.rayleigh,
+      mieCoefficient: value.mieCoefficient,
+      mieDirectionalG: value.mieDirectionalG,
+      sunAngularRadius: value.sunAngularRadius,
+    } as const;
+    environmentCandidates.push({
+      kind: 'atmosphere',
+      entityKey: row.entity,
+      sourceKey: `atmosphere:${row.entity}`,
+      atmosphere,
+    });
+  }
+  const directionalDirection = directional?.direction;
+  const directionalLength =
+    directionalDirection === undefined
+      ? 0
+      : Math.hypot(
+          directionalDirection[0] ?? 0,
+          directionalDirection[1] ?? 0,
+          directionalDirection[2] ?? 0,
+        );
+  const sun =
+    directional === undefined || directionalLength <= 1e-6
+      ? []
+      : [
+          {
+            entityKey: 0,
+            direction: [
+              -(directionalDirection?.[0] ?? 0) / directionalLength,
+              -(directionalDirection?.[1] ?? 0) / directionalLength,
+              -(directionalDirection?.[2] ?? 0) / directionalLength,
+            ] as [number, number, number],
+            color: [
+              directional.color[0] ?? 0,
+              directional.color[1] ?? 0,
+              directional.color[2] ?? 0,
+            ] as [number, number, number],
+            intensity: directional.intensity,
+          },
+        ];
+  const environmentSelection = selectEnvironment({
+    environments: environmentCandidates,
+    fogs: fog === undefined ? [] : [fog],
+    suns: sun,
+    lane: 'direct',
+  });
+  if (!environmentSelection.ok) {
+    routeWorldError(world, environmentSelection.error, {
+      systemName: 'RenderSystem.extract (environment-selection)',
+    });
+    throw environmentSelection.error;
+  }
+  const environment: EnvironmentFrame = environmentSelection.value;
+
   // feat-20260528-frustum-culling M3 / w10: precompute per-camera frustum
   // planes so entities can be tested against all cameras in the inner loop.
   // Cameras with degenerate projection parameters (e.g. zero fov, zero aspect)
@@ -4541,18 +4662,21 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
   // recordFrame's `activeCameras[0]` selection.
   const tonemapCamera = cameras[0];
   if (tonemapCamera !== undefined) {
-    postProcessParams.set(STANDARD_TONEMAP_FEATURE_ID, tonemapParams(tonemapCamera));
+    postProcessParams.set(STANDARD_OUTPUT_TRANSFORM_FEATURE_ID, tonemapParams(tonemapCamera));
   }
 
   return {
     cameras,
     lights,
+    environment,
+    environmentReady: true,
     renderables,
     dispatch,
     skylight,
     skylightCount,
     skybox,
     skyboxCount,
+    fog,
     frustumStats: { culled: frustumCulled, total: frustumTotal },
     visibilityStats: { explicitlyHidden: explicitlyHidden.size },
     postProcessParams,