@forgeax/engine-render 0.1.2

package/src/features/taa-resolve.ts

@@ -0,0 +1,244 @@
+import type { RenderGraphBuilder } from '@forgeax/engine-render-graph';
+import type {
+  BindGroup,
+  BindGroupLayout,
+  Buffer,
+  RenderPipeline,
+  RhiDevice,
+  RhiError,
+  Sampler,
+  ShaderModule,
+  TextureView,
+} from '@forgeax/engine-rhi';
+import { err, ok, type Result } from '@forgeax/engine-types';
+import { TemporalUnsupportedError } from '../errors/render';
+import { GPU_SHADER_STAGE_FRAGMENT } from '../gpu-stage';
+import { GPU_BUFFER_USAGE_COPY_DST, GPU_BUFFER_USAGE_UNIFORM } from '../gpu-usage';
+import type {
+  RenderPipelineBuildError,
+  RenderPipelineFeatureTarget,
+  RenderPipelineFrame,
+  RenderPipelineTemporalOutput,
+} from '../render-pipeline';
+import type { TaaHistoryGraphResources } from '../taa-history-store';
+
+export interface TaaResolvePipelineResources {
+  readonly pipeline: RenderPipeline;
+  readonly bindGroupLayout: BindGroupLayout;
+  readonly sampler: Sampler;
+}
+
+export function createTaaResolvePipelineResources(
+  device: RhiDevice,
+  module: ShaderModule,
+): Result<TaaResolvePipelineResources, RhiError> {
+  const bindGroupLayout = device.createBindGroupLayout({
+    label: 'taa-resolve-bgl',
+    entries: [
+      ...[0, 1, 2, 3].map((binding) => ({
+        binding,
+        visibility: GPU_SHADER_STAGE_FRAGMENT,
+        texture: { sampleType: 'float' as const, viewDimension: '2d' as const },
+      })),
+      {
+        binding: 4,
+        visibility: GPU_SHADER_STAGE_FRAGMENT,
+        sampler: { type: 'filtering' },
+      },
+      {
+        binding: 5,
+        visibility: GPU_SHADER_STAGE_FRAGMENT,
+        buffer: { type: 'uniform' },
+      },
+    ],
+  });
+  if (!bindGroupLayout.ok) return bindGroupLayout;
+  const pipelineLayout = device.createPipelineLayout({
+    label: 'taa-resolve-layout',
+    bindGroupLayouts: [bindGroupLayout.value],
+  });
+  if (!pipelineLayout.ok) return pipelineLayout;
+  const pipeline = device.createRenderPipeline({
+    label: 'taa-resolve',
+    layout: pipelineLayout.value as unknown as GPUPipelineLayout,
+    vertex: {
+      module: module as unknown as GPUShaderModule,
+      entryPoint: 'vs_taa_resolve',
+      buffers: [],
+    },
+    fragment: {
+      module: module as unknown as GPUShaderModule,
+      entryPoint: 'fs_taa_resolve',
+      targets: [{ format: 'rgba16float' }, { format: 'rgba16float' }],
+    },
+    primitive: { topology: 'triangle-list', cullMode: 'none' },
+  });
+  if (!pipeline.ok) return pipeline;
+  const sampler = device.createSampler({
+    label: 'taa-resolve-sampler',
+    magFilter: 'linear',
+    minFilter: 'linear',
+    mipmapFilter: 'nearest',
+    addressModeU: 'clamp-to-edge',
+    addressModeV: 'clamp-to-edge',
+  });
+  if (!sampler.ok) return sampler;
+  return ok({
+    pipeline: pipeline.value,
+    bindGroupLayout: bindGroupLayout.value,
+    sampler: sampler.value,
+  });
+}
+
+export function ensureTaaResolveParamsBuffer(
+  device: RhiDevice,
+  resources: { taaResolveParamsBuffer: Buffer | null },
+): Result<Buffer, RhiError> {
+  if (resources.taaResolveParamsBuffer !== null) return ok(resources.taaResolveParamsBuffer);
+  const created = device.createBuffer({
+    label: 'taa-resolve-params',
+    size: 16,
+    usage: GPU_BUFFER_USAGE_UNIFORM | GPU_BUFFER_USAGE_COPY_DST,
+    mappedAtCreation: false,
+  });
+  if (!created.ok) return created;
+  resources.taaResolveParamsBuffer = created.value;
+  return created;
+}
+
+function resolvedView(
+  resources: import('@forgeax/engine-render-graph').GraphResourceResolver,
+  view: import('@forgeax/engine-render-graph').GraphTextureView,
+): TextureView {
+  const resolved = resources.textureView(view);
+  if (!resolved.ok) throw resolved.error;
+  return resolved.value;
+}
+
+function createResolveBindGroup(
+  frame: RenderPipelineFrame,
+  views: readonly [TextureView, TextureView, TextureView, TextureView],
+): BindGroup {
+  const pass = frame.pipelineState.perPassResources;
+  const layout = pass.taaResolveBindGroupLayout;
+  const sampler = pass.taaResolveSampler;
+  const paramsBuffer = pass.taaResolveParamsBuffer;
+  if (layout === null || sampler === null || paramsBuffer === null) {
+    throw new TemporalUnsupportedError(
+      'resolve-resources-missing',
+      'renderer-owned TAA resolve resources',
+      'missing',
+    );
+  }
+  const created = frame.runtime.device.createBindGroup({
+    label: 'taa-resolve-bind-group',
+    layout,
+    entries: [
+      { binding: 0, resource: { kind: 'textureView', value: views[0] } },
+      { binding: 1, resource: { kind: 'textureView', value: views[1] } },
+      { binding: 2, resource: { kind: 'textureView', value: views[2] } },
+      { binding: 3, resource: { kind: 'textureView', value: views[3] } },
+      { binding: 4, resource: { kind: 'sampler', value: sampler } },
+      { binding: 5, resource: { kind: 'buffer', value: { buffer: paramsBuffer } } },
+    ],
+  });
+  if (!created.ok) throw created.error;
+  return created.value;
+}
+
+function writeResolveParams(frame: RenderPipelineFrame): void {
+  const temporalFrame = (
+    frame as RenderPipelineFrame & {
+      readonly temporalFrame?: import('../temporal-frame-transaction').TemporalFrameAttempt;
+    }
+  ).temporalFrame;
+  const view = temporalFrame?.view;
+  const buffer = frame.pipelineState.perPassResources.taaResolveParamsBuffer;
+  if (temporalFrame === undefined || view === undefined || buffer === null) {
+    throw new TemporalUnsupportedError(
+      'resolve-frame-missing',
+      'active TAA temporal view and params buffer',
+      'missing',
+    );
+  }
+  const bytes = new ArrayBuffer(16);
+  const floats = new Float32Array(bytes);
+  const integers = new Uint32Array(bytes);
+  floats[0] = view.currentJitterUv[0];
+  floats[1] = view.currentJitterUv[1];
+  integers[2] = temporalFrame.historyValid ? 1 : 0;
+  integers[3] = view.temporalFrameIndex;
+  const written = frame.runtime.device.queue.writeBuffer(buffer, 0, bytes);
+  if (!written.ok) throw written.error;
+}
+
+export function addTaaResolvePass(
+  graph: RenderGraphBuilder<RenderPipelineFrame>,
+  input: {
+    readonly sceneColor: RenderPipelineFeatureTarget;
+    readonly sceneTemporal: RenderPipelineFeatureTarget;
+    readonly history: TaaHistoryGraphResources | undefined;
+    readonly available: boolean;
+  },
+): Result<RenderPipelineTemporalOutput, RenderPipelineBuildError> {
+  if (!input.available || input.history === undefined) {
+    return err(
+      new TemporalUnsupportedError(
+        'resolve-resources-missing',
+        'renderer-owned TAA resolve resources and history generation',
+        'missing',
+      ),
+    );
+  }
+  const history = input.history;
+  const added = graph.addRasterPass('taa-resolve', {
+    accesses: [
+      { resource: input.sceneColor.view, usage: 'sampled-read' },
+      { resource: input.sceneTemporal.view, usage: 'sampled-read' },
+      { resource: history.colorRead.view, usage: 'sampled-read' },
+      { resource: history.temporalRead.view, usage: 'sampled-read' },
+      { resource: history.colorWrite.view, usage: 'color-attachment' },
+      { resource: history.temporalWrite.view, usage: 'color-attachment' },
+    ],
+    colorAttachments: [
+      { view: history.colorWrite.view, loadOp: 'clear', storeOp: 'store' },
+      {
+        view: history.temporalWrite.view,
+        loadOp: 'clear',
+        storeOp: 'store',
+        clearValue: { r: 0, g: 0, b: -1, a: 1 },
+      },
+    ],
+    encode: ({ pass, frame, resources }) => {
+      const pipeline = frame.pipelineState.perPassResources.taaResolvePipeline;
+      if (pipeline === null) {
+        throw new TemporalUnsupportedError(
+          'resolve-resources-missing',
+          'compiled renderer-owned TAA resolve pipeline',
+          'missing',
+        );
+      }
+      writeResolveParams(frame);
+      const bindGroup = createResolveBindGroup(frame, [
+        resolvedView(resources, input.sceneColor.view),
+        resolvedView(resources, input.sceneTemporal.view),
+        resolvedView(resources, history.colorRead.view),
+        resolvedView(resources, history.temporalRead.view),
+      ]);
+      pass.setPipeline(pipeline);
+      pass.setBindGroup(0, bindGroup);
+      pass.draw(3, 1, 0, 0);
+    },
+  });
+  return added.ok
+    ? ok({
+        resolvedColor: {
+          kind: 'scene-color',
+          texture: history.colorWrite.texture,
+          view: history.colorWrite.view,
+          format: 'rgba16float',
+          sampleCount: 1,
+        },
+      })
+    : added;
+}

