Type erased materials #19667

tychedelia · 2025-06-16T01:04:25Z

Objective

In order to enable a number of patterns for dynamic materials in the engine, it's necessary to decouple the renderer from the Material trait.

This opens the possibility for:

Materials that aren't coupled to AsBindGroup.
2d using the underlying 3d bindless infrastructure.
Dynamic materials that can change their layout at runtime.
Materials that aren't even backed by a Rust struct at all.

Solution

In short, remove all trait bounds from render world material systems and resources. This means moving a bunch of stuff onto MaterialProperties and engaging in some hacks to make specialization work. Rather than storing the bind group data in MaterialBindGroupAllocator, right now we're storing it in a closure on MaterialProperties. TBD if this has bad performance characteristics.

Benchmarks

many_cubes:
cargo run --example many_cubes --release --features=bevy/trace_tracy -- --vary-material-data-per-instance:
@DGriffin91's Caldera
cargo run --release --features=bevy/trace_tracy -- --random-materials
@DGriffin91's Caldera with 20 unique material types (i.e. MaterialPlugin<M>) and random materials per mesh
cargo run --release --features=bevy/trace_tracy -- --random-materials

TODO

We almost certainly lost some parallelization from removing the type params that could be gained back from smarter iteration.
Test all the things that could have broken.
~~Fix meshlets~~

Showcase

See the example for a custom material implemented without the use of the Material trait and thus AsBindGroup.

github-actions · 2025-06-16T01:11:45Z

Your PR caused a change in the graphical output of an example or rendering test. This might be intentional, but it could also mean that something broke!
You can review it at https://pixel-eagle.com/project/B04F67C0-C054-4A6F-92EC-F599FEC2FD1D?filter=PR-19667

If it's expected, please add the M-Deliberate-Rendering-Change label.

If this change seems unrelated to your PR, you can consider updating your PR to target the latest main branch, either by rebasing or merging main into it.

github-actions · 2025-06-16T01:21:35Z

Your PR caused a change in the graphical output of an example or rendering test. This might be intentional, but it could also mean that something broke!
You can review it at https://pixel-eagle.com/project/B04F67C0-C054-4A6F-92EC-F599FEC2FD1D?filter=PR-19667

If it's expected, please add the M-Deliberate-Rendering-Change label.

If this change seems unrelated to your PR, you can consider updating your PR to target the latest main branch, either by rebasing or merging main into it.

github-actions · 2025-06-16T06:37:36Z

Your PR caused a change in the graphical output of an example or rendering test. This might be intentional, but it could also mean that something broke!
You can review it at https://pixel-eagle.com/project/B04F67C0-C054-4A6F-92EC-F599FEC2FD1D?filter=PR-19667

If it's expected, please add the M-Deliberate-Rendering-Change label.

If this change seems unrelated to your PR, you can consider updating your PR to target the latest main branch, either by rebasing or merging main into it.

IceSentry · 2025-06-16T19:32:46Z

Cargo.toml

@@ -566,7 +566,7 @@ ron = "0.10"
 flate2 = "1.0"
 serde = { version = "1", features = ["derive"] }
 serde_json = "1.0.140"
-bytemuck = "1.7"


Why did this need to change?

So the way that we're erasing material key (aka bind group data) in this PR at the moment is by going through bytemuck (see MaterialProperties where it's stored as a SmallVec), which basically puts it in our public api.

I'm somewhat uncertain about this change as it enforces new constraints on AsBindGroup::Data, namely the bytemuck derives and repr c. On the one hand, our use of bind group data internal to the engine is always in the form of flags and so this just makes that explicit. On the other hand, if people want to have weird material keys, maybe it isn't our place to stop them.

The alternative is doing Box<dyn Any>, but I ran into problems with making that hashable. The key bit here is that while the erased key only needs to be downcast to the concrete material key in the event you are respecializing, it needs to be hashable for the internal pipeline cache check. While actual respecialization is rare, the cache check happens any time a mesh/material changes.

I'm not sure I understand how this relates to changing the bytemuck version 😅

Oh sorry! It needs to match the version used in bevy_pbr. If we wanted to add that constraint, we should probably re-export it.

examples/3d/custom_material_implementation.rs

tychedelia · 2025-06-27T07:45:51Z

@ecoskey

I'm not the biggest fan of all the new interned labels or how big MaterialProperties has gotten, but it makes sense while we figure out better workflows/materials-as-entities.

I'm not either at all, but having a bunch of fields was gross. Part of the goal here too is to be able to re-use this for 2d, and so it would be ideal to keep it somewhat general. I have a version of this PR where I convert everything to entities and components and it's nice and clean but results in a lot more changes. I think we can get there but I wanted to do this as an incremental step. I'd be happy to remove the labels since ideally we remove them before 0.17 but idk, having 27 shader fields wasn't great either.

JMS55 · 2025-06-27T15:36:31Z

crates/bevy_pbr/src/material.rs

