How Clypra’s Render Engine Spatial and Temporal Tier System (L0-L3) Works

Clypra’s deterministic media render engine uses a two-dimensional tier system where SpatialTier (L0-L3) controls resolution from 160×90 to 480×270 pixels and TemporalTier (L0-L3) controls frame-sampling density from 5-second to 20-millisecond intervals, dynamically selected based on zoom level, viewport density, velocity state, and quality presets.

Clypra’s render engine implements a sophisticated deterministic approach to media processing through its spatial and temporal tier system. This architecture, defined in the AIEraDev/Clypra repository, balances visual fidelity with performance by adjusting both resolution and frame sampling density in real-time as users interact with the timeline. Understanding how the L0-L3 tiers interact is essential for optimizing render pipelines and cache strategies in video editing applications.

Understanding the Two-Dimensional Tier Architecture

The tier system operates along two independent axes defined in src/lib/renderEngine/types.ts. SpatialTier governs the resolution of rendered frames, while TemporalTier determines how frequently frames are sampled from the source media. Each axis supports four levels (L0-L3), with L0 representing the coarsest settings and L3 providing the finest detail.

Spatial Tier (Resolution)

The spatial tier maps directly to specific base dimensions and zoom ranges according to the DEFAULT_SRP_CONFIG defined in src/lib/renderEngine/types.ts.

Tier	Enum	Base dimensions (w × h)	Typical zoom range
L0	SpatialTier.L0	160 × 90	0.1 – 0.5 ×
L1	SpatialTier.L1	240 × 135	0.5 – 1.0 ×
L2	SpatialTier.L2	320 × 180	1.0 – 2.0 ×
L3	SpatialTier.L3	480 × 270	2.0 – 4.0 ×

These dimensions must align precisely with the Rust thumbnail pyramid implementation in src-tauri/src/thumbnail_engine/pyramid.rs to prevent blur or stretch artifacts. While the tier boundaries are configurable via the SRP configuration, the defaults above ship with the production build.

Temporal Tier (Frame Sampling)

Temporal tiers control the interval between sampled frames, with separate base and near-edit intervals defined in TEMPORAL_TIER_INTERVALS within src/lib/renderEngine/types.ts.

Tier	Enum	Base interval (s)	Near‑edit interval (s)
L0	TemporalTier.L0	5.0	2.5
L1	TemporalTier.L1	1.0	0.5
L2	TemporalTier.L2	0.2	0.1
L3	TemporalTier.L3	0.02	0.01

These intervals must remain synchronized with the Rust implementation of DensityLevel::time_interval() found in src-tauri/src/thumbnail_engine/types.rs. The near-edit intervals apply when the playhead approaches an edit boundary, ensuring sufficient temporal resolution for precise trimming operations.

How the Engine Selects Render Tiers

The render engine follows a deterministic seven-step evaluation process to select appropriate tiers for each render epoch.

1. Zoom level mapping to spatial tier
   The current viewport zoom level is evaluated against DEFAULT_SRP_CONFIG intervals. The tier whose [min, max) range contains the zoom value becomes the target spatial tier.

2. Viewport density hint to temporal tier
   A density hint derived from visible area, scroll speed, and device pixel ratio (DPR) maps analogously to spatial tiers. TemporalTier.L3 corresponds to the highest density scenario, approximately equivalent to 50 frames per second.

3. Quality preset constraints
   User-selected quality presets (Low, Medium, High, Ultra) restrict eligible spatial tiers. High and Ultra allow L3; Medium limits to L2; Low restricts to L1.

4. Velocity state classification
   Scroll and zoom velocity is bucketed into Stable, Slow, Fast, or Ballistic states via the classifyVelocity function. Fast or ballistic motion can skip intermediate tiers to prevent render churn.

5. Epoch validation
   A render epoch is uniquely identified by nine dimensions: clip ID, version, transform graph version, viewport bounds, velocity state, zoom level, spatial tier, temporal tier, and renderer mode. Changing any dimension forces a new epoch and may trigger tier recalculation.

6. Coupled versus decoupled tiers
   By default, spatial and temporal tiers remain coupled (L2 spatial implies L2 temporal). The engine supports decoupling when quality presets permit higher spatial tiers while maintaining lower temporal tiers to respect bandwidth constraints.

7. Cache interaction
   Each tier maintains dedicated cache buckets (FilmstripCache, BackendTierCache). When tier changes occur, the engine checks the appropriate cache before dispatching new render jobs.

Key Implementation Files

The tier system spans TypeScript frontend code and Rust backend implementations.

File	Role
src/lib/renderEngine/types.ts	Defines SpatialTier, TemporalTier, tier-boundary configurations, and quality-preset mappings.
src/lib/renderEngine/srp.ts	Implements the Spatial Render Pyramid logic for zoom-to-spatial-tier mapping.
src/lib/renderEngine/tsp.ts	Implements the Temporal Sampling Pyramid for viewport-density-to-temporal-tier mapping.
src/lib/renderEngine/transport.ts	Serializes render artifacts between backend and frontend while preserving tier identifiers.
src/lib/renderEngine/__tests__/srp.test.ts	Unit tests validating zoom-to-tier mapping, clamping behavior, and preset restrictions.
src/lib/renderEngine/__tests__/renderEngine.test.ts	Integration tests confirming high-quality presets correctly enable L3 rendering.
src/lib/filmstrip/filmstripTiers.ts	Adapts spatial tiers for filmstrip thumbnail intervals.

