Architecture Overview

A high-level guide to the OpenGPEX v2 engine architecture — a full WebGPU rewrite that replaces the v1 Canvas2D/wasm-vips rendering stack with a single hardware-accelerated pipeline for both live preview and file export.

Design Mission

OpenGPEX 1.0 established its feature baseline on React + Worker multithreading + Canvas2D / wasm-vips. v2.0 is a "power rewrite": WebGPU is the only core rendering substrate. All pixel compositing, color matrix conversion, filter convolution, and brush computation run directly on the GPU, targeting desktop-native responsiveness (4K / 8K at high frame rates) with end-to-end physically accurate color.

The v1 constraints this removes:

Two Chains, One Pipeline

v2 has exactly two execution chains that meet only where source pixels are obtained:

┌─────────────────────────────────────────────────────────────────────┐
│  UI / State layer (React, declarative)                               │
│  stage/ viewport · plugin drawers · core/state (reducer + fast track)│
└───────────────┬─────────────────────────────────┬───────────────────┘
                │                                 │
     ┌──────────▼─────────────┐        ┌──────────▼──────────────────┐
     │ RENDER CHAIN (main      │        │ IO CHAIN (cross-Worker)     │
     │ thread, pure GPU)       │        │                             │
     │                         │        │ PixelFacade → dispatchers   │
     │ SceneAssembler          │        │ → WorkerBridge → Engine     │
     │   → Scene (pure data)   │        │ Worker (decode, resample,   │
     │ WebGpuEngine.render()   │        │ pixel extraction,           │
     │   → SceneCompiler       │        │ histogram — no vips)        │
     │   → RenderGraph         │        │                             │
     │   → passes              │        │ core/files transcode        │
     │   → final sink          │        │ Workers (shared vips        │
     │                         │        │ singleton + on-demand       │
     └──────────┬──────────────┘        │ libraw / resvg / gs / avif) │
                │                       └─────────────────────────────┘
      ┌─────────┴──────────┐
      ▼                    ▼
  Swapchain             Readback
  (display-p3,      (copyTextureToBuffer
   HDR tone map)     → f32 Float32Array)

Key points:

• Rendering and export share the same RenderGraph; only the final sink differs (swapchain vs. readback buffer). This is the One Pipeline invariant.
• SceneAssembler is the only module that straddles both chains — it requests source pixels from the IO chain — which is why it lives in the assembly layer (core/engine/pipeline/scene/), not the GPU kernel.
• The two chains touch only indirectly, through shared caches (SourceBitmapCache / HighDepthTextureCache).

Module Layering

Dependencies flow strictly top-down as an acyclic DAG. External consumers import only through top-level barrels; deep imports are forbidden.

Outer shells (workspace/ layout, plugins/*) depend inward only, via stable service contexts.

Core Architectural Aspects

Key Design Decisions

1. One Pipeline (Single Source of Truth)

One WGSL / RenderGraph serves both screen presentation and file export; the baked pixels are bit-identical to the on-screen preview. Readback returns premultiplied linear Display-P3 Float32Array (f32), which acts as the common superset for both terminal encodings (view shader and export encode).

2. Declarative First

The UI/state layer only produces pure data descriptors — layer JSON, stroke point streams, adjustment parameters. The engine compiles them into GPU commands; side effects are contained entirely inside the engine, making frames cacheable and replayable.

3. Fixed Working Color Space

All compositing happens in Linear Display-P3 at rgba16float, regardless of source encoding. Source gamuts are aligned per-sample in the fragment shader via 3×3 matrices, with no clamping — out-of-gamut values survive as negative / >1.0 floats and can be recovered losslessly on export.

4. Depth Bifurcation with a Single Convergence Point

Storage honors each layer's true source bit depth (8-bit sources stay rgba8unorm, 16/32-bit sources become float textures); all math converges at rgba16float linear light; export depth is decided independently by the document. Three invariants (store / compute / export) keep this tractable — see Rendering & Engine.

5. Zero-Compromise Fallback

v2 ships no Canvas2D degradation patches. Environments without WebGPU are directed to the v1.x LTS maintenance line instead of silently losing fidelity.

Comparison with v1

Last updated: 2026-10-12