Skip to content

architecture.md

Latest commit

 

History

History
52 lines (34 loc) · 2.07 KB

architecture.md

File metadata and controls

52 lines (34 loc) · 2.07 KB
Raw

Architecture

Runtime boundary

Interactive sketches use two operating-system processes:

R session                         processing-host
callbacks and data               window, input, GPU
        |                                |
        +---- batched frame commands --->|
        |<-------- input events ----------+

The separation keeps the R event loop independent from the renderer's main-thread requirements, isolates GPU crashes, and lets the host ship on a cadence different from the R package.

Components

Protocol

The protocol is the stable contract between language clients and the host. Rust implementation details and libprocessing handles must never cross this boundary. Every session starts with version and capability negotiation.

Protocol v1 uses newline-delimited JSON to make the initial integration observable and easy to debug. A future binary payload extension can coexist with the same message model for large vectors, pixels, images, and geometry.

Host state machine

The host accepts requests in this order:

AwaitingHello -> Ready -> Surface -> Stopped

Invalid transitions return structured errors without crashing the process.

Renderer interface

Renderer separates protocol lifecycle from graphics implementation. The current ValidationRenderer checks ordering and frame identifiers without opening a window. The planned LibprocessingRenderer will:

  1. initialize libprocessing on the process main thread;
  2. create and own the native window and WebGPU surface;
  3. translate a complete protocol frame into DrawCommand records;
  4. present the frame;
  5. publish input and window events back to the client.

Compatibility policy

  • The protocol follows semantic versioning independently of the executable.
  • Breaking wire changes require a new protocol version.
  • Host releases pin an exact tested libprocessing tag or revision.
  • Clients use capability negotiation instead of assuming optional features.
  • Conformance tests should compare representative sketches with Processing Java and upstream libprocessing examples.