Expand description
§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};
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());Compilation rejects unknown resources, multiple writers, unproduced transient reads, and dependency cycles. A backend can then use:
execution_orderto submit passes;barriersto make writes visible before dependent reads;assign_transient_memoryto reuse compatible, non-overlapping allocations;cache_keyandchanged_passesto 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.
Modules§
- reference
- A CPU reference executor for a compiled
RenderGraph.
Structs§
- Barrier
- A synchronization point:
resourcewritten byaftermust be made visible tobefore(a read-after-write dependency) before that pass executes. - Cache
Key - An opaque, deterministic cache key for one compiled pass.
- Compiled
Graph - A validated, scheduled graph with per-pass cache keys, resource lifetimes, barriers, and transient-memory aliasing.
- Pass
Desc - Declaration of a pass: what it reads, what it writes, and what makes its output vary.
- PassId
- Handle to a pass declared in a
RenderGraph. - Render
Graph - A mutable render-graph description.
- Resource
Desc - Declaration of a graph resource.
- Resource
Id - Handle to a resource declared in a
RenderGraph. - Resource
Lifetime - Lifetime of a resource over the execution order, as
[first, last]indices into the compiled graph’s execution order. - Transient
Allocation - Assignment of transient resources to reusable physical memory slots.
Enums§
- Resource
Kind - The kind of a graph resource.