Vulkan.Extensions.VK_KHR_incremental_present

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

Extension and Version Dependencies

• Requires support for Vulkan 1.0
• Requires VK_KHR_swapchain to be enabled for any device-level functionality

Contact

• Ian Elliott @ianelliottus%0A*Here describe the issue or question you have about the VK_KHR_incremental_present extension*

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

• PresentRegionKHR

• RectLayerKHR

• Extending PresentInfoKHR:

  • PresentRegionsKHR

New Enum Constants

• KHR_INCREMENTAL_PRESENT_EXTENSION_NAME

• KHR_INCREMENTAL_PRESENT_SPEC_VERSION

• Extending StructureType:

  • STRUCTURE_TYPE_PRESENT_REGIONS_KHR

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.

Documentation

data PresentRegionsKHR

VkPresentRegionsKHR - Structure hint of rectangular regions changed by vkQueuePresentKHR

Valid Usage

• swapchainCount must be the same value as PresentInfoKHR::swapchainCount, where PresentInfoKHR is included in the pNext chain of this PresentRegionsKHR structure

Valid Usage (Implicit)

• sType must be STRUCTURE_TYPE_PRESENT_REGIONS_KHR

• 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.

Instances

Show PresentRegionsKHR

Defined in Vulkan.Extensions.VK_KHR_incremental_present

Methods

showsPrec :: Int -> PresentRegionsKHR -> ShowS

show :: PresentRegionsKHR -> String

showList :: [PresentRegionsKHR] -> ShowS

FromCStruct PresentRegionsKHR

Defined in Vulkan.Extensions.VK_KHR_incremental_present

Methods

peekCStruct :: Ptr PresentRegionsKHR -> IO PresentRegionsKHR

ToCStruct PresentRegionsKHR

Defined in Vulkan.Extensions.VK_KHR_incremental_present

Methods

withCStruct :: PresentRegionsKHR -> (Ptr PresentRegionsKHR -> IO b) -> IO b

pokeCStruct :: Ptr PresentRegionsKHR -> PresentRegionsKHR -> IO b -> IO b

withZeroCStruct :: (Ptr PresentRegionsKHR -> IO b) -> IO b

pokeZeroCStruct :: Ptr PresentRegionsKHR -> IO b -> IO b

cStructSize :: Int

cStructAlignment :: Int

Zero PresentRegionsKHR

Defined in Vulkan.Extensions.VK_KHR_incremental_present

Methods

zero :: PresentRegionsKHR

data PresentRegionKHR

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.

Instances

Show PresentRegionKHR

Defined in Vulkan.Extensions.VK_KHR_incremental_present

Methods

showsPrec :: Int -> PresentRegionKHR -> ShowS

show :: PresentRegionKHR -> String

showList :: [PresentRegionKHR] -> ShowS

FromCStruct PresentRegionKHR

Defined in Vulkan.Extensions.VK_KHR_incremental_present

Methods

peekCStruct :: Ptr PresentRegionKHR -> IO PresentRegionKHR

ToCStruct PresentRegionKHR

Defined in Vulkan.Extensions.VK_KHR_incremental_present

Methods

withCStruct :: PresentRegionKHR -> (Ptr PresentRegionKHR -> IO b) -> IO b

pokeCStruct :: Ptr PresentRegionKHR -> PresentRegionKHR -> IO b -> IO b

withZeroCStruct :: (Ptr PresentRegionKHR -> IO b) -> IO b

pokeZeroCStruct :: Ptr PresentRegionKHR -> IO b -> IO b

cStructSize :: Int

cStructAlignment :: Int

Zero PresentRegionKHR

Defined in Vulkan.Extensions.VK_KHR_incremental_present

Methods

zero :: PresentRegionKHR

data RectLayerKHR

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

• The sum of offset and extent, after being transformed according to the preTransform member of the SwapchainCreateInfoKHR structure, must be no greater than the imageExtent member of the SwapchainCreateInfoKHR structure passed to createSwapchainKHR

• layer must be less than the imageArrayLayers member of the SwapchainCreateInfoKHR structure passed to createSwapchainKHR

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.

Instances

Storable RectLayerKHR

Defined in Vulkan.Extensions.VK_KHR_incremental_present

Methods

sizeOf :: RectLayerKHR -> Int

alignment :: RectLayerKHR -> Int

peekElemOff :: Ptr RectLayerKHR -> Int -> IO RectLayerKHR

pokeElemOff :: Ptr RectLayerKHR -> Int -> RectLayerKHR -> IO ()

peekByteOff :: Ptr b -> Int -> IO RectLayerKHR

pokeByteOff :: Ptr b -> Int -> RectLayerKHR -> IO ()

peek :: Ptr RectLayerKHR -> IO RectLayerKHR

poke :: Ptr RectLayerKHR -> RectLayerKHR -> IO ()

Show RectLayerKHR

Defined in Vulkan.Extensions.VK_KHR_incremental_present

Methods

showsPrec :: Int -> RectLayerKHR -> ShowS

show :: RectLayerKHR -> String

showList :: [RectLayerKHR] -> ShowS

FromCStruct RectLayerKHR

Defined in Vulkan.Extensions.VK_KHR_incremental_present

Methods

peekCStruct :: Ptr RectLayerKHR -> IO RectLayerKHR

ToCStruct RectLayerKHR

Defined in Vulkan.Extensions.VK_KHR_incremental_present

Methods

withCStruct :: RectLayerKHR -> (Ptr RectLayerKHR -> IO b) -> IO b

pokeCStruct :: Ptr RectLayerKHR -> RectLayerKHR -> IO b -> IO b

withZeroCStruct :: (Ptr RectLayerKHR -> IO b) -> IO b

pokeZeroCStruct :: Ptr RectLayerKHR -> IO b -> IO b

cStructSize :: Int

cStructAlignment :: Int

Zero RectLayerKHR

Defined in Vulkan.Extensions.VK_KHR_incremental_present

Methods

zero :: RectLayerKHR

type KHR_INCREMENTAL_PRESENT_SPEC_VERSION = 2

pattern KHR_INCREMENTAL_PRESENT_SPEC_VERSION :: forall a. Integral a => a

type KHR_INCREMENTAL_PRESENT_EXTENSION_NAME = "VK_KHR_incremental_present"

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