@forgeax/engine-render 0.0.0-dev.8d955ade1c79

package/src/features/render-graph-raster.ts

@@ -0,0 +1,332 @@
+import type {
+  GraphBuffer,
+  GraphResourceResolver,
+  GraphTexture,
+  GraphTextureView,
+  RasterDepthStencilAttachment,
+  RenderGraphBuilder,
+  RenderGraphError,
+  RenderGraphFrame,
+} from '@forgeax/engine-render-graph';
+import type { BindGroup, RhiRenderPassEncoder } from '@forgeax/engine-rhi';
+import { err, ok, type Result } from '@forgeax/engine-types';
+import {
+  type RenderError,
+  RenderFeatureDrawRecordingFailedError,
+  RenderFeatureStageFailedError,
+} from '../errors/render';
+import type {
+  PreparedGraphicsResolvedResource,
+  PreparedGraphicsResolvedSnapshot,
+} from '../prepare/prepared-graphics-resolver';
+import type { RenderFeatureResolvedGpuBuffer } from './prepared-gpu-work';
+import type {
+  RenderFeatureGraphicsPassDescriptor,
+  RenderFeaturePreparedGraphicsState,
+  RenderFeaturePreparedRef,
+} from './prepared-graphics';
+import { validateRenderFeatureGraphicsPass } from './prepared-graphics';
+import {
+  createRenderFeatureGraphBufferState,
+  importRenderFeatureGraphBuffer,
+  type RenderFeatureGraphBufferState,
+} from './render-graph-resources';
+import type { RenderFeatureTargetHandle } from './targets';
+
+export interface RenderFeatureGraphTarget {
+  readonly texture: GraphTexture;
+  readonly view: GraphTextureView;
+  readonly resolveTarget?: GraphTextureView | undefined;
+}
+
+export type RenderFeatureGraphTargetResolver = (
+  resource: string | RenderFeatureTargetHandle,
+) => RenderFeatureGraphTarget | undefined;
+
+export type RenderFeatureGraphBindingsResolution =
+  | BindGroup
+  | {
+      readonly handle: BindGroup;
+      readonly dynamicOffsets?: readonly number[];
+    };
+
+export type RenderFeatureGraphBindingsResolver<FrameCtx extends RenderGraphFrame> = (input: {
+  readonly frame: FrameCtx;
+  readonly binding: Extract<PreparedGraphicsResolvedResource, { readonly kind: 'bindings' }>;
+  readonly resources: GraphResourceResolver;
+  readonly resolveTarget: RenderFeatureGraphTargetResolver;
+}) => RenderFeatureGraphBindingsResolution | undefined;
+
+interface ResolvedDrawBuffers {
+  readonly vertex: ReadonlyMap<object, GraphBuffer>;
+  readonly index: ReadonlyMap<object, GraphBuffer>;
+  readonly indirect: ReadonlyMap<object, GraphBuffer>;
+}
+
+function missing(featureIdentity: string, order: number): RenderFeatureStageFailedError {
+  return new RenderFeatureStageFailedError(featureIdentity, order, 'record', 'renderer-recover');
+}
+
+function resolved(
+  snapshot: PreparedGraphicsResolvedSnapshot,
+  reference: RenderFeaturePreparedRef,
+): PreparedGraphicsResolvedResource | undefined {
+  return snapshot.resolve(reference);
+}
+
+export class RenderFeatureRasterGraphProjection<FrameCtx extends RenderGraphFrame> {
+  private readonly buffers: RenderFeatureGraphBufferState;
+
+  constructor(
+    private readonly builder: RenderGraphBuilder<FrameCtx>,
+    private readonly resolveTarget: RenderFeatureGraphTargetResolver,
+    private readonly resolveBindings?: RenderFeatureGraphBindingsResolver<FrameCtx>,
+    buffers?: RenderFeatureGraphBufferState,
+    private readonly reportError?: (error: RenderError) => void,
+  ) {
+    this.buffers = buffers ?? createRenderFeatureGraphBufferState();
+  }
+
+  addPass(
+    name: string,
+    featureIdentity: string,
+    order: number,
+    descriptor: RenderFeatureGraphicsPassDescriptor,
+    state: RenderFeaturePreparedGraphicsState,
+    snapshot: PreparedGraphicsResolvedSnapshot,
+  ): Result<void, RenderGraphError | RenderError> {
+    const validated = validateRenderFeatureGraphicsPass(featureIdentity, descriptor, state);
+    if (!validated.ok) return validated;
+
+    const accesses = [];
+    const colors = [];
+    for (const attachment of descriptor.attachments.colors) {
+      const target = this.resolveTarget(attachment.resource);
+      if (target === undefined) return err(missing(featureIdentity, order));
+      accesses.push({ resource: target.view, usage: 'color-attachment' } as const);
+      colors.push({
+        view: target.view,
+        ...(target.resolveTarget === undefined ? {} : { resolveTarget: target.resolveTarget }),
+        loadOp: attachment.loadOp,
+        storeOp: attachment.storeOp,
+      });
+    }
+
+    let depthStencilAttachment: RasterDepthStencilAttachment | undefined;
+    const depth = descriptor.attachments.depthStencil;
+    if (depth !== undefined) {
+      const target = this.resolveTarget(depth.resource);
+      if (target === undefined) return err(missing(featureIdentity, order));
+      const sampled = (descriptor.sampledTargets ?? []).some(
+        (candidate) =>
+          typeof depth.resource !== 'string' &&
+          candidate.kind === depth.resource.kind &&
+          candidate.format === depth.resource.format &&
+          candidate.sampleCount === depth.resource.sampleCount,
+      );
+      accesses.push({
+        resource: target.view,
+        usage: sampled ? ('depth-stencil-read' as const) : ('depth-stencil-write' as const),
+      });
+      depthStencilAttachment = sampled
+        ? { view: target.view, depthReadOnly: true, stencilReadOnly: true }
+        : {
+            view: target.view,
+            depthLoadOp: depth.depthLoadOp,
+            depthStoreOp: depth.depthStoreOp,
+            stencilLoadOp: depth.depthLoadOp,
+            stencilStoreOp: depth.depthStoreOp,
+          };
+    }
+
+    for (const sampled of descriptor.sampledTargets ?? []) {
+      const target = this.resolveTarget(sampled);
+      if (target === undefined) return err(missing(featureIdentity, order));
+      accesses.push({ resource: target.view, usage: 'sampled-read' } as const);
+    }
+
+    const drawBuffers = this.importDrawBuffers(name, featureIdentity, order, descriptor, snapshot);
+    if (!drawBuffers.ok) return drawBuffers;
+    for (const handle of drawBuffers.value.vertex.values()) {
+      accesses.push({ resource: handle, usage: 'vertex-read' } as const);
+    }
+    for (const handle of drawBuffers.value.index.values()) {
+      accesses.push({ resource: handle, usage: 'index-read' } as const);
+    }
+    for (const handle of drawBuffers.value.indirect.values()) {
+      accesses.push({ resource: handle, usage: 'indirect-read' } as const);
+    }
+
+    return this.builder.addRasterPass(name, {
+      accesses,
+      colorAttachments: colors,
+      ...(depthStencilAttachment === undefined ? {} : { depthStencilAttachment }),
+      encode: ({ pass, frame, resources }) => {
+        try {
+          this.encode(
+            featureIdentity,
+            order,
+            descriptor,
+            snapshot,
+            drawBuffers.value,
+            pass,
+            frame,
+            resources,
+          );
+        } catch (failure) {
+          this.reportError?.(
+            failure instanceof Error && typeof (failure as Partial<RenderError>).code === 'string'
+              ? (failure as RenderError)
+              : new RenderFeatureDrawRecordingFailedError(
+                  featureIdentity,
+                  order,
+                  name,
+                  'pipeline',
+                  'backend-recording-failed',
+                  failure instanceof Error ? failure.message : String(failure),
+                  'renderer-recover',
+                ),
+          );
+        }
+      },
+    });
+  }
+
+  private importDrawBuffers(
+    name: string,
+    featureIdentity: string,
+    order: number,
+    descriptor: RenderFeatureGraphicsPassDescriptor,
+    snapshot: PreparedGraphicsResolvedSnapshot,
+  ): Result<ResolvedDrawBuffers, RenderGraphError | RenderError> {
+    const vertex = new Map<object, GraphBuffer>();
+    const index = new Map<object, GraphBuffer>();
+    const indirect = new Map<object, GraphBuffer>();
+    const add = (
+      destination: Map<object, GraphBuffer>,
+      key: object,
+      resource: RenderFeatureResolvedGpuBuffer,
+    ): Result<void, RenderGraphError> => {
+      if (destination.has(key)) return ok(undefined);
+      const imported = importRenderFeatureGraphBuffer(this.builder, this.buffers, name, resource);
+      if (!imported.ok) return imported;
+      destination.set(key, imported.value);
+      return ok(undefined);
+    };
+
+    for (const draw of descriptor.draws) {
+      for (const binding of draw.vertexData) {
+        const resource = resolved(snapshot, binding.resource);
+        if (resource?.kind !== 'vertex-data') return err(missing(featureIdentity, order));
+        const added = add(vertex, binding.resource as object, {
+          buffer: resource.handle,
+          size: resource.size,
+          physicalUsage: resource.physicalUsage,
+        });
+        if (!added.ok) return added;
+      }
+      if (draw.indexData !== undefined) {
+        const resource = resolved(snapshot, draw.indexData.resource);
+        if (resource?.kind !== 'index-data') return err(missing(featureIdentity, order));
+        const added = add(index, draw.indexData.resource as object, {
+          buffer: resource.handle,
+          size: resource.size,
+          physicalUsage: resource.physicalUsage,
+        });
+        if (!added.ok) return added;
+      }
+      if (draw.kind === 'draw-indirect' || draw.kind === 'draw-indexed-indirect') {
+        const resource = snapshot.resolveGpuBuffer?.(draw.command.buffer);
+        if (resource === undefined) return err(missing(featureIdentity, order));
+        const added = add(indirect, draw.command.buffer as object, resource);
+        if (!added.ok) return added;
+      }
+    }
+    return ok({ vertex, index, indirect });
+  }
+
+  private encode(
+    featureIdentity: string,
+    order: number,
+    descriptor: RenderFeatureGraphicsPassDescriptor,
+    snapshot: PreparedGraphicsResolvedSnapshot,
+    buffers: ResolvedDrawBuffers,
+    pass: RhiRenderPassEncoder,
+    frame: FrameCtx,
+    resources: GraphResourceResolver,
+  ): void {
+    for (const draw of descriptor.draws) {
+      const pipeline = resolved(snapshot, draw.pipeline);
+      if (pipeline?.kind !== 'pipeline') throw missing(featureIdentity, order);
+      pass.setPipeline(pipeline.handle);
+      for (const [group, reference] of draw.bindings.entries()) {
+        const binding = resolved(snapshot, reference);
+        if (binding?.kind !== 'bindings') throw missing(featureIdentity, order);
+        const resolvedBindings =
+          binding.handle ??
+          this.resolveBindings?.({ frame, binding, resources, resolveTarget: this.resolveTarget });
+        const handle =
+          resolvedBindings !== undefined &&
+          typeof resolvedBindings === 'object' &&
+          'handle' in resolvedBindings
+            ? resolvedBindings.handle
+            : resolvedBindings;
+        if (handle === undefined) throw missing(featureIdentity, order);
+        const targetGroup = binding.descriptor?.values.group ?? group;
+        const dynamicOffsets =
+          resolvedBindings !== undefined &&
+          typeof resolvedBindings === 'object' &&
+          'handle' in resolvedBindings
+            ? resolvedBindings.dynamicOffsets
+            : binding.dynamicOffsets;
+        pass.setBindGroup(targetGroup, handle, dynamicOffsets);
+      }
+      for (const vertex of draw.vertexData) {
+        const handle = buffers.vertex.get(vertex.resource as object);
+        if (handle === undefined) throw missing(featureIdentity, order);
+        const physical = resources.buffer(handle);
+        if (!physical.ok) throw physical.error;
+        pass.setVertexBuffer(vertex.slot, physical.value);
+      }
+      if (draw.indexData !== undefined) {
+        const handle = buffers.index.get(draw.indexData.resource as object);
+        if (handle === undefined) throw missing(featureIdentity, order);
+        const physical = resources.buffer(handle);
+        if (!physical.ok) throw physical.error;
+        pass.setIndexBuffer(physical.value, draw.indexData.format);
+      }
+      switch (draw.kind) {
+        case 'draw':
+          pass.draw(
+            draw.command.vertexCount,
+            draw.command.instanceCount,
+            draw.command.firstVertex,
+            draw.command.firstInstance,
+          );
+          break;
+        case 'draw-indexed':
+          pass.drawIndexed(
+            draw.command.indexCount,
+            draw.command.instanceCount,
+            draw.command.firstIndex,
+            draw.command.baseVertex,
+            draw.command.firstInstance,
+          );
+          break;
+        case 'draw-indirect':
+        case 'draw-indexed-indirect': {
+          const handle = buffers.indirect.get(draw.command.buffer as object);
+          if (handle === undefined) throw missing(featureIdentity, order);
+          const physical = resources.buffer(handle);
+          if (!physical.ok) throw physical.error;
+          if (draw.kind === 'draw-indirect') {
+            pass.drawIndirect(physical.value, draw.command.offset ?? 0);
+          } else {
+            pass.drawIndexedIndirect(physical.value, draw.command.offset ?? 0);
+          }
+          break;
+        }
+      }
+    }
+  }
+}

