Skip to content

Commit e6fbcb7

Browse files
cartmockersf
cart
authored and
mockersf
committed
Make PCSS experimental (#16382)
# Objective PCSS still has some fundamental issues (#16155). We should resolve them before "releasing" the feature. ## Solution 1. Rename the already-optional `pbr_pcss` cargo feature to `experimental_pbr_pcss` to better communicate its state to developers. 2. Adjust the description of the `experimental_pbr_pcss` cargo feature to better communicate its state to developers. 3. Gate PCSS-related light component fields behind that cargo feature, to prevent surfacing them to developers by default.
1 parent 988770a commit e6fbcb7

File tree

10 files changed

+41
-26
lines changed

10 files changed

+41
-26
lines changed

‎Cargo.toml

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -403,7 +403,7 @@ pbr_multi_layer_material_textures = [
403403
pbr_anisotropy_texture = ["bevy_internal/pbr_anisotropy_texture"]
404404

405405
# Enable support for PCSS, at the risk of blowing past the global, per-shader sampler limit on older/lower-end GPUs
406-
pbr_pcss = ["bevy_internal/pbr_pcss"]
406+
experimental_pbr_pcss = ["bevy_internal/experimental_pbr_pcss"]
407407

408408
# Enable some limitations to be able to use WebGL2. Please refer to the [WebGL2 and WebGPU](https://github.com/bevyengine/bevy/tree/latest/examples#webgl2-and-webgpu) section of the examples README for more information on how to run Wasm builds with WebGPU.
409409
webgl2 = ["bevy_internal/webgl"]
@@ -3790,7 +3790,7 @@ wasm = true
37903790
name = "pcss"
37913791
path = "examples/3d/pcss.rs"
37923792
doc-scrape-examples = true
3793-
required-features = ["pbr_pcss"]
3793+
required-features = ["experimental_pbr_pcss"]
37943794

37953795
[package.metadata.example.pcss]
37963796
name = "Percentage-closer soft shadows"

‎crates/bevy_internal/Cargo.toml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -135,7 +135,7 @@ pbr_anisotropy_texture = [
135135
]
136136

137137
# Percentage-closer soft shadows
138-
pbr_pcss = ["bevy_pbr?/pbr_pcss"]
138+
experimental_pbr_pcss = ["bevy_pbr?/experimental_pbr_pcss"]
139139

140140
# Optimise for WebGL2
141141
webgl = [

‎crates/bevy_pbr/Cargo.toml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ webgpu = []
1414
pbr_transmission_textures = []
1515
pbr_multi_layer_material_textures = []
1616
pbr_anisotropy_texture = []
17-
pbr_pcss = []
17+
experimental_pbr_pcss = []
1818
shader_format_glsl = ["bevy_render/shader_format_glsl"]
1919
trace = ["bevy_render/trace"]
2020
ios_simulator = ["bevy_render/ios_simulator"]

‎crates/bevy_pbr/src/light/directional_light.rs

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -95,6 +95,7 @@ pub struct DirectionalLight {
9595
///
9696
/// Note that soft shadows are significantly more expensive to render than
9797
/// hard shadows.
98+
#[cfg(feature = "experimental_pbr_pcss")]
9899
pub soft_shadow_size: Option<f32>,
99100

100101
/// A value that adjusts the tradeoff between self-shadowing artifacts and
@@ -120,9 +121,10 @@ impl Default for DirectionalLight {
120121
color: Color::WHITE,
121122
illuminance: light_consts::lux::AMBIENT_DAYLIGHT,
122123
shadows_enabled: false,
123-
soft_shadow_size: None,
124124
shadow_depth_bias: Self::DEFAULT_SHADOW_DEPTH_BIAS,
125125
shadow_normal_bias: Self::DEFAULT_SHADOW_NORMAL_BIAS,
126+
#[cfg(feature = "experimental_pbr_pcss")]
127+
soft_shadow_size: None,
126128
}
127129
}
128130
}

‎crates/bevy_pbr/src/light/point_light.rs

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -61,6 +61,7 @@ pub struct PointLight {
6161
///
6262
/// Note that soft shadows are significantly more expensive to render than
6363
/// hard shadows.
64+
#[cfg(feature = "experimental_pbr_pcss")]
6465
pub soft_shadows_enabled: bool,
6566

6667
/// A bias used when sampling shadow maps to avoid "shadow-acne", or false shadow occlusions
@@ -95,10 +96,11 @@ impl Default for PointLight {
9596
range: 20.0,
9697
radius: 0.0,
9798
shadows_enabled: false,
98-
soft_shadows_enabled: false,
9999
shadow_depth_bias: Self::DEFAULT_SHADOW_DEPTH_BIAS,
100100
shadow_normal_bias: Self::DEFAULT_SHADOW_NORMAL_BIAS,
101101
shadow_map_near_z: Self::DEFAULT_SHADOW_MAP_NEAR_Z,
102+
#[cfg(feature = "experimental_pbr_pcss")]
103+
soft_shadows_enabled: false,
102104
}
103105
}
104106
}

‎crates/bevy_pbr/src/light/spot_light.rs

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -57,6 +57,7 @@ pub struct SpotLight {
5757
///
5858
/// Note that soft shadows are significantly more expensive to render than
5959
/// hard shadows.
60+
#[cfg(feature = "experimental_pbr_pcss")]
6061
pub soft_shadows_enabled: bool,
6162

6263
/// A value that adjusts the tradeoff between self-shadowing artifacts and
@@ -115,12 +116,13 @@ impl Default for SpotLight {
115116
range: 20.0,
116117
radius: 0.0,
117118
shadows_enabled: false,
118-
soft_shadows_enabled: false,
119119
shadow_depth_bias: Self::DEFAULT_SHADOW_DEPTH_BIAS,
120120
shadow_normal_bias: Self::DEFAULT_SHADOW_NORMAL_BIAS,
121121
shadow_map_near_z: Self::DEFAULT_SHADOW_MAP_NEAR_Z,
122122
inner_angle: 0.0,
123123
outer_angle: core::f32::consts::FRAC_PI_4,
124+
#[cfg(feature = "experimental_pbr_pcss")]
125+
soft_shadows_enabled: false,
124126
}
125127
}
126128
}

