kael_render_graph 0.3.1

Render-graph: pass/resource DAG, scheduling, and time-varying cache invalidation for Kael
Documentation

kael_render_graph

kael_render_graph is Kael's small, GPU-backend-neutral render scheduler. It turns pass and resource declarations into a validated execution order with read-after-write barriers, transient-resource lifetimes, reusable memory slots, and deterministic dirty-subtree cache keys.

Use it with Kael, or independently in a renderer that owns its GPU API and resource types.

Build a graph

use kael_render_graph::{PassDesc, RenderGraph, ResourceDesc};

# fn main() -> anyhow::Result<()> {
let mut graph = RenderGraph::new();
let source = graph.add_resource(
    ResourceDesc::imported_texture("source").allocation_class(0x1001),
);
let filtered = graph.add_resource(
    ResourceDesc::transient_texture("filtered").allocation_class(0x1001),
);

let filter = graph.add_pass(
    PassDesc::new("filter")
        .read(source)
        .write(filtered)
        .param_hash(0x5eeda11),
);

let compiled = graph.compile()?;
assert_eq!(compiled.execution_order(), &[filter]);
assert!(compiled.cache_key(filter).is_some());
# Ok(())
# }

Compilation rejects unknown resources, multiple writers, unproduced transient reads, and dependency cycles. A backend can then use:

  • execution_order to submit passes;
  • barriers to make writes visible before dependent reads;
  • assign_transient_memory to reuse compatible, non-overlapping allocations;
  • cache_key and changed_passes to reuse unchanged pass outputs.

Transient resources alias only when their lifetimes do not overlap and their resource kind and caller-defined allocation_class match. Backends should derive that class from every allocation constraint, including dimensions, format, sample count, and usage. CompiledGraph::is_current_for detects a compilation made stale by subsequent graph construction.

Cache identity contract

PassDesc::param_hash is caller-defined. It must represent the operation identity, every output-affecting parameter, and a content generation for any imported input. frame_pts is a convenient identity component for decoded or otherwise time-varying frames. Omitting an identity component can reuse stale output.

The opaque 128-bit CacheKey is deterministic but is only an in-memory reuse key. Do not persist it or treat its format as stable across Kael releases. GPU backends should also scope cached resources by execution context that is not in the graph, including dimensions, pixel format, color space, and device.

CPU reference executor

The reference module evaluates texture-only graphs over linear, straight-alpha RGBA f32 images. It is useful for correctness tests, deterministic previews, and validating a GPU implementation. Its ExecutionCache applies explicit entry and resident-byte limits and refuses to reuse images at a different resolution.

The reference executor limits each image to 256 MiB and all returned logical images to 1 GiB. Graph construction is limited to 100,000 resources, 100,000 passes, 1,000,000 resource references, 4 KiB per diagnostic name, and 16 MiB across names. Use try_add_resource and try_add_pass when graph shape is dynamic so limit failures are returned instead of panicking.

This module is not a GPU backend, a color-management pipeline, or an optimized production image processor. Applications should execute compiled graphs on their rendering backend; the reference implementation is the portable oracle.

License

Licensed under the Apache License, Version 2.0. See LICENSE-APACHE.