RenderTask #21603

JMS55 · 2025-10-19T15:23:03Z

Objective

Reduce boilerplate for render nodes, building on my experience writing SSAO, TAA, virtual geometry, Solari, etc
Provide the missing low-level render API helper:
- High level - Material and FullscreenMaterial
- Mid level - Phase stuff
- Low level - Missing until now

Solution

Provide a new RenderTask trait to handle all the boilerplate you would otherwise have to write manually:
- Checking GPU features/limits when setting up the plugin
- Setting up a render graph node and edge ordering
- Preparing and caching textures and buffers
- Preparing and caching pipelines
- Preparing and caching bind groups/layouts
- Setting up wgpu compute/render passes and setting state between dispatches/draws
- Inserting profiling spans

Testing

Did you test these changes? If so, how?
Are there any parts that need more testing?
How can other people (reviewers) test your changes? Is there anything specific they need to know?
If relevant, what platforms did you test these changes on, and are there any important ones you can't test?

Showcase

impl RenderTask for SolariLighting {
    type RenderNodeLabel = node::graph::SolariLightingNode;
    type RenderNodeSubGraph = Core3d;
    fn render_node_ordering() -> impl IntoRenderNodeArray {
        (
            Node3d::EndPrepasses,
            node::graph::SolariLightingNode,
            Node3d::EndMainPass,
        )
    }

    fn encode_commands(&self, mut encoder: RenderTaskEncoder, entity: Entity, world: &World) {
        let Some((
            solari_lighting_resources,
            view_target,
            view_prepass_textures,
            view_uniform_offset,
            previous_view_uniform_offset,
        )) = world.entity(entity).get_components::<(
            &SolariLightingResources,
            &ViewTarget,
            &ViewPrepassTextures,
            &ViewUniformOffset,
            &PreviousViewUniformOffset,
        )>()
        else {
            return;
        };

        let frame_count = world.resource::<FrameCount>();
        let frame_index = frame_count.0.wrapping_mul(5782582);

        let push_constants = &[frame_index, self.reset as u32];

        encoder
            .compute_pass("presample_light_tiles")
            .shader(load_embedded_asset!(world, "presample_light_tiles.wgsl"))
            .push_constants(push_constants)
            .dispatch_1d(LIGHT_TILE_BLOCKS as u32);
    }
}

torsteingrindvik · 2025-10-19T17:48:20Z

Is ordering always (before, myself, after)? If so is it enough to specify before and after?

JMS55 · 2025-10-19T17:59:48Z

Is ordering always (before, myself, after)? If so is it enough to specify before and after?

I suppose yeah, but before/after can be more than 1 thing.

atlv24 · 2025-10-19T21:59:48Z

I think @torsteingrindvik was suggesting having

    type AfterNodeLabel = Node3d::EndPrepasses;
    type RenderNodeLabel = node::graph::SolariLightingNode;
    type BeforeNodeLabel = Node3d::EndMainPass;
    
    // this is the same for all RenderTasks
    fn render_node_ordering() -> impl IntoRenderNodeArray {
        (
            Self::AfterNodeLabel,
            Self::RenderNodeLabel,
            Self::BeforeNodeLabel,
        )
    }

JMS55 · 2025-10-19T23:49:50Z

No yeah I get the idea. I just don't think we can do that because you could want more than 1 thing before/after.

Render api2

Further doc work

tychedelia · 2025-10-31T18:36:37Z

Need to review more closely, but I'm a little on the fence about this. On the one hand, I've wanted to implement something exactly this shape before for similar reasons. But I've hesitated in the past because this kind of approach feels a bit like patching over fundamental deficiencies of our render graph architecture rather than a real solution. I worry that these kinds of trait based solutions are brittle and often do not reduce as much boilerplate as we would like. I've often had the feeling when working with ECS that things can be ugly but them being ad-hoc is still preferable to being formalized prematurely into a clunky abstraction, which is what I worry about here.

cart · 2025-10-31T20:06:08Z

but I'm a little on the fence about this

Same. Adding a new layer of abstraction should be a method of last resort, and I'm not (yet) convinced this is a net win. It would be helpful to port a few Bevy features over in this PR to illustrate the value here (and also show that the abstraction is functional).

superdump · 2025-10-31T21:33:37Z

crates/bevy_render/src/render_task/resource_cache.rs

