KhronosGroup / Vulkan-Docs

The Vulkan API Specification and related tools
Other
2.7k stars 452 forks source link

Inconsistency of unit of bufferRowLength and bufferImageHeight #2378

Open litherum opened 1 month ago

litherum commented 1 month ago

The description of VkBufferImageCopy says:

bufferRowLength and bufferImageHeight specify in texels a subregion of a larger two- or three-dimensional image in buffer memory, and control the addressing calculations.

Specifically, that "in texels" indicates the unit for these fields is texels.

However, the top of the section says:

For each (x,y,z,layer) coordinate, bytes in the buffer are accessed at offsets in the range [texelOffset, texelOffset + blockSize), where:

texelOffset = bufferOffset + (x × blockSize) + (y × rowExtent) + (z × sliceExtent) + (layer × layerExtent)

blockSize is the size of the block in bytes for the format

rowExtent = max(bufferRowLength, ⌈imageExtent.width / blockWidth⌉ × blockSize)

sliceExtent = max(bufferImageHeight, imageExtent.height × rowExtent)

layerExtent = imageExtent.depth × sliceExtent

Specifically, that "bytes in the buffer are accessed at offsets" indicates that the unit of texelOffset is bytes, which means each term in the sequence of additions has to have the same unit of bytes. y is a count (dimensionless), so rowExtent must also have the unit of bytes, which then means that bufferRowLength must also have the unit of bytes given its definition. The same logic can be applied to bufferImageHeight.

litherum commented 1 month ago

From experimentation, the unit of bufferRowLength appears to be texels, and the unit of bufferImageHeight appears to be rows.