Image::reinterpret_size and Image::reinterpret_stacked_2d_as_array now return a Result

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 {

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");
         }
     }
 }

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()

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());

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`.