Skip to content

Release notes for decals #2085

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 8 commits into from
Closed

Release notes for decals #2085

Show file tree
Hide file tree
Changes from 6 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
575e519
Unify decals work into a single note
alice-i-cecile Apr 7, 2025
447600f
Basic structure
alice-i-cecile Apr 7, 2025
237859a
Thanks to Nise and Griffin too!
alice-i-cecile Apr 8, 2025
c76b59b
Explain how to use them
alice-i-cecile Apr 8, 2025
ec885a1
Call out bindless textures
alice-i-cecile Apr 8, 2025
c12ce40
Explain how clustered decals work
alice-i-cecile Apr 8, 2025
b7571c4
We hate objects
alice-i-cecile Apr 8, 2025
b7baa10
Typo
alice-i-cecile Apr 8, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 0 additions & 4 deletions ...16/release-notes/16600_Forward_decals_port_of_bevy_contact_projective_decals.md
View file
Open in desktop

This file was deleted.

4 changes: 0 additions & 4 deletions ...-content/0.16/release-notes/17315_Implement_basic_clustered_decal_projectors.md
View file
Open in desktop

This file was deleted.

10 changes: 5 additions & 5 deletions release-content/0.16/release-notes/_release-notes.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -86,11 +86,11 @@ prs = [17096]
file_name = "17096_Anamorphic_Bloom.md"

[[release_notes]]
title = "Forward decals (port of bevy_contact_projective_decals)"
authors = ["@JMS55"]
contributors = ["@IceSentry"]
prs = [16600]
file_name = "16600_Forward_decals_port_of_bevy_contact_projective_decals.md"
title = "Decals"
authors = ["@naasblod", "@JMS55", "@pcwalton"]
contributors = ["@IceSentry", "@NiseVoid", "@DGriffin91"]
prs = [16600, 17315]
file_name = "decals.md"

[[release_notes]]
title = "Procedural atmospheric scattering"
Expand Down
29 changes: 29 additions & 0 deletions release-content/0.16/release-notes/decals.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
**Decals** are textures which can be dynamically layered on top of existing meshes, conforming to their geometry.
This has two benefits over simply changing a mesh's texture:

1. You can add them dynamically in response to player actions. Most famously, bullet holes in FPS games use decals for this.
2. You don't need to create an entirely new texture for every combination, which makes them more efficient and flexible when creating levels with details like graffiti or cracks in building facades.

Like many things in rendering, there are a huge number of ways to implement this feature, each with their own tradeoffs.
In Bevy 0.16, we've selected two complementary approaches: **forward decals** and **clustered decals**.

TODO: add decal image.

Our implementation of forward decals (or to be more precise, contrast projective decals) was inspired by [Alexander Sannikovs talk on the rendering techniques of Path of Exile 2], and was upstreamed from the [`bevy_contact_projective_decals`] ecosystem crate.
Due to nature of this technique, looking at the decal from very steep angles will cause distortion.
This can be mitigated by creating textures that are bigger than the effect, giving the decal more space to stretch.
To create a forward decal, spawn a [`ForwardDecal`] object, which uses a [`ForwardDecalMaterial`] using the [`ForwardDecalMaterialExt`] material extension.

Clustered decals (or decal projectors) work by projecting images from a 1x1x1 cube onto surfaces found in the +Z direction.
Copy link
Contributor

@superdump superdump Apr 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is the +z direction part correct?

I’m not certain how this feature works so don’t rely on my feedback without verifying. I was thinking that this is like a 2D image on the right-handed x-right, y-up, z-back cube’s z faces being projected through the cube along its z-axis and covering any surfaces along the path. I have a feeling that I also saw it project onto both front and back faces from the cube’s perspective. Here a picture would surely be a thousand words. :)

Copy link
Member Author

@alice-i-cecile alice-i-cecile Apr 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That was taken from the existing docs :)

Copy link
Contributor

@JMS55 JMS55 Apr 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Feels like too much pointless technical info. Even I don't really care about cubes or +z direction.

They are clusterable objects, just like point lights and light probes, which means that decals are only evaluated for objects within the bounds of the projector, and they don't require a second rendering pass.
Copy link
Contributor

@JMS55 JMS55 Apr 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

and they don't require a second rendering pass.

Kind of implies that forward decals do require a second rendering pass, which sorta isn't true.

Small summary of how they work:

  1. Forward decals basically map to mesh + material under the hood, I just did some fancy API stuff to make it ergonomic for users to spawn. It's literately just an extra alpha-blended mesh that gets rendered in the transparent phase.
  2. Clustered decals get binned into froxels(iirc?), and then during the opaque pass each fragments lookup what froxel they're in, and then iterate over the decals in the froxel and apply them. Same as how points/spot lights work, and I guess light probes although I forgot about that bit.

Copy link
Contributor

@superdump superdump Apr 11, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So forward decals results in the same fragment being shaded twice? In which case:

Suggested change
They are clusterable objects, just like point lights and light probes, which means that decals are only evaluated for objects within the bounds of the projector, and they don't require a second rendering pass.
They are clusterable objects, just like point lights and light probes, which means that decals are only evaluated for objects within the bounds of the projector, and they don't require shading the same fragment an additional time to blend the decal on top.

To create a clustered decal, spawn a [`ClusteredDecal`] entity.

Ultimately, forward decals offer broader hardware and driver support, while clustered decals are higher quality and don't require the creation of bounding geometry, improving performance.
Copy link
Contributor

@JMS55 JMS55 Apr 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think forward decals are also a little easier to customize, since it's 99% just using the material API. Clustered decals can be customized, but are a little harder.

There might also be other quality differences and situations where one or the other is better, but idk enough about decals to say.

Copy link
Contributor

@JMS55 JMS55 Apr 11, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh yeah forward decals are basically transparent objects, so they won't work as well with TAA and such.

Currently, WebGL2, WebGPU, iOS and Mac only support forward decals, as clustered decals require bindless textures.

[Alexander Sannikovs talk on the rendering techniques of Path of Exile 2]: https://www.youtube.com/watch?v=TrHHTQqmAaM
[`bevy_contact_projective_decals`]: https://github.com/naasblod/bevy_contact_projective_decals
[`ForwardDecal`]: https://dev-docs.bevyengine.org/bevy/pbr/decal/struct.ForwardDecal.html
[`ForwardDecalMaterial`]: https://dev-docs.bevyengine.org/bevy/pbr/decal/type.ForwardDecalMaterial.html
[`ForwardDecalMaterialExt`]: https://dev-docs.bevyengine.org/bevy/pbr/decal/struct.ForwardDecalMaterialExt.html
[`ClusteredDecal`]: https://dev-docs.bevyengine.org/bevy/pbr/decal/clustered/struct.ClusteredDecal.html