C Specification

To query available shading rates, call:

// Provided by VK_KHR_fragment_shading_rate
VkResult vkGetPhysicalDeviceFragmentShadingRatesKHR(
    VkPhysicalDevice                            physicalDevice,
    uint32_t*                                   pFragmentShadingRateCount,
    VkPhysicalDeviceFragmentShadingRateKHR*     pFragmentShadingRates);

Parameters

  • physicalDevice is the handle to the physical device whose properties will be queried.

  • pFragmentShadingRateCount is a pointer to an integer related to the number of fragment shading rates available or queried, as described below.

  • pFragmentShadingRates is either NULL or a pointer to an array of VkPhysicalDeviceFragmentShadingRateKHR structures.

Description

If pFragmentShadingRates is NULL, then the number of fragment shading rates available is returned in pFragmentShadingRateCount. Otherwise, pFragmentShadingRateCount must point to a variable set by the user to the number of elements in the pFragmentShadingRates array, and on return the variable is overwritten with the number of structures actually written to pFragmentShadingRates. If pFragmentShadingRateCount is less than the number of fragment shading rates available, at most pFragmentShadingRateCount structures will be written, and VK_INCOMPLETE will be returned instead of VK_SUCCESS, to indicate that not all the available fragment shading rates were returned.

The returned array of fragment shading rates must be ordered from largest fragmentSize.width value to smallest, and each set of fragment shading rates with the same fragmentSize.width value must be ordered from largest fragmentSize.height to smallest. Any two entries in the array must not have the same fragmentSize values.

For any entry in the array, the following rules also apply:

  • The value of fragmentSize.width must be less than or equal to maxFragmentSize.width.

  • The value of fragmentSize.width must be greater than or equal to 1.

  • The value of fragmentSize.width must be a power-of-two.

  • The value of fragmentSize.height must be less than or equal to maxFragmentSize.height.

  • The value of fragmentSize.height must be greater than or equal to 1.

  • The value of fragmentSize.height must be a power-of-two.

  • The highest sample count in sampleCounts must be less than or equal to maxFragmentShadingRateRasterizationSamples.

  • The product of fragmentSize.width, fragmentSize.height, and the highest sample count in sampleCounts must be less than or equal to maxFragmentShadingRateCoverageSamples.

Implementations must support at least the following shading rates:

sampleCounts fragmentSize

VK_SAMPLE_COUNT_1_BIT | VK_SAMPLE_COUNT_4_BIT

{2,2}

VK_SAMPLE_COUNT_1_BIT | VK_SAMPLE_COUNT_4_BIT

{2,1}

~0

{1,1}

If framebufferColorSampleCounts, includes VK_SAMPLE_COUNT_2_BIT, the required rates must also include VK_SAMPLE_COUNT_2_BIT.

Note

Including the {1,1} fragment size is done for completeness; it has no actual effect on the support of rendering without setting the fragment size. All sample counts and render pass transforms are supported for this rate.

The returned set of fragment shading rates must be returned in the native (rotated) coordinate system. For rasterization using render pass transform not equal to VK_SURFACE_TRANSFORM_IDENTITY_BIT_KHR, the application must transform the returned fragment shading rates into the current (unrotated) coordinate system to get the supported rates for that transform.

Note

For example, consider an implementation returning support for 4x2, but not 2x4 in the set of supported fragment shading rates. This means that for transforms VK_SURFACE_TRANSFORM_ROTATE_90_BIT_KHR and VK_SURFACE_TRANSFORM_ROTATE_270_BIT_KHR, 2x4 is a supported rate, but 4x2 is an unsupported rate.
Valid Usage (Implicit)

  • VUID-vkGetPhysicalDeviceFragmentShadingRatesKHR-physicalDevice-parameter
    physicalDevice must be a valid VkPhysicalDevice handle

  • VUID-vkGetPhysicalDeviceFragmentShadingRatesKHR-pFragmentShadingRateCount-parameter
    pFragmentShadingRateCount must be a valid pointer to a uint32_t value

  • VUID-vkGetPhysicalDeviceFragmentShadingRatesKHR-pFragmentShadingRates-parameter
    If the value referenced by pFragmentShadingRateCount is not 0, and pFragmentShadingRates is not NULL, pFragmentShadingRates must be a valid pointer to an array of pFragmentShadingRateCount VkPhysicalDeviceFragmentShadingRateKHR structures

Return Codes
On success, this command returns

  • VK_SUCCESS

  • VK_INCOMPLETE

On failure, this command returns

  • VK_ERROR_OUT_OF_HOST_MEMORY

See Also

VK_KHR_fragment_shading_rate, VkPhysicalDevice, VkPhysicalDeviceFragmentShadingRateKHR

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-2024 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0