Realm/Surface/RealmGraph - Foundation Plan

This document consolidates Phase 0 architecture replacement items: contracts, IDs, and foundational rules for Realm/Surface/RealmGraph.

1. Internal contracts (fields, defaults, lifecycle)

• Realm
  • kind: ThreeD or TwoD.
  • output_surface: primary realm SurfaceId.
  • render_graph_id: logical reference to a graph in the global catalog.
  • flags: reserved for execution policies.
• Surface
  • kind: Onscreen or Offscreen.
  • size: logical size in pixels.
  • format_policy: optional; core defines defaults when missing.
  • alpha_policy: optional; core defines defaults when missing.
  • msaa_samples: optional; core resolves when missing.
• Present
  • windowId -> surfaceId (virtual swapchain).
• Connector
  • sourceSurfaceId
  • rect
  • zIndex
  • blendMode
  • clip
  • inputFlags

2. Logical IDs and generation

All tables (Realm, Surface, Connector, Present) use logical IDs with generation. The goal is to prevent use of expired IDs and guarantee safe disposal.

3. Surface buffering and PreviousFrame

Each Surface must keep at least 2 images (current/previous) to allow:

• PreviousFrame reads for history-dependent effects;
• blocking reads from the current output of the same realm.

4. Multi-window composition

The same Surface can be presented in multiple windows in the same frame:

• ordering by zIndex;
• rect rules similar to CSS position: fixed (viewport-relative coordinates);
• connector-level clipping.

5. rect rules (connector)

rect is defined per connector with CSS-like position: fixed behavior:

• coordinates are relative to the window viewport;
• clipping and height alignment with width-based crop.

6. Profiling and GPU timestamp impact

Profiling should reflect multi-realm execution:

• realm execution order;
• cycle-cut edges;
• cached/fallback surfaces;
• realm/compositor timestamps.

7. Minimal RealmGraph (Phase B)

• RealmGraphPlanner builds the graph from Connectors and Presents.
• Hard edges protect presents; Soft edges may be cut to break cycles.
• The plan records cut_edges for diagnostics and cache of LastGoodSurface/FallbackSurface.
• Realm compositor applies Connector by zIndex order, with position: fixed-style rect, height alignment, and width clipping when needed.
• Realm output is always renderable/sampleable (float targets), with composition converting size and format according to the final target.