VkQueueFamilyOptimalImageTransferGranularityPropertiesKHR(3)

# VkQueueFamilyOptimalImageTransferGranularityPropertiesKHR(3) Manual Page

## Name

VkQueueFamilyOptimalImageTransferGranularityPropertiesKHR - Structure specifying the optimal image transfer granularity for a queue family

## 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)

- VUID-VkQueueFamilyOptimalImageTransferGranularityPropertiesKHR-sType-sType
  `sType` must be VK_STRUCTURE_TYPE_QUEUE_FAMILY_OPTIMAL_IMAGE_TRANSFER_GRANULARITY_PROPERTIES_KHR

Structure Chaining

Extends the structure

  - VkQueueFamilyProperties2

## 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