Struct RenderGraph

pub struct RenderGraph { /* private fields */ }

The render graph configures the modular and re-usable render logic.

It is a retained and stateless (nodes themselves may have their own internal state) structure, which can not be modified while it is executed by the graph runner.

The render graph runner is responsible for executing the entire graph each frame. It will execute each node in the graph in the correct order, based on the edges between the nodes.

It consists of three main components: Nodes, Edges and Slots.

Nodes are responsible for generating draw calls and operating on input and output slots. Edges specify the order of execution for nodes and connect input and output slots together. Slots describe the render resources created or used by the nodes.

Additionally a render graph can contain multiple sub graphs, which are run by the corresponding nodes. Every render graph can have its own optional input node.

Example

Here is a simple render graph example with two nodes connected by a node edge.

#[derive(RenderLabel)]
enum Labels {
    A,
    B,
}

let mut graph = RenderGraph::default();
graph.add_node(Labels::A, MyNode);
graph.add_node(Labels::B, MyNode);
graph.add_node_edge(Labels::B, Labels::A);

Implementations

impl RenderGraph

pub fn update(&mut self, world: &mut World)

Updates all nodes and sub graphs of the render graph. Should be called before executing it.

pub fn set_input(&mut self, inputs: Vec<SlotInfo>)

Creates an GraphInputNode with the specified slots if not already present.

pub fn get_input_node(&self) -> Option<&NodeState>

Returns the NodeState of the input node of this graph.

See also

• input_node for an unchecked version.

pub fn input_node(&self) -> &NodeState

Returns the NodeState of the input node of this graph.

Panics

Panics if there is no input node set.

See also

• get_input_node for a version which returns an Option instead.

pub fn add_node<T>(&mut self, label: impl RenderLabel, node: T)

where T: Node,

Adds the node with the label to the graph. If the label is already present replaces it instead.

Examples found in repository

examples/shader/gpu_readback.rs (line 61)

    fn finish(&self, app: &mut App) {
        let render_app = app.sub_app_mut(RenderApp);
        render_app.init_resource::<ComputePipeline>().add_systems(
            Render,
            prepare_bind_group
                .in_set(RenderSet::PrepareBindGroups)
                // We don't need to recreate the bind group every frame
                .run_if(not(resource_exists::<GpuBufferBindGroup>)),
        );

        // Add the compute node as a top level node to the render graph
        // This means it will only execute once per frame
        render_app
            .world_mut()
            .resource_mut::<RenderGraph>()
            .add_node(ComputeNodeLabel, ComputeNode::default());
    }

examples/shader/compute_shader_game_of_life.rs (line 112)

    fn build(&self, app: &mut App) {
        // Extract the game of life image resource from the main world into the render world
        // for operation on by the compute shader and display on the sprite.
        app.add_plugins(ExtractResourcePlugin::<GameOfLifeImages>::default());
        let render_app = app.sub_app_mut(RenderApp);
        render_app.add_systems(
            Render,
            prepare_bind_group.in_set(RenderSet::PrepareBindGroups),
        );

        let mut render_graph = render_app.world_mut().resource_mut::<RenderGraph>();
        render_graph.add_node(GameOfLifeLabel, GameOfLifeNode::default());
        render_graph.add_node_edge(GameOfLifeLabel, bevy::render::graph::CameraDriverLabel);
    }

examples/app/headless_renderer.rs (line 211)

    fn build(&self, app: &mut App) {
        let (s, r) = crossbeam_channel::unbounded();

        let render_app = app
            .insert_resource(MainWorldReceiver(r))
            .sub_app_mut(RenderApp);

        let mut graph = render_app.world_mut().resource_mut::<RenderGraph>();
        graph.add_node(ImageCopy, ImageCopyDriver);
        graph.add_node_edge(bevy::render::graph::CameraDriverLabel, ImageCopy);

        render_app
            .insert_resource(RenderWorldSender(s))
            // Make ImageCopiers accessible in RenderWorld system and plugin
            .add_systems(ExtractSchedule, image_copy_extract)
            // Receives image data from buffer to channel
            // so we need to run it after the render graph is done
            .add_systems(Render, receive_image_from_buffer.after(RenderSet::Render));
    }

