@forgeax/engine-render 0.1.4 → 0.1.7

package/src/features/prepared-graphics.ts

@@ -4,9 +4,10 @@
  * The five prepared kinds are declarative references only: the render owner
  * retains device, resource, graph, recording, and submission ownership.
  */
+
+import type { TextureFormat } from '@forgeax/engine-rhi';
 import {
   err,
-  type MaterialAsset,
   type MaterialRenderState,
   ok,
   type PrimitiveTopology,
@@ -15,14 +16,15 @@ import {
 import {
   type RenderError,
   RenderFeaturePreparationFailedError,
+  type RenderFeaturePreparedStateMismatchDetail,
   RenderFeaturePreparedStateMismatchError,
 } from '../errors/render';
 import type { RenderFeatureGpuBufferRef } from './prepared-gpu-work';
 import type { RenderFeatureTargetHandle } from './targets';
-import type { RenderFeaturePreparedStateMismatchDetail } from './types';
+import type { PreparedKind } from './vocabulary';
 
 /** Closed prepared kinds: pipeline, bindings, vertex/index data, and attachment. */
-export type PreparedKind = 'pipeline' | 'bindings' | 'vertex-data' | 'index-data' | 'attachment';
+export type { PreparedKind } from './vocabulary';
 
 /** Canonical vertex layouts owned by the prepared-graphics host. */
 export const RENDER_FEATURE_VERTEX_LAYOUTS = Object.freeze({
@@ -48,8 +50,8 @@ export interface RenderFeaturePreparedRef<Kind extends PreparedKind = PreparedKi
 export interface RenderFeaturePipelineDescriptor {
   readonly shader: string;
   readonly vertexLayout: string;
-  readonly colorFormats: readonly string[];
-  readonly depthFormat?: string;
+  readonly colorFormats: readonly TextureFormat[];
+  readonly depthFormat?: TextureFormat;
   /** Sample count of the target this pipeline will draw into. */
   readonly sampleCount?: 1 | 4;
   /** Primitive topology consumed by the prepared draw. */
@@ -70,6 +72,8 @@ export interface RenderFeatureBindingsDescriptor {
   readonly values: Readonly<Record<string, unknown>> & {
     readonly group?: number;
     readonly sceneDepth?: RenderFeatureTargetHandle;
+    /** Binding slot for a view-plus-scene-depth group (0 keeps legacy behavior). */
+    readonly sceneDepthBinding?: number;
   };
 }
 
@@ -105,12 +109,6 @@ export type RenderFeatureIndexDataDescriptor =
  * render owner retains resource, graph, recording, and submission ownership.
  */
 export interface RenderFeatureGraphicsPrepare {
-  /** Resolve and register a cooked MaterialAsset through the Render owner. */
-  resolveMaterialAsset(material: MaterialAsset): Result<MaterialAsset, RenderError>;
-  /** Resolve the renderer-owned binding contract for a material shader. */
-  getMaterialShaderBindingContract(
-    materialShaderId: string,
-  ): RenderFeatureMaterialShaderBindingContract;
   /** Prepare a registered graphics pipeline without exposing backend state. */
   preparePipeline(
     name: string,
@@ -133,17 +131,10 @@ export interface RenderFeatureGraphicsPrepare {
   ): Result<RenderFeaturePreparedRef<'index-data'>, RenderError>;
 }
 
-export type RenderFeatureMaterialShaderBindingContract =
-  | 'group-0'
-  | 'group-0-resource'
-  | 'view-only'
-  | 'view-with-resource'
-  | 'render-material';
-
 /** A color target declared by a graphics pass. */
 export interface RenderFeatureColorAttachment {
   readonly resource: string | RenderFeatureTargetHandle;
-  readonly format: string;
+  readonly format: TextureFormat;
   readonly loadOp: 'load' | 'clear';
   readonly storeOp: 'store' | 'discard';
 }
@@ -151,7 +142,7 @@ export interface RenderFeatureColorAttachment {
 /** A depth/stencil target declared by a graphics pass. */
 export interface RenderFeatureDepthStencilAttachment {
   readonly resource: string | RenderFeatureTargetHandle;
-  readonly format: string;
+  readonly format: TextureFormat;
   readonly depthLoadOp: 'load' | 'clear';
   readonly depthStoreOp: 'store' | 'discard';
 }
@@ -244,21 +235,9 @@ export interface RenderFeatureGraphicsPassDescriptor {
   readonly attachments: RenderFeatureGraphicsPassAttachments;
   /** Targets sampled by shaders but not attached for writing in this pass. */
   readonly sampledTargets?: readonly RenderFeatureTargetHandle[];
-  /** Explicit temporal producer class; omission is fail-closed coverage. */
-  readonly temporalCoverage?: 'exact' | 'reactive';
   readonly draws: readonly RenderFeatureDrawRecord[];
 }
 
-/** Graph-owned staging entry for declarative graphics work. */
-export interface RenderFeatureGraphicsContributionStaging {
-  /** Add one declarative graphics pass while preserving graph ownership. */
-  addGraphicsPass(
-    name: string,
-    descriptor: RenderFeatureGraphicsPassDescriptor,
-    options?: import('./graph-contribution').RenderFeaturePassOptions,
-  ): Result<void, RenderError>;
-}
-
 /**
  * Prepared state projected by the render owner for pure descriptor validation.
  * The generation and opaque references are host facts, not producer-owned GPU
@@ -269,7 +248,7 @@ export interface RenderFeaturePreparedGraphicsState {
   readonly generation: number;
   readonly attachments: readonly {
     readonly resource: string | RenderFeatureTargetHandle;
-    readonly format: string;
+    readonly format: TextureFormat;
   }[];
   readonly pipeline: RenderFeaturePreparedRef | undefined;
   /** All prepared pipelines available to the current graphics pass. */
@@ -314,25 +293,6 @@ function invalid(
   return err(new RenderFeaturePreparedStateMismatchError(detail));
 }
 
-function preparationFailure(
-  featureIdentity: string,
-  order: number,
-  operation: string,
-  resourceKind: PreparedKind,
-): Result<never, RenderError> {
-  return err(
-    new RenderFeaturePreparationFailedError(
-      featureIdentity,
-      order,
-      operation,
-      resourceKind,
-      'unavailable',
-      'prepared-graphics-host-unavailable',
-      'next-frame',
-    ),
-  );
-}
-
 function validRef<Kind extends PreparedKind>(
   reference: RenderFeaturePreparedRef<Kind>,
   kind: Kind,
@@ -458,22 +418,3 @@ export function validateRenderFeatureGraphicsPass(
   }
   return ok({ acceptedDrawCount: descriptor.draws.length });
 }
-
-/** Create the explicit unavailable facade used until a Host owns prepared state. */
-export function createRenderFeatureGraphicsPrepare(
-  featureIdentity: string,
-  order: number,
-): RenderFeatureGraphicsPrepare {
-  return {
-    resolveMaterialAsset: (material) => ok(material),
-    getMaterialShaderBindingContract: () => 'render-material',
-    preparePipeline: () =>
-      preparationFailure(featureIdentity, order, 'prepare-pipeline', 'pipeline'),
-    prepareBindings: () =>
-      preparationFailure(featureIdentity, order, 'prepare-bindings', 'bindings'),
-    prepareVertexData: () =>
-      preparationFailure(featureIdentity, order, 'prepare-vertex-data', 'vertex-data'),
-    prepareIndexData: () =>
-      preparationFailure(featureIdentity, order, 'prepare-index-data', 'index-data'),
-  };
-}

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

@@ -9,17 +9,21 @@ import {
   encodeRenderFeatureGpuComputePass,
   type RenderFeatureResolvedGpuComputePass,
 } from './prepared-gpu-work';
-import { RenderFeatureGraphBufferRegistry } from './render-graph-resources';
+import {
+  createRenderFeatureGraphBufferState,
+  importRenderFeatureGraphBuffer,
+  type RenderFeatureGraphBufferState,
+} from './render-graph-resources';
 
 export class RenderFeatureComputeGraphProjection<FrameCtx extends RenderGraphFrame> {
-  private readonly resources: RenderFeatureGraphBufferRegistry<FrameCtx>;
+  private readonly resources: RenderFeatureGraphBufferState;
 
   constructor(
     private readonly builder: RenderGraphBuilder<FrameCtx>,
-    resources?: RenderFeatureGraphBufferRegistry<FrameCtx>,
+    resources?: RenderFeatureGraphBufferState,
     private readonly reportError?: (error: RenderError) => void,
   ) {
-    this.resources = resources ?? new RenderFeatureGraphBufferRegistry(builder);
+    this.resources = resources ?? createRenderFeatureGraphBufferState();
   }
 
   addPass(
@@ -30,7 +34,12 @@ export class RenderFeatureComputeGraphProjection<FrameCtx extends RenderGraphFra
   ): Result<void, RenderGraphError> {
     const accesses = [];
     for (const resource of work.buffers) {
-      const imported = this.resources.import(`${name}.${resource.name}`, resource);
+      const imported = importRenderFeatureGraphBuffer(
+        this.builder,
+        this.resources,
+        `${name}.${resource.name}`,
+        resource,
+      );
       if (!imported.ok) return imported;
       accesses.push({ resource: imported.value, usage: resource.access } as const);
     }

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

@@ -5,45 +5,26 @@ import type {
 } from '@forgeax/engine-render-graph';
 import { err, ok, type Result } from '@forgeax/engine-types';
 import { type RenderError, RenderFeatureStageFailedError } from '../errors/render';
-import {
-  mergeRenderFeatureContributions,
-  type RenderFeatureGraphContribution,
-} from './graph-contribution';
+import type { RenderFeaturePlanExecution } from './host';
 import { RenderFeatureComputeGraphProjection } from './render-graph-compute';
 import {
   type RenderFeatureGraphBindingsResolver,
   type RenderFeatureGraphTargetResolver,
   RenderFeatureRasterGraphProjection,
 } from './render-graph-raster';
-import { RenderFeatureGraphBufferRegistry } from './render-graph-resources';
-
-export interface RenderFeatureTypedGraphProjection {
-  readonly topologySignature: string;
-  readonly passNames: readonly string[];
-}
+import { createRenderFeatureGraphBufferState } from './render-graph-resources';
 
-export function projectRenderFeatureContributions<FrameCtx extends RenderGraphFrame>(
+/** Project the host-owned plan execution directly into the one typed graph. */
+export function projectRenderFeaturePlans<FrameCtx extends RenderGraphFrame>(
   builder: RenderGraphBuilder<FrameCtx>,
-  contributions: readonly RenderFeatureGraphContribution[],
+  executions: readonly RenderFeaturePlanExecution[],
   options: {
     readonly resolveTarget: RenderFeatureGraphTargetResolver;
     readonly resolveBindings?: RenderFeatureGraphBindingsResolver<FrameCtx> | undefined;
     readonly reportError?: ((error: RenderError) => void) | undefined;
   },
-): Result<RenderFeatureTypedGraphProjection, RenderGraphError | RenderError> {
-  const merged = mergeRenderFeatureContributions(contributions);
-  if (!merged.ok) return merged;
-  if (merged.value.resources.length > 0) {
-    return err(
-      new RenderFeatureStageFailedError(
-        merged.value.featureIdentity,
-        merged.value.order,
-        'contribute',
-        'next-frame',
-      ),
-    );
-  }
-  const buffers = new RenderFeatureGraphBufferRegistry(builder);
+): Result<void, RenderGraphError | RenderError> {
+  const buffers = createRenderFeatureGraphBufferState();
   const compute = new RenderFeatureComputeGraphProjection(builder, buffers, options.reportError);
   const raster = new RenderFeatureRasterGraphProjection(
     builder,
@@ -52,44 +33,43 @@ export function projectRenderFeatureContributions<FrameCtx extends RenderGraphFr
     buffers,
     options.reportError,
   );
-  for (const pass of merged.value.passes) {
-    if (pass.resolvedGpuCompute !== undefined) {
-      const added = compute.addPass(
-        pass.name,
-        pass.featureIdentity,
-        pass.order,
-        pass.resolvedGpuCompute,
-      );
-      if (!added.ok) return added;
-      continue;
-    }
-    if (
-      pass.graphics !== undefined &&
-      pass.graphicsState !== undefined &&
-      pass.resolvedGraphics !== undefined
-    ) {
-      const added = raster.addPass(
-        pass.name,
-        pass.featureIdentity,
-        pass.order,
-        pass.graphics,
-        pass.graphicsState,
-        pass.resolvedGraphics,
+  for (const execution of executions) {
+    for (const pass of execution.passes) {
+      if (pass.resolvedGpuCompute !== undefined) {
+        const added = compute.addPass(
+          pass.name,
+          execution.featureIdentity,
+          execution.order,
+          pass.resolvedGpuCompute,
+        );
+        if (!added.ok) return added;
+        continue;
+      }
+      if (
+        pass.graphics !== undefined &&
+        pass.graphicsState !== undefined &&
+        pass.resolvedGraphics !== undefined
+      ) {
+        const added = raster.addPass(
+          pass.name,
+          execution.featureIdentity,
+          execution.order,
+          pass.graphics,
+          pass.graphicsState,
+          pass.resolvedGraphics,
+        );
+        if (!added.ok) return added;
+        continue;
+      }
+      return err(
+        new RenderFeatureStageFailedError(
+          execution.featureIdentity,
+          execution.order,
+          'plan',
+          'next-frame',
+        ),
       );
-      if (!added.ok) return added;
-      continue;
     }
-    return err(
-      new RenderFeatureStageFailedError(
-        pass.featureIdentity,
-        pass.order,
-        'contribute',
-        'next-frame',
-      ),
-    );
   }
-  return ok({
-    topologySignature: merged.value.topologySignature,
-    passNames: Object.freeze(merged.value.passes.map((pass) => pass.name)),
-  });
+  return ok(undefined);
 }

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

@@ -26,7 +26,11 @@ import type {
   RenderFeaturePreparedRef,
 } from './prepared-graphics';
 import { validateRenderFeatureGraphicsPass } from './prepared-graphics';
-import { RenderFeatureGraphBufferRegistry } from './render-graph-resources';
+import {
+  createRenderFeatureGraphBufferState,
+  importRenderFeatureGraphBuffer,
+  type RenderFeatureGraphBufferState,
+} from './render-graph-resources';
 import type { RenderFeatureTargetHandle } from './targets';
 
 export interface RenderFeatureGraphTarget {
@@ -39,12 +43,19 @@ 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;
-}) => BindGroup | undefined;
+}) => RenderFeatureGraphBindingsResolution | undefined;
 
 interface ResolvedDrawBuffers {
   readonly vertex: ReadonlyMap<object, GraphBuffer>;
@@ -64,16 +75,16 @@ function resolved(
 }
 
 export class RenderFeatureRasterGraphProjection<FrameCtx extends RenderGraphFrame> {
-  private readonly buffers: RenderFeatureGraphBufferRegistry<FrameCtx>;
+  private readonly buffers: RenderFeatureGraphBufferState;
 
   constructor(
     private readonly builder: RenderGraphBuilder<FrameCtx>,
     private readonly resolveTarget: RenderFeatureGraphTargetResolver,
     private readonly resolveBindings?: RenderFeatureGraphBindingsResolver<FrameCtx>,
-    buffers?: RenderFeatureGraphBufferRegistry<FrameCtx>,
+    buffers?: RenderFeatureGraphBufferState,
     private readonly reportError?: (error: RenderError) => void,
   ) {
-    this.buffers = buffers ?? new RenderFeatureGraphBufferRegistry(builder);
+    this.buffers = buffers ?? createRenderFeatureGraphBufferState();
   }
 
   addPass(
@@ -197,7 +208,7 @@ export class RenderFeatureRasterGraphProjection<FrameCtx extends RenderGraphFram
       resource: RenderFeatureResolvedGpuBuffer,
     ): Result<void, RenderGraphError> => {
       if (destination.has(key)) return ok(undefined);
-      const imported = this.buffers.import(name, resource);
+      const imported = importRenderFeatureGraphBuffer(this.builder, this.buffers, name, resource);
       if (!imported.ok) return imported;
       destination.set(key, imported.value);
       return ok(undefined);
@@ -251,11 +262,24 @@ export class RenderFeatureRasterGraphProjection<FrameCtx extends RenderGraphFram
       for (const [group, reference] of draw.bindings.entries()) {
         const binding = resolved(snapshot, reference);
         if (binding?.kind !== 'bindings') throw missing(featureIdentity, order);
-        const handle =
+        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);
-        pass.setBindGroup(group, handle, binding.dynamicOffsets);
+        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);

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

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

@@ -1,6 +1,8 @@
+import type { TextureFormat } from '@forgeax/engine-rhi';
+
 /** Render-owned logical targets exposed to producer-owned RenderFeatures. */
 
-export type RenderFeatureTargetKind = 'scene-color' | 'scene-depth' | 'scene-temporal';
+export type RenderFeatureTargetKind = 'scene-color' | 'scene-depth';
 
 /**
  * A logical attachment supplied by the active RenderPipeline.
@@ -11,14 +13,14 @@ export type RenderFeatureTargetKind = 'scene-color' | 'scene-depth' | 'scene-tem
  */
 export interface RenderFeatureTargetHandle {
   readonly kind: RenderFeatureTargetKind;
-  readonly format: string;
+  readonly format: TextureFormat;
   readonly sampleCount: 1 | 4;
   readonly __renderFeatureTarget: unique symbol;
 }
 
 export interface RenderFeatureTargetInput {
   readonly kind: RenderFeatureTargetKind;
-  readonly format: string;
+  readonly format: TextureFormat;
   readonly sampleCount: 1 | 4;
 }
 
@@ -32,9 +34,7 @@ export function isRenderFeatureTargetHandle(value: unknown): value is RenderFeat
   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') &&
+    (candidate.kind === 'scene-color' || candidate.kind === 'scene-depth') &&
     typeof candidate.format === 'string' &&
     (candidate.sampleCount === 1 || candidate.sampleCount === 4)
   );
@@ -47,22 +47,18 @@ export function renderFeatureAttachmentResource(
 }
 
 export function resolveStandardRenderFeatureTargets(input: {
-  readonly pipelineId: string;
   readonly tonemap: string;
   readonly antialias: string;
   readonly storageBuffer: boolean;
   readonly multisample: boolean;
-  readonly colorAttachmentFormat: string;
+  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.pipelineId === 'forgeax::hdrp' || input.tonemap !== 'none' || linearLdr
-          ? 'rgba16float'
-          : input.colorAttachmentFormat,
+      format: input.tonemap !== 'none' || linearLdr ? 'rgba16float' : input.colorAttachmentFormat,
       sampleCount,
     }),
     createRenderFeatureTarget({
@@ -70,14 +66,5 @@ export function resolveStandardRenderFeatureTargets(input: {
       format: 'depth24plus-stencil8',
       sampleCount,
     }),
-    ...(input.antialias === 'taa'
-      ? [
-          createRenderFeatureTarget({
-            kind: 'scene-temporal',
-            format: 'rgba16float',
-            sampleCount: 1,
-          }),
-        ]
-      : []),
   ];
 }