Vulkan.Extensions.VK_KHR_surface_maintenance1

VkSurfacePresentModeKHR - Structure describing present mode of a surface

Description

If the SurfacePresentModeKHR structure is included in the pNext chain of PhysicalDeviceSurfaceInfo2KHR, the values returned in SurfaceCapabilitiesKHR::minImageCount, SurfaceCapabilitiesKHR::maxImageCount, SurfacePresentScalingCapabilitiesKHR::minScaledImageExtent, and SurfacePresentScalingCapabilitiesKHR::maxScaledImageExtent are valid only for the specified presentMode. If presentMode is PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR or PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR, the per-present mode image counts must both be one. The per-present mode image counts may be less-than or greater-than the image counts returned when SurfacePresentModeKHR is not provided.

If SwapchainPresentModesCreateInfoKHR is provided to swapchain creation, the requirements for forward progress may be less strict. For example, a FIFO swapchain might only require 2 images to guarantee forward progress, but a MAILBOX one might require 4. Without the per-present image counts, such an implementation would have to return 4 in SurfaceCapabilitiesKHR::minImageCount, which pessimizes FIFO. Conversely, an implementation may return a low number for minImageCount, but internally bump the image count when application queries getSwapchainImagesKHR, which can surprise applications, and is not discoverable until swapchain creation. Using SurfacePresentModeKHR and SwapchainPresentModesCreateInfoKHR together effectively removes this problem.

SwapchainPresentModesCreateInfoKHR is required for the specification to be backwards compatible with applications that do not know about, or make use of this feature.

Structure Chaining

Extends the structure

• PhysicalDeviceSurfaceInfo2KHR

See Also

VK_EXT_surface_maintenance1, VK_KHR_surface_maintenance1, PresentModeKHR, StructureType

VkSurfacePresentScalingCapabilitiesKHR - Structure describing the presentation scaling capabilities of the surface

Description

To query the set of supported scaling modes for a given present mode, add a SurfacePresentModeKHR structure in the pNext chain of PhysicalDeviceSurfaceInfo2KHR when calling getPhysicalDeviceSurfaceCapabilities2KHR. The implementation must return the same values in SurfacePresentScalingCapabilitiesKHR for any of the compatible present modes as obtained through SurfacePresentModeCompatibilityKHR.

The application can specify the scaling mode when creating a swapchain through the use of SwapchainPresentScalingCreateInfoKHR.

Structure Chaining

Extends the structure

• SurfaceCapabilities2KHR

See Also

VK_EXT_surface_maintenance1, VK_KHR_surface_maintenance1, Extent2D, PresentGravityFlagsKHR, PresentScalingFlagsKHR, StructureType

VkSurfacePresentModeCompatibilityKHR - Structure describing the subset of compatible presentation modes for the purposes of switching without swapchain recreation

Description

If pPresentModes is NULL, then the number of present modes that are compatible with the one specified in SurfacePresentModeKHR is returned in presentModeCount. Otherwise, presentModeCount must be set by the application to the number of elements in the pPresentModes array, and on return is overwritten with the number of values actually written to pPresentModes. If the value of presentModeCount is less than the number of compatible present modes that are supported, at most presentModeCount values will be written to pPresentModes. The implementation must include the present mode passed to SurfacePresentModeKHR in pPresentModes, unless presentModeCount is zero.

To query the set of present modes compatible with a given initial present mode, add a SurfacePresentModeKHR structure in the pNext chain of PhysicalDeviceSurfaceInfo2KHR when calling getPhysicalDeviceSurfaceCapabilities2KHR.

The application can create a swapchain whose present mode can be modified through the use of SwapchainPresentModesCreateInfoKHR.

Valid Usage (Implicit)

• sType must be STRUCTURE_TYPE_SURFACE_PRESENT_MODE_COMPATIBILITY_KHR

• If presentModeCount is not 0, and pPresentModes is not NULL, pPresentModes must be a valid pointer to an array of presentModeCount PresentModeKHR values

Structure Chaining

Extends the structure

• SurfaceCapabilities2KHR

See Also

VK_EXT_surface_maintenance1, VK_KHR_surface_maintenance1, PresentModeKHR, StructureType

VkPresentScalingFlagBitsKHR - Bitmask specifying presentation scaling methods

Description

• PRESENT_SCALING_ONE_TO_ONE_BIT_KHR specifies that no scaling occurs, and pixels in the swapchain image are mapped to one and only one pixel in the surface. The mapping between pixels is defined by the chosen presentation gravity.

• PRESENT_SCALING_ASPECT_RATIO_STRETCH_BIT_KHR specifies that the swapchain image will be minified or magnified such that at least one of the resulting width or height is equal to the corresponding surface dimension, and the other resulting dimension is less than or equal to the corresponding surface dimension, with the aspect ratio of the resulting image being identical to that of the original swapchain image.

• PRESENT_SCALING_STRETCH_BIT_KHR specifies that the swapchain image will be minified or magnified such that the resulting image dimensions are equal to those of the surface.

See Also

