Package org.lwjgl.vulkan

Class EXTFullScreenExclusive

java.lang.Object

org.lwjgl.vulkan.EXTFullScreenExclusive

public class EXTFullScreenExclusive
extends java.lang.Object

This extension allows applications to set the policy for swapchain creation and presentation mechanisms relating to full-screen access. Implementations may be able to acquire exclusive access to a particular display for an application window that covers the whole screen. This can increase performance on some systems by bypassing composition, however it can also result in disruptive or expensive transitions in the underlying windowing system when a change occurs.

Applications can choose between explicitly disallowing or allowing this behavior, letting the implementation decide, or managing this mode of operation directly using the new AcquireFullScreenExclusiveModeEXT and ReleaseFullScreenExclusiveModeEXT commands.

Name String

VK_EXT_full_screen_exclusive

Extension Type

Device extension

Registered Extension Number

256

Revision

4

Extension and Version Dependencies

• Requires Vulkan 1.0
• Requires VK_KHR_get_physical_device_properties2
• Requires VK_KHR_surface
• Requires VK_KHR_get_surface_capabilities2
• Requires VK_KHR_swapchain

Contact

• James Jones cubanismo

Last Modified Date

2019-03-12

IP Status

No known IP claims.

Interactions and External Dependencies

• Interacts with VK_KHR_device_group, VK_KHR_win32_surface, and Vulkan 1.1

Contributors

• Hans-Kristian Arntzen, ARM
• Slawomir Grajewski, Intel
• Tobias Hector, AMD
• James Jones, NVIDIA
• Daniel Rakos, AMD
• Jeff Juliano, NVIDIA
• Joshua Schnarr, NVIDIA
• Aaron Hagan, AMD

Field Summary

Fields

Modifier and Type	Field	Description
static int	VK_ERROR_FULL_SCREEN_EXCLUSIVE_MODE_LOST_EXT	Extends VkResult.
static java.lang.String	VK_EXT_FULL_SCREEN_EXCLUSIVE_EXTENSION_NAME	The extension name.
static int	VK_EXT_FULL_SCREEN_EXCLUSIVE_SPEC_VERSION	The extension specification version.
static int	VK_FULL_SCREEN_EXCLUSIVE_ALLOWED_EXT VK_FULL_SCREEN_EXCLUSIVE_APPLICATION_CONTROLLED_EXT VK_FULL_SCREEN_EXCLUSIVE_DEFAULT_EXT VK_FULL_SCREEN_EXCLUSIVE_DISALLOWED_EXT	VkFullScreenExclusiveEXT - Hint values an application can specify affecting full-screen transition behavior
static int	VK_STRUCTURE_TYPE_SURFACE_CAPABILITIES_FULL_SCREEN_EXCLUSIVE_EXT VK_STRUCTURE_TYPE_SURFACE_FULL_SCREEN_EXCLUSIVE_INFO_EXT VK_STRUCTURE_TYPE_SURFACE_FULL_SCREEN_EXCLUSIVE_WIN32_INFO_EXT	Extends VkStructureType.

Method Summary

Modifier and Type	Method	Description
static int	nvkGetDeviceGroupSurfacePresentModes2EXT(VkDevice device, long pSurfaceInfo, long pModes)	Unsafe version of: GetDeviceGroupSurfacePresentModes2EXT
static int	nvkGetPhysicalDeviceSurfacePresentModes2EXT(VkPhysicalDevice physicalDevice, long pSurfaceInfo, long pPresentModeCount, long pPresentModes)	Unsafe version of: GetPhysicalDeviceSurfacePresentModes2EXT
static int	vkAcquireFullScreenExclusiveModeEXT(VkDevice device, long swapchain)	Acquire full-screen exclusive mode for a swapchain.
static int	vkGetDeviceGroupSurfacePresentModes2EXT(VkDevice device, VkPhysicalDeviceSurfaceInfo2KHR pSurfaceInfo, int[] pModes)	Array version of: GetDeviceGroupSurfacePresentModes2EXT
static int	vkGetDeviceGroupSurfacePresentModes2EXT(VkDevice device, VkPhysicalDeviceSurfaceInfo2KHR pSurfaceInfo, java.nio.IntBuffer pModes)	Query device group present capabilities for a surface.
static int	vkGetPhysicalDeviceSurfacePresentModes2EXT(VkPhysicalDevice physicalDevice, VkPhysicalDeviceSurfaceInfo2KHR pSurfaceInfo, int[] pPresentModeCount, int[] pPresentModes)	Array version of: GetPhysicalDeviceSurfacePresentModes2EXT
static int	vkGetPhysicalDeviceSurfacePresentModes2EXT(VkPhysicalDevice physicalDevice, VkPhysicalDeviceSurfaceInfo2KHR pSurfaceInfo, java.nio.IntBuffer pPresentModeCount, java.nio.IntBuffer pPresentModes)	Query supported presentation modes.
static int	vkReleaseFullScreenExclusiveModeEXT(VkDevice device, long swapchain)	Release full-screen exclusive mode from a swapchain.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

