@clypra/runtime 1.0.0

package/src/planner/optimizer.ts

@@ -0,0 +1,247 @@
+/**
+ * @clypra/runtime — Frame Graph Optimizer
+ *
+ * Optimizes frame graphs for better performance.
+ * - Merges redundant passes
+ * - Reorders passes for better cache locality
+ * - Reduces transient resource usage
+ */
+
+import type { FrameGraph, RenderPass, ResourceRequest } from "./types";
+
+export interface OptimizationResult {
+  optimized: FrameGraph;
+  stats: {
+    passesRemoved: number;
+    resourcesReduced: number;
+    estimatedSavingsMs: number;
+  };
+}
+
+/**
+ * FrameGraphOptimizer - Optimizes frame graphs
+ */
+export class FrameGraphOptimizer {
+  /**
+   * Optimize a frame graph
+   */
+  optimize(frameGraph: FrameGraph): OptimizationResult {
+    let optimized = frameGraph;
+    let passesRemoved = 0;
+    let resourcesReduced = 0;
+
+    // Merge redundant passes
+    const { passes: mergedPasses, removed: passRemoved } = this.mergeRedundantPasses(optimized.passes);
+    passesRemoved += passRemoved;
+    optimized = { ...optimized, passes: mergedPasses };
+
+    // Reduce transient resources
+    const { resources: reducedResources, reduced: resourceReduced } = this.reduceTransientResources(optimized.resourceRequests, optimized.passes);
+    resourcesReduced += resourceReduced;
+    optimized = { ...optimized, resourceRequests: reducedResources };
+
+    // Reorder passes for cache locality
+    const reorderedPasses = this.reorderPasses(optimized.passes);
+    optimized = { ...optimized, passes: reorderedPasses };
+
+    return {
+      optimized,
+      stats: {
+        passesRemoved,
+        resourcesReduced,
+        estimatedSavingsMs: this.estimateSavings(passesRemoved, resourcesReduced),
+      },
+    };
+  }
+
+  /**
+   * Merge redundant passes
+   */
+  private mergeRedundantPasses(passes: readonly RenderPass[]): {
+    passes: readonly RenderPass[];
+    removed: number;
+  } {
+    const merged: RenderPass[] = [];
+    const seen = new Set<string>();
+    let removed = 0;
+
+    for (const pass of passes) {
+      // Create a key based on shader and inputs
+      const key = `${pass.shaderId}:${pass.inputs.join(",")}`;
+
+      if (seen.has(key)) {
+        removed++;
+        continue;
+      }
+
+      seen.add(key);
+      merged.push(pass);
+    }
+
+    return { passes: merged, removed };
+  }
+
+  /**
+   * Reduce transient resource allocations
+   */
+  private reduceTransientResources(
+    resources: readonly ResourceRequest[],
+    passes: readonly RenderPass[],
+  ): {
+    resources: readonly ResourceRequest[];
+    reduced: number;
+  } {
+    const reduced: ResourceRequest[] = [];
+    const transient: ResourceRequest[] = [];
+    let reducedCount = 0;
+
+    // Separate transient from persistent
+    for (const resource of resources) {
+      if (resource.transient) {
+        transient.push(resource);
+      } else {
+        reduced.push(resource);
+      }
+    }
+
+    // Build resource usage map
+    const usage = this.buildResourceUsageMap(transient, passes);
+
+    // Pool transient resources that don't overlap
+    const pooled = this.poolResources(transient, usage);
+    reducedCount = transient.length - pooled.length;
+
+    reduced.push(...pooled);
+
+    return { resources: reduced, reduced: reducedCount };
+  }
+
+  /**
+   * Build resource usage map (which passes use which resources)
+   */
+  private buildResourceUsageMap(resources: ResourceRequest[], passes: readonly RenderPass[]): Map<string, number[]> {
+    const usage = new Map<string, number[]>();
+
+    for (const resource of resources) {
+      usage.set(resource.id, []);
+    }
+
+    passes.forEach((pass, index) => {
+      for (const input of pass.inputs) {
+        if (usage.has(input)) {
+          usage.get(input)!.push(index);
+        }
+      }
+      if (usage.has(pass.output)) {
+        usage.get(pass.output)!.push(index);
+      }
+    });
+
+    return usage;
+  }
+
+  /**
+   * Pool resources that don't have overlapping usage
+   */
+  private poolResources(resources: ResourceRequest[], usage: Map<string, number[]>): ResourceRequest[] {
+    const pooled: ResourceRequest[] = [];
+    const processed = new Set<string>();
+
+    for (const resource of resources) {
+      if (processed.has(resource.id)) continue;
+
+      const resourceUsage = usage.get(resource.id) || [];
+
+      // Try to find another resource with non-overlapping usage
+      let found = false;
+      for (const other of resources) {
+        if (other.id === resource.id || processed.has(other.id)) continue;
+        if (other.format !== resource.format) continue;
+        if (other.width !== resource.width || other.height !== resource.height) continue;
+
+        const otherUsage = usage.get(other.id) || [];
+
+        // Check if usage overlaps
+        const overlaps = resourceUsage.some((idx) => otherUsage.includes(idx));
+        if (!overlaps) {
+          // Can reuse this resource
+          processed.add(other.id);
+          found = true;
+        }
+      }
+
+      if (!found || pooled.length === 0) {
+        pooled.push(resource);
+      }
+      processed.add(resource.id);
+    }
+
+    return pooled;
+  }
+
+  /**
+   * Reorder passes for better cache locality
+   */
+  private reorderPasses(passes: readonly RenderPass[]): readonly RenderPass[] {
+    // Build dependency graph
+    const deps = new Map<string, Set<string>>();
+    const inDegree = new Map<string, number>();
+
+    for (const pass of passes) {
+      deps.set(pass.id, new Set());
+      inDegree.set(pass.id, 0);
+    }
+
+    // Calculate dependencies
+    for (const pass of passes) {
+      for (const input of pass.inputs) {
+        // Find pass that outputs this resource
+        const producer = passes.find((p) => p.output === input);
+        if (producer) {
+          deps.get(pass.id)!.add(producer.id);
+          inDegree.set(pass.id, inDegree.get(pass.id)! + 1);
+        }
+      }
+    }
+
+    // Topological sort (Kahn's algorithm)
+    const sorted: RenderPass[] = [];
+    const queue: RenderPass[] = [];
+
+    // Start with passes that have no dependencies
+    for (const pass of passes) {
+      if (inDegree.get(pass.id) === 0) {
+        queue.push(pass);
+      }
+    }
+
+    while (queue.length > 0) {
+      const pass = queue.shift()!;
+      sorted.push(pass);
+
+      // Update in-degrees
+      for (const other of passes) {
+        if (deps.get(other.id)!.has(pass.id)) {
+          const newDegree = inDegree.get(other.id)! - 1;
+          inDegree.set(other.id, newDegree);
+
+          if (newDegree === 0) {
+            queue.push(other);
+          }
+        }
+      }
+    }
+
+    return sorted;
+  }
+
+  /**
+   * Estimate performance savings
+   */
+  private estimateSavings(passesRemoved: number, resourcesReduced: number): number {
+    // Rough estimates:
+    // - Each pass costs ~1ms
+    // - Each resource allocation costs ~0.5ms
+    return passesRemoved * 1.0 + resourcesReduced * 0.5;
+  }
+}

