Package org.lwjgl.vulkan

Class EXTFullScreenExclusive

java.lang.Object

org.lwjgl.vulkan.EXTFullScreenExclusive

public class EXTFullScreenExclusive
extends 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.

VK_EXT_full_screen_exclusive

Name String

VK_EXT_full_screen_exclusive

Extension Type

Device extension

Registered Extension Number

256

Revision

4

Extension and Version Dependencies

VK_KHR_get_physical_device_properties2 and VK_KHR_surface and VK_KHR_get_surface_capabilities2 and VK_KHR_swapchain

Contact

• James Jones cubanismo

Other Extension Metadata

Last Modified Date

2019-03-12

IP Status

No known IP claims.

Interactions and External Dependencies

• Interacts with Vulkan 1.1
• Interacts with VK_KHR_device_group
• Interacts with VK_KHR_win32_surface

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 final int	VK_ERROR_FULL_SCREEN_EXCLUSIVE_MODE_LOST_EXT	Extends VkResult.
static final String	VK_EXT_FULL_SCREEN_EXCLUSIVE_EXTENSION_NAME	The extension name.
static final int	VK_EXT_FULL_SCREEN_EXCLUSIVE_SPEC_VERSION	The extension specification version.
static final int	VK_FULL_SCREEN_EXCLUSIVE_ALLOWED_EXT	VkFullScreenExclusiveEXT - Hint values an application can specify affecting full-screen transition behavior
static final int	VK_FULL_SCREEN_EXCLUSIVE_APPLICATION_CONTROLLED_EXT	VkFullScreenExclusiveEXT - Hint values an application can specify affecting full-screen transition behavior
static final int	VK_FULL_SCREEN_EXCLUSIVE_DEFAULT_EXT	VkFullScreenExclusiveEXT - Hint values an application can specify affecting full-screen transition behavior
static final int	VK_FULL_SCREEN_EXCLUSIVE_DISALLOWED_EXT	VkFullScreenExclusiveEXT - Hint values an application can specify affecting full-screen transition behavior
static final int	VK_STRUCTURE_TYPE_SURFACE_CAPABILITIES_FULL_SCREEN_EXCLUSIVE_EXT	Extends VkStructureType.
static final int	VK_STRUCTURE_TYPE_SURFACE_FULL_SCREEN_EXCLUSIVE_INFO_EXT	Extends VkStructureType.
static final int	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, 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, IntBuffer pPresentModeCount, 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 Details

VK_EXT_FULL_SCREEN_EXCLUSIVE_SPEC_VERSION

public static final int VK_EXT_FULL_SCREEN_EXCLUSIVE_SPEC_VERSION

The extension specification version.

See Also:

• Constant Field Values

VK_EXT_FULL_SCREEN_EXCLUSIVE_EXTENSION_NAME

public static final String VK_EXT_FULL_SCREEN_EXCLUSIVE_EXTENSION_NAME

The extension name.

See Also:

• Constant Field Values

VK_STRUCTURE_TYPE_SURFACE_FULL_SCREEN_EXCLUSIVE_INFO_EXT

public static final int VK_STRUCTURE_TYPE_SURFACE_FULL_SCREEN_EXCLUSIVE_INFO_EXT

Extends VkStructureType.

Enum values:

• STRUCTURE_TYPE_SURFACE_FULL_SCREEN_EXCLUSIVE_INFO_EXT
• STRUCTURE_TYPE_SURFACE_CAPABILITIES_FULL_SCREEN_EXCLUSIVE_EXT

See Also:

• Constant Field Values

VK_STRUCTURE_TYPE_SURFACE_CAPABILITIES_FULL_SCREEN_EXCLUSIVE_EXT

public static final int 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

See Also:

• Constant Field Values

VK_ERROR_FULL_SCREEN_EXCLUSIVE_MODE_LOST_EXT

public static final int VK_ERROR_FULL_SCREEN_EXCLUSIVE_MODE_LOST_EXT

Extends VkResult.

See Also:

• Constant Field Values

VK_STRUCTURE_TYPE_SURFACE_FULL_SCREEN_EXCLUSIVE_WIN32_INFO_EXT

public static final int VK_STRUCTURE_TYPE_SURFACE_FULL_SCREEN_EXCLUSIVE_WIN32_INFO_EXT

Extends VkStructureType.

See Also:

• Constant Field Values

VK_FULL_SCREEN_EXCLUSIVE_DEFAULT_EXT

public static final int VK_FULL_SCREEN_EXCLUSIVE_DEFAULT_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

See Also:

• Constant Field Values

VK_FULL_SCREEN_EXCLUSIVE_ALLOWED_EXT

public static final int VK_FULL_SCREEN_EXCLUSIVE_ALLOWED_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

See Also:

• Constant Field Values

VK_FULL_SCREEN_EXCLUSIVE_DISALLOWED_EXT

public static final int VK_FULL_SCREEN_EXCLUSIVE_DISALLOWED_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

See Also:

• Constant Field Values

VK_FULL_SCREEN_EXCLUSIVE_APPLICATION_CONTROLLED_EXT

public static final int 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

See Also:

• Constant Field Values

Method Details

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,
 IntBuffer pPresentModeCount,
 @Nullable
 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

• If the VK_GOOGLE_surfaceless_query extension is not enabled, pSurfaceInfo→surface must be a valid VkSurfaceKHR handle
• If pSurfaceInfo→surface is not NULL_HANDLE, it must be supported by physicalDevice, as reported by GetPhysicalDeviceSurfaceSupportKHR or an equivalent platform-specific mechanism

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 - a pointer to a 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 a VkSurfaceFullScreenExclusiveInfoEXT 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 VkDevice handle
• swapchain must be a valid VkSwapchainKHR handle
• swapchain must have been created, allocated, or retrieved from device

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 a VkSurfaceFullScreenExclusiveInfoEXT structure, 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,
 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

• pSurfaceInfo→surface must be supported by all physical devices associated with device, as reported by GetPhysicalDeviceSurfaceSupportKHR or an equivalent platform-specific mechanism

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 - a pointer to a VkPhysicalDeviceSurfaceInfo2KHR structure describing the surface and other fixed parameters that would be consumed by CreateSwapchainKHR.

pModes - a pointer to a VkDeviceGroupPresentModeFlagsKHR in which the supported device group present modes for the surface are returned.

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