Introduction

Welcome to the OpenGPEX v2 documentation — the reference for the WebGPU generation of the open-source, industrial-grade web image editor.

[!IMPORTANT] Documentation Lag & Maintenance Notice OpenGPEX is actively developed and iterating rapidly. Due to limited maintainer bandwidth, this documentation may occasionally lag behind the latest codebase changes.

If you notice any discrepancies, the source code is the ultimate source of truth. Contributions to update and correct these guides are highly welcome — please consider opening a Pull Request!

What is OpenGPEX v2?

OpenGPEX v2 is a ground-up rewrite of the OpenGPEX rendering engine on WebGPU. Where v1 was built on React + Worker multithreading with Canvas2D / wasm-vips software rasterization, v2 moves every pixel-composite, color-matrix conversion, filter convolution, and brush computation onto the GPU. The goal is responsiveness on par with native desktop tools (Affinity, Figma, Photoshop): 4K/8K documents at high frame rates with hardware acceleration end to end.

v2 keeps the product model you know from v1 — layers, non-destructive editing, masks, adjustments, plugins — while replacing the engine underneath:

• WebGPU is the only rendering backend. There is no Canvas2D fallback path. Environments without WebGPU support are directed to the v1.x LTS maintenance line.
• One pipeline for screen and export. A single declarative RenderGraph serves both real-time presentation and file export; they differ only in the final sink (swapchain vs. readback buffer). What you preview is bit-identical to what you export.
• Linear Display-P3 working color space. All compositing happens in physically linear light at rgba16float (upgraded to rgba32float when the adapter grants both float32-blendable and float32-filterable), with wide-gamut sources mapped into the working space without clamping.

Core Capabilities

1. GPU Rendering Core

• Declarative RenderGraph: The UI produces pure data descriptors (a Scene of layer nodes); the engine compiles them into GPU passes. Side effects are confined to the engine, making compilation cacheable and replayable.
• Compose-Once, View-Many: Document-space compositing is camera-independent. Pan and zoom only re-run a lightweight view pass — they never trigger recomposition. Value-based dirty detection (compositeSignature) skips composition entirely when nothing changed.
• Hardware Layer Blending: 16 blend modes implemented in linear light on the GPU. Source-over layers batch through hardware blend state; the remaining non-separable modes run ping-pong in shader. 4K documents with ~100 layers composite in single-digit milliseconds.
• Zero-Allocation Frame Loop: A tiered TexturePool recycles transient textures by size bucket; intermediate results are pooled so steady-state frames produce no allocation garbage.
• Tiled, Resolution-Independent Editing: High-resolution artwork is uploaded as GPU textures with per-layer source-fidelity storage — 8-bit sources stay rgba8unorm (zero-copy), 16/32-bit sources use rgba16float/rgba32float float textures.

2. Color Pipeline

• Linear Display-P3 Working Space: All compositing, adjustments, and filters operate in linear light. Premultiplication and blending in gamma space (the historical cause of dark edge artifacts) is eliminated by construction.
• High Bit Depth End to End: The composition buffer is rgba16float linear light by default regardless of source bit depth. 8-bit sources are never bloated to float; 32-bit float sources (scRGB, float TIFF) pass through at full precision via rgba32float.
• No-Clamp Gamut Mapping: Out-of-working-space values are preserved as-is in float buffers and can be round-tripped losslessly on export via the inverse matrix.
• HDR and Wide-Gamut Presentation: The swapchain declares display-p3; on Windows 11 with Auto Color Management or HDR (toneMapping: extended), highlights can exceed 1.0 through to scRGB.
• Single-Track Adjustments: Curves, levels, color balance, channel mixer, and 3D LUTs are inlined into the layer/blend shaders as a shared WGSL function with TRC wrapping — no more dual-track (small-preview + delayed-worker) preview splitting. 4K adjustment evaluation is sub-millisecond.

3. Editing Tools

• Brush2 Stroke Engine: GPU compute stroke extrusion (capsule SDF with MAX blending) with a 40,000-point soft cap, dual ring buffers, and identical preview and commit paths.
• GPU Text Rendering: Text is a first-class vector renderer with a shared layout engine (one typographic truth for the DOM editor, GPU, and export), a glyph atlas, and instanced drawing — no bitmap fallback.
• Orthogonal Mask System: Hand-painted bitmap masks (bmask, with inversion-record erase/restore) and analytic geometric masks (vmask, SDF or GPU-baked, transform-independent caching) compose independently in the main shader.
• Unified Edge Model: Anti-aliasing is a per-tool property with a three-tier model (off / 1px coverage / viewport-direct), replacing ad-hoc geometry-shrink hacks.
• Non-Destructive Everything: Erase via masks, adjustment stacks per layer, clip masks, and viewport-isolated undo all carry over from v1's interaction model, now backed by GPU state.

4. IO and Files

• Declarative Ingest/Egest Decisions: resolveIngestDecision and resolveEgestDecision are the single decision authority for every format × bit depth × color space combination. High-bit-depth decode failures raise errors; there is no silent downgrade to 8-bit.
• RAW, TIFF, HEIC, AVIF, SVG, EPS: Format handlers run in self-owned transcode workers (lib-vips, libraw, resvg, Ghostscript, avif), isolated by WASM threading model, lifecycle, and crash domain from the render engine.
• Pass-Through Export: Unedited files whose export parameters match the source bypass the GPU entirely — original bytes stream out with EXIF/ICC metadata fully intact.
• Three Export Channels: canvas-8 (browser encoders), raw-8 (wide-gamut 8-bit raw pixels), and raw-16 (full-gamut 16-bit PNG/TIFF), with export bit depth orthogonal to source bit depth.
• Unified Asset Storage: assetId (sha256 + page) as the single source of truth over a three-key IndexedDB topology, with reference-counted garbage collection.

5. Extensibility

• Plugin System: The v1 modular plugin architecture, slots, and command/signal hooks carry into v2. Plugins produce declarative state; the engine owns all GPU execution.
• Sandboxed Errors: Plugin error boundaries still contain third-party failures locally.

Architecture at a Glance

v2 separates two link chains that meet only at source pixels and shared caches:

Key invariants:

1. Storage forks by source depth, computation always converges. Resident texture format equals the layer's true source bit depth; all compositing happens in linear light at rgba16float (or rgba32float on adapters that support it); export bit depth is set per document.
2. One pipeline. Baked pixels match the on-screen preview bit-for-bit; readback is f32 premultiplied linear Display-P3, the common superset for both terminal encodings.
3. No compromise fallback. No Canvas2D compatibility shims; unsupported environments use v1.x LTS.

Technology Stack

Deployment Models

OpenGPEX supports multiple deployment modes:

1. Local Development — Run on your machine with pnpm dev
2. Self-Hosted — Deploy to your own infrastructure (Docker, VPS, etc.)
3. GPEX-Cloud SaaS — Official cloud service with storage, auth, and collaboration (coming soon)

Browser Requirements

v2 requires a browser with WebGPU support (Chrome/Edge 113+ or an equivalent WebGPU-capable browser; Safari is supported per the upstream README). If your environment does not support WebGPU, use the v1.x LTS release, which remains on the Canvas2D engine.

License

OpenGPEX is released under the GPL-3.0 license. Contributions are welcome via GitHub.

Last updated: 2026-10-12