Architecture
RITEG runs a project as a compiled graph of shader passes. This document describes the host side: how a Lua project becomes a render plan and how GPU memory is reused between passes.
From graph to plan
A project is a directed acyclic graph:
- program — compiled GLSL, uniform locations, no render target;
- node — an instance of a program with a fixed size, format, sampler state and inputs;
- source — anything that can produce a texture: a node, the loaded image or a blank texture.
After the Lua script finishes, project::finalize() asks Graph::compile() to build a flat plan:
- Roots.
displayfirst, thenoutputif it is a different node. - Reachability and order. A depth-first traversal emits nodes in post-order. Shared nodes are emitted once, so a graph branch that converges on one consumer is not rendered twice. A gray node encountered again is a cycle and aborts compilation. The only legal cycle is
node:prev(), whoseNodePrevsource refers to the owner's back buffer and does not create an ordering edge when the owner is the node itself. - Liveness. For every node,
last_useis the maximum plan index of its consumers. Display and output roots are pinned for the whole frame. - Target allocation. Targets are pooled by the exact key
(width, height, format, filter, wrap). A pass takes a free target from its bucket or creates a new one; after a pass, targets whoselast_useequals the current index are returned to the pool. Feedback nodes bypass the pool and own a dedicated front/back pair.
The result is m_plan, a flat list of nodes, plus m_targets, the set of GPU textures that back it.
Why exact-size buckets
Many shaders call textureSize() or derive texel sizes from iResolution. Reusing a larger target for a smaller pass would silently change those values. The allocator therefore never mixes sizes (or formats, filters and wraps). Cross-size reuse would require passing a logical size separately and removing textureSize() from shaders; it is intentionally not done.
Target count
For a linear chain, two targets are enough: the previous result and the current output. For a branch such as upsample + lowerpass -> combined, three are needed because both inputs are live while the output is being written. The theoretical minimum is the Strahler number of the graph (with no in-place writes); the implementation uses a deterministic depth-first post-order over input channels, which is a good heuristic but not an optimal register allocator. -dump-plan prints the actual buckets and their total size.
Runtime
Graph::render():
- binds the shared vertex array;
- swaps the front/back target of every feedback node (so
prev()returns the previous frame); - renders each node from the plan in order.
Node::render() binds its target, clears it, sets the Shadertoy uniforms, binds inputs to iChannel0..3, applies custom uniforms and draws a fullscreen triangle strip.
Feedback
node:prev() returns a NodePrev source that reads the owner's back buffer. The owner is allocated a pair of targets outside the pool and never released. The swap happens at the beginning of the frame, so the first frame reads a cleared black buffer.
Flags
-dump-plan— print pass order, target buckets and bytes after compilation;-no-target-reuse— allocate a fresh target per non-feedback node; useful for A/B checking aliasing correctness.