@forgeax/engine-render 0.1.32 → 0.1.34

package/src/pipeline-spec.ts

@@ -562,8 +562,8 @@ export interface PassKindAttachmentPolicy {
  * 4. `'point-shadow-caster'` — HDRP point-shadow caster: depth-only
  * 5. `'skybox'` — fullscreen skybox: color-only clear/store
  * 6. `'tonemap'` — HDR→LDR tonemap fullscreen: color-only clear/store
- * 7. `'bloom-bright'` / `'bloom-blur'` — bloom downsample/blur: color-only
- *    clear/store
+ * 7. `'bloom-downsample'` / `'bloom-upsample'` — multiscale Bloom pyramid:
+ *    color-only clear/store
  * 8. `'bloom-composite'` — bloom add-back: color-only load/store (NOT clear)
  * 9. `'fxaa'` — fullscreen FXAA: color-only clear/store
  * 10. `'post-process'` — generic fullscreen primitive (SSAO, render-graph
@@ -633,7 +633,7 @@ export const passKindPolicyTable: Readonly<Record<string, PassKindAttachmentPoli
     },
     defaultDepthOps: undefined,
   },
-  'bloom-bright': {
+  'bloom-downsample': {
     shape: 'color-only',
     defaultColorOps: {
       loadOp: 'clear',
@@ -642,7 +642,7 @@ export const passKindPolicyTable: Readonly<Record<string, PassKindAttachmentPoli
     },
     defaultDepthOps: undefined,
   },
-  'bloom-blur': {
+  'bloom-upsample': {
     shape: 'color-only',
     defaultColorOps: {
       loadOp: 'clear',
@@ -1220,7 +1220,7 @@ export function buildSpecConstTable(
     // has sampleCount=4. Both use empty vertexLayout (fullscreen triangle, no
     // attributes) and cullMode='none' (forward cull for fullscreen-quad passthrough).
     //
-    // Shadow-probe / fxaa / bloom 4-stage / SSAO 2-stage are lazy-build — not in
+    // Shadow-probe / fxaa / Bloom 10-pass / SSAO 2-stage are lazy-build — not in
     // SPEC_CONST_TABLE (R-D4 decision: only entries that are always-present on
     // every boot).
 

package/src/plugin.ts

@@ -1,7 +1,9 @@
 import type { Component, World } from '@forgeax/engine-ecs';
 import type { Plugin } from '@forgeax/engine-plugin';
 import { Atmosphere } from './components/atmosphere';
+import { BarrelDistortion } from './components/barrel-distortion';
 import { Camera } from './components/camera';
+import { CloudLayer } from './components/cloud-layer';
 import { DepthOfField } from './components/depth-of-field';
 import { DirectionalLight } from './components/directional-light';
 import { DynamicResolution } from './components/dynamic-resolution';
@@ -31,7 +33,9 @@ import { Visibility } from './components/visibility';
 
 const RENDER_COMPONENTS: readonly Component[] = [
   Atmosphere,
+  BarrelDistortion,
   Camera,
+  CloudLayer,
   DirectionalLight,
   DynamicResolution,
   DepthOfField,

package/src/points-lines/__tests__/points-lines.bench.ts

@@ -1,6 +1,12 @@
 import { World } from '@forgeax/engine-ecs';
 import { buildMeshAttributeMapForUvSets } from '@forgeax/engine-geometry';
 import { buildProfileModel, createProfiler } from '@forgeax/engine-profiler';
+import type { RhiRenderPassEncoder } from '@forgeax/engine-rhi';
+import { rhi } from '@forgeax/engine-rhi-null';
+import { Transform } from '@forgeax/engine-scene';
+import { err, type MeshAsset, ok } from '@forgeax/engine-types';
+import { bench, describe } from 'vitest';
+import { createRenderer as constructRenderer } from '../../assembly/factory';
 import {
   Camera,
   Lines,
@@ -10,13 +16,7 @@ import {
   PointShapeValue,
   Points,
   perspective,
-} from '@forgeax/engine-render';
-import type { RhiRenderPassEncoder } from '@forgeax/engine-rhi';
-import { rhi } from '@forgeax/engine-rhi-null';
-import { Transform } from '@forgeax/engine-scene';
-import { err, type MeshAsset, ok } from '@forgeax/engine-types';
-import { bench, describe } from 'vitest';
-import { createRenderer as constructRenderer } from '../../assembly/factory';
+} from '../../index';
 import { recordPointsLinesDraw } from '../../record/main-pass-geometry';
 import { admitPointsLines } from '../admission';
 import { PointsLinesExpansionCache } from '../expansion-cache';
@@ -186,7 +186,7 @@ function makeRealScene(
 async function createRealRoute(): Promise<RealRoute> {
   const profiler = createProfiler();
   const renderer = await constructRenderer(
-    { getContext: () => null },
+    { width: 1280, height: 720, getContext: () => null },
     { rhi, profiler },
     { shaderManifestUrl: manifestUrl() },
   );
@@ -328,6 +328,15 @@ const LINE_MESH = buildMesh('line-list');
 validateWorkload(POINT_MESH, LINE_MESH);
 const REAL_ROUTE = await createRealRoute();
 const REAL_PROFILE = await captureProfile(REAL_ROUTE, REAL_ROUTE.pointsLines);
+const recordedPointsLines = REAL_ROUTE.renderer.inspect().renderScene.pointsLines;
+if (
+  recordedPointsLines.length !== 2 ||
+  recordedPointsLines.some((entry) => entry.drawCount === 0 || entry.refusal !== undefined) ||
+  !recordedPointsLines.some((entry) => entry.pointCount === POINT_COUNT) ||
+  !recordedPointsLines.some((entry) => entry.segmentCount === SEGMENT_COUNT)
+) {
+  throw new Error('Points/Lines benchmark must draw its complete authored workload');
+}
 const DIRECT_PROFILE = await captureProfile(REAL_ROUTE, REAL_ROUTE.direct);
 
 function phaseDeltas(): Readonly<Record<string, number>> {

package/src/points-lines/__tests__/view-ubo.unit.test.ts

@@ -25,7 +25,8 @@ function camera(): CameraSnapshot {
     bloom: 'off',
     bloomThreshold: 1,
     bloomIntensity: 1,
-    bloomBlurRadius: 4,
+    bloomSoftKnee: 0.5,
+    bloomScatter: 0.7,
     clearColor: [0, 0, 0, 1],
   };
 }

package/src/prepare/prepared-graphics-resolver.ts

@@ -115,6 +115,8 @@ export interface PreparedGraphicsResolvedSnapshot {
   readonly resolveGpuBuffer?: (
     reference: import('../features/prepared-gpu-work').RenderFeatureGpuBufferRef,
   ) => RenderFeatureResolvedGpuBuffer | undefined;
+  /** Resolve a feature-owned prepared buffer by its declarative resource name. */
+  readonly resolveGpuResource?: (name: string) => RenderFeatureResolvedGpuBuffer | undefined;
 }
 
 function preparationFailure(

package/src/record/__tests__/main-pass-geometry.unit.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, it } from 'vitest';
 import type { DispatchEntry } from '../../render-system-extract';
 import {
+  authoredTransparentDepthWrite,
   geometryRenderStateForPass,
   requestsStandardTransmissionVariant,
   sameOpaqueTemporalDraw,
@@ -21,6 +22,35 @@ describe('geometry pass render state', () => {
     });
   });
 
+  it('does not force depth writes for alpha smoke while allowing authored water depth', () => {
+    expect(
+      authoredTransparentDepthWrite(true, {
+        blend: {
+          color: {
+            srcFactor: 'src-alpha',
+            dstFactor: 'one-minus-src-alpha',
+            operation: 'add',
+          },
+          alpha: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha', operation: 'add' },
+        },
+      }),
+    ).toBe(false);
+    expect(
+      authoredTransparentDepthWrite(true, {
+        depthWriteEnabled: true,
+        depthCompare: 'less-equal',
+        blend: {
+          color: {
+            srcFactor: 'src-alpha',
+            dstFactor: 'one-minus-src-alpha',
+            operation: 'add',
+          },
+          alpha: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha', operation: 'add' },
+        },
+      }),
+    ).toBe(true);
+  });
+
   it('does not rewrite the base state for colour passes', () => {
     const base = {
       cullMode: 'none' as const,

package/src/record/__tests__/sprite-material-abi.unit.test.ts

@@ -38,7 +38,7 @@ describe('sprite Standard material ABI', () => {
 
     // Sprite no longer owns a parallel material-entry builder. Preserve the
     // shared user-region/IBL layout gate; actual sampler selection is covered
-    // by the source-derived 300-frame Sprite raster smoke in both tone lanes.
+    // by the source-derived 60-frame Sprite raster smoke in both tone lanes.
     const entries: BindGroupEntry[] = [
       { binding: 0, resource: { kind: 'buffer', value: { buffer: {} as Buffer } } },
     ];

package/src/record/__tests__/temporal-payload.unit.test.ts

@@ -70,7 +70,8 @@ function camera(): CameraSnapshot {
     bloom: 'off',
     bloomThreshold: 1,
     bloomIntensity: 1,
-    bloomBlurRadius: 4,
+    bloomSoftKnee: 0.5,
+    bloomScatter: 0.7,
     clearColor: [0, 0, 0, 1],
   };
 }
@@ -160,7 +161,7 @@ describe('temporal GPU payloads', () => {
     );
 
     const payload = new Float32Array(uploads[0]?.buffer ?? new ArrayBuffer(0));
-    expect(payload.length).toBe(240);
+    expect(payload.length).toBe(256);
     expect(payload[196]).toBeCloseTo(Math.sqrt(3));
     expect(payload[212]).toBe(3);
     expect(payload[228]).toBeCloseTo(0.1);

package/src/record/__tests__/transparent-group2-selection.unit.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, it } from 'vitest';
 import { selectPipelineLayoutForVariant } from '../../assembly/factory';
+import { resolveMaterialPipelineGroup2Contract } from '../../assembly/material/pipeline-helpers';
 import { resolvePipelineGroup2Contract } from '../../pbr-pipeline';
 import { projectDeviceOwnedBindGroup } from '../frame-lighting';
 import { selectMaterialGroup2 } from '../main-pass-material';
@@ -33,6 +34,16 @@ describe('transparent material group 2 selection', () => {
     ).toBe('skin-cluster');
   });
 
+  it('keeps a Surface direct group receipt aligned with its explicit layout', () => {
+    const meshOnlySource = '@group(2) @binding(0) var<storage> mesh: array<u32>;';
+    expect(resolveMaterialPipelineGroup2Contract(meshOnlySource, 'surface-direct-pbr')).toBe(
+      'mesh',
+    );
+    expect(
+      resolveMaterialPipelineGroup2Contract(meshOnlySource, 'surface-direct-cluster-pbr'),
+    ).toBe('cluster');
+  });
+
   it('lets the resolved clustered contract select the unified group', () => {
     expect(selectMaterialGroup2(clusterGroup, meshGroup, 'cluster')).toBe(clusterGroup);
     expect(selectMaterialGroup2(clusterGroup, meshGroup, 'skin')).toBeNull();

package/src/record/__tests__/typed-frame-graph-plan.unit.test.ts

@@ -40,6 +40,7 @@ function executeCapture(overrides: CaptureOverrides = {}) {
   };
   const frameState = {
     compiledFrameGraph: graph,
+    compiledFrameGraphTopologyKey: 'synthetic-capture',
     frameNumber: 13,
     graphTargetCapture: {
       name: 'standard-output-color',

package/src/record/__tests__/view-ubo-layout.unit.test.ts

@@ -9,10 +9,10 @@ const commonWgslSrc = readFileSync(
 );
 
 describe('View UBO directional shadow ABI', () => {
-  it('keeps the 960 B payload inside the existing 1024 B slot', () => {
-    expect(viewUboSrc).toMatch(/VIEW_UNIFORM_BYTES\s*=\s*960/);
+  it('keeps the 1024 B payload inside the fixed 1024 B slot', () => {
+    expect(viewUboSrc).toMatch(/VIEW_UNIFORM_BYTES\s*=\s*1024/);
     expect(viewUboSrc).toMatch(/VIEW_UNIFORM_SLOT_STRIDE\s*=\s*1024/);
-    expect(viewUboSrc).toMatch(/VIEW_PAYLOAD_FLOATS\s*=\s*240/);
+    expect(viewUboSrc).toMatch(/VIEW_PAYLOAD_FLOATS\s*=\s*256/);
   });
 
   it('packs all four cascade metrics into the existing vec4 lanes', () => {
@@ -35,6 +35,7 @@ describe('View UBO directional shadow ABI', () => {
     const viewStruct = commonWgslSrc.match(/struct View \{[\s\S]*?\n\};/)?.[0] ?? '';
     expect(viewStruct).toMatch(/directionalShadowFilter\s*:\s*vec4<f32>/);
     expect(viewStruct).toMatch(/ssrParams\s*:\s*vec4<f32>/);
+    expect(viewStruct).toMatch(/cloudShadowProjection\s*:\s*vec4<f32>/);
     expect(viewUboSrc).toMatch(/viewPayload\[236\]\s*=\s*ssr\.maxDistance/);
     expect(viewUboSrc).toMatch(/viewPayload\[237\]\s*=\s*ssr\.thickness/);
     expect(viewUboSrc).toMatch(/viewPayload\[238\]\s*=\s*ssr\.maxRoughness/);

package/src/record/barrel-distortion-frame.ts

@@ -0,0 +1,110 @@
+import {
+  attachBarrelDistortionCameraFrame,
+  type BarrelDistortionMapping,
+  createBarrelDistortionMapping,
+} from '../barrel-distortion';
+import type { BarrelDistortionInspection } from '../inspection-types';
+import { projectBarrelDistortionInspection } from '../inspection-types';
+import type { CameraSnapshot } from '../render-contract';
+import type { RenderFrameState } from './frame-snapshot';
+import { computeProjectionMatrix, computeViewMatrix } from './helpers';
+
+function submittedCameraFrame(camera: CameraSnapshot) {
+  return {
+    projection: camera.projection,
+    far: camera.far,
+    viewMatrix: computeViewMatrix(camera),
+    projectionMatrix: computeProjectionMatrix(camera),
+  } as const;
+}
+
+function identityBarrelMapping(
+  camera: CameraSnapshot,
+  width: number,
+  height: number,
+): BarrelDistortionMapping | undefined {
+  const identity = createBarrelDistortionMapping(width, height, undefined);
+  return identity.ok
+    ? attachBarrelDistortionCameraFrame(identity.value, submittedCameraFrame(camera))
+    : undefined;
+}
+
+export function packBarrelDistortionParams(mapping: BarrelDistortionMapping): Uint8Array {
+  const params = new Uint8Array(16);
+  const view = new DataView(params.buffer);
+  view.setFloat32(0, mapping.strength, true);
+  view.setFloat32(4, mapping.centerX, true);
+  view.setFloat32(8, mapping.centerY, true);
+  view.setFloat32(12, mapping.radiusSquared, true);
+  return params;
+}
+
+function resolveRetainedBarrelMapping(
+  accepted: BarrelDistortionMapping,
+  camera: CameraSnapshot,
+  width: number,
+  height: number,
+): BarrelDistortionMapping | undefined {
+  const mapping = createBarrelDistortionMapping(width, height, {
+    strength: accepted.strength,
+    centerX: accepted.centerX,
+    centerY: accepted.centerY,
+  });
+  return mapping.ok
+    ? attachBarrelDistortionCameraFrame(mapping.value, submittedCameraFrame(camera))
+    : undefined;
+}
+
+export function resolveSubmittedBarrelMapping(
+  frameState: RenderFrameState,
+  graph: { readonly inspect: () => { readonly passes: readonly { readonly name: string }[] } },
+  camera: CameraSnapshot,
+  width: number,
+  height: number,
+): BarrelDistortionMapping | undefined {
+  const retained = frameState.barrelDistortionGraphResolution === 'retained';
+  const accepted = frameState.lastSuccessfulBarrelDistortion;
+  if (retained && accepted !== undefined) {
+    return resolveRetainedBarrelMapping(accepted, camera, width, height);
+  }
+  const hasBarrelPass = graph.inspect().passes.some((pass) => pass.name === 'barrel-distortion');
+  if (!hasBarrelPass) return identityBarrelMapping(camera, width, height);
+  const authored = camera.barrelDistortion;
+  if (!retained && authored !== undefined && authored.strength > 0) {
+    const mapping = createBarrelDistortionMapping(width, height, authored);
+    return mapping.ok
+      ? attachBarrelDistortionCameraFrame(mapping.value, submittedCameraFrame(camera))
+      : undefined;
+  }
+  return accepted === undefined
+    ? identityBarrelMapping(camera, width, height)
+    : resolveRetainedBarrelMapping(accepted, camera, width, height);
+}
+
+export function resetBarrelDistortionGraphState(state: RenderFrameState): void {
+  state.barrelDistortionPreviousGraph = null;
+  state.barrelDistortionPreviousGraphKey = null;
+  state.barrelDistortionPreviousPerFrameGraph = undefined;
+  state.barrelDistortionPreviousGraphGeneration = 0;
+  state.barrelDistortionPreviousCompiledGraphGeneration = 0;
+  state.barrelDistortionPreviousStandardLightingGraphSignature = '';
+  state.barrelDistortionCandidateGraph = null;
+}
+
+export function inspectBarrelDistortionState(
+  state: RenderFrameState,
+  deviceGeneration: number,
+): BarrelDistortionInspection {
+  const mapping = state.lastSuccessfulBarrelDistortion;
+  const graph = state.compiledFrameGraph?.inspect();
+  return projectBarrelDistortionInspection({
+    effectiveMapping: mapping,
+    frameId: state.frameNumber,
+    deviceGeneration,
+    graphGeneration: graph?.generation ?? state.graphGeneration,
+    lastKnownGood:
+      mapping !== undefined &&
+      state.compiledFrameGraph !== null &&
+      state.barrelDistortionGraphResolution === 'retained',
+  });
+}

package/src/record/dynamic-geometry-consumption.ts

@@ -1,12 +1,20 @@
 import type { World } from '@forgeax/engine-ecs';
+import type { DynamicGeometryRecordStageLane } from '../dynamic-geometry';
 import type { RenderFrameState, ValidatedRenderable } from './frame-snapshot';
 
+type RecordStageDrawLane = 'cpu' | 'gpu';
+
+interface PendingDynamicGeometryBinding {
+  readonly meshHandle: number;
+  readonly lanes: Set<RecordStageDrawLane>;
+}
+
 /** Capture the render-stage mesh binding used by the current submitted frame. */
 export function createDynamicGeometryConsumptionRecorder(
   worlds: readonly World[],
-  bindings: WeakMap<World, Map<number, number>>,
-): (entry: ValidatedRenderable) => void {
-  return (entry) => {
+  bindings: WeakMap<World, Map<number, PendingDynamicGeometryBinding>>,
+): (entry: ValidatedRenderable, lane?: RecordStageDrawLane) => void {
+  return (entry, lane = 'cpu') => {
     const renderable = entry.source;
     const world = worlds[renderable.worldId];
     if (world === undefined) return;
@@ -15,27 +23,42 @@ export function createDynamicGeometryConsumptionRecorder(
       worldBindings = new Map();
       bindings.set(world, worldBindings);
     }
-    worldBindings.set(renderable.entityKey, renderable.assetHandle);
+    const existing = worldBindings.get(renderable.entityKey);
+    if (existing === undefined || existing.meshHandle !== renderable.assetHandle) {
+      worldBindings.set(renderable.entityKey, {
+        meshHandle: renderable.assetHandle,
+        lanes: new Set([lane]),
+      });
+      return;
+    }
+    existing.lanes.add(lane);
   };
 }
 
 export interface DynamicGeometryFrameBindings {
   begin(): void;
-  onRenderableDraw(worlds: readonly World[]): (entry: ValidatedRenderable) => void;
+  onRenderableDraw(
+    worlds: readonly World[],
+  ): (entry: ValidatedRenderable, lane?: RecordStageDrawLane) => void;
   commit(submitted: boolean): void;
   isConsumed(world: World, entity: number, meshHandle: number | undefined): boolean;
+  recordStageLane(
+    world: World,
+    entity: number,
+    meshHandle: number | undefined,
+  ): DynamicGeometryRecordStageLane | undefined;
 }
 
 /** Own the submitted-frame receipt used by dynamic-geometry publication. */
 export function createDynamicGeometryFrameBindings(): DynamicGeometryFrameBindings {
-  let submitted = new WeakMap<World, ReadonlyMap<number, number>>();
-  let pending = new WeakMap<World, Map<number, number>>();
+  let submitted = new WeakMap<World, ReadonlyMap<number, PendingDynamicGeometryBinding>>();
+  let pending = new WeakMap<World, Map<number, PendingDynamicGeometryBinding>>();
   return {
     begin(): void {
       submitted = new WeakMap();
       pending = new WeakMap();
     },
-    onRenderableDraw(worlds): (entry: ValidatedRenderable) => void {
+    onRenderableDraw(worlds): (entry: ValidatedRenderable, lane?: RecordStageDrawLane) => void {
       return createDynamicGeometryConsumptionRecorder(worlds, pending);
     },
     commit(didSubmit): void {
@@ -43,7 +66,14 @@ export function createDynamicGeometryFrameBindings(): DynamicGeometryFrameBindin
     },
     isConsumed(world, entity, meshHandle): boolean {
       if (!Number.isInteger(entity) || meshHandle === undefined) return false;
-      return submitted.get(world)?.get(entity) === meshHandle;
+      return submitted.get(world)?.get(entity)?.meshHandle === meshHandle;
+    },
+    recordStageLane(world, entity, meshHandle): DynamicGeometryRecordStageLane | undefined {
+      if (!Number.isInteger(entity) || meshHandle === undefined) return undefined;
+      const binding = submitted.get(world)?.get(entity);
+      if (binding?.meshHandle !== meshHandle) return undefined;
+      if (binding.lanes.size > 1) return 'mixed';
+      return binding.lanes.has('gpu') ? 'gpu' : 'cpu';
     },
   };
 }