vkGetPhysicalDeviceSurfacePresentModes2EXT - Query supported presentation modes

Parameters

• physicalDevice is the physical device that will be associated with the swapchain to be created, as described for createSwapchainKHR.

• pSurfaceInfo is a pointer to a PhysicalDeviceSurfaceInfo2KHR structure describing the surface and other fixed parameters that would be consumed by createSwapchainKHR.
• pPresentModeCount is a pointer to an integer related to the number of presentation modes available or queried, as described below.
• pPresentModes is either NULL or a pointer to an array of PresentModeKHR values, indicating the supported presentation modes.

Description

getPhysicalDeviceSurfacePresentModes2EXT behaves similarly to getPhysicalDeviceSurfacePresentModesKHR, with the ability to specify extended inputs via chained input structures.

Valid Usage (Implicit)

• physicalDevice must be a valid PhysicalDevice handle

• pSurfaceInfo must be a valid pointer to a valid PhysicalDeviceSurfaceInfo2KHR structure
• pPresentModeCount must be a valid pointer to a uint32_t value
• If the value referenced by pPresentModeCount is not 0, and pPresentModes is not NULL, pPresentModes must be a valid pointer to an array of pPresentModeCount PresentModeKHR values

Return Codes

Success

• SUCCESS
• INCOMPLETE

Failure

• ERROR_OUT_OF_HOST_MEMORY
• ERROR_OUT_OF_DEVICE_MEMORY
• ERROR_SURFACE_LOST_KHR

See Also

PhysicalDevice, PhysicalDeviceSurfaceInfo2KHR, PresentModeKHR

vkGetDeviceGroupSurfacePresentModes2EXT - Query device group present capabilities for a surface

Parameters

• device is the logical device.

• pSurfaceInfo is a pointer to a PhysicalDeviceSurfaceInfo2KHR structure describing the surface and other fixed parameters that would be consumed by createSwapchainKHR.
• pModes is a pointer to a DeviceGroupPresentModeFlagsKHR in which the supported device group present modes for the surface are returned.

Description

getDeviceGroupSurfacePresentModes2EXT behaves similarly to getDeviceGroupSurfacePresentModesKHR, with the ability to specify extended inputs via chained input structures.

Return Codes

Success

• SUCCESS

Failure

• ERROR_OUT_OF_HOST_MEMORY
• ERROR_OUT_OF_DEVICE_MEMORY
• ERROR_SURFACE_LOST_KHR

See Also

Device, DeviceGroupPresentModeFlagsKHR, PhysicalDeviceSurfaceInfo2KHR

vkAcquireFullScreenExclusiveModeEXT - Acquire full-screen exclusive mode for a swapchain

Parameters

• device is the device associated with swapchain.

• swapchain is the swapchain to acquire exclusive full-screen access for.

Valid Usage

• swapchain must not be in the retired state

• swapchain must be a swapchain created with a SurfaceFullScreenExclusiveInfoEXT structure, with fullScreenExclusive set to FULL_SCREEN_EXCLUSIVE_APPLICATION_CONTROLLED_EXT
• swapchain must not currently have exclusive full-screen access

A return value of SUCCESS indicates that the swapchain successfully acquired exclusive full-screen access. The swapchain will retain this exclusivity until either the application releases exclusive full-screen access with releaseFullScreenExclusiveModeEXT, destroys the swapchain, or if any of the swapchain commands return ERROR_FULL_SCREEN_EXCLUSIVE_MODE_LOST_EXT indicating that the mode was lost because of platform-specific changes.

If the swapchain was unable to acquire exclusive full-screen access to the display then ERROR_INITIALIZATION_FAILED is returned. An application can attempt to acquire exclusive full-screen access again for the same swapchain even if this command fails, or if ERROR_FULL_SCREEN_EXCLUSIVE_MODE_LOST_EXT has been returned by a swapchain command.

Valid Usage (Implicit)

• device must be a valid Device handle

• swapchain must be a valid SwapchainKHR handle
• Both of device, and swapchain must have been created, allocated, or retrieved from the same Instance

Return Codes

Success

• SUCCESS

Failure

• ERROR_OUT_OF_HOST_MEMORY
• ERROR_OUT_OF_DEVICE_MEMORY
• ERROR_INITIALIZATION_FAILED
• ERROR_SURFACE_LOST_KHR

See Also

Device, SwapchainKHR

vkReleaseFullScreenExclusiveModeEXT - Release full-screen exclusive mode from a swapchain

Parameters

• device is the device associated with swapchain.

• swapchain is the swapchain to release exclusive full-screen access from.

Description

Note

Applications will not be able to present to swapchain after this call until exclusive full-screen access is reacquired. This is usually useful to handle when an application is minimised or otherwise intends to stop presenting for a time.

Valid Usage

See Also

Device, SwapchainKHR

VkSurfaceFullScreenExclusiveInfoEXT - Structure specifying the preferred full-screen transition behavior

Description

If this structure is not present, fullScreenExclusive is considered to be FULL_SCREEN_EXCLUSIVE_DEFAULT_EXT.

Valid Usage (Implicit)

See Also

FullScreenExclusiveEXT, StructureType

VkSurfaceFullScreenExclusiveWin32InfoEXT - Structure specifying additional creation parameters specific to Win32 fullscreen exclusive mode

Description

Note

If hmonitor is invalidated (e.g. the monitor is unplugged) during the lifetime of a swapchain created with this structure, operations on that swapchain will return ERROR_OUT_OF_DATE_KHR.

Note

It is the responsibility of the application to change the display settings of the targeted Win32 display using the appropriate platform APIs. Such changes may alter the surface capabilities reported for the created surface.

Valid Usage (Implicit)

See Also

StructureType

VkSurfaceCapabilitiesFullScreenExclusiveEXT - Structure describing full screen exclusive capabilities of a surface

Description

This structure can be included in the pNext chain of SurfaceCapabilities2KHR to determine support for exclusive full-screen access. If fullScreenExclusiveSupported is FALSE, it indicates that exclusive full-screen access is not obtainable for this surface.

Applications must not attempt to create swapchains with FULL_SCREEN_EXCLUSIVE_APPLICATION_CONTROLLED_EXT set if fullScreenExclusiveSupported is FALSE.

Valid Usage (Implicit)

See Also

Bool32, StructureType

VkFullScreenExclusiveEXT - Hint values an application can specify affecting full-screen transition behavior

See Also

SurfaceFullScreenExclusiveInfoEXT

VkSurfaceKHR - Opaque handle to a surface object

Description

The VK_KHR_surface extension declares the SurfaceKHR object, and provides a function for destroying SurfaceKHR objects. Separate platform-specific extensions each provide a function for creating a SurfaceKHR object for the respective platform. From the application’s perspective this is an opaque handle, just like the handles of other Vulkan objects.

See Also

PhysicalDeviceSurfaceInfo2KHR, SwapchainCreateInfoKHR, createAndroidSurfaceKHR, createDisplayPlaneSurfaceKHR, createHeadlessSurfaceEXT, createIOSSurfaceMVK, createImagePipeSurfaceFUCHSIA, createMacOSSurfaceMVK, createMetalSurfaceEXT, createStreamDescriptorSurfaceGGP, createViSurfaceNN, createWaylandSurfaceKHR, createWin32SurfaceKHR, createXcbSurfaceKHR, createXlibSurfaceKHR, destroySurfaceKHR, getDeviceGroupSurfacePresentModesKHR, getPhysicalDevicePresentRectanglesKHR, getPhysicalDeviceSurfaceCapabilities2EXT, getPhysicalDeviceSurfaceCapabilitiesKHR, getPhysicalDeviceSurfaceFormatsKHR, getPhysicalDeviceSurfacePresentModesKHR, getPhysicalDeviceSurfaceSupportKHR

VkSwapchainKHR - Opaque handle to a swapchain object

Description

A swapchain is an abstraction for an array of presentable images that are associated with a surface. The presentable images are represented by Image objects created by the platform. One image (which can be an array image for multiview/stereoscopic-3D surfaces) is displayed at a time, but multiple images can be queued for presentation. An application renders to the image, and then queues the image for presentation to the surface.

A native window cannot be associated with more than one non-retired swapchain at a time. Further, swapchains cannot be created for native windows that have a non-Vulkan graphics API surface associated with them.

Note

The presentation engine is an abstraction for the platform’s compositor or display engine.

The presentation engine may be synchronous or asynchronous with respect to the application and/or logical device.

Some implementations may use the device’s graphics queue or dedicated presentation hardware to perform presentation.

The presentable images of a swapchain are owned by the presentation engine. An application can acquire use of a presentable image from the presentation engine. Use of a presentable image must occur only after the image is returned by acquireNextImageKHR, and before it is presented by queuePresentKHR. This includes transitioning the image layout and rendering commands.

An application can acquire use of a presentable image with acquireNextImageKHR. After acquiring a presentable image and before modifying it, the application must use a synchronization primitive to ensure that the presentation engine has finished reading from the image. The application can then transition the image’s layout, queue rendering commands to it, etc. Finally, the application presents the image with queuePresentKHR, which releases the acquisition of the image.

The presentation engine controls the order in which presentable images are acquired for use by the application.

Note

This allows the platform to handle situations which require out-of-order return of images after presentation. At the same time, it allows the application to generate command buffers referencing all of the images in the swapchain at initialization time, rather than in its main loop.

See Also

AcquireNextImageInfoKHR, BindImageMemorySwapchainInfoKHR, ImageSwapchainCreateInfoKHR, PresentInfoKHR, SwapchainCreateInfoKHR, acquireFullScreenExclusiveModeEXT, acquireNextImageKHR, createSharedSwapchainsKHR, createSwapchainKHR, destroySwapchainKHR, getPastPresentationTimingGOOGLE, getRefreshCycleDurationGOOGLE, getSwapchainCounterEXT, getSwapchainImagesKHR, getSwapchainStatusKHR, releaseFullScreenExclusiveModeEXT, setHdrMetadataEXT, setLocalDimmingAMD

VkPhysicalDeviceSurfaceInfo2KHR - Structure specifying a surface and related swapchain creation parameters

Description

The members of PhysicalDeviceSurfaceInfo2KHR correspond to the arguments to getPhysicalDeviceSurfaceCapabilitiesKHR, with sType and pNext added for extensibility.

Additional capabilities of a surface may be available to swapchains created with different full-screen exclusive settings - particularly if exclusive full-screen access is application controlled. These additional capabilities can be queried by adding a SurfaceFullScreenExclusiveInfoEXT structure to the pNext chain of this structure when used to query surface properties. Additionally, for Win32 surfaces with application controlled exclusive full-screen access, chaining a SurfaceFullScreenExclusiveWin32InfoEXT structure may also report additional surface capabilities. These additional capabilities only apply to swapchains created with the same parameters included in the pNext chain of SwapchainCreateInfoKHR.

Valid Usage

• If the pNext chain includes a SurfaceFullScreenExclusiveInfoEXT structure with its fullScreenExclusive member set to FULL_SCREEN_EXCLUSIVE_APPLICATION_CONTROLLED_EXT, and surface was created using createWin32SurfaceKHR, a SurfaceFullScreenExclusiveWin32InfoEXT structure must be included in the pNext chain

Valid Usage (Implicit)

• sType must be STRUCTURE_TYPE_PHYSICAL_DEVICE_SURFACE_INFO_2_KHR

• Each pNext member of any structure (including this one) in the pNext chain must be either NULL or a pointer to a valid instance of SurfaceFullScreenExclusiveInfoEXT or SurfaceFullScreenExclusiveWin32InfoEXT
• The sType value of each struct in the pNext chain must be unique
• surface must be a valid SurfaceKHR handle

See Also

StructureType, SurfaceKHR, getDeviceGroupSurfacePresentModes2EXT, getPhysicalDeviceSurfaceCapabilities2KHR, getPhysicalDeviceSurfaceFormats2KHR, getPhysicalDeviceSurfacePresentModes2EXT

VkPresentModeKHR - presentation mode supported for a surface

Description

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

Note

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

SwapchainCreateInfoKHR, getPhysicalDeviceSurfacePresentModes2EXT, getPhysicalDeviceSurfacePresentModesKHR

VkDeviceGroupPresentModeFlagBitsKHR - Bitmask specifying supported device group present modes

See Also

DeviceGroupPresentInfoKHR, DeviceGroupPresentModeFlagsKHR