@forgeax/engine-render 0.1.32 → 0.1.34

package/src/transmission/single-layer-medium.ts

@@ -0,0 +1,322 @@
+import { type Color3, fresnelReflectance, type Uv2 } from './oracle.js';
+
+export type MediumVector3 = readonly [number, number, number];
+
+export interface SingleLayerMediumCoefficients {
+  /** Linear, inverse-metre absorption coefficients. */
+  readonly absorption: MediumVector3;
+  /** Linear, inverse-metre scattering coefficients. */
+  readonly scattering: MediumVector3;
+  readonly ior: number;
+  /** Henyey-Greenstein phase anisotropy in [-1, 1]. */
+  readonly phaseG?: number;
+}
+
+export interface SingleLayerMediumOptics {
+  readonly sigmaT: MediumVector3;
+  readonly transmittance: MediumVector3;
+  /** Uniform-medium single-scatter integral sigmaS * (1 - T) / sigmaT. */
+  readonly singleScatter: MediumVector3;
+  readonly reflectance: number;
+  readonly transmissionWeight: number;
+  readonly phase: number;
+  readonly distanceMeters: number;
+}
+
+export type SingleLayerMediumBackgroundReason = 'front' | 'shore' | 'edge' | 'sky-miss';
+
+export interface SingleLayerMediumBackgroundCandidate {
+  readonly color: Color3;
+  readonly depthMeters: number;
+  readonly uv: Uv2;
+}
+
+export interface SingleLayerMediumBackgroundInput {
+  /** No-water color and raw depth must come from the same view identity. */
+  readonly original: SingleLayerMediumBackgroundCandidate;
+  /** Refracted candidate carries color and depth as one pair. */
+  readonly refracted?: SingleLayerMediumBackgroundCandidate;
+  readonly environment?: Color3;
+  readonly surfaceDepthMeters: number;
+  readonly maxDistanceMeters: number;
+  readonly depthToleranceMeters?: number;
+}
+
+export interface SingleLayerMediumBackgroundResolution {
+  readonly source: 'refracted' | 'unrefracted' | 'environment';
+  readonly reason?: SingleLayerMediumBackgroundReason;
+  readonly candidate: SingleLayerMediumBackgroundCandidate | undefined;
+  readonly color: Color3;
+  readonly distanceMeters: number;
+}
+
+const DEFAULT_MAX_DISTANCE_METERS = 1000;
+const DEFAULT_DEPTH_TOLERANCE_METERS = 0.001;
+const DEFAULT_IOR = 1.333;
+
+const finiteOr = (value: number, fallback: number): number =>
+  Number.isFinite(value) ? value : fallback;
+
+function oneMinusExpNeg(value: number): number {
+  const x = Math.max(finiteOr(value, 0), 0);
+  if (x < 1e-3) {
+    const x2 = x * x;
+    return x * (1 - x * 0.5 + x2 / 6 - (x * x2) / 24);
+  }
+  return -Math.expm1(-x);
+}
+
+function singleScatterIntegral(sigmaS: number, sigmaT: number, distance: number): number {
+  const scattering = Math.max(finiteOr(sigmaS, 0), 0);
+  const extinction = Math.max(finiteOr(sigmaT, 0), 0);
+  const path = Math.max(finiteOr(distance, 0), 0);
+  if (extinction === 0) return scattering * path;
+  return (scattering * oneMinusExpNeg(extinction * path)) / extinction;
+}
+
+const nonNegative = (value: number): number => Math.max(finiteOr(value, 0), 0);
+
+const clamp01 = (value: number): number => Math.min(Math.max(finiteOr(value, 0), 0), 1);
+
+/** Test an endpoint against the undisturbed geometric water plane. */
+export function isBelowSingleLayerMediumPlane(input: {
+  readonly surfacePosition: MediumVector3;
+  readonly geometricNormal: MediumVector3;
+  readonly endpoint: MediumVector3;
+  readonly epsilonMeters?: number;
+}): boolean {
+  const [nx, ny, nz] = input.geometricNormal;
+  const length = Math.hypot(nx, ny, nz);
+  if (!Number.isFinite(length) || length <= 1e-8) return false;
+  const signedDistance =
+    ((input.endpoint[0] - input.surfacePosition[0]) * nx +
+      (input.endpoint[1] - input.surfacePosition[1]) * ny +
+      (input.endpoint[2] - input.surfacePosition[2]) * nz) /
+    length;
+  return Number.isFinite(signedDistance) && signedDistance <= (input.epsilonMeters ?? 0.001);
+}
+
+function vector3(input: MediumVector3 | undefined): MediumVector3 {
+  return [nonNegative(input?.[0] ?? 0), nonNegative(input?.[1] ?? 0), nonNegative(input?.[2] ?? 0)];
+}
+
+function finiteColor(input: Color3 | undefined): input is Color3 {
+  return input !== undefined && input.length === 3 && input.every(Number.isFinite);
+}
+
+function finiteUv(input: Uv2): boolean {
+  return input.length === 2 && input.every(Number.isFinite);
+}
+
+function safeDistance(value: number, maxDistance: number): number {
+  return Math.min(Math.max(finiteOr(value, 0), 0), maxDistance);
+}
+
+/**
+ * Evaluate the stable analytic portion of the Engine's single-layer model.
+ * Zero extinction uses the continuous limit and every returned component is
+ * finite, even when an authored value is NaN or infinite.
+ */
+export function integrateSingleLayerMedium(input: {
+  readonly coefficients: SingleLayerMediumCoefficients;
+  readonly distanceMeters: number;
+  readonly cosTheta: number;
+  readonly phaseCosTheta?: number;
+  /** Finite authored propagation bound; defaults to the conservative 1000 m bound. */
+  readonly maxDistanceMeters?: number;
+}): SingleLayerMediumOptics {
+  const absorption = vector3(input.coefficients.absorption);
+  const scattering = vector3(input.coefficients.scattering);
+  const sigmaT: MediumVector3 = [
+    absorption[0] + scattering[0],
+    absorption[1] + scattering[1],
+    absorption[2] + scattering[2],
+  ];
+  const maxDistanceMeters = Math.min(
+    Math.max(
+      finiteOr(input.maxDistanceMeters ?? DEFAULT_MAX_DISTANCE_METERS, DEFAULT_MAX_DISTANCE_METERS),
+      0,
+    ),
+    100000,
+  );
+  const distanceMeters = safeDistance(input.distanceMeters, maxDistanceMeters);
+  const transmittance: MediumVector3 = [
+    Number.isFinite(sigmaT[0]) && sigmaT[0] > 0 ? Math.exp(-sigmaT[0] * distanceMeters) : 1,
+    Number.isFinite(sigmaT[1]) && sigmaT[1] > 0 ? Math.exp(-sigmaT[1] * distanceMeters) : 1,
+    Number.isFinite(sigmaT[2]) && sigmaT[2] > 0 ? Math.exp(-sigmaT[2] * distanceMeters) : 1,
+  ];
+  const singleScatter: MediumVector3 = [
+    singleScatterIntegral(scattering[0], sigmaT[0], distanceMeters),
+    singleScatterIntegral(scattering[1], sigmaT[1], distanceMeters),
+    singleScatterIntegral(scattering[2], sigmaT[2], distanceMeters),
+  ];
+  const iorCandidate = finiteOr(input.coefficients.ior, DEFAULT_IOR);
+  const ior = iorCandidate >= 1 ? iorCandidate : DEFAULT_IOR;
+  const reflectance = fresnelReflectance(input.cosTheta, 1 / ior);
+  const transmissionWeight = 1 - reflectance;
+  const phaseG = Math.min(Math.max(finiteOr(input.coefficients.phaseG ?? 0, 0), -1), 1);
+  const phaseCosTheta = clamp01(input.phaseCosTheta ?? input.cosTheta);
+  const phaseDenominator = Math.max(1 + phaseG * phaseG - 2 * phaseG * phaseCosTheta, 1e-6);
+  const phase = (1 - phaseG * phaseG) / (4 * Math.PI * phaseDenominator ** 1.5);
+  return {
+    sigmaT,
+    transmittance,
+    singleScatter,
+    reflectance,
+    transmissionWeight,
+    phase: finiteOr(phase, 1 / (4 * Math.PI)),
+    distanceMeters,
+  };
+}
+
+/** Compose linear HDR terms after exactly one Fresnel allocation. */
+export function composeSingleLayerMediumColor(input: {
+  readonly optics: SingleLayerMediumOptics;
+  readonly background: Color3;
+  readonly reflection: Color3;
+  readonly foamColor?: Color3;
+  readonly coverage?: number;
+  readonly foam?: number;
+}): Color3 {
+  const coverage = clamp01(input.coverage ?? 1);
+  const foam = clamp01(input.foam ?? 0) * coverage;
+  const foamColor = finiteColor(input.foamColor) ? input.foamColor : [1, 1, 1];
+  const background = finiteColor(input.background) ? input.background : [0, 0, 0];
+  const reflection = finiteColor(input.reflection) ? input.reflection : [0, 0, 0];
+  const medium: MediumVector3 = [
+    background[0] * input.optics.transmittance[0] + input.optics.singleScatter[0],
+    background[1] * input.optics.transmittance[1] + input.optics.singleScatter[1],
+    background[2] * input.optics.transmittance[2] + input.optics.singleScatter[2],
+  ];
+  const waterWeight = input.optics.transmissionWeight * coverage * (1 - foam);
+  const reflectionWeight = input.optics.reflectance * coverage;
+  const foamWeight = foam;
+  return [
+    finiteOr(
+      reflection[0] * reflectionWeight + medium[0] * waterWeight + foamColor[0] * foamWeight,
+      0,
+    ),
+    finiteOr(
+      reflection[1] * reflectionWeight + medium[1] * waterWeight + foamColor[1] * foamWeight,
+      0,
+    ),
+    finiteOr(
+      reflection[2] * reflectionWeight + medium[2] * waterWeight + foamColor[2] * foamWeight,
+      0,
+    ),
+  ];
+}
+
+function validCandidate(
+  candidate: SingleLayerMediumBackgroundCandidate | undefined,
+  maxDistance: number,
+): candidate is SingleLayerMediumBackgroundCandidate {
+  return (
+    candidate !== undefined &&
+    finiteColor(candidate.color) &&
+    finiteUv(candidate.uv) &&
+    Number.isFinite(candidate.depthMeters) &&
+    candidate.depthMeters >= 0 &&
+    candidate.depthMeters <= maxDistance
+  );
+}
+
+/**
+ * Resolve paired color/depth input with front, shore, edge, and sky-miss
+ * reasons. Environment is a reflection/background fallback only; it is never
+ * used as a riverbed transmission sample when a valid original pair exists.
+ */
+export function resolveSingleLayerMediumBackground(
+  input: SingleLayerMediumBackgroundInput,
+): SingleLayerMediumBackgroundResolution {
+  const maxDistance = Math.max(finiteOr(input.maxDistanceMeters, DEFAULT_MAX_DISTANCE_METERS), 0);
+  const tolerance = Math.max(
+    finiteOr(
+      input.depthToleranceMeters ?? DEFAULT_DEPTH_TOLERANCE_METERS,
+      DEFAULT_DEPTH_TOLERANCE_METERS,
+    ),
+    0,
+  );
+  const surfaceDepth = finiteOr(input.surfaceDepthMeters, 0);
+  if (
+    validCandidate(input.refracted, maxDistance) &&
+    input.refracted.uv.every((coordinate) => coordinate >= 0 && coordinate <= 1)
+  ) {
+    if (input.refracted.depthMeters + tolerance < surfaceDepth) {
+      return {
+        source: 'unrefracted',
+        reason: 'front',
+        candidate: validCandidate(input.original, maxDistance) ? input.original : undefined,
+        color: validCandidate(input.original, maxDistance) ? input.original.color : [0, 0, 0],
+        distanceMeters: validCandidate(input.original, maxDistance)
+          ? Math.max(input.original.depthMeters - surfaceDepth, 0)
+          : 0,
+      };
+    }
+    return {
+      source: 'refracted',
+      candidate: input.refracted,
+      color: input.refracted.color,
+      distanceMeters: Math.max(input.refracted.depthMeters - surfaceDepth, 0),
+    };
+  }
+  if (validCandidate(input.original, maxDistance)) {
+    const reason: SingleLayerMediumBackgroundReason =
+      input.refracted === undefined
+        ? 'shore'
+        : finiteUv(input.refracted.uv) &&
+            input.refracted.uv.some((coordinate) => coordinate < 0 || coordinate > 1)
+          ? 'edge'
+          : 'shore';
+    return {
+      source: 'unrefracted',
+      reason,
+      candidate: input.original,
+      color: input.original.color,
+      distanceMeters: Math.max(input.original.depthMeters - surfaceDepth, 0),
+    };
+  }
+  if (finiteColor(input.environment)) {
+    return {
+      source: 'environment',
+      reason: 'sky-miss',
+      candidate: undefined,
+      color: input.environment,
+      distanceMeters: maxDistance,
+    };
+  }
+  return {
+    source: 'environment',
+    reason: 'sky-miss',
+    candidate: undefined,
+    color: [0, 0, 0],
+    distanceMeters: maxDistance,
+  };
+}
+
+/** Screen-space approximation of the Euclidean endpoint path, clamped to the declared maximum. */
+export function estimateSingleLayerPathLength(input: {
+  readonly surfacePosition: readonly [number, number, number];
+  readonly backgroundPosition: readonly [number, number, number] | undefined;
+  readonly maxDistanceMeters: number;
+}): { readonly distanceMeters: number; readonly valid: boolean } {
+  const maxDistance = Math.max(finiteOr(input.maxDistanceMeters, DEFAULT_MAX_DISTANCE_METERS), 0);
+  if (
+    input.surfacePosition.length !== 3 ||
+    input.backgroundPosition === undefined ||
+    input.backgroundPosition.length !== 3 ||
+    !input.surfacePosition.every(Number.isFinite) ||
+    !input.backgroundPosition.every(Number.isFinite)
+  ) {
+    return { distanceMeters: maxDistance, valid: false };
+  }
+  const distance = Math.hypot(
+    (input.backgroundPosition[0] ?? 0) - (input.surfacePosition[0] ?? 0),
+    (input.backgroundPosition[1] ?? 0) - (input.surfacePosition[1] ?? 0),
+    (input.backgroundPosition[2] ?? 0) - (input.surfacePosition[2] ?? 0),
+  );
+  return {
+    distanceMeters: Math.min(Math.max(finiteOr(distance, maxDistance), 0), maxDistance),
+    valid: Number.isFinite(distance),
+  };
+}