+                );
+
+            #[cfg(feature = "meshlet")]
+            render_app.add_systems(


Now that these don't depend on material generics, lets move them into the meshlet plugin.

crates/bevy_pbr/src/material.rs

crates/bevy_pbr/src/meshlet/mod.rs

atlv24 · 2025-06-27T18:33:42Z

crates/bevy_pbr/src/material.rs

+                    (
+                        check_views_lights_need_specialization.in_set(RenderSystems::PrepareAssets),
+                        // specialize_shadows also needs to run after prepare_assets::<PreparedMaterial>,
+                        // which is fine since ManageViews is after PrepareAssets


will ManageViews always be after PrepareAssets or might something change it down the line? i think a redundant edge for defensiveness doesnt have overhead, right?

atlv24

so cool. so good

IceSentry · 2025-06-27T20:11:26Z

examples/shader/texture_binding_array.rs

        })
    }

+    fn bind_group_data(&self) -> Self::Data {}


Very minor thing, but if it's valid to not return anything this should probably just the default behaviour of the trait

IceSentry

I think there's a couple of things that could still be simplified, but this is a good starting point and we can iterate on everything else. I'm very excited for what kind of features this will unlock for us!

LGTM to me

tychedelia added 2 commits June 15, 2025 16:54

Erase material types from the render world.

99be854

Custom material example.

1f74dfe

tychedelia changed the title ~~Erase material types from the render world~~ Remove Material trait bound from all render world systems and resources Jun 16, 2025

github-project-automation bot added this to Rendering Jun 16, 2025

Ci.

e449f3a

ecoskey self-requested a review June 16, 2025 01:46

Switch to SmallVec + fn ptr.

8d5d1ee

tychedelia added 3 commits June 16, 2025 02:46

Use labels.

838c4d3

Ci.

235f823

Ci.

0b98281

tychedelia changed the title ~~Remove Material trait bound from all render world systems and resources~~ Type erased materials Jun 16, 2025

tychedelia added 6 commits June 16, 2025 03:37

Ci.

21f1b95

Ci.

71f4a21

Fix example.

026c91e

Fix example.

40348f3

Docs.

1b616da

Merge branch 'main' into 18075-type-erased-materials

0f2b1c5

IceSentry self-requested a review June 16, 2025 19:32

IceSentry reviewed Jun 16, 2025

View reviewed changes

examples/3d/custom_material_implementation.rs Outdated Show resolved Hide resolved

tychedelia requested a review from IceSentry June 27, 2025 07:35

tychedelia added 2 commits June 27, 2025 00:42

Remove unused trait.

ab91ef7

Correct docs.

141d233

tychedelia requested a review from ecoskey June 27, 2025 07:48

Remove unused import.

1e6b8ed

github-actions bot mentioned this pull request Jun 27, 2025

19667 bevyengine/bevy-example-runner#156

Closed

JMS55 reviewed Jun 27, 2025

View reviewed changes

tychedelia requested a review from pcwalton June 27, 2025 16:13

IceSentry reviewed Jun 27, 2025

View reviewed changes

crates/bevy_pbr/src/material.rs Outdated Show resolved Hide resolved

IceSentry and others added 2 commits June 27, 2025 13:59

Couple of minor changes

5d939a2

Merge pull request #1 from IceSentry/erased_materials_minor_changes

11e9eb0

JMS55 reviewed Jun 27, 2025

View reviewed changes

crates/bevy_pbr/src/meshlet/mod.rs Outdated Show resolved Hide resolved

atlv24 reviewed Jun 27, 2025

View reviewed changes

atlv24 approved these changes Jun 27, 2025

View reviewed changes

tychedelia added 2 commits June 27, 2025 12:56

Ci.

fd6534b

Merge branch 'main' into 18075-type-erased-materials

81c12e2

IceSentry reviewed Jun 27, 2025

View reviewed changes

IceSentry approved these changes Jun 27, 2025

View reviewed changes

ecoskey approved these changes Jun 27, 2025

View reviewed changes

alice-i-cecile added this pull request to the merge queue Jun 27, 2025

Merged via the queue into bevyengine:main with commit e6ba9a6 Jun 27, 2025
40 checks passed

github-project-automation bot moved this to Done in Rendering Jun 27, 2025

rparrett mentioned this pull request Jun 28, 2025

Shadows in decals example are missing #19850

Open

Uh oh!

Type erased materials #19667

Type erased materials #19667

Uh oh!

Conversation

tychedelia commented Jun 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Objective

Solution

Benchmarks

TODO

Showcase

Uh oh!

github-actions bot commented Jun 16, 2025

Uh oh!

github-actions bot commented Jun 16, 2025

Uh oh!

github-actions bot commented Jun 16, 2025

Uh oh!

IceSentry Jun 16, 2025

Choose a reason for hiding this comment

Uh oh!

tychedelia Jun 16, 2025

Choose a reason for hiding this comment

Uh oh!

IceSentry Jun 16, 2025

Choose a reason for hiding this comment

Uh oh!

tychedelia Jun 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

tychedelia commented Jun 27, 2025

Uh oh!

JMS55 Jun 27, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

atlv24 Jun 27, 2025

Choose a reason for hiding this comment

Uh oh!

atlv24 left a comment

Choose a reason for hiding this comment

Uh oh!

IceSentry Jun 27, 2025

Choose a reason for hiding this comment

Uh oh!

IceSentry left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

tychedelia commented Jun 16, 2025 •

edited

Loading

tychedelia Jun 16, 2025 •

edited

Loading