Skip to content

Photon

Jump to bottom
Edgar Mesquita edited this page Aug 5, 2026 · 12 revisions

Photon — The Native GPU Engine (Track N)

Photon is eQuantic.UI's proprietary GPU rendering engine for mobile (and eventually desktop): a from-scratch, Impeller-inspired renderer that draws the component tree pixel by pixel on the GPU — Metal on iOS/macOS, Vulkan on Android — with no Skia tier and no WebView. It is the second realization target of the write-once component architecture: the same C# components that lower to DOM+CSS on the web are rasterized by Photon natively.

The living plan is docs/NATIVE-GPU-ENGINE-PLAN.md in the main repo — vision, decisions (D1–D12), workstreams (W1–W8), milestones (M0–M5) and a dated status log. This page is the overview.

Why proprietary, why no Skia

The decision (2026-07): if the project was going to own a native tier at all, it would own the whole rendering stack — direct Metal/Vulkan backends with precompiled shaders, not a wrapper over Skia. That buys:

  • Predictable performance: fixed pipeline-state registry, zero shader compilation at runtime (the jank source Impeller was built to kill).
  • A tiny surface: UI rendering needs a handful of primitives, not a general 2D library.
  • One normative model: the same math, testable to the pixel, across CPU reference and every GPU backend.

Architecture at a glance

C# components (write-once, eQuantic.UI.Primitives vocabulary)
        │  Build(ComponentContext)          — pure, token-based, mode-free
        ▼
eQuantic.UI.Native.Framework                — C# flex layout engine (spec A2)
        ▼
eQuantic.UI.Native.Components               — PhotonRealizer: abstract tree → display list
        ▼
eQuantic.UI.Native.Engine                   — geometry, color model, Sdf.cs (NORMATIVE), DisplayList
        ▼
IRenderBackend
   ├── eQuantic.UI.Native.Engine.Reference  — scalar CPU rasterizer (golden ground truth, never shipped)
   ├── eQuantic.UI.Native.Engine.Metal      — Apple GPUs (offscreen spike landed)
   └── (Vulkan — planned)

The normative core

  • Sdf.cs is a spec, not a library: per-corner rounded-rect signed distance, centered stroke (|d| − w/2), 1-pixel anti-aliasing coverage ramp. Every rasterizer — the CPU reference and the GPU fragment shaders — implements exactly these formulas.
  • Color model: sRGB authoring → linear premultiplied blending → sRGB store, mirroring GPU hardware behavior with sRGB render targets.
  • Display lists: flat, heap-free DrawCommand records (Clear / FillRRect / StrokeRRect, solid or two-stop linear gradient paints, baked 2D transforms).

Golden-image harness

Every scene renders through a backend into a surface, reads back sRGB pixels, and compares against committed PNG goldens (dependency-free codec, EQ_UPDATE_GOLDENS=1 regeneration flow, ±2 tolerance, failure artifacts with amplified diffs). The scene catalog is shared: the Reference backend pins the goldens; GPU backends run the same catalog for parity.

Metal spike result (2026-07-04)

The first GPU frames validated the whole model: an offscreen Metal backend driven by ~100 lines of typed objc_msgSend P/Invoke (no binding framework, no C shims), one pipeline built at device init, runtime-compiled MSL that transliterates Sdf.cs. Measured against the CPU reference across all 14 golden scenes (fills, strokes, gradients, rotation/scale transforms, translucent blending, radius clamping):

Max channel difference: 1 (of 255). Zero pixels beyond ±2.

The GPU passes the golden harness's own tolerance — Sdf-as-spec and the color model hold end-to-end on hardware. Production shaders move to an offline Slang toolchain (single shader source → SPIR-V for Vulkan + metallib for Metal, embedded like the Bun binaries).

Component rendering today

The native realizer draws real component chrome (token-resolved fills, inside borders, per-corner radii) with documented placeholders where subsystems are pending:

