use crate::{BufferAddress, Extent3d, TexelCopyBufferLayout, TextureAspect, TextureFormat}; impl TexelCopyBufferLayout { /// Extract a variety of information about the given copy operation. /// /// Returns an error if the size of the copy overflows a `u64`, or if the arguments are /// not valid in conjunction with the `bytes_per_row` or `rows_per_image` parameters in /// `self`. /// /// This is public for use by `wgpu-core` and `wgpu-hal`, it is not a stable API. /// /// Although WebGPU requires that `bytes_per_row` and `rows_per_image` be specified in /// cases where they apply, we are more lenient here (although it's not clear if that is /// necessary). Our caller, `validate_linear_texture_data`, enforces this and other /// WebGPU requirements on the copy parameters that we do not check here. #[doc(hidden)] #[inline(always)] pub fn get_buffer_texture_copy_info( &self, format: TextureFormat, aspect: TextureAspect, copy_size: &Extent3d, ) -> Result { let copy_width = BufferAddress::from(copy_size.width); let copy_height = BufferAddress::from(copy_size.height); let depth_or_array_layers = BufferAddress::from(copy_size.depth_or_array_layers); let block_size_bytes = BufferAddress::from(format.block_copy_size(Some(aspect)).unwrap()); let (block_width, block_height) = format.block_dimensions(); let block_width_texels = BufferAddress::from(block_width); let block_height_texels = BufferAddress::from(block_height); let width_blocks = copy_width.div_ceil(block_width_texels); let height_blocks = copy_height.div_ceil(block_height_texels); // The spec calls this bytesInLastRow. let row_bytes_dense = width_blocks * block_size_bytes; let row_stride_bytes = match self.bytes_per_row.map(BufferAddress::from) { Some(bytes_per_row) if bytes_per_row >= row_bytes_dense => bytes_per_row, Some(_) => return Err(Error::InvalidBytesPerRow), None => row_bytes_dense, }; let image_rows_dense = height_blocks; let image_stride_rows = match self.rows_per_image.map(BufferAddress::from) { Some(rows_per_image) if rows_per_image >= image_rows_dense => rows_per_image, Some(_) => return Err(Error::InvalidRowsPerImage), None => image_rows_dense, }; let image_bytes_dense = match image_rows_dense.checked_sub(1) { Some(rows_minus_one) => rows_minus_one .checked_mul(row_stride_bytes) .ok_or(Error::ImageBytesOverflow(false))? .checked_add(row_bytes_dense) .ok_or(Error::ImageBytesOverflow(true))?, None => 0, }; // It is possible that `image_stride_bytes` overflows, but the actual // copy size does not, when the copy only has a single layer and // `image_size_bytes` is not used. We don't worry about handling this // gracefully because WebGPU texture size limits should keep things out // of this realm entirely. let image_stride_bytes = row_stride_bytes .checked_mul(image_stride_rows) .ok_or(Error::ImageStrideOverflow)?; let bytes_in_copy = if depth_or_array_layers <= 1 { depth_or_array_layers * image_bytes_dense } else { (depth_or_array_layers - 1) .checked_mul(image_stride_bytes) .ok_or(Error::ArraySizeOverflow(false))? .checked_add(image_bytes_dense) .ok_or(Error::ArraySizeOverflow(true))? }; Ok(BufferTextureCopyInfo { copy_width, copy_height, depth_or_array_layers, offset: self.offset, block_size_bytes, block_width_texels, block_height_texels, width_blocks, height_blocks, row_bytes_dense, row_stride_bytes, image_stride_rows, image_stride_bytes, image_rows_dense, image_bytes_dense, bytes_in_copy, }) } } /// Information about a copy between a buffer and a texture. /// /// Mostly used for internal calculations, but useful nonetheless. /// Generated by [`TexelCopyBufferLayout::get_buffer_texture_copy_info`]. #[derive(Debug, Clone, Copy, PartialEq, Eq)] pub struct BufferTextureCopyInfo { /// The width of the copy region in pixels. pub copy_width: u64, /// The height of the copy region in pixels. pub copy_height: u64, /// The depth of the copy region in pixels. pub depth_or_array_layers: u64, /// The offset in the buffer where the copy starts. pub offset: u64, /// The size of a single texture texel block in bytes. pub block_size_bytes: u64, /// The number of texel in a texel block in the x direction. pub block_width_texels: u64, /// The number of texel in a texel block in the y direction. pub block_height_texels: u64, /// The width of the copy region in blocks. pub width_blocks: u64, /// The height of the copy region in blocks. pub height_blocks: u64, /// The number of bytes in the last row of the copy region. pub row_bytes_dense: u64, /// The stride in bytes between the start of one row in an image and the next row in the same image. /// /// This includes any padding between one row and the next row. pub row_stride_bytes: u64, /// The stride in rows between the start of one image and the next image. pub image_stride_rows: u64, /// The stride in bytes between the start of one image and the next image. pub image_stride_bytes: u64, /// The number of rows in a densely packed list of images. /// /// This is the number of rows in the image that are actually used for texel data, /// and does not include any padding rows, unlike `image_stride_rows`. pub image_rows_dense: u64, /// The number of bytes in a densely packed list of images. /// /// This is the number of bytes in the image that are actually used for texel data, /// or are used for padding between _rows_. Padding at the end of the last row and /// between _images_ is not included. pub image_bytes_dense: u64, /// The total number of bytes in the copy region. /// /// This includes all padding except the padding after the last row in the copy. pub bytes_in_copy: u64, } /// Errors that can occur while populating `BufferTextureCopyInfo`. // // We use the additional detail provided by these errors (over wgpu-core's // `TransferError`) to improve the reliability of the tests in this module. It // doesn't seem worth plumbing them upwards, because at the API level it // shouldn't be possible to exceed them without exceeding the WebGPU limits on // texture dimension. But the WebGPU limits are not currently enforced, so we // have to do something here to protect against overflows. // // Even when the WebGPU limits are enforced, it may still be useful to keep the // checks here as a failsafe if the correctness of the primary limit enforcement // is not immediately apparent. #[derive(Clone, Copy, Debug, Eq, PartialEq)] pub enum BufferTextureCopyInfoError { /// The `bytes_per_row` is too small for the texture width. InvalidBytesPerRow, /// The `rows_per_image` is too small for the texture height. InvalidRowsPerImage, /// The image stride overflows a `u64`. ImageStrideOverflow, /// The last-layer byte size overflows a `u64`. /// /// The bool value indicates whether the multiplication (false) or the /// addition (true) overflowed. ImageBytesOverflow(bool), /// The total size of the copy overflows a `u64`. /// /// The bool value indicates whether the multiplication (false) or the /// addition (true) overflowed. ArraySizeOverflow(bool), } type Error = BufferTextureCopyInfoError; #[cfg(test)] mod tests { use super::*; #[derive(Clone)] struct LTDTest { layout: TexelCopyBufferLayout, format: TextureFormat, aspect: TextureAspect, copy_size: Extent3d, expected_result: BufferTextureCopyInfo, // Normally a Result would be make sense, // but since the existing tests were written to mutate // `LTDTest.expected_result`, keeping this separate avoids a bunch of // `unwrap`s. expected_error: Option, } impl LTDTest { #[track_caller] fn run(&self) { let linear_texture_data = self.layout .get_buffer_texture_copy_info(self.format, self.aspect, &self.copy_size); let expected = match self.expected_error { Some(err) => Err(err), None => Ok(self.expected_result), }; assert_eq!(linear_texture_data, expected); } } #[test] fn linear_texture_data_1d_copy() { let mut test = LTDTest { layout: TexelCopyBufferLayout { offset: 0, bytes_per_row: None, rows_per_image: None, }, format: TextureFormat::Rgba8Unorm, aspect: TextureAspect::All, copy_size: Extent3d { width: 4, height: 1, depth_or_array_layers: 1, }, expected_result: BufferTextureCopyInfo { copy_width: 4, copy_height: 1, depth_or_array_layers: 1, offset: 0, block_size_bytes: 4, block_width_texels: 1, block_height_texels: 1, width_blocks: 4, height_blocks: 1, row_bytes_dense: 16, row_stride_bytes: 16, image_stride_rows: 1, image_stride_bytes: 16, image_rows_dense: 1, image_bytes_dense: 16, bytes_in_copy: 16, }, expected_error: None, }; test.run(); // Changing bytes_per_row should only change the bytes_per_row, not the bytes_in_copy // as that is only affected by the last row size. test.layout.bytes_per_row = Some(32); test.expected_result.row_stride_bytes = 32; test.expected_result.image_stride_bytes = 32; test.run(); // Changing rows_per_image should only change the rows_per_image and bytes_per_image, nothing else test.layout.rows_per_image = Some(4); test.expected_result.image_stride_bytes = 128; // 32 * 4 test.expected_result.image_stride_rows = 4; test.run(); // Changing the offset should change nothing. test.layout.offset = 4; test.expected_result.offset = 4; test.run(); } #[test] fn linear_texture_data_2d_3d_copy() { let template = LTDTest { layout: TexelCopyBufferLayout { offset: 0, bytes_per_row: None, rows_per_image: None, }, format: TextureFormat::Rgba8Unorm, aspect: TextureAspect::All, copy_size: Extent3d { width: 7, height: 12, depth_or_array_layers: 1, }, expected_result: BufferTextureCopyInfo { copy_width: 7, copy_height: 12, depth_or_array_layers: 1, offset: 0, block_size_bytes: 4, block_width_texels: 1, block_height_texels: 1, width_blocks: 7, height_blocks: 12, row_bytes_dense: 4 * 7, row_stride_bytes: 4 * 7, image_stride_rows: 12, image_stride_bytes: 4 * 7 * 12, image_rows_dense: 12, image_bytes_dense: 4 * 7 * 12, bytes_in_copy: 4 * 7 * 12, }, expected_error: None, }; let mut test = template.clone(); test.run(); // Changing bytes_per_row changes a number of other properties. test.layout.bytes_per_row = Some(48); test.expected_result.row_stride_bytes = 48; test.expected_result.image_stride_bytes = 48 * 12; test.expected_result.image_bytes_dense = 48 * 11 + (4 * 7); test.expected_result.bytes_in_copy = 48 * 11 + (4 * 7); test.run(); // Making this a 3D copy only changes the depth_or_array_layers and the bytes_in_copy. test.copy_size.depth_or_array_layers = 4; test.expected_result.depth_or_array_layers = 4; test.expected_result.bytes_in_copy = 48 * 12 * 3 + 48 * 11 + (4 * 7); // 4 layers test.run(); // Changing rows_per_image test.layout.rows_per_image = Some(20); test.expected_result.image_stride_rows = 20; test.expected_result.image_stride_bytes = 20 * test.expected_result.row_stride_bytes; test.expected_result.bytes_in_copy = 48 * 20 * 3 + 48 * 11 + (4 * 7); // 4 layers test.run(); // Invalid because the row stride is too small. let mut test = template.clone(); test.layout.bytes_per_row = Some(20); test.expected_error = Some(Error::InvalidBytesPerRow); test.run(); // Invalid because the image stride is too small. let mut test = template.clone(); test.layout.rows_per_image = Some(8); test.expected_error = Some(Error::InvalidRowsPerImage); test.run(); // Invalid because width * height * texel_size_bytes overflows. let mut test = template.clone(); test.copy_size.width = u32::MAX; test.copy_size.height = u32::MAX; test.expected_error = Some(Error::ImageBytesOverflow(false)); test.run(); // Invalid because the addition of row_bytes_dense overflows. // (But the product rows_minus_one * row_stride_bytes does not overflow.) let mut test = template.clone(); test.copy_size.width = 0x8000_0000; test.copy_size.height = 0x8000_0000; test.expected_error = Some(Error::ImageBytesOverflow(true)); test.run(); // Invalid because image_stride_bytes overflows. let mut test = template.clone(); test.copy_size.width = 0x8000_0000; test.layout.rows_per_image = Some(0x8000_0000); test.expected_result.image_stride_rows = 0x8000_0000; test.expected_error = Some(Error::ImageStrideOverflow); test.run(); // Invalid because (layers - 1) * image_stride_bytes overflows. let mut test = template.clone(); test.copy_size.depth_or_array_layers = 0x8000_0000; test.copy_size.width = 0x1_0000; test.copy_size.height = 0x1_0000; test.expected_error = Some(Error::ArraySizeOverflow(false)); test.run(); // Invalid because the total size of the copy overflows (but the product // (layers - 1) * image_stride_bytes does not overflow). let mut test = template.clone(); test.copy_size.depth_or_array_layers = 0x3fff_8001; test.copy_size.width = 0x1_0001; test.copy_size.height = 0x1_0001; test.expected_error = Some(Error::ArraySizeOverflow(true)); test.run(); } #[test] fn linear_texture_data_2d_3d_compressed_copy() { let mut test = LTDTest { layout: TexelCopyBufferLayout { offset: 0, bytes_per_row: None, rows_per_image: None, }, format: TextureFormat::Bc1RgbaUnorm, aspect: TextureAspect::All, copy_size: Extent3d { width: 7, height: 13, depth_or_array_layers: 1, }, expected_result: BufferTextureCopyInfo { copy_width: 7, copy_height: 13, depth_or_array_layers: 1, offset: 0, block_size_bytes: 8, block_width_texels: 4, block_height_texels: 4, width_blocks: 2, height_blocks: 4, row_bytes_dense: 8 * 2, // block size * width_blocks row_stride_bytes: 8 * 2, image_stride_rows: 4, image_stride_bytes: 8 * 2 * 4, // block size * width_blocks * height_blocks image_rows_dense: 4, image_bytes_dense: 8 * 2 * 4, bytes_in_copy: 8 * 2 * 4, }, expected_error: None, }; test.run(); // Changing bytes_per_row. test.layout.bytes_per_row = Some(48); test.expected_result.row_stride_bytes = 48; test.expected_result.image_stride_bytes = 48 * 4; test.expected_result.image_bytes_dense = 48 * 3 + (8 * 2); test.expected_result.bytes_in_copy = 48 * 3 + (8 * 2); test.run(); // Changing rows_per_image. test.layout.rows_per_image = Some(8); test.expected_result.image_stride_bytes = 48 * 8; test.expected_result.image_stride_rows = 8; test.run(); // Making this a 3D copy only changes the depth_or_array_layers and the bytes_in_copy. test.copy_size.depth_or_array_layers = 4; test.expected_result.depth_or_array_layers = 4; test.expected_result.bytes_in_copy = 48 * 8 * 3 + 48 * 3 + (8 * 2); // 4 layers test.run(); } }