plurigrid Rio WebGPU Tiles
GPU-accelerated tile rendering in Rio Terminal using wgpu and the sugarloaf brush architecture.
Architecture Overview
OSC 1337 Sequence → rio-backend (parse) → RioEvent::InsertTile → rioterm (frontend) → sugarloaf TileBrush → wgpu render
Core Files
| File | Purpose |
|---|---|
sugarloaf/src/components/tiles/mod.rs |
TileBrush, TileWorldState, GPU buffers |
sugarloaf/src/sugarloaf.rs |
Main renderer integration, public API |
rio-backend/src/ansi/tile_protocol.rs |
OSC 1337 Tile= parsing |
rio-backend/src/performer/handler.rs |
OSC dispatch to handler |
rio-backend/src/event/mod.rs |
InsertTile event variant |
frontends/rioterm/src/application.rs |
Frontend event handling |
Protocol: OSC 1337 Tile Extension
# Format: ESC ] 1337 ; Tile = key:value,key:value,... BEL
printf '\033]1337;Tile=shader:plasma,x:50,y:50,w:200,h:150\007'
Parameters
| Key | Type | Description |
|---|---|---|
shader |
string | plasma, clock, noise, or custom ID |
x, y |
f32 | Position in pixels |
w, h |
f32 | Size in pixels |
id |
u64 | Tile ID (0 = auto-assign) |
kind |
string | persistent (default) or transient |
r, g, b, a |
f32 | Custom color/data (0.0-1.0) |
time_offset |
f32 | Animation time offset |
Tile Lifecycle
Persistent Tiles
Remain until explicitly removed by ID:
let id = sugarloaf.create_persistent_tile(scene);
// ... later
sugarloaf.remove_persistent_tile(id);
Transient Tiles
Cleared at begin_frame(), must be re-pushed each frame:
sugarloaf.push_transient_tile(scene);
TileWorldState
Manages CPU state with high-precision time (f64), converted to modular f32 for GPU:
pub struct TileWorldState {
persistent: HashMap<TileId, TileScene>,
transient: Vec<TileScene>,
world_time_seconds: f64,
next_id: TileId,
}
impl TileWorldState {
pub fn begin_frame(&mut self, dt_seconds: f64) {
self.world_time_seconds += dt_seconds;
self.transient.clear();
}
}
Writing WGSL Shaders
Uniform structure available in shaders:
struct Uniforms {
position: vec2<f32>, // NDC position
size: vec2<f32>, // NDC size
time: f32, // Animation time (modular)
custom: vec4<f32>, // r,g,b,a from protocol
}
@group(0) @binding(0) var<uniform> u: Uniforms;
Vertex Shader Pattern
@vertex
fn vs_main(@location(0) pos: vec2<f32>, @location(1) uv: vec2<f32>) -> VertexOutput {
var out: VertexOutput;
let screen_pos = u.position + pos * u.size;
out.position = vec4<f32>(screen_pos, 0.0, 1.0);
out.uv = uv;
return out;
}
Fragment Shader Pattern
@fragment
fn fs_main(in: VertexOutput) -> @location(0) vec4<f32> {
let t = u.time;
// Your shader logic using in.uv, t, u.custom
return vec4<f32>(color, 1.0);
}
Demo Scripts
# Plasma effect
printf '\033]1337;Tile=shader:plasma,x:50,y:50,w:200,h:150,r:0.5,g:0.2,b:0.8\007'
# Clock display
printf '\033]1337;Tile=shader:clock,x:300,y:50,w:250,h:80\007'
# Remove by ID
printf '\033]1337;Tile=remove:42\007'
Integration Checklist
- Add TileBrush to sugarloaf - Register in brush list, call in render loop
- Parse OSC 1337 in rio-backend - Extend performer handler
- Create RioEvent variant -
InsertTile(TileSpec) - Handle in frontend - Convert TileSpec → TileScene, call sugarloaf API
- Manage state - Call
begin_frame(dt)before each render
Shader Examples
See reference/shaders.md for complete plasma, clock, and noise shader implementations.