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

package/src/index.ts

@@ -0,0 +1,97 @@
+// @forgeax/engine-render-graph -- declarative render-graph abstraction.
+//
+// Public surface (charter proposition 1: progressive disclosure):
+// - RenderGraph / PassDescriptor / ResourceDescriptor -- core primitives
+// - RenderGraphError / RenderGraphErrorCode -- closed-union error model
+// - Result<T, E> / ok / err -- binary result type
+// - PassInfo / ResourceInfo -- query interfaces
+
+export { RenderGraphBuilder } from './builder.js';
+export {
+  err,
+  type InvalidFormatDetail,
+  ok,
+  RenderGraphError,
+  type RenderGraphErrorCode,
+  type RenderGraphErrorDetail,
+  type ResourceAllocFailedDetail,
+  type Result,
+  type ResultErr,
+  type ResultOk,
+} from './errors.js';
+export type {
+  BufferRole,
+  ColorTargetDescriptor,
+  ColorTargetHandle,
+  ColorTargetSize,
+  CompileOptions,
+  ComputePassDescriptor,
+  InternalizedGraph,
+  InternalizedPass,
+  PassDescriptor,
+  PassInfo,
+  ResolveContext,
+  ResolvedBuffer,
+  ResolvedBufferType,
+  ResolvedColorTargetDescriptor,
+  ResourceDescriptor,
+  ResourceInfo,
+  ResourceKind,
+  ResourceLifetime,
+} from './graph.js';
+export { RenderGraph } from './graph.js';
+export {
+  type CurrentFrameObservationDescriptor,
+  type CurrentFrameObservationLease,
+  type CurrentFrameObservationLifetime,
+  type CurrentFrameObservationSource,
+  createCurrentFrameObservationLease,
+  type ObservationSize,
+} from './observation.js';
+export {
+  COLOR_VALUE_DOMAINS,
+  type ColorDomainConnection,
+  type ColorDomainConversion,
+  type ColorDomainValidation,
+  type ColorResourceDescriptor,
+  type ColorValueDomain,
+  deserializeColorResourceDescriptor,
+  deserializeColorValueDomain,
+  isColorValueDomain,
+  serializeColorResourceDescriptor,
+  serializeColorValueDomain,
+  validateColorDomainConnection,
+} from './pipeline/color-value-domain.js';
+export type {
+  CompiledRenderGraph,
+  CompiledRenderGraphInfo,
+  ComputeGraphPass,
+  CopyGraphPass,
+  GraphAccess,
+  GraphAccessInfo,
+  GraphBuffer,
+  GraphBufferAccess,
+  GraphBufferDescriptor,
+  GraphExtent,
+  GraphPass,
+  GraphPassKind,
+  GraphResource,
+  GraphResourceKind,
+  GraphResourceOrigin,
+  GraphResourceResolver,
+  GraphTexture,
+  GraphTextureAccess,
+  GraphTextureDescriptor,
+  GraphTextureView,
+  GraphTextureViewDescriptor,
+  ImportedBufferDescriptor,
+  ImportedTextureDescriptor,
+  ImportedTextureViewResolver,
+  RasterColorAttachment,
+  RasterDepthStencilAttachment,
+  RasterGraphPass,
+  RenderGraphCompileOptions,
+  RenderGraphFrame,
+  RenderGraphPassExecution,
+  RenderGraphPassRunner,
+} from './types.js';

package/src/kernel-internal.ts

