@forgeax/engine-render 0.1.7 → 0.1.19

package/src/record/main-pass.ts

@@ -39,8 +39,57 @@ export type MainPassOptions = {
   readonly depthView?: TextureView | null;
   readonly passKind?: PassKind;
   readonly clearColor?: readonly [number, number, number, number];
+  readonly recordMode?: 'opaque' | 'transmission' | 'transparent';
+  readonly transmissionBackdropView?: TextureView | null;
 };
 
+const TRANSMISSION_VARIANT_SET = 'TRANSMISSION_AVAILABLE=true';
+
+function isTransmissionMaterial(material: MaterialSnapshot): boolean {
+  return (
+    material.materialShaderId === 'forgeax::default-standard-pbr' &&
+    typeof material.paramSnapshot?.transmission === 'number' &&
+    material.paramSnapshot.transmission > 0
+  );
+}
+
+function matchesRecordMode(
+  material: MaterialSnapshot,
+  mode: 'opaque' | 'transmission' | 'transparent',
+): boolean {
+  const transmission = isTransmissionMaterial(material);
+  if (mode === 'transmission') return transmission;
+  if (mode === 'transparent') return material.transparent === true && !transmission;
+  return !transmission && material.transparent !== true;
+}
+
+function matchedMaterialsForRecordMode(
+  c: _InternalRenderPipelineContext,
+  matchedMaterials: ReadonlyMap<number, ReadonlySet<number>> | null,
+  mode: 'opaque' | 'transmission' | 'transparent' | undefined,
+): ReadonlyMap<number, ReadonlySet<number>> | null {
+  if (mode === undefined) return matchedMaterials;
+  const filtered = new Map<number, ReadonlySet<number>>();
+  for (const entry of c.validatedOrdered) {
+    const dispatchHandles = matchedMaterials?.get(entry.renderableIndex);
+    if (matchedMaterials !== null && dispatchHandles === undefined) continue;
+    const candidateHandles =
+      dispatchHandles ??
+      (mode === 'transmission'
+        ? []
+        : entry.source.materials.map((material) => material.materialHandle ?? 0));
+    const handles = new Set<number>();
+    for (const handle of candidateHandles) {
+      const material =
+        entry.source.materials.find((candidate) => (candidate.materialHandle ?? 0) === handle) ??
+        entry.source.material;
+      if (matchesRecordMode(material, mode)) handles.add(handle);
+    }
+    if (handles.size > 0) filtered.set(entry.renderableIndex, handles);
+  }
+  return filtered;
+}
+
 /**
  * feat-20260529-rendergraph-pass-abstraction M4 / w13b: main forward
  * (geometry) pass recording, extracted verbatim from recordFrame. Uses the
@@ -87,9 +136,20 @@ export function recordMainPass(
   // msaaActive boolean (already on the context).
   const sampleCount = msaaActive ? 4 : 1;
   const passKind = options?.passKind ?? 'forward';
+  const recordMode = options?.recordMode;
+  const transmissionBackdropView = options?.transmissionBackdropView;
+  if (recordMode === 'transmission' && transmissionBackdropView == null) {
+    throw new RhiError({
+      code: 'webgpu-runtime-error',
+      expected: 'transmissionBackdropView != null for transmission record mode',
+      hint: 'the typed Standard transmission pass must resolve its private backdrop view',
+    });
+  }
   const colorViews = options?.colorViews ?? [geometryColorView];
   const colorFormats = options?.colorFormats ?? [
-    (c.tonemapActive ? 'rgba16float' : pipelineState.colorAttachmentFormat) as GPUTextureFormat,
+    (c.tonemapActive || c.transparentColorFormat === 'rgba16float'
+      ? 'rgba16float'
+      : pipelineState.colorAttachmentFormat) as GPUTextureFormat,
   ];
   const targetDepthView = options?.depthView ?? geometryDepthView;
   const clearColor = options?.clearColor ?? clear;
@@ -198,8 +258,20 @@ export function recordMainPass(
   // feat-20260609 M2: filter entities by pass selector.
   const matchedIndices =
     selector !== undefined ? buildMatchedRenderableIndices(dispatch, selector) : null;
-  const matchedMaterials =
+  const selectorMatchedMaterials =
     selector !== undefined ? buildMatchedMaterialHandlesByRenderable(dispatch, selector) : null;
+  const matchedMaterials = matchedMaterialsForRecordMode(c, selectorMatchedMaterials, recordMode);
+  const recordContext =
+    recordMode === undefined
+      ? c
+      : {
+          ...c,
+          splitLdrSprite: recordMode === 'transparent' ? false : c.splitLdrSprite,
+          validatedOrdered: c.validatedOrdered.map((entry) => ({
+            ...entry,
+            ...(recordMode === 'transmission' ? { variantSet: TRANSMISSION_VARIANT_SET } : {}),
+          })),
+        };
 
   if (validatedOrdered.length > 0) {
     // feat-20260518-pbr-direct-lighting-mvp M5 / w22.10 (D-4 + D-9 +
@@ -363,6 +435,7 @@ export function recordMainPass(
       materialBgShared: frameState.materialBgShared,
       materialBgAssemblyCache: c.materialBgAssemblyCache,
       bindGroupCounts,
+      ...(transmissionBackdropView === undefined ? {} : { transmissionBackdropView }),
     };
     const buildPerSubmeshMaterialBg = (
       submeshMaterial: MaterialSnapshot,
@@ -551,7 +624,7 @@ export function recordMainPass(
     // M-3 / w12: vertexBuffer/indexBuffer state locals migrate to GpuBuffer.
     const recordGeometry = (): void => {
       recordGeometryDraws(
-        c,
+        recordContext,
         pass,
         matchedMaterials,
         materialSlotIndices,
@@ -581,7 +654,7 @@ export function recordMainPass(
     // already-encoded geometry pixels. Depth is loaded from the geometry
     // pass so sprite-vs-mesh occlusion (depthCompare=less-equal) is
     // preserved (plan-strategy §2 D-2 + §4 R-4).
-    if (passKind === 'forward') {
+    if (passKind === 'forward' && recordMode === undefined) {
       geometryPassEnded = recordSpritePass(
         c,
         pass,

package/src/record/mesh-ssbo.ts

@@ -365,10 +365,11 @@ export function uploadMeshSsboBatch(
   for (let i = 0; i < slotCount; i++) {
     const entry = validatedOrdered[i];
     if (entry === undefined) continue;
-    // Float32Array view into this entity's 256-byte slot (28 floats used,
-    // rest remains 0 from the fill above). Byte offset i*256 is always
+    // Float32Array view into this entity's 256-byte slot (current world,
+    // normal, previous world, and reactive metadata use 45 floats; the
+    // remaining padding stays zero). Byte offset i*256 is always
     // 4-byte aligned since MESH_PER_ENTITY_STRIDE=256 is divisible by 4.
-    const slot = new Float32Array(_meshSsboScratch.buffer, i * MESH_PER_ENTITY_STRIDE, 28);
+    const slot = new Float32Array(_meshSsboScratch.buffer, i * MESH_PER_ENTITY_STRIDE, 48);
     const isFoldHead = foldDispatchPlan?.headBuckets.has(i) === true;
     if (isFoldHead) {
       // identity mat4
@@ -380,6 +381,13 @@ export function uploadMeshSsboBatch(
       slot[16] = 1;
       slot[20] = 1;
       slot[24] = 1;
+      // Fold heads use the instance storage path; keep the mesh temporal
+      // fields deterministic for shader variants that still read the slot.
+      slot[28] = 1;
+      slot[33] = 1;
+      slot[38] = 1;
+      slot[43] = 1;
+      slot[44] = 1;
     } else {
       const worldFromLocal = entry.source.transform.world;
       for (let k = 0; k < 16; k++) slot[k] = worldFromLocal[k] ?? 0;
@@ -393,6 +401,17 @@ export function uploadMeshSsboBatch(
       slot[24] = normal[6] ?? 0;
       slot[25] = normal[7] ?? 0;
       slot[26] = normal[8] ?? 0;
+      const previousWorld = entry.source.temporal?.previousTransform.world ?? worldFromLocal;
+      for (let k = 0; k < 16; k++) slot[28 + k] = previousWorld[k] ?? 0;
+      const reactiveMaterial = entry.source.materials.some(
+        (material) =>
+          material.transparent === true ||
+          material.materialShaderId === 'forgeax::sprite' ||
+          material.materialShaderId === 'forgeax::sprite-lit' ||
+          (material.materialShaderId !== undefined &&
+            !material.materialShaderId.startsWith('forgeax::')),
+      );
+      slot[44] = entry.source.temporal?.reactive === true || reactiveMaterial ? 1 : 0;
     }
   }
   if (neededBytes > 0) {

package/src/record/render-context.ts

@@ -2,6 +2,7 @@ import type { AssetRegistry, DynamicTextureStore } from '@forgeax/engine-assets-
 import type { World } from '@forgeax/engine-ecs';
 import type { VertexLayoutProjection } from '@forgeax/engine-geometry';
 import type { Profiler } from '@forgeax/engine-profiler';
+import type { CompiledRenderGraphInfo } from '@forgeax/engine-render-graph';
 import type {
   BindGroup,
   BindGroupLayout,
@@ -11,13 +12,13 @@ import type {
   Result,
   RhiCanvasContext,
   RhiDevice,
-  RhiError,
   RenderPipeline as RhiRenderPipeline,
   Sampler,
   Texture,
   TextureFormat,
   TextureView,
 } from '@forgeax/engine-rhi';
+import { err, ok, RhiError } from '@forgeax/engine-rhi';
 import type { MaterialRuntimeArtifact } from '@forgeax/engine-shader';
 import type {
   MaterialRenderState,
@@ -31,12 +32,14 @@ import type { DeviceScope } from '../device/device-scope';
 import type { MeshGpuHandles } from '../device/gpu-residency';
 import type { EngineMetrics } from '../engine-metrics';
 import type { RenderFeatureHost } from '../features/host';
+import type { RenderFeatureShaderModuleMode } from '../features/types';
 import {
   GPU_TEXTURE_USAGE_COPY_SRC,
   GPU_TEXTURE_USAGE_RENDER_ATTACHMENT,
   GPU_TEXTURE_USAGE_TEXTURE_BINDING,
 } from '../gpu-texture-usage';
 import type { SkylightFallback } from '../ibl/skylight-bind-group';
+import type { BloomInspection } from '../inspection-types';
 import type { HealthListenerRegistry, RhiErrorListenerRegistry } from '../lifecycle';
 import type { StandardProfile } from '../pipeline/standard-profile';
 import type { PipelineBuilderShaderModuleFactory } from '../pipeline-builder';
@@ -64,6 +67,7 @@ import type {
 import type { SkinPaletteAllocator } from '../systems/skin-palette-allocator';
 import type {
   BindGroupCounts,
+  BloomFrameReceipts,
   DispatchCounts,
   MaterialBgAssemblyCacheEntry,
   RenderFrameState,
@@ -94,6 +98,8 @@ export interface RenderSystemRuntime {
     depthFormatOverride?: GPUTextureFormat | null,
     vertexLayout?: string,
     vertexLayoutProjection?: VertexLayoutProjection,
+    shaderModuleMode?: RenderFeatureShaderModuleMode,
+    layoutKindOverride?: 'pbr' | 'pbr-skin',
   ) => RhiRenderPipeline | null;
   readonly getMaterialShaderBindingContract?: (
     materialShaderId: string,
@@ -110,6 +116,8 @@ export interface RenderSystemRuntime {
     bgl: BindGroupLayout,
     colorFormat: GPUTextureFormat,
   ) => RhiRenderPipeline | null;
+  readonly clearPostProcessPipelineCache?: (id: string) => void;
+  readonly invalidateShaderModule?: (label: string) => void;
   readonly dynamicTextureStore?: DynamicTextureStore | undefined;
 }
 
@@ -152,18 +160,27 @@ export interface PerPassResources {
   readonly skyboxBindGroupLayout: BindGroupLayout | null;
   readonly skyboxSampler: Sampler | null;
   readonly skyboxRotationBuffer: Buffer | null;
-  readonly bloomBrightPipeline: RhiRenderPipeline | null;
-  readonly bloomBlurHPipeline: RhiRenderPipeline | null;
-  readonly bloomBlurVPipeline: RhiRenderPipeline | null;
-  readonly bloomCompositePipeline: RhiRenderPipeline | null;
-  readonly bloomBrightBindGroupLayout: BindGroupLayout | null;
-  readonly bloomBlurBindGroupLayout: BindGroupLayout | null;
-  readonly bloomCompositeBindGroupLayout: BindGroupLayout | null;
-  readonly bloomSampler: Sampler | null;
-  readonly bloomBrightParamsBuffer: Buffer | null;
-  readonly bloomBlurHParamsBuffer: Buffer | null;
-  readonly bloomBlurVParamsBuffer: Buffer | null;
-  readonly bloomCompositeParamsBuffer: Buffer | null;
+  bloomBrightPipeline: RhiRenderPipeline | null;
+  bloomBlurHPipeline: RhiRenderPipeline | null;
+  bloomBlurVPipeline: RhiRenderPipeline | null;
+  bloomCompositePipeline: RhiRenderPipeline | null;
+  bloomBrightBindGroupLayout: BindGroupLayout | null;
+  bloomBlurBindGroupLayout: BindGroupLayout | null;
+  bloomCompositeBindGroupLayout: BindGroupLayout | null;
+  bloomSampler: Sampler | null;
+  bloomBrightParamsBuffer: Buffer | null;
+  bloomBlurHParamsBuffer: Buffer | null;
+  bloomBlurVParamsBuffer: Buffer | null;
+  bloomCompositeParamsBuffer: Buffer | null;
+  ensureBloomResources?: () => void;
+  getBloomResources?: () => BloomPersistentBundle | null;
+  commitBloomResources?: () => void;
+  commitBloomFrameReceipts?: (receipts: BloomFrameReceipts) => void;
+  discardBloomResources?: () => void;
+  retireBloomResources?: (completion: Promise<unknown>) => void;
+  /** Drain candidate, active, and fence-retiring Bloom generations. */
+  drainBloomResources?: () => void;
+  inspectBloomResources?: (graph?: CompiledRenderGraphInfo) => BloomInspection;
   bloomBrightTexture: Texture | null;
   bloomBrightView: TextureView | null;
   bloomBrightWidth: number;