Practical Code Examples

Determining the Target Spatial Tier from Zoom

The following function maps zoom levels to spatial tiers using the default SRP configuration:

import { SpatialTier, DEFAULT_SRP_CONFIG } from '@/lib/renderEngine/types';

function spatialTierForZoom(zoom: number): SpatialTier {
  const tiers = Object.values(SpatialTier).filter(v => typeof v === 'number') as SpatialTier[];
  for (const tier of tiers) {
    const { min, max } = DEFAULT_SRP_CONFIG[tier];
    if (zoom >= min && zoom < max) return tier;
  }
  // Clamp out-of-range zooms to the highest tier
  return SpatialTier.L3;
}

Reference: DEFAULT_SRP_CONFIG is defined in types.ts lines 99-104.

Mapping Viewport Density to Temporal Tier

Convert viewport density hints to temporal tiers based on multipliers where 1.0 approximates L2 density:

import { TemporalTier, TEMPORAL_TIER_INTERVALS } from '@/lib/renderEngine/types';

function temporalTierForDensity(densityHint: number): TemporalTier {
  // Assume densityHint is a multiplier where 1.0 ≈ L2 density.
  if (densityHint >= 4) return TemporalTier.L3;
  if (densityHint >= 2) return TemporalTier.L2;
  if (densityHint >= 0.5) return TemporalTier.L1;
  return TemporalTier.L0;
}

Applying Quality Preset Constraints

Restrict available tiers based on user quality preferences:

import { QualityPreset, QUALITY_PRESET_TIERS } from '@/lib/renderEngine/types';

function allowedSpatialTiers(preset: QualityPreset): SpatialTier[] {
  return QUALITY_PRESET_TIERS[preset];
}

// Example: Ultra preset allows all tiers including L3
const tiers = allowedSpatialTiers('Ultra'); // [L0, L1, L2, L3]

Complete Rendering Decision Flow

Combine zoom, density, preset, and velocity to determine final tiers:

function decideRenderTier(
  zoom: number,
  densityHint: number,
  preset: QualityPreset,
  velocityPxSec: number
) {
  const spatial = spatialTierForZoom(zoom);
  const temporal = temporalTierForDensity(densityHint);
  const velocity = classifyVelocity(velocityPxSec);

  // Respect quality preset limits
  const allowed = allowedSpatialTiers(preset);
  const finalSpatial = allowed.includes(spatial) ? spatial : allowed[allowed.length - 1];

  // Optionally decouple tiers when bandwidth limited
  return { spatialTier: finalSpatial, temporalTier: temporal, velocityState: velocity };
}

Accessing Render State in React Components

Use the provided hook to react to tier changes in the UI:

import { useRenderRuntime } from '@/hooks/useRenderRuntime';

function ClipViewer({ clipId }: { clipId: string }) {
  const { getRenderState } = useRenderRuntime();
  const state = getRenderState(clipId);

  return (
    <canvas
      width={state.currentTier.spatialTier === 3 ? 480 : 320}
      height={state.currentTier.spatialTier === 3 ? 270 : 180}
      // Render appropriate artifact based on current tier...
    />
  );
}

Summary

• Clypra's render engine employs a two-dimensional tier system with SpatialTier controlling resolution (160×90 to 480×270) and TemporalTier controlling frame intervals (5s to 0.02s).
• Tier selection depends on zoom level, viewport density hints, quality presets (Low through Ultra), and velocity states (Stable to Ballistic).
• Epoch validation uses nine-dimensional identifiers to determine when tier changes are necessary.
• Cache isolation ensures each tier maintains separate storage buckets (FilmstripCache, BackendTierCache) to optimize retrieval performance.
• Implementation spans TypeScript frontend modules (types.ts, srp.ts, tsp.ts) and Rust backend code (pyramid.rs, types.rs).

Frequently Asked Questions

What happens when the zoom level exceeds the defined L3 range?

When zoom exceeds the 2.0–4.0× range defined for L3, the engine clamps to SpatialTier.L3 as the maximum available resolution. According to the implementation in spatialTierForZoom, out-of-range values return the highest tier rather than throwing errors, ensuring continuous rendering at maximum fidelity.

Can spatial and temporal tiers operate independently?

Yes, while the default configuration couples spatial and temporal tiers (L2 spatial implies L2 temporal), the engine supports decoupling when quality presets permit. This allows high spatial resolution (L3) with lower temporal sampling (L1 or L2) to maintain performance within bandwidth constraints, particularly during fast scrubbing operations.

How does the velocity state affect tier selection?

The classifyVelocity function buckets motion into Stable, Slow, Fast, or Ballistic states. Fast and ballistic velocities can trigger tier skipping— bypassing intermediate tiers to reduce render churn—while stable states allow the engine to progress through finer tiers for maximum quality.

Where are the tier interval constants defined?

Spatial tier dimensions and zoom boundaries reside in DEFAULT_SRP_CONFIG within src/lib/renderEngine/types.ts. Temporal tier intervals are defined in TEMPORAL_TIER_INTERVALS in the same file. These must synchronize with the Rust implementations in src-tauri/src/thumbnail_engine/pyramid.rs and src-tauri/src/thumbnail_engine/types.rs respectively.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}