Implement basic clustered decal projectors. by pcwalton · Pull Request #17315 · bevyengine/bevy

pcwalton · 2025-01-11T22:01:02Z

This commit adds support for decal projectors to Bevy, allowing for textures to be projected on top of geometry. Decal projectors are clusterable objects, just as punctual lights and light probes are. This means that decals are only evaluated for objects within the conservative bounds of the projector, and they don't require a second pass.

These clustered decals require support for bindless textures and as such currently don't work on WebGL 2, WebGPU, macOS, or iOS. For an alternative that doesn't require bindless, see PR #16600. I believe that both contact projective decals in #16600 and clustered decals are desirable to have in Bevy. Contact projective decals offer broader hardware and driver support, while clustered decals don't require the creation of bounding geometry.

A new example, decal_projectors, has been added, which demonstrates multiple decals on a rotating object. The decal projectors can be scaled and rotated with the mouse.

There are several limitations of this initial patch that can be addressed in follow-ups:

There's no way to specify the Z-index of decals. That is, the order in which multiple decals are blended on top of one another is arbitrary. A follow-up could introduce some sort of Z-index field so that artists can specify that some decals should be blended on top of others.
Decals don't take the normal of the surface they're projected onto into account. Most decal implementations in other engines have a feature whereby the angle between the decal projector and the normal of the surface must be within some threshold for the decal to appear. Often, artists can specify a fade-off range for a smooth transition between oblique surfaces and aligned surfaces.
There's no distance-based fadeoff toward the end of the projector range. Many decal implementations have this.

This addresses #2401.

Showcase

This commit adds support for *decal projectors* to Bevy, allowing for textures to be projected on top of geometry. Decal projectors are clusterable objects, just as punctual lights and light probes are. This means that decals are only evaluated for objects within the conservative bounds of the projector, and they don't require a second pass. These clustered decals require support for bindless textures and as such currently don't work on WebGL 2, WebGPU, macOS, or iOS. For an alternative that doesn't require bindless, see PR bevyengine#16600. I believe that both contact projective decals in bevyengine#16600 and clustered decals are desirable to have in Bevy. Contact projective decals offer broader hardware and driver support, while clustered decals don't require the creation of bounding geometry. A new example, `decal_projectors`, has been added, which demonstrates multiple decals on a rotating object. The decal projectors can be scaled and rotated with the mouse. There are several limitations of this initial patch that can be addressed in follow-ups: 1. There's no way to specify the Z-index of decals. That is, the order in which multiple decals are blended on top of one another is arbitrary. A follow-up could introduce some sort of Z-index field so that artists can specify that some decals should be blended on top of others. 2. Decals don't take the normal of the surface they're projected onto into account. Most decal implementations in other engines have a feature whereby the angle between the decal projector and the normal of the surface must be within some threshold for the decal to appear. Often, artists can specify a fade-off range for a smooth transition between oblique surfaces and aligned surfaces. 3. There's no distance-based fadeoff toward the end of the projector range. Many decal implementations have this.

github-actions · 2025-01-11T22:20:39Z

The generated examples/README.md is out of sync with the example metadata in Cargo.toml or the example readme template. Please run cargo run -p build-templated-pages -- update examples to update it, and commit the file change.

JMS55

Generally looks fine. Two requests:

Can you unify the naming a little more? In some places they're called clustered decals, othertimes projected. I'd rather stick with clustered everywhere.
Won't block on it, but I would like to have one of the decals in the example be a custom material, so that users can see how to do that. I'm not sure myself, I think you'd need a switch statement on the decal type for any material on a surface that could receive a decal? Not sure.

JMS55 · 2025-01-12T21:54:37Z

crates/bevy_pbr/src/cluster/assign.rs

    }

