@forgeax/engine-render 0.1.27 → 0.1.29

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

@@ -6,13 +6,20 @@ import type {
   RenderGraphError,
   ResolveContext,
 } from '@forgeax/engine-render-graph';
-import { RhiError, type TextureView } from '@forgeax/engine-rhi';
+import {
+  type Buffer,
+  RhiError,
+  type Texture,
+  type TextureFormat,
+  type TextureView,
+} from '@forgeax/engine-rhi';
 import { ok, type PassKind, type PassSelector, type Result } from '@forgeax/engine-types';
 import {
   GPU_TEXTURE_USAGE_COPY_SRC,
   GPU_TEXTURE_USAGE_RENDER_ATTACHMENT,
   GPU_TEXTURE_USAGE_TEXTURE_BINDING,
 } from './gpu-texture-usage';
+import { GPU_BUFFER_USAGE_COPY_DST, GPU_BUFFER_USAGE_MAP_READ } from './gpu-usage';
 import { buildPerFrameBindGroups } from './record/frame-lighting';
 import { encodeMainPass } from './record/main-pass';
 import type {
@@ -88,6 +95,136 @@ function resolvedDepthView(
   return view.value;
 }
 
+export type TypedFrameObservationDomain = 'linear-hdr' | 'linear-ldr' | 'final-srgb';
+
+/**
+ * One graph-owned copy destination for a receipt-bound color-domain capture.
+ * The buffer is created by the same encoder transaction as the source copy;
+ * callers map it only after the matching receipt fence resolves.
+ */
+export interface TypedFrameObservationCapture {
+  readonly domain: TypedFrameObservationDomain;
+  /** Native source format is required so consumers can decode BGRA surfaces truthfully. */
+  readonly format: TextureFormat;
+  readonly device: import('@forgeax/engine-rhi').RhiDevice;
+  readonly texture: Texture;
+  readonly buffer: Buffer;
+  readonly frameNumber: number;
+  readonly deviceGeneration: number;
+  readonly graphGeneration: number;
+  readonly backendId: string;
+  readonly width: number;
+  readonly height: number;
+  readonly bytesPerRow: number;
+}
+
+function observationBytesPerPixel(format: TextureFormat): number {
+  return format === 'rgba16float' ? 8 : 4;
+}
+
+function observationBytesPerRow(width: number, format: TextureFormat): number {
+  const unaligned = width * observationBytesPerPixel(format);
+  return Math.ceil(unaligned / 256) * 256;
+}
+
+function addObservationCapturePass(
+  graph: RenderGraphBuilder<RenderPipelineFrame>,
+  target: RenderPipelineTarget,
+  domain: TypedFrameObservationDomain,
+): Result<void, RenderGraphError> {
+  return graph.addCopyPass(`${domain}-observation`, {
+    accesses: [{ resource: target.view, usage: 'copy-src' }],
+    encode: ({ encoder, frame, resources }) => {
+      const texture = resources.texture(target.texture);
+      if (!texture.ok) throw texture.error;
+      const internal = frame as _InternalRenderPipelineContext;
+      // The RenderSystem frame counter is the identity used by
+      // observeCurrentFrame after this submission. The public receipt counter
+      // is intentionally separate and is only used by receipt-bound copies;
+      // using observationFrameId here makes a current source look stale by one
+      // frame to the legacy same-frame observer.
+      if (domain === 'linear-hdr') {
+        internal.frameState.currentFrameObservationSource = {
+          texture: texture.value,
+          descriptor: {
+            texture: texture.value,
+            format: target.format,
+            size: { width: frame.targetW, height: frame.targetH },
+            usage:
+              GPU_TEXTURE_USAGE_COPY_SRC |
+              GPU_TEXTURE_USAGE_RENDER_ATTACHMENT |
+              GPU_TEXTURE_USAGE_TEXTURE_BINDING,
+            sample: target.sampleCount,
+          },
+          frameId: internal.frameState.frameNumber,
+          pipelineId: 'forgeax::standard',
+          backendId: frame.runtime.device.caps.backendKind,
+        };
+      }
+      const owner = frame.runtime.observationCaptureOwner;
+      if (owner === undefined) {
+        // Standalone graph-contract tests do not assemble a renderer owner.
+        // Preserve the legacy HDR source projection without allocating an
+        // unowned readback buffer; production frames always inject the owner.
+        return;
+      }
+      // Observation is an explicit host demand, not a property of every
+      // submitted frame. The graph keeps its copy pass declaration so the
+      // committed topology remains inspectable, but ordinary production
+      // frames must not allocate a MAP_READ buffer or enqueue a copy.
+      // The source projection is different: the Renderer owns the current
+      // linear-HDR texture for every submitted frame, even when no host asked
+      // for a MAP_READ copy. Consumers such as the auto-exposure meter use
+      // this same-frame source; publishing it only on an explicit capture
+      // would make ordinary frames appear to have no observation source.
+      if (!frame.runtime.observationCaptureDomains?.includes(domain)) return;
+      const width = frame.targetW;
+      const height = frame.targetH;
+      const bytesPerRow = observationBytesPerRow(width, target.format);
+      const created = frame.runtime.device.createBuffer({
+        label: `${domain}-observation-readback`,
+        size: bytesPerRow * height,
+        usage: GPU_BUFFER_USAGE_COPY_DST | GPU_BUFFER_USAGE_MAP_READ,
+        mappedAtCreation: false,
+      });
+      if (!created.ok) throw created.error;
+      try {
+        encoder.copyTextureToBuffer(
+          { texture: texture.value, mipLevel: 0, origin: { x: 0, y: 0, z: 0 } },
+          { buffer: created.value, bytesPerRow, rowsPerImage: height },
+          { width, height, depthOrArrayLayers: 1 },
+        );
+        // Publish the graph fence through the renderer runtime before any
+        // capture is registered. The assembly consumes this renderer-issued
+        // value for the receipt; it never derives the expected fence from the
+        // first capture in an otherwise untrusted capture set.
+        frame.runtime.observationGraphGeneration = internal.frameState.graphGeneration;
+        owner.register({
+          domain,
+          format: target.format,
+          device: frame.runtime.device,
+          texture: texture.value,
+          buffer: created.value,
+          // The assembly reserves this public receipt identity before encoding.
+          // The frame-state counter is an internal record counter and is not an
+          // identity source when non-receipt frames are recorded.
+          frameNumber: frame.runtime.observationFrameId ?? internal.frameState.frameNumber,
+          deviceGeneration: frame.runtime.deviceGeneration ?? 0,
+          graphGeneration: internal.frameState.graphGeneration,
+          backendId: frame.runtime.device.caps.backendKind,
+          width,
+          height,
+          bytesPerRow,
+        });
+      } catch (cause) {
+        const destroyed = frame.runtime.device.destroyBuffer(created.value);
+        if (!destroyed.ok) throw destroyed.error;
+        throw cause;
+      }
+    },
+  });
+}
+
 function legacyResolver(
   resources: GraphResourceResolver,
   targets: Readonly<Record<string, RenderPipelineTarget>>,
@@ -131,9 +268,13 @@ export interface TypedScenePassOptions {
   readonly passKind?: PassKind | undefined;
   readonly colorTargets?: readonly RenderPipelineTarget[] | undefined;
   readonly clearColor?: readonly [number, number, number, number] | undefined;
-  readonly colorLoadOp?: GPULoadOp | undefined;
+  readonly colorLoadOp?: GPULoadOp | readonly GPULoadOp[] | undefined;
   readonly depthLoadOp?: GPULoadOp | undefined;
   readonly recordMode?: 'opaque' | 'transmission' | 'transparent' | 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. */
+  readonly includeSelector?: PassSelector | undefined;
   readonly transmissionBackdrop?: GraphTextureView | undefined;
   readonly extraAccesses?: readonly GraphAccess[] | undefined;
   readonly gpuDriven?: RenderPipelineGpuDrivenProjection | undefined;
@@ -171,7 +312,10 @@ export function addTypedScenePass(
       ...(index === 0 && options.resolve !== undefined
         ? { resolveTarget: options.resolve.view }
         : {}),
-      loadOp: options.colorLoadOp ?? 'clear',
+      loadOp:
+        (typeof options.colorLoadOp === 'string'
+          ? options.colorLoadOp
+          : options.colorLoadOp?.[index]) ?? 'clear',
       storeOp: 'store',
       clearValue: {
         r: options.clearColor?.[0] ?? 0,
@@ -228,47 +372,66 @@ export function addTypedScenePass(
         true,
         internal.standardLighting,
       );
-      if (groups.viewBindGroup !== null) {
-        options.gpuDriven?.encode(groups.viewBindGroup, pass, resources);
-      }
+      // GPU-driven indirect draws are encoded by `recordMainPass` after it
+      // has populated the frame-global material bind-group receipt. Encoding
+      // here would race that producer and either observe an empty receipt or
+      // issue the same indirect draw twice. Keep this wrapper responsible for
+      // resolving graph-owned attachments; the main-pass owner orders the
+      // material producer before the GPU consumer.
       // The context carries the frame's primary occlusion projection for
       // pipeline construction, but only the pass that owns that projection
       // may begin its query. Forwarding it to deferred/temporal scene passes
       // leaves their descriptors without an occlusionQuerySet and makes Dawn
       // reject beginOcclusionQuery in those passes.
       const activeOcclusion = options.occlusion;
-      encodeMainPass(
-        {
-          ...internal,
-          ...(activeOcclusion === undefined ? {} : { occlusion: activeOcclusion }),
-          geometryColorView: colorViews[0] ?? null,
-          geometryDepthView: depthView,
-          geometryColorResolveView: resolveView,
-          transparentColorFormat: colorTargets[0]?.format as GPUTextureFormat,
-          ...(colorTargets[1]?.format === 'rgba16float'
-            ? { reflectionFallbackColorFormat: 'rgba16float' as const }
-            : {}),
-          msaaActive: colorTargets[0]?.sampleCount === 4,
-          viewBindGroup: groups.viewBindGroup,
-          meshBindGroup: groups.meshBindGroup,
-          hdrpClusterBindGroup: groups.hdrpClusterBindGroup,
-          hdrpClusterMembershipBindGroup: groups.hdrpClusterMembershipBindGroup,
-          ...(ssao === undefined ? {} : { hdrpSsaoBlurredView: ssao }),
-        },
-        pass,
-        options.selector,
-        {
-          colorViews,
-          colorFormats: colorTargets.map((target) => target.format as GPUTextureFormat),
-          depthView,
-          passKind: options.passKind ?? 'forward',
-          ...(options.clearColor === undefined ? {} : { clearColor: options.clearColor }),
-          ...(options.recordMode === undefined ? {} : { recordMode: options.recordMode }),
-          ...(options.transmissionBackdrop === undefined
-            ? {}
-            : { transmissionBackdropView: transmissionBackdrop }),
-        },
-      );
+      const passContext: _InternalRenderPipelineContext = {
+        ...internal,
+        ...(activeOcclusion === undefined ? {} : { occlusion: activeOcclusion }),
+        geometryColorView: colorViews[0] ?? null,
+        geometryDepthView: depthView,
+        geometryColorResolveView: resolveView,
+        transparentColorFormat: colorTargets[0]?.format as GPUTextureFormat,
+        ...((options.passKind === 'deferred'
+          ? colorTargets[3]?.format
+          : colorTargets[1]?.format) === 'rgba16float'
+          ? { reflectionFallbackColorFormat: 'rgba16float' as const }
+          : {}),
+        msaaActive: colorTargets[0]?.sampleCount === 4,
+        viewBindGroup: groups.viewBindGroup,
+        meshBindGroup: groups.meshBindGroup,
+        hdrpClusterBindGroup: groups.hdrpClusterBindGroup,
+        hdrpClusterMembershipBindGroup: groups.hdrpClusterMembershipBindGroup,
+        ...(ssao === undefined ? {} : { hdrpSsaoBlurredView: ssao }),
+      };
+      encodeMainPass(passContext, pass, options.selector, {
+        colorViews,
+        colorFormats: colorTargets.map((target) => target.format as GPUTextureFormat),
+        depthView,
+        passKind: options.passKind ?? 'forward',
+        ...(options.clearColor === undefined ? {} : { clearColor: options.clearColor }),
+        ...(options.recordMode === undefined ? {} : { recordMode: options.recordMode }),
+        ...(options.excludeSelector === undefined
+          ? {}
+          : { excludeSelector: options.excludeSelector }),
+        ...(options.includeSelector === undefined
+          ? {}
+          : { includeSelector: options.includeSelector }),
+        ...(options.transmissionBackdrop === undefined
+          ? {}
+          : { transmissionBackdropView: transmissionBackdrop }),
+        ...(options.gpuDriven === undefined
+          ? {}
+          : { gpuDriven: { projection: options.gpuDriven, resources } }),
+      });
+      // encodeMainPass receives a pass-local context so attachment and
+      // bind-group overrides stay isolated. Its material UBO payload cache is
+      // frame-owned, however: return it to the original context so the next
+      // Standard scene pass can reuse the same validated slot projection.
+      // This remains frame-local and keeps the existing writeBuffer, texture
+      // readiness, UV-scale, and missing-texture diagnostic behavior intact.
+      if (passContext.materialUboPayloadCache !== undefined) {
+        internal.materialUboPayloadCache = passContext.materialUboPayloadCache;
+      }
       if (activeOcclusion !== undefined) {
         const proxyResult = activeOcclusion.encodeProxyBounds(pass);
         if (!proxyResult.ok) throw proxyResult.error;
@@ -282,30 +445,8 @@ export function addTypedFrameObservationPass(
   target: RenderPipelineTarget,
   pipelineId: 'forgeax::standard',
 ): Result<void, RenderGraphError> {
-  return graph.addCopyPass('linear-hdr-observation', {
-    accesses: [{ resource: target.view, usage: 'copy-src' }],
-    encode: ({ frame, resources }) => {
-      const internal = frame as _InternalRenderPipelineContext;
-      const texture = resources.texture(target.texture);
-      if (!texture.ok) throw texture.error;
-      internal.frameState.currentFrameObservationSource = {
-        texture: texture.value,
-        descriptor: {
-          texture: texture.value,
-          format: target.format,
-          size: { width: frame.targetW, height: frame.targetH },
-          usage:
-            GPU_TEXTURE_USAGE_COPY_SRC |
-            GPU_TEXTURE_USAGE_RENDER_ATTACHMENT |
-            GPU_TEXTURE_USAGE_TEXTURE_BINDING,
-          sample: target.sampleCount,
-        },
-        frameId: internal.frameState.frameNumber,
-        pipelineId,
-        backendId: frame.runtime.device.caps.backendKind,
-      };
-    },
-  });
+  void pipelineId;
+  return addObservationCapturePass(graph, target, 'linear-hdr');
 }
 
 /** Publish the same-frame fallback MRT as a detached, copy-readable source. */
@@ -508,6 +649,8 @@ export function addTypedSsaoPasses(
 export interface TypedFullscreenPassOptions {
   readonly name: string;
   readonly shader: string;
+  /** Optional fragment entry point override for composed fullscreen shaders. */
+  readonly fragmentEntryPoint?: string | undefined;
   readonly input: RenderPipelineTarget;
   readonly output: RenderPipelineTarget;
   readonly outputOnly?: boolean | undefined;
@@ -525,12 +668,16 @@ export interface TypedFullscreenPassOptions {
 
 export interface TypedTemporalResolveTargets {
   readonly scene: RenderPipelineTarget;
+  /** Optional producer-owned R-channel reactivity in current screen space. */
+  readonly secondaryReactivity?: GraphTextureView;
   readonly currentTemporal: RenderPipelineTarget;
   readonly depth: RenderPipelineTarget;
   readonly historyColor: RenderPipelineTarget;
   readonly historyTemporal: RenderPipelineTarget;
+  readonly historyStability: RenderPipelineTarget;
   readonly writeColor: RenderPipelineTarget;
   readonly writeTemporal: RenderPipelineTarget;
+  readonly writeStability: RenderPipelineTarget;
 }
 
 export function addTypedTemporalResolvePass(
@@ -543,8 +690,13 @@ export function addTypedTemporalResolvePass(
       { resource: targets.currentTemporal.view, usage: 'sampled-read' },
       { resource: targets.historyColor.view, usage: 'sampled-read' },
       { resource: targets.historyTemporal.view, usage: 'sampled-read' },
+      { resource: targets.historyStability.view, usage: 'sampled-read' },
+      ...(targets.secondaryReactivity === undefined
+        ? []
+        : [{ resource: targets.secondaryReactivity, usage: 'sampled-read' as const }]),
       { resource: targets.writeColor.view, usage: 'color-attachment' },
       { resource: targets.writeTemporal.view, usage: 'color-attachment' },
+      { resource: targets.writeStability.view, usage: 'color-attachment' },
     ],
     colorAttachments: [
       {
@@ -559,6 +711,12 @@ export function addTypedTemporalResolvePass(
         storeOp: 'store',
         clearValue: { r: 0, g: 0, b: 0, a: 0 },
       },
+      {
+        view: targets.writeStability.view,
+        loadOp: 'clear',
+        storeOp: 'store',
+        clearValue: { r: 0, g: 0, b: 0, a: 0 },
+      },
     ],
     encode: ({ pass, frame, resources }) => {
       const internal = frame as _InternalRenderPipelineContext;
@@ -574,11 +732,12 @@ export function addTypedTemporalResolvePass(
       const currentTemporal = resolvedView(resources, targets.currentTemporal.view);
       const historyColor = resolvedView(resources, targets.historyColor.view);
       const historyTemporal = resolvedView(resources, targets.historyTemporal.view);
+      const historyStability = resolvedView(resources, targets.historyStability.view);
       const params = getTemporalParamsBuffer(state);
-      if (params === undefined || built.sampler === null) {
+      if (params === undefined || built.sampler === null || built.temporalSampler === null) {
         throwTemporalEncodeFailure('TAA resolve has an admitted params buffer and sampler');
       }
-      const payload = new ArrayBuffer(16);
+      const payload = new ArrayBuffer(32);
       new Float32Array(payload).set([
         frame.camera.temporal?.currentJitterUv?.[0] ?? 0,
         frame.camera.temporal?.currentJitterUv?.[1] ?? 0,
@@ -586,6 +745,7 @@ export function addTypedTemporalResolvePass(
       const words = new Uint32Array(payload);
       words[2] = state.valid && (frame.camera.temporal?.historyValid ?? true) ? 1 : 0;
       words[3] = frame.camera.temporal?.temporalFrameIndex ?? 0;
+      words[4] = Number(targets.secondaryReactivity !== undefined);
       const written = frame.runtime.device.queue.writeBuffer(params, 0, new Uint8Array(payload));
       if (!written.ok)
         throwTemporalEncodeFailure('TAA resolve params upload succeeds', written.error);
@@ -598,20 +758,31 @@ export function addTypedTemporalResolvePass(
           { binding: 2, resource: { kind: 'textureView', value: historyColor } },
           { binding: 3, resource: { kind: 'sampler', value: built.sampler } },
           { binding: 4, resource: { kind: 'textureView', value: historyTemporal } },
-          { binding: 5, resource: { kind: 'sampler', value: built.sampler } },
+          { binding: 5, resource: { kind: 'sampler', value: built.temporalSampler } },
           { binding: 6, resource: { kind: 'textureView', value: currentTemporal } },
-          { binding: 7, resource: { kind: 'sampler', value: built.sampler } },
+          { binding: 7, resource: { kind: 'sampler', value: built.temporalSampler } },
           { binding: 8, resource: { kind: 'buffer', value: { buffer: params } } },
+          { binding: 9, resource: { kind: 'textureView', value: historyStability } },
+          {
+            binding: 10,
+            resource: {
+              kind: 'textureView',
+              value:
+                targets.secondaryReactivity === undefined
+                  ? currentTemporal
+                  : resolvedView(resources, targets.secondaryReactivity),
+            },
+          },
         ] as never,
       });
       if (!bindGroup.ok) {
         throwTemporalEncodeFailure('TAA resolve bind group creation succeeds', bindGroup.error);
       }
-      const pipeline = frame.runtime.getPostProcessPipeline?.(
-        'forgeax.taa-resolve',
-        built.layout,
-        targets.writeColor.format as GPUTextureFormat,
-      );
+      const pipeline = frame.runtime.getPostProcessPipeline?.('forgeax.taa-resolve', built.layout, [
+        targets.writeColor.format,
+        targets.writeTemporal.format,
+        targets.writeStability.format,
+      ] as GPUTextureFormat[]);
       if (pipeline === null || pipeline === undefined) {
         throwTemporalEncodeFailure('TAA resolve pipeline is ready before frame encoding');
       }
@@ -680,6 +851,9 @@ export function addTypedFullscreenPass(
           : {
               paramsOverride: options.paramsTransform(frame.postProcessParams.get(options.shader)),
             }),
+        ...(options.fragmentEntryPoint === undefined
+          ? {}
+          : { fragmentEntryPoint: options.fragmentEntryPoint }),
       });
     },
   });
@@ -746,11 +920,20 @@ export function addTypedOutputTransformPass(
   graph: RenderGraphBuilder<RenderPipelineFrame>,
   input: RenderPipelineTarget,
   output: RenderPipelineTarget,
-  options: { readonly outputOnly?: boolean; readonly dither?: boolean } = {},
+  options: {
+    readonly outputOnly?: boolean;
+    readonly dither?: boolean;
+    readonly name?: string | undefined;
+    readonly fragmentEntryPoint?: string | undefined;
+  } = {},
 ): Result<void, RenderGraphError> {
   const outputOnly = options.outputOnly ?? false;
-  return addTypedFullscreenPass(graph, {
-    name: outputOnly ? 'present' : 'output-transform',
+  if (options.fragmentEntryPoint === 'fs_encode_only') {
+    const ldrCapture = addObservationCapturePass(graph, input, 'linear-ldr');
+    if (!ldrCapture.ok) return ldrCapture;
+  }
+  const transformed = addTypedFullscreenPass(graph, {
+    name: options.name ?? (outputOnly ? 'present' : 'output-transform'),
     shader: STANDARD_OUTPUT_TRANSFORM_FEATURE_ID,
     input,
     output,
@@ -770,5 +953,14 @@ export function addTypedOutputTransformPass(
           },
         }
       : {}),
+    ...(options.fragmentEntryPoint === undefined
+      ? {}
+      : { fragmentEntryPoint: options.fragmentEntryPoint }),
   });
+  if (!transformed.ok) return transformed;
+  if (options.fragmentEntryPoint === 'fs_encode_only') {
+    const finalCapture = addObservationCapturePass(graph, output, 'final-srgb');
+    if (!finalCapture.ok) return finalCapture;
+  }
+  return ok(undefined);
 }