package/src/planner/planner.ts

@@ -0,0 +1,201 @@
+/**
+ * @clypra/runtime — Frame Graph Planner
+ *
+ * Converts media processing graphs into executable frame graphs.
+ */
+
+import type { MediaProcessingGraph, GraphNode } from "../graph/types";
+import { GraphHelper } from "../graph/types";
+import type { FrameGraph, ResourceRequest, RenderPass, PlannerConfig } from "./types";
+
+/**
+ * FrameGraphPlanner - Plans frame execution from media processing graphs
+ */
+export class FrameGraphPlanner {
+  private config: PlannerConfig;
+
+  constructor(config: Partial<PlannerConfig> = {}) {
+    this.config = {
+      targetWidth: config.targetWidth || 1920,
+      targetHeight: config.targetHeight || 1080,
+      enableOptimizations: config.enableOptimizations ?? true,
+      allowHalfResolution: config.allowHalfResolution ?? true,
+      maxTransientResources: config.maxTransientResources || 8,
+    };
+  }
+
+  /**
+   * Plan frame execution for a specific frame number
+   */
+  plan(graph: MediaProcessingGraph, frameNumber: number, timeMs: number): FrameGraph {
+    // Get topologically sorted nodes
+    const sortedNodes = GraphHelper.topologicalSort(graph);
+
+    // Filter active nodes (for now, all nodes are active)
+    const activeNodes = this.filterActiveNodes(sortedNodes, frameNumber);
+
+    // Generate resource requests
+    const resourceRequests = this.generateResourceRequests(activeNodes);
+
+    // Generate render passes
+    const passes = this.generateRenderPasses(graph, activeNodes);
+
+    return {
+      frameNumber,
+      timelineTimeMs: timeMs,
+      nodes: activeNodes,
+      edges: graph.edges,
+      resourceRequests,
+      passes,
+    };
+  }
+
+  /**
+   * Filter nodes that contribute to the current frame
+   */
+  private filterActiveNodes(nodes: readonly GraphNode[], frameNumber: number): readonly GraphNode[] {
+    // For now, all nodes are active
+    // In the future, we can skip nodes based on temporal properties, conditions, etc.
+    return nodes.filter((node) => {
+      // Skip nodes that are disabled or culled
+      if (node.lifecycle === "Disposed") return false;
+
+      // Include all other nodes
+      return true;
+    });
+  }
+
+  /**
+   * Generate resource requests for active nodes
+   */
+  private generateResourceRequests(nodes: readonly GraphNode[]): readonly ResourceRequest[] {
+    const requests: ResourceRequest[] = [];
+    let resourceId = 0;
+
+    for (const node of nodes) {
+      // Input resources (from MediaInput nodes)
+      if (node.type === "MediaInput") {
+        requests.push({
+          id: `resource-${resourceId++}`,
+          type: "texture",
+          width: this.config.targetWidth,
+          height: this.config.targetHeight,
+          format: "rgba8",
+          transient: false,
+        });
+      }
+
+      // Output resources
+      const outputKeys = Object.keys(node.outputs);
+      for (const outputKey of outputKeys) {
+        const output = node.outputs[outputKey];
+        const format = this.getFormatForType(output.type);
+
+        requests.push({
+          id: `resource-${resourceId++}`,
+          type: "texture",
+          width: this.config.targetWidth,
+          height: this.config.targetHeight,
+          format,
+          transient: node.type !== "Output", // Output resource is not transient
+        });
+      }
+
+      // Temporary resources for multipass effects
+      if (node.requirements.multipass) {
+        requests.push({
+          id: `resource-${resourceId++}-temp`,
+          type: "texture",
+          width: this.config.targetWidth,
+          height: this.config.targetHeight,
+          format: "rgba16f",
+          transient: true,
+        });
+      }
+    }
+
+    return requests;
+  }
+
+  /**
+   * Generate render passes from nodes
+   */
+  private generateRenderPasses(graph: MediaProcessingGraph, nodes: readonly GraphNode[]): readonly RenderPass[] {
+    const passes: RenderPass[] = [];
+
+    for (const node of nodes) {
+      // Skip input and output nodes (they don't have shaders)
+      if (node.type === "MediaInput" || node.type === "Output") {
+        continue;
+      }
+
+      // Get input resources
+      const inputResourceIds: string[] = [];
+      const incomingEdges = GraphHelper.getIncomingEdges(graph, node.id);
+      for (const edge of incomingEdges) {
+        // Find the resource ID for this edge
+        // For now, use a simple naming scheme
+        inputResourceIds.push(`${edge.fromNodeId}-${edge.fromPinId}`);
+      }
+
+      // Get output resource
+      const outputResourceId = `${node.id}-output`;
+
+      // Create pass
+      const pass: RenderPass = {
+        id: `pass-${node.id}`,
+        name: node.type,
+        shaderId: node.type,
+        inputs: inputResourceIds,
+        output: outputResourceId,
+        uniforms: node.params,
+      };
+
+      passes.push(pass);
+
+      // If multipass, add additional passes
+      if (node.requirements.multipass) {
+        // Add a second pass (e.g., for blur, we'd do horizontal then vertical)
+        passes.push({
+          id: `pass-${node.id}-2`,
+          name: `${node.type}-pass2`,
+          shaderId: `${node.type}-pass2`,
+          inputs: [outputResourceId],
+          output: `${node.id}-output-final`,
+          uniforms: node.params,
+        });
+      }
+    }
+
+    return passes;
+  }
+
+  /**
+   * Get texture format based on data type
+   */
+  private getFormatForType(type: string): "rgba8" | "rgba16f" | "rgba32f" | "r8" | "depth24" {
+    switch (type) {
+      case "Depth":
+        return "depth24";
+      case "Mask":
+        return "r8";
+      case "Texture":
+      default:
+        return "rgba8";
+    }
+  }
+
+  /**
+   * Update configuration
+   */
+  updateConfig(config: Partial<PlannerConfig>): void {
+    this.config = { ...this.config, ...config };
+  }
+
+  /**
+   * Get current configuration
+   */
+  getConfig(): PlannerConfig {
+    return { ...this.config };
+  }
+}

