@forgeax/engine-render-graph 0.1.2

package/src/resource-registry.ts

@@ -0,0 +1,173 @@
+// @forgeax/engine-render-graph/src/resource-registry.ts — resource
+// declaration registry (plan-strategy 3.1).
+//
+// Shape (D-4/D-6.1):
+// - string key -> ResourceDescriptor + bufferRole + lifetime
+// - duplicate-resource fail-fast across every declaration form
+// - unknown-resource fail-fast at pass binding time
+// - addColorTarget: color target registration with format/size/sample/usage
+
+import {
+  type AliasSourceDetail,
+  type CapMissingDetail,
+  type DanglingReadDetail,
+  type DuplicateResourceDetail,
+  err,
+  ok,
+  RenderGraphError,
+  type Result,
+} from './errors.js';
+import type {
+  ColorTargetDescriptor,
+  ColorTargetSize,
+  ResourceDescriptor,
+  ResourceLifetime,
+} from './graph.js';
+import type { ColorValueDomain } from './pipeline/color-value-domain.js';
+
+/**
+ * Per-resource GPU allocation metadata carried through compile.
+ * When the resource was registered via addColorTarget, colorTarget
+ * carries the format/size/sample/usage fields (w5); when via
+ * addResource it is undefined.
+ */
+export interface ColorTargetResourceMeta {
+  readonly format: string;
+  readonly size: ColorTargetSize;
+  readonly sample: number;
+  readonly usage: number;
+  /** Explicit semantic color domain; never derived from format. */
+  readonly domain?: ColorValueDomain | undefined;
+  /**
+   * Extra texture view formats pre-declared at GPU texture creation. Mirrors
+   * GPUTextureDescriptor.viewFormats. Used by the LDR MSAA path which needs a
+   * `bgra8unorm` storage texture plus a `bgra8unorm-srgb` view of the same
+   * texture for hardware sRGB encoding on store.
+   */
+  readonly viewFormats?: readonly string[] | undefined;
+  /**
+   * When set, this resource is an alias of the given source resource.
+   * The compile allocation phase folds the alias into the source's
+   * physical texture (KB-1 MoveNode pattern, D-2).
+   */
+  readonly aliasedFrom?: string | undefined;
+}
+
+export interface ResourceEntry {
+  readonly key: string;
+  readonly descriptor: ResourceDescriptor;
+  readonly lifetime: ResourceLifetime;
+  /** Present when the resource was registered via addColorTarget (w5). */
+  readonly colorTarget?: ColorTargetResourceMeta | undefined;
+}
+
+export class ResourceRegistry {
+  private readonly resources = new Map<string, ResourceEntry>();
+
+  add(key: string, descriptor: ResourceDescriptor): Result<ResourceEntry, RenderGraphError> {
+    const entry: ResourceEntry = {
+      key,
+      descriptor,
+      lifetime: descriptor.lifetime,
+    };
+    return this.register(entry);
+  }
+
+  /**
+   * Register a color target resource (D-8).
+   * Same semantics as addResource with kind:'texture' plus GPU texture
+   * allocation metadata. Existing callers default to a transient target.
+   */
+  addColorTarget(
+    name: string,
+    desc: ColorTargetDescriptor,
+  ): Result<ResourceEntry, RenderGraphError> {
+    const lifetime = desc.lifetime ?? 'transient';
+    const colorTargetMeta: ColorTargetResourceMeta = {
+      format: desc.format,
+      size: desc.size,
+      sample: desc.sample ?? 1,
+      usage: desc.usage ?? 0x10 | 0x04, // RENDER_ATTACHMENT | TEXTURE_BINDING
+      ...(desc.domain !== undefined ? { domain: desc.domain } : {}),
+      ...(desc.viewFormats !== undefined ? { viewFormats: desc.viewFormats } : {}),
+    };
+    const entry: ResourceEntry = {
+      key: name,
+      descriptor: { kind: 'texture', lifetime },
+      lifetime,
+      colorTarget: colorTargetMeta,
+    };
+    return this.register(entry);
+  }
+
+  /**
+   * Register a color target alias that folds into the source's physical
+   * texture at compile time (KB-1 MoveNode pattern, D-2).
+   * The source must already be registered via addColorTarget.
+   */
+  addColorTargetAlias(name: string, source: string): Result<ResourceEntry, RenderGraphError> {
+    if (this.resources.has(name)) return this.duplicateResource(name);
+    const sourceMeta = this.resources.get(source)?.colorTarget;
+    if (sourceMeta === undefined) {
+      return err(
+        new RenderGraphError({
+          code: 'alias-source-missing',
+          expected: `alias '${name}' source '${source}' must be a registered color target`,
+          hint: `call addColorTarget('${source}', ...) before retrying alias '${name}'`,
+          detail: { aliasKey: name, sourceKey: source } satisfies AliasSourceDetail,
+        }),
+      );
+    }
+    const entry: ResourceEntry = {
+      key: name,
+      descriptor: { kind: 'texture', lifetime: 'transient' },
+      lifetime: 'transient',
+      colorTarget: {
+        format: sourceMeta.format,
+        size: sourceMeta.size,
+        sample: sourceMeta.sample,
+        usage: sourceMeta.usage,
+        ...(sourceMeta.domain !== undefined ? { domain: sourceMeta.domain } : {}),
+        ...(sourceMeta.viewFormats !== undefined ? { viewFormats: sourceMeta.viewFormats } : {}),
+        aliasedFrom: source,
+      },
+    };
+    return this.register(entry);
+  }
+
+  private duplicateResource(key: string): Result<ResourceEntry, RenderGraphError> {
+    return err(
+      new RenderGraphError({
+        code: 'duplicate-resource',
+        expected: `resource key '${key}' registered exactly once`,
+        hint: `remove the duplicate resource declaration for '${key}' or use a different key`,
+        detail: { resourceKey: key } satisfies DuplicateResourceDetail,
+      }),
+    );
+  }
+
+  private register(entry: ResourceEntry): Result<ResourceEntry, RenderGraphError> {
+    if (this.resources.has(entry.key)) return this.duplicateResource(entry.key);
+    this.resources.set(entry.key, entry);
+    return ok(entry);
+  }
+
+  get(key: string): ResourceEntry | undefined {
+    return this.resources.get(key);
+  }
+
+  getColorTargetMeta(key: string): ColorTargetResourceMeta | undefined {
+    return this.resources.get(key)?.colorTarget;
+  }
+
+  has(key: string): boolean {
+    return this.resources.has(key);
+  }
+
+  entries(): IterableIterator<ResourceEntry> {
+    return this.resources.values();
+  }
+}
+
+// Re-export detail types for use by graph.ts compile fail-fast.
+export type { CapMissingDetail, DanglingReadDetail, DuplicateResourceDetail };