@@ -0,0 +1,148 @@
+import type { Buffer, Texture, TextureView } from '@forgeax/engine-rhi';
+import type {
+  GraphAccess,
+  GraphBuffer,
+  GraphBufferDescriptor,
+  GraphPass,
+  GraphResourceKind,
+  GraphResourceOrigin,
+  GraphTexture,
+  GraphTextureDescriptor,
+  GraphTextureView,
+  GraphTextureViewDescriptor,
+  ImportedBufferDescriptor,
+  ImportedTextureDescriptor,
+  ImportedTextureViewResolver,
+  RenderGraphFrame,
+} from './types.js';
+
+export interface TextureHandleData {
+  readonly owner: object;
+  readonly id: number;
+  readonly kind: 'texture';
+}
+
+export interface TextureViewHandleData {
+  readonly owner: object;
+  readonly id: number;
+  readonly kind: 'texture-view';
+  readonly textureId: number;
+}
+
+export interface BufferHandleData {
+  readonly owner: object;
+  readonly id: number;
+  readonly kind: 'buffer';
+}
+
+export type ResourceHandleData = TextureHandleData | TextureViewHandleData | BufferHandleData;
+
+export function textureHandle(owner: object, id: number): GraphTexture {
+  return Object.freeze({ owner, id, kind: 'texture' }) as unknown as GraphTexture;
+}
+
+export function textureViewHandle(owner: object, id: number, textureId: number): GraphTextureView {
+  return Object.freeze({
+    owner,
+    id,
+    kind: 'texture-view',
+    textureId,
+  }) as unknown as GraphTextureView;
+}
+
+export function bufferHandle(owner: object, id: number): GraphBuffer {
+  return Object.freeze({ owner, id, kind: 'buffer' }) as unknown as GraphBuffer;
+}
+
+export function handleData(resource: unknown): ResourceHandleData | undefined {
+  if (typeof resource !== 'object' || resource === null) return undefined;
+  const candidate = resource as Partial<ResourceHandleData>;
+  if (typeof candidate.id !== 'number' || typeof candidate.owner !== 'object') return undefined;
+  if (
+    candidate.kind !== 'texture' &&
+    candidate.kind !== 'texture-view' &&
+    candidate.kind !== 'buffer'
+  ) {
+    return undefined;
+  }
+  return candidate as ResourceHandleData;
+}
+
+interface ResourceRecordBase {
+  readonly id: number;
+  readonly label: string;
+  readonly kind: GraphResourceKind;
+  readonly origin: GraphResourceOrigin;
+}
+
+export interface CreatedTextureRecord extends ResourceRecordBase {
+  readonly kind: 'texture';
+  readonly origin: 'created';
+  readonly descriptor: GraphTextureDescriptor;
+}
+
+export interface ImportedTextureRecord<FrameCtx> extends ResourceRecordBase {
+  readonly kind: 'texture';
+  readonly origin: 'imported';
+  readonly descriptor: ImportedTextureDescriptor;
+  readonly resolve: (frame: FrameCtx) => Texture;
+}
+
+export interface CreatedBufferRecord extends ResourceRecordBase {
+  readonly kind: 'buffer';
+  readonly origin: 'created';
+  readonly descriptor: GraphBufferDescriptor;
+}
+
+export interface ImportedBufferRecord<FrameCtx> extends ResourceRecordBase {
+  readonly kind: 'buffer';
+  readonly origin: 'imported';
+  readonly descriptor: ImportedBufferDescriptor;
+  readonly resolve: (frame: FrameCtx) => Buffer;
+}
+
+export type ResourceRecord<FrameCtx> =
+  | CreatedTextureRecord
+  | ImportedTextureRecord<FrameCtx>
+  | CreatedBufferRecord
+  | ImportedBufferRecord<FrameCtx>;
+
+export interface TextureViewRecord<FrameCtx extends RenderGraphFrame = RenderGraphFrame> {
+  readonly id: number;
+  readonly label: string;
+  readonly textureId: number;
+  readonly descriptor: GraphTextureViewDescriptor;
+  readonly resolve?: ImportedTextureViewResolver<FrameCtx> | undefined;
+}
+
+export interface PassRecord<FrameCtx extends RenderGraphFrame> {
+  readonly id: number;
+  readonly name: string;
+  readonly pass: GraphPass<FrameCtx>;
+}
+
+export interface CompiledResource<FrameCtx> {
+  readonly record: ResourceRecord<FrameCtx>;
+  readonly usage: number;
+  readonly firstUse: number | null;
+  readonly lastUse: number | null;
+  readonly texture?: Texture | undefined;
+  readonly buffer?: Buffer | undefined;
+}
+
+export interface CompiledView<FrameCtx extends RenderGraphFrame = RenderGraphFrame> {
+  readonly record: TextureViewRecord<FrameCtx>;
+  readonly view?: TextureView | undefined;
+}
+
+export interface CompiledPass<FrameCtx extends RenderGraphFrame> extends PassRecord<FrameCtx> {
+  readonly dependencies: readonly number[];
+  readonly resourceIds: ReadonlySet<number>;
+  readonly viewIds: ReadonlySet<number>;
+}
+
+export function accessResourceId(access: GraphAccess): number | undefined {
+  const data = handleData(access.resource);
+  if (data?.kind === 'texture-view') return data.textureId;
+  return data?.id;
+}

package/src/observation.ts

