Forward decals (port of bevy_contact_projective_decals) #16600

JMS55 · 2024-12-02T04:58:45Z

Objective

Implement ForwardDecal as outlined in Custom projection / decal support #2401

Solution

Port https://github.com/naasblod/bevy_contact_projective_decals, and cleanup the API a little.

Testing

Ran the new decal example.

Showcase

Changelog

Added ForwardDecal and associated types
Added MaterialExtension::alpha_mode()

…decal2

JMS55 · 2025-01-11T18:45:20Z

crates/bevy_pbr/src/decal/forward.rs

+    ///
+    /// Decreasing this value will cause the decal to blend only to surfaces closer to it.
+    ///
+    /// Units are in meters.


Units are in meters.

I think?

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.

pcwalton

I got:

2025-01-12T01:11:09.471156Z ERROR bevy_render::render_resource::pipeline_cache: failed to process shader:
error: failed to build a valid final module: Function [74] 'bevy_pbr::decal::forward::get_forward_decal_info' is invalid
   ┌─ crates\bevy_pbr\src\decal\forward_decal.wgsl:22:1
   │
22 │ ╭   fn get_forward_decal_info(in: bevy_pbr::forward_io::VertexOutput) -> ForwardDecalInformation {
23 │ │       let world_from_local = bevy_pbr::mesh_functions::get_world_from_local(in.instance_index);
24 │ │       let scale = (world_from_local * vec4(1.0, 1.0, 1.0, 0.0)).xyz;
25 │ │       let scaled_tangent = vec4(in.world_tangent.xyz / scale, in.world_tangent.w);
   · │
44 │ │       let uv = bevy_pbr::parallax_mapping::parallaxed_uv(
   │ │ ╭──────────────^
45 │ │ │         normal_depth,
46 │ │ │         1.0,
47 │ │ │         0u,
48 │ │ │         in.uv,
49 │ │ │         Vt,
   │ │ ╰──────────^ invalid function call
   · │ │
54 │ │
55 │ │       return ForwardDecalInformation(world_position, uv, alpha);
   │ ╰────────────────────────────────────────────────────────────────^ naga::Function [74]
   │
   = Call to [72] is invalid
   = Requires 6 arguments, but 5 are provided

pcwalton · 2025-01-12T00:56:12Z

Cargo.toml

 wasm = true

+[[example]]
+name = "decal"


I think perhaps we should either rename this to forward_decal, or else add support for toggling between forward decals and decal projectors from #17315 to this example..

crates/bevy_pbr/src/decal/forward_decal.wgsl

pcwalton · 2025-01-12T01:00:45Z

crates/bevy_pbr/src/extended_material.rs


-    fn alpha_mode(&self) -> crate::AlphaMode {
-        B::alpha_mode(&self.base)
+    fn alpha_mode(&self) -> AlphaMode {


This is technically a breaking change and should be documented as such.

It's not a breaking change, because E::alpha_mode() did not exist until now.

JMS55 · 2025-01-12T21:47:23Z

Updated the PR, but I don't know why bevy_contact_projective_decals is calling parallaxed_uv() which samples the material's depth map, which for custom materials won't exist, and for standard material will probably be a placeholder.

examples/3d/decal.rs

IceSentry · 2025-01-14T02:26:06Z

examples/3d/decal.rs

+                base_color_texture: Some(asset_server.load("textures/uv_checker_bw.png")),
+                ..default()
+            },
+            extension: ForwardDecalMaterialExt {


Suggested change

extension: ForwardDecalMaterialExt {

// The decal material is implemented as an extended material

// The default implementation extends the StandardMaterial so decals are rendered using PBR

extension: ForwardDecalMaterialExt {

Ehh don't think this is quite accurate. I left some pretty detailed docs on the decal extension stuff, I'd rather people read that.

It's more like you can use ~any material, but you need to wrap it in the extension for CPU-side stuff, and also make some changes in the shader that StandardMaterial already has setup.

examples/3d/decal.rs

IceSentry · 2025-01-14T02:27:24Z

I suggested a few comments for the example. They don't need to be used verbatim, but a few comments like those would be nice.

IceSentry · 2025-01-14T04:06:16Z

Not sure if it's related to this PR, but a few examples are broken when running this PR https://pixel-eagle.com/project/B25A040A-A980-4602-B90C-D480AB84076D?filter=PR-16600

JMS55 · 2025-01-14T04:13:25Z

I doubt it's related, probably just non-deterministic examples.

Co-authored-by: IceSentry <IceSentry@users.noreply.github.com>

…orward_decal2

…decal2

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: 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 #2401. ## Showcase ![Screenshot 2025-01-11 052913](https://github.com/user-attachments/assets/8fabbafc-60fb-461d-b715-d7977e10fe1f)

…6600) # Objective - Implement ForwardDecal as outlined in bevyengine#2401 ## Solution - Port https://github.com/naasblod/bevy_contact_projective_decals, and cleanup the API a little. ## Testing - Ran the new decal example. --- ## Showcase ![image](https://github.com/user-attachments/assets/72134af0-724f-4df9-a11f-b0888819a791) ## Changelog * Added ForwardDecal and associated types * Added MaterialExtension::alpha_mode() --------- Co-authored-by: IceSentry <IceSentry@users.noreply.github.com>

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:07:46Z

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#1980 if you'd like to help out.

JMS55 added 5 commits December 1, 2024 20:58

WIP forward decals

c2d10be

Add MaterialExtension::alpha_mode()

84b1d91

More WIP

64f953f

Register standard material decal extension

1890284

Register ForwardDecal

735086f

JMS55 added 9 commits December 2, 2024 20:00

Misc cleanup

8e28b50

Setup example file

babab6e

Misc refactor

fc45247

Fixes

369dd07

WIP example

038b6e2

Docs

8185d22

WIP example

463f78d

Wording tweak

5e1062d

Merge commit '5c0e13f29bc6b028a81dcf46f9a234ab53b70d3f' into forward_…

689cf05

…decal2

JMS55 requested a review from pcwalton January 11, 2025 18:32

JMS55 added 3 commits January 11, 2025 10:36

Fix formatting

b410615

Fixes

b9a6b3d

Tweak doc wording

86a39e0

JMS55 commented Jan 11, 2025

View reviewed changes

pcwalton mentioned this pull request Jan 11, 2025

Implement basic clustered decal projectors. #17315

Merged

pcwalton suggested changes Jan 12, 2025

View reviewed changes

Fix rebase

3c7cadf

JMS55 mentioned this pull request Jan 12, 2025

update to 0.15 naasblod/bevy_contact_projective_decals#12

Merged

Fix, kinda

190d3d5

JMS55 marked this pull request as ready for review January 13, 2025 01:06

JMS55 requested a review from pcwalton January 13, 2025 01:06

pcwalton approved these changes Jan 13, 2025

View reviewed changes

JMS55 requested a review from IceSentry January 13, 2025 06:49

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

16600 bevyengine/bevy-example-runner#84

Closed

IceSentry approved these changes Jan 14, 2025

View reviewed changes

IceSentry reviewed Jan 14, 2025

View reviewed changes

examples/3d/decal.rs Show resolved Hide resolved

IceSentry reviewed Jan 14, 2025

View reviewed changes

examples/3d/decal.rs Show resolved Hide resolved

IceSentry reviewed Jan 14, 2025

View reviewed changes

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

JMS55 and others added 6 commits January 14, 2025 17:37

Update examples/3d/decal.rs

c67c633

Co-authored-by: IceSentry <IceSentry@users.noreply.github.com>

Update examples/3d/decal.rs

0067efd

Co-authored-by: IceSentry <IceSentry@users.noreply.github.com>

Remove envmap

e0109ae

Merge branch 'forward_decal2' of https://github.com/JMS55/bevy into f…

871b061

…orward_decal2

Fmt

88124af

Merge commit '26bb0b40d26ee93a8938986ed68a58a897a0e166' into forward_…

124fa59

…decal2

JMS55 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-Waiting-on-Author The author needs to make changes or address concerns before this can be merged labels Jan 15, 2025

JMS55 requested a review from alice-i-cecile January 15, 2025 01:41

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

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

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

Write release notes for PR #16600: Forward decals (port of bevy_contact_projective_decals) bevyengine/bevy-website#1980

Closed

Uh oh!

Forward decals (port of bevy_contact_projective_decals) #16600

Forward decals (port of bevy_contact_projective_decals) #16600

Uh oh!

Conversation

JMS55 commented Dec 2, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Objective

Solution

Testing

Showcase

Changelog

Uh oh!

JMS55 Jan 11, 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!

pcwalton left a comment

Choose a reason for hiding this comment

Uh oh!

pcwalton Jan 12, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

pcwalton Jan 12, 2025

Choose a reason for hiding this comment

Uh oh!

JMS55 Jan 12, 2025

Choose a reason for hiding this comment

Uh oh!

JMS55 commented Jan 12, 2025

Uh oh!

Uh oh!

Uh oh!

IceSentry Jan 14, 2025

Choose a reason for hiding this comment

Uh oh!

JMS55 Jan 15, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

IceSentry commented Jan 14, 2025

Uh oh!

IceSentry commented Jan 14, 2025

Uh oh!

JMS55 commented Jan 14, 2025

Uh oh!

Uh oh!

alice-i-cecile commented Mar 25, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

JMS55 commented Dec 2, 2024 •

edited

Loading

JMS55 Jan 11, 2025 •

edited

Loading