diff --git a/crates/bevy_image/src/image.rs b/crates/bevy_image/src/image.rs index 9a6fcc63b8a7e..3f52d494a38e2 100644 --- a/crates/bevy_image/src/image.rs +++ b/crates/bevy_image/src/image.rs @@ -1063,21 +1063,21 @@ impl Image { } } - /// Changes the `size`, asserting that the total number of data elements (pixels) remains the - /// same. - /// - /// # Panics - /// Panics if the `new_size` does not have the same volume as to old one. - pub fn reinterpret_size(&mut self, new_size: Extent3d) { - assert_eq!( - new_size.volume(), - self.texture_descriptor.size.volume(), - "Incompatible sizes: old = {:?} new = {:?}", - self.texture_descriptor.size, - new_size - ); + /// Changes the `size` if the total number of data elements (pixels) remains the same. + /// If not, returns [`TextureReinterpretationError::IncompatibleSizes`]. + pub fn reinterpret_size( + &mut self, + new_size: Extent3d, + ) -> Result<(), TextureReinterpretationError> { + if new_size.volume() != self.texture_descriptor.size.volume() { + return Err(TextureReinterpretationError::IncompatibleSizes { + old: self.texture_descriptor.size, + new: new_size, + }); + } self.texture_descriptor.size = new_size; + Ok(()) } /// Resizes the image to the new size, keeping the pixel data intact, anchored at the top-left. @@ -1128,21 +1128,31 @@ impl Image { /// Takes a 2D image containing vertically stacked images of the same size, and reinterprets /// it as a 2D array texture, where each of the stacked images becomes one layer of the /// array. This is primarily for use with the `texture2DArray` shader uniform type. - /// - /// # Panics - /// Panics if the texture is not 2D, has more than one layers or is not evenly dividable into - /// the `layers`. - pub fn reinterpret_stacked_2d_as_array(&mut self, layers: u32) { + pub fn reinterpret_stacked_2d_as_array( + &mut self, + layers: u32, + ) -> Result<(), TextureReinterpretationError> { // Must be a stacked image, and the height must be divisible by layers. - assert_eq!(self.texture_descriptor.dimension, TextureDimension::D2); - assert_eq!(self.texture_descriptor.size.depth_or_array_layers, 1); - assert_eq!(self.height() % layers, 0); + if self.texture_descriptor.dimension != TextureDimension::D2 { + return Err(TextureReinterpretationError::WrongDimension); + } + if self.texture_descriptor.size.depth_or_array_layers != 1 { + return Err(TextureReinterpretationError::InvalidLayerCount); + } + if self.height() % layers != 0 { + return Err(TextureReinterpretationError::HeightNotDivisibleByLayers { + height: self.height(), + layers, + }); + } self.reinterpret_size(Extent3d { width: self.width(), height: self.height() / layers, depth_or_array_layers: layers, - }); + })?; + + Ok(()) } /// Convert a texture from a format to another. Only a few formats are @@ -1741,6 +1751,19 @@ pub enum TranscodeFormat { Rgb8, } +/// An error that occurs when reinterpreting an image. +#[derive(Error, Debug)] +pub enum TextureReinterpretationError { + #[error("incompatible sizes: old = {old:?} new = {new:?}")] + IncompatibleSizes { old: Extent3d, new: Extent3d }, + #[error("must be a 2d image")] + WrongDimension, + #[error("must not already be a layered image")] + InvalidLayerCount, + #[error("can not evenly divide height = {height} by layers = {layers}")] + HeightNotDivisibleByLayers { height: u32, layers: u32 }, +} + /// An error that occurs when accessing specific pixels in a texture. #[derive(Error, Debug)] pub enum TextureAccessError { diff --git a/examples/2d/tilemap_chunk.rs b/examples/2d/tilemap_chunk.rs index ac2df4e26e577..b47f745ce9185 100644 --- a/examples/2d/tilemap_chunk.rs +++ b/examples/2d/tilemap_chunk.rs @@ -64,7 +64,9 @@ fn update_tileset_image( for event in events.read() { if event.is_loaded_with_dependencies(chunk.tileset.id()) { let image = images.get_mut(&chunk.tileset).unwrap(); - image.reinterpret_stacked_2d_as_array(4); + image + .reinterpret_stacked_2d_as_array(4) + .expect("asset should be 2d texture with height evenly divisible by 4"); } } } diff --git a/examples/3d/skybox.rs b/examples/3d/skybox.rs index acfe0644d74cb..16d167c8d8c33 100644 --- a/examples/3d/skybox.rs +++ b/examples/3d/skybox.rs @@ -157,7 +157,9 @@ fn asset_loaded( // NOTE: PNGs do not have any metadata that could indicate they contain a cubemap texture, // so they appear as one texture. The following code reconfigures the texture as necessary. if image.texture_descriptor.array_layer_count() == 1 { - image.reinterpret_stacked_2d_as_array(image.height() / image.width()); + image + .reinterpret_stacked_2d_as_array(image.height() / image.width()) + .expect("asset should be 2d texture and height will always be evenly divisible with the given layers"); image.texture_view_descriptor = Some(TextureViewDescriptor { dimension: Some(TextureViewDimension::Cube), ..default() diff --git a/examples/shader/array_texture.rs b/examples/shader/array_texture.rs index 3897d2dca7c36..51703ae14837e 100644 --- a/examples/shader/array_texture.rs +++ b/examples/shader/array_texture.rs @@ -65,7 +65,9 @@ fn create_array_texture( // Create a new array texture asset from the loaded texture. let array_layers = 4; - image.reinterpret_stacked_2d_as_array(array_layers); + image + .reinterpret_stacked_2d_as_array(array_layers) + .expect("asset should be 2d texture with height evenly divisible by array_layers"); // Spawn some cubes using the array texture let mesh_handle = meshes.add(Cuboid::default()); diff --git a/release-content/migration-guides/image_reinterpret_returns_result.md b/release-content/migration-guides/image_reinterpret_returns_result.md new file mode 100644 index 0000000000000..29280afa5a5e6 --- /dev/null +++ b/release-content/migration-guides/image_reinterpret_returns_result.md @@ -0,0 +1,10 @@ +--- +title: "Image::reinterpret_size and Image::reinterpret_stacked_2d_as_array now return a Result" +pull_requests: [20797] +--- + +`Image::reinterpret_size` and `Image::reinterpret_stacked_2d_as_array` now return a `Result` instead of panicking. + +Previously, calling this method on image assets that did not conform to certain constraints could lead to runtime panics. The new return type makes the API safer and more explicit about the constraints. + +To migrate your code, you will need to handle the `Result` returned by `Image::reinterpret_size` or `Image::reinterpret_stacked_2d_as_array`.