package/src/features/targets.ts

@@ -0,0 +1,83 @@
+/** Render-owned logical targets exposed to producer-owned RenderFeatures. */
+
+export type RenderFeatureTargetKind = 'scene-color' | 'scene-depth' | 'scene-temporal';
+
+/**
+ * A logical attachment supplied by the active RenderPipeline.
+ *
+ * The semantic kind plus attachment facts identify the target. The active
+ * pipeline supplies the graph resource, so feature authors never name an
+ * internal graph key.
+ */
+export interface RenderFeatureTargetHandle {
+  readonly kind: RenderFeatureTargetKind;
+  readonly format: string;
+  readonly sampleCount: 1 | 4;
+  readonly __renderFeatureTarget: unique symbol;
+}
+
+export interface RenderFeatureTargetInput {
+  readonly kind: RenderFeatureTargetKind;
+  readonly format: string;
+  readonly sampleCount: 1 | 4;
+}
+
+export function createRenderFeatureTarget(
+  input: RenderFeatureTargetInput,
+): RenderFeatureTargetHandle {
+  return Object.freeze({ ...input }) as RenderFeatureTargetHandle;
+}
+
+export function isRenderFeatureTargetHandle(value: unknown): value is RenderFeatureTargetHandle {
+  if (value === null || typeof value !== 'object') return false;
+  const candidate = value as Partial<RenderFeatureTargetInput>;
+  return (
+    (candidate.kind === 'scene-color' ||
+      candidate.kind === 'scene-depth' ||
+      candidate.kind === 'scene-temporal') &&
+    typeof candidate.format === 'string' &&
+    (candidate.sampleCount === 1 || candidate.sampleCount === 4)
+  );
+}
+
+export function renderFeatureAttachmentResource(
+  resource: string | RenderFeatureTargetHandle,
+): string {
+  return isRenderFeatureTargetHandle(resource) ? resource.kind : resource;
+}
+
+export function resolveStandardRenderFeatureTargets(input: {
+  readonly pipelineId: string;
+  readonly tonemap: string;
+  readonly antialias: string;
+  readonly storageBuffer: boolean;
+  readonly multisample: boolean;
+  readonly colorAttachmentFormat: string;
+}): readonly RenderFeatureTargetHandle[] {
+  const sampleCount: 1 | 4 = input.antialias === 'msaa' && input.multisample ? 4 : 1;
+  const linearLdr = input.tonemap === 'none' && input.storageBuffer;
+  return [
+    createRenderFeatureTarget({
+      kind: 'scene-color',
+      format:
+        input.pipelineId === 'forgeax::hdrp' || input.tonemap !== 'none' || linearLdr
+          ? 'rgba16float'
+          : input.colorAttachmentFormat,
+      sampleCount,
+    }),
+    createRenderFeatureTarget({
+      kind: 'scene-depth',
+      format: 'depth24plus-stencil8',
+      sampleCount,
+    }),
+    ...(input.antialias === 'taa'
+      ? [
+          createRenderFeatureTarget({
+            kind: 'scene-temporal',
+            format: 'rgba16float',
+            sampleCount: 1,
+          }),
+        ]
+      : []),
+  ];
+}