‎crates/bevy_pbr/src/render/light.rs

Lines changed: 22 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -41,12 +41,12 @@ pub struct ExtractedPointLight {
4141
pub radius: f32,
4242
pub transform: GlobalTransform,
4343
pub shadows_enabled: bool,
44-
pub soft_shadows_enabled: bool,
4544
pub shadow_depth_bias: f32,
4645
pub shadow_normal_bias: f32,
4746
pub shadow_map_near_z: f32,
4847
pub spot_light_angles: Option<(f32, f32)>,
4948
pub volumetric: bool,
49+
pub soft_shadows_enabled: bool,
5050
}
5151

5252
#[derive(Component, Debug)]
@@ -56,13 +56,13 @@ pub struct ExtractedDirectionalLight {
5656
pub transform: GlobalTransform,
5757
pub shadows_enabled: bool,
5858
pub volumetric: bool,
59-
pub soft_shadow_size: Option<f32>,
6059
pub shadow_depth_bias: f32,
6160
pub shadow_normal_bias: f32,
6261
pub cascade_shadow_config: CascadeShadowConfig,
6362
pub cascades: EntityHashMap<Vec<Cascade>>,
6463
pub frusta: EntityHashMap<Vec<Frustum>>,
6564
pub render_layers: RenderLayers,
65+
pub soft_shadow_size: Option<f32>,
6666
}
6767

6868
// NOTE: These must match the bit flags in bevy_pbr/src/render/mesh_view_types.wgsl!
@@ -147,10 +147,10 @@ pub const MAX_CASCADES_PER_LIGHT: usize = 1;
147147
#[derive(Resource, Clone)]
148148
pub struct ShadowSamplers {
149149
pub point_light_comparison_sampler: Sampler,
150-
#[cfg(feature = "pbr_pcss")]
150+
#[cfg(feature = "experimental_pbr_pcss")]
151151
pub point_light_linear_sampler: Sampler,
152152
pub directional_light_comparison_sampler: Sampler,
153-
#[cfg(feature = "pbr_pcss")]
153+
#[cfg(feature = "experimental_pbr_pcss")]
154154
pub directional_light_linear_sampler: Sampler,
155155
}
156156

