Make Skybox’s image optional so that Skybox::default() is valid. (#23691)

# Objective

- Partially addresses #23688.
- Prevents use of `Skybox::default()` from causing errors.

## Solution

`Skybox::default()` is problematic because it contains an `Image` that
is not a valid skybox. ~~This change removes the `Default`
implementation and instead provides a `new()` function which takes the
image as a parameter (and also the brightness, which is practically
required).~~ This change makes the `image` field optional so that the
default `None` renders nothing.

Things we could do instead of this:
* Make `Skybox` not implement `Default`. I am informed this is a bad
idea.
* Create a default cubemap image for `default()` to use.

## Testing

Ran the `skybox` and `irradiance_volumes` examples.

Author: kpreid

_release-content/migration-guides/skybox_image.md

@@ -0,0 +1,42 @@
+---
+title: "`Skybox` `image` is now optional"
+pull_requests: [23691]
+---
+
+The `image` field of the `Skybox` component now has the type `Option<Handle<Image>>` instead of `Handle<Image>`.
+A `Skybox` component without an image will not draw anything, just like it was not present.
+
+If you were creating a skybox with an image, wrap the image handle in `Some`:
+
+```rust
+// 0.18
+Skybox {
+    image: my_skybox,
+    brightness: 1000.0,
+    ..default()
+}
+
+// 0.19
+Skybox {
+    image: Some(my_skybox),
+    brightness: 1000.0,
+    ..default()
+}
+```
+
+If you were previously creating a `Skybox` component with a placeholder image to be changed later, you can now remove the placeholder:
+
+```rust
+// 0.18
+Skybox {
+    image: cubemap_image_that_will_not_actually_be_seen,
+    brightness: 1000.0,
+    ..default()
+}
+
+// 0.19
+Skybox {
+    brightness: 1000.0,
+    ..default()
+}
+```

crates/bevy_core_pipeline/src/skybox/mod.rs

@@ -227,17 +227,18 @@ fn prepare_skybox_bind_groups(
     views: Query<(Entity, &Skybox, &DynamicUniformIndex<SkyboxUniforms>)>,
 ) {
     for (entity, skybox, skybox_uniform_index) in &views {
-        if let (Some(skybox), Some(view_uniforms), Some(skybox_uniforms)) = (
-            images.get(&skybox.image),
+        if let (Some(image_handle), Some(view_uniforms), Some(skybox_uniforms)) = (
+            &skybox.image,
             view_uniforms.uniforms.binding(),
             skybox_uniforms.binding(),
-        ) {
+        ) && let Some(image) = images.get(image_handle)
+        {
             let bind_group = render_device.create_bind_group(
                 "skybox_bind_group",
                 &pipeline_cache.get_bind_group_layout(&pipeline.bind_group_layout),
                 &BindGroupEntries::sequential((
-                    &skybox.texture_view,
-                    &skybox.sampler,
+                    &image.texture_view,
+                    &image.sampler,
                     view_uniforms,
                     skybox_uniforms,
                 )),
@@ -246,6 +247,8 @@ fn prepare_skybox_bind_groups(
             commands
                 .entity(entity)
                 .insert(SkyboxBindGroup((bind_group, skybox_uniform_index.index())));
+        } else {
+            commands.entity(entity).remove::<SkyboxBindGroup>();
         }
     }
 }

crates/bevy_light/src/probe.rs

@@ -1,7 +1,8 @@
-use bevy_asset::{Assets, Handle, RenderAssetUsages};
+use bevy_asset::{Assets, Handle, HandleTemplate, RenderAssetUsages};
 use bevy_camera::visibility::{self, ViewVisibility, Visibility, VisibilityClass};
 use bevy_color::{Color, ColorToComponents, Srgba};
 use bevy_ecs::prelude::*;
+use bevy_ecs::template::{FromTemplate, OptionTemplate};
 use bevy_image::Image;
 use bevy_math::{Quat, UVec2, Vec3};
 use bevy_reflect::prelude::*;
@@ -224,7 +225,12 @@ impl Default for EnvironmentMapLight {
 #[reflect(Component, Default, Clone)]
 pub struct Skybox {
     /// The cubemap to use.
-    pub image: Handle<Image>,
+    ///
+    /// If this is [`None`], the skybox will not be rendered, as if it does not exist.
+    /// This allows `Skybox` to implement [`Default`].
+    #[template(OptionTemplate<HandleTemplate<Image>>)]
+    pub image: Option<Handle<Image>>,
+
     /// Scale factor applied to the skybox image.
     /// After applying this multiplier to the image samples, the resulting values should
     /// be in units of [cd/m^2](https://en.wikipedia.org/wiki/Candela_per_square_metre).
@@ -239,7 +245,7 @@ pub struct Skybox {
 impl Default for Skybox {
     fn default() -> Self {
         Skybox {
-            image: Handle::default(),
+            image: None,
             brightness: 0.0,
             rotation: Quat::IDENTITY,
         }

examples/3d/anisotropy.rs

@@ -305,7 +305,7 @@ fn add_skybox_and_environment_map(
         .entity(entity)
         .insert(Skybox {
             brightness: 5000.0,
-            image: asset_server.load("environment_maps/pisa_specular_rgb9e5_zstd.ktx2"),
+            image: Some(asset_server.load("environment_maps/pisa_specular_rgb9e5_zstd.ktx2")),
             ..default()
         })
         .insert(EnvironmentMapLight {

examples/3d/auto_exposure.rs

@@ -46,7 +46,7 @@ fn setup(
             ..default()
         },
         Skybox {
-            image: asset_server.load("environment_maps/pisa_specular_rgb9e5_zstd.ktx2"),
+            image: Some(asset_server.load("environment_maps/pisa_specular_rgb9e5_zstd.ktx2")),
             brightness: light_consts::lux::DIRECT_SUNLIGHT,
             ..default()
         },

examples/3d/clearcoat.rs

@@ -203,7 +203,7 @@ fn spawn_camera(commands: &mut Commands, asset_server: &AssetServer) {
         ))
         .insert(Skybox {
             brightness: 5000.0,
-            image: asset_server.load("environment_maps/pisa_specular_rgb9e5_zstd.ktx2"),
+            image: Some(asset_server.load("environment_maps/pisa_specular_rgb9e5_zstd.ktx2")),
             ..default()
         })
         .insert(EnvironmentMapLight {

examples/3d/contact_shadows.rs

@@ -117,7 +117,7 @@ fn setup(mut commands: Commands, asset_server: Res<AssetServer>) {
         Hdr,
         Skybox {
             brightness: 1000.0,
-            image: asset_server.load("environment_maps/pisa_diffuse_rgb9e5_zstd.ktx2"),
+            image: Some(asset_server.load("environment_maps/pisa_diffuse_rgb9e5_zstd.ktx2")),
             ..default()
         },
         EnvironmentMapLight {

examples/3d/irradiance_volumes.rs

@@ -236,7 +236,7 @@ fn spawn_camera(commands: &mut Commands, assets: &ExampleAssets) {
         Camera3d::default(),
         Transform::from_xyz(-10.012, 4.8605, 13.281).looking_at(Vec3::ZERO, Vec3::Y),
         Skybox {
-            image: assets.skybox.clone(),
+            image: Some(assets.skybox.clone()),
             brightness: 150.0,
             ..default()
         },

examples/3d/pcss.rs

@@ -177,7 +177,7 @@ fn spawn_camera(commands: &mut Commands, asset_server: &AssetServer) {
         .insert(MotionVectorPrepass)
         // Add a nice skybox.
         .insert(Skybox {
-            image: asset_server.load("environment_maps/sky_skybox.ktx2"),
+            image: Some(asset_server.load("environment_maps/sky_skybox.ktx2")),
             brightness: 500.0,
             rotation: Quat::IDENTITY,
         });

examples/3d/reflection_probes.rs

@@ -197,7 +197,7 @@ fn add_environment_map_to_camera(
             .entity(camera_entity)
             .insert(create_camera_environment_map_light(&cubemaps))
             .insert(Skybox {
-                image: cubemaps.specular_environment_map.clone(),
+                image: Some(cubemaps.specular_environment_map.clone()),
                 brightness: ENV_MAP_INTENSITY,
                 ..default()
             });