Skip to main content

Crate kael_render_graph

Crate kael_render_graph 

Source
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_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.

Modules§

reference
A CPU reference executor for a compiled RenderGraph.

Structs§

Barrier
A synchronization point: resource written by after must be made visible to before (a read-after-write dependency) before that pass executes.
CacheKey
An opaque, deterministic cache key for one compiled pass.
CompiledGraph
A validated, scheduled graph with per-pass cache keys, resource lifetimes, barriers, and transient-memory aliasing.
PassDesc
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.
RenderGraph
A mutable render-graph description.
ResourceDesc
Declaration of a graph resource.
ResourceId
Handle to a resource declared in a RenderGraph.
ResourceLifetime
Lifetime of a resource over the execution order, as [first, last] indices into the compiled graph’s execution order.
TransientAllocation
Assignment of transient resources to reusable physical memory slots.

Enums§

ResourceKind
The kind of a graph resource.