github/wgpu
1
1
Fork 0
mirror of https://github.com/gfx-rs/wgpu.git synced 2026-04-22 03:02:01 -04:00
Code Issues Packages Projects Releases Wiki Activity

Improve documentation of ImageDataLayout

Browse Source
This commit is contained in:
Connor Fitzgerald
2021-07-12 00:11:18 -04:00
parent e5142b3cdc
commit 3deb4f5fb6
1 changed files with 26 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files

33
wgpu-types/src/lib.rs
View File

@@ -2738,6 +2738,15 @@ impl<T> Default for RenderBundleDescriptor<Option<T>> {
}
/// Layout of a texture in a buffer's memory.
///
/// The bytes per row and rows per image can be hard to figure out so here are some examples:
///
/// | Resolution | Format | Bytes per block | Pixels per block | Bytes per row | Rows per image |
/// |------------|--------|-----------------|------------------|----------------------------------------|------------------------------|
/// | 256x256 | RGBA8 | 4 | 1 * 1 * 1 | 256 * 4 = Some(1024) | None |
/// | 32x16x8 | RGBA8 | 4 | 1 * 1 * 1 | 32 * 4 = 128 padded to 256 = Some(256) | None |
/// | 256x256 | BC3 | 16 | 4 * 4 * 1 | 16 * (256 / 4) = 1024 = Some(1024) | None |
/// | 64x64x8 | BC3 | 16 | 4 * 4 * 1 | 16 * (64 / 4) = 256 = Some(256) | 64 / 4 = 16 = Some(16) |
#[repr(C)]
#[derive(Clone, Copy, Debug, Default)]
#[cfg_attr(feature = "trace", derive(serde::Serialize))]
@@ -2746,18 +2755,28 @@ pub struct ImageDataLayout {
/// Offset into the buffer that is the start of the texture. Must be a multiple of texture block size.
/// For non-compressed textures, this is 1.
pub offset: BufferAddress,
/// Bytes per "row" of the image. This represents one row of pixels in the x direction. Compressed
/// textures include multiple rows of pixels in each "row".
/// Required if there are multiple rows (i.e. height or depth is more than one pixel or pixel block for compressed textures)
/// Bytes per "row" in an image.
///
/// A row is one row of pixels or of compressed blocks in the x direction.
///
/// This value is required if there are multiple rows (i.e. height or depth is more than one pixel or pixel block for compressed textures)
///
/// Must be a multiple of 256 for [`CommandEncoder::copy_buffer_to_texture`] and [`CommandEncoder::copy_texture_to_buffer`]. You must manually pad
/// the image such that this is a multiple of 256. It will not affect the image data.
///
/// Must be a multiple of 256 for [`CommandEncoder::copy_buffer_to_texture`] and [`CommandEncoder::copy_texture_to_buffer`].
/// [`Queue::write_texture`] does not have this requirement.
///
/// Must be a multiple of the texture block size. For non-compressed textures, this is 1.
pub bytes_per_row: Option<NonZeroU32>,
/// Rows that make up a single "image". Each "image" is one layer in the z direction of a 3D image. May be larger
/// than `copy_size.y`.
/// Required if there are multiple images (i.e. the depth is more than one)
/// "Rows" that make up a single "image".
///
/// A row is one row of pixels or of compressed blocks in the x direction.
///
/// An image is one layer in the z direction of a 3D image or 2DArray texture.
///
/// The amount of rows per image may be larger than the actual amount of rows of data.
///
/// Required if there are multiple images (i.e. the depth is more than one).
pub rows_per_image: Option<NonZeroU32>,
}