@forgeax/engine-render 0.1.2

package/src/renderer/asset-service.ts

@@ -0,0 +1,32 @@
+import type { CookedMaterialRecord } from '@forgeax/engine-pack';
+import {
+  type MaterialArtifactConflictError,
+  MaterialArtifactRegistry,
+  type MaterialRuntimeArtifact,
+  registerMaterialArtifact,
+} from '@forgeax/engine-shader';
+import { err, ok, type Result } from '@forgeax/engine-types';
+
+export interface MaterialAssetService {
+  publish(
+    record: CookedMaterialRecord,
+  ): Result<CookedMaterialRecord, MaterialArtifactConflictError>;
+  inspect(key: string): ReturnType<MaterialArtifactRegistry['inspect']>;
+}
+
+/** Render owns the CPU material artifact handoff; no GPU cache is introduced. */
+export function createMaterialAssetService(): MaterialAssetService {
+  const artifacts = new MaterialArtifactRegistry();
+  return {
+    publish(record) {
+      const artifact: MaterialRuntimeArtifact = {
+        key: record.specializationKey ?? record.receipt.inputDigest,
+        bytes: record.artifact.bytes,
+        digest: record.artifact.digest,
+      };
+      const registered = registerMaterialArtifact(artifacts, artifact);
+      return registered.ok ? ok(record) : err(registered.error);
+    },
+    inspect: (key) => artifacts.inspect(key),
+  };
+}

package/src/renderer/backend-selection.ts

@@ -0,0 +1,121 @@
+import type {
+  Result,
+  RhiCanvasContext,
+  RhiDevice,
+  RhiError,
+  RhiInstance,
+  ShaderModule,
+} from '@forgeax/engine-rhi';
+import { err, ok, RhiError as RhiErrorClass } from '@forgeax/engine-rhi';
+import * as rhiWebgpu from '@forgeax/engine-rhi-webgpu';
+import type { RendererOptions } from '../renderer';
+
+export interface RhiBackendInstrumentation {
+  readonly resolveSurfaceDevice?: (device: RhiDevice) => Result<RhiDevice, RhiError>;
+  readonly onFrameBoundary?: () => void;
+  readonly onDeviceLost?: () => void;
+}
+
+export interface RhiBackendPack {
+  readonly rhi: RhiInstance & {
+    readonly acquireCanvasContext: (
+      canvas: HTMLCanvasElement | OffscreenCanvas,
+    ) => Result<RhiCanvasContext, RhiError>;
+  };
+  readonly createShaderModule?: (
+    device: RhiDevice,
+    desc: { code: string; label?: string | undefined },
+  ) => Promise<Result<ShaderModule, RhiError>>;
+  readonly translateErrorEventToRhiError?: (event: unknown) => {
+    readonly ok: false;
+    readonly error: RhiError;
+  };
+  /** @internal */
+  readonly _internal_getRawDevice?: (device: RhiDevice) => unknown | undefined;
+  readonly instrumentation?: RhiBackendInstrumentation;
+}
+
+function readOptionalExport(mod: Record<string, unknown>, key: string): unknown {
+  try {
+    return mod[key];
+  } catch {
+    return undefined;
+  }
+}
+
+export function loadRhiPack(mod: Record<string, unknown>): RhiBackendPack {
+  const createShaderModule = readOptionalExport(mod, 'createShaderModule');
+  const translateErrorEventToRhiError = readOptionalExport(mod, 'translateErrorEventToRhiError');
+  const rawDeviceExport = readOptionalExport(mod, '_internal_getRawDevice');
+  const instrumentation = readOptionalExport(mod, 'instrumentation');
+  return {
+    rhi: mod.rhi as RhiBackendPack['rhi'],
+    ...(createShaderModule !== undefined
+      ? {
+          createShaderModule: createShaderModule as NonNullable<
+            RhiBackendPack['createShaderModule']
+          >,
+        }
+      : {}),
+    ...(translateErrorEventToRhiError !== undefined
+      ? {
+          translateErrorEventToRhiError: translateErrorEventToRhiError as NonNullable<
+            RhiBackendPack['translateErrorEventToRhiError']
+          >,
+        }
+      : {}),
+    ...(rawDeviceExport !== undefined
+      ? {
+          _internal_getRawDevice: rawDeviceExport as NonNullable<
+            RhiBackendPack['_internal_getRawDevice']
+          >,
+        }
+      : {}),
+    ...(instrumentation !== undefined
+      ? { instrumentation: instrumentation as RhiBackendInstrumentation }
+      : {}),
+  };
+}
+
+function applyInstrumentation(
+  pack: RhiBackendPack,
+  instrumentation: RhiBackendInstrumentation | undefined,
+): RhiBackendPack {
+  return instrumentation === undefined ? pack : { ...pack, instrumentation };
+}
+
+export async function loadBackendPack(
+  options: RendererOptions | undefined,
+): Promise<Result<RhiBackendPack, RhiError>> {
+  const explicit = options?.rhi;
+  if (explicit !== undefined && explicit !== null) {
+    const extras = explicit as unknown as Record<string, unknown>;
+    return ok(
+      applyInstrumentation(loadRhiPack({ rhi: explicit, ...extras }), options?.rhiInstrumentation),
+    );
+  }
+  const nav =
+    typeof globalThis === 'undefined'
+      ? undefined
+      : (globalThis as { navigator?: { gpu?: unknown } }).navigator;
+  if (nav?.gpu !== undefined && nav.gpu !== null)
+    return ok(
+      applyInstrumentation(
+        loadRhiPack(rhiWebgpu as unknown as Record<string, unknown>),
+        options?.rhiInstrumentation,
+      ),
+    );
+  try {
+    const mod = (await import('@forgeax/engine-rhi-wgpu')) as Record<string, unknown>;
+    await (mod.ensureReady as () => Promise<unknown>)();
+    return ok(applyInstrumentation(loadRhiPack(mod), options?.rhiInstrumentation));
+  } catch (cause) {
+    return err(
+      new RhiErrorClass({
+        code: 'rhi-not-available',
+        expected: 'a usable RHI backend is available',
+        hint: `failed to load wgpu backend: ${String(cause)}`,
+      }),
+    );
+  }
+}

