@forgeax/engine-render 0.1.32 → 0.1.34

package/src/device/gpu-residency.ts

@@ -75,7 +75,6 @@ import {
   type TextureAsset,
   type TextureShape,
   type MeshAsset as TypesMeshAsset,
-  toShared,
 } from '@forgeax/engine-types';
 import { GpuBuffer, GpuTexture } from '../gpu-resource';
 import {
@@ -570,6 +569,12 @@ export class GpuResidencyCache {
   // equirect source always resolves to the same cubemap (idempotent, A2).
   private readonly cubemapIdempotentMap: Map<number, Handle<'EquirectAsset', 'shared'>> = new Map();
   private readonly meshGpuHandles: Map<string | number, MeshGpuHandles> = new Map();
+  /**
+   * Lower-detail POD identities packed into each resident mesh entry. The
+   * GPU entry only carries byte ranges; keeping the source identities beside
+   * it lets a later draw upgrade a root-only upload without hashing vertices.
+   */
+  private readonly meshLodAssets = new WeakMap<MeshGpuHandles, readonly TypesMeshAsset[]>();
   private readonly meshLifetimes = new WeakMap<MeshGpuHandles, MeshResidencyLifetime>();
   private readonly retiredMeshes = new Set<MeshGpuHandles>();
 
@@ -832,7 +837,7 @@ export class GpuResidencyCache {
     handle: Handle<'MeshAsset', 'shared'>,
     worldId: World | number = 0,
   ): { freed: number; errors: RhiError[] } {
-    const id = this.worldKey(handleSlot(handle), worldId);
+    const id = this.worldKey(Number(handle), worldId);
     const entry = this.meshGpuHandles.get(id);
     if (entry === undefined) return { freed: 0, errors: [] };
 
@@ -1090,7 +1095,7 @@ export class GpuResidencyCache {
     handle: Handle<'MeshAsset', 'shared'>,
     worldId: World | number = 0,
   ): MeshGpuHandles | undefined {
-    return this.meshGpuHandles.get(this.worldKey(handleSlot(handle), worldId));
+    return this.meshGpuHandles.get(this.worldKey(Number(handle), worldId));
   }
 
   /** Candidate leases retain the concrete allocation even after cache invalidation. */
@@ -1098,7 +1103,7 @@ export class GpuResidencyCache {
     handle: Handle<'MeshAsset', 'shared'>,
     worldId: World | number = 0,
   ): MeshResidencyLease | undefined {
-    const key = this.worldKey(handleSlot(handle), worldId);
+    const key = this.worldKey(Number(handle), worldId);
     const entry = this.meshGpuHandles.get(key);
     return entry === undefined
       ? undefined
@@ -1110,7 +1115,7 @@ export class GpuResidencyCache {
 
   /** In-place author changes immediately miss the cache; old submissions keep their allocation. */
   invalidateMesh(handle: number, worldId: World | number = 0): void {
-    const key = this.worldKey(handleSlot(toShared<'MeshAsset'>(handle)), worldId);
+    const key = this.worldKey(handle, worldId);
     const entry = this.meshGpuHandles.get(key);
     if (entry !== undefined) this.retireMeshEntry(key, entry);
   }
@@ -1156,9 +1161,32 @@ export class GpuResidencyCache {
     // path, not routed here).
     switch (pod.kind) {
       case 'mesh': {
-        const key = this.worldKey(id, worldId);
+        // Recycled shared slots can coexist with an older GPU submission.
+        // The generation is part of mesh residency identity, not only its slot.
+        const key = this.worldKey(Number(handle), worldId);
         const existing = this.meshGpuHandles.get(key);
-        if (existing !== undefined) return ok(existing);
+        if (existing !== undefined) {
+          // A root mesh can become resident before its lower-detail assets are
+          // available. Preserve the fast hit for the common case, but publish
+          // a complete chain once the caller supplies one. Never downgrade a
+          // resident chain when a later call has no lower assets yet.
+          if (lodMeshes.length === 0) return ok(existing);
+          const previousLodAssets = this.meshLodAssets.get(existing);
+          const sameLodChain =
+            previousLodAssets !== undefined &&
+            previousLodAssets.length === lodMeshes.length &&
+            previousLodAssets.every((asset, index) => asset === lodMeshes[index]);
+          if (sameLodChain) return ok(existing);
+
+          const projected = deriveRenderDataMesh(pod);
+          if (!projected.ok) return projected;
+          const upgraded = this.uploadMeshById(key, pod, projected.value, lodMeshes);
+          if (!upgraded.ok) return upgraded;
+          // uploadMeshById publishes the new entry before this call so the
+          // old allocation stays available to any already-recorded frame.
+          this.retireMeshEntry(key, existing);
+          return upgraded;
+        }
         const projected = deriveRenderDataMesh(pod);
         if (!projected.ok) return projected;
         return this.uploadMeshById(key, pod, projected.value, lodMeshes);
@@ -1204,7 +1232,7 @@ export class GpuResidencyCache {
   ): Result<RecoveryResidencyPreparation, RhiError | AssetError | ImageError> {
     const id = handleSlot(handle);
     if (pod.kind === 'mesh') {
-      const key = this.worldKey(id, worldId);
+      const key = this.worldKey(Number(handle), worldId);
       if (this.meshGpuHandles.has(key)) return ok({});
       const projected = deriveRenderDataMesh(pod);
       if (!projected.ok) return projected;
@@ -2035,6 +2063,10 @@ export class GpuResidencyCache {
     // Vertex-only mesh: skip the index buffer entirely. The indexed path below
     // is unchanged byte-for-byte when `indices` is present.
     let ibo: Buffer | null = null;
+    const cleanupUpload = (): void => {
+      if (ibo !== null) device.destroyBuffer(ibo);
+      device.destroyBuffer(vbo);
+    };
     if (indices !== undefined) {
       const iboResult = device.createBuffer({
         label: `mesh-${id}-ibo`,
@@ -2042,17 +2074,24 @@ export class GpuResidencyCache {
         usage: renderData.indexUsage,
         mappedAtCreation: false,
       });
-      if (!iboResult.ok) return iboResult;
+      if (!iboResult.ok) {
+        cleanupUpload();
+        return iboResult;
+      }
       ibo = iboResult.value;
     }
 
     const vboWriteResult = device.queue.writeBuffer(vbo, 0, vertices);
-    if (!vboWriteResult.ok) return err(vboWriteResult.error);
+    if (!vboWriteResult.ok) {
+      cleanupUpload();
+      return err(vboWriteResult.error);
+    }
 
     if (indices !== undefined) {
       const indexSrc = new Uint8Array(indexBytes);
       indexSrc.set(new Uint8Array(indices.buffer, indices.byteOffset, indexBytesUnpadded));
-      if (ibo === null)
+      if (ibo === null) {
+        cleanupUpload();
         return err(
           new RhiError({
             code: 'webgpu-runtime-error',
@@ -2060,8 +2099,12 @@ export class GpuResidencyCache {
             hint: 'the indexed mesh upload lost its RHI index-buffer owner',
           }),
         );
+      }
       const iboWriteResult = device.queue.writeBuffer(ibo, 0, indexSrc);
-      if (!iboWriteResult.ok) return err(iboWriteResult.error);
+      if (!iboWriteResult.ok) {
+        cleanupUpload();
+        return err(iboWriteResult.error);
+      }
     }
 
     // The geometry projection already contains every packed attribute,
@@ -2085,6 +2128,7 @@ export class GpuResidencyCache {
       ...(lodRanges === undefined ? {} : { lodRanges }),
     };
     this.meshGpuHandles.set(id, entry);
+    this.meshLodAssets.set(entry, lodMeshes);
     this.meshResidencyEpoch += 1;
     return ok(entry);
   }

package/src/dynamic-geometry.ts

@@ -53,6 +53,9 @@ export interface DynamicGeometryCandidate {
   readonly state: DynamicGeometryCandidateState;
 }
 
+/** Record-stage lane that consumed a published dynamic-geometry candidate. */
+export type DynamicGeometryRecordStageLane = 'cpu' | 'gpu' | 'mixed';
+
 /** Receipt that ties candidate publication to the sole Renderer FrameReceipt. */
 export interface DynamicGeometryReceipt {
   readonly candidateId: string;
@@ -69,6 +72,8 @@ export interface DynamicGeometryReceipt {
   };
   /** Whether the Renderer record stage consumed this candidate for this frame. */
   readonly recordStageConsumed: boolean;
+  /** Lane evidence from the exact submitted record stage, when attached. */
+  readonly recordStageLane?: DynamicGeometryRecordStageLane;
   /** Actual frame fixed step; may be newer than the preparation step. */
   readonly publicationFixedStep?: number;
 }
@@ -271,6 +276,9 @@ export interface DynamicGeometryLifecycle {
     worlds?: readonly object[],
     fixedStep?: number,
     canPublish?: (candidate: DynamicGeometryCandidate) => boolean,
+    recordStageLane?: (
+      candidate: DynamicGeometryCandidate,
+    ) => DynamicGeometryRecordStageLane | undefined,
   ): readonly DynamicGeometryReceipt[];
   invalidateWorld(world: object, completion?: Promise<unknown>): void;
   invalidateGeneration(generation: number): void;
@@ -610,7 +618,7 @@ export function createDynamicGeometryLifecycle(
       meshBytes = Math.max(0, meshBytes - record.candidate.meshBytes);
       return ok(undefined);
     },
-    publishFrame(frame, worlds, fixedStep, canPublish) {
+    publishFrame(frame, worlds, fixedStep, canPublish, recordStageLane) {
       if (disposed || frame.deviceGeneration !== currentGeneration) return [];
       const receipts: DynamicGeometryReceipt[] = [];
       for (const record of records.values()) {
@@ -630,6 +638,8 @@ export function createDynamicGeometryLifecycle(
           continue;
         }
         if (canPublish !== undefined && !canPublish(record.candidate)) continue;
+        const consumedLane =
+          canPublish === undefined ? undefined : recordStageLane?.(record.candidate);
         record.candidate = Object.freeze({ ...record.candidate, state: 'published' as const });
         const receipt = Object.freeze({
           candidateId: record.candidate.candidateId,
@@ -642,6 +652,7 @@ export function createDynamicGeometryLifecycle(
           frameId: frame.frameId,
           deviceGeneration: frame.deviceGeneration,
           recordStageConsumed: canPublish !== undefined,
+          ...(consumedLane === undefined ? {} : { recordStageLane: consumedLane }),
           ...(fixedStep === undefined ? {} : { publicationFixedStep: fixedStep }),
           frame: Object.freeze({ ...frame }),
         });

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/cloud.ts

@@ -0,0 +1,103 @@
+/** Closed errors produced by the CloudLayer authoring and resource route. */
+
+export interface CloudLayerInvalidParameterDetail {
+  readonly field: string;
+  readonly value: unknown;
+  readonly expected: string;
+}
+
+export class CloudLayerInvalidParameterError extends Error {
+  readonly code = 'cloud-layer-invalid-parameter' as const;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: CloudLayerInvalidParameterDetail;
+
+  constructor(field: string, value: unknown, expected: string) {
+    super(`CloudLayer.${field} is invalid`);
+    this.name = 'CloudLayerInvalidParameterError';
+    this.expected = `CloudLayer.${field} must be ${expected}`;
+    this.hint = `set CloudLayer.${field} to ${expected}`;
+    this.detail = { field, value, expected };
+  }
+}
+
+export interface CloudLayerOwnerConflictDetail {
+  readonly count: number;
+}
+
+export class CloudLayerOwnerConflictError extends Error {
+  readonly code = 'cloud-layer-owner-conflict' as const;
+  readonly expected = 'at most one CloudLayer owns a World frame';
+  readonly hint = 'remove additional CloudLayer owners before extraction';
+  readonly detail: CloudLayerOwnerConflictDetail;
+
+  constructor(count: number) {
+    super(`CloudLayer owner cardinality is ${count}`);
+    this.name = 'CloudLayerOwnerConflictError';
+    this.detail = { count };
+  }
+}
+
+export interface CloudLayerCacheInvalidDetail {
+  readonly sourceKey: string;
+  readonly reason: string;
+}
+
+export class CloudLayerCacheInvalidError extends Error {
+  readonly code = 'cloud-layer-cache-invalid' as const;
+  readonly expected = 'the density cache payload matches its reconstructible source';
+  readonly hint = 'discard the derived cache and rebuild it from CloudLayer source facts';
+  readonly detail: CloudLayerCacheInvalidDetail;
+
+  constructor(sourceKey: string, reason: string) {
+    super(`CloudLayer cache is invalid: ${reason}`);
+    this.name = 'CloudLayerCacheInvalidError';
+    this.detail = { sourceKey, reason };
+  }
+}
+
+export interface CloudLayerCapabilityMissingDetail {
+  readonly capability: string;
+}
+
+export class CloudLayerCapabilityMissingError extends Error {
+  readonly code = 'cloud-layer-capability-missing' as const;
+  readonly expected = 'the selected backend exposes the capability required by the cloud lane';
+  readonly hint =
+    'inspect the capability report, disable the cloud lane on this backend, or retry on a backend with the required capability';
+  readonly detail: CloudLayerCapabilityMissingDetail;
+
+  constructor(capability: string) {
+    super(`CloudLayer capability is unavailable: ${capability}`);
+    this.name = 'CloudLayerCapabilityMissingError';
+    this.detail = { capability };
+  }
+}
+
+export interface CloudLayerResourceFailureDetail {
+  readonly stage: 'cache' | 'shadow' | 'view' | 'history' | 'retire';
+  readonly generation: number;
+  readonly cause?: unknown;
+}
+
+export class CloudLayerResourceFailureError extends Error {
+  readonly code = 'cloud-layer-resource-failed' as const;
+  readonly expected = 'cloud resources are created, submitted and retired as one generation';
+  readonly hint = 'keep the last-known-good cloud generation and retry after recovery';
+  readonly detail: CloudLayerResourceFailureDetail;
+
+  constructor(detail: CloudLayerResourceFailureDetail) {
+    super(`CloudLayer ${detail.stage} resource failed at generation ${detail.generation}`);
+    this.name = 'CloudLayerResourceFailureError';
+    this.detail = detail;
+  }
+}
+
+export type CloudLayerError =
+  | CloudLayerInvalidParameterError
+  | CloudLayerOwnerConflictError
+  | CloudLayerCacheInvalidError
+  | CloudLayerCapabilityMissingError
+  | CloudLayerResourceFailureError;
+
+export type CloudLayerErrorCode = CloudLayerError['code'];

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,
@@ -28,6 +30,7 @@ import type {
 import type { AutoExposureError } from '../pipeline/standard-output/auto-exposure/inspection';
 import type { SceneDataLane, SceneDataSchemaId } from '../temporal/scene-data';
 import type { TransmissionCapabilityFact } from '../transmission/backdrop';
+import type { CloudLayerError } from './cloud';
 import type { RecoveryOutcome, RecoveryPhase } from './recover';
 
 // Public render errors keep one machine-readable order: closed `code`,
@@ -783,6 +786,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 +952,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 +960,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 }),
+    };
   }
 }
 
@@ -1381,6 +1393,27 @@ export type DynamicResolutionError =
   | DynamicResolutionRequiresTaaError
   | DynamicResolutionTimingUnavailableError;
 
+export interface BarrelDistortionInvalidParameterDetail {
+  readonly field: 'width' | 'height' | 'strength' | 'centerX' | 'centerY';
+  readonly value: number;
+  readonly expected: string;
+}
+
+export class BarrelDistortionInvalidParameterError extends Error {
+  readonly code = 'barrel-distortion-invalid-parameter' as const;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: BarrelDistortionInvalidParameterDetail;
+
+  constructor(detail: BarrelDistortionInvalidParameterDetail) {
+    super(`BarrelDistortion.${detail.field} is invalid`);
+    this.name = 'BarrelDistortionInvalidParameterError';
+    this.expected = `BarrelDistortion.${detail.field} must be ${detail.expected}`;
+    this.hint = `set BarrelDistortion.${detail.field} to a value that is ${detail.expected}`;
+    this.detail = detail;
+  }
+}
+
 export interface OwnerStageFailedDetail {
   readonly owner: 'environment' | 'temporal' | 'fog' | 'renderer';
   readonly stage: 'extract' | 'prepare' | 'record' | 'finish' | 'submit';
@@ -1828,8 +1861,8 @@ export interface VolumeOwnerConflictDetail {
 
 export class VolumeOwnerConflictError extends Error {
   readonly code = 'volume-owner-conflict' as const;
-  readonly expected = 'exactly one global VolumetricFog owner is authored';
-  readonly hint = 'remove additional VolumetricFog owners and retry extraction';
+  readonly expected = 'at most eight local VolumetricFog owners per rendered World';
+  readonly hint = 'reduce simultaneously visible volume owners and retry extraction';
   readonly detail: VolumeOwnerConflictDetail;
 
   constructor(ownerCount: number) {
@@ -1883,13 +1916,26 @@ export interface VolumeInvalidParametersDetail {
 export class VolumeInvalidParametersError extends Error {
   readonly code = 'volume-invalid-parameters' as const;
   readonly expected = 'volume parameters remain finite and inside their closed ranges';
-  readonly hint = 'repair extinction, albedo, emission, anisotropy, or maxDistance';
+  readonly hint = 'repair extinction, albedo, emission, anisotropy, maxDistance, or sampling';
   readonly detail: VolumeInvalidParametersDetail;
 
-  constructor(input: { readonly maxDistance?: number; readonly anisotropy?: number }) {
-    const field =
-      input.maxDistance !== undefined && input.maxDistance <= 0 ? 'maxDistance' : 'parameters';
-    const value = field === 'maxDistance' ? input.maxDistance : input.anisotropy;
+  constructor(input: {
+    readonly maxDistance?: number;
+    readonly anisotropy?: number;
+    readonly sampling?: string;
+  }) {
+    const invalidSampling =
+      input.sampling !== undefined && input.sampling !== 'noise' && input.sampling !== 'density';
+    const field = invalidSampling
+      ? 'sampling'
+      : input.maxDistance !== undefined && input.maxDistance <= 0
+        ? 'maxDistance'
+        : 'parameters';
+    const value = invalidSampling
+      ? input.sampling
+      : field === 'maxDistance'
+        ? input.maxDistance
+        : input.anisotropy;
     super(`volume-invalid-parameters: ${field} is outside the authored range`);
     this.name = 'VolumeInvalidParametersError';
     this.detail = { field, value };
@@ -1966,12 +2012,16 @@ export type RenderError =
   | RenderFeatureDrawRecordingFailedError
   | EnvironmentSourceConflictError
   | FogCardinalityError
+  | SunCardinalityError
   | TaaCapsInsufficientError
   | EnvironmentGenerationFailedError
   | AtmosphereInvalidParameterError
+  | BarrelDistortionInvalidParameterError
+  | CloudLayerError
   | DynamicResolutionInvalidParameterError
   | DynamicResolutionRequiresTaaError
   | DynamicResolutionTimingUnavailableError
+  | MotionBlurValidationError
   | OwnerStageFailedError
   | PointsLinesInvalidStyleError
   | PointsLinesTopologyMismatchError

package/src/examples/single-layer-medium-surface.ts

@@ -0,0 +1,59 @@
+import type { MaterialRootAsset } from '@forgeax/engine-types';
+
+/**
+ * A public root asset showing the model declaration and its bounded input.
+ * The page is shared by every material instance; Render supplies the page
+ * bytes and each instance publishes its own range.
+ */
+export const SINGLE_LAYER_MEDIUM_SURFACE_EXAMPLE = {
+  kind: 'material',
+  surface: {
+    model: 'single-layer-medium',
+    module: 'game::water_surface_a',
+    dynamicInput: {
+      name: 'waterEvents',
+      fields: [
+        { name: 'position', type: 'vec3<f32>' },
+        { name: 'time', type: 'f32' },
+        { name: 'eventId', type: 'u32' },
+      ],
+      maxRecords: 64,
+      maxDomains: 8,
+      maxPageBytes: 2048,
+      maxBindings: 1,
+      maxEventsPerSample: 8,
+    },
+  },
+  passes: [
+    {
+      name: 'color',
+      program: { module: 'forgeax::single-layer-medium' },
+    },
+  ],
+  parameters: [],
+  values: {},
+} as const satisfies MaterialRootAsset;
+
+/** Two different imported Surface implementations consuming one model ABI. */
+export const SINGLE_LAYER_MEDIUM_SURFACE_EXAMPLES = [
+  {
+    module: 'game::water_surface_a',
+    source: `#define_import_path game::water_surface_a
+#import forgeax_material::single_layer_medium_surface_v1::{SingleLayerMediumSurfaceInput, SingleLayerMediumSurfaceData}
+fn evaluate_surface(input : SingleLayerMediumSurfaceInput) -> SingleLayerMediumSurfaceData {
+  let event = read_waterEvents(input.eventRangeStart);
+  let normal = normalize(input.geometricNormalWS + vec3<f32>(0.0, 0.0, event.time * 0.02));
+  return SingleLayerMediumSurfaceData(normal, 0.18, 1.0, 0.0, vec3<f32>(0.18, 0.06, 0.02), vec3<f32>(0.02, 0.04, 0.08), 1.333, 0.2, 1000.0);
+}`,
+  },
+  {
+    module: 'game::water_surface_b',
+    source: `#define_import_path game::water_surface_b
+#import forgeax_material::single_layer_medium_surface_v1::{SingleLayerMediumSurfaceInput, SingleLayerMediumSurfaceData}
+fn evaluate_surface(input : SingleLayerMediumSurfaceInput) -> SingleLayerMediumSurfaceData {
+  let event = read_waterEvents(input.eventRangeStart);
+  let normal = normalize(input.geometricNormalWS + vec3<f32>(event.position.xy * 0.01, 0.0));
+  return SingleLayerMediumSurfaceData(normal, 0.32, 1.0, clamp(event.time * 0.1, 0.0, 1.0), vec3<f32>(0.04, 0.02, 0.01), vec3<f32>(0.08, 0.05, 0.02), 1.333, -0.1, 800.0);
+}`,
+  },
+] as const;

package/src/extract/camera.ts

@@ -2,13 +2,17 @@ import type { EntityHandle, World } from '@forgeax/engine-ecs';
 import { readRenderArrayView } from '@forgeax/engine-ecs/projection';
 import { mat4, vec3 } from '@forgeax/engine-math';
 import { GlobalTransform } from '@forgeax/engine-scene';
+import {
+  BarrelDistortion,
+  validateBarrelDistortionParameters,
+} from '../components/barrel-distortion';
 import {
   antialiasFromF32,
-  bloomEnabledFromF32,
   Camera,
   cameraExposureFromColumns,
   cameraProjectionFromF32,
   tonemapFromF32,
+  validateCameraBloom,
   validateCameraColorGrading,
 } from '../components/camera';
 import { DepthOfField } from '../components/depth-of-field';
@@ -22,6 +26,7 @@ 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';
 
@@ -37,13 +42,23 @@ export function extractCameraSnapshots(world: World): CameraSnapshot[] {
   const cameraQuery = world
     .query({
       read: [Camera],
-      optional: [MotionBlur, DynamicResolution, ScreenSpaceReflection, DepthOfField],
+      optional: [
+        MotionBlur,
+        DynamicResolution,
+        ScreenSpaceReflection,
+        DepthOfField,
+        BarrelDistortion,
+      ],
       with: [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);
     validateCameraColorGrading(cam.temperature, cam.tint, cam.colorLutStrength);
     const dynamicResolution = row.get(DynamicResolution);
@@ -58,12 +73,21 @@ export function extractCameraSnapshots(world: World): CameraSnapshot[] {
       ? 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;
     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,
       historyVersion: cam.historyVersion,
@@ -92,10 +116,11 @@ 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,
@@ -106,15 +131,17 @@ export function extractCameraSnapshots(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
         ? {}
         : {