+        todo!()
+        // self.bind_groups
+        //     .entry(descriptor.clone())
+        //     .or_insert_with(|| render_device.wgpu_device().create_bind_group(&descriptor))
+        //     .clone()


I haven't implemented caching for bind groups yet. Tricky to figure out how to do the hashing.

superdump · 2025-10-31T21:35:17Z

crates/bevy_render/src/render_task/resource_cache.rs

+    textures: HashMap<(Entity, TextureDescriptor<'static>), TextureView>,
+    buffers: HashMap<(Entity, BufferDescriptor<'static>), Buffer>,
+    _bind_groups: HashMap<BindGroupDescriptor<'static>, BindGroup>,
+    compute_pipelines: HashMap<ComputePipelineDescriptor, CachedComputePipelineId>,
+    render_pipelines: HashMap<RenderPipelineDescriptor, CachedRenderPipelineId>,


I wonder if some of these should be separate / global and not constrained to one render task instance?

They could be, but I don't see much point in it, and it would reduce parallelism unless we used a parallel hashmap.

superdump · 2025-10-31T21:42:36Z

crates/bevy_render/src/render_task/node.rs

+
+    /// Begin a new render pass.
+    pub fn render_pass(&mut self) {
+        todo!()


It's easy enough to add later, but I wanted to focus on compute first.

superdump · 2025-10-31T21:45:25Z

crates/bevy_render/src/render_task/node.rs

+pub struct RenderTaskContext<'a> {
+    camera_entity: Entity,
+    command_encoder: &'a mut CommandEncoder,
+    compute_pass: Option<ComputePass<'static>>,


That this is 'static looks surprising to me. It feels like it should have its own lifetime that is bound to the lifetime of the CommandEncoder, which is 'a?

It's a little bit of a hack because I can't express the lifetime properly. Notice that I used forget_lifetime.

superdump · 2025-10-31T21:50:34Z

crates/bevy_render/src/render_task/bind.rs

+/// Corresponds to `var<storage, read> my_buffer: T` in a WGSL shader.
+#[derive(Clone, Deref)]
+pub struct StorageBufferReadOnly<'a>(pub &'a Buffer);
+
+/// Corresponds to `var<storage, read_write> my_buffer: T` in a WGSL shader.
+#[derive(Clone, Deref)]
+pub struct StorageBufferReadWrite<'a>(pub &'a Buffer);
+
+/// Corresponds to `var my_texture: texture_2d<T>` in a WGSL shader.
+#[derive(Clone, Deref)]
+pub struct SampledTexture<'a>(pub &'a TextureView);
+
+/// Corresponds to `var my_texture: texture_storage_2d<F, read_write>` in a WGSL shader.
+#[derive(Clone, Deref)]
+pub struct StorageTextureReadWrite<'a>(pub &'a TextureView);
+
+/// Corresponds to `var my_texture: texture_storage_2d<F, write>` in a WGSL shader.
+#[derive(Clone, Deref)]
+pub struct StorageTextureWriteOnly<'a>(pub &'a TextureView);
+
+/// Corresponds to `var my_texture: texture_storage_2d<F, read>` in a WGSL shader.
+#[derive(Clone, Deref)]
+pub struct StorageTextureReadOnly<'a>(pub &'a TextureView);
+
+/// Corresponds to `var my_texture: texture_storage_2d<F, atomic>` in a WGSL shader.
+#[derive(Clone, Deref)]
+pub struct StorageTextureAtomic<'a>(pub &'a TextureView);


I'm not keen on this. Adding separate types for all combinations of buffer and texture binding types feel 'undesirable'?

Why so? You need to specify the bindings types somewhere.

superdump · 2025-10-31T21:52:57Z

crates/bevy_render/src/render_task/compute_builder.rs

+    pub fn dispatch_1d(mut self, x: u32) -> Option<Self> {
+        self.setup_state()?;
+        self.pass.dispatch_workgroups(x, 1, 1);
+        Some(self)
+    }
+
+    pub fn dispatch_2d(mut self, x: u32, y: u32) -> Option<Self> {
+        self.setup_state()?;
+        self.pass.dispatch_workgroups(x, y, 1);
+        Some(self)
+    }
+
+    pub fn dispatch_3d(mut self, x: u32, y: u32, z: u32) -> Option<Self> {
+        self.setup_state()?;
+        self.pass.dispatch_workgroups(x, y, z);
+        Some(self)
+    }


Is there much value in these three instead of just dispatch_3d called dispatch?