package/src/planner/types.ts

@@ -0,0 +1,56 @@
+/**
+ * @clypra/runtime — Planner Types
+ *
+ * Defines transient planning constructs: resource requests, frame-isolated graphs, and render passes.
+ */
+
+import type { GraphNode, GraphEdge } from "../graph/types";
+
+export interface ResourceRequest {
+  readonly id: string;
+  readonly type: "texture" | "buffer";
+  readonly width: number;
+  readonly height: number;
+  readonly format: "rgba8" | "rgba16f" | "rgba32f" | "r8" | "depth24";
+  readonly transient: boolean; // True if it can be reclaimed after the pass completes
+}
+
+export interface RenderPass {
+  readonly id: string;
+  readonly name: string;
+  readonly shaderId: string;
+  readonly inputs: readonly string[]; // Active resource IDs
+  readonly output: string; // Target resource ID
+  readonly uniforms: Readonly<Record<string, any>>;
+  readonly blendMode?: string;
+  readonly clearBeforeRender?: boolean;
+}
+
+/**
+ * A flattened, active graph containing only nodes contributing to a specific frame.
+ */
+export interface FrameGraph {
+  readonly frameNumber: number;
+  readonly timelineTimeMs: number;
+  readonly nodes: readonly GraphNode[];
+  readonly edges: readonly GraphEdge[];
+  readonly resourceRequests: readonly ResourceRequest[];
+  readonly passes: readonly RenderPass[];
+}
+
+export interface DependencyGraph {
+  readonly executionOrder: readonly string[]; // Topologically sorted list of node IDs
+  readonly readDependencies: Readonly<Record<string, readonly string[]>>; // nodeId -> list of input resource IDs
+  readonly writeDependencies: Readonly<Record<string, string>>; // nodeId -> output resource ID
+}
+
+/**
+ * Planner configuration
+ */
+export interface PlannerConfig {
+  readonly targetWidth: number;
+  readonly targetHeight: number;
+  readonly enableOptimizations: boolean;
+  readonly allowHalfResolution: boolean;
+  readonly maxTransientResources: number;
+}