VK_EXT_FULL_SCREEN_EXCLUSIVE_SPEC_VERSION

The extension specification version.

VK_EXT_FULL_SCREEN_EXCLUSIVE_EXTENSION_NAME

The extension name.

VK_STRUCTURE_TYPE_SURFACE_FULL_SCREEN_EXCLUSIVE_INFO_EXT, VK_STRUCTURE_TYPE_SURFACE_CAPABILITIES_FULL_SCREEN_EXCLUSIVE_EXT

Extends VkStructureType.

Enum values:

• STRUCTURE_TYPE_SURFACE_FULL_SCREEN_EXCLUSIVE_INFO_EXT
• STRUCTURE_TYPE_SURFACE_CAPABILITIES_FULL_SCREEN_EXCLUSIVE_EXT

VK_ERROR_FULL_SCREEN_EXCLUSIVE_MODE_LOST_EXT

Extends VkResult.

VK_STRUCTURE_TYPE_SURFACE_FULL_SCREEN_EXCLUSIVE_WIN32_INFO_EXT

Extends VkStructureType.

VK_FULL_SCREEN_EXCLUSIVE_DEFAULT_EXT, VK_FULL_SCREEN_EXCLUSIVE_ALLOWED_EXT, VK_FULL_SCREEN_EXCLUSIVE_DISALLOWED_EXT, VK_FULL_SCREEN_EXCLUSIVE_APPLICATION_CONTROLLED_EXT

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

Description

• FULL_SCREEN_EXCLUSIVE_DEFAULT_EXT indicates the implementation should determine the appropriate full-screen method by whatever means it deems appropriate.
• FULL_SCREEN_EXCLUSIVE_ALLOWED_EXT indicates 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 indicates the implementation should avoid using full-screen mechanisms which rely on disruptive transitions.
• FULL_SCREEN_EXCLUSIVE_APPLICATION_CONTROLLED_EXT indicates the application will manage full-screen exclusive mode by using the AcquireFullScreenExclusiveModeEXT and ReleaseFullScreenExclusiveModeEXT commands.

See Also

VkSurfaceFullScreenExclusiveInfoEXT

Method Detail

nvkGetPhysicalDeviceSurfacePresentModes2EXT

public static int nvkGetPhysicalDeviceSurfacePresentModes2EXT(VkPhysicalDevice physicalDevice,
                                                              long pSurfaceInfo,
                                                              long pPresentModeCount,
                                                              long pPresentModes)

Unsafe version of: GetPhysicalDeviceSurfacePresentModes2EXT

Parameters:

pPresentModeCount - a pointer to an integer related to the number of presentation modes available or queried, as described below.

vkGetPhysicalDeviceSurfacePresentModes2EXT

public static int vkGetPhysicalDeviceSurfacePresentModes2EXT(VkPhysicalDevice physicalDevice,
                                                             VkPhysicalDeviceSurfaceInfo2KHR pSurfaceInfo,
                                                             java.nio.IntBuffer pPresentModeCount,
                                                             @Nullable
                                                             java.nio.IntBuffer pPresentModes)

Query supported presentation modes.

C Specification

Alternatively, to query the supported presentation modes for a surface combined with select other fixed swapchain creation parameters, call:

 VkResult vkGetPhysicalDeviceSurfacePresentModes2EXT(
     VkPhysicalDevice                            physicalDevice,
     const VkPhysicalDeviceSurfaceInfo2KHR*      pSurfaceInfo,
     uint32_t*                                   pPresentModeCount,
     VkPresentModeKHR*                           pPresentModes);

Description

vkGetPhysicalDeviceSurfacePresentModes2EXT behaves similarly to GetPhysicalDeviceSurfacePresentModesKHR, with the ability to specify extended inputs via chained input structures.

Valid Usage (Implicit)

• physicalDevice must be a valid VkPhysicalDevice handle
• pSurfaceInfo must be a valid pointer to a valid VkPhysicalDeviceSurfaceInfo2KHR 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 VkPresentModeKHR values

Return Codes

On success, this command returns

• SUCCESS
• INCOMPLETE

On failure, this command returns

• ERROR_OUT_OF_HOST_MEMORY
• ERROR_OUT_OF_DEVICE_MEMORY
• ERROR_SURFACE_LOST_KHR

See Also

VkPhysicalDeviceSurfaceInfo2KHR

Parameters:

physicalDevice - the physical device that will be associated with the swapchain to be created, as described for CreateSwapchainKHR.

pSurfaceInfo - points to an instance of the VkPhysicalDeviceSurfaceInfo2KHR structure, describing the surface and other fixed parameters that would be consumed by CreateSwapchainKHR.

pPresentModeCount - a pointer to an integer related to the number of presentation modes available or queried, as described below.

pPresentModes - either NULL or a pointer to an array of VkPresentModeKHR values, indicating the supported presentation modes.

