Vulkan-Docs/appendices/VK_EXT_full_screen_exclusiv...

// Copyright (c) 2018 Khronos Group. This work is licensed under a
// Creative Commons Attribution 4.0 International License; see
// http://creativecommons.org/licenses/by/4.0/

include::meta/VK_EXT_full_screen_exclusive.txt[]

*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

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 flink:vkAcquireFullScreenExclusiveModeEXT
and flink:vkReleaseFullScreenExclusiveModeEXT commands.

=== New Enum Constants

  * Extending elink:VkResult
  ** ename:VK_ERROR_FULL_SCREEN_EXCLUSIVE_MODE_LOST_EXT
  * Extending elink:VkStructureType
  ** ename:VK_STRUCTURE_TYPE_SURFACE_FULL_SCREEN_EXCLUSIVE_INFO_EXT
  ** ename:VK_STRUCTURE_TYPE_SURFACE_CAPABILITIES_FULL_SCREEN_EXCLUSIVE_EXT
ifdef::VK_KHR_win32_surface[]
  ** ename:VK_STRUCTURE_TYPE_SURFACE_FULL_SCREEN_EXCLUSIVE_WIN32_INFO_EXT
endif::VK_KHR_win32_surface[]

=== New Enums

  * elink:VkFullScreenExclusiveEXT

=== New Structures

  * slink:VkSurfaceFullScreenExclusiveInfoEXT
  * slink:VkSurfaceCapabilitiesFullScreenExclusiveEXT
ifdef::VK_KHR_win32_surface[]
  * slink:VkSurfaceFullScreenExclusiveWin32InfoEXT
endif::VK_KHR_win32_surface[]

=== New Functions

  * flink:vkGetPhysicalDeviceSurfacePresentModes2EXT
  * flink:vkGetDeviceGroupSurfacePresentModes2EXT
  * flink:vkAcquireFullScreenExclusiveModeEXT
  * flink:vkReleaseFullScreenExclusiveModeEXT

=== Issues

1) What should the extension & flag be called?

RESOLVED: VK_EXT_full_screen_exclusive.

Other options considered (prior to the app-controlled mode) were:

  * VK_EXT_smooth_fullscreen_transition
  * VK_EXT_fullscreen_behavior
  * VK_EXT_fullscreen_preference
  * VK_EXT_fullscreen_hint
  * VK_EXT_fast_fullscreen_transition
  * VK_EXT_avoid_fullscreen_exclusive

2) Do we need more than a boolean toggle?

RESOLVED: Yes.

Using an enum with default/allowed/disallowed/app-controlled enables
applications to accept driver default behavior, specifically override it in
either direction without implying the driver is ever required to use
full-screen exclusive mechanisms, or manage this mode explicitly.

3) Should this be a KHR or EXT extension?

RESOLVED: EXT, in order to allow it to be shipped faster.

4) Can the fullscreen hint affect the surface capabilities, and if so,
    should the hint also be specified as input when querying the surface
    capabilities?

RESOLVED: Yes on both accounts.

While the hint does not guarantee a particular fullscreen mode will be used
when the swapchain is created, it can sometimes imply particular modes will
NOT be used.
If the driver determines that it will opt-out of using a particular mode
based on the policy, and knows it can only support certain capabilities if
that mode is used, it would be confusing at best to the application to
report those capabilities in such cases.
Not allowing implementations to report this state to applications could
result in situations where applications are unable to determine why
swapchain creation fails when they specify certain hint values, which could
result in never- terminating surface creation loops.

5) Should full-screen be one word or two?

RESOLVED: Two words.

"Fullscreen" is not in my dictionary, and web searches did not turn up
definitive proof that it is a colloquially accepted compound word.
Documentation for the corresponding Windows API mechanisms dithers.
The text consistently uses a hyphen, but none-the-less, there is a
SetFullscreenState method in the DXGI swapchain object.
Given this inconclusive external guidance, it is best to adhere to the
Vulkan style guidelines and avoid inventing new compound words.

=== Version History

 * Revision 4, 2019-03-12 (Tobias Hector)
   - Added application-controlled mode, and related functions
   - Tidied up appendix

 * Revision 3, 2019-01-03 (James Jones)
   - Renamed to VK_EXT_full_screen_exclusive
   - Made related adjustments to the tri-state enumerant names.

 * Revision 2, 2018-11-27 (James Jones)
   - Renamed to VK_KHR_fullscreen_behavior
   - Switched from boolean flag to tri-state enum

 * Revision 1, 2018-11-06 (James Jones)
   - Internal revision
