vulkan-3.26.1: Bindings to the Vulkan graphics API.
Safe HaskellSafe-Inferred
LanguageHaskell2010

Vulkan.Extensions.VK_KHR_incremental_present

Description

Name

VK_KHR_incremental_present - device extension

VK_KHR_incremental_present

Name String
VK_KHR_incremental_present
Extension Type
Device extension
Registered Extension Number
85
Revision
2
Ratification Status
Ratified
Extension and Version Dependencies
VK_KHR_swapchain
Contact

Other Extension Metadata

Last Modified Date
2016-11-02
IP Status
No known IP claims.
Contributors
  • Ian Elliott, Google
  • Jesse Hall, Google
  • Alon Or-bach, Samsung
  • James Jones, NVIDIA
  • Daniel Rakos, AMD
  • Ray Smith, ARM
  • Mika Isojarvi, Google
  • Jeff Juliano, NVIDIA
  • Jeff Bolz, NVIDIA

Description

This device extension extends queuePresentKHR, from the VK_KHR_swapchain extension, allowing an application to specify a list of rectangular, modified regions of each image to present. This should be used in situations where an application is only changing a small portion of the presentable images within a swapchain, since it enables the presentation engine to avoid wasting time presenting parts of the surface that have not changed.

This extension is leveraged from the EGL_KHR_swap_buffers_with_damage extension.

New Structures

New Enum Constants

Issues

1) How should we handle steroescopic-3D swapchains? We need to add a layer for each rectangle. One approach is to create another struct containing the Rect2D plus layer, and have PresentRegionsKHR point to an array of that struct. Another approach is to have two parallel arrays, pRectangles and pLayers, where pRectangles[i] and pLayers[i] must be used together. Which approach should we use, and if the array of a new structure, what should that be called?

RESOLVED: Create a new structure, which is a Rect2D plus a layer, and will be called RectLayerKHR.

2) Where is the origin of the RectLayerKHR?

RESOLVED: The upper left corner of the presentable image(s) of the swapchain, per the definition of framebuffer coordinates.

3) Does the rectangular region, RectLayerKHR, specify pixels of the swapchain’s image(s), or of the surface?

RESOLVED: Of the image(s). Some presentation engines may scale the pixels of a swapchain’s image(s) to the size of the surface. The size of the swapchain’s image(s) will be consistent, where the size of the surface may vary over time.

4) What if all of the rectangles for a given swapchain contain a width and/or height of zero?

RESOLVED: The application is indicating that no pixels changed since the last present. The presentation engine may use such a hint and not update any pixels for the swapchain. However, all other semantics of queuePresentKHR must still be honored, including waiting for semaphores to signal.

5) When the swapchain is created with SwapchainCreateInfoKHR::preTransform set to a value other than SURFACE_TRANSFORM_IDENTITY_BIT_KHR, should the rectangular region, RectLayerKHR, be transformed to align with the preTransform?

RESOLVED: No. The rectangular region in RectLayerKHR should not be transformed. As such, it may not align with the extents of the swapchain’s image(s). It is the responsibility of the presentation engine to transform the rectangular region. This matches the behavior of the Android presentation engine, which set the precedent.

Version History

  • Revision 1, 2016-11-02 (Ian Elliott)

    • Internal revisions
  • Revision 2, 2021-03-18 (Ian Elliott)

    • Clarified alignment of rectangles for presentation engines that support transformed swapchains.

See Also

PresentRegionKHR, PresentRegionsKHR, RectLayerKHR

Document Notes

For more information, see the Vulkan Specification

This page is a generated document. Fixes and changes should be made to the generator scripts, not directly.

Synopsis

Documentation

data PresentRegionsKHR Source #

VkPresentRegionsKHR - Structure hint of rectangular regions changed by vkQueuePresentKHR

Valid Usage

Valid Usage (Implicit)

  • If pRegions is not NULL, pRegions must be a valid pointer to an array of swapchainCount valid PresentRegionKHR structures
  • swapchainCount must be greater than 0

See Also

VK_KHR_incremental_present, PresentRegionKHR, StructureType

Constructors

PresentRegionsKHR 

Fields

  • swapchainCount :: Word32

    swapchainCount is the number of swapchains being presented to by this command.

  • regions :: Vector PresentRegionKHR

    pRegions is NULL or a pointer to an array of PresentRegionKHR elements with swapchainCount entries. If not NULL, each element of pRegions contains the region that has changed since the last present to the swapchain in the corresponding entry in the PresentInfoKHR::pSwapchains array.

data PresentRegionKHR Source #

VkPresentRegionKHR - Structure containing rectangular region changed by vkQueuePresentKHR for a given VkImage

Valid Usage (Implicit)

  • If rectangleCount is not 0, and pRectangles is not NULL, pRectangles must be a valid pointer to an array of rectangleCount valid RectLayerKHR structures

See Also

VK_KHR_incremental_present, PresentRegionsKHR, RectLayerKHR

Constructors

PresentRegionKHR 

Fields

  • rectangleCount :: Word32

    rectangleCount is the number of rectangles in pRectangles, or zero if the entire image has changed and should be presented.

  • rectangles :: Vector RectLayerKHR

    pRectangles is either NULL or a pointer to an array of RectLayerKHR structures. The RectLayerKHR structure is the framebuffer coordinates, plus layer, of a portion of a presentable image that has changed and must be presented. If non-NULL, each entry in pRectangles is a rectangle of the given image that has changed since the last image was presented to the given swapchain. The rectangles must be specified relative to SurfaceCapabilitiesKHR::currentTransform, regardless of the swapchain’s preTransform. The presentation engine will apply the preTransform transformation to the rectangles, along with any further transformation it applies to the image content.

data RectLayerKHR Source #

VkRectLayerKHR - Structure containing a rectangle, including layer, changed by vkQueuePresentKHR for a given VkImage

Description

Some platforms allow the size of a surface to change, and then scale the pixels of the image to fit the surface. RectLayerKHR specifies pixels of the swapchain’s image(s), which will be constant for the life of the swapchain.

Valid Usage

See Also

VK_KHR_incremental_present, Extent2D, Offset2D, PresentRegionKHR

Constructors

RectLayerKHR 

Fields

  • offset :: Offset2D

    offset is the origin of the rectangle, in pixels.

  • extent :: Extent2D

    extent is the size of the rectangle, in pixels.

  • layer :: Word32

    layer is the layer of the image. For images with only one layer, the value of layer must be 0.

type KHR_INCREMENTAL_PRESENT_EXTENSION_NAME = "VK_KHR_incremental_present" Source #

pattern KHR_INCREMENTAL_PRESENT_EXTENSION_NAME :: forall a. (Eq a, IsString a) => a Source #