VK_EXT_surface_maintenance1, VK_KHR_surface_maintenance1, PresentScalingFlagsKHR

VkPresentGravityFlagBitsKHR - Bitmask specifying presentation pixel gravity on either the x or y axis

Description

• PRESENT_GRAVITY_MIN_BIT_KHR means that the pixels will gravitate towards the top or left side of the surface.

• PRESENT_GRAVITY_MAX_BIT_KHR means that the pixels will gravitate towards the bottom or right side of the surface.

• PRESENT_GRAVITY_CENTERED_BIT_KHR means that the pixels will be centered in the surface.

If the value in SurfaceCapabilitiesKHR::currentTransform is not SURFACE_TRANSFORM_IDENTITY_BIT_KHR, it is implementation-defined whether the gravity configuration applies to the presented image before or after transformation.

See Also

VK_EXT_surface_maintenance1, VK_KHR_surface_maintenance1, PresentGravityFlagsKHR

VkPresentModeKHR - Presentation mode supported for a surface

Description

• PRESENT_MODE_IMMEDIATE_KHR specifies that the presentation engine does not wait for a vertical blanking period to update the current image, meaning this mode may result in visible tearing. No internal queuing of presentation requests is needed, as the requests are applied immediately.

• PRESENT_MODE_MAILBOX_KHR specifies that the presentation engine waits for the next vertical blanking period to update the current image. Tearing cannot be observed. An internal single-entry queue is used to hold pending presentation requests. If the queue is full when a new presentation request is received, the new request replaces the existing entry, and any images associated with the prior entry become available for reuse by the application. One request is removed from the queue and processed during each vertical blanking period in which the queue is non-empty.

• PRESENT_MODE_FIFO_KHR specifies that the presentation engine waits for the next vertical blanking period to update the current image. Tearing cannot be observed. An internal queue is used to hold pending presentation requests. New requests are appended to the end of the queue, and one request is removed from the beginning of the queue and processed during each vertical blanking period in which the queue is non-empty. This is the only value of presentMode that is required to be supported.

• PRESENT_MODE_FIFO_RELAXED_KHR specifies that the presentation engine generally waits for the next vertical blanking period to update the current image. If a vertical blanking period has already passed since the last update of the current image then the presentation engine does not wait for another vertical blanking period for the update, meaning this mode may result in visible tearing in this case. This mode is useful for reducing visual stutter with an application that will mostly present a new image before the next vertical blanking period, but may occasionally be late, and present a new image just after the next vertical blanking period. An internal queue is used to hold pending presentation requests. New requests are appended to the end of the queue, and one request is removed from the beginning of the queue and processed during or after each vertical blanking period in which the queue is non-empty.

• PRESENT_MODE_FIFO_LATEST_READY_KHR specifies that the presentation engine waits for the next vertical blanking period to update the current image. Tearing cannot be observed. An internal queue is used to hold pending presentation requests. New requests are appended to the end of the queue. At each vertical blanking period, the presentation engine dequeues all successive requests that are ready to be presented from the beginning of the queue. If using the VK_GOOGLE_display_timing extension or the presentAtAbsoluteTime feature to provide a target present time, the presentation engine checks the specified time for each image. If the target present time is less-than or equal-to the current time, the presentation engine dequeues the image and checks the next one. The image of the last dequeued request is presented. The other dequeued requests are dropped.

• PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR specifies that the presentation engine and application have concurrent access to a single image, which is referred to as a shared presentable image. The presentation engine is only required to update the current image after a new presentation request is received. Therefore the application must make a presentation request whenever an update is required. However, the presentation engine may update the current image at any point, meaning this mode may result in visible tearing.

• PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR specifies that the presentation engine and application have concurrent access to a single image, which is referred to as a shared presentable image. The presentation engine periodically updates the current image on its regular refresh cycle. The application is only required to make one initial presentation request, after which the presentation engine must update the current image without any need for further presentation requests. The application can indicate the image contents have been updated by making a presentation request, but this does not guarantee the timing of when it will be updated. This mode may result in visible tearing if rendering to the image is not timed correctly.

The supported ImageUsageFlagBits of the presentable images of a swapchain created for a surface may differ depending on the presentation mode, and can be determined as per the table below:

Presentable Image Usage Queries

For reference, the mode indicated by PRESENT_MODE_FIFO_KHR is equivalent to the behavior of {wgl|glX|egl}SwapBuffers with a swap interval of 1, while the mode indicated by PRESENT_MODE_FIFO_RELAXED_KHR is equivalent to the behavior of {wgl|glX}SwapBuffers with a swap interval of -1 (from the {WGL|GLX}_EXT_swap_control_tear extensions).

See Also

VK_KHR_surface, LatencySurfaceCapabilitiesNV, SurfacePresentModeCompatibilityKHR, SurfacePresentModeKHR, SwapchainCreateInfoKHR, SwapchainPresentModeInfoKHR, SwapchainPresentModesCreateInfoKHR, getPhysicalDeviceSurfacePresentModes2EXT, getPhysicalDeviceSurfacePresentModesKHR