@forgeax/engine-render 0.1.4 → 0.1.7

package/src/scene-utils/collect-subtree.ts

@@ -1,40 +0,0 @@
-// M1 shared util — collectSubtree (AC-16).
-// Extracted from post-spawn-resolve-joints.ts:116-133.
-// Walks Children.entities BFS from spawnRoot; accepts optional external visited Set
-// for cross-root de-duplication (AC-03).
-
-import type { EntityHandle, World } from '@forgeax/engine-ecs';
-
-import { Children } from '@forgeax/engine-scene';
-
-/**
- * Walk `Children.entities` BFS from `spawnRoot` to collect all descendant
- * entities (incl. spawnRoot itself). When a shared `visited` Set is passed,
- * it is reused across roots for cross-root de-duplication; when omitted a
- * fresh Set is created (single-root / backward-compat).
- *
- * Entities without a `Children` component surface as leaves.
- */
-export function collectSubtree(
-  world: World,
-  spawnRoot: EntityHandle,
-  visited?: Set<number>,
-): Set<number> {
-  if (visited === undefined) visited = new Set<number>();
-  if (visited.has(spawnRoot as number)) return visited;
-  const queue: number[] = [spawnRoot as number];
-  visited.add(spawnRoot as number);
-  while (queue.length > 0) {
-    const cur = queue.shift() as number;
-    const childrenData = world.get(cur as EntityHandle, Children);
-    if (!childrenData.ok) continue;
-    const list = childrenData.value.entities as ArrayLike<number>;
-    for (let i = 0; i < list.length; i++) {
-      const child = list[i] as number;
-      if (visited.has(child)) continue;
-      visited.add(child);
-      queue.push(child);
-    }
-  }
-  return visited;
-}

package/src/ssao-data.ts

@@ -1,106 +0,0 @@
-// @forgeax/engine-runtime — SSAO kernel + noise data generation.
-//
-// feat-20260612-hdrp-ssao M1 / w2.
-//
-// Implements the LO 5.9 host-side algorithm (research F1 + F2):
-//  - generateSsaoKernel: 64 vec3 hemisphere samples with quadratic falloff
-//    bias (lerp(0.1, 1.0, (i/64)^2)), deterministic given a seed.
-//  - generateSsaoNoise: 4x4 vec3 rotation vectors (z=0 tangent-plane),
-//    deterministic given a seed.
-//
-// Both are one-shot, host-side generated (requirements OOS-7: no runtime
-// regeneration). Output fits directly into Float32Array for writeBuffer upload.
-//
-// The mulberry32 PRNG is used for deterministic reproducibility across
-// runs — same seed always yields same kernel/noise (AC-03 snapshot).
-
-export const SSAO_KERNEL_SAMPLE_COUNT = 64;
-const NOISE_SIZE = 16; // 4 x 4
-
-/**
- * Mulberry32 PRNG — fast 32-bit deterministic generator.
- * Returns a float in [0, 1).
- */
-function mulberry32(seed: number): () => number {
-  let state = seed | 0;
-  return () => {
-    state = (state + 0x6d2b79f5) | 0;
-    let t = Math.imul(state ^ (state >>> 15), 1 | state);
-    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
-    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
-  };
-}
-
-function lerp(a: number, b: number, t: number): number {
-  return a + t * (b - a);
-}
-
-/**
- * Generate 64 SSAO hemisphere sample vectors (tangent-space, z >= 0).
- *
- * Algorithm (LO 5.9, research F1):
- *  1. Random direction on unit sphere with z >= 0.
- *  2. Normalize.
- *  3. Scale by random [0,1].
- *  4. Scale by lerp(0.1, 1.0, (i/64)^2) for quadratic falloff.
- *
- * Each sample is returned as a `[x, y, z]` tuple in a `Float32Array`
- * slice — 64 slices of 3 floats each, packed contiguously for upload.
- *
- * @param seed Optional PRNG seed (default 0). Same seed always produces
- *   the same kernel.
- * @returns Array of 64 `[x, y, z]` arrays (each Float32Array length 3).
- */
-export function generateSsaoKernel(seed: number = 0): readonly Float32Array[] {
-  const rand = mulberry32(seed);
-  const kernel: Float32Array[] = [];
-  for (let i = 0; i < SSAO_KERNEL_SAMPLE_COUNT; i++) {
-    // Step 1: random direction on unit hemisphere (z >= 0)
-    let x = rand() * 2 - 1;
-    let y = rand() * 2 - 1;
-    let z = rand(); // [0, 1] => z >= 0 hemisphere
-    // Step 1b: normalize
-    const len = Math.sqrt(x * x + y * y + z * z);
-    x /= len;
-    y /= len;
-    z /= len;
-    // Step 2: random length [0, 1]
-    const r = rand();
-    x *= r;
-    y *= r;
-    z *= r;
-    // Step 3: quadratic falloff — more samples near origin
-    const scale = lerp(0.1, 1.0, (i / SSAO_KERNEL_SAMPLE_COUNT) * (i / SSAO_KERNEL_SAMPLE_COUNT));
-    const sample = new Float32Array(3);
-    sample[0] = x * scale;
-    sample[1] = y * scale;
-    sample[2] = z * scale;
-    kernel.push(sample);
-  }
-  return kernel;
-}
-
-/**
- * Generate 4x4 noise rotation vectors (tangent-space, z = 0).
- *
- * Algorithm (LO 5.9, research F2):
- *  16 vec3 vectors with random xy directions and z = 0.
- *  Used by shader to rotate the 64-sample kernel per-pixel via
- *  tiled sampling (REPEAT addressing).
- *
- * Returns a flat Float32Array of 48 floats (16 vectors x 3
- * components each), suitable for upload as a 4x4 rgba32float texture.
- *
- * @param seed Optional PRNG seed (default 0).
- * @returns Float32Array of length 48.
- */
-export function generateSsaoNoise(seed: number = 0): Float32Array {
-  const rand = mulberry32(seed);
-  const noise = new Float32Array(NOISE_SIZE * 3); // 16 * 3 = 48
-  for (let i = 0; i < NOISE_SIZE; i++) {
-    noise[i * 3 + 0] = rand() * 2 - 1;
-    noise[i * 3 + 1] = rand() * 2 - 1;
-    noise[i * 3 + 2] = 0; // tangent-plane rotation (z = 0)
-  }
-  return noise;
-}

