Struct bevy::render::render_graph::RenderGraph

pub struct RenderGraph { /* private fields */ }
Expand description

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

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

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/compute_shader_game_of_life.rs (line 114)
103
104
105
106
107
108
109
110
111
112
113
114
115
116
    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);
    }
More examples
Hide additional examples
examples/app/headless_renderer.rs (line 209)
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
    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));
    }
examples/shader/gpu_readback.rs (line 93)
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
    fn finish(&self, app: &mut App) {
        let (s, r) = crossbeam_channel::unbounded();
        app.insert_resource(MainWorldReceiver(r));

        let render_app = app.sub_app_mut(RenderApp);
        render_app
            .insert_resource(RenderWorldSender(s))
            .init_resource::<ComputePipeline>()
            .init_resource::<Buffers>()
            .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>)),
                    // We need to run it after the render graph is done
                    // because this needs to happen after submit()
                    map_and_read_buffer.after(RenderSet::Render),
                ),
            );

        // 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());
    }

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

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

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

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
Examples found in repository?
examples/shader/compute_shader_game_of_life.rs (line 115)
103
104
105
106
107
108
109
110
111
112
113
114
115
116
    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);
    }
More examples
Hide additional examples
examples/app/headless_renderer.rs (line 210)
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
    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

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

Trait Implementations§

§

impl Debug for RenderGraph

§

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

Formats the value using the given formatter. Read more
§

impl Default for RenderGraph

§

fn default() -> RenderGraph

Returns the “default value” for a type. Read more
§

impl Resource for RenderGraph
where RenderGraph: Send + Sync + 'static,

Auto Trait Implementations§

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
§

impl<T, U> AsBindGroupShaderType<U> for T
where U: ShaderType, &'a T: for<'a> Into<U>,

§

fn as_bind_group_shader_type(&self, _images: &RenderAssets<GpuImage>) -> U

Return the T ShaderType for self. When used in AsBindGroup derives, it is safe to assume that all images in self exist.
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
§

impl<T> Downcast<T> for T

§

fn downcast(&self) -> &T

§

impl<T> Downcast for T
where T: Any,

§

fn into_any(self: Box<T>) -> Box<dyn Any>

Convert Box<dyn Trait> (where Trait: Downcast) to Box<dyn Any>. Box<dyn Any> can then be further downcast into Box<ConcreteType> where ConcreteType implements Trait.
§

fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>

Convert Rc<Trait> (where Trait: Downcast) to Rc<Any>. Rc<Any> can then be further downcast into Rc<ConcreteType> where ConcreteType implements Trait.
§

fn as_any(&self) -> &(dyn Any + 'static)

Convert &Trait (where Trait: Downcast) to &Any. This is needed since Rust cannot generate &Any’s vtable from &Trait’s.
§

fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)

Convert &mut Trait (where Trait: Downcast) to &Any. This is needed since Rust cannot generate &mut Any’s vtable from &mut Trait’s.
§

impl<T> DowncastSync for T
where T: Any + Send + Sync,

§

fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Sync + Send>

Convert Arc<Trait> (where Trait: Downcast) to Arc<Any>. Arc<Any> can then be further downcast into Arc<ConcreteType> where ConcreteType implements Trait.
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

§

impl<S> FromSample<S> for S

§

fn from_sample_(s: S) -> S

§

impl<T> FromWorld for T
where T: Default,

§

fn from_world(_world: &mut World) -> T

Creates Self using data from the given World.
§

impl<T> Instrument for T

§

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
§

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> IntoEither for T

source§

fn into_either(self, into_left: bool) -> Either<Self, Self>

Converts self into a Left variant of Either<Self, Self> if into_left is true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
source§

fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
where F: FnOnce(&Self) -> bool,

Converts self into a Left variant of Either<Self, Self> if into_left(&self) returns true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
§

impl<F, T> IntoSample<T> for F
where T: FromSample<F>,

§

fn into_sample(self) -> T

§

impl<T> NoneValue for T
where T: Default,

§

type NoneType = T

§

fn null_value() -> T

The none-equivalent value.
§

impl<T> Pointable for T

§

const ALIGN: usize = _

The alignment of pointer.
§

type Init = T

The type for initializers.
§

unsafe fn init(init: <T as Pointable>::Init) -> usize

Initializes a with the given initializer. Read more
§

unsafe fn deref<'a>(ptr: usize) -> &'a T

Dereferences the given pointer. Read more
§

unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

Mutably dereferences the given pointer. Read more
§

unsafe fn drop(ptr: usize)

Drops the object pointed to by the given pointer. Read more
source§

impl<R, P> ReadPrimitive<R> for P
where R: Read + ReadEndian<P>, P: Default,

source§

fn read_from_little_endian(read: &mut R) -> Result<Self, Error>

Read this value from the supplied reader. Same as ReadEndian::read_from_little_endian().
source§

fn read_from_big_endian(read: &mut R) -> Result<Self, Error>

Read this value from the supplied reader. Same as ReadEndian::read_from_big_endian().
source§

fn read_from_native_endian(read: &mut R) -> Result<Self, Error>

Read this value from the supplied reader. Same as ReadEndian::read_from_native_endian().
source§

impl<T> Same for T

§

type Output = T

Should always be Self
§

impl<T, U> ToSample<U> for T
where U: FromSample<T>,

§

fn to_sample_(self) -> U

source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
§

impl<T> Upcast<T> for T

§

fn upcast(&self) -> Option<&T>

§

impl<V, T> VZip<V> for T
where V: MultiLane<T>,

§

fn vzip(self) -> V

§

impl<T> WithSubscriber for T

§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
§

fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more
§

impl<T> ConditionalSend for T
where T: Send,

§

impl<S, T> Duplex<S> for T
where T: FromSample<S> + ToSample<S>,

§

impl<T> Settings for T
where T: 'static + Send + Sync,

§

impl<T> WasmNotSend for T
where T: Send,

§

impl<T> WasmNotSendSync for T
where T: WasmNotSend + WasmNotSync,

§

impl<T> WasmNotSync for T
where T: Sync,