vkGetPhysicalDeviceFragmentShadingRatesKHR(3)

# vkGetPhysicalDeviceFragmentShadingRatesKHR(3) Manual Page

## Name

vkGetPhysicalDeviceFragmentShadingRatesKHR - Get available shading rates for a physical device

Loading… please wait.

## 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 are supported for this 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

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 (c) 2014-2020 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0