Change log for March 18, 2019 Vulkan 1.1.104 spec update: * Update release number to 104. Public Issues: * Remove the incorrect line from "`Initial`" to "`Invalid`" state in the <<commandbuffer-lifecycle-diagram, Lifecycle of a command buffer>> diagram (public issue 881). * Add Fuchsia platform to <<boilerplate-wsi-header-table, Window System Extensions and Headers>> table (public pull request 933). * Change the type of slink:VkBufferDeviceAddressCreateInfoEXT::pname:deviceAddress from basetype:VkDeviceSize to basetype:VkDeviceAddress. These are both typedefs of code:uint64_t, so it is an ABI-compatible change (public issue 934). Internal Issues: * Remove generated header files and update the CI tests to build a copy of the headers for use by the hpp-generate / hpp-compile CI stages. Targets to generate the headers will not be removed, but keeping these generated files in the repository increased the frequency of conflicts between branches when merging to master (internal issue 745). * Reword "`undefined: behavior if action" to "`must: not do action`" in the places the old terminology was used, and add a new <<writing-undefined, Describing Undefined Behavior>> section of the style guide to explain how to write such language in the future (internal issue 1579). * Move almost all Python scripts into the toplevel `scripts/` directory. Apply extensive internal edits to clean up and simplify the scripts, and try to follow PEP8 guidelines. Generalize the scripts with the use of a Conventions object controlling many aspects of output generation, to enable their use in other Khronos projects with similar requirements. Autogenerate extension interface refpages (these are experimental and may be retired going forward). New Extensions: * `VK_AMD_display_native_hdr` * `VK_EXT_full_screen_exclusive` (internal issue 1439) * `VK_EXT_host_query_reset` * `VK_EXT_pipeline_creation_feedback` (internal issue 1560) * `VK_KHR_surface_protected_capabilities` (internal issue 1520) 2019-03-17 13:05:46 +00:00			`// Copyright (c) 2018 Khronos Group. This work is licensed under a`
			`// Creative Commons Attribution 4.0 International License; see`
			`// http://creativecommons.org/licenses/by/4.0/`

			`include::meta/VK_EXT_full_screen_exclusive.txt[]`

			`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`

			`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 flink:vkAcquireFullScreenExclusiveModeEXT`
			`and flink:vkReleaseFullScreenExclusiveModeEXT commands.`

			`=== New Enum Constants`

			`* Extending elink:VkResult`
			`** ename:VK_ERROR_FULL_SCREEN_EXCLUSIVE_MODE_LOST_EXT`
			`* Extending elink:VkStructureType`
			`** ename:VK_STRUCTURE_TYPE_SURFACE_FULL_SCREEN_EXCLUSIVE_INFO_EXT`
			`** ename:VK_STRUCTURE_TYPE_SURFACE_CAPABILITIES_FULL_SCREEN_EXCLUSIVE_EXT`
			`ifdef::VK_KHR_win32_surface[]`
			`** ename:VK_STRUCTURE_TYPE_SURFACE_FULL_SCREEN_EXCLUSIVE_WIN32_INFO_EXT`
			`endif::VK_KHR_win32_surface[]`

			`=== New Enums`

			`* elink:VkFullScreenExclusiveEXT`

			`=== New Structures`

			`* slink:VkSurfaceFullScreenExclusiveInfoEXT`
			`* slink:VkSurfaceCapabilitiesFullScreenExclusiveEXT`
			`ifdef::VK_KHR_win32_surface[]`
			`* slink:VkSurfaceFullScreenExclusiveWin32InfoEXT`
			`endif::VK_KHR_win32_surface[]`

			`=== New Functions`

			`* flink:vkGetPhysicalDeviceSurfacePresentModes2EXT`
			`* flink:vkGetDeviceGroupSurfacePresentModes2EXT`
			`* flink:vkAcquireFullScreenExclusiveModeEXT`
			`* flink:vkReleaseFullScreenExclusiveModeEXT`

			`=== Issues`

			`1) What should the extension & flag be called?`

			`RESOLVED: VK_EXT_full_screen_exclusive.`

			`Other options considered (prior to the app-controlled mode) were:`

			`* VK_EXT_smooth_fullscreen_transition`
			`* VK_EXT_fullscreen_behavior`
			`* VK_EXT_fullscreen_preference`
			`* VK_EXT_fullscreen_hint`
			`* VK_EXT_fast_fullscreen_transition`
			`* VK_EXT_avoid_fullscreen_exclusive`

			`2) Do we need more than a boolean toggle?`

			`RESOLVED: Yes.`

			`Using an enum with default/allowed/disallowed/app-controlled enables`
			`applications to accept driver default behavior, specifically override it in`
			`either direction without implying the driver is ever required to use`
			`full-screen exclusive mechanisms, or manage this mode explicitly.`

			`3) Should this be a KHR or EXT extension?`

			`RESOLVED: EXT, in order to allow it to be shipped faster.`

			`4) Can the fullscreen hint affect the surface capabilities, and if so,`
			`should the hint also be specified as input when querying the surface`
			`capabilities?`

			`RESOLVED: Yes on both accounts.`

			`While the hint does not guarantee a particular fullscreen mode will be used`
			`when the swapchain is created, it can sometimes imply particular modes will`
			`NOT be used.`
			`If the driver determines that it will opt-out of using a particular mode`
			`based on the policy, and knows it can only support certain capabilities if`
			`that mode is used, it would be confusing at best to the application to`
			`report those capabilities in such cases.`
			`Not allowing implementations to report this state to applications could`
			`result in situations where applications are unable to determine why`
			`swapchain creation fails when they specify certain hint values, which could`
			`result in never- terminating surface creation loops.`

			`5) Should full-screen be one word or two?`

			`RESOLVED: Two words.`

			`"Fullscreen" is not in my dictionary, and web searches did not turn up`
			`definitive proof that it is a colloquially accepted compound word.`
			`Documentation for the corresponding Windows API mechanisms dithers.`
			`The text consistently uses a hyphen, but none-the-less, there is a`
			`SetFullscreenState method in the DXGI swapchain object.`
			`Given this inconclusive external guidance, it is best to adhere to the`
			`Vulkan style guidelines and avoid inventing new compound words.`

			`=== Version History`

			`* Revision 4, 2019-03-12 (Tobias Hector)`
			`- Added application-controlled mode, and related functions`
			`- Tidied up appendix`

			`* Revision 3, 2019-01-03 (James Jones)`
			`- Renamed to VK_EXT_full_screen_exclusive`
			`- Made related adjustments to the tri-state enumerant names.`

			`* Revision 2, 2018-11-27 (James Jones)`
			`- Renamed to VK_KHR_fullscreen_behavior`
			`- Switched from boolean flag to tri-state enum`

			`* Revision 1, 2018-11-06 (James Jones)`
			`- Internal revision`