package/src/renderer/environment-classify.ts

@@ -0,0 +1,30 @@
+const GPU_CODES = new Set([
+  'adapter-unavailable',
+  'feature-not-enabled',
+  'limit-exceeded',
+  'rhi-not-available',
+  'device-lost',
+  'oom',
+]);
+export function classifyEnvErrorReason(
+  base: string,
+  primary: { code?: unknown; name?: unknown } | undefined,
+): string {
+  if (!primary || typeof primary !== 'object') return base;
+  const code = primary.code;
+  if (typeof code === 'string' && GPU_CODES.has(code)) return base;
+  const name = typeof primary.name === 'string' ? primary.name : 'inner';
+  return typeof code === 'string' && code.length > 0
+    ? `engine init failed (${name}: ${code})`
+    : `engine init failed (${name})`;
+}
+export function composeEnvErrorHint(webgpuError: unknown, wgpuError: unknown): string | undefined {
+  const a = (webgpuError as { code?: unknown } | undefined)?.code;
+  const b = (wgpuError as { code?: unknown } | undefined)?.code;
+  if (
+    (a === 'adapter-unavailable' || a === 'rhi-not-available') &&
+    (b === 'adapter-unavailable' || b === 'rhi-not-available')
+  )
+    return 'both channels report environmental failure';
+  return undefined;
+}

package/src/renderer/environment-error.ts

@@ -0,0 +1,19 @@
+import type { RhiError } from '@forgeax/engine-rhi';
+export interface EngineEnvironmentErrorDetail {
+  readonly webgpuError?: RhiError | Error | undefined;
+  readonly wgpuError?: RhiError | Error | undefined;
+}
+export class EngineEnvironmentError extends Error {
+  readonly reason: string;
+  readonly webgpuError?: RhiError | Error | undefined;
+  readonly wgpuError?: RhiError | Error | undefined;
+  readonly detail: EngineEnvironmentErrorDetail;
+  constructor(reason: string, detail: EngineEnvironmentErrorDetail = {}) {
+    super(`forgeax-engine: no usable backend (${reason})`);
+    this.name = 'EngineEnvironmentError';
+    this.reason = reason;
+    this.webgpuError = detail.webgpuError;
+    this.wgpuError = detail.wgpuError;
+    this.detail = detail;
+  }
+}