package/src/surface-format.ts

@@ -1,37 +0,0 @@
-import type { RhiDevice } from '@forgeax/engine-rhi';
-
-export interface SwapChainFormatPair {
-  readonly storage: GPUTextureFormat;
-  readonly view: GPUTextureFormat;
-  readonly fallbackReason?: 'preferred-canvas-format-missing';
-}
-
-export type SurfaceBackendKind = RhiDevice['caps']['backendKind'];
-
-export function resolveSurfaceFormatPair(
-  backendKind: SurfaceBackendKind,
-  storage: GPUTextureFormat,
-  view: GPUTextureFormat,
-): SwapChainFormatPair {
-  return backendKind === 'wgpu-webgl2' ? { storage: view, view } : { storage, view };
-}
-
-export function selectSwapChainFormat(storageBufferCapable: boolean): SwapChainFormatPair {
-  if (!storageBufferCapable) {
-    return { storage: 'rgba8unorm', view: 'rgba8unorm-srgb' };
-  }
-  const nav = (
-    globalThis as { navigator?: { gpu?: { getPreferredCanvasFormat?: () => GPUTextureFormat } } }
-  ).navigator;
-  const gpu = nav?.gpu;
-  const getPreferred = gpu?.getPreferredCanvasFormat;
-  if (gpu !== undefined && typeof getPreferred === 'function') {
-    const storage = getPreferred.call(gpu);
-    return { storage, view: `${storage}-srgb` as unknown as GPUTextureFormat };
-  }
-  return {
-    storage: 'rgba8unorm',
-    view: 'rgba8unorm-srgb',
-    fallbackReason: 'preferred-canvas-format-missing',
-  };
-}

package/src/taa-history-store.ts

