Skip to content

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:

  1. Roots. display first, then output if it is a different node.
  2. 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(), whose NodePrev source refers to the owner's back buffer and does not create an ordering edge when the owner is the node itself.
  3. Liveness. For every node, last_use is the maximum plan index of its consumers. Display and output roots are pinned for the whole frame.
  4. 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 whose last_use equals 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():

  1. binds the shared vertex array;
  2. swaps the front/back target of every feedback node (so prev() returns the previous frame);
  3. 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.