vkAcquireFullScreenExclusiveModeEXT

public static int vkAcquireFullScreenExclusiveModeEXT(VkDevice device,
                                                      long swapchain)

Acquire full-screen exclusive mode for a swapchain.

C Specification

To acquire exclusive full-screen access for a swapchain, call:

 VkResult vkAcquireFullScreenExclusiveModeEXT(
     VkDevice                                    device,
     VkSwapchainKHR                              swapchain);

Valid Usage

• swapchain must not be in the retired state
• swapchain must be a swapchain created with an instance of VkSurfaceFullScreenExclusiveInfoEXT, 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 VkDevice handle
• swapchain must be a valid VkSwapchainKHR handle
• Both of device, and swapchain must have been created, allocated, or retrieved from the same VkInstance

Return Codes

On success, this command returns

• SUCCESS

On failure, this command returns

• ERROR_OUT_OF_HOST_MEMORY
• ERROR_OUT_OF_DEVICE_MEMORY
• ERROR_INITIALIZATION_FAILED
• ERROR_SURFACE_LOST_KHR

Parameters:

device - the device associated with swapchain.

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

vkReleaseFullScreenExclusiveModeEXT

public static int vkReleaseFullScreenExclusiveModeEXT(VkDevice device,
                                                      long swapchain)

Release full-screen exclusive mode from a swapchain.

C Specification

To release exclusive full-screen access from a swapchain, call:

 VkResult vkReleaseFullScreenExclusiveModeEXT(
     VkDevice                                    device,
     VkSwapchainKHR                              swapchain);

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

• swapchain must not be in the retired state
• swapchain must be a swapchain created with an instance of VkSurfaceFullScreenExclusiveInfoEXT, with fullScreenExclusive set to FULL_SCREEN_EXCLUSIVE_APPLICATION_CONTROLLED_EXT

Parameters:

device - the device associated with swapchain.

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

nvkGetDeviceGroupSurfacePresentModes2EXT

public static int nvkGetDeviceGroupSurfacePresentModes2EXT(VkDevice device,
                                                           long pSurfaceInfo,
                                                           long pModes)

Unsafe version of: GetDeviceGroupSurfacePresentModes2EXT

vkGetDeviceGroupSurfacePresentModes2EXT

public static int vkGetDeviceGroupSurfacePresentModes2EXT(VkDevice device,
                                                          VkPhysicalDeviceSurfaceInfo2KHR pSurfaceInfo,
                                                          java.nio.IntBuffer pModes)

Query device group present capabilities for a surface.

C Specification

Alternatively, to query the supported device group presentation modes for a surface combined with select other fixed swapchain creation parameters, call:

 VkResult vkGetDeviceGroupSurfacePresentModes2EXT(
     VkDevice                                    device,
     const VkPhysicalDeviceSurfaceInfo2KHR*      pSurfaceInfo,
     VkDeviceGroupPresentModeFlagsKHR*           pModes);

Description

vkGetDeviceGroupSurfacePresentModes2EXT behaves similarly to GetDeviceGroupSurfacePresentModesKHR, with the ability to specify extended inputs via chained input structures.

Valid Usage (Implicit)

• device must be a valid VkDevice handle
• pSurfaceInfo must be a valid pointer to a valid VkPhysicalDeviceSurfaceInfo2KHR structure
• pModes must be a valid pointer to a VkDeviceGroupPresentModeFlagsKHR value

Return Codes

On success, this command returns

• SUCCESS

On failure, this command returns

• ERROR_OUT_OF_HOST_MEMORY
• ERROR_OUT_OF_DEVICE_MEMORY
• ERROR_SURFACE_LOST_KHR

See Also

VkPhysicalDeviceSurfaceInfo2KHR

Parameters:

device - the logical device.

pSurfaceInfo - points to an instance of the VkPhysicalDeviceSurfaceInfo2KHR structure, describing the surface and other fixed parameters that would be consumed by vkCreateSwapchainKHR.

pModes - a pointer to a value of type VkDeviceGroupPresentModeFlagsKHR that is filled with the supported device group present modes for the surface.

vkGetPhysicalDeviceSurfacePresentModes2EXT

public static int vkGetPhysicalDeviceSurfacePresentModes2EXT(VkPhysicalDevice physicalDevice,
                                                             VkPhysicalDeviceSurfaceInfo2KHR pSurfaceInfo,
                                                             int[] pPresentModeCount,
                                                             @Nullable
                                                             int[] pPresentModes)

Array version of: GetPhysicalDeviceSurfacePresentModes2EXT

vkGetDeviceGroupSurfacePresentModes2EXT

public static int vkGetDeviceGroupSurfacePresentModes2EXT(VkDevice device,
                                                          VkPhysicalDeviceSurfaceInfo2KHR pSurfaceInfo,
                                                          int[] pModes)

Array version of: GetDeviceGroupSurfacePresentModes2EXT