package/src/features/types.ts

@@ -0,0 +1,291 @@
+/** Public RenderFeature lifecycle, diagnostics, and host-context declarations. */
+import type { EntityHandle, World } from '@forgeax/engine-ecs';
+import type { RhiCaps } from '@forgeax/engine-rhi';
+import type { Result } from '@forgeax/engine-types';
+import type { RenderError } from '../errors/render';
+import type { VisibilitySnapshot } from '../extract/visibility';
+import type { RenderFeatureContributionStaging } from './graph-contribution';
+import type { RenderFeatureGpuPrepare } from './prepared-gpu-work';
+import type {
+  PreparedKind,
+  RenderFeatureGraphicsContributionStaging,
+  RenderFeatureGraphicsPrepare,
+} from './prepared-graphics';
+import type { RenderFeatureTargetHandle } from './targets';
+
+export type { RenderFeatureTargetHandle } from './targets';
+
+/** Closed lifecycle states exposed by the feature host. */
+export type RenderFeatureStatus = 'active' | 'failed' | 'disabled' | 'disposed';
+
+/** Callback stages that can attribute a feature failure. */
+export type RenderFeatureStage =
+  | 'extract'
+  | 'prepare'
+  | 'contribute'
+  | 'record'
+  | 'recover'
+  | 'dispose';
+
+/** Recovery action attached to a structured feature failure. */
+export type RenderFeatureRecovery = 'next-frame' | 'renderer-recover' | 'registration';
+
+/**
+ * Render-owned feature error codes. The detail map below is the membership
+ * owner consumed by the RenderError union.
+ */
+export type RenderFeatureErrorCode = keyof RenderFeatureErrorDetailByCode;
+
+/** Boolean capability names are derived from the RHI capability source. */
+type BooleanCapabilityKey = {
+  [Key in keyof RhiCaps]-?: RhiCaps[Key] extends boolean ? Key : never;
+}[keyof RhiCaps];
+
+export type RenderFeatureCapabilityKey = BooleanCapabilityKey;
+
+export interface RenderFeatureRegistrationConflictDetail {
+  readonly featureIdentity: string;
+  readonly order: number;
+  readonly conflictingOrder: number;
+}
+
+export interface RenderFeatureStageFailedDetail {
+  readonly featureIdentity: string;
+  readonly order: number;
+  readonly stage: RenderFeatureStage;
+  readonly recovery: RenderFeatureRecovery;
+  readonly cleanupFailures?: readonly RenderFeatureCleanupFailure[];
+}
+
+export interface RenderFeatureCleanupFailure {
+  readonly featureIdentity: string;
+  readonly order: number;
+  readonly code: string;
+}
+
+export interface RenderFeatureCapabilityMissingDetail {
+  readonly featureIdentity: string;
+  readonly order: number;
+  readonly capability: RenderFeatureCapabilityKey;
+}
+
+export interface RenderFeaturePassOrderConflictDetail {
+  readonly featureIdentity: string;
+  readonly order: number;
+  readonly passIdentity: string;
+  readonly dependencyIdentity: string;
+}
+
+export interface RenderFeaturePreparationFailedDetail {
+  readonly featureIdentity: string;
+  readonly order: number;
+  readonly stage: 'prepare';
+  readonly operation: string;
+  readonly resourceKind: PreparedKind;
+  readonly resourceName: string;
+  readonly reason: string;
+  readonly recovery: RenderFeatureRecovery;
+}
+
+export type RenderFeaturePreparedStateMismatchDetail =
+  | {
+      readonly featureIdentity: string;
+      readonly order: number;
+      readonly stage: 'contribute';
+      readonly operation: string;
+      readonly resourceKind: PreparedKind;
+      readonly reason: 'missing-prepared-state';
+      readonly missingResource: string;
+      readonly recovery: RenderFeatureRecovery;
+    }
+  | {
+      readonly featureIdentity: string;
+      readonly order: number;
+      readonly stage: 'contribute';
+      readonly operation: string;
+      readonly resourceKind: PreparedKind;
+      readonly reason: 'foreign-feature';
+      readonly expectedFeatureIdentity: string;
+      readonly actualFeatureIdentity: string;
+      readonly recovery: RenderFeatureRecovery;
+    }
+  | {
+      readonly featureIdentity: string;
+      readonly order: number;
+      readonly stage: 'contribute';
+      readonly operation: string;
+      readonly resourceKind: PreparedKind;
+      readonly reason: 'foreign-kind';
+      readonly expectedKind: PreparedKind;
+      readonly actualKind: PreparedKind;
+      readonly recovery: RenderFeatureRecovery;
+    }
+  | {
+      readonly featureIdentity: string;
+      readonly order: number;
+      readonly stage: 'contribute';
+      readonly operation: string;
+      readonly resourceKind: PreparedKind;
+      readonly reason: 'generation-mismatch';
+      readonly expectedGeneration: number;
+      readonly actualGeneration: number;
+      readonly recovery: RenderFeatureRecovery;
+    }
+  | {
+      readonly featureIdentity: string;
+      readonly order: number;
+      readonly stage: 'contribute';
+      readonly operation: string;
+      readonly resourceKind: PreparedKind;
+      readonly reason: 'layout-mismatch';
+      readonly expectedLayout: string;
+      readonly actualLayout: string;
+      readonly recovery: RenderFeatureRecovery;
+    }
+  | {
+      readonly featureIdentity: string;
+      readonly order: number;
+      readonly stage: 'contribute';
+      readonly operation: string;
+      readonly resourceKind: PreparedKind;
+      readonly reason: 'format-mismatch';
+      readonly expectedFormat: string;
+      readonly actualFormat: string;
+      readonly recovery: RenderFeatureRecovery;
+    };
+
+export interface RenderFeatureDrawRecordingFailedDetail {
+  readonly featureIdentity: string;
+  readonly order: number;
+  readonly stage: 'record';
+  readonly operation: string;
+  readonly resourceKind: PreparedKind;
+  readonly reason: string;
+  readonly backendReason: string;
+  readonly recovery: RenderFeatureRecovery;
+}
+
+export type RenderFeatureErrorDetailByCode = {
+  'render-feature-registration-conflict': RenderFeatureRegistrationConflictDetail;
+  'render-feature-stage-failed': RenderFeatureStageFailedDetail;
+  'render-feature-capability-missing': RenderFeatureCapabilityMissingDetail;
+  'render-feature-pass-order-conflict': RenderFeaturePassOrderConflictDetail;
+  'render-feature-preparation-failed': RenderFeaturePreparationFailedDetail;
+  'render-feature-prepared-state-mismatch': RenderFeaturePreparedStateMismatchDetail;
+  'render-feature-draw-recording-failed': RenderFeatureDrawRecordingFailedDetail;
+};
+
+/** Machine-readable four-field diagnostic exposed by every feature error. */
+export type RenderFeatureErrorDescriptor = {
+  [Code in RenderFeatureErrorCode]: {
+    readonly code: Code;
+    readonly expected: string;
+    readonly hint: string;
+    readonly detail: RenderFeatureErrorDetailByCode[Code];
+  };
+}[RenderFeatureErrorCode];
+
+export interface RenderFeatureFrameIdentity {
+  readonly frameNumber: number;
+}
+
+export interface RenderFeatureResourceHandle {
+  readonly __renderFeatureResource: unique symbol;
+}
+
+export interface RenderFeatureErrorSink {
+  report(error: RenderError): void;
+}
+
+/** One World-local visibility snapshot prepared for the current frame batch. */
+export interface RenderFeatureWorldVisibilitySnapshot {
+  readonly world: World;
+  readonly snapshot: VisibilitySnapshot;
+}
+
+/** A producer's structured report for one hidden render candidate. */
+export interface RenderFeatureHiddenEntityReport {
+  readonly world: World;
+  readonly entity: EntityHandle;
+}
+
+export interface RenderFeatureExtractContext {
+  readonly worlds: readonly World[];
+  readonly owner: number;
+  readonly frameNumber: number;
+  /** Same-batch World snapshots; absent for synthetic direct feature probes. */
+  readonly visibilitySnapshots?: readonly RenderFeatureWorldVisibilitySnapshot[];
+  /** Host-owned report sink; feature code never owns the merged diagnostic. */
+  readonly reportHiddenEntity?: (report: RenderFeatureHiddenEntityReport) => void;
+}
+
+/**
+ * Host-owned preparation surface. A feature prepares references here first and
+ * consumes them later through the contribute staging surface. The host owns
+ * resources and generation validity for the whole lifecycle.
+ */
+export interface RenderFeaturePrepareContext {
+  readonly caps: Readonly<RhiCaps>;
+  readonly frame: RenderFeatureFrameIdentity;
+  readonly resources: readonly RenderFeatureResourceHandle[];
+  readonly targets: readonly RenderFeatureTargetHandle[];
+  readonly reportError: RenderFeatureErrorSink;
+  /** Controlled pipeline, bindings, vertex-data, and index-data preparation. */
+  readonly graphics: RenderFeatureGraphicsPrepare;
+  /** Renderer-owned persistent compute/storage preparation, when compute is available. */
+  readonly gpu?: RenderFeatureGpuPrepare;
+}
+
+/** The narrow context visible to a feature-owned graph pass. */
+export interface RenderFeaturePassContext {
+  readonly frame: RenderFeatureFrameIdentity;
+  /** The named pass currently executing inside the active RenderGraph. */
+  readonly pass: {
+    readonly name: string;
+    readonly reads: readonly string[];
+    readonly writes: readonly string[];
+  };
+}
+
+export interface RenderFeatureContributeContext extends RenderFeaturePrepareContext {
+  /** Graph-owned staging retains the ordinary graph-only `addPass` path. */
+  readonly staging: RenderFeatureContributionStaging & RenderFeatureGraphicsContributionStaging;
+}
+
+/**
+ * Producer-owned extension seam for one render frame.
+ *
+ * `FrameData` is the single value that crosses extract, prepare, and
+ * contribute. A producer owns its shape; the host owns ordering, failure
+ * isolation, graph composition, recovery, generation checks, and disposal.
+ * The lifecycle is extract -> prepare -> contribute, with optional recover and
+ * dispose callbacks.
+ */
+export interface RenderFeature<FrameData> {
+  readonly identity: string;
+  readonly requiredCapabilities?: readonly RenderFeatureCapabilityKey[];
+  /**
+   * Material shader identifiers whose modules must be ready before the first
+   * frame. The renderer resolves these against the loaded manifest and seeds
+   * the same lazy module cache used by prepared graphics.
+   */
+  readonly requiredMaterialShaders?: readonly string[];
+  extract(context: RenderFeatureExtractContext): Result<FrameData, RenderError>;
+  prepare(data: FrameData, context: RenderFeaturePrepareContext): Result<void, RenderError>;
+  contribute(data: FrameData, context: RenderFeatureContributeContext): Result<void, RenderError>;
+  recover?(context: RenderFeaturePrepareContext): Result<void, RenderError>;
+  dispose?(context: RenderFeaturePrepareContext): Result<void, RenderError>;
+}
+
+export interface RenderFeatureRecoverInput {
+  readonly caps: Readonly<RhiCaps>;
+  readonly frameNumber: number;
+}
+
+/** Read-only, machine-readable lifecycle state for one registered feature. */
+export interface RenderFeatureDiagnostics {
+  readonly identity: string;
+  readonly order: number;
+  readonly status: RenderFeatureStatus;
+  readonly latestError: RenderFeatureErrorDescriptor | undefined;
+}

package/src/frame-chain.ts

@@ -0,0 +1,21 @@
+import type { RenderResult } from './renderer';
+
+export interface ExtractedFrame {
+  readonly worlds: readonly unknown[];
+}
+export interface PreparedFrame {
+  readonly extracted: ExtractedFrame;
+  readonly resources: Map<unknown, unknown>;
+}
+export function buildFrameChain(worlds: readonly unknown[]): ExtractedFrame {
+  return { worlds };
+}
+export function prepareFrame(
+  extracted: ExtractedFrame,
+  options: { resources: Map<unknown, unknown> },
+): PreparedFrame {
+  return { extracted, resources: options.resources };
+}
+export function recordFrame(_frame: PreparedFrame): RenderResult<void, Error> {
+  return { ok: true, value: undefined };
+}