@forgeax/engine-render 0.1.2

package/src/record/typed-frame-graph.ts

@@ -0,0 +1,499 @@
+import {
+  type CompiledRenderGraph,
+  type GraphResourceResolver,
+  RenderGraphBuilder,
+} from '@forgeax/engine-render-graph';
+import type {
+  BindGroup,
+  BindGroupLayout,
+  CommandBuffer,
+  RenderPipeline,
+  RhiCommandEncoder,
+  Texture,
+  TextureFormat,
+} from '@forgeax/engine-rhi';
+import { RhiError } from '@forgeax/engine-rhi';
+import { err, ok } from '@forgeax/engine-types';
+import { type EnvironmentGpuBundle, isEnvironmentGpuBundle } from '../environment/gpu-bundle';
+import {
+  type EnvironmentTransactionAttempt,
+  importEnvironmentGraphTargets,
+} from '../environment/graph';
+import { TemporalUnsupportedError } from '../errors/render';
+import { directionalCascadeAtlasSize } from '../extract/directional-csm';
+import { projectRenderFeatureContributions } from '../features/render-graph-contribution';
+import type { RenderFeatureGraphTargetResolver } from '../features/render-graph-raster';
+import { addTaaResolvePass, ensureTaaResolveParamsBuffer } from '../features/taa-resolve';
+import { isRenderFeatureTargetHandle } from '../features/targets';
+import type { PreparedGpuDrivenFrame } from '../gpu-driven/production-raster';
+import type {
+  RenderPipelineFeatureTarget,
+  RenderPipelineFrame,
+  RenderPipelineTopology,
+} from '../render-pipeline';
+import { createRenderPipelineTemporalContract } from '../render-pipeline';
+import type { PipelineState, RenderSystemInternals } from '../render-system';
+import { getRenderFeatureGraphState, reportRenderFeatureGraphError } from '../render-system';
+import type { CameraSnapshot, ExtractedLights } from '../render-system-extract';
+import { resolveSurfaceFormatPair } from '../surface-format';
+import type { TemporalFrameAttempt, TemporalFrameTransaction } from '../temporal-frame-transaction';
+import { temporalViewId } from '../temporal-view';
+import { buildPerFrameBindGroups } from './frame-lighting';
+import type { RenderFrameState } from './frame-snapshot';
+import { commandBufferPlanForFrame, createShadowSubmitModeState } from './shadow-submit-mode';
+import { VIEW_UNIFORM_BYTES } from './view-ubo';
+
+function featureSignature(internals: RenderSystemInternals): string {
+  return JSON.stringify(
+    getRenderFeatureGraphState(internals).contributions.map((contribution) => [
+      contribution.featureIdentity,
+      contribution.order,
+      contribution.topologySignature,
+    ]),
+  );
+}
+
+function topologyOf(
+  internals: RenderSystemInternals,
+  frameState: RenderFrameState,
+  pipelineState: PipelineState,
+  camera: CameraSnapshot,
+  lights: ExtractedLights,
+  width: number,
+  height: number,
+  shadowMapSize: number | undefined,
+  gpuDriven: PreparedGpuDrivenFrame | undefined,
+): RenderPipelineTopology {
+  const cascadeCount = Math.max(1, Math.min(4, Math.round(lights.cascadeCount ?? 1))) as
+    | 1
+    | 2
+    | 3
+    | 4;
+  const surfaceFormats = resolveSurfaceFormatPair(
+    internals.device.caps.backendKind,
+    pipelineState.format as GPUTextureFormat,
+    pipelineState.colorAttachmentFormat as GPUTextureFormat,
+  );
+  return {
+    pipelineId: frameState.activePipelineId,
+    config: frameState.installedPipelineConfig,
+    surface: {
+      width,
+      height,
+      storageFormat: surfaceFormats.storage as TextureFormat,
+      viewFormat: surfaceFormats.view as TextureFormat,
+    },
+    camera: {
+      tonemap: camera.tonemap,
+      antialias: camera.antialias,
+      bloom: camera.bloom,
+    },
+    shadow: {
+      mapSize: shadowMapSize ?? 1024,
+      cascadeCount,
+      pointCount: Math.min(4, lights.pointShadow.length),
+      pointFaceSize: lights.pointShadow[0]?.mapSize ?? 512,
+      spotCount: Math.min(
+        4,
+        lights.spot.filter(
+          (light) => light.shadowAtlasTile >= 0 && light.lightViewProj !== undefined,
+        ).length,
+      ),
+    },
+    lane: {
+      compute: internals.device.caps.compute,
+      storageBuffer: internals.device.caps.storageBuffer,
+      multisample: internals.device.caps.backendKind !== 'wgpu-webgl2',
+      maxColorAttachments: internals.device.caps.maxColorAttachments,
+    },
+    featureTopologySignature: featureSignature(internals),
+    gpuDrivenTopologySignature: gpuDriven?.topologySignature ?? '',
+    environment: {
+      enabled:
+        frameState.environmentGeneration.active !== undefined ||
+        frameState.environmentGeneration.candidate !== undefined,
+      dirty: frameState.environmentGeneration.candidate !== undefined,
+    },
+  };
+}
+
+function environmentBundle(frameState: RenderFrameState): EnvironmentGpuBundle | undefined {
+  const record =
+    frameState.environmentGeneration.candidate ?? frameState.environmentGeneration.active;
+  return record !== undefined && isEnvironmentGpuBundle(record.handle) ? record.handle : undefined;
+}
+
+function topologyKey(topology: RenderPipelineTopology): string {
+  return JSON.stringify(topology);
+}
+
+function targetResolver(
+  targets: readonly RenderPipelineFeatureTarget[],
+): RenderFeatureGraphTargetResolver {
+  return (resource) => {
+    if (!isRenderFeatureTargetHandle(resource)) return undefined;
+    const target = targets.find(
+      (candidate) =>
+        candidate.kind === resource.kind &&
+        candidate.format === resource.format &&
+        candidate.sampleCount === resource.sampleCount,
+    );
+    return target === undefined
+      ? undefined
+      : {
+          texture: target.texture,
+          view: target.view,
+          ...(target.resolveTarget === undefined ? {} : { resolveTarget: target.resolveTarget }),
+        };
+  };
+}
+
+function resolveTargetBindings(input: {
+  readonly frame: RenderPipelineFrame;
+  readonly binding: import('../prepare/prepared-graphics-resolver').PreparedGraphicsResolvedResource & {
+    readonly kind: 'bindings';
+  };
+  readonly resources: GraphResourceResolver;
+  readonly resolveTarget: RenderFeatureGraphTargetResolver;
+}): BindGroup | undefined {
+  const descriptor = input.binding.descriptor;
+  const pipeline = input.binding.pipeline as
+    | (RenderPipeline & { getBindGroupLayout?: (index: number) => BindGroupLayout })
+    | undefined;
+  const sceneDepth = descriptor?.values.sceneDepth;
+  if (pipeline === undefined) return undefined;
+  if (sceneDepth === undefined) {
+    return (
+      buildPerFrameBindGroups(
+        input.frame.runtime as RenderSystemInternals,
+        input.frame.frameState,
+        input.frame.pipelineState,
+        true,
+        input.frame.bindGroupCounts,
+        {
+          directionalShadow: input.frame.frameState.currentDirectionalShadowView ?? undefined,
+          spotShadow: input.frame.frameState.currentSpotShadowView ?? undefined,
+        },
+      ).viewBindGroup ?? undefined
+    );
+  }
+  const target = input.resolveTarget(sceneDepth);
+  if (target === undefined) return undefined;
+  const texture = input.resources.texture(target.texture);
+  if (!texture.ok) throw texture.error;
+  const depthView = input.frame.runtime.device.createTextureView(texture.value as Texture, {
+    aspect: 'depth-only',
+    dimension: '2d',
+  });
+  if (!depthView.ok) throw depthView.error;
+  const group = descriptor?.values.group === 1 ? 1 : 0;
+  const layout = pipeline.getBindGroupLayout?.(group);
+  if (layout === undefined) return undefined;
+  const shader = descriptor?.values.shader;
+  const viewWithResource =
+    typeof shader === 'string' &&
+    (input.frame.runtime as RenderSystemInternals).getMaterialShaderBindingContract?.(shader) ===
+      'view-with-resource';
+  const entries = viewWithResource
+    ? [
+        {
+          binding: 0,
+          resource: {
+            kind: 'buffer' as const,
+            value: {
+              buffer: input.frame.pipelineState.viewUniformBuffer,
+              size: VIEW_UNIFORM_BYTES,
+            },
+          },
+        },
+        { binding: 1, resource: { kind: 'textureView' as const, value: depthView.value } },
+      ]
+    : [{ binding: 0, resource: { kind: 'textureView' as const, value: depthView.value } }];
+  const created = input.frame.runtime.device.createBindGroup({
+    layout,
+    entries,
+  });
+  if (!created.ok) throw created.error;
+  return created.value;
+}
+
+function retire(
+  frameState: RenderFrameState,
+  graph: CompiledRenderGraph<RenderPipelineFrame>,
+  historyStore?: TemporalFrameTransaction['historyStore'],
+): void {
+  frameState.retiredCompiledFrameGraphs.add(graph);
+  (historyStore?.retireGraph(graph) ?? graph.retire())
+    .finally(() => frameState.retiredCompiledFrameGraphs.delete(graph))
+    .catch(() => undefined);
+}
+
+export function ensureCompiledFrameGraph(
+  internals: RenderSystemInternals,
+  frameState: RenderFrameState,
+  pipelineState: PipelineState,
+  camera: CameraSnapshot,
+  lights: ExtractedLights,
+  width: number,
+  height: number,
+  shadowMapSize: number | undefined,
+  gpuDriven?: PreparedGpuDrivenFrame,
+  temporalTransaction?: TemporalFrameTransaction,
+): CompiledRenderGraph<RenderPipelineFrame> | null {
+  const historyStore = temporalTransaction?.historyStore;
+  const surfaceWidth = Math.max(1, width);
+  const surfaceHeight = Math.max(1, height);
+  const topology = topologyOf(
+    internals,
+    frameState,
+    pipelineState,
+    camera,
+    lights,
+    surfaceWidth,
+    surfaceHeight,
+    shadowMapSize,
+    gpuDriven,
+  );
+  const atlasSize = directionalCascadeAtlasSize(
+    topology.shadow.cascadeCount,
+    topology.shadow.mapSize,
+  );
+  pipelineState.perPassResources.shadowAtlasWidth = atlasSize.width;
+  pipelineState.perPassResources.shadowAtlasHeight = atlasSize.height;
+  const preparedHistory = historyStore?.prepare({
+    enabled: camera.antialias === 'taa',
+    width: surfaceWidth,
+    height: surfaceHeight,
+    viewId: temporalViewId(camera.worldId, camera.entityKey),
+    pipelineOwnerGeneration: frameState.installedPipelineHandle,
+    surfaceFormat: topology.surface.storageFormat,
+  });
+  if (preparedHistory !== undefined && !preparedHistory.ok) {
+    temporalTransaction?.notePipelineFailure('capability');
+    internals.errorRegistry.fire(preparedHistory.error);
+    return null;
+  }
+  const history = preparedHistory?.value;
+  const temporalEnabled = topology.camera.antialias === 'taa';
+  const key = `${topologyKey(topology)}|taa-history:${history?.ownerGeneration ?? 0}`;
+  if (frameState.compiledFrameGraph !== null && frameState.compiledFrameGraphTopologyKey === key) {
+    if (history !== undefined) historyStore?.abort(history);
+    return frameState.compiledFrameGraph;
+  }
+
+  const builder = new RenderGraphBuilder<RenderPipelineFrame>();
+  const bundle = environmentBundle(frameState);
+  let environmentTargets: import('../environment/graph').EnvironmentGraphTargets | undefined;
+  if (topology.environment?.enabled === true && bundle !== undefined) {
+    const imported = importEnvironmentGraphTargets(builder, {
+      descriptors: bundle.descriptors,
+      generation:
+        frameState.environmentGeneration.candidate?.generation ??
+        frameState.environmentGeneration.active?.generation ??
+        0,
+      resolve: (kind) =>
+        kind === 'sky' ? bundle.sky : kind === 'irradiance' ? bundle.irradiance : bundle.prefilter,
+    });
+    if (!imported.ok) {
+      if (history !== undefined) historyStore?.abort(history);
+      internals.errorRegistry.fire(imported.error);
+      return null;
+    }
+    environmentTargets = imported.value;
+  }
+  const importedHistory = history?.importResources(builder);
+  if (importedHistory !== undefined && !importedHistory.ok) {
+    if (temporalEnabled) temporalTransaction?.notePipelineFailure('pipeline');
+    if (history !== undefined) historyStore?.abort(history);
+    internals.errorRegistry.fire(importedHistory.error);
+    return null;
+  }
+  let projectedFeatures = false;
+  let projectedGpuDriven = false;
+  const temporalContract = createRenderPipelineTemporalContract({
+    enabled: temporalEnabled,
+    rgba16floatRenderable: internals.device.caps.rgba16floatRenderable,
+    maxColorAttachments: internals.device.caps.maxColorAttachments,
+    project: (targets) => {
+      const temporal = targets.sceneTemporal;
+      if (temporal === undefined) {
+        return err(
+          new TemporalUnsupportedError(
+            'temporal-attachment-missing',
+            'validated scene-temporal attachment',
+            'missing',
+          ),
+        );
+      }
+      const paramsBuffer = ensureTaaResolveParamsBuffer(
+        internals.device,
+        pipelineState.perPassResources,
+      );
+      if (!paramsBuffer.ok) return paramsBuffer;
+      return addTaaResolvePass(builder, {
+        sceneColor: targets.sceneColor,
+        sceneTemporal: temporal,
+        history: importedHistory?.value,
+        available: pipelineState.perPassResources.taaResolvePipeline !== null,
+      });
+    },
+  });
+  const built = frameState.activePipeline.build(
+    {
+      graph: builder,
+      environment:
+        topology.environment?.enabled === true
+          ? {
+              enabled: true,
+              dirty: topology.environment.dirty,
+              ...(environmentTargets === undefined ? {} : { targets: environmentTargets }),
+              ...(environmentTargets?.skyCube === undefined
+                ? {}
+                : { sampledSky: environmentTargets.skyCube }),
+            }
+          : undefined,
+      projectGpuDriven: (target) => {
+        if (projectedGpuDriven || gpuDriven === undefined) return ok(undefined);
+        projectedGpuDriven = true;
+        return gpuDriven.project(builder, target.format, target.sampleCount);
+      },
+      contributeFeatures: (targets) => {
+        if (projectedFeatures) return ok(undefined);
+        projectedFeatures = true;
+        const contributions = getRenderFeatureGraphState(internals).contributions;
+        if (contributions.length === 0) return ok(undefined);
+        const resolveTarget = targetResolver(targets);
+        const projected = projectRenderFeatureContributions(builder, contributions, {
+          resolveTarget,
+          resolveBindings: resolveTargetBindings,
+          reportError: (error) => reportRenderFeatureGraphError(internals, error),
+        });
+        return projected.ok ? ok(undefined) : projected;
+      },
+      resolveTemporal: temporalContract.resolve,
+    },
+    topology,
+  );
+  if (!built.ok) {
+    if (temporalEnabled) {
+      temporalTransaction?.notePipelineFailure(
+        built.error.code === 'taa-caps-insufficient' ? 'capability' : 'pipeline',
+        built.error.code === 'temporal-unsupported' ? 'temporal-unsupported' : 'graph-build-failed',
+      );
+    }
+    if (history !== undefined) historyStore?.abort(history);
+    internals.errorRegistry.fire(built.error);
+    return null;
+  }
+  const temporalTopology = temporalContract.finish();
+  if (!temporalTopology.ok) {
+    if (temporalEnabled) {
+      temporalTransaction?.notePipelineFailure('pipeline', 'temporal-unsupported');
+    }
+    if (history !== undefined) historyStore?.abort(history);
+    internals.errorRegistry.fire(temporalTopology.error);
+    return null;
+  }
+  const compiled = builder.compile({
+    device: internals.device,
+    surfaceSize: { width: surfaceWidth, height: surfaceHeight },
+  });
+  if (!compiled.ok) {
+    if (temporalEnabled) temporalTransaction?.notePipelineFailure('pipeline');
+    if (history !== undefined) historyStore?.abort(history);
+    internals.errorRegistry.fire(compiled.error);
+    return null;
+  }
+  const previous = frameState.compiledFrameGraph;
+  frameState.compiledFrameGraph = compiled.value;
+  frameState.compiledFrameGraphTopologyKey = key;
+  if (history !== undefined) historyStore?.commitGraph(compiled.value, history);
+  if (previous !== null) retire(frameState, previous, historyStore);
+  return compiled.value;
+}
+
+export function retireCompiledFrameGraph(
+  frameState: RenderFrameState,
+  historyStore?: TemporalFrameTransaction['historyStore'],
+): void {
+  const graph = frameState.compiledFrameGraph;
+  if (graph === null) return;
+  frameState.compiledFrameGraph = null;
+  frameState.compiledFrameGraphTopologyKey = null;
+  retire(frameState, graph, historyStore);
+}
+
+export function executeCompiledFrameGraph(
+  internals: RenderSystemInternals,
+  frameState: RenderFrameState,
+  frame: RenderPipelineFrame,
+  encoder: RhiCommandEncoder,
+  runPass?: import('@forgeax/engine-render-graph').RenderGraphPassRunner,
+  temporalFrame?: TemporalFrameAttempt,
+  environmentAttempt?: EnvironmentTransactionAttempt,
+): boolean {
+  const graph = frameState.compiledFrameGraph;
+  if (graph === null) {
+    temporalFrame?.abort('graph-unavailable');
+    environmentAttempt?.abort('execute');
+    return false;
+  }
+  const executed = graph.execute(frame, runPass);
+  if (!executed.ok) {
+    internals.errorRegistry.fire(executed.error);
+    temporalFrame?.abort('graph-execute');
+    environmentAttempt?.abort('execute');
+    return false;
+  }
+  const finished = encoder.finish();
+  if (!finished.ok) {
+    internals.membershipTiming?.markEncodeFailed(finished.error.hint);
+    internals.errorRegistry.fire(finished.error);
+    temporalFrame?.abort('encoder-finish');
+    environmentAttempt?.abort('finish');
+    return false;
+  }
+  const command: CommandBuffer = finished.value;
+  internals.membershipTiming?.markEncodeFinished();
+  internals.membershipTiming?.markSubmitStarted();
+  // RenderFrameState is created with an owner-admission state in production,
+  // but direct record-stage callers can provide an older partial state. Keep
+  // the submission boundary fail-closed to the historical independent mode
+  // instead of dereferencing an absent owner state after a successful encode.
+  const shadowSubmitModeState = frameState.shadowSubmitModeState ?? createShadowSubmitModeState();
+  frameState.shadowSubmitModeState = shadowSubmitModeState;
+  const pendingShadowCommandBuffers = frameState.pendingShadowCommandBuffers ?? [];
+  const plan = commandBufferPlanForFrame(
+    shadowSubmitModeState,
+    pendingShadowCommandBuffers,
+    command,
+  );
+  frameState.pendingShadowCommandBuffers = [];
+  if (!plan.ok) {
+    internals.membershipTiming?.markSubmitFailed();
+    internals.errorRegistry.fire(
+      new RhiError({
+        code: 'webgpu-runtime-error',
+        expected: 'renderer owner submission plan is valid',
+        hint: plan.error.hint,
+      }),
+    );
+    temporalFrame?.abort('submission-plan');
+    environmentAttempt?.abort('submit');
+    return false;
+  }
+  for (const submission of plan.value.rawSubmissions) {
+    const submitted = internals.device.queue.submit([...submission.commandBuffers]);
+    if (!submitted.ok) {
+      internals.membershipTiming?.markSubmitFailed();
+      internals.errorRegistry.fire(submitted.error);
+      temporalFrame?.abort('queue-submit');
+      environmentAttempt?.abort('submit');
+      return false;
+    }
+  }
+  internals.membershipTiming?.markSubmitted(command);
+  environmentAttempt?.publish();
+  temporalFrame?.commit();
+  return true;
+}