@forgeax/engine-render 0.1.32 → 0.1.34

package/src/volume/component.ts

@@ -5,9 +5,11 @@ import {
   type VolumeError,
   VolumeInvalidBoundsError,
   VolumeInvalidParametersError,
-  VolumeOwnerConflictError,
 } from '../errors/render';
 
+export const MAX_VOLUMETRIC_FOG_OWNERS = 8;
+export const VolumetricFogSamplingValue = { noise: 0, density: 1 } as const;
+
 export interface VolumeDensityBinding {
   readonly guid: string;
   readonly generation: number;
@@ -35,7 +37,6 @@ export interface VolumetricFogAuthoring {
   readonly light: EntityHandle;
   /** The optional same-World SpotLight paired with a PointLight. */
   readonly spotLight?: EntityHandle;
-  /** Linear scalar density over bounds; the renderer adds no noise or animation. */
   readonly density: VolumeDensityBinding;
   readonly bounds: VolumeBounds;
   readonly extinction: readonly [number, number, number];
@@ -43,16 +44,15 @@ export interface VolumetricFogAuthoring {
   readonly emission: readonly [number, number, number];
   readonly anisotropy: number;
   readonly maxDistance: number;
-  readonly ownerCount?: number;
+  /** Noise grain is the atmospheric default; density samples local bounds directly. */
+  readonly sampling?: 'noise' | 'density';
 }
 
 export type VolumetricFogLightSelection =
   | { readonly light: EntityHandle; readonly spotLight?: undefined }
   | { readonly light: EntityHandle; readonly spotLight: EntityHandle };
 
-export interface ValidatedVolumetricFog extends VolumetricFogAuthoring {
-  readonly ownerCount: 1;
-}
+export type ValidatedVolumetricFog = VolumetricFogAuthoring;
 
 export const VolumetricFog = defineComponent('VolumetricFog', {
   light: { type: 'entity' },
@@ -65,6 +65,7 @@ export const VolumetricFog = defineComponent('VolumetricFog', {
   emission: { type: 'array<f32, 3>' },
   anisotropy: { type: 'f32', default: 0 },
   maxDistance: { type: 'f32', default: 100 },
+  sampling: { type: 'enum', labels: VolumetricFogSamplingValue, default: 0 },
 });
 
 function finiteVector(value: readonly [number, number, number]): boolean {
@@ -87,8 +88,6 @@ function validRange(
 export function validateVolumetricFog(
   input: VolumetricFogAuthoring,
 ): Result<ValidatedVolumetricFog, VolumeError> {
-  const ownerCount = input.ownerCount ?? 1;
-  if (ownerCount !== 1) return err(new VolumeOwnerConflictError(ownerCount));
   if (input.density.shape.viewDimension !== '3d' || input.density.colorSpace === 'srgb') {
     return err(
       new VolumeDensityShapeMismatchError(input.density.guid, input.density.shape.viewDimension),
@@ -103,9 +102,10 @@ export function validateVolumetricFog(
     input.anisotropy <= -1 ||
     input.anisotropy >= 1 ||
     !Number.isFinite(input.maxDistance) ||
-    input.maxDistance <= 0
+    input.maxDistance <= 0 ||
+    (input.sampling !== undefined && input.sampling !== 'noise' && input.sampling !== 'density')
   ) {
     return err(new VolumeInvalidParametersError(input));
   }
-  return ok({ ...input, ownerCount: 1 });
+  return ok(input);
 }

package/src/volume/extract.ts

@@ -1,6 +1,7 @@
 import { err, ok, type Result } from '@forgeax/engine-types';
 import { type VolumeError, VolumeOwnerConflictError } from '../errors/render';
 import {
+  MAX_VOLUMETRIC_FOG_OWNERS,
   type ValidatedVolumetricFog,
   type VolumetricFogAuthoring,
   validateVolumetricFog,
@@ -8,14 +9,19 @@ import {
 
 export type VolumetricFogExtract =
   | { readonly status: 'off' }
-  | { readonly status: 'available'; readonly fog: ValidatedVolumetricFog };
+  | { readonly status: 'available'; readonly fogs: readonly ValidatedVolumetricFog[] };
 
 export function extractVolumetricFog(
   inputs: readonly VolumetricFogAuthoring[],
 ): Result<VolumetricFogExtract, VolumeError> {
   if (inputs.length === 0) return ok({ status: 'off' });
-  if (inputs.length !== 1) return err(new VolumeOwnerConflictError(inputs.length));
-  const validated = validateVolumetricFog(inputs[0] as VolumetricFogAuthoring);
-  if (!validated.ok) return validated;
-  return ok({ status: 'available', fog: validated.value });
+  if (inputs.length > MAX_VOLUMETRIC_FOG_OWNERS)
+    return err(new VolumeOwnerConflictError(inputs.length));
+  const fogs: ValidatedVolumetricFog[] = [];
+  for (const input of inputs) {
+    const validated = validateVolumetricFog(input);
+    if (!validated.ok) return validated;
+    fogs.push(validated.value);
+  }
+  return ok({ status: 'available', fogs });
 }

package/src/volume/inspection.ts

@@ -7,6 +7,8 @@ export type VolumetricFogInspectionStatus = 'off' | 'available' | 'unavailable'
 export type VolumetricFogResourceStage = 'none' | 'candidate' | 'accepted' | 'lkg' | 'recovering';
 
 export interface VolumetricFogInspection {
+  /** Owners in the last successfully submitted volume collection. */
+  readonly ownerCount: number;
   readonly status: VolumetricFogInspectionStatus;
   readonly resourceStage: VolumetricFogResourceStage;
   readonly guid: string | undefined;
@@ -57,6 +59,7 @@ export function inspectVolumetricFog(input: VolumetricFogInspectionInput): Volum
         ? 'degraded'
         : 'available';
   return Object.freeze({
+    ownerCount: 0,
     status,
     resourceStage: resourceStage(input),
     guid: recovery?.guid,

package/src/volume/passes.ts

@@ -25,6 +25,7 @@ import type {
   RenderPipelineTarget,
   RenderPipelineTopology,
 } from '../render-pipeline';
+import { MAX_VOLUMETRIC_FOG_OWNERS } from './component';
 import type { VolumetricFogResources } from './resources';
 import {
   createVolumetricFogResources,
@@ -32,6 +33,7 @@ import {
   VOLUME_HISTORY_FORMAT,
   VOLUME_PACKING_Z,
   VOLUME_RESOLVED_FORMAT,
+  VOLUMETRIC_FOG_PARAMS_BYTES,
 } from './resources';
 import type { VolumeProjectorTuple } from './temporal';
 
@@ -79,6 +81,7 @@ export interface VolumetricFogPassInputs {
   readonly linearHdr: RenderPipelineTarget;
   readonly sceneDepth: GraphTextureView;
   readonly density: GraphTextureView;
+  readonly additionalDensities?: readonly GraphTextureView[];
   readonly params: GraphBuffer;
   readonly view: GraphBuffer;
   readonly directionalShadow?: GraphTextureView;
@@ -89,6 +92,8 @@ export interface VolumetricFogPassInputs {
   readonly clusterUniform: GraphBuffer;
   readonly selectedLightKind: 'directional' | 'point' | 'spot';
   readonly projector?: GraphTextureView;
+  /** Stable world-space cloud shadow map sampled at each volume point. */
+  readonly cloudShadow?: GraphTextureView;
 }
 function pipelineError(stage: string): RhiError {
   return new RhiError({
@@ -164,6 +169,7 @@ function importVolumeInputs(
   spotShadow: GraphTextureView,
   selectedLightKind: 'directional' | 'point' | 'spot' | undefined,
   clusterBuffers: StandardClusterGraphBuffers | null,
+  cloudShadow: GraphTextureView | undefined,
 ): Result<ImportedVolumeInputs | undefined, RenderGraphError> {
   const volume = topology.volumetricFog;
   if (volume?.enabled !== true || volume.format === undefined || volume.extent === undefined)
@@ -212,9 +218,45 @@ function importVolumeInputs(
     },
   );
   if (!density.ok) return density;
+  const additionalDensities: GraphTextureView[] = [];
+  for (const [index, member] of (volume.additional ?? []).entries()) {
+    const texture = graph.importTexture(
+      `volume-density-${index + 1}`,
+      {
+        format: member.format,
+        size: {
+          width: member.extent.width,
+          height: member.extent.height,
+          depthOrArrayLayers: member.extent.depth,
+        },
+        dimension: '3d',
+        usage: GPU_TEXTURE_USAGE_TEXTURE_BINDING,
+      },
+      (frame) => {
+        const value = frame.volumetricFog?.additional?.[index];
+        if (value === undefined) throw pipelineError('local density residency');
+        return value.densityTexture;
+      },
+    );
+    if (!texture.ok) return texture;
+    const view = graph.importView(
+      texture.value,
+      { label: `volume-density-${index + 1}.view`, dimension: '3d' },
+      (frame) => {
+        const value = frame.volumetricFog?.additional?.[index];
+        if (value === undefined) throw pipelineError('local density view residency');
+        return value.densityView;
+      },
+    );
+    if (!view.ok) return view;
+    additionalDensities.push(view.value);
+  }
   const params = graph.importBuffer(
     'volume-params',
-    { size: 128, usage: GPU_BUFFER_USAGE_UNIFORM | GPU_BUFFER_USAGE_COPY_DST },
+    {
+      size: VOLUMETRIC_FOG_PARAMS_BYTES,
+      usage: GPU_BUFFER_USAGE_UNIFORM | GPU_BUFFER_USAGE_COPY_DST,
+    },
     (frame) => {
       const context = frame.volumetricFog as VolumetricFogFrameContext | undefined;
       if (context === undefined) throw pipelineError('parameter residency');
@@ -261,6 +303,7 @@ function importVolumeInputs(
     linearHdr,
     sceneDepth,
     density: density.value,
+    additionalDensities,
     params: params.value,
     view: view.value,
     ...(directionalShadow === undefined ? {} : { directionalShadow }),
@@ -269,6 +312,7 @@ function importVolumeInputs(
     clusterUniform: clusterBuffers.clusterUniform,
     selectedLightKind: selectedLightKind ?? 'directional',
     ...(projector === undefined ? {} : { projector }),
+    ...(cloudShadow === undefined ? {} : { cloudShadow }),
   });
 }
 export function addAuthoredVolumetricFogPasses(
@@ -279,6 +323,7 @@ export function addAuthoredVolumetricFogPasses(
   directionalShadow: GraphTextureView | undefined,
   spotShadow: GraphTextureView,
   clusterBuffers: StandardClusterGraphBuffers | null,
+  cloudShadow?: GraphTextureView,
 ): Result<void, RenderGraphError> {
   // A paired Point+Spot volume stores the Spot shadow lane as well. The
   // topology's primary light remains PointLight for radiance selection, but
@@ -297,6 +342,7 @@ export function addAuthoredVolumetricFogPasses(
     spotShadow,
     shadowLightKind,
     clusterBuffers,
+    cloudShadow,
   );
   if (!imported.ok) return imported;
   if (imported.value === undefined) return ok(undefined);
@@ -322,10 +368,7 @@ export function addVolumetricFogPasses(
   // 2D depth binding; use the always-present spot target as the inert binding
   // when directional shadows are disabled. Directional selection still uses
   // its own target whenever one exists, and spot selection uses spotShadow.
-  const shadowResource =
-    inputs.selectedLightKind === 'spot'
-      ? inputs.spotShadow
-      : (inputs.directionalShadow ?? inputs.spotShadow);
+  const shadowResource = inputs.directionalShadow ?? inputs.spotShadow;
   let inject: ComputeState | undefined;
   let integrate: ComputeState | undefined;
   let temporal: ComputeState | undefined;
@@ -345,6 +388,7 @@ export function addVolumetricFogPasses(
         ? []
         : [{ resource: inputs.projector, usage: 'sampled-read' as const }]),
       { resource: inputs.resources.froxelView, usage: 'storage-write' },
+      { resource: inputs.spotShadow, usage: 'sampled-read' },
     ],
     encode: ({ pass, frame, resources }) => {
       inject ??= computeState(frame, shaderSource(frame, 'inject'), 'volume_inject', [
@@ -363,8 +407,11 @@ export function addVolumetricFogPasses(
         },
         { binding: 7, visibility: 4, buffer: { type: 'read-only-storage' } },
         { binding: 8, visibility: 4, buffer: { type: 'uniform' } },
+        { binding: 9, visibility: 4, texture: { sampleType: 'depth', viewDimension: '2d' } },
       ]);
       const shadow = resources.textureView(shadowResource);
+      const spotShadow = resources.textureView(inputs.spotShadow);
+      if (!spotShadow.ok) throw spotShadow.error;
       const params = resources.buffer(inputs.params);
       const view = resources.buffer(inputs.view);
       const lightData = resources.buffer(inputs.lightData);
@@ -386,6 +433,7 @@ export function addVolumetricFogPasses(
         { binding: 6, resource: { kind: 'textureView', value: froxel.value as never } },
         { binding: 7, resource: { kind: 'buffer', value: { buffer: lightData.value } } },
         { binding: 8, resource: { kind: 'buffer', value: { buffer: clusterUniform.value } } },
+        { binding: 9, resource: { kind: 'textureView', value: spotShadow.value as never } },
       ]);
       pass.setPipeline(inject.pipeline);
       pass.setBindGroup(0, bindings);
@@ -398,6 +446,10 @@ export function addVolumetricFogPasses(
       { resource: inputs.resources.froxelView, usage: 'sampled-read' },
       { resource: inputs.sceneDepth, usage: 'sampled-read' },
       { resource: inputs.density, usage: 'sampled-read' },
+      ...(inputs.additionalDensities ?? []).map((resource) => ({
+        resource,
+        usage: 'sampled-read' as const,
+      })),
       { resource: inputs.resources.resolvedView, usage: 'storage-write' },
       { resource: inputs.resources.historyView, usage: 'storage-write' },
       { resource: inputs.resources.temporalView, usage: 'storage-write' },
@@ -408,6 +460,9 @@ export function addVolumetricFogPasses(
       ...(inputs.projector === undefined
         ? []
         : [{ resource: inputs.projector, usage: 'sampled-read' as const }]),
+      ...(inputs.cloudShadow === undefined
+        ? []
+        : [{ resource: inputs.cloudShadow, usage: 'sampled-read' as const }]),
     ],
     encode: ({ pass, frame, resources }) => {
       integrate ??= computeState(frame, shaderSource(frame, 'integrate'), 'volume_integrate', [
@@ -449,6 +504,13 @@ export function addVolumetricFogPasses(
         { binding: 11, visibility: 4, buffer: { type: 'uniform' } },
         { binding: 12, visibility: 4, texture: { sampleType: 'float', viewDimension: '2d' } },
         { binding: 13, visibility: 4, sampler: { type: 'filtering' } },
+        { binding: 16, visibility: 4, texture: { sampleType: 'float', viewDimension: '2d' } },
+        { binding: 17, visibility: 4, sampler: { type: 'filtering' } },
+        ...Array.from({ length: MAX_VOLUMETRIC_FOG_OWNERS - 1 }, (_, index) => ({
+          binding: 18 + index,
+          visibility: 4,
+          texture: { sampleType: 'float' as const, viewDimension: '3d' as const },
+        })),
       ]);
       const froxel = resources.textureView(inputs.resources.froxelView);
       const depth = resources.textureView(inputs.sceneDepth);
@@ -462,6 +524,8 @@ export function addVolumetricFogPasses(
       const clusterUniform = resources.buffer(inputs.clusterUniform);
       const projector =
         inputs.projector === undefined ? undefined : resources.textureView(inputs.projector);
+      const cloudShadow =
+        inputs.cloudShadow === undefined ? undefined : resources.textureView(inputs.cloudShadow);
       if (!froxel.ok) throw froxel.error;
       if (!depth.ok) throw depth.error;
       if (!density.ok) throw density.error;
@@ -473,6 +537,7 @@ export function addVolumetricFogPasses(
       if (!lightData.ok) throw lightData.error;
       if (!clusterUniform.ok) throw clusterUniform.error;
       if (projector !== undefined && !projector.ok) throw projector.error;
+      if (cloudShadow !== undefined && !cloudShadow.ok) throw cloudShadow.error;
       const sampler = frame.runtime.device.createSampler({
         minFilter: 'linear',
         magFilter: 'linear',
@@ -481,9 +546,9 @@ export function addVolumetricFogPasses(
       const densitySampler = frame.runtime.device.createSampler({
         minFilter: 'linear',
         magFilter: 'linear',
-        addressModeU: 'clamp-to-edge',
-        addressModeV: 'clamp-to-edge',
-        addressModeW: 'clamp-to-edge',
+        addressModeU: 'repeat',
+        addressModeV: 'repeat',
+        addressModeW: 'repeat',
       });
       if (!densitySampler.ok) throw densitySampler.error;
       const bindings = volumeBindGroup(frame, integrate.layout, [
@@ -516,6 +581,28 @@ export function addVolumetricFogPasses(
             value: frame.volumetricFog?.projectorSampler ?? frame.pipelineState.defaultSampler,
           },
         },
+        {
+          binding: 16,
+          resource: {
+            kind: 'textureView',
+            value:
+              cloudShadow === undefined
+                ? frame.pipelineState.defaultWhiteTextureView
+                : (cloudShadow.value as never),
+          },
+        },
+        {
+          binding: 17,
+          resource: { kind: 'sampler', value: frame.pipelineState.defaultSampler },
+        },
+        ...Array.from({ length: MAX_VOLUMETRIC_FOG_OWNERS - 1 }, (_, index) => {
+          const view = resources.textureView(inputs.additionalDensities?.[index] ?? inputs.density);
+          if (!view.ok) throw view.error;
+          return {
+            binding: 18 + index,
+            resource: { kind: 'textureView' as const, value: view.value as never },
+          };
+        }),
       ]);
       pass.setPipeline(integrate.pipeline);
       pass.setBindGroup(0, bindings);

package/src/volume/resources.ts

@@ -8,6 +8,7 @@ import type {
 } from '@forgeax/engine-render-graph';
 import { ok, type Result } from '@forgeax/engine-types';
 import type { RenderPipelineFrame } from '../render-pipeline';
+import { MAX_VOLUMETRIC_FOG_OWNERS } from './component';
 
 export const VOLUME_FROXEL_FORMAT = 'rgba8unorm' as const;
 export const VOLUME_HISTORY_FORMAT = 'rgba16float' as const;
@@ -15,7 +16,7 @@ export const VOLUME_RESOLVED_FORMAT = 'rgba16float' as const;
 export const VOLUME_DEPTH_FORMAT = 'r32float' as const;
 export const VOLUME_PACKING_Z = 4;
 /** Renderer-owned parameter allocation shared by staging and inspection. */
-export const VOLUMETRIC_FOG_PARAMS_BYTES = 8 * 16;
+export const VOLUMETRIC_FOG_PARAMS_BYTES = (1 + MAX_VOLUMETRIC_FOG_OWNERS) * 9 * 16;
 
 export interface VolumetricFogExtent {
   readonly width: number;

package/src/volume/temporal.ts

@@ -5,6 +5,8 @@ export interface VolumeTemporalSignature {
   readonly densityGeneration: number;
   readonly width: number;
   readonly height: number;
+  /** World-owned authored-medium time; render frame identity never advances the medium. */
+  readonly worldTimeSeconds?: number;
   readonly lightKind?: 'directional' | 'point' | 'spot';
   readonly lightEntity?: number;
   readonly pointLightEntity?: number;
@@ -28,6 +30,7 @@ export type VolumeTemporalResetReason =
   | 'fog-revision'
   | 'light-revision'
   | 'density-generation'
+  | 'simulation-time'
   | 'resize'
   | 'reprojection-out-of-screen'
   | 'reprojection-depth-discontinuity';
@@ -92,6 +95,14 @@ export function resolveVolumeTemporalReset(
   if (previous.lightShadowRevision !== next.lightShadowRevision) {
     return { reset: true, reason: 'light-revision' };
   }
+  if (previous.worldTimeSeconds !== next.worldTimeSeconds) {
+    const delta = (next.worldTimeSeconds ?? NaN) - (previous.worldTimeSeconds ?? NaN);
+    // Small monotonic ticks animate the same medium. Reset only on a clock
+    // discontinuity; rejecting every tick prevents temporal reuse in live play.
+    if (!Number.isFinite(delta) || delta < 0 || delta > 0.1) {
+      return { reset: true, reason: 'simulation-time' };
+    }
+  }
   if (previous.densityGeneration !== next.densityGeneration) {
     return { reset: true, reason: 'density-generation' };
   }