package/src/features/render-graph-resources.ts

@@ -0,0 +1,38 @@
+import type {
+  GraphBuffer,
+  RenderGraphBuilder,
+  RenderGraphError,
+  RenderGraphFrame,
+} from '@forgeax/engine-render-graph';
+import type { Buffer } from '@forgeax/engine-rhi';
+import { ok, type Result } from '@forgeax/engine-types';
+import type { RenderFeatureResolvedGpuBuffer } from './prepared-gpu-work';
+
+export interface RenderFeatureGraphBufferState {
+  readonly handles: Map<Buffer, GraphBuffer>;
+  readonly labelCounts: Map<string, number>;
+}
+
+export function createRenderFeatureGraphBufferState(): RenderFeatureGraphBufferState {
+  return { handles: new Map(), labelCounts: new Map() };
+}
+
+export function importRenderFeatureGraphBuffer<FrameCtx extends RenderGraphFrame>(
+  builder: RenderGraphBuilder<FrameCtx>,
+  state: RenderFeatureGraphBufferState,
+  label: string,
+  resource: RenderFeatureResolvedGpuBuffer,
+): Result<GraphBuffer, RenderGraphError> {
+  const existing = state.handles.get(resource.buffer);
+  if (existing !== undefined) return ok(existing);
+  const count = state.labelCounts.get(label) ?? 0;
+  state.labelCounts.set(label, count + 1);
+  const imported = builder.importBuffer(
+    count === 0 ? label : `${label}.${count}`,
+    { size: resource.size, usage: resource.physicalUsage },
+    () => resource.buffer,
+  );
+  if (!imported.ok) return imported;
+  state.handles.set(resource.buffer, imported.value);
+  return imported;
+}

