/ appendices / VK_KHR_display.txt
VK_KHR_display.txt
1 // Copyright (c) 2014-2019 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_KHR_display.txt[] 6 7 *Last Modified Date*:: 8 2017-03-13 9 *IP Status*:: 10 No known IP claims. 11 *Contributors*:: 12 - James Jones, NVIDIA 13 - Norbert Nopper, Freescale 14 - Jeff Vigil, Qualcomm 15 - Daniel Rakos, AMD 16 17 This extension provides the API to enumerate displays and available modes on 18 a given device. 19 20 === New Object Types 21 22 * slink:VkDisplayKHR 23 * slink:VkDisplayModeKHR 24 25 === New Enum Constants 26 27 * Extending elink:VkStructureType: 28 ** ename:VK_STRUCTURE_TYPE_DISPLAY_MODE_CREATE_INFO_KHR 29 ** ename:VK_STRUCTURE_TYPE_DISPLAY_SURFACE_CREATE_INFO_KHR 30 31 === New Enums 32 33 * elink:VkDisplayPlaneAlphaFlagBitsKHR 34 35 === New Structures 36 37 * slink:VkDisplayPropertiesKHR 38 * slink:VkDisplayModeParametersKHR 39 * slink:VkDisplayModePropertiesKHR 40 * slink:VkDisplayModeCreateInfoKHR 41 * slink:VkDisplayPlanePropertiesKHR 42 * slink:VkDisplayPlaneCapabilitiesKHR 43 * slink:VkDisplaySurfaceCreateInfoKHR 44 45 === New Functions 46 47 * flink:vkGetPhysicalDeviceDisplayPropertiesKHR 48 * flink:vkGetPhysicalDeviceDisplayPlanePropertiesKHR 49 * flink:vkGetDisplayPlaneSupportedDisplaysKHR 50 * flink:vkGetDisplayModePropertiesKHR 51 * flink:vkCreateDisplayModeKHR 52 * flink:vkGetDisplayPlaneCapabilitiesKHR 53 * flink:vkCreateDisplayPlaneSurfaceKHR 54 55 === Issues 56 57 1) Which properties of a mode should be fixed in the mode info vs. 58 settable in some other function when setting the mode? E.g., do we need to 59 double the size of the mode pool to include both stereo and non-stereo 60 modes? YUV and RGB scanout even if they both take RGB input images? BGR vs. 61 RGB input? etc. 62 63 *PROPOSED RESOLUTION*: Many modern displays support at most a handful of 64 resolutions and timings natively. 65 Other "`modes`" are expected to be supported using scaling hardware on the 66 display engine or GPU. 67 Other properties, such as rotation and mirroring should not require 68 duplicating hardware modes just to express all combinations. 69 Further, these properties may be implemented on a per-display or per-overlay 70 granularity. 71 72 To avoid the exponential growth of modes as mutable properties are added, as 73 was the case with code:EGLConfig/WGL pixel formats/code:GLXFBConfig, this 74 specification should separate out hardware properties and configurable state 75 into separate objects. 76 Modes and overlay planes will express capabilities of the hardware, while a 77 separate structure will allow applications to configure scaling, rotation, 78 mirroring, color keys, LUT values, alpha masks, etc. 79 for a given swapchain independent of the mode in use. 80 Constraints on these settings will be established by properties of the 81 immutable objects. 82 83 Note the resolution of this issue may affect issue 5 as well. 84 85 2) What properties of a display itself are useful? 86 87 *PROPOSED RESOLUTION*: This issue is too broad. 88 It was meant to prompt general discussion, but resolving this issue amounts 89 to completing this specification. 90 All interesting properties should be included. 91 The issue will remain as a placeholder since removing it would make it hard 92 to parse existing discussion notes that refer to issues by number. 93 94 3) How are multiple overlay planes within a display or mode enumerated? 95 96 *PROPOSED RESOLUTION*: They are referred to by an index. 97 Each display will report the number of overlay planes it contains. 98 99 4) Should swapchains be created relative to a mode or a display? 100 101 *PROPOSED RESOLUTION*: When using this extension, swapchains are created 102 relative to a mode and a plane. 103 The mode implies the display object the swapchain will present to. 104 If the specified mode is not the display's current mode, the new mode will 105 be applied when the first image is presented to the swapchain, and the 106 default operating system mode, if any, will be restored when the swapchain 107 is destroyed. 108 109 5) Should users query generic ranges from displays and construct their own 110 modes explicitly using those constraints rather than querying a fixed set of 111 modes (Most monitors only have one real "`mode`" these days, even though 112 many support relatively arbitrary scaling, either on the monitor side or in 113 the GPU display engine, making "`modes`" something of a relic/compatibility 114 construct). 115 116 *PROPOSED RESOLUTION*: Expose both. 117 Display info structures will expose a set of predefined modes, as well as 118 any attributes necessary to construct a customized mode. 119 120 6) Is it fine if we return the display and display mode handles in the 121 structure used to query their properties? 122 123 *PROPOSED RESOLUTION*: Yes. 124 125 7) Is there a possibility that not all displays of a device work with all of 126 the present queues of a device? If yes, how do we determine which displays 127 work with which present queues? 128 129 *PROPOSED RESOLUTION*: No known hardware has such limitations, but 130 determining such limitations is supported automatically using the existing 131 `<<VK_KHR_surface>>` and `<<VK_KHR_swapchain>>` query mechanisms. 132 133 8) Should all presentation need to be done relative to an overlay plane, or 134 can a display mode + display be used alone to target an output? 135 136 *PROPOSED RESOLUTION*: Require specifying a plane explicitly. 137 138 9) Should displays have an associated window system display, such as an 139 code:HDC or code:Display*? 140 141 *PROPOSED RESOLUTION*: No. 142 Displays are independent of any windowing system in use on the system. 143 Further, neither code:HDC nor code:Display* refer to a physical display 144 object. 145 146 10) Are displays queried from a physical GPU or from a device instance? 147 148 *PROPOSED RESOLUTION*: Developers prefer to query modes directly from the 149 physical GPU so they can use display information as an input to their device 150 selection algorithms prior to device creation. 151 This avoids the need to create dummy device instances to enumerate displays. 152 153 This preference must be weighed against the extra initialization that must 154 be done by driver vendors prior to device instance creation to support this 155 usage. 156 157 11) Should displays and/or modes be dispatchable objects? If functions are 158 to take displays, overlays, or modes as their first parameter, they must be 159 dispatchable objects as defined in Khronos bug 13529. 160 If they are not added to the list of dispatchable objects, functions 161 operating on them must take some higher-level object as their first 162 parameter. 163 There is no performance case against making them dispatchable objects, but 164 they would be the first extension objects to be dispatchable. 165 166 *PROPOSED RESOLUTION*: Do not make displays or modes dispatchable. 167 They will dispatch based on their associated physical device. 168 169 12) Should hardware cursor capabilities be exposed? 170 171 *PROPOSED RESOLUTION*: Defer. 172 This could be a separate extension on top of the base WSI specs. 173 174 ifdef::editing-notes[] 175 [NOTE] 176 .editing-note 177 ==== 178 There appears to be a missing sentence for the first part of issue 13 here. 179 ==== 180 endif::editing-notes[] 181 182 if they are one physical display device to an end user, but may internally 183 be implemented as two side-by-side displays using the same display engine 184 (and sometimes cabling) resources as two physically separate display 185 devices. 186 187 *RESOLVED*: Tiled displays will appear as a single display object in this 188 API. 189 190 14) Should the raw EDID data be included in the display information? 191 192 *RESOLVED*: No. 193 A future extension could be added which reports the EDID if necessary. 194 This may be complicated by the outcome of issue 13. 195 196 15) Should min and max scaling factor capabilities of overlays be exposed? 197 198 *RESOLVED*: Yes. 199 This is exposed indirectly by allowing applications to query the min/max 200 position and extent of the source and destination regions from which image 201 contents are fetched by the display engine when using a particular mode and 202 overlay pair. 203 204 16) Should devices be able to expose planes that can be moved between 205 displays? If so, how? 206 207 *RESOLVED*: Yes. 208 Applications can determine which displays a given plane supports using 209 flink:vkGetDisplayPlaneSupportedDisplaysKHR. 210 211 17) Should there be a way to destroy display modes? If so, does it support 212 destroying "`built in`" modes? 213 214 *RESOLVED*: Not in this extension. 215 A future extension could add this functionality. 216 217 18) What should the lifetime of display and built-in display mode objects 218 be? 219 220 *RESOLVED*: The lifetime of the instance. 221 These objects cannot be destroyed. 222 A future extension may be added to expose a way to destroy these objects 223 and/or support display hotplug. 224 225 19) Should persistent mode for smart panels be enabled/disabled at swapchain 226 creation time, or on a per-present basis. 227 228 *RESOLVED*: On a per-present basis. 229 230 === Examples 231 232 [NOTE] 233 .Note 234 ==== 235 The example code for the `VK_KHR_display` and `<<VK_KHR_display_swapchain>>` 236 extensions was removed from the appendix after revision 1.0.43. 237 The display enumeration example code was ported to the cube demo that is 238 shipped with the official Khronos SDK, and is being kept up-to-date in that 239 location (see: 240 https://github.com/KhronosGroup/Vulkan-Tools/blob/master/cube/cube.c). 241 ==== 242 243 === Version History 244 245 * Revision 1, 2015-02-24 (James Jones) 246 - Initial draft 247 248 * Revision 2, 2015-03-12 (Norbert Nopper) 249 - Added overlay enumeration for a display. 250 251 * Revision 3, 2015-03-17 (Norbert Nopper) 252 - Fixed typos and namings as discussed in Bugzilla. 253 - Reordered and grouped functions. 254 - Added functions to query count of display, mode and overlay. 255 - Added native display handle, which is maybe needed on some platforms to 256 create a native Window. 257 258 * Revision 4, 2015-03-18 (Norbert Nopper) 259 - Removed primary and virtualPostion members (see comment of James Jones 260 in Bugzilla). 261 - Added native overlay handle to info structure. 262 - Replaced , with ; in struct. 263 264 * Revision 6, 2015-03-18 (Daniel Rakos) 265 - Added WSI extension suffix to all items. 266 - Made the whole API more "Vulkanish". 267 - Replaced all functions with a single vkGetDisplayInfoKHR function to 268 better match the rest of the API. 269 - Made the display, display mode, and overlay objects be first class 270 objects, not subclasses of VkBaseObject as they do not support the 271 common functions anyways. 272 - Renamed *Info structures to *Properties. 273 - Removed overlayIndex field from VkOverlayProperties as there is an 274 implicit index already as a result of moving to a "Vulkanish" API. 275 - Displays are not get through device, but through physical GPU to match 276 the rest of the Vulkan API. 277 Also this is something ISVs explicitly requested. 278 - Added issue (6) and (7). 279 280 * Revision 7, 2015-03-25 (James Jones) 281 - Added an issues section 282 - Added rotation and mirroring flags 283 284 * Revision 8, 2015-03-25 (James Jones) 285 - Combined the duplicate issues sections introduced in last change. 286 - Added proposed resolutions to several issues. 287 288 * Revision 9, 2015-04-01 (Daniel Rakos) 289 - Rebased extension against Vulkan 0.82.0 290 291 * Revision 10, 2015-04-01 (James Jones) 292 - Added issues (10) and (11). 293 - Added more straw-man issue resolutions, and cleaned up the proposed 294 resolution for issue (4). 295 - Updated the rotation and mirroring enums to have proper bitmask 296 semantics. 297 298 * Revision 11, 2015-04-15 (James Jones) 299 - Added proposed resolution for issues (1) and (2). 300 - Added issues (12), (13), (14), and (15) 301 - Removed pNativeHandle field from overlay structure. 302 - Fixed small compilation errors in example code. 303 304 * Revision 12, 2015-07-29 (James Jones) 305 - Rewrote the guts of the extension against the latest WSI swapchain 306 specifications and the latest Vulkan API. 307 - Address overlay planes by their index rather than an object handle and 308 refer to them as "planes" rather than "overlays" to make it slightly 309 clearer that even a display with no "overlays" still has at least one 310 base "plane" that images can be displayed on. 311 - Updated most of the issues. 312 - Added an "extension type" section to the specification header. 313 - Re-used the VK_EXT_KHR_surface surface transform enumerations rather 314 than redefining them here. 315 - Updated the example code to use the new semantics. 316 317 * Revision 13, 2015-08-21 (Ian Elliott) 318 - Renamed this extension and all of its enumerations, types, functions, 319 etc. 320 This makes it compliant with the proposed standard for Vulkan 321 extensions. 322 - Switched from "revision" to "version", including use of the 323 VK_MAKE_VERSION macro in the header file. 324 325 * Revision 14, 2015-09-01 (James Jones) 326 - Restore single-field revision number. 327 328 * Revision 15, 2015-09-08 (James Jones) 329 - Added alpha flags enum. 330 - Added premultiplied alpha support. 331 332 * Revision 16, 2015-09-08 (James Jones) 333 - Added description section to the spec. 334 - Added issues 16 - 18. 335 336 * Revision 17, 2015-10-02 (James Jones) 337 - Planes are now a property of the entire device rather than individual 338 displays. 339 This allows planes to be moved between multiple displays on devices 340 that support it. 341 - Added a function to create a VkSurfaceKHR object describing a display 342 plane and mode to align with the new per-platform surface creation 343 conventions. 344 - Removed detailed mode timing data. 345 It was agreed that the mode extents and refresh rate are sufficient for 346 current use cases. 347 Other information could be added back2 in as an extension if it is 348 needed in the future. 349 - Added support for smart/persistent/buffered display devices. 350 351 * Revision 18, 2015-10-26 (Ian Elliott) 352 - Renamed from VK_EXT_KHR_display to VK_KHR_display. 353 354 * Revision 19, 2015-11-02 (James Jones) 355 - Updated example code to match revision 17 changes. 356 357 * Revision 20, 2015-11-03 (Daniel Rakos) 358 - Added allocation callbacks to creation functions. 359 360 * Revision 21, 2015-11-10 (Jesse Hall) 361 - Added VK_DISPLAY_PLANE_ALPHA_OPAQUE_BIT_KHR, and use 362 VkDisplayPlaneAlphaFlagBitsKHR for 363 VkDisplayPlanePropertiesKHR::alphaMode instead of 364 VkDisplayPlaneAlphaFlagsKHR, since it only represents one mode. 365 - Added reserved flags bitmask to VkDisplayPlanePropertiesKHR. 366 - Use VkSurfaceTransformFlagBitsKHR instead of obsolete 367 VkSurfaceTransformKHR. 368 - Renamed vkGetDisplayPlaneSupportedDisplaysKHR parameters for clarity. 369 370 * Revision 22, 2015-12-18 (James Jones) 371 - Added missing "planeIndex" parameter to 372 vkGetDisplayPlaneSupportedDisplaysKHR() 373 374 * Revision 23, 2017-03-13 (James Jones) 375 - Closed all remaining issues. 376 The specification and implementations have been shipping with the 377 proposed resolutions for some time now. 378 - Removed the sample code and noted it has been integrated into the 379 official Vulkan SDK cube demo.