pub fn add_node_edges<const N: usize>( &mut self, edges: impl IntoRenderNodeArray<N>, )

Add node_edges based on the order of the given edges array.

Defining an edge that already exists is not considered an error with this api. It simply won’t create a new edge.

pub fn remove_node( &mut self, label: impl RenderLabel, ) -> Result<(), RenderGraphError>

Removes the node with the label from the graph. If the label does not exist, nothing happens.

pub fn get_node_state( &self, label: impl RenderLabel, ) -> Result<&NodeState, RenderGraphError>

Retrieves the NodeState referenced by the label.

pub fn get_node_state_mut( &mut self, label: impl RenderLabel, ) -> Result<&mut NodeState, RenderGraphError>

Retrieves the NodeState referenced by the label mutably.

pub fn get_node<T>( &self, label: impl RenderLabel, ) -> Result<&T, RenderGraphError>

where T: Node,

Retrieves the Node referenced by the label.

pub fn get_node_mut<T>( &mut self, label: impl RenderLabel, ) -> Result<&mut T, RenderGraphError>

where T: Node,

Retrieves the Node referenced by the label mutably.

pub fn try_add_slot_edge( &mut self, output_node: impl RenderLabel, output_slot: impl Into<SlotLabel>, input_node: impl RenderLabel, input_slot: impl Into<SlotLabel>, ) -> Result<(), RenderGraphError>

Adds the Edge::SlotEdge to the graph. This guarantees that the output_node is run before the input_node and also connects the output_slot to the input_slot.

Fails if any invalid RenderLabels or SlotLabels are given.

See also

• add_slot_edge for an infallible version.

pub fn add_slot_edge( &mut self, output_node: impl RenderLabel, output_slot: impl Into<SlotLabel>, input_node: impl RenderLabel, input_slot: impl Into<SlotLabel>, )

Adds the Edge::SlotEdge to the graph. This guarantees that the output_node is run before the input_node and also connects the output_slot to the input_slot.

Panics

Any invalid RenderLabels or SlotLabels are given.

See also

• try_add_slot_edge for a fallible version.

pub fn remove_slot_edge( &mut self, output_node: impl RenderLabel, output_slot: impl Into<SlotLabel>, input_node: impl RenderLabel, input_slot: impl Into<SlotLabel>, ) -> Result<(), RenderGraphError>

Removes the Edge::SlotEdge from the graph. If any nodes or slots do not exist then nothing happens.

pub fn try_add_node_edge( &mut self, output_node: impl RenderLabel, input_node: impl RenderLabel, ) -> Result<(), RenderGraphError>

Adds the Edge::NodeEdge to the graph. This guarantees that the output_node is run before the input_node.

Fails if any invalid RenderLabel is given.

See also

• add_node_edge for an infallible version.

pub fn add_node_edge( &mut self, output_node: impl RenderLabel, input_node: impl RenderLabel, )

Adds the Edge::NodeEdge to the graph. This guarantees that the output_node is run before the input_node.

Panics

Panics if any invalid RenderLabel is given.

See also

• try_add_node_edge for a fallible version.

Examples found in repository

examples/shader/compute_shader_game_of_life.rs (line 113)

    fn build(&self, app: &mut App) {
        // Extract the game of life image resource from the main world into the render world
        // for operation on by the compute shader and display on the sprite.
        app.add_plugins(ExtractResourcePlugin::<GameOfLifeImages>::default());
        let render_app = app.sub_app_mut(RenderApp);
        render_app.add_systems(
            Render,
            prepare_bind_group.in_set(RenderSet::PrepareBindGroups),
        );

        let mut render_graph = render_app.world_mut().resource_mut::<RenderGraph>();
        render_graph.add_node(GameOfLifeLabel, GameOfLifeNode::default());
        render_graph.add_node_edge(GameOfLifeLabel, bevy::render::graph::CameraDriverLabel);
    }