package/src/types.ts

@@ -0,0 +1,217 @@
+import type {
+  Buffer,
+  ComputePassDescriptor,
+  RhiCommandEncoder,
+  RhiComputePassEncoder,
+  RhiDevice,
+  RhiRenderPassEncoder,
+  Texture,
+  TextureFormat,
+  TextureView,
+} from '@forgeax/engine-rhi';
+import type { RenderGraphError, Result } from './errors.js';
+
+declare const graphTextureBrand: unique symbol;
+declare const graphTextureViewBrand: unique symbol;
+declare const graphBufferBrand: unique symbol;
+
+export interface GraphTexture {
+  readonly [graphTextureBrand]: true;
+}
+
+export interface GraphTextureView {
+  readonly [graphTextureViewBrand]: true;
+}
+
+export interface GraphBuffer {
+  readonly [graphBufferBrand]: true;
+}
+
+export type GraphResource = GraphTexture | GraphTextureView | GraphBuffer;
+export type GraphResourceOrigin = 'created' | 'imported';
+export type GraphResourceKind = 'texture' | 'buffer';
+
+export type GraphExtent =
+  | 'surface'
+  | 'half-surface'
+  | {
+      readonly width: number;
+      readonly height: number;
+      readonly depthOrArrayLayers?: number | undefined;
+    };
+
+export interface GraphTextureDescriptor {
+  readonly format: TextureFormat;
+  readonly size: GraphExtent;
+  readonly mipLevelCount?: number | undefined;
+  readonly sampleCount?: number | undefined;
+  readonly dimension?: GPUTextureDimension | undefined;
+  readonly viewFormats?: readonly TextureFormat[] | undefined;
+}
+
+export interface ImportedTextureDescriptor extends GraphTextureDescriptor {
+  readonly usage: number;
+}
+
+export interface GraphTextureViewDescriptor {
+  readonly label?: string | undefined;
+  readonly format?: TextureFormat | undefined;
+  readonly dimension?: GPUTextureViewDimension | undefined;
+  readonly aspect?: GPUTextureAspect | undefined;
+  readonly baseMipLevel?: number | undefined;
+  readonly mipLevelCount?: number | undefined;
+  readonly baseArrayLayer?: number | undefined;
+  readonly arrayLayerCount?: number | undefined;
+}
+
+export type ImportedTextureViewResolver<FrameCtx> = (frame: FrameCtx) => TextureView;
+
+export interface GraphBufferDescriptor {
+  readonly size: number;
+  readonly mappedAtCreation?: boolean | undefined;
+}
+
+export interface ImportedBufferDescriptor extends GraphBufferDescriptor {
+  readonly usage: number;
+}
+
+export type GraphBufferAccess =
+  | 'uniform-read'
+  | 'storage-read'
+  | 'storage-write'
+  | 'storage-read-write'
+  | 'indirect-read'
+  | 'vertex-read'
+  | 'index-read'
+  | 'copy-src'
+  | 'copy-dst';
+
+export type GraphTextureAccess =
+  | 'sampled-read'
+  | 'storage-read'
+  | 'storage-write'
+  | 'storage-read-write'
+  | 'color-attachment'
+  | 'depth-stencil-read'
+  | 'depth-stencil-write'
+  | 'copy-src'
+  | 'copy-dst';
+
+export type GraphAccess =
+  | { readonly resource: GraphBuffer; readonly usage: GraphBufferAccess }
+  | { readonly resource: GraphTextureView; readonly usage: GraphTextureAccess };
+
+export interface GraphResourceResolver {
+  buffer(resource: GraphBuffer): Result<Buffer, RenderGraphError>;
+  texture(resource: GraphTexture): Result<Texture, RenderGraphError>;
+  textureView(resource: GraphTextureView): Result<TextureView, RenderGraphError>;
+}
+
+export interface RasterColorAttachment<FrameCtx> {
+  readonly view: GraphTextureView;
+  readonly resolveTarget?: GraphTextureView | undefined;
+  readonly clearValue?: GPUColor | ((frame: FrameCtx) => GPUColor) | undefined;
+  readonly loadOp: GPULoadOp;
+  readonly storeOp: GPUStoreOp;
+  readonly depthSlice?: number | undefined;
+}
+
+export interface RasterDepthStencilAttachment {
+  readonly view: GraphTextureView;
+  readonly depthClearValue?: number | undefined;
+  readonly depthLoadOp?: GPULoadOp | undefined;
+  readonly depthStoreOp?: GPUStoreOp | undefined;
+  readonly depthReadOnly?: boolean | undefined;
+  readonly stencilClearValue?: number | undefined;
+  readonly stencilLoadOp?: GPULoadOp | undefined;
+  readonly stencilStoreOp?: GPUStoreOp | undefined;
+  readonly stencilReadOnly?: boolean | undefined;
+}
+
+export interface RasterGraphPass<FrameCtx> {
+  readonly accesses: readonly GraphAccess[];
+  readonly colorAttachments: readonly RasterColorAttachment<FrameCtx>[];
+  readonly depthStencilAttachment?: RasterDepthStencilAttachment | undefined;
+  readonly executeIf?: ((frame: FrameCtx) => boolean) | undefined;
+  encode(context: {
+    readonly pass: RhiRenderPassEncoder;
+    readonly frame: FrameCtx;
+    readonly resources: GraphResourceResolver;
+  }): void;
+}
+
+export interface ComputeGraphPass<FrameCtx> {
+  readonly accesses: readonly GraphAccess[];
+  readonly executeIf?: ((frame: FrameCtx) => boolean) | undefined;
+  readonly begin?: ((frame: FrameCtx) => ComputePassDescriptor) | undefined;
+  readonly onBeginError?: ((frame: FrameCtx, cause: unknown) => void) | undefined;
+  encode(context: {
+    readonly pass: RhiComputePassEncoder;
+    readonly frame: FrameCtx;
+    readonly resources: GraphResourceResolver;
+  }): void;
+  readonly after?: ((frame: FrameCtx) => void) | undefined;
+}
+
+export interface CopyGraphPass<FrameCtx> {
+  readonly accesses: readonly GraphAccess[];
+  readonly executeIf?: ((frame: FrameCtx) => boolean) | undefined;
+  encode(context: {
+    readonly encoder: RhiCommandEncoder;
+    readonly frame: FrameCtx;
+    readonly resources: GraphResourceResolver;
+  }): void;
+}
+
+export type GraphPass<FrameCtx> =
+  | { readonly kind: 'raster'; readonly descriptor: RasterGraphPass<FrameCtx> }
+  | { readonly kind: 'compute'; readonly descriptor: ComputeGraphPass<FrameCtx> }
+  | { readonly kind: 'copy'; readonly descriptor: CopyGraphPass<FrameCtx> };
+
+export type GraphPassKind = GraphPass<unknown>['kind'];
+
+export interface GraphAccessInfo {
+  readonly resource: string;
+  readonly usage: GraphBufferAccess | GraphTextureAccess;
+}
+
+export interface CompiledRenderGraphInfo {
+  readonly passes: readonly {
+    readonly name: string;
+    readonly kind: GraphPassKind;
+    readonly executionIndex: number;
+    readonly accesses: readonly GraphAccessInfo[];
+    readonly dependencies: readonly string[];
+  }[];
+  readonly resources: readonly {
+    readonly label: string;
+    readonly kind: GraphResourceKind;
+    readonly origin: GraphResourceOrigin;
+    readonly firstUse: number | null;
+    readonly lastUse: number | null;
+    readonly derivedUsage: number;
+  }[];
+}
+
+export interface RenderGraphFrame {
+  readonly encoder: RhiCommandEncoder;
+}
+
+export interface RenderGraphPassExecution {
+  readonly name: string;
+  readonly kind: GraphPassKind;
+  readonly executionIndex: number;
+}
+
+export type RenderGraphPassRunner = (pass: RenderGraphPassExecution, encode: () => void) => void;
+
+export interface RenderGraphCompileOptions {
+  readonly device: RhiDevice;
+  readonly surfaceSize: { readonly width: number; readonly height: number };
+}
+
+export interface CompiledRenderGraph<FrameCtx extends RenderGraphFrame> {
+  execute(frame: FrameCtx, runPass?: RenderGraphPassRunner): Result<void, RenderGraphError>;
+  inspect(): CompiledRenderGraphInfo;
+  retire(): Promise<Result<void, RenderGraphError>>;
+}