@@ -0,0 +1,134 @@
+import type { Texture, TextureFormat } from '@forgeax/engine-rhi';
+import { err, ok, RenderGraphError, type Result } from './errors.js';
+
+export { RenderGraphError } from './errors.js';
+
+const COPY_SRC = 0x01;
+
+export interface ObservationSize {
+  readonly width: number;
+  readonly height: number;
+}
+
+/** Generic producer-owned metadata for one current-frame texture. */
+export interface CurrentFrameObservationDescriptor {
+  readonly texture: Texture;
+  readonly format: TextureFormat;
+  readonly size: ObservationSize;
+  readonly usage: number;
+  readonly frameId: number;
+}
+
+export interface CurrentFrameObservationLifetime {
+  readonly frameId: number;
+  readonly state: 'active' | 'retired';
+}
+
+/** The only resource information a downstream copy consumer receives. */
+export interface CurrentFrameObservationSource {
+  readonly texture: Texture;
+  readonly descriptor: CurrentFrameObservationDescriptor;
+  readonly lifetime: CurrentFrameObservationLifetime;
+}
+
+export interface CurrentFrameObservationLease {
+  readonly descriptor: CurrentFrameObservationDescriptor;
+  readonly lifetime: CurrentFrameObservationLifetime;
+  readonly state: 'active' | 'retired';
+  beginReadback(): Result<CurrentFrameObservationSource, RenderGraphError>;
+  retire(): void;
+}
+
+function observationError(
+  code:
+    | 'observation-absent'
+    | 'observation-invalid-format'
+    | 'observation-invalid-size'
+    | 'observation-missing-copy-src'
+    | 'observation-stale',
+  expected: string,
+  hint: string,
+): Result<never, RenderGraphError> {
+  return err(new RenderGraphError({ code, expected, hint }));
+}
+
+/**
+ * Validate and lease a producer's current-frame texture without naming any
+ * semantic, pipeline, backend policy, or graph resource key.
+ */
+export function createCurrentFrameObservationLease(
+  descriptor: CurrentFrameObservationDescriptor,
+  currentFrameId: number,
+): Result<CurrentFrameObservationLease, RenderGraphError> {
+  if (descriptor.texture === undefined || descriptor.texture === null) {
+    return observationError(
+      'observation-absent',
+      'a producer-owned texture handle',
+      'provide the current frame color texture before requesting an observation',
+    );
+  }
+  if (descriptor.format !== 'rgba16float') {
+    return observationError(
+      'observation-invalid-format',
+      "current-frame observation format 'rgba16float'",
+      'use the producer target format without reinterpretation',
+    );
+  }
+  if (
+    !Number.isInteger(descriptor.size.width) ||
+    !Number.isInteger(descriptor.size.height) ||
+    descriptor.size.width <= 0 ||
+    descriptor.size.height <= 0
+  ) {
+    return observationError(
+      'observation-invalid-size',
+      'positive integer observation width and height',
+      'capture a non-empty current-frame target',
+    );
+  }
+  if ((descriptor.usage & COPY_SRC) === 0) {
+    return observationError(
+      'observation-missing-copy-src',
+      'current-frame texture usage includes COPY_SRC',
+      'add COPY_SRC to the producer target before requesting readback',
+    );
+  }
+  if (descriptor.frameId !== currentFrameId) {
+    return observationError(
+      'observation-stale',
+      `observation frame ${currentFrameId}`,
+      `discard frame ${descriptor.frameId} and request the current producer target`,
+    );
+  }
+
+  let state: 'active' | 'retired' = 'active';
+  const lifetime: CurrentFrameObservationLifetime = {
+    frameId: descriptor.frameId,
+    get state() {
+      return state;
+    },
+  };
+  const lease: CurrentFrameObservationLease = {
+    descriptor,
+    lifetime,
+    get state() {
+      return state;
+    },
+    beginReadback() {
+      if (state === 'retired') {
+        return err(
+          new RenderGraphError({
+            code: 'observation-retired',
+            expected: 'active current-frame observation lease',
+            hint: 'submit the eager copy before the producer retires this frame',
+          }),
+        );
+      }
+      return ok({ texture: descriptor.texture, descriptor, lifetime });
+    },
+    retire() {
+      state = 'retired';
+    },
+  };
+  return ok(lease);
+}

package/src/pass-registry.ts