Subsystem State (2026-07-31)
Shapes, borders, gradients, transforms, blending, clip ✅ Full, golden-tested
Layout (flex + wrap, grid, stacks, adaptive, truncation) ✅ C# engine
Shadows (elevation §05) ✅ Analytic ShadowCoverage, both backends
Text ✅ REAL — Texture primitive (A8 coverage × tint) + platform ITextRasterizer; macOS = CoreText (system frameworks only — no HarfBuzz/FreeType where the platform has a text engine). One engine measures AND rasters, so line breaks agree by construction. Two faces: the system's proportional one and its monospaced one (TypeStyle.Mono). No glyph is ever clipped — the bitmap is sized from the line's INK box (CTLineGetImageBounds, not the font's declared metrics: a deep g tail passes beyond them) and reports how far above the line box it had to reach, so the realizer raises the draw by exactly that and the line box still lands where layout put it
Icons ✅ REAL — pure-C# SVG path parser (full command set, arcs via F.6.5) + CoreGraphics rasterizer, same Texture primitive
Group opacity / transforms (S1) ✅ Engine layers (Reference exact; Metal per-command spike fence)
Scroll compositor ✅ Path-keyed offsets, real Sticky pinning (vertical)
Motion ✅ Loop motion, value transitions (B14), Presence enter/exit with command-snapshot replay
Gestures ✅ Hover pipeline, press with slop-cancel, drag-to-dismiss (follow + glide)
Anchored overlays ✅ Synthetic overlay layers positioned from absolute anchor bounds
Images SurfaceSubtle box until decode/upload (the remaining Texture consumer, A11/M4)

Interaction is wired: PhotonHost holds a retained root, SetState invalidates, taps dispatch to hit regions (topmost wins, disabled swallows; ≥48dp under a finger, the control's own size under a pointer — see Density) — the native Counter runs tap → SetState → rebuild end-to-end in tests. PhotonHost.FocusedPath reports what holds the keyboard, including a field being edited (the caret is that field's own focus indicator) — a platform accessibility bridge needs one honest answer, not the ring's half of it.

Layout: the CSS rules the engine owes you

The native engine is judged against the browser, because the web twin renders the same tree there:

  • Fill inherits indeterminacy — on an axis the parent sizes from content, a Fill child has nothing to fill and passes the question through; leftover is not distributed on such an axis.
  • Block semantics, width only — a box whose width is decided stretches an auto-sized CONTAINER child across it (a div's child div is full-width), while a button, link or input hugs there: they are inline-block, and only a FLEX stretch reaches through them (StretchKind).
  • flex-shrink with a min-content floor — a line that does not fit shrinks its items instead of overflowing, and never below each item's min-content (the longest word of a text, the sum of a row's children). Overflow used to be swallowed by the clip — silently, because a clipped press region cannot be pressed either.
  • Min/Max reflow — when a clamp changes a box's extent, its child re-measures against the final size.

The macOS shell — Photon's first real window (W5, 2026-07-31)

eQuantic.UI.Native.Shell.MacOS: an NSWindow hosting a CAMetalLayer, zero third-party packages — slim typed objc_msgSend AppKit bindings, the Metal-spike pattern. The Metal backend encodes each frame straight into the layer's drawable (per-pixel-format pipeline cache, BGRA8_sRGB for windows); PhotonHost.RenderScale rasters at backingScaleFactor while layout/input stay in dp (retina). OS mouse/scroll events route into the ordinary pointer pipeline — press visuals, hover diffs and anchored menus behave exactly like the tests. Real San Francisco text and real pack icons render on screen. Try it: dotnet run --project samples/PhotonDesktop. Two headless modes need no window at all: --Photon:MaxFrames 120 presents that many frames and exits, and --Photon:ScreenshotPath out.png (with --Photon:Mode Dark for the other palette) renders ONE settled frame through the reference backend with the same CoreText metrics — the CI screenshot step, and the way a fidelity pass against a design handoff is checked. Calling Run() off the main thread now says so in .NET terms instead of dying inside AppKit. Resize the window freely — the host adopts the viewport with all state intact.

Shaders — ONE normative Slang source

Sdf.slang (transliterating Sdf.cs) compiles offline via the embedded slangc into committed MSL + SPIR-V — SDF fragment plus the W4b textured fragment (texel Load, nearest by definition — rasters are device-scale, exact Reference parity). GPU↔CPU parity holds at 17/17 scenes within the golden tolerance.

Status

Native suite: 301 tests, 74 goldens (component pairs light+dark, mid-drag sheet states, texture coverage). The window runs the write-once showroom with real text, icons, menus and gestures. Next on this track: window resize (host viewport), image decode/upload, RHI extraction from the Metal spike's shape, Vulkan backend, iOS shell (NativeAOT gate).

Clone this wiki locally