package/src/renderer/material/assembly.ts

@@ -0,0 +1,53 @@
+import type { CookedMaterialRecord } from '@forgeax/engine-pack';
+import type { MaterialValue } from '@forgeax/engine-types';
+
+export interface MaterialRenderPassProjection {
+  readonly name: string;
+  readonly module: string;
+  readonly vertexEntry?: string;
+  readonly fragmentEntry?: string;
+  readonly moduleSlots?: Readonly<Record<string, string>>;
+  readonly renderState?: Readonly<Record<string, unknown>>;
+  readonly artifactHash: string;
+}
+
+export interface MaterialRenderProjection {
+  readonly materialGuid: string;
+  readonly specializationKey: string;
+  readonly artifactHash: string;
+  readonly layoutIdentity: string;
+  readonly passes: readonly MaterialRenderPassProjection[];
+  readonly runtimeValues: Readonly<Record<string, MaterialValue | null>>;
+  readonly staticSelection: readonly string[];
+}
+
+function projectPass(
+  record: CookedMaterialRecord,
+  pass: CookedMaterialRecord['resolved']['passes'][number],
+): MaterialRenderPassProjection {
+  const program = pass.program;
+  return {
+    name: pass.name,
+    module: program.module,
+    ...(program.vertexEntry === undefined ? {} : { vertexEntry: program.vertexEntry }),
+    ...(program.fragmentEntry === undefined ? {} : { fragmentEntry: program.fragmentEntry }),
+    ...(program.moduleSlots === undefined ? {} : { moduleSlots: program.moduleSlots }),
+    ...(pass.renderState === undefined ? {} : { renderState: pass.renderState }),
+    artifactHash: record.artifact.digest,
+  };
+}
+
+export function assembleMaterialProjection(record: CookedMaterialRecord): MaterialRenderProjection {
+  return {
+    materialGuid: record.guid,
+    specializationKey: record.receipt.inputDigest,
+    artifactHash: record.artifact.digest,
+    layoutIdentity: record.receipt.layoutIdentity,
+    passes: record.resolved.passes.map((pass) => projectPass(record, pass)),
+    runtimeValues: record.resolved.values,
+    staticSelection: record.resolved.parameters
+      .filter((parameter) => parameter.static)
+      .map((parameter) => parameter.name)
+      .sort(),
+  };
+}

package/src/renderer/material/pipeline-projection.ts