@@ -194,10 +211,30 @@ export interface PerPassResources {
   } | null;
 }
 
+/** Renderer-private Bloom bundle selected for one record transaction. */
+export interface BloomPersistentBundle {
+  readonly scope: DeviceScope;
+  readonly generation: number;
+  readonly bloomBrightPipeline: RhiRenderPipeline | null;
+  readonly bloomBlurHPipeline: RhiRenderPipeline | null;
+  readonly bloomBlurVPipeline: RhiRenderPipeline | null;
+  readonly bloomCompositePipeline: RhiRenderPipeline | null;
+  readonly bloomBrightBindGroupLayout: BindGroupLayout | null;
+  readonly bloomBlurBindGroupLayout: BindGroupLayout | null;
+  readonly bloomCompositeBindGroupLayout: BindGroupLayout | null;
+  readonly bloomSampler: Sampler | null;
+  readonly bloomBrightParamsBuffer: Buffer | null;
+  readonly bloomBlurHParamsBuffer: Buffer | null;
+  readonly bloomBlurVParamsBuffer: Buffer | null;
+  readonly bloomCompositeParamsBuffer: Buffer | null;
+}
+
 export interface PipelineState {
   readonly meshes: ReadonlyMap<number, MeshGpuHandles>;
   readonly format: TextureFormat;
   readonly colorAttachmentFormat: TextureFormat;
+  /** Surface route committed by configureSurface for inspection provenance. */
+  readonly surfaceProfile?: 'dual-view' | 'raw-only';
   readonly viewBindGroupLayout: BindGroupLayout;
   readonly materialBindGroupLayout: BindGroupLayout;
   readonly meshBindGroupLayout: BindGroupLayout;
@@ -240,6 +277,8 @@ export interface RenderSystemInternals extends RenderSystemRuntime {
   readonly standardPipeline: RenderFrameState['activePipeline'];
   readonly featureHost?: RenderFeatureHost | undefined;
   readonly shaderModuleFactory?: PipelineBuilderShaderModuleFactory;
+  /** Optional handle-first factory for feature-owned generated shader programs. */
+  readonly immediateShaderModuleFactory?: PipelineBuilderShaderModuleFactory;
   readonly profiler?: Profiler | undefined;
   readonly context: RhiCanvasContext | null;
   readonly getPipelineState: () => PipelineState | null;
@@ -269,6 +308,7 @@ export interface _StandardForwardSceneView {
   readonly assets: AssetRegistry;
   readonly store: import('../device/gpu-residency').GpuResidencyCache;
   readonly pipelineState: PipelineState;
+  readonly bloomResources?: BloomPersistentBundle | null;
   readonly runtime: RenderSystemRuntime;
   readonly validated: readonly ValidatedRenderable[];
   readonly validatedOrdered: readonly ValidatedRenderable[];
@@ -314,7 +354,7 @@ export type _InternalRenderPipelineContext = RenderPipelineContext & _StandardFo
 
 export type RecordProfileRunner = <T>(phase: RenderRecordPhase, action: () => T) => T;
 
-export const STANDARD_PBR_UBO_SIZE = 304;
+export const STANDARD_PBR_UBO_SIZE = 384;
 export const MATERIAL_PER_ENTITY_STRIDE = 512;
 
 export type SwapChainFormatPair = {
@@ -323,14 +363,88 @@ export type SwapChainFormatPair = {
   readonly fallbackReason?: 'preferred-canvas-format-missing';
 };
 
+/** Internal closed projection of the concrete surface route. */
+export type SurfaceProfile =
+  | {
+      readonly kind: 'dual-view';
+      readonly storageFormat: GPUTextureFormat;
+      readonly viewFormat: GPUTextureFormat;
+      readonly viewFormats: readonly [GPUTextureFormat];
+      readonly hasDisplayEndpoint: true;
+    }
+  | {
+      readonly kind: 'raw-only';
+      readonly storageFormat: GPUTextureFormat;
+      readonly viewFormat: GPUTextureFormat;
+      readonly viewFormats: readonly [];
+      readonly hasDisplayEndpoint: false;
+    };
+
+export interface SurfaceCapabilityFacts {
+  /** Concrete wgpu downlevel `SURFACE_VIEW_FORMATS` flag. */
+  readonly surfaceViewFormats: boolean;
+  readonly rawAttachment: boolean;
+  readonly floatRenderAttachment: boolean;
+}
+
+export function resolveSurfaceProfile(
+  storageFormat: GPUTextureFormat,
+  viewFormat: GPUTextureFormat,
+  facts: SurfaceCapabilityFacts,
+): Result<SurfaceProfile, RhiError> {
+  if (facts.surfaceViewFormats) {
+    return ok({
+      kind: 'dual-view',
+      storageFormat,
+      viewFormat,
+      viewFormats: [viewFormat],
+      hasDisplayEndpoint: true,
+    });
+  }
+  if (!facts.rawAttachment || !facts.floatRenderAttachment) {
+    return err(
+      new RhiError({
+        code: 'webgpu-runtime-error',
+        expected: 'raw surface attachment and rgba16float render attachment capabilities',
+        hint: 'surface profile cannot establish a raw-only linear output route',
+        detail: {
+          error: {
+            code: 'surface-raw-endpoint-failed',
+            message: 'raw-only surface capabilities are incomplete',
+          },
+        },
+      }),
+    );
+  }
+  return ok({
+    kind: 'raw-only',
+    storageFormat,
+    viewFormat: storageFormat,
+    viewFormats: [],
+    hasDisplayEndpoint: false,
+  });
+}
+
 export type SurfaceBackendKind = 'webgpu' | 'wgpu-native' | 'wgpu-webgl2' | 'null';
 
 export function resolveSurfaceFormatPair(
-  backendKind: SurfaceBackendKind,
+  _backendKind: SurfaceBackendKind,
   storage: GPUTextureFormat,
   view: GPUTextureFormat,
 ): SwapChainFormatPair {
-  return backendKind === 'wgpu-webgl2' ? { storage: view, view } : { storage, view };
+  return { storage, view };
+}
+
+function surfaceCapabilityFacts(
+  device: RhiDevice,
+  storageFormat: GPUTextureFormat,
+): SurfaceCapabilityFacts {
+  const internal = device as unknown as { readonly surfaceViewFormats?: boolean };
+  return {
+    surfaceViewFormats: internal.surfaceViewFormats ?? device.caps?.backendKind !== 'wgpu-webgl2',
+    rawAttachment: storageFormat === 'rgba8unorm' || storageFormat === 'bgra8unorm',
+    floatRenderAttachment: device.caps?.rgba16floatRenderable ?? true,
+  };
 }
 
 export function configureSurface(
@@ -346,8 +460,20 @@ export function configureSurface(
     format as GPUTextureFormat,
     colorAttachmentFormat as GPUTextureFormat,
   );
-  const supportsTextureBinding = device.caps?.storageBuffer ?? true;
-  return context.configure({
+  const profile = resolveSurfaceProfile(
+    surfaceFormats.storage,
+    surfaceFormats.view,
+    surfaceCapabilityFacts(device, surfaceFormats.storage),
+  );
+  if (!profile.ok) return profile;
+  // WebGL2 surface pixels are proven by the compositor fixture, so it has no
+  // surface consumer for optional TEXTURE_BINDING/COPY_SRC usage. The concrete
+  // wgpu surface derives supported usages from SurfaceCapabilities and rejects
+  // unsupported requests; this path requests only the guaranteed attachment
+  // usage. Raw-only deliberately has no alternate view.
+  const supportsTextureBinding =
+    backendKind !== 'wgpu-webgl2' && (device.caps?.storageBuffer ?? true);
+  const configured = context.configure({
     device,
     format: surfaceFormats.storage,
     alphaMode: isWebGl2 ? 'opaque' : 'premultiplied',
@@ -355,12 +481,49 @@ export function configureSurface(
       GPU_TEXTURE_USAGE_RENDER_ATTACHMENT |
       (supportsTextureBinding ? GPU_TEXTURE_USAGE_TEXTURE_BINDING : 0) |
       (isWebGl2 ? 0 : GPU_TEXTURE_USAGE_COPY_SRC),
-    ...(!isWebGl2 ? { viewFormats: [surfaceFormats.view] } : {}),
+    viewFormats: [...profile.value.viewFormats],
   });
+  if (!configured.ok) return configured;
+  if (
+    isWebGl2 &&
+    (context.presentationProof === undefined ||
+      !context.presentationProof.descriptor ||
+      !context.presentationProof.acquisition ||
+      !context.presentationProof.validation ||
+      typeof context.presentationProof.surfaceIdentity !== 'string' ||
+      context.presentationProof.surfaceIdentity.length === 0 ||
+      context.presentationProof.requested === undefined ||
+      context.presentationProof.validated === undefined ||
+      JSON.stringify(context.presentationProof.requested) !==
+        JSON.stringify(context.presentationProof.validated))
+  ) {
+    return err(
+      new RhiError({
+        code: 'webgpu-runtime-error',
+        expected: 'WebGL2 surface storage has descriptor, acquisition, and validation proof',
+        hint: 'run the concrete presentation probe and retain the last-known-good graph when proof is absent',
+        detail: {
+          error: {
+            code: 'surface-raw-endpoint-failed',
+            message: 'surface storage raw endpoint proof is incomplete',
+          },
+        },
+      }),
+    );
+  }
+  return ok(undefined);
 }
 
-export function selectSwapChainFormat(storageBufferCapable: boolean): SwapChainFormatPair {
-  if (!storageBufferCapable) return { storage: 'rgba8unorm', view: 'rgba8unorm-srgb' };
+export function selectSwapChainFormat(
+  storageBufferCapable: boolean,
+  surfaceViewFormats = true,
+): SwapChainFormatPair {
+  if (!storageBufferCapable) {
+    return {
+      storage: 'rgba8unorm',
+      view: surfaceViewFormats ? 'rgba8unorm-srgb' : 'rgba8unorm',
+    };
+  }
   const nav = (
     globalThis as { navigator?: { gpu?: { getPreferredCanvasFormat?: () => GPUTextureFormat } } }
   ).navigator;
@@ -374,11 +537,14 @@ export function selectSwapChainFormat(storageBufferCapable: boolean): SwapChainF
         : storage === 'bgra8unorm'
           ? 'bgra8unorm-srgb'
           : storage;
-    return { storage, view };
+    return {
+      storage,
+      view: surfaceViewFormats ? view : storage,
+    };
   }
   return {
     storage: 'rgba8unorm',
-    view: 'rgba8unorm-srgb',
+    view: surfaceViewFormats ? 'rgba8unorm-srgb' : 'rgba8unorm',
     fallbackReason: 'preferred-canvas-format-missing',
   };
 }