@@ -0,0 +1,43 @@
+// @forgeax/engine-render-graph/src/pass-registry.ts — pass declaration
+// registry (plan-strategy 3.1).
+//
+// Shape (D-5):
+// - name -> reads/writes declaration + optional execute closure
+// - supports listPasses enumeration
+
+import { RenderGraphError } from './errors.js';
+import type { PassDescriptor } from './graph.js';
+
+export interface PassEntry<Ctx = unknown> {
+  readonly name: string;
+  readonly descriptor: PassDescriptor<Ctx>;
+}
+
+export class PassRegistry<Ctx = unknown> {
+  private readonly passes: PassEntry<Ctx>[] = [];
+
+  add(name: string, descriptor: PassDescriptor<Ctx>, before?: string): PassEntry<Ctx> {
+    if (this.passes.some((pass) => pass.name === name)) {
+      throw new RenderGraphError({
+        code: 'duplicate-pass-name',
+        expected: `pass name '${name}' is unique within one graph`,
+        hint: `rename the second '${name}' pass; labels are diagnostics, not identity`,
+        detail: { passName: name },
+      });
+    }
+    const entry: PassEntry<Ctx> = { name, descriptor };
+    const beforeIndex =
+      before === undefined ? -1 : this.passes.findIndex((pass) => pass.name === before);
+    if (beforeIndex < 0) this.passes.push(entry);
+    else this.passes.splice(beforeIndex, 0, entry);
+    return entry;
+  }
+
+  list(): readonly PassEntry<Ctx>[] {
+    return this.passes;
+  }
+
+  count(): number {
+    return this.passes.length;
+  }
+}

package/src/pipeline/__tests__/color-value-domain.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, it } from 'vitest';
+import {
+  COLOR_VALUE_DOMAINS,
+  type ColorResourceDescriptor,
+  type ColorValueDomain,
+  deserializeColorValueDomain,
+  serializeColorResourceDescriptor,
+  serializeColorValueDomain,
+} from '../color-value-domain';
+
+describe('ColorValueDomain', () => {
+  it('keeps the closed domain union in pipeline order', () => {
+    expect(COLOR_VALUE_DOMAINS).toEqual(['linear-hdr', 'linear-ldr', 'display-encoded']);
+  });
+
+  it.each([
+    'linear-hdr',
+    'linear-ldr',
+    'display-encoded',
+  ] as const)('round-trips the %s domain through serialization', (domain: ColorValueDomain) => {
+    expect(deserializeColorValueDomain(serializeColorValueDomain(domain))).toEqual({
+      ok: true,
+      value: domain,
+    });
+  });
+
+  it('serializes a resource descriptor without using the attachment format as authority', () => {
+    const descriptor: ColorResourceDescriptor = {
+      domain: 'linear-hdr',
+      format: 'rgba8unorm',
+    };
+    expect(JSON.parse(serializeColorResourceDescriptor(descriptor))).toEqual(descriptor);
+  });
+
+  it.each([undefined, 'gamma-magic'])('rejects a missing or unknown domain: %s', (value) => {
+    const result = deserializeColorValueDomain(value);
+    expect(result.ok).toBe(false);
+    if (result.ok) throw new Error('expected an invalid color domain');
+    expect(result.error.code).toBe('invalid-color-domain');
+    expect(result.error.expected).toContain('linear-hdr');
+    expect(result.error.hint).toContain('domain');
+  });
+});

package/src/pipeline/color-value-domain.ts