package/src/resources/cache.ts

@@ -0,0 +1,166 @@
+/**
+ * @clypra/runtime — LRU Cache
+ *
+ * Generic LRU cache for resource management.
+ */
+
+export interface CacheEntry<T> {
+  key: string;
+  value: T;
+  size: number;
+  lastUsed: number;
+}
+
+export interface CacheStats {
+  size: number;
+  capacity: number;
+  hits: number;
+  misses: number;
+  evictions: number;
+}
+
+/**
+ * Least Recently Used (LRU) Cache
+ */
+export class LRUCache<T> {
+  private cache = new Map<string, CacheEntry<T>>();
+  private capacity: number;
+  private currentSize = 0;
+  private hits = 0;
+  private misses = 0;
+  private evictions = 0;
+
+  constructor(capacity: number) {
+    this.capacity = capacity;
+  }
+
+  /**
+   * Get a value from the cache
+   */
+  get(key: string): T | undefined {
+    const entry = this.cache.get(key);
+
+    if (entry) {
+      // Update last used time
+      entry.lastUsed = Date.now();
+      this.hits++;
+      return entry.value;
+    }
+
+    this.misses++;
+    return undefined;
+  }
+
+  /**
+   * Put a value into the cache
+   */
+  put(key: string, value: T, size: number = 1): void {
+    // Remove existing entry if present
+    if (this.cache.has(key)) {
+      const existing = this.cache.get(key)!;
+      this.currentSize -= existing.size;
+      this.cache.delete(key);
+    }
+
+    // Evict entries if necessary
+    while (this.currentSize + size > this.capacity && this.cache.size > 0) {
+      this.evictLRU();
+    }
+
+    // Add new entry
+    this.cache.set(key, {
+      key,
+      value,
+      size,
+      lastUsed: Date.now(),
+    });
+
+    this.currentSize += size;
+  }
+
+  /**
+   * Remove a value from the cache
+   */
+  remove(key: string): T | undefined {
+    const entry = this.cache.get(key);
+    if (!entry) return undefined;
+
+    this.cache.delete(key);
+    this.currentSize -= entry.size;
+    return entry.value;
+  }
+
+  /**
+   * Check if key exists
+   */
+  has(key: string): boolean {
+    return this.cache.has(key);
+  }
+
+  /**
+   * Evict least recently used entry
+   */
+  private evictLRU(): void {
+    let oldestKey: string | null = null;
+    let oldestTime = Infinity;
+
+    for (const [key, entry] of this.cache.entries()) {
+      if (entry.lastUsed < oldestTime) {
+        oldestTime = entry.lastUsed;
+        oldestKey = key;
+      }
+    }
+
+    if (oldestKey) {
+      const entry = this.cache.get(oldestKey)!;
+      this.cache.delete(oldestKey);
+      this.currentSize -= entry.size;
+      this.evictions++;
+    }
+  }
+
+  /**
+   * Get cache statistics
+   */
+  getStats(): CacheStats {
+    return {
+      size: this.currentSize,
+      capacity: this.capacity,
+      hits: this.hits,
+      misses: this.misses,
+      evictions: this.evictions,
+    };
+  }
+
+  /**
+   * Clear the cache
+   */
+  clear(): void {
+    this.cache.clear();
+    this.currentSize = 0;
+    this.hits = 0;
+    this.misses = 0;
+    this.evictions = 0;
+  }
+
+  /**
+   * Get all keys
+   */
+  keys(): string[] {
+    return Array.from(this.cache.keys());
+  }
+
+  /**
+   * Get all values
+   */
+  values(): T[] {
+    return Array.from(this.cache.values()).map((entry) => entry.value);
+  }
+
+  /**
+   * Get cache size
+   */
+  get size(): number {
+    return this.cache.size;
+  }
+}

package/src/resources/index.ts

@@ -0,0 +1,9 @@
+/**
+ * @clypra/runtime — Resource Management
+ *
+ * Manages texture and buffer resources with LRU caching.
+ */
+
+export * from "./types";
+export * from "./manager";
+export * from "./cache";