Back to Bevy

`Image::pixel_bytes` and `Image::pixel_data_offset` now return `Result`

_release-content/migration-guides/image_pixel_bytes_result.md

0.19.01.3 KB
Original Source

Image::pixel_bytes, Image::pixel_bytes_mut, and Image::pixel_data_offset now return Result<..., TextureAccessError>.

Previously, these methods returned Option and would silently fail for both out-of-bounds access and unsupported texture formats (such as compressed textures). This caused error information to be lost, making it impossible for callers to distinguish between these different failure cases.

Now, these methods properly propagate TextureAccessError:

  • TextureAccessError::OutOfBounds for coordinates outside the image bounds
  • TextureAccessError::UnsupportedTextureFormat for compressed or unsupported texture formats
  • TextureAccessError::Uninitialized if the image data is not initialized

Update any code using these methods to handle the Result return type:

rust
// 0.18
if let Some(bytes) = image.pixel_bytes(coords) {
    // use bytes
}

// 0.19
match image.pixel_bytes(coords) {
    Ok(bytes) => {
        // use bytes
    }
    Err(TextureAccessError::Uninitialized) => {
        // handle missing image data
    }
    Err(TextureAccessError::OutOfBounds { .. }) => {
        // handle out of bounds
    }
    Err(TextureAccessError::UnsupportedTextureFormat(format)) => {
        // handle compressed/unsupported format
    }
}