1  // Copyright (c) 2018 Khronos Group. This work is licensed under a
  2  // Creative Commons Attribution 4.0 International License; see
  3  // http://creativecommons.org/licenses/by/4.0/
  4  
  5  include::meta/VK_EXT_full_screen_exclusive.txt[]
  6  
  7  *Last Modified Date*::
  8      2019-03-12
  9  *IP Status*::
 10      No known IP claims.
 11  *Interactions and External Dependencies*::
 12    - Interacts with VK_KHR_device_group, VK_KHR_win32_surface, and Vulkan 1.1
 13  *Contributors*::
 14    - Hans-Kristian Arntzen, ARM
 15    - Slawomir Grajewski, Intel
 16    - Tobias Hector, AMD
 17    - James Jones, NVIDIA
 18    - Daniel Rakos, AMD
 19    - Jeff Juliano, NVIDIA
 20    - Joshua Schnarr, NVIDIA
 21    - Aaron Hagan, AMD
 22  
 23  This extension allows applications to set the policy for swapchain creation
 24  and presentation mechanisms relating to full-screen access.
 25  Implementations may be able to acquire exclusive access to a particular
 26  display for an application window that covers the whole screen.
 27  This can increase performance on some systems by bypassing composition,
 28  however it can also result in disruptive or expensive transitions in the
 29  underlying windowing system when a change occurs.
 30  
 31  Applications can choose between explicitly disallowing or allowing this
 32  behavior, letting the implementation decide, or managing this mode of
 33  operation directly using the new flink:vkAcquireFullScreenExclusiveModeEXT
 34  and flink:vkReleaseFullScreenExclusiveModeEXT commands.
 35  
 36  === New Enum Constants
 37  
 38    * Extending elink:VkResult
 39    ** ename:VK_ERROR_FULL_SCREEN_EXCLUSIVE_MODE_LOST_EXT
 40    * Extending elink:VkStructureType
 41    ** ename:VK_STRUCTURE_TYPE_SURFACE_FULL_SCREEN_EXCLUSIVE_INFO_EXT
 42    ** ename:VK_STRUCTURE_TYPE_SURFACE_CAPABILITIES_FULL_SCREEN_EXCLUSIVE_EXT
 43  ifdef::VK_KHR_win32_surface[]
 44    ** ename:VK_STRUCTURE_TYPE_SURFACE_FULL_SCREEN_EXCLUSIVE_WIN32_INFO_EXT
 45  endif::VK_KHR_win32_surface[]
 46  
 47  === New Enums
 48  
 49    * elink:VkFullScreenExclusiveEXT
 50  
 51  === New Structures
 52  
 53    * slink:VkSurfaceFullScreenExclusiveInfoEXT
 54    * slink:VkSurfaceCapabilitiesFullScreenExclusiveEXT
 55  ifdef::VK_KHR_win32_surface[]
 56    * slink:VkSurfaceFullScreenExclusiveWin32InfoEXT
 57  endif::VK_KHR_win32_surface[]
 58  
 59  === New Functions
 60  
 61    * flink:vkGetPhysicalDeviceSurfacePresentModes2EXT
 62    * flink:vkGetDeviceGroupSurfacePresentModes2EXT
 63    * flink:vkAcquireFullScreenExclusiveModeEXT
 64    * flink:vkReleaseFullScreenExclusiveModeEXT
 65  
 66  === Issues
 67  
 68  1) What should the extension & flag be called?
 69  
 70  RESOLVED: VK_EXT_full_screen_exclusive.
 71  
 72  Other options considered (prior to the app-controlled mode) were:
 73  
 74    * VK_EXT_smooth_fullscreen_transition
 75    * VK_EXT_fullscreen_behavior
 76    * VK_EXT_fullscreen_preference
 77    * VK_EXT_fullscreen_hint
 78    * VK_EXT_fast_fullscreen_transition
 79    * VK_EXT_avoid_fullscreen_exclusive
 80  
 81  2) Do we need more than a boolean toggle?
 82  
 83  RESOLVED: Yes.
 84  
 85  Using an enum with default/allowed/disallowed/app-controlled enables
 86  applications to accept driver default behavior, specifically override it in
 87  either direction without implying the driver is ever required to use
 88  full-screen exclusive mechanisms, or manage this mode explicitly.
 89  
 90  3) Should this be a KHR or EXT extension?
 91  
 92  RESOLVED: EXT, in order to allow it to be shipped faster.
 93  
 94  4) Can the fullscreen hint affect the surface capabilities, and if so,
 95      should the hint also be specified as input when querying the surface
 96      capabilities?
 97  
 98  RESOLVED: Yes on both accounts.
 99  
100  While the hint does not guarantee a particular fullscreen mode will be used
101  when the swapchain is created, it can sometimes imply particular modes will
102  NOT be used.
103  If the driver determines that it will opt-out of using a particular mode
104  based on the policy, and knows it can only support certain capabilities if
105  that mode is used, it would be confusing at best to the application to
106  report those capabilities in such cases.
107  Not allowing implementations to report this state to applications could
108  result in situations where applications are unable to determine why
109  swapchain creation fails when they specify certain hint values, which could
110  result in never- terminating surface creation loops.
111  
112  5) Should full-screen be one word or two?
113  
114  RESOLVED: Two words.
115  
116  "Fullscreen" is not in my dictionary, and web searches did not turn up
117  definitive proof that it is a colloquially accepted compound word.
118  Documentation for the corresponding Windows API mechanisms dithers.
119  The text consistently uses a hyphen, but none-the-less, there is a
120  SetFullscreenState method in the DXGI swapchain object.
121  Given this inconclusive external guidance, it is best to adhere to the
122  Vulkan style guidelines and avoid inventing new compound words.
123  
124  === Version History
125  
126   * Revision 4, 2019-03-12 (Tobias Hector)
127     - Added application-controlled mode, and related functions
128     - Tidied up appendix
129  
130   * Revision 3, 2019-01-03 (James Jones)
131     - Renamed to VK_EXT_full_screen_exclusive
132     - Made related adjustments to the tri-state enumerant names.
133  
134   * Revision 2, 2018-11-27 (James Jones)
135     - Renamed to VK_KHR_fullscreen_behavior
136     - Switched from boolean flag to tri-state enum
137  
138   * Revision 1, 2018-11-06 (James Jones)
139     - Internal revision