examples/app/headless_renderer.rs (line 212)

    fn build(&self, app: &mut App) {
        let (s, r) = crossbeam_channel::unbounded();

        let render_app = app
            .insert_resource(MainWorldReceiver(r))
            .sub_app_mut(RenderApp);

        let mut graph = render_app.world_mut().resource_mut::<RenderGraph>();
        graph.add_node(ImageCopy, ImageCopyDriver);
        graph.add_node_edge(bevy::render::graph::CameraDriverLabel, ImageCopy);

        render_app
            .insert_resource(RenderWorldSender(s))
            // Make ImageCopiers accessible in RenderWorld system and plugin
            .add_systems(ExtractSchedule, image_copy_extract)
            // Receives image data from buffer to channel
            // so we need to run it after the render graph is done
            .add_systems(Render, receive_image_from_buffer.after(RenderSet::Render));
    }

pub fn remove_node_edge( &mut self, output_node: impl RenderLabel, input_node: impl RenderLabel, ) -> Result<(), RenderGraphError>

Removes the Edge::NodeEdge from the graph. If either node does not exist then nothing happens.

pub fn validate_edge( &mut self, edge: &Edge, should_exist: EdgeExistence, ) -> Result<(), RenderGraphError>

Verifies that the edge existence is as expected and checks that slot edges are connected correctly.

pub fn has_edge(&self, edge: &Edge) -> bool

Checks whether the edge already exists in the graph.

pub fn iter_nodes(&self) -> impl Iterator<Item = &NodeState>

Returns an iterator over the NodeStates.

pub fn iter_nodes_mut(&mut self) -> impl Iterator<Item = &mut NodeState>

Returns an iterator over the NodeStates, that allows modifying each value.

pub fn iter_sub_graphs( &self, ) -> impl Iterator<Item = (Interned<dyn RenderSubGraph>, &RenderGraph)>

Returns an iterator over the sub graphs.

pub fn iter_sub_graphs_mut( &mut self, ) -> impl Iterator<Item = (Interned<dyn RenderSubGraph>, &mut RenderGraph)>

Returns an iterator over the sub graphs, that allows modifying each value.

pub fn iter_node_inputs( &self, label: impl RenderLabel, ) -> Result<impl Iterator<Item = (&Edge, &NodeState)>, RenderGraphError>

Returns an iterator over a tuple of the input edges and the corresponding output nodes for the node referenced by the label.

pub fn iter_node_outputs( &self, label: impl RenderLabel, ) -> Result<impl Iterator<Item = (&Edge, &NodeState)>, RenderGraphError>

Returns an iterator over a tuple of the output edges and the corresponding input nodes for the node referenced by the label.

pub fn add_sub_graph( &mut self, label: impl RenderSubGraph, sub_graph: RenderGraph, )

Adds the sub_graph with the label to the graph. If the label is already present replaces it instead.

pub fn remove_sub_graph(&mut self, label: impl RenderSubGraph)

Removes the sub_graph with the label from the graph. If the label does not exist then nothing happens.

pub fn get_sub_graph(&self, label: impl RenderSubGraph) -> Option<&RenderGraph>

Retrieves the sub graph corresponding to the label.

pub fn get_sub_graph_mut( &mut self, label: impl RenderSubGraph, ) -> Option<&mut RenderGraph>

Retrieves the sub graph corresponding to the label mutably.

pub fn sub_graph(&self, label: impl RenderSubGraph) -> &RenderGraph

Retrieves the sub graph corresponding to the label.

Panics

Panics if any invalid subgraph label is given.

See also

• get_sub_graph for a fallible version.

pub fn sub_graph_mut(&mut self, label: impl RenderSubGraph) -> &mut RenderGraph

Retrieves the sub graph corresponding to the label mutably.

Panics

Panics if any invalid subgraph label is given.

See also

• get_sub_graph_mut for a fallible version.

Trait Implementations

impl Debug for RenderGraph

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Default for RenderGraph

fn default() -> RenderGraph

Returns the “default value” for a type.

impl Resource for RenderGraph

where RenderGraph: Send + Sync + 'static,