C Specification

The VkQueueFamilyOptimalImageTransferGranularityPropertiesKHR structure is defined as:

// Provided by VK_KHR_maintenance11
typedef struct VkQueueFamilyOptimalImageTransferGranularityPropertiesKHR {
    VkStructureType    sType;
    void*              pNext;
    VkExtent3D         optimalImageTransferGranularity;
} VkQueueFamilyOptimalImageTransferGranularityPropertiesKHR;

Members

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • optimalImageTransferGranularity is the optimal granularity for image copy operations in this queue family.

Description

If this structure is included in the pNext chain of the VkQueueFamilyProperties2 structure passed to vkGetPhysicalDeviceQueueFamilyProperties2, then it is filled with the optimal image transfer granularity for the specified queue family.

The value returned in optimalImageTransferGranularity has a unit of compressed texel blocks for images having a block-compressed format, and a unit of texels otherwise.

Possible values of optimalImageTransferGranularity are:

  • (0,0,0) specifies that an image copy operation is optimal only when copying whole mip levels, i.e. all of the following conditions are met:

    • The x, y, and z members of a VkOffset3D are zero.

    • The width, height, and depth members of a VkExtent3D parameter match the width, height, and depth of the image subresource corresponding to the parameter, respectively.

  • (Ax, Ay, Az) where Ax, Ay, and Az are all integer powers of two. An image copy operation is optimal when all of the following conditions are met:

    • width of a VkExtent3D parameter is an integer multiple of Ax, or else x + width equals the width of the image subresource corresponding to the parameter.

    • height of a VkExtent3D parameter is an integer multiple of Ay, or else y + height equals the height of the image subresource corresponding to the parameter.

    • depth of a VkExtent3D parameter is an integer multiple of Az, or else z + depth equals the depth of the image subresource corresponding to the parameter.

    • If the format of the image corresponding to the parameters is one of the block-compressed formats then for the purposes of the above calculations the granularity must be scaled up by the compressed texel block dimensions.

Note

While it is not required that copies are optimal, there may be a performance cost for copies not aligned to optimalImageTransferGranularity.
Valid Usage (Implicit)
Structure Chaining
Extends the structure

See Also

VK_KHR_maintenance11, VkExtent3D, VkStructureType

Document Notes

For more information, see the Vulkan Specification.

This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.

Copyright

Copyright 2014-2026 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0