[Merged by Bors] - Better cascades config defaults + builder, tweak example configs

[danchia]

Objective

• Improve ergonomics / documentation of cascaded shadow maps
• Allow for the customization of the nearest shadowing distance.
• Fixes Many Foxes shadows vibrate #7393
• Fixes Document how to configure cascaded shadow maps in different situations #7362

Solution

• Introduce CascadeShadowConfigBuilder
• Tweak various example cascade settings for better quality.

---

Changelog

• Made examples look nicer under cascaded shadow maps.
• Introduce CascadeShadowConfigBuilder to help with creating CascadeShadowConfig

Migration Guide

• Configure settings for cascaded shadow maps for directional lights using the newly introduced CascadeShadowConfigBuilder.

[rparrett]

The builder seems to be missing an overlap_proportion method.

[rparrett]

Updated my little playground for this PR here: https://gist.github.com/rparrett/7f028c5893df13920ab792b398e65787

[rparrett]

I am also debugging by logging the resulting texel size of each cascade, and this isn't producing the result I would expect when adjusting minimum_distance.

• only the first cascade's texel size changes
• the texel size increases rather than decreases?
• shadows do not visually change.

(note) in the playground only the third and fourth cascades are actually visible

[alice-i-cecile]

Adding to the milestone optimistically. I'd like to ship better UX / defaults if we can.

[danchia]

Thank you for trying it out!

I am also debugging by logging the resulting texel size of each cascade, and this isn't producing the result I would expect when adjusting minimum_distance.

• only the first cascade's texel size changes

This is expected, as the first cascade is defined by minimum_distance)...first_cascade_far_bound and the rest of the cascades
are spaced exponentially from first_cascade_far_bound..maximum_distance

• the texel size increases rather than decreases?

This is not really expected. Just to confirm, could you point me to what you're calculating as the texel size?

• shadows do not visually change.

(note) in the playground only the third and fourth cascades are actually visible

Similarly, this is expected since only the third and fourth cascades are visible, and minimum_distance is only affecting the first. Adjusting first_cascade_far_bound does affect shadow visual quality in your example

[danchia]

@rparrett I just noticed the lack of validation of minimum_distance, which I have added. You'll need to adjust your playground to avoid exceeding first_cascade_far_bound when adjusting minimum_distance to avoid assertion failure

[rparrett]

This is not really expected. Just to confirm, could you point me to what you're calculating as the texel size?

I am just tracing texel_size on Cascade in update_directional_light_cascades, and I am generally seeing smaller texel sizes and higher quality shadows when adjusting maximum_distance, but not minimum_distance.

This is expected, as the first cascade is defined by minimum_distance)...first_cascade_far_bound and the rest of the cascades
are spaced exponentially from first_cascade_far_bound..maximum_distance

I see... so in order to reduce the total shadow volume from the near side, I need to be adjusting both minimum_distance and first_cascade_far_bound?

That does seem to be working much better.

[rparrett]

Thank you for trying it out!

Hopefully my bumbling around is at least providing some sort of insight into the user experience.

I thought that first_cascade_far_bound would be relative to minimum_distance.

[danchia]

Hopefully my bumbling around is at least providing some sort of insight into the user experience.

It is invaluable and I will be updating doc comments in response to them!

I thought that first_cascade_far_bound would be relative to minimum_distance.

Ah, I will add more comments to make this clear!

This is not really expected. Just to confirm, could you point me to what you're calculating as the texel size?

This is a bit in the weeds of how cascade shadow maps are implemented, but the shadow map covers an area that's more than what's strictly necessary for the sub-frustum defined by the cascade bounds. It actually covers a sphere in which the sub-frustum can freely rotate. The reason for this is shadow stability - we don't want the texel size to be changing as we look around as it would cause shadows to flicker.
http://the-witness.net/news/2010/03/graphics-tech-shadow-maps-part-1/ explains it well.

