Crate engawa 

Engawa (縁側) — typed render-graph IR for pleme-io GPU consumers.

An engawa is the wooden veranda that runs along the outside of a traditional Japanese house — a layered transition space between the bare ground and the polished interior. The image: every visual effect composes onto the operator’s screen through a series of layered passes, the way a kabuki actor steps through the engawa before entering the room.

Frame

Bevy’s bevy_render is the reference for what a “good” render graph looks like — typed nodes, explicit dependencies, deterministic compilation. Engawa borrows the design, not the dependency. Bevy assumes a game-loop ECS world; mado (engawa’s first consumer) is a terminal emulator that’s idle most of the time and demands byte-deterministic rendering (see mado’s L1/L2/L3 verification ladder). Pulling in bevy wholesale would invalidate that work.

Engawa keeps the parts of bevy_render’s design that fit:

• Typed DAG of render nodes with explicit input/output resources (textures, samplers, uniform buffers, storage buffers).
• Pass kinds — render, compute, blit — declared per node so the compiler picks the right wgpu encoder dispatch.
• Topological compile — nodes are sorted into a deterministic execution order; missing inputs / cycles are caught at compile time, not at the first frame.
• Material/effect composition — a chain of effects composes via shared render targets; turn one off, the graph re-orders without breaking dependencies.
• Hot-reload-ready IR — pure data, serializable, swappable from a shikumi watcher (effects authored in tatara-lisp → compiled to engawa IR → live-reloaded into the graph).

Engawa drops the parts that don’t fit a terminal:

• No ECS world. Mado tracks its own cell grid + cursor; engawa doesn’t impose a component model.
• No render-every-vsync assumption. Engawa graphs are passive — the consumer decides when to dispatch.
• No asset pipeline. Shader source is a String or a path; shikumi’s notify watcher (already shipped fleet-wide) handles the hot-reload story.
• No 3D camera / lighting / PBR. Effects target a 2D viewport; the math collapses to one resolution uniform.

Layering

Engawa is one of three pleme-io GPU primitives. Each owns a distinct concern:

Crate	Concern	Used by
garasu	GPU context, text rendering, headless harness	mado, ayatsuri, hibikine, namimado, …
engawa (this crate)	Render-graph IR, effects composition	mado (next), ayatsuri (TBD)
madori	winit window + event loop	mado, ayatsuri

Status

v0.1.0 ships the pure-data IR + topo-sort + validation + extensive unit-test coverage. Wgpu wiring (taking a CompiledGraph and dispatching against a wgpu::Device + a garasu HeadlessTarget) lands in v0.2 once the IR has been exercised against mado’s existing post-pipeline.

Re-exports

pub use decoration::CurlyBand;

pub use decoration::DecorationRect;

pub use decoration::Rgb;

pub use decoration::SegmentRun;

pub use decoration::UnderlineColor;

pub use decoration::UnderlineGeometry;

pub use decoration::UnderlineMetrics;

pub use decoration::UnderlineStyle;

pub use decoration::emit_underline_rects;

pub use decoration::overline_rect;

pub use dispatch::DispatchError;

pub use dispatch::Dispatcher;

pub use dispatch::RecordedDispatch;

pub use dispatch::RecordingDispatcher;

pub use dispatch::ResourceBindings;

pub use dispatch::ResourceHandle;

pub use effect::Effect;

pub use error::EngawaError;

pub use error::ValidationError;

pub use graph::CompiledGraph;

pub use graph::RenderGraph;

pub use material::BindingKind;

pub use material::Material;

pub use material::ShaderSource;

pub use material::UniformBinding;

pub use node::Node;

pub use node::NodeId;

pub use pass::PassKind;

pub use resource::ResourceId;

pub use resource::ResourceKind;

Modules

decoration

Text-decoration vocabulary + typed geometry emitters (M3-C2).

dispatch

Dispatcher contract — the API consumers (mado, future ayatsuri) implement to drive a CompiledGraph against actual GPU resources.

effect

Operator-facing effect — material + enable bit + ordering priority. Effects are the unit operators turn on/off in their YAML / lisp config; a node is the IR after compile.

error

Typed errors. Every failure path through the graph compile returns one of these; consumers never see a generic anyhow::Error from engawa.

graph

The render graph proper — typed DAG of nodes + compile-time validation + topo sort into execution order.

material

Materials — shader source + uniform/binding declarations.

node

Render-graph nodes — the unit of work in the engawa IR.

pass

Pass kinds — what wgpu encoder dispatch a node compiles to.

resource

Typed GPU resources flowing through the render graph.