package/src/features/targets.ts

@@ -0,0 +1,70 @@
+import type { TextureFormat } from '@forgeax/engine-rhi';
+
+/** Render-owned logical targets exposed to producer-owned RenderFeatures. */
+
+export type RenderFeatureTargetKind = 'scene-color' | 'scene-depth';
+
+/**
+ * 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: TextureFormat;
+  readonly sampleCount: 1 | 4;
+  readonly __renderFeatureTarget: unique symbol;
+}
+
+export interface RenderFeatureTargetInput {
+  readonly kind: RenderFeatureTargetKind;
+  readonly format: TextureFormat;
+  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') &&
+    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 tonemap: string;
+  readonly antialias: string;
+  readonly storageBuffer: boolean;
+  readonly multisample: boolean;
+  readonly colorAttachmentFormat: TextureFormat;
+}): 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.tonemap !== 'none' || linearLdr ? 'rgba16float' : input.colorAttachmentFormat,
+      sampleCount,
+    }),
+    createRenderFeatureTarget({
+      kind: 'scene-depth',
+      format: 'depth24plus-stencil8',
+      sampleCount,
+    }),
+  ];
+}

package/src/features/types.ts

@@ -0,0 +1,103 @@
+/** 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, RenderFeatureErrorDescriptor } from '../errors/render';
+import type { VisibilitySnapshot } from '../extract/visibility';
+import type { RenderFeaturePlan, RenderFeaturePlanContext } from './plan';
+import type { RenderFeatureCapabilityKey } from './vocabulary';
+
+export type {
+  RenderFeatureCapabilityMissingDetail,
+  RenderFeatureCleanupFailure,
+  RenderFeatureDrawRecordingFailedDetail,
+  RenderFeatureErrorCode,
+  RenderFeatureErrorDescriptor,
+  RenderFeaturePassOrderConflictDetail,
+  RenderFeaturePreparationFailedDetail,
+  RenderFeaturePreparedStateMismatchDetail,
+  RenderFeatureRegistrationConflictDetail,
+  RenderFeatureStageFailedDetail,
+} from '../errors/render';
+export type {
+  RenderFeatureDispatch,
+  RenderFeatureDraw,
+  RenderFeatureDrawDeclaration,
+  RenderFeatureFullscreenProgramDeclaration,
+  RenderFeatureLogicalTarget,
+  RenderFeaturePassDeclaration,
+  RenderFeaturePlan,
+  RenderFeaturePlanContext,
+  RenderFeatureResourceDeclaration,
+  RenderFeatureResourceUsage,
+} from './plan';
+export type { RenderFeatureTargetHandle } from './targets';
+export type {
+  PreparedKind,
+  RenderFeatureCapabilityKey,
+  RenderFeatureRecovery,
+  RenderFeatureStage,
+} from './vocabulary';
+
+/** Closed lifecycle states exposed by the feature host. */
+export type RenderFeatureStatus = 'active' | 'failed' | 'disabled' | 'disposed';
+
+export interface RenderFeatureResourceHandle {
+  readonly __renderFeatureResource: unique symbol;
+}
+
+/** 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;
+}
+
+/**
+ * Producer-owned extension seam for one render frame.
+ *
+ * `FrameData` is the single value that crosses extract into the mandatory
+ * declarative plan. The host derives preparation, graph access, recording,
+ * recovery, and retirement from that plan; no producer callback receives GPU
+ * authority or maintains a parallel lifecycle.
+ */
+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>;
+  plan(data: FrameData, context: RenderFeaturePlanContext): Result<RenderFeaturePlan, 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/features/vocabulary.ts

@@ -0,0 +1,24 @@
+import type { RhiCaps } from '@forgeax/engine-rhi';
+
+/** Closed prepared-resource kinds owned by the RenderFeature vocabulary. */
+export type PreparedKind = 'pipeline' | 'bindings' | 'vertex-data' | 'index-data' | 'attachment';
+
+/** Closed stages that can attribute a feature failure. */
+export type RenderFeatureStage =
+  | 'extract'
+  | 'plan'
+  | 'prepare'
+  | 'contribute'
+  | 'record'
+  | 'recover'
+  | 'dispose';
+
+/** Recovery action attached to a structured feature failure. */
+export type RenderFeatureRecovery = 'next-frame' | 'renderer-recover' | 'registration';
+
+/** 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;