@@ -1,429 +0,0 @@
-import type {
-  CompiledRenderGraph,
-  GraphTexture,
-  GraphTextureView,
-  RenderGraphBuilder,
-  RenderGraphError,
-} from '@forgeax/engine-render-graph';
-import type { RhiDevice, RhiError, Texture, TextureFormat } from '@forgeax/engine-rhi';
-import { err, ok, type Result } from '@forgeax/engine-types';
-import {
-  GPU_TEXTURE_USAGE_COPY_SRC,
-  GPU_TEXTURE_USAGE_RENDER_ATTACHMENT_AND_TEXTURE_BINDING,
-} from './gpu-texture-usage';
-import type { RenderPipelineFrame } from './render-pipeline';
-import type { TemporalHistoryDirection } from './temporal-frame-transaction';
-import type { TemporalView, TemporalViewResetReason } from './temporal-view';
-
-const HISTORY_FORMAT: TextureFormat = 'rgba16float';
-const HISTORY_TEXTURE_COUNT = 4;
-const RGBA16FLOAT_BYTES_PER_PIXEL = 8;
-const HISTORY_USAGE =
-  GPU_TEXTURE_USAGE_RENDER_ATTACHMENT_AND_TEXTURE_BINDING | GPU_TEXTURE_USAGE_COPY_SRC;
-
-export type TaaHistoryResetReason =
-  | TemporalViewResetReason
-  | 'resize'
-  | 'format-changed'
-  | 'pipeline-owner-changed'
-  | 'world-detached'
-  | 'coverage-incomplete'
-  | 'environment-published'
-  | 'device-recovery';
-
-export interface TaaHistoryInspection {
-  readonly enabled: boolean;
-  readonly ownerGeneration: number;
-  readonly viewId: string | undefined;
-  readonly width: number;
-  readonly height: number;
-  readonly format: TextureFormat | undefined;
-  readonly direction: TemporalHistoryDirection;
-  readonly valid: boolean;
-  readonly resetReason: TaaHistoryResetReason | undefined;
-  readonly historyBytes: number;
-  readonly retiringGenerations: number;
-}
-
-export interface TaaHistoryPrepareInput {
-  readonly enabled: boolean;
-  readonly width: number;
-  readonly height: number;
-  readonly viewId: string;
-  readonly pipelineOwnerGeneration: number;
-  readonly surfaceFormat: TextureFormat;
-}
-
-export interface TaaHistoryGraphResources {
-  readonly colorRead: { readonly texture: GraphTexture; readonly view: GraphTextureView };
-  readonly colorWrite: { readonly texture: GraphTexture; readonly view: GraphTextureView };
-  readonly temporalRead: { readonly texture: GraphTexture; readonly view: GraphTextureView };
-  readonly temporalWrite: { readonly texture: GraphTexture; readonly view: GraphTextureView };
-}
-
-interface TaaHistoryConfig {
-  readonly width: number;
-  readonly height: number;
-  readonly viewId: string;
-  readonly pipelineOwnerGeneration: number;
-  readonly surfaceFormat: TextureFormat;
-}
-
-interface TaaHistoryGeneration {
-  readonly ownerGeneration: number;
-  readonly config: TaaHistoryConfig;
-  readonly textures: readonly [Texture, Texture, Texture, Texture];
-  readonly bytes: number;
-  refs: number;
-  abandoned: boolean;
-  destroyed: boolean;
-}
-
-export interface TaaHistoryPreparation {
-  readonly enabled: boolean;
-  readonly ownerGeneration: number;
-  readonly resetReason: TaaHistoryResetReason | undefined;
-  importResources(
-    graph: RenderGraphBuilder<RenderPipelineFrame>,
-  ): Result<TaaHistoryGraphResources | undefined, RenderGraphError>;
-}
-
-export interface TaaHistoryFrameAttempt {
-  readonly direction: TemporalHistoryDirection;
-  readonly valid: boolean;
-  readonly resetReason: TaaHistoryResetReason | undefined;
-  commit(): void;
-  abort(): void;
-}
-
-interface MutablePreparation extends TaaHistoryPreparation {
-  readonly generation: TaaHistoryGeneration | undefined;
-  readonly created: boolean;
-  state: 'prepared' | 'committed' | 'aborted';
-}
-
-function historyTextureIndex(
-  semanticIndex: number,
-  direction: TemporalHistoryDirection,
-): 0 | 1 | 2 | 3 {
-  const readOffset = direction === 'a-to-b' ? 0 : 1;
-  if (semanticIndex < 2) return (semanticIndex === 0 ? readOffset : 1 - readOffset) as 0 | 1;
-  return (semanticIndex === 2 ? readOffset + 2 : 3 - readOffset) as 2 | 3;
-}
-
-function configResetReason(
-  current: TaaHistoryGeneration | undefined,
-  next: TaaHistoryConfig,
-): TaaHistoryResetReason | undefined {
-  if (current === undefined) return 'first-frame';
-  if (current.config.width !== next.width || current.config.height !== next.height) return 'resize';
-  if (current.config.surfaceFormat !== next.surfaceFormat) return 'format-changed';
-  if (current.config.viewId !== next.viewId) return 'camera-switch';
-  if (current.config.pipelineOwnerGeneration !== next.pipelineOwnerGeneration) {
-    return 'pipeline-owner-changed';
-  }
-  return undefined;
-}
-
-function sameConfig(left: TaaHistoryConfig, right: TaaHistoryConfig): boolean {
-  return (
-    left.width === right.width &&
-    left.height === right.height &&
-    left.viewId === right.viewId &&
-    left.pipelineOwnerGeneration === right.pipelineOwnerGeneration &&
-    left.surfaceFormat === right.surfaceFormat
-  );
-}
-
-/** Renderer-owned active-view TAA history and compiled-graph generation leases. */
-export class TaaHistoryStore {
-  private active: TaaHistoryGeneration | undefined;
-  private readonly generations = new Set<TaaHistoryGeneration>();
-  private readonly graphGenerations = new WeakMap<object, TaaHistoryGeneration>();
-  private nextOwnerGeneration = 1;
-  private direction: TemporalHistoryDirection = 'a-to-b';
-  private valid = false;
-  private resetReason: TaaHistoryResetReason | undefined;
-  private forcedResetReason: TaaHistoryResetReason | undefined;
-  private disposed = false;
-
-  constructor(private readonly device: RhiDevice) {}
-
-  prepare(input: TaaHistoryPrepareInput): Result<TaaHistoryPreparation, RhiError> {
-    if (!input.enabled) return ok(this.preparation(undefined, false, undefined));
-    const config: TaaHistoryConfig = {
-      width: Math.max(1, Math.trunc(input.width)),
-      height: Math.max(1, Math.trunc(input.height)),
-      viewId: input.viewId,
-      pipelineOwnerGeneration: input.pipelineOwnerGeneration,
-      surfaceFormat: input.surfaceFormat,
-    };
-    const reusable =
-      this.forcedResetReason === undefined &&
-      this.active !== undefined &&
-      !this.active.destroyed &&
-      sameConfig(this.active.config, config)
-        ? this.active
-        : undefined;
-    if (reusable !== undefined) return ok(this.preparation(reusable, false, undefined));
-    const resetReason = this.forcedResetReason ?? configResetReason(this.active, config);
-    const created = this.allocate(config);
-    return created.ok ? ok(this.preparation(created.value, true, resetReason)) : created;
-  }
-
-  commitGraph(
-    graph: CompiledRenderGraph<RenderPipelineFrame>,
-    preparation: TaaHistoryPreparation,
-  ): void {
-    const mutable = preparation as MutablePreparation;
-    if (mutable.state !== 'prepared') return;
-    mutable.state = 'committed';
-    this.forcedResetReason = undefined;
-    if (mutable.generation === undefined) {
-      this.active = undefined;
-      this.direction = 'a-to-b';
-      this.valid = false;
-      this.resetReason = undefined;
-      return;
-    }
-    mutable.generation.refs += 1;
-    this.graphGenerations.set(graph, mutable.generation);
-    if (this.active !== mutable.generation) {
-      this.active = mutable.generation;
-      this.direction = 'a-to-b';
-      this.valid = false;
-      this.resetReason = mutable.resetReason;
-    }
-  }
-
-  abort(preparation: TaaHistoryPreparation): void {
-    const mutable = preparation as MutablePreparation;
-    if (mutable.state !== 'prepared') return;
-    mutable.state = 'aborted';
-    if (mutable.created && mutable.generation !== undefined) this.destroy(mutable.generation);
-  }
-
-  retireGraph(
-    graph: CompiledRenderGraph<RenderPipelineFrame>,
-  ): ReturnType<CompiledRenderGraph<RenderPipelineFrame>['retire']> {
-    const generation = this.graphGenerations.get(graph);
-    this.graphGenerations.delete(graph);
-    const retired = graph.retire();
-    if (generation !== undefined) {
-      retired.finally(() => this.release(generation)).catch(() => undefined);
-    }
-    return retired;
-  }
-
-  beginFrame(view: TemporalView | undefined, coverageComplete = true): TaaHistoryFrameAttempt {
-    const direction = this.direction;
-    const resetReason = !coverageComplete
-      ? 'coverage-incomplete'
-      : !this.valid &&
-          this.resetReason !== undefined &&
-          this.resetReason !== 'environment-published'
-        ? this.resetReason
-        : (view?.resetReason ?? this.resetReason);
-    const valid =
-      view !== undefined &&
-      coverageComplete &&
-      this.active !== undefined &&
-      this.valid &&
-      view.historyValid;
-    let state: 'active' | 'committed' | 'aborted' = 'active';
-    return {
-      direction,
-      valid,
-      resetReason,
-      commit: () => {
-        if (state !== 'active') return;
-        state = 'committed';
-        if (view === undefined || this.active === undefined) {
-          this.direction = 'a-to-b';
-          this.valid = false;
-          return;
-        }
-        this.direction = direction === 'a-to-b' ? 'b-to-a' : 'a-to-b';
-        this.valid = coverageComplete;
-        this.resetReason = coverageComplete
-          ? (view.resetReason ?? this.resetReason)
-          : 'coverage-incomplete';
-      },
-      abort: () => {
-        if (state === 'active') state = 'aborted';
-      },
-    };
-  }
-
-  invalidate(reason: TaaHistoryResetReason): void {
-    this.valid = false;
-    this.direction = 'a-to-b';
-    this.resetReason = reason;
-    this.forcedResetReason = reason;
-  }
-
-  inspect(): TaaHistoryInspection {
-    const active = this.active;
-    return {
-      enabled: active !== undefined,
-      ownerGeneration: active?.ownerGeneration ?? 0,
-      viewId: active?.config.viewId,
-      width: active?.config.width ?? 0,
-      height: active?.config.height ?? 0,
-      format: active === undefined ? undefined : HISTORY_FORMAT,
-      direction: this.direction,
-      valid: this.valid,
-      resetReason: this.resetReason,
-      historyBytes: active?.bytes ?? 0,
-      retiringGenerations: [...this.generations].filter(
-        (generation) => generation !== active && !generation.destroyed,
-      ).length,
-    };
-  }
-
-  resetForRecover(): void {
-    for (const generation of this.generations) generation.abandoned = true;
-    this.active = undefined;
-    this.direction = 'a-to-b';
-    this.valid = false;
-    this.resetReason = 'device-recovery';
-    this.forcedResetReason = 'device-recovery';
-  }
-
-  dispose(): void {
-    if (this.disposed) return;
-    this.disposed = true;
-    this.active = undefined;
-    for (const generation of this.generations) {
-      if (generation.refs === 0) this.destroy(generation);
-    }
-  }
-
-  private allocate(config: TaaHistoryConfig): Result<TaaHistoryGeneration, RhiError> {
-    const textures: Texture[] = [];
-    for (let index = 0; index < HISTORY_TEXTURE_COUNT; index += 1) {
-      const created = this.device.createTexture({
-        label: `taa-history-${index}`,
-        size: { width: config.width, height: config.height, depthOrArrayLayers: 1 },
-        mipLevelCount: 1,
-        sampleCount: 1,
-        dimension: '2d',
-        format: HISTORY_FORMAT,
-        usage: HISTORY_USAGE,
-        textureBindingViewDimension: undefined,
-        viewFormats: [],
-      });
-      if (!created.ok) {
-        for (const texture of textures) this.device.destroyTexture(texture);
-        return err(created.error);
-      }
-      textures.push(created.value);
-    }
-    const generation: TaaHistoryGeneration = {
-      ownerGeneration: this.nextOwnerGeneration,
-      config,
-      textures: textures as unknown as readonly [Texture, Texture, Texture, Texture],
-      bytes: HISTORY_TEXTURE_COUNT * RGBA16FLOAT_BYTES_PER_PIXEL * config.width * config.height,
-      refs: 0,
-      abandoned: false,
-      destroyed: false,
-    };
-    this.nextOwnerGeneration += 1;
-    this.generations.add(generation);
-    return ok(generation);
-  }
-
-  private preparation(
-    generation: TaaHistoryGeneration | undefined,
-    created: boolean,
-    resetReason: TaaHistoryResetReason | undefined,
-  ): MutablePreparation {
-    const preparation: MutablePreparation = {
-      enabled: generation !== undefined,
-      ownerGeneration: generation?.ownerGeneration ?? 0,
-      resetReason,
-      generation,
-      created,
-      state: 'prepared',
-      importResources: (graph) => this.importResources(graph, generation),
-    };
-    return preparation;
-  }
-
-  private importResources(
-    graph: RenderGraphBuilder<RenderPipelineFrame>,
-    generation: TaaHistoryGeneration | undefined,
-  ): Result<TaaHistoryGraphResources | undefined, RenderGraphError> {
-    if (generation === undefined) return ok(undefined);
-    const labels = ['color-read', 'color-write', 'temporal-read', 'temporal-write'] as const;
-    const textures: GraphTexture[] = [];
-    const views: GraphTextureView[] = [];
-    for (let index = 0; index < labels.length; index += 1) {
-      const semanticIndex = index;
-      const texture = graph.importTexture(
-        `taa-history-${labels[index]}`,
-        {
-          format: HISTORY_FORMAT,
-          size: {
-            width: generation.config.width,
-            height: generation.config.height,
-            depthOrArrayLayers: 1,
-          },
-          mipLevelCount: 1,
-          sampleCount: 1,
-          dimension: '2d',
-          usage: HISTORY_USAGE,
-          viewFormats: [],
-        },
-        (frame) => {
-          const temporalFrame = (
-            frame as RenderPipelineFrame & {
-              readonly temporalFrame?: { readonly historyDirection: TemporalHistoryDirection };
-            }
-          ).temporalFrame;
-          if (temporalFrame === undefined) {
-            throw new RangeError('TAA history resolution requires an active temporal frame');
-          }
-          const physicalIndex = historyTextureIndex(semanticIndex, temporalFrame.historyDirection);
-          return generation.textures[physicalIndex] as Texture;
-        },
-      );
-      if (!texture.ok) return texture;
-      const view = graph.view(texture.value, { label: `taa-history-${labels[index]}.view` });
-      if (!view.ok) return view;
-      textures.push(texture.value);
-      views.push(view.value);
-    }
-    return ok({
-      colorRead: {
-        texture: textures[0] as GraphTexture,
-        view: views[0] as GraphTextureView,
-      },
-      colorWrite: {
-        texture: textures[1] as GraphTexture,
-        view: views[1] as GraphTextureView,
-      },
-      temporalRead: {
-        texture: textures[2] as GraphTexture,
-        view: views[2] as GraphTextureView,
-      },
-      temporalWrite: {
-        texture: textures[3] as GraphTexture,
-        view: views[3] as GraphTextureView,
-      },
-    });
-  }
-
-  private release(generation: TaaHistoryGeneration): void {
-    generation.refs = Math.max(0, generation.refs - 1);
-    if (generation.refs === 0 && generation !== this.active) this.destroy(generation);
-  }
-
-  private destroy(generation: TaaHistoryGeneration): void {
-    if (generation.destroyed) return;
-    generation.destroyed = true;
-    this.generations.delete(generation);
-    if (generation.abandoned) return;
-    for (const texture of generation.textures) this.device.destroyTexture(texture);
-  }
-}