I mean sure, but I think it's nice compared to doing dispatch(x, y, 1).

Trashtalk217 · 2025-11-01T00:35:51Z

crates/bevy_render/src/render_task/extract.rs

+use bevy_camera::Camera;
+use bevy_ecs::system::{Commands, Query};
+
+// TODO: Use SyncComponentPlugin or ExtractComponentPlugin?


I'm 90% sure that ExtractComponentPlugin handles everything you're trying to do here. Including handling when a Camera is removed.

Maybe not mutating T in the main world, but then again. I'm not quite sure of all the things you're trying to do with RenderTask. If you have more precise questions, I think I can answer them though.

Yeah I think you're right. And I think I can get away with not needing to handle main world mutations if I move temporal reset tracking to a dedicated component.

Except handling camera.is_active, actually.

WIP RenderTask

jasmine-nominal and others added 12 commits October 16, 2025 12:24

WIP RenderTask API

f8c6697

WIP ComputeCommandBuilder

5cc39a3

Merge commit 'c392d28d30f34b7d2b69b806136b9643379f9284' into render-api

4ff01a9

More WIP

c32863b

Lifetime fixes

ec0d216

Fix type

782c353

Adjust approach for query data

9d6c1b1

Fix lifetime issues

7217018

More WIP

531efb4

More progress

4970d62

Get render_node_ordering() working

7873d53

Make dispatches return option

f4a1e35

github-project-automation bot added this to Rendering Oct 19, 2025

Merge branch 'main' into render-api

04114e1

JMS55 mentioned this pull request Oct 19, 2025

Add FullscreenMaterial #20414

Open

jasmine-nominal and others added 7 commits October 20, 2025 15:59

Merge commit '04114e12d98f520060d5ea3ea5a5b4dab13aab88' into render-api

2ae97b2

Bind group WIP

b27f683

Resource cache WIP

baf7d5a

WIP bindings

0c14c0d

Misc

077cb57

More WIP

0d85d55

Merge commit '0d85d5558521e2ed670d9fc34cbe5e1d11c50576' into render-api2

1b8431d

jasmine-nominal and others added 5 commits October 31, 2025 11:14

Skip BG cache and assume D2 textures to get things working for now

3a1ad7d

Suppress unused

ebc3e77

Docs

10e6423

Merge commit '906bc14d735b0f29ca4faf1c3f39aff9080da94a' into render-api2

ed8ff39

Merge pull request #41 from jasmine-nominal/render-api2

044938b

Render api2

JMS55 marked this pull request as ready for review October 31, 2025 17:53

JMS55 added S-Needs-Review Needs reviewer attention (from anyone!) to move forward and removed S-Waiting-on-Author The author needs to make changes or address concerns before this can be merged labels Oct 31, 2025

jasmine-nominal and others added 2 commits October 31, 2025 14:24

Further doc work

9d715b7

Merge pull request #42 from jasmine-nominal/render-api2

656b790

Further doc work

IceSentry self-requested a review October 31, 2025 18:26

superdump reviewed Oct 31, 2025

View reviewed changes

Trashtalk217 reviewed Nov 1, 2025

View reviewed changes

JMS55 and others added 8 commits November 16, 2025 20:39

Merge commit 'd87d491d29a628db44a69c04665c56322d912512' into render-api2

830cefa

API changes

2d3b1a3

Add note about depth textures

fdcd620

Make encode_commands return Option<()>

f122f17

WIP SSAO port

d3526c8

API improvements

5c0bd04

More work porting SSAO example

74436ec

Merge pull request #43 from jasmine-nominal/render-api3

cebf37c

WIP RenderTask

JMS55 marked this pull request as draft November 26, 2025 03:30

Merge branch 'main' into render-api

6e92d97

Uh oh!

RenderTask #21603

Are you sure you want to change the base?

RenderTask #21603

Conversation

JMS55 commented Oct 19, 2025 • edited by alice-i-cecile Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Objective

Solution

Testing

Showcase

Uh oh!

torsteingrindvik commented Oct 19, 2025

Uh oh!

JMS55 commented Oct 19, 2025

Uh oh!

atlv24 commented Oct 19, 2025

Uh oh!

JMS55 commented Oct 19, 2025

Uh oh!

tychedelia commented Oct 31, 2025

Uh oh!

cart commented Oct 31, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

9 participants

JMS55 commented Oct 19, 2025 •

edited by alice-i-cecile

Loading