@forgeax/engine-render 0.1.31 → 0.1.33

package/src/environment/analytic-fog.ts

@@ -0,0 +1,44 @@
+import { mat4 } from '@forgeax/engine-math';
+import type { FogFrame } from '../extract/environment';
+import { computeProjectionMatrix, computeViewMatrix } from '../record/helpers';
+import type { CameraSnapshot } from '../render-contract';
+
+/** Numerical reference for the shader's closed-form height-density integral. */
+export function analyticFogOpacity(
+  fog: Pick<FogFrame, 'density' | 'heightFalloff' | 'maxOpacity'>,
+  originY: number,
+  endY: number,
+  distance: number,
+): number {
+  const rho = fog.density * Math.exp(Math.max(-60, Math.min(60, -fog.heightFalloff * originY)));
+  const t = Math.max(-60, Math.min(60, fog.heightFalloff * (endY - originY)));
+  const integral = Math.abs(t) < 0.001 ? 1 - t / 2 + (t * t) / 6 : -Math.expm1(-t) / t;
+  return fog.maxOpacity * -Math.expm1(-Math.min(80, Math.max(0, rho * distance * integral)));
+}
+
+export function encodeAnalyticFogParams(fog: FogFrame, camera: CameraSnapshot): Uint8Array {
+  const projection = computeProjectionMatrix(camera);
+  // Match the scene depth's jittered projection before temporal resolve.
+  const jitter = camera.temporal?.currentJitterUv;
+  if (jitter !== undefined) {
+    for (let column = 0; column < 4; column++) {
+      projection[column * 4] =
+        (projection[column * 4] ?? 0) + jitter[0] * 2 * (projection[column * 4 + 3] ?? 0);
+      projection[column * 4 + 1] =
+        (projection[column * 4 + 1] ?? 0) - jitter[1] * 2 * (projection[column * 4 + 3] ?? 0);
+    }
+  }
+  const inverse = mat4.invert(
+    mat4.create(),
+    mat4.multiply(mat4.create(), projection, computeViewMatrix(camera)),
+  );
+  const data = new Float32Array(28);
+  data.set(inverse, 0);
+  data.set(camera.position, 16);
+  data.set([...fog.color, fog.density], 20);
+  data.set(
+    [fog.heightFalloff, fog.maxOpacity, camera.near, camera.projection === 'orthographic' ? 1 : 0],
+    24,
+  );
+  return new Uint8Array(data.buffer);
+}

package/src/environment/background.ts

@@ -88,8 +88,8 @@ export function addAtmosphereBackground(
         settings.mieDirectionalG,
         settings.sunAngularRadius,
         settings.sunAngularRadius > 0 ? 1 : 0,
-        0,
-        0,
+        settings.circumsolarStrength,
+        settings.circumsolarWidth,
       ]);
       frame.runtime.device.queue
         .writeBuffer(resources.buffer(params.value).unwrap(), 0, values)

package/src/errors/render.ts

@@ -19,6 +19,8 @@ import type {
   SurfaceFailureKind,
 } from '@forgeax/engine-render-graph';
 import type { DeviceResourceKind, DeviceScopeReceipt } from '../device/resource-types';