+    // TODO: this should be "if supports_bindless" or something
+    if binding_arrays_are_usable(&render_device, &render_adapter) {


I don't know how expensive this check is, maybe pull out of the loop?

I removed the out-of-date comment. It should already be pulled out of the loop.

crates/bevy_pbr/src/decal/projector.rs

JMS55 · 2025-01-12T22:04:51Z

crates/bevy_pbr/src/decal/clustered.wgsl

+) -> vec4<f32> {
+    var base_color = initial_base_color;
+
+#ifdef CLUSTERED_DECALS_ARE_USABLE


Suggested change

#ifdef CLUSTERED_DECALS_ARE_USABLE

#ifdef CLUSTERED_DECALS_ARE_USABLE

Is this supposed to be called that? Do you mean to call it "CLUSTERED_DECALS_USED_IN_SCENE" or something?

Yeah, it's supposed to be called CLUSTERED_DECALS_ARE_USABLE; it's #define'd based on whether bindless is available.

HAS_CLUSTERED_DECALS or WITH_CLUSTERED_DECALS are more common

pcwalton · 2025-01-13T01:51:31Z

@JMS55 Do you still think a projector should be called a DecalProjector? Or should I change that to ClusteredDecal? I took the name from Unity's Decal Projectors.

alice-i-cecile · 2025-01-15T02:32:10Z

Merging #16600 first since it's ready; we can merge the examples together into one here :)

pcwalton · 2025-01-22T06:06:47Z

@JMS55 I updated this with a couple of important changes:

The term "projector" has been replaced with "clustered" everywhere.
There's now a tag, which is intended to be used for application-specific purposes like indexing an array of normal maps. I added a simple demonstration of its use to the example.

rparrett

Limited review, most of the rendering code is out of my league. "Approved" once platform support questions are addressed.

examples/3d/clustered_decals.rs

crates/bevy_pbr/src/decal/clustered.rs

rparrett · 2025-01-25T15:46:05Z

crates/bevy_pbr/src/decal/clustered.rs

+/// The maximum number of decals that can be present in a view.
+///
+/// This number is currently relatively low in order to work around the lack of
+/// first-class binding arrays in `wgpu`. When that feature is implemented, this


Is there a tracking issue for this?

There's gfx-rs/wgpu#3637, is that what you mean?

rparrett · 2025-01-25T15:48:54Z

crates/bevy_pbr/src/decal/clustered.rs

+//!
+//! Clustered decals are the highest-quality types of decals that Bevy supports,
+//! but they require bindless textures. This means that they presently can't be
+//! used on WebGL 2, WebGPU, macOS, or iOS. Bevy's clustered decals can be used


The example seems to work on my m1 mac?

Fails as expected on WebGL and WebGPU, but with sort of mysterious errors. Not sure if this is expected or if the bindless gating isn't working properly.

(This text is repeated for ClusteredDecal docs, so any rework should be repeated there)

// webgl2 ERROR crates/bevy_render/src/render_resource/pipeline_cache.rs:895 failed to process shader:error: no definition in scope for identifier: 'bevy_pbr::decal::clustered::clustered_decal_iterator_new' /// webgpu displays the same error, but also has various complains. [Invalid ShaderModule (unlabeled)] is invalid. - While validating compute stage ([Invalid ShaderModule (unlabeled)], entryPoint: "main"). - While calling [Device].CreateComputePipeline([ComputePipelineDescriptor ""build indexed indirect parameters""]). Understand this warningAI 127.0.0.1/:1 Compilation log for [Invalid ShaderModule (unlabeled)]: 1 error(s) generated while compiling the shader: :36:1 error: atomic variables in 'storage' address space must have 'read_write' access mode var<storage> indirect_parameters_metadata: array<IndirectParametersMetadataX_naga_oil_mod_XMJSXM6K7OBRHEOR2NVSXG2C7OBZGK4DSN5RWK43TL52HS4DFOMX>; ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ :25:5 note: atomic sub-type of 'array<IndirectParametersMetadataX_naga_oil_mod_XMJSXM6K7OBRHEOR2NVSXG2C7OBZGK4DSN5RWK43TL52HS4DFOMX>' is declared here instance_count: atomic<u32>, ^^^^^^^^^^^^^^

For WebGL, that's expected. I don't think there's much point in gating off decals with an ifdef in the example's custom shader if the example requires a platform that decals don't work on to begin with.
For WebGPU, the indirect parameters metadata error is unrelated and I'd rather not fix that here.

Good point on the macOS/iOS thing. They don't have true bindless, but I forget that wgpu has a partial workaround that's good enough to make clustered decals work. I removed the mention of those platforms.

The error means some bound buffer is marked read-only but contains some atomic. That's not allowed by WGSL. In Hanabi I use some #ifdef to change the definition of the atomic fields to non-aromic and read them as non-atomic where it's safe to do so, to avoid that error. That's a bit tedious but it's clean.

crates/bevy_pbr/src/render/mesh_view_types.wgsl

tychedelia

Tested on m1 mbp.

tychedelia · 2025-01-25T18:09:31Z

crates/bevy_pbr/src/decal/clustered.wgsl

+//
+// Returns true if another decal was found or false if no more decals were found
+// for this position.
+fn clustered_decal_iterator_next(iterator: ptr<function, ClusteredDecalIterator>) -> bool {


cool pattern, hadn't seen this before

alice-i-cecile · 2025-01-26T20:13:33Z

Example runner looks good! https://pixel-eagle.com/project/B25A040A-A980-4602-B90C-D480AB84076D/run/7475/compare/7463

This commit adds support for *decal projectors* to Bevy, allowing for textures to be projected on top of geometry. Decal projectors are clusterable objects, just as punctual lights and light probes are. This means that decals are only evaluated for objects within the conservative bounds of the projector, and they don't require a second pass. These clustered decals require support for bindless textures and as such currently don't work on WebGL 2, WebGPU, macOS, or iOS. For an alternative that doesn't require bindless, see PR bevyengine#16600. I believe that both contact projective decals in bevyengine#16600 and clustered decals are desirable to have in Bevy. Contact projective decals offer broader hardware and driver support, while clustered decals don't require the creation of bounding geometry. A new example, `decal_projectors`, has been added, which demonstrates multiple decals on a rotating object. The decal projectors can be scaled and rotated with the mouse. There are several limitations of this initial patch that can be addressed in follow-ups: 1. There's no way to specify the Z-index of decals. That is, the order in which multiple decals are blended on top of one another is arbitrary. A follow-up could introduce some sort of Z-index field so that artists can specify that some decals should be blended on top of others. 2. Decals don't take the normal of the surface they're projected onto into account. Most decal implementations in other engines have a feature whereby the angle between the decal projector and the normal of the surface must be within some threshold for the decal to appear. Often, artists can specify a fade-off range for a smooth transition between oblique surfaces and aligned surfaces. 3. There's no distance-based fadeoff toward the end of the projector range. Many decal implementations have this. This addresses bevyengine#2401. ## Showcase ![Screenshot 2025-01-11 052913](https://github.com/user-attachments/assets/8fabbafc-60fb-461d-b715-d7977e10fe1f)

alice-i-cecile · 2025-03-25T20:08:10Z

Thank you to everyone involved with the authoring or reviewing of this PR! This work is relatively important and needs release notes! Head over to bevyengine/bevy-website#1986 if you'd like to help out.

pcwalton requested review from Elabajaba, IceSentry and JMS55 January 11, 2025 22:01

pcwalton added A-Rendering Drawing game state to the screen C-Feature A new feature, making something new possible S-Needs-Review Needs reviewer attention (from anyone!) to move forward labels Jan 11, 2025

Typo police

adf84e1

BenjaminBrienen added D-Complex Quite challenging from either a design or technical perspective. Ask for help! D-Shaders This code uses GPU shader languages labels Jan 11, 2025

pcwalton mentioned this pull request Jan 12, 2025

Forward decals (port of bevy_contact_projective_decals) #16600

Merged

alice-i-cecile added the M-Release-Note Work that should be called out in the blog due to impact label Jan 12, 2025

pcwalton added 4 commits January 11, 2025 19:12

Merge remote-tracking branch 'origin/main' into decal-projectors

0a328bd

Fix meshlet compile problem

626774f

Update README.md

1dd2fbf

Doc check police

dc7f17e

JMS55 approved these changes Jan 12, 2025

View reviewed changes

Merge remote-tracking branch 'origin/main' into decal-projectors

a780653

pcwalton added 3 commits January 21, 2025 19:34

Merge remote-tracking branch 'origin/main' into decal-projectors

92d6467

Rename "decal projector" to "clustered decal"

fa427e3

Add an example to show custom decal rendering

b04960a

Address review comments

def2468

pcwalton requested a review from JMS55 January 22, 2025 06:08

pcwalton added 3 commits January 21, 2025 22:09

Merge remote-tracking branch 'origin/main' into decal-projectors

07b9568

Internal import police

b261c70

Merge remote-tracking branch 'origin/main' into decal-projectors

bf074e5

pcwalton added 2 commits January 23, 2025 10:58

Make the maximum number of view decals match the shader

4531ffa

Update for the HashMap change

2692bcd

rparrett approved these changes Jan 25, 2025

View reviewed changes

Merge remote-tracking branch 'origin/main' into decal-projectors

69dd57b

tychedelia approved these changes Jan 25, 2025

View reviewed changes

Address review comments

161a02d

pcwalton added S-Ready-For-Final-Review This PR has been approved by the community. It's ready for a maintainer to consider merging it and removed S-Needs-Review Needs reviewer attention (from anyone!) to move forward labels Jan 25, 2025

github-actions bot mentioned this pull request Jan 26, 2025

17315 bevyengine/bevy-example-runner#95

Closed

alice-i-cecile added this pull request to the merge queue Jan 26, 2025

Merged via the queue into bevyengine:main with commit fc831c3 Jan 26, 2025
33 checks passed

alice-i-cecile mentioned this pull request Mar 25, 2025

Write release notes for PR #17315: Implement basic clustered decal projectors. bevyengine/bevy-website#1986

Closed

	#ifdef CLUSTERED_DECALS_ARE_USABLE
	#ifdef CLUSTERED_DECALS_ARE_USABLE

Uh oh!

Conversation

pcwalton commented Jan 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Showcase

Uh oh!

github-actions bot commented Jan 11, 2025

Uh oh!

JMS55 left a comment

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!

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!

pcwalton commented Jan 13, 2025

Uh oh!

alice-i-cecile commented Jan 15, 2025

Uh oh!

pcwalton commented Jan 22, 2025

Uh oh!

rparrett left a comment • 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!

Uh oh!

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!

Uh oh!

tychedelia left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

alice-i-cecile commented Jan 26, 2025

Uh oh!

Uh oh!

alice-i-cecile commented Mar 25, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

pcwalton commented Jan 11, 2025 •

edited

Loading

rparrett left a comment •

edited

Loading