rename/deprecate block_size -> block_copy_size, improve docs (#4647)

Co-authored-by: Teodor Tanasoaia <[email protected]>

CHANGELOG.md

@@ -47,6 +47,7 @@ For naga changelogs at or before v0.14.0. See [naga's changelog](naga/CHANGELOG.
 #### General
 
 - Log vulkan validation layer messages during instance creation and destruction: By @exrook in [#4586](https://github.com/gfx-rs/wgpu/pull/4586)
+- `TextureFormat::block_size` is deprecated, use `TextureFormat::block_copy_size` instead: By @wumpf in [#4647](https://github.com/gfx-rs/wgpu/pull/4647)
 
 ### Bug Fixes
 

tests/src/image.rs

@@ -388,7 +388,7 @@ fn copy_texture_to_buffer_with_aspect(
     aspect: TextureAspect,
 ) {
     let (block_width, block_height) = texture.format().block_dimensions();
-    let block_size = texture.format().block_size(Some(aspect)).unwrap();
+    let block_size = texture.format().block_copy_size(Some(aspect)).unwrap();
     let bytes_per_row = align_to(
         (texture.width() / block_width) * block_size,
         COPY_BYTES_PER_ROW_ALIGNMENT,
@@ -501,7 +501,7 @@ impl ReadbackBuffers {
             let mut buffer_depth_bytes_per_row = (texture.width() / block_width)
                 * texture
                     .format()
-                    .block_size(Some(TextureAspect::DepthOnly))
+                    .block_copy_size(Some(TextureAspect::DepthOnly))
                     .unwrap_or(4);
             if should_align_buffer_size {
                 buffer_depth_bytes_per_row =
@@ -515,7 +515,7 @@ impl ReadbackBuffers {
                 (texture.width() / block_width)
                     * texture
                         .format()
-                        .block_size(Some(TextureAspect::StencilOnly))
+                        .block_copy_size(Some(TextureAspect::StencilOnly))
                         .unwrap_or(4),
                 COPY_BYTES_PER_ROW_ALIGNMENT,
             );
@@ -542,8 +542,8 @@ impl ReadbackBuffers {
                 buffer_stencil: Some(buffer_stencil),
             }
         } else {
-            let mut bytes_per_row =
-                (texture.width() / block_width) * texture.format().block_size(None).unwrap_or(4);
+            let mut bytes_per_row = (texture.width() / block_width)
+                * texture.format().block_copy_size(None).unwrap_or(4);
             if should_align_buffer_size {
                 bytes_per_row = align_to(bytes_per_row, COPY_BYTES_PER_ROW_ALIGNMENT);
             }
@@ -581,7 +581,7 @@ impl ReadbackBuffers {
         device.poll(Maintain::Wait);
         let (block_width, block_height) = self.texture_format.block_dimensions();
         let expected_bytes_per_row = (self.texture_width / block_width)
-            * self.texture_format.block_size(aspect).unwrap_or(4);
+            * self.texture_format.block_copy_size(aspect).unwrap_or(4);
         let expected_buffer_size = expected_bytes_per_row
             * (self.texture_height / block_height)
             * self.texture_depth_or_array_layers;

tests/tests/zero_init_texture_after_discard.rs

@@ -167,7 +167,7 @@ impl<'ctx> TestCase<'ctx> {
             });
             ctx.queue.submit([encoder.finish()]);
         } else {
-            let block_size = format.block_size(None).unwrap();
+            let block_size = format.block_copy_size(None).unwrap();
             let bytes_per_row = texture.width() * block_size;
 
             // Size for tests is chosen so that we don't need to care about buffer alignments.

wgpu-core/src/command/clear.rs

@@ -331,7 +331,7 @@ fn clear_texture_via_buffer_copies<A: hal::Api>(
     let mut zero_buffer_copy_regions = Vec::new();
     let buffer_copy_pitch = alignments.buffer_copy_pitch.get() as u32;
     let (block_width, block_height) = texture_desc.format.block_dimensions();
-    let block_size = texture_desc.format.block_size(None).unwrap();
+    let block_size = texture_desc.format.block_copy_size(None).unwrap();
 
     let bytes_per_row_alignment = get_lowest_common_denom(buffer_copy_pitch, block_size);
 

wgpu-core/src/command/transfer.rs

@@ -254,7 +254,7 @@ pub(crate) fn validate_linear_texture_data(
 
     let offset = layout.offset;
 
-    let block_size = format.block_size(Some(aspect)).unwrap() as BufferAddress;
+    let block_size = format.block_copy_size(Some(aspect)).unwrap() as BufferAddress;
     let (block_width, block_height) = format.block_dimensions();
     let block_width = block_width as BufferAddress;
     let block_height = block_height as BufferAddress;

wgpu-core/src/device/queue.rs

@@ -697,7 +697,7 @@ impl<G: GlobalIdentityHandlerFactory> Global<G> {
         let block_size = dst
             .desc
             .format
-            .block_size(Some(destination.aspect))
+            .block_copy_size(Some(destination.aspect))
             .unwrap();
         let bytes_per_row_alignment =
             get_lowest_common_denom(device.alignments.buffer_copy_pitch.get() as u32, block_size);

wgpu-hal/src/dx12/command.rs

@@ -39,7 +39,7 @@ impl crate::BufferTextureCopy {
                     let actual = self.buffer_layout.bytes_per_row.unwrap_or_else(|| {
                         // this may happen for single-line updates
                         let block_size = format
-                            .block_size(Some(self.texture_base.aspect.map()))
+                            .block_copy_size(Some(self.texture_base.aspect.map()))
                             .unwrap();
                         (self.size.width / block_width) * block_size
                     });

wgpu-hal/src/gles/queue.rs

@@ -564,7 +564,7 @@ impl super::Queue {
                 ref copy,
             } => {
                 let (block_width, block_height) = dst_format.block_dimensions();
-                let block_size = dst_format.block_size(None).unwrap();
+                let block_size = dst_format.block_copy_size(None).unwrap();
                 let format_desc = self.shared.describe_texture_format(dst_format);
                 let row_texels = copy
                     .buffer_layout
@@ -702,7 +702,7 @@ impl super::Queue {
                 dst_target: _,
                 ref copy,
             } => {
-                let block_size = src_format.block_size(None).unwrap();
+                let block_size = src_format.block_copy_size(None).unwrap();
                 if src_format.is_compressed() {
                     log::error!("Not implemented yet: compressed texture copy to buffer");
                     return;

wgpu-hal/src/vulkan/command.rs

@@ -23,7 +23,7 @@ impl super::Texture {
                 buffer_offset: r.buffer_layout.offset,
                 buffer_row_length: r.buffer_layout.bytes_per_row.map_or(0, |bpr| {
                     let block_size = format
-                        .block_size(Some(r.texture_base.aspect.map()))
+                        .block_copy_size(Some(r.texture_base.aspect.map()))
                         .unwrap();
                     block_width * (bpr / block_size)
                 }),

wgpu-types/src/lib.rs

@@ -2813,7 +2813,9 @@ impl TextureFormat {
         }
     }
 
-    /// Returns the dimension of a block of texels.
+    /// Returns the dimension of a [block](https://gpuweb.github.io/gpuweb/#texel-block) of texels.
+    ///
+    /// Uncompressed formats have a block dimension of `(1, 1)`.
     pub fn block_dimensions(&self) -> (u32, u32) {
         match *self {
             Self::R8Unorm
@@ -3225,14 +3227,34 @@ impl TextureFormat {
         }
     }
 
-    /// Returns the [texel block size](https://gpuweb.github.io/gpuweb/#texel-block-size)
-    /// of this format.
+    /// The number of bytes one [texel block](https://gpuweb.github.io/gpuweb/#texel-block) occupies during an image copy, if applicable.
+    ///
+    /// Known as the [texel block copy footprint](https://gpuweb.github.io/gpuweb/#texel-block-copy-footprint).
+    ///
+    /// Note that for uncompressed formats this is the same as the size of a single texel,
+    /// since uncompressed formats have a block size of 1x1.
     ///
     /// Returns `None` if any of the following are true:
     ///  - the format is combined depth-stencil and no `aspect` was provided
     ///  - the format is `Depth24Plus`
     ///  - the format is `Depth24PlusStencil8` and `aspect` is depth.
+    #[deprecated(since = "0.19.0", note = "Use `block_copy_size` instead.")]
     pub fn block_size(&self, aspect: Option<TextureAspect>) -> Option<u32> {
+        self.block_copy_size(aspect)
+    }
+
+    /// The number of bytes one [texel block](https://gpuweb.github.io/gpuweb/#texel-block) occupies during an image copy, if applicable.
+    ///
+    /// Known as the [texel block copy footprint](https://gpuweb.github.io/gpuweb/#texel-block-copy-footprint).
+    ///
+    /// Note that for uncompressed formats this is the same as the size of a single texel,
+    /// since uncompressed formats have a block size of 1x1.
+    ///
+    /// Returns `None` if any of the following are true:
+    ///  - the format is combined depth-stencil and no `aspect` was provided
+    ///  - the format is `Depth24Plus`
+    ///  - the format is `Depth24PlusStencil8` and `aspect` is depth.
+    pub fn block_copy_size(&self, aspect: Option<TextureAspect>) -> Option<u32> {
         match *self {
             Self::R8Unorm | Self::R8Snorm | Self::R8Uint | Self::R8Sint => Some(1),
 

wgpu/src/util/device.rs

@@ -88,7 +88,7 @@ impl DeviceExt for crate::Device {
         // Will return None only if it's a combined depth-stencil format
         // If so, default to 4, validation will fail later anyway since the depth or stencil
         // aspect needs to be written to individually
-        let block_size = desc.format.block_size(None).unwrap_or(4);
+        let block_size = desc.format.block_copy_size(None).unwrap_or(4);
         let (block_width, block_height) = desc.format.block_dimensions();
         let layer_iterations = desc.array_layer_count();