@@ -0,0 +1,140 @@
+import type { MaterialRuntimeArtifact } from '@forgeax/engine-shader';
+import {
+  createMaterialError,
+  type MaterialErrorFor,
+  type MaterialValue,
+} from '@forgeax/engine-types';
+import { type MaterialDrawDiagnostic, materialDrawDiagnostic } from '../../errors/render.js';
+import type { MaterialRenderProjection } from './assembly.js';
+
+export interface MaterialRenderReady {
+  readonly status: 'Ready';
+  readonly guid: string;
+  readonly materialGuid: string;
+  readonly publicationGeneration: number;
+  readonly specializationKey: string;
+  readonly artifactDigest: string;
+  readonly sourceClosure: readonly string[];
+  readonly parameterContract: unknown;
+  readonly record: unknown;
+  readonly artifact: MaterialRuntimeArtifact;
+}
+
+export interface MaterialRenderError {
+  readonly status: 'Error';
+  readonly error: {
+    readonly code: string;
+    readonly expected: string;
+    readonly hint: string;
+    readonly retryable: boolean;
+    readonly recoveryActions: readonly string[];
+    readonly detail: {
+      readonly guid: string;
+      readonly specializationKey: string;
+      readonly publicationGeneration?: number;
+      readonly actual?: string;
+    };
+  };
+}
+
+export type MaterialReadiness = MaterialRenderReady | MaterialRenderError;
+
+export type MaterialDrawRoute<TPipeline> =
+  | { readonly kind: 'draw'; readonly pipeline: TPipeline }
+  | { readonly kind: 'skip'; readonly diagnostic?: MaterialDrawDiagnostic };
+
+export type MaterialReadinessRoute =
+  | { readonly kind: 'draw'; readonly readiness: MaterialRenderReady }
+  | { readonly kind: 'skip'; readonly diagnostic?: MaterialDrawDiagnostic };
+
+export interface MaterialPipelineProjection {
+  readonly specializationKey: string;
+  readonly artifactHash: string;
+  readonly layoutIdentity: string;
+  readonly passes: MaterialRenderProjection['passes'];
+}
+
+export interface MaterialPipelineReady extends MaterialPipelineProjection {
+  readonly kind: 'ready';
+  readonly artifact: MaterialRuntimeArtifact;
+}
+
+export interface MaterialPipelineMiss {
+  readonly kind: 'error';
+  readonly error: {
+    readonly code: MaterialErrorFor<'material-specialization-not-cooked'>['code'];
+    readonly expected: MaterialErrorFor<'material-specialization-not-cooked'>['expected'];
+    readonly hint: MaterialErrorFor<'material-specialization-not-cooked'>['hint'];
+    readonly detail: MaterialErrorFor<'material-specialization-not-cooked'>['detail'];
+    readonly message: MaterialErrorFor<'material-specialization-not-cooked'>['message'];
+  };
+}
+
+export function projectMaterialPipeline(
+  projection: MaterialRenderProjection,
+): MaterialPipelineProjection {
+  return {
+    specializationKey: projection.specializationKey,
+    artifactHash: projection.artifactHash,
+    layoutIdentity: projection.layoutIdentity,
+    passes: projection.passes,
+  };
+}
+
+export function updateMaterialRuntimeValues(
+  projection: MaterialRenderProjection,
+  values: Readonly<Record<string, MaterialValue | null>>,
+): MaterialRenderProjection {
+  return {
+    ...projection,
+    runtimeValues: { ...projection.runtimeValues, ...values },
+  };
+}
+
+export function routeMaterialPipeline(args: {
+  readonly projection: MaterialRenderProjection;
+  readonly lookupArtifact: (key: string) => MaterialRuntimeArtifact | undefined;
+}): MaterialPipelineReady | MaterialPipelineMiss {
+  const artifact = args.lookupArtifact(args.projection.specializationKey);
+  if (artifact === undefined || artifact.digest !== args.projection.artifactHash) {
+    return {
+      kind: 'error',
+      error: createMaterialError('material-specialization-not-cooked', {
+        code: 'material-specialization-not-cooked',
+        material: args.projection.materialGuid,
+        staticSelection: args.projection.staticSelection,
+      }),
+    };
+  }
+  return { kind: 'ready', ...projectMaterialPipeline(args.projection), artifact };
+}
+
+/**
+ * Route one draw from the canonical MaterialReady result.
+ *
+ * A failed readiness result never reaches the pipeline builder. The caller
+ * owns one Set for the render lifetime so repeated frames and re-entry share
+ * the same material identity dedupe boundary.
+ */
+export function routeMaterialDraw<TPipeline>(args: {
+  readonly readiness: MaterialReadiness;
+  readonly buildPipeline: (ready: MaterialRenderReady) => TPipeline;
+  readonly reportedDiagnosticKeys: Set<string>;
+}): MaterialDrawRoute<TPipeline> {
+  const route = routeMaterialReadiness(args);
+  return route.kind === 'draw'
+    ? { kind: 'draw', pipeline: args.buildPipeline(route.readiness) }
+    : route;
+}
+
+/** Route the production record decision before pipeline selection or draw. */
+export function routeMaterialReadiness(args: {
+  readonly readiness: MaterialReadiness;
+  readonly reportedDiagnosticKeys: Set<string>;
+}): MaterialReadinessRoute {
+  if (args.readiness.status === 'Ready') return { kind: 'draw', readiness: args.readiness };
+  const diagnostic = materialDrawDiagnostic(args.readiness);
+  if (args.reportedDiagnosticKeys.has(diagnostic.key)) return { kind: 'skip' };
+  args.reportedDiagnosticKeys.add(diagnostic.key);
+  return { kind: 'skip', diagnostic };
+}