Vulkan.Extensions.VK_EXT_full_screen_exclusive

vkGetPhysicalDeviceSurfacePresentModes2EXT - Query supported presentation modes

Description

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

Valid Usage

• If the VK_GOOGLE_surfaceless_query extension is not enabled, pSurfaceInfo->surface must be a valid SurfaceKHR handle

• If pSurfaceInfo->surface is not NULL_HANDLE, pSurfaceInfo->surface must be supported by physicalDevice, as reported by getPhysicalDeviceSurfaceSupportKHR or an equivalent platform-specific mechanism

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

• INCOMPLETE

• SUCCESS

Failure

• ERROR_OUT_OF_DEVICE_MEMORY

• ERROR_OUT_OF_HOST_MEMORY

• ERROR_SURFACE_LOST_KHR

• ERROR_UNKNOWN

• ERROR_VALIDATION_FAILED

See Also

VK_EXT_full_screen_exclusive, PhysicalDevice, PhysicalDeviceSurfaceInfo2KHR, PresentModeKHR

vkGetDeviceGroupSurfacePresentModes2EXT - Query device group present capabilities for a surface

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_DEVICE_MEMORY

• ERROR_OUT_OF_HOST_MEMORY

• ERROR_SURFACE_LOST_KHR

• ERROR_UNKNOWN

• ERROR_VALIDATION_FAILED

See Also

VK_EXT_full_screen_exclusive, VK_KHR_device_group, VK_VERSION_1_1, Device, DeviceGroupPresentModeFlagsKHR, PhysicalDeviceSurfaceInfo2KHR

vkAcquireFullScreenExclusiveModeEXT - Acquire full-screen exclusive mode for a swapchain

Valid Usage

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.

Return Codes

Success

• SUCCESS

Failure

• ERROR_INITIALIZATION_FAILED

• ERROR_OUT_OF_DEVICE_MEMORY

• ERROR_OUT_OF_HOST_MEMORY

• ERROR_SURFACE_LOST_KHR

• ERROR_UNKNOWN

• ERROR_VALIDATION_FAILED

See Also

VK_EXT_full_screen_exclusive, Device, SwapchainKHR

vkReleaseFullScreenExclusiveModeEXT - Release full-screen exclusive mode from a swapchain

Description

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 minimized or otherwise intends to stop presenting for a time.

Return Codes

Success

• SUCCESS

Failure

• ERROR_OUT_OF_DEVICE_MEMORY

• ERROR_OUT_OF_HOST_MEMORY

• ERROR_SURFACE_LOST_KHR

• ERROR_UNKNOWN

• ERROR_VALIDATION_FAILED

See Also

VK_EXT_full_screen_exclusive, 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.

Structure Chaining

Extends the structures

• PhysicalDeviceSurfaceInfo2KHR

• SwapchainCreateInfoKHR

See Also

VK_EXT_full_screen_exclusive, FullScreenExclusiveEXT, StructureType

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

Description

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.

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.

Structure Chaining

Extends the structures

• PhysicalDeviceSurfaceInfo2KHR

• SwapchainCreateInfoKHR

See Also

VK_EXT_full_screen_exclusive, VK_KHR_win32_surface, 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.

Structure Chaining

Extends the structure

• SurfaceCapabilities2KHR

See Also

VK_EXT_full_screen_exclusive, Bool32, StructureType

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

Description

• FULL_SCREEN_EXCLUSIVE_DEFAULT_EXT specifies that the implementation should determine the appropriate full-screen method by whatever means it deems appropriate.

• FULL_SCREEN_EXCLUSIVE_ALLOWED_EXT specifies that the implementation may use full-screen exclusive mechanisms when available. Such mechanisms may result in better performance and/or the availability of different presentation capabilities, but may require a more disruptive transition during swapchain initialization, first presentation and/or destruction.

• FULL_SCREEN_EXCLUSIVE_DISALLOWED_EXT specifies that the implementation should avoid using full-screen mechanisms which rely on disruptive transitions.

