vkGetPhysicalDevicePresentRectanglesKHR(3)

# vkGetPhysicalDevicePresentRectanglesKHR(3) Manual Page

## Name

vkGetPhysicalDevicePresentRectanglesKHR - Query present rectangles for a surface on a physical device

Loading… please wait.

## C Specification

When using `VK_DEVICE_GROUP_PRESENT_MODE_LOCAL_MULTI_DEVICE_BIT_KHR`, the application may need to know which regions of the surface are used when presenting locally on each physical device. Presentation of swapchain images to this surface need only have valid contents in the regions returned by this command.

To query a set of rectangles used in presentation on the physical device, call:

    // Provided by VK_KHR_swapchain with VK_VERSION_1_1, VK_KHR_device_group with VK_KHR_surface
    VkResult vkGetPhysicalDevicePresentRectanglesKHR(
        VkPhysicalDevice                            physicalDevice,
        VkSurfaceKHR                                surface,
        uint32_t*                                   pRectCount,
        VkRect2D*                                   pRects);

## Parameters

- `physicalDevice` is the physical device.

- `surface` is the surface.

- `pRectCount` is a pointer to an integer related to the number of rectangles available or queried, as described below.

- `pRects` is either `NULL` or a pointer to an array of VkRect2D structures.

## Description

If `pRects` is `NULL`, then the number of rectangles used when presenting the given `surface` is returned in `pRectCount`. Otherwise, `pRectCount` must point to a variable set by the user to the number of elements in the `pRects` array, and on return the variable is overwritten with the number of structures actually written to `pRects`. If the value of `pRectCount` is less than the number of rectangles, at most `pRectCount` structures will be written. If `pRectCount` is smaller than the number of rectangles used for the given `surface`, `VK_INCOMPLETE` will be returned instead of `VK_SUCCESS` to indicate that not all the available values were returned.

The values returned by this command are not invariant, and may change in response to the surface being moved, resized, or occluded.

The rectangles returned by this command must not overlap.

Valid Usage (Implicit)

- VUID-vkGetPhysicalDevicePresentRectanglesKHR-physicalDevice-parameter
  `physicalDevice` must be a valid VkPhysicalDevice handle

- VUID-vkGetPhysicalDevicePresentRectanglesKHR-surface-parameter
  `surface` must be a valid VkSurfaceKHR handle

- VUID-vkGetPhysicalDevicePresentRectanglesKHR-pRectCount-parameter
  `pRectCount` must be a valid pointer to a `uint32_t` value

- VUID-vkGetPhysicalDevicePresentRectanglesKHR-pRects-parameter
  If the value referenced by `pRectCount` is not `0`, and `pRects` is not `NULL`, `pRects` must be a valid pointer to an array of `pRectCount` VkRect2D structures

- VUID-vkGetPhysicalDevicePresentRectanglesKHR-commonparent
  Both of `physicalDevice`, and `surface` must have been created, allocated, or retrieved from the same VkInstance

Host Synchronization

- Host access to `surface` must be externally synchronized

Return Codes

On success, this command returns

  - `VK_SUCCESS`

  - `VK_INCOMPLETE`

On failure, this command returns

  - `VK_ERROR_OUT_OF_HOST_MEMORY`

  - `VK_ERROR_OUT_OF_DEVICE_MEMORY`

## See Also

VkPhysicalDevice, VkRect2D, VkSurfaceKHR

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