+import type { SunCardinalityError } from '../environment/frame';
+import type { MotionBlurValidationError } from '../features/motion-blur/motion-blur-params';
 import type {
   PreparedKind,
   RenderFeatureCapabilityKey,
@@ -783,6 +785,8 @@ export interface RenderFeatureStageFailedDetail {
   readonly stage: RenderFeatureStage;
   readonly recovery: RenderFeatureRecovery;
   readonly cleanupFailures?: readonly RenderFeatureCleanupFailure[];
+  /** Original stage exception when the feature did not return a RenderError. */
+  readonly cause?: unknown;
 }
 
 export interface RenderFeatureCapabilityMissingDetail {
@@ -947,6 +951,7 @@ export class RenderFeatureStageFailedError extends Error {
     order: number,
     stage: RenderFeatureStage,
     recovery: RenderFeatureRecovery,
+    cause?: unknown,
   ) {
     const expected = `feature '${featureIdentity}' completes its ${stage} stage without an error`;
     const hint = renderFeatureRecoveryHintByRecovery[recovery](featureIdentity, stage);
@@ -954,7 +959,13 @@ export class RenderFeatureStageFailedError extends Error {
     this.name = 'RenderFeatureStageFailedError';
     this.expected = expected;
     this.hint = hint;
-    this.detail = { featureIdentity, order, stage, recovery };
+    this.detail = {
+      featureIdentity,
+      order,
+      stage,
+      recovery,
+      ...(cause === undefined ? {} : { cause }),
+    };
   }
 }
 
@@ -1966,12 +1977,14 @@ export type RenderError =
   | RenderFeatureDrawRecordingFailedError
   | EnvironmentSourceConflictError
   | FogCardinalityError
+  | SunCardinalityError
   | TaaCapsInsufficientError
   | EnvironmentGenerationFailedError
   | AtmosphereInvalidParameterError
   | DynamicResolutionInvalidParameterError
   | DynamicResolutionRequiresTaaError
   | DynamicResolutionTimingUnavailableError
+  | MotionBlurValidationError
   | OwnerStageFailedError
   | PointsLinesInvalidStyleError
   | PointsLinesTopologyMismatchError

package/src/extract/camera.ts

@@ -4,19 +4,25 @@ import { mat4, vec3 } from '@forgeax/engine-math';
 import { GlobalTransform } from '@forgeax/engine-scene';
 import {
   antialiasFromF32,
-  bloomEnabledFromF32,
   Camera,
   cameraExposureFromColumns,
   cameraProjectionFromF32,
   tonemapFromF32,
+  validateCameraBloom,
   validateCameraColorGrading,
 } from '../components/camera';
+import { DepthOfField } from '../components/depth-of-field';
 import {
   DynamicResolution,
   validateDynamicResolutionCamera,
 } from '../components/dynamic-resolution';
 import { MotionBlur } from '../components/motion-blur';
 import { ScreenSpaceReflection } from '../components/screen-space-reflection';
+import {
+  depthOfFieldRequestFailure,
+  resolveDepthOfFieldParams,
+} from '../features/depth-of-field/depth-of-field-params';
+import { resolveMotionBlurParams } from '../features/motion-blur/motion-blur-params';
 import type { CameraSnapshot } from '../render-contract';
 import { getActiveCamera, selectActiveCameraIndex } from '../systems/active-camera';
 
@@ -32,16 +38,37 @@ export function extractCameraSnapshots(world: World): CameraSnapshot[] {
   const cameraQuery = world
     .query({
       read: [Camera],
-      optional: [MotionBlur, DynamicResolution, ScreenSpaceReflection],
+      optional: [MotionBlur, DynamicResolution, ScreenSpaceReflection, DepthOfField],
       with: [GlobalTransform],
     })
     .unwrap();
   for (const row of cameraQuery) {
     const cam = row.get(Camera);
     const motionBlur = row.get(MotionBlur);
+    const motionBlurResult = resolveMotionBlurParams(motionBlur);
+    if (!motionBlurResult.ok) throw motionBlurResult.error;
+    const motionBlurParams = motionBlurResult.value;
+    const depthOfField = row.get(DepthOfField);
     validateCameraColorGrading(cam.temperature, cam.tint, cam.colorLutStrength);
     const dynamicResolution = row.get(DynamicResolution);
+    const projection = cameraProjectionFromF32(cam.projection);
+    const depthOfFieldResult = resolveDepthOfFieldParams(depthOfField, {
+      projection,
+      fov: cam.fov,
+      near: cam.near,
+      far: cam.far,
+    });
+    const depthOfFieldError = depthOfFieldResult.ok
+      ? undefined
+      : depthOfFieldRequestFailure(depthOfFieldResult.error);
     const screenSpaceReflection = row.get(ScreenSpaceReflection);
+    const bloom = validateCameraBloom(
+      cam.bloom,
+      cam.bloomThreshold,
+      cam.bloomIntensity,
+      cam.bloomSoftKnee,
+      cam.bloomScatter,
+    );
     const entity = row.entity as EntityHandle;
     const worldMat = readWorldMatrix(world, entity);
     if (worldMat === undefined) continue;
@@ -57,7 +84,7 @@ export function extractCameraSnapshots(world: World): CameraSnapshot[] {
       aspect: cam.aspect,
       near: cam.near,
       far: cam.far,
-      projection: cameraProjectionFromF32(cam.projection),
+      projection,
       orthoLeft: cam.left,
       orthoRight: cam.right,
       orthoBottom: cam.bottom,
@@ -76,23 +103,29 @@ export function extractCameraSnapshots(world: World): CameraSnapshot[] {
       ...(dynamicResolutionResult.value === undefined
         ? {}
         : { dynamicResolution: dynamicResolutionResult.value }),
-      bloom: bloomEnabledFromF32(cam.bloom),
+      bloom,
       bloomThreshold: cam.bloomThreshold,
       bloomIntensity: cam.bloomIntensity,
-      bloomBlurRadius: cam.bloomBlurRadius,
+      bloomSoftKnee: cam.bloomSoftKnee,
+      bloomScatter: cam.bloomScatter,
       clearColor: [
         cam.clearColor[0] ?? 0,
         cam.clearColor[1] ?? 0,
         cam.clearColor[2] ?? 0,
         cam.clearColor[3] ?? 1,
       ],
-      ...(motionBlur === undefined
+      ...(depthOfFieldResult.ok && depthOfFieldResult.value !== undefined
+        ? { depthOfField: depthOfFieldResult.value }
+        : {}),
+      ...(depthOfFieldError === undefined ? {} : { depthOfFieldError }),
+      ...(motionBlurParams === undefined
         ? {}
         : {
             motionBlur: {
-              shutterAngle: motionBlur.shutterAngle,
-              maxRadiusPixels: motionBlur.maxRadiusPixels,
-              sampleCount: motionBlur.sampleCount,
+              shutterAngle: motionBlurParams.shutterAngle,
+              maxRadiusPixels: motionBlurParams.maxRadiusPixels,
+              sampleCount: motionBlurParams.sampleCount,
+              targetFps: motionBlurParams.targetFps,
             },
           }),
       ...(screenSpaceReflection === undefined

package/src/extract/contracts.ts

@@ -394,6 +394,8 @@ export interface ExtractedVolumetricFog {
   readonly generation?: number;
   readonly digest?: string;
   readonly worldId?: number;
+  /** Canonical simulation time projected from the owning World. */
+  readonly worldTimeSeconds?: number;
   readonly lightEntity?: EntityHandle;
   readonly lightKind?: 'directional' | 'point' | 'spot';
   readonly pointLightEntity?: EntityHandle;
@@ -530,6 +532,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;
@@ -563,6 +568,8 @@ export interface GpuDrivenDrawSnapshot {
 export interface InstancesSnapshot {
   /** Packed column-major mat4 transforms (16 f32 per instance). */
   readonly transforms: Float32Array;
+  /** Optional unique identity generations; tokens travel with instances through reorder. */
+  readonly generations?: Uint32Array;
   /** Number of instances (transforms.length / 16). */
   readonly instanceCount: number;
   /** Stable per-entity GPU buffer cache key (the packed Entity u32). */

package/src/extract/environment.ts

@@ -39,6 +39,8 @@ export interface AtmosphereParameters {
   readonly mieCoefficient: number;
   readonly mieDirectionalG: number;
   readonly sunAngularRadius: number;
+  readonly circumsolarStrength: number;
+  readonly circumsolarWidth: number;
 }
 
 /** Shared CPU contract for values accepted by the atmosphere shaders. */
@@ -50,6 +52,8 @@ export const ATMOSPHERE_PARAMETER_RANGES: Readonly<
   mieCoefficient: Object.freeze({ min: 0, max: Number.POSITIVE_INFINITY }),
   mieDirectionalG: Object.freeze({ min: 0, max: 0.999 }),
   sunAngularRadius: Object.freeze({ min: 0, max: Number.POSITIVE_INFINITY }),
+  circumsolarStrength: Object.freeze({ min: 0, max: 4 }),
+  circumsolarWidth: Object.freeze({ min: 0.25, max: 4 }),
 });
 
 export interface FogCandidate {