package/src/typed-render-graph-primitives.ts

@@ -1,10 +1,10 @@
-import type {
-  GraphAccess,
-  GraphResourceResolver,
-  GraphTextureView,
-  RenderGraphBuilder,
+import {
+  type GraphAccess,
+  type GraphResourceResolver,
+  type GraphTextureView,
+  type RenderGraphBuilder,
   RenderGraphError,
-  ResolveContext,
+  type ResolveContext,
 } from '@forgeax/engine-render-graph';
 import {
   type Buffer,
@@ -13,7 +13,7 @@ import {
   type TextureFormat,
   type TextureView,
 } from '@forgeax/engine-rhi';
-import { ok, type PassKind, type PassSelector, type Result } from '@forgeax/engine-types';
+import { err, ok, type PassKind, type PassSelector, type Result } from '@forgeax/engine-types';
 import {
   GPU_TEXTURE_USAGE_COPY_SRC,
   GPU_TEXTURE_USAGE_RENDER_ATTACHMENT,
@@ -28,10 +28,9 @@ import type {
 } from './record/render-context';
 import {
   encodeSkyboxPass,
-  recordBloomBlurHPass,
-  recordBloomBlurVPass,
-  recordBloomBrightPass,
   recordBloomCompositePass,
+  recordBloomDownsamplePass,
+  recordBloomUpsamplePass,
 } from './record/skybox-post-pass';
 import { STANDARD_OUTPUT_TRANSFORM_FEATURE_ID } from './render-contract';
 import {
@@ -39,7 +38,12 @@ import {
   recordSsaoBlurPass,
   recordSsaoCalcPass,
 } from './render-graph-primitives';
-import type { RenderPipelineFrame, RenderPipelineGpuDrivenProjection } from './render-pipeline';
+import type {
+  RenderPipelineFrame,
+  RenderPipelineGpuDrivenFilter,
+  RenderPipelineGpuDrivenProjection,
+  RenderPipelineSurfaceMediumPair,
+} from './render-pipeline';
 import { createRenderPipelineTarget, type RenderPipelineTarget } from './render-pipeline';
 import type { OcclusionFrameProjection } from './scene/visibility/occlusion-runtime';
 import {
@@ -266,6 +270,8 @@ export interface TypedScenePassOptions {
   readonly sampled?: readonly RenderPipelineTarget[] | undefined;
   readonly directionalShadow?: RenderPipelineTarget | undefined;
   readonly spotShadow?: RenderPipelineTarget | undefined;
+  /** Stable world-space cloud shadow map sampled by direct-solar receivers. */
+  readonly cloudShadow?: RenderPipelineTarget | undefined;
   readonly ssao?: RenderPipelineTarget | undefined;
   readonly selector: PassSelector;
   readonly passKind?: PassKind | undefined;
@@ -273,8 +279,24 @@ export interface TypedScenePassOptions {
   readonly clearColor?: readonly [number, number, number, number] | undefined;
   readonly colorLoadOp?: GPULoadOp | readonly GPULoadOp[] | undefined;
   readonly depthLoadOp?: GPULoadOp | undefined;
+  /** Preserve nearest transparent fragment depth for downstream medium clipping. */
+  readonly transparentDepthWrite?: boolean | undefined;
   readonly coverageOnly?: boolean | undefined;
-  readonly recordMode?: 'opaque' | 'transmission' | 'transparent' | undefined;
+  readonly recordMode?:
+    | 'opaque'
+    | 'transmission'
+    | 'transparent'
+    | 'single-layer-medium-nearest-layer'
+    | 'single-layer-medium-color'
+    | undefined;
+  /** Graph-paired Surface inputs. The raw depth status is intentionally typed. */
+  readonly surfacePair?: RenderPipelineSurfaceMediumPair | undefined;
+  /** Nearest-layer color produced by the preceding medium pass. */
+  readonly surfaceNearestLayer?: GraphTextureView | undefined;
+  /** Nearest-layer depth produced by the preceding medium pass. */
+  readonly surfaceNearestDepth?: GraphTextureView | undefined;
+  /** Restrict GPU-driven projection to the material family owned by this pass. */
+  readonly gpuDrivenFilter?: RenderPipelineGpuDrivenFilter | undefined;
   /** Exclude material/pass pairs consumed by an earlier graph lane. */
   readonly excludeSelector?: PassSelector | undefined;
   /** Require material membership in another lane without selecting its entries. */
@@ -300,9 +322,23 @@ export function addTypedScenePass(
       resource: target.view,
       usage: 'sampled-read' as const,
     })),
+    ...(options.cloudShadow === undefined
+      ? []
+      : [{ resource: options.cloudShadow.view, usage: 'sampled-read' as const }]),
     ...(options.transmissionBackdrop === undefined
       ? []
       : [{ resource: options.transmissionBackdrop, usage: 'sampled-read' as const }]),
+    ...(options.surfacePair?.rawDepth.status === 'available'
+      ? [{ resource: options.surfacePair.rawDepth.view, usage: 'sampled-read' as const }]
+      : []),
+    ...(options.recordMode === 'single-layer-medium-color' &&
+    options.surfaceNearestLayer !== undefined
+      ? [{ resource: options.surfaceNearestLayer, usage: 'sampled-read' as const }]
+      : []),
+    ...(options.recordMode === 'single-layer-medium-color' &&
+    options.surfaceNearestDepth !== undefined
+      ? [{ resource: options.surfaceNearestDepth, usage: 'sampled-read' as const }]
+      : []),
     ...(options.environment === undefined
       ? []
       : [options.environment.irradiance, options.environment.prefilter].map((resource) => ({
@@ -358,12 +394,28 @@ export function addTypedScenePass(
         options.spotShadow === undefined
           ? undefined
           : resolvedView(resources, options.spotShadow.view);
+      const cloudShadow =
+        options.cloudShadow === undefined
+          ? undefined
+          : resolvedView(resources, options.cloudShadow.view);
       const ssao =
         options.ssao === undefined ? undefined : resolvedView(resources, options.ssao.view);
       const transmissionBackdrop =
         options.transmissionBackdrop === undefined
           ? null
           : resolvedView(resources, options.transmissionBackdrop);
+      const surfaceRawDepth =
+        options.surfacePair?.rawDepth.status === 'available'
+          ? resolvedView(resources, options.surfacePair.rawDepth.view)
+          : null;
+      const surfaceNearestLayer =
+        options.surfaceNearestLayer === undefined
+          ? null
+          : resolvedView(resources, options.surfaceNearestLayer);
+      const surfaceNearestDepth =
+        options.surfaceNearestDepth === undefined
+          ? null
+          : resolvedView(resources, options.surfaceNearestDepth);
       internal.frameState.currentDirectionalShadowView = directionalShadow ?? null;
       internal.frameState.currentSpotShadowView = spotShadow ?? null;
       const groups = buildPerFrameBindGroups(
@@ -375,6 +427,7 @@ export function addTypedScenePass(
         {
           directionalShadow,
           spotShadow,
+          cloudShadow,
           projector: internal.spotLightProjector?.view ?? internal.volumetricFog?.projectorView,
           projectorSampler:
             internal.spotLightProjector?.sampler ?? internal.volumetricFog?.projectorSampler,
@@ -428,6 +481,9 @@ export function addTypedScenePass(
         passKind: options.passKind ?? 'forward',
         ...(options.clearColor === undefined ? {} : { clearColor: options.clearColor }),
         ...(options.recordMode === undefined ? {} : { recordMode: options.recordMode }),
+        ...(options.transparentDepthWrite === undefined
+          ? {}
+          : { transparentDepthWrite: options.transparentDepthWrite }),
         ...(options.coverageOnly === undefined ? {} : { coverageOnly: options.coverageOnly }),
         ...(options.excludeSelector === undefined
           ? {}
@@ -438,9 +494,20 @@ export function addTypedScenePass(
         ...(options.transmissionBackdrop === undefined
           ? {}
           : { transmissionBackdropView: transmissionBackdrop }),
+        ...(surfaceRawDepth === null ? {} : { surfaceRawDepthView: surfaceRawDepth }),
+        ...(surfaceNearestLayer === null ? {} : { surfaceNearestLayerView: surfaceNearestLayer }),
+        ...(surfaceNearestDepth === null ? {} : { surfaceNearestDepthView: surfaceNearestDepth }),
+        ...(options.recordMode === 'single-layer-medium-nearest-layer'
+          ? { fragmentEntryPoint: 'fs_nearest_layer' }
+          : options.recordMode === 'single-layer-medium-color'
+            ? { fragmentEntryPoint: 'fs_color' }
+            : {}),
         ...(options.gpuDriven === undefined
           ? {}
           : { gpuDriven: { projection: options.gpuDriven, resources } }),
+        ...(options.gpuDrivenFilter === undefined
+          ? {}
+          : { gpuDrivenFilter: options.gpuDrivenFilter }),
       });
       // encodeMainPass receives a pass-local context so attachment and
       // bind-group overrides stay isolated. Its material UBO payload cache is
@@ -502,57 +569,57 @@ export function addReflectionFallbackObservationPass(
 export interface TypedBloomTargets {
   readonly scene: RenderPipelineTarget;
   readonly composited: RenderPipelineTarget;
-  readonly bright: RenderPipelineTarget;
-  readonly blurH: RenderPipelineTarget;
-  readonly blurV: RenderPipelineTarget;
+  readonly downsample: readonly RenderPipelineTarget[];
+  readonly upsample: readonly RenderPipelineTarget[];
+  readonly levelDimensions: readonly { readonly width: number; readonly height: number }[];
 }
 
 /** The semantic Bloom pass owner; graph inspection consumes these same identities. */
 export const TYPED_BLOOM_PASS_NAMES = {
-  bright: 'bloom-bright',
-  blurH: 'bloom-blur-h',
-  blurV: 'bloom-blur-v',
+  downsample: 'bloom-downsample',
+  upsample: 'bloom-upsample',
   composite: 'bloom-composite',
 } as const;
 
+export function typedBloomLevelPassName(kind: 'downsample' | 'upsample', level: number): string {
+  return `${TYPED_BLOOM_PASS_NAMES[kind]}-${level}`;
+}
+
 export function addTypedBloomPasses(
   graph: RenderGraphBuilder<RenderPipelineFrame>,
   targets: TypedBloomTargets,
 ): Result<void, RenderGraphError> {
-  const named = {
+  const named: Record<string, RenderPipelineTarget> = {
     hdrColor: targets.scene,
     hdrComposited: targets.composited,
-    bloomBright: targets.bright,
-    bloomBlurH: targets.blurH,
-    bloomBlurV: targets.blurV,
   };
-  const descriptors = [
-    {
-      name: TYPED_BLOOM_PASS_NAMES.bright,
-      reads: [targets.scene],
-      write: targets.bright,
-      encode: recordBloomBrightPass,
-    },
-    {
-      name: TYPED_BLOOM_PASS_NAMES.blurH,
-      reads: [targets.bright],
-      write: targets.blurH,
-      encode: recordBloomBlurHPass,
-    },
-    {
-      name: TYPED_BLOOM_PASS_NAMES.blurV,
-      reads: [targets.blurH],
-      write: targets.blurV,
-      encode: recordBloomBlurVPass,
-    },
-    {
-      name: TYPED_BLOOM_PASS_NAMES.composite,
-      reads: [targets.scene, targets.blurV],
-      write: targets.composited,
-      encode: recordBloomCompositePass,
-    },
-  ] as const;
-  for (const descriptor of descriptors) {
+  targets.downsample.forEach((target, level) => {
+    named[`bloomDownsample${level}`] = target;
+  });
+  targets.upsample.forEach((target, level) => {
+    named[`bloomUpsample${level}`] = target;
+  });
+
+  const add = (
+    name: string,
+    reads: readonly RenderPipelineTarget[],
+    write: RenderPipelineTarget,
+    encode: (
+      frame: _InternalRenderPipelineContext,
+      resolve: ResolveContext,
+      pass: import('@forgeax/engine-rhi').RhiRenderPassEncoder,
+      level?: number,
+      size?: { readonly width: number; readonly height: number },
+    ) => void,
+    level?: number,
+  ): Result<void, RenderGraphError> => {
+    const descriptor = {
+      name,
+      reads,
+      write,
+      encode,
+      level,
+    };
     const added = graph.addRasterPass(descriptor.name, {
       accesses: [
         ...descriptor.reads.map((target) => ({
@@ -574,11 +641,85 @@ export function addTypedBloomPasses(
           frame as _InternalRenderPipelineContext,
           legacyResolver(resources, named),
           pass,
+          descriptor.level,
+          descriptor.level === undefined ? undefined : targets.levelDimensions[descriptor.level],
         ),
     });
+    return added.ok ? ok(undefined) : added;
+  };
+
+  for (const [level, write] of targets.downsample.entries()) {
+    const source = level === 0 ? targets.scene : targets.downsample[level - 1];
+    if (source === undefined) {
+      return err(
+        new RenderGraphError({
+          code: 'resource-resolution-failed',
+          expected: 'Bloom downsample levels form one adjacent pyramid',
+          hint: 'rebuild the Standard Bloom target declaration from one level list',
+          detail: { resourceLabel: `bloom-level-${level}` },
+        }),
+      );
+    }
+    const added = add(
+      typedBloomLevelPassName('downsample', level),
+      [source],
+      write,
+      (frame, resolve, pass, passLevel) =>
+        recordBloomDownsamplePass(
+          frame,
+          resolve,
+          pass,
+          passLevel ?? level,
+          targets.levelDimensions[passLevel ?? level],
+        ),
+      level,
+    );
     if (!added.ok) return added;
   }
-  return ok(undefined);
+  for (let level = targets.upsample.length - 1; level >= 0; level -= 1) {
+    const current = targets.downsample[level];
+    const coarse =
+      level === targets.downsample.length - 2
+        ? targets.downsample[level + 1]
+        : targets.upsample[level + 1];
+    const write = targets.upsample[level];
+    if (current === undefined || coarse === undefined || write === undefined) {
+      return err(
+        new RenderGraphError({
+          code: 'resource-resolution-failed',
+          expected: 'Bloom downsample and upsample levels form one adjacent pyramid',
+          hint: 'rebuild the Standard Bloom target declaration from one level list',
+          detail: { resourceLabel: `bloom-level-${level}` },
+        }),
+      );
+    }
+    const added = add(
+      typedBloomLevelPassName('upsample', level),
+      [current, coarse],
+      write,
+      (frame, resolve, pass, passLevel) =>
+        recordBloomUpsamplePass(frame, resolve, pass, passLevel ?? level),
+      level,
+    );
+    if (!added.ok) return added;
+  }
+  const finest = targets.upsample[0] ?? targets.downsample[0];
+  if (finest === undefined) {
+    return err(
+      new RenderGraphError({
+        code: 'resource-resolution-failed',
+        expected: 'Bloom has at least one downsample level',
+        hint: 'derive Bloom levels from a positive output extent',
+        detail: { resourceLabel: 'bloom-downsample-0' },
+      }),
+    );
+  }
+  return add(
+    TYPED_BLOOM_PASS_NAMES.composite,
+    [targets.scene, finest],
+    targets.composited,
+    (frame, resolve, pass) => recordBloomCompositePass(frame, resolve, pass),
+  );
 }
 
 export interface TypedSsaoTargets {