@@ -174,15 +174,15 @@ impl FromWorld for ShadowSamplers {
174174
compare: Some(CompareFunction::GreaterEqual),
175175
..base_sampler_descriptor
176176
}),
177-
#[cfg(feature = "pbr_pcss")]
177+
#[cfg(feature = "experimental_pbr_pcss")]
178178
point_light_linear_sampler: render_device.create_sampler(&base_sampler_descriptor),
179179
directional_light_comparison_sampler: render_device.create_sampler(
180180
&SamplerDescriptor {
181181
compare: Some(CompareFunction::GreaterEqual),
182182
..base_sampler_descriptor
183183
},
184184
),
185-
#[cfg(feature = "pbr_pcss")]
185+
#[cfg(feature = "experimental_pbr_pcss")]
186186
directional_light_linear_sampler: render_device
187187
.create_sampler(&base_sampler_descriptor),
188188
}
@@ -291,7 +291,6 @@ pub fn extract_lights(
291291
radius: point_light.radius,
292292
transform: *transform,
293293
shadows_enabled: point_light.shadows_enabled,
294-
soft_shadows_enabled: point_light.soft_shadows_enabled,
295294
shadow_depth_bias: point_light.shadow_depth_bias,
296295
// The factor of SQRT_2 is for the worst-case diagonal offset
297296
shadow_normal_bias: point_light.shadow_normal_bias
@@ -300,6 +299,10 @@ pub fn extract_lights(
300299
shadow_map_near_z: point_light.shadow_map_near_z,
301300
spot_light_angles: None,
302301
volumetric: volumetric_light.is_some(),
302+
#[cfg(feature = "experimental_pbr_pcss")]
303+
soft_shadows_enabled: point_light.soft_shadows_enabled,
304+
#[cfg(not(feature = "experimental_pbr_pcss"))]
305+
soft_shadows_enabled: false,
303306
};
304307
point_lights_values.push((
305308
render_entity,
@@ -350,7 +353,6 @@ pub fn extract_lights(
350353
radius: spot_light.radius,
351354
transform: *transform,
352355
shadows_enabled: spot_light.shadows_enabled,
353-
soft_shadows_enabled: spot_light.soft_shadows_enabled,
354356
shadow_depth_bias: spot_light.shadow_depth_bias,
355357
// The factor of SQRT_2 is for the worst-case diagonal offset
356358
shadow_normal_bias: spot_light.shadow_normal_bias
@@ -359,6 +361,10 @@ pub fn extract_lights(
359361
shadow_map_near_z: spot_light.shadow_map_near_z,
360362
spot_light_angles: Some((spot_light.inner_angle, spot_light.outer_angle)),
361363
volumetric: volumetric_light.is_some(),
364+
#[cfg(feature = "experimental_pbr_pcss")]
365+
soft_shadows_enabled: spot_light.soft_shadows_enabled,
366+
#[cfg(not(feature = "experimental_pbr_pcss"))]
367+
soft_shadows_enabled: false,
362368
},
363369
render_visible_entities,
364370
*frustum,
@@ -430,7 +436,10 @@ pub fn extract_lights(
430436
illuminance: directional_light.illuminance,
431437
transform: *transform,
432438
volumetric: volumetric_light.is_some(),
439+
#[cfg(feature = "experimental_pbr_pcss")]
433440
soft_shadow_size: directional_light.soft_shadow_size,
441+
#[cfg(not(feature = "experimental_pbr_pcss"))]
442+
soft_shadow_size: None,
434443
shadows_enabled: directional_light.shadows_enabled,
435444
shadow_depth_bias: directional_light.shadow_depth_bias,
436445
// The factor of SQRT_2 is for the worst-case diagonal offset
@@ -911,17 +920,17 @@ pub fn prepare_lights(
911920
.extend(1.0 / (light.range * light.range)),
912921
position_radius: light.transform.translation().extend(light.radius),
913922
flags: flags.bits(),
914-
soft_shadow_size: if light.soft_shadows_enabled {
915-
light.radius
916-
} else {
917-
0.0
918-
},
919923
shadow_depth_bias: light.shadow_depth_bias,
920924
shadow_normal_bias: light.shadow_normal_bias,
921925
shadow_map_near_z: light.shadow_map_near_z,
922926
spot_light_tan_angle,
923927
pad_a: 0.0,
924928
pad_b: 0.0,
929+
soft_shadow_size: if light.soft_shadows_enabled {
930+
light.radius
931+
} else {
932+
0.0
933+
},
925934
});
926935
global_light_meta.entity_to_index.insert(entity, index);
927936
}

‎crates/bevy_pbr/src/render/mesh.rs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1859,7 +1859,7 @@ impl SpecializedMeshPipeline for MeshPipeline {
18591859
#[cfg(all(feature = "webgl", target_arch = "wasm32", not(feature = "webgpu")))]
18601860
shader_defs.push("WEBGL2".into());
18611861

1862-
#[cfg(feature = "pbr_pcss")]
1862+
#[cfg(feature = "experimental_pbr_pcss")]
18631863
shader_defs.push("PCSS_SAMPLERS_AVAILABLE".into());
18641864

18651865
if key.contains(MeshPipelineKey::TONEMAP_IN_SHADER) {

‎crates/bevy_pbr/src/render/mesh_view_bindings.rs

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -228,7 +228,7 @@ fn layout_entries(
228228
// Point Shadow Texture Array Comparison Sampler
229229
(3, sampler(SamplerBindingType::Comparison)),
230230
// Point Shadow Texture Array Linear Sampler
231-
#[cfg(feature = "pbr_pcss")]
231+
#[cfg(feature = "experimental_pbr_pcss")]
232232
(4, sampler(SamplerBindingType::Filtering)),
233233
// Directional Shadow Texture Array
234234
(
@@ -245,7 +245,7 @@ fn layout_entries(
245245
// Directional Shadow Texture Array Comparison Sampler
246246
(6, sampler(SamplerBindingType::Comparison)),
247247
// Directional Shadow Texture Array Linear Sampler
248-
#[cfg(feature = "pbr_pcss")]
248+
#[cfg(feature = "experimental_pbr_pcss")]
249249
(7, sampler(SamplerBindingType::Filtering)),
250250
// PointLights
251251
(
@@ -580,11 +580,11 @@ pub fn prepare_mesh_view_bind_groups(
580580
(1, light_binding.clone()),
581581
(2, &shadow_bindings.point_light_depth_texture_view),
582582
(3, &shadow_samplers.point_light_comparison_sampler),
583-
#[cfg(feature = "pbr_pcss")]
583+
#[cfg(feature = "experimental_pbr_pcss")]
584584
(4, &shadow_samplers.point_light_linear_sampler),
585585
(5, &shadow_bindings.directional_light_depth_texture_view),
586586
(6, &shadow_samplers.directional_light_comparison_sampler),
587-
#[cfg(feature = "pbr_pcss")]
587+
#[cfg(feature = "experimental_pbr_pcss")]
588588
(7, &shadow_samplers.directional_light_linear_sampler),
589589
(8, clusterable_objects_binding.clone()),
590590
(

‎docs/cargo_features.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -67,6 +67,7 @@ The default feature set enables most of the expected features of a game engine,
6767
|detailed_trace|Enable detailed trace event logging. These trace events are expensive even when off, thus they require compile time opt-in|
6868
|dynamic_linking|Force dynamic linking, which improves iterative compile times|
6969
|embedded_watcher|Enables watching in memory asset providers for Bevy Asset hot-reloading|
70+
|experimental_pbr_pcss|Enable support for PCSS, at the risk of blowing past the global, per-shader sampler limit on older/lower-end GPUs|
7071
|exr|EXR image format support|
7172
|ff|Farbfeld image format support|
7273
|file_watcher|Enables watching the filesystem for Bevy Asset hot-reloading|
@@ -83,7 +84,6 @@ The default feature set enables most of the expected features of a game engine,
8384
|mp3|MP3 audio format support|
8485
|pbr_anisotropy_texture|Enable support for anisotropy texture in the `StandardMaterial`, at the risk of blowing past the global, per-shader texture limit on older/lower-end GPUs|
8586
|pbr_multi_layer_material_textures|Enable support for multi-layer material textures in the `StandardMaterial`, at the risk of blowing past the global, per-shader texture limit on older/lower-end GPUs|
86-
|pbr_pcss|Enable support for PCSS, at the risk of blowing past the global, per-shader sampler limit on older/lower-end GPUs|
8787
|pbr_transmission_textures|Enable support for transmission-related textures in the `StandardMaterial`, at the risk of blowing past the global, per-shader texture limit on older/lower-end GPUs|
8888
|pnm|PNM image format support, includes pam, pbm, pgm and ppm|
8989
|qoi|QOI image format support|

0 commit comments

Comments
 (0)