@@ -0,0 +1,139 @@
+import { err, ok, RenderGraphError, type Result } from '../errors.js';
+
+export const COLOR_VALUE_DOMAINS = ['linear-hdr', 'linear-ldr', 'display-encoded'] as const;
+
+export type ColorValueDomain = (typeof COLOR_VALUE_DOMAINS)[number];
+
+export type ColorDomainConversion =
+  | { readonly kind: 'encode-srgb' }
+  | { readonly kind: 'decode-srgb' }
+  | { readonly kind: 'tone-map' };
+
+export interface ColorResourceDescriptor {
+  readonly domain: ColorValueDomain;
+  readonly format: string;
+}
+
+export interface ColorDomainConnection {
+  readonly source: string;
+  readonly destination: string;
+  readonly conversion?: ColorDomainConversion | undefined;
+}
+
+export type ColorDomainValidation =
+  | { readonly ok: true }
+  | { readonly ok: false; readonly error: RenderGraphError };
+
+export function isColorValueDomain(value: unknown): value is ColorValueDomain {
+  return typeof value === 'string' && COLOR_VALUE_DOMAINS.includes(value as ColorValueDomain);
+}
+
+function invalidDomain(value: unknown): RenderGraphError {
+  return new RenderGraphError({
+    code: 'invalid-color-domain',
+    expected: `domain is one of ${COLOR_VALUE_DOMAINS.join(', ')}`,
+    hint: 'set an explicit color domain; do not infer it from the attachment format',
+    detail: { value: String(value) },
+  });
+}
+
+function missingDomain(resourceKey?: string): RenderGraphError {
+  return new RenderGraphError({
+    code: 'missing-color-domain',
+    expected: 'every connected color resource has an explicit domain',
+    hint: `add domain to the color resource descriptor${resourceKey === undefined ? '' : ` '${resourceKey}'`}`,
+    detail: { resourceKey: resourceKey ?? '<descriptor>' },
+  });
+}
+
+export function serializeColorValueDomain(domain: ColorValueDomain): string {
+  if (!isColorValueDomain(domain)) throw invalidDomain(domain);
+  return JSON.stringify(domain);
+}
+
+export function deserializeColorValueDomain(
+  value: unknown,
+): Result<ColorValueDomain, RenderGraphError> {
+  let candidate = value;
+  if (typeof value === 'string') {
+    try {
+      candidate = JSON.parse(value) as unknown;
+    } catch {
+      candidate = value;
+    }
+  }
+  return isColorValueDomain(candidate) ? ok(candidate) : err(invalidDomain(candidate));
+}
+
+export function serializeColorResourceDescriptor(descriptor: ColorResourceDescriptor): string {
+  if (!isColorValueDomain(descriptor.domain)) throw invalidDomain(descriptor.domain);
+  return JSON.stringify(descriptor);
+}
+
+export function deserializeColorResourceDescriptor(
+  value: unknown,
+): Result<ColorResourceDescriptor, RenderGraphError> {
+  if (typeof value !== 'object' || value === null) return err(missingDomain());
+  const candidate = value as { domain?: unknown; format?: unknown };
+  if (candidate.domain === undefined) return err(missingDomain());
+  if (!isColorValueDomain(candidate.domain)) return err(invalidDomain(candidate.domain));
+  if (typeof candidate.format !== 'string' || candidate.format.length === 0) {
+    return err(
+      new RenderGraphError({
+        code: 'invalid-color-domain',
+        expected: 'color resource descriptor includes a non-empty format',
+        hint: 'set format separately from the explicit color domain',
+        detail: { value: String(candidate.format) },
+      }),
+    );
+  }
+  return ok({ domain: candidate.domain, format: candidate.format });
+}
+
+function conversionMatches(
+  source: ColorValueDomain,
+  destination: ColorValueDomain,
+  conversion: ColorDomainConversion,
+): boolean {
+  if (conversion.kind === 'encode-srgb') {
+    return (
+      (source === 'linear-hdr' || source === 'linear-ldr') && destination === 'display-encoded'
+    );
+  }
+  if (conversion.kind === 'decode-srgb') {
+    return (
+      source === 'display-encoded' && (destination === 'linear-hdr' || destination === 'linear-ldr')
+    );
+  }
+  return (
+    source === 'linear-hdr' && (destination === 'linear-ldr' || destination === 'display-encoded')
+  );
+}
+
+export function validateColorDomainConnection(
+  source: unknown,
+  destination: unknown,
+  conversion?: ColorDomainConversion,
+): ColorDomainValidation {
+  if (source === undefined || source === null) return { ok: false, error: missingDomain('source') };
+  if (destination === undefined || destination === null) {
+    return { ok: false, error: missingDomain('destination') };
+  }
+  if (!isColorValueDomain(source)) return { ok: false, error: invalidDomain(source) };
+  if (!isColorValueDomain(destination)) return { ok: false, error: invalidDomain(destination) };
+  if (source === destination) return { ok: true };
+  if (conversion !== undefined && conversionMatches(source, destination, conversion)) {
+    return { ok: true };
+  }
+  return {
+    ok: false,
+    error: new RenderGraphError({
+      code: 'color-domain-mismatch',
+      expected: `source and destination share a domain or use an explicit valid conversion (${source} -> ${destination})`,
+      hint: 'insert an explicit linear blend or output encoding pass; never mix into an encoded destination',
+      detail: { sourceDomain: source, destinationDomain: destination },
+    }),
+  };
+}
+
+export { invalidDomain, missingDomain };