This does mean that if the(minimum distance to first cascade bound) of the view frustum was not driving the area covered by the shadow map (but rather it's width at first cascade bound for example), you would find that there's no change from moving minimum distance further out.

[superdump]

Mostly good to go from looking through the code. But I'll have a play with it to see how it works. Probably in shadow_biases and scene_viewer.

[superdump]

I did a bit of hacking to add some debug visualisation and then took a look at many_foxes. On this PR:

And then I tweaked the minimum distance, first cascade far bound, and maximum_distance:

EDIT: I noticed that currently on this PR, the foxes in the distance don't have shadows, I think. They're beyond the last cascade. And because the minimum distance wasn't adjusted, the first cascade was covering a lot of unused space.

[danchia]

I did a bit of hacking to add some debug visualisation and then took a look at many_foxes. On this PR: And then I tweaked the minimum distance, first cascade far bound, and maximum_distance:

EDIT: I noticed that currently on this PR, the foxes in the distance don't have shadows, I think. They're beyond the last cascade. And because the minimum distance wasn't adjusted, the first cascade was covering a lot of unused space.

Oops, I thought I checked in Renderdoc, but probably made a mistake. The debug viz is really useful, I wonder if we should try and ship some form of it for end-users in future?

[superdump]

Here it is: 0001-bevy_pbr-Add-cascade-debug-visualization.patch You can just git am <path to patch> on top of your branch if you like and include it in this PR. danchia#1 We have clustered forward rendering cluster debug stuff like this.

[superdump]

The debug visualisation shades the fragment based on the cascade index, which identifies the cascade shadow map that will be sampled. I guess looking in RenderDoc you would see the shadow map textures and see what they cover and you were tweaking based on that?

[superdump]

Oh... that made me think "but I guess depending on the angle of the light, the cascades are going to cover a lot larger area than the view frustum slice" and then I thought that perhaps we should cull meshes against the view frustum slices (accounting for the overlap proportion) rather than the shadow map frusta... The shadow map frusta are >= the view frustum slice (accounting for the overlap iirc) but we will only sample from within the view frustum slice so there's no point rendering meshes outside that region.

[rparrett]

With one cascade I am seeing a pretty interesting (to me) distribution of shadows. This behavior is dependent on light directon.

I'm guessing that this is not unexpected, but sharing just in case.

[danchia]

[danchia]

Oh... that made me think "but I guess depending on the angle of the light, the cascades are going to cover a lot larger area than the view frustum slice" and then I thought that perhaps we should cull meshes against the view frustum slices (accounting for the overlap proportion) rather than the shadow map frusta... The shadow map frusta are >= the view frustum slice (accounting for the overlap iirc) but we will only sample from within the view frustum slice so there's no point rendering meshes outside that region.

Oh yes I was indeed looking at the shadow map! Indeed our culling is probably overly conservative right now. We could indeed consider culling against (part of) view frusta, but it's more subtle that it sounds - we need any shadow casters that are between the view frusta and the "infinitely far away directional light plane"

I will retweak the examples with your patch.

[superdump]

It seems like the default DirectionalLightShadowMap size was initially reduced to 1024 prior to webgl builds being limited to 1 cascade.

Should that be put back to 2048? Even with the tweaked bounds, shadows in wasm builds are noticeably worse (looking specifically at the lighting example)

Your suggestion makes sense, as long as webgl can only have one cascade.

[superdump]

I think while the debug visualisation of which cascade is sampled for a given fragment is useful, we also need to be able to draw the cascade frusta so we can see the impact of adjusting the minimum distance. I was hacking on this when I was going to try to finish off CSM myself but @danchia figured out the problems without it. :)

[superdump]

Depends on the FOV I suppose. A narrower FOV would make the view frustum body diagonal relatively larger compared to the far plane face diagonal. A wider FOV would shift their relationship in the other direction. Not sure how we can communicate this in a simple and easy way.

[superdump]

Testing locally again to take a look at how the examples look to see if more tweaking is needed:

• atmospheric_fog has quite a bit of aliasing in the foreground shadows.
• CSM shadows don't seem to be working on load_gltf - there should be shadows cast by the helmet and stand on the base.
• CSM shadows have aliasing in shadow_caster_receiver

The rest look good to me. :)

[superdump]

Could the aliasing in atmospheric_fog be just a particularly challenging case for projective aliasing where a shadow map texel covers the depth difference of the foreground slope into shadow on the left to the crest of the hill casting that shadow? The cascade distribution looks fine to me.

[superdump]

load_gltf maximum distance needs to be at least 1.6 I think. At that point adjusting the minimum distance makes no difference.

Another interesting aspect of this is that the view frustum is impacted by the window size. So reducing the width of the window by resizing it does indeed seem to reduce the aliasing seen under the goggles as the light moves around behind the helmet.

[superdump]

So, for clarity, I think for this PR we can adjust the load_gltf maximum distance to 1.6, and as webgl can only have one cascade for now, change the resolution back to what it was before the CSM PR, and then we can get this merged. It's not clear to me what more can be done to improve things and I'm happy to take a step now and then if we have more ideas we can always make new PRs.

[danchia]

so in the latest four commits, I have

1. adjusted webgl shadowmap size to default. (good catch @rparrett! I must have changed it before realizing webgl only had 1 cascade later only).
2. tweaked load_gltf as suggested with only max_dist 1.6, and I also bumped the shadowmap res since we're only using 1 cascade.
3. I tried to clarify the language around minimum_distance more. Please LMK if it can be made better.

[robtfm]

looks far better on all the examples. a couple of nit-picky points (depending what others think) but i'll approve as-is.

[robtfm]

i think webgl and non-webgl should have the same default settings (apart from num cascades). then things will work the same (but look worse) on webgl by default.

[superdump]

Hmm... not sure I agree on that. Having a 1km (assuming world units are metres) single-cascade will look horribly bad. I think it's better to reduce the shadow max distance instead and just not have shadows further away. If people want to, they can change it.

[danchia]

This was my intention behind the differing defaults - I felt with only 1 cascade it would be a better tradeoff to just have a shorter shadow distance.

[superdump]

robtfm's comments + these, then we can merge. :)

[superdump]

bors r+

[bors]

Pull request successfully merged into main.

Build succeeded:

• build-and-install-on-iOS
• build-android
• build (macos-latest)
• build (ubuntu-latest)
• build-wasm
• build (windows-latest)
• build-without-default-features (bevy)
• build-without-default-features (bevy_ecs)
• build-without-default-features (bevy_reflect)
• check-compiles
• check-doc
• check-missing-examples-in-docs
• ci
• markdownlint
• msrv
• run-examples
• run-examples-on-wasm
• run-examples-on-windows-dx12