• FULL_SCREEN_EXCLUSIVE_APPLICATION_CONTROLLED_EXT specifies that the application will manage full-screen exclusive mode by using the acquireFullScreenExclusiveModeEXT and releaseFullScreenExclusiveModeEXT commands.

See Also

VK_EXT_full_screen_exclusive, 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

VK_DEFINE_NON_DISPATCHABLE_HANDLE, VK_KHR_surface, PhysicalDeviceSurfaceInfo2KHR, SwapchainCreateInfoKHR, createAndroidSurfaceKHR, createDirectFBSurfaceEXT, createDisplayPlaneSurfaceKHR, createHeadlessSurfaceEXT, createIOSSurfaceMVK, createImagePipeSurfaceFUCHSIA, createMacOSSurfaceMVK, createMetalSurfaceEXT, createScreenSurfaceQNX, createStreamDescriptorSurfaceGGP, vkCreateSurfaceOHOS, vkCreateUbmSurfaceSEC, 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.

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 released 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 application can also release the acquisition of the image through releaseSwapchainImagesKHR, if the image is not in use by the device, and skip the present operation.

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

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

VK_DEFINE_NON_DISPATCHABLE_HANDLE, VK_KHR_swapchain, AcquireNextImageInfoKHR, BindImageMemorySwapchainInfoKHR, ImageSwapchainCreateInfoKHR, PastPresentationTimingInfoEXT, PresentInfoKHR, ReleaseSwapchainImagesInfoKHR, SwapchainCalibratedTimestampInfoEXT, SwapchainCreateInfoKHR, acquireFullScreenExclusiveModeEXT, acquireNextImageKHR, createSharedSwapchainsKHR, createSwapchainKHR, destroySwapchainKHR, getLatencyTimingsNV, getPastPresentationTimingGOOGLE, getRefreshCycleDurationGOOGLE, getSwapchainCounterEXT, getSwapchainImagesKHR, getSwapchainStatusKHR, getSwapchainTimeDomainPropertiesEXT, getSwapchainTimingPropertiesEXT, latencySleepNV, queuePresentKHR, releaseFullScreenExclusiveModeEXT, setHdrMetadataEXT, setLatencyMarkerNV, setLatencySleepModeNV, setLocalDimmingAMD, setSwapchainPresentTimingQueueSizeEXT, waitForPresent2KHR, waitForPresentKHR

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

• If surface is not VK_NULL_HANDLE, and the VK_GOOGLE_surfaceless_query extension is not enabled, surface must be a valid SurfaceKHR handle

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, SurfaceFullScreenExclusiveWin32InfoEXT, or SurfacePresentModeKHR

• The sType value of each structure in the pNext chain must be unique

See Also

VK_KHR_get_surface_capabilities2, StructureType, SurfaceKHR, getDeviceGroupSurfacePresentModes2EXT, getPhysicalDeviceSurfaceCapabilities2KHR, getPhysicalDeviceSurfaceFormats2KHR, getPhysicalDeviceSurfacePresentModes2EXT

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

VkDeviceGroupPresentModeFlagBitsKHR - Bitmask specifying supported device group present modes

Description

• DEVICE_GROUP_PRESENT_MODE_LOCAL_BIT_KHR specifies that any physical device with a presentation engine can present its own swapchain images.

• DEVICE_GROUP_PRESENT_MODE_REMOTE_BIT_KHR specifies that any physical device with a presentation engine can present swapchain images from any physical device in its presentMask.

• DEVICE_GROUP_PRESENT_MODE_SUM_BIT_KHR specifies that any physical device with a presentation engine can present the sum of swapchain images from any physical devices in its presentMask.

• DEVICE_GROUP_PRESENT_MODE_LOCAL_MULTI_DEVICE_BIT_KHR specifies that multiple physical devices with a presentation engine can each present their own swapchain images.

See Also

VK_KHR_device_group, VK_KHR_surface, VK_KHR_swapchain, VK_VERSION_1_1, DeviceGroupPresentInfoKHR, DeviceGroupPresentModeFlagsKHR