1// Copyright (c) 2014-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 5include::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 17This extension provides the API to enumerate displays and available modes on 18a 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 571) Which properties of a mode should be fixed in the mode info vs. 58settable in some other function when setting the mode? E.g., do we need to 59double the size of the mode pool to include both stereo and non-stereo 60modes? YUV and RGB scanout even if they both take RGB input images? BGR vs. 61RGB input? etc. 62 63*PROPOSED RESOLUTION*: Many modern displays support at most a handful of 64resolutions and timings natively. 65Other "`modes`" are expected to be supported using scaling hardware on the 66display engine or GPU. 67Other properties, such as rotation and mirroring should not require 68duplicating hardware modes just to express all combinations. 69Further, these properties may be implemented on a per-display or per-overlay 70granularity. 71 72To avoid the exponential growth of modes as mutable properties are added, as 73was the case with code:EGLConfig/WGL pixel formats/code:GLXFBConfig, this 74specification should separate out hardware properties and configurable state 75into separate objects. 76Modes and overlay planes will express capabilities of the hardware, while a 77separate structure will allow applications to configure scaling, rotation, 78mirroring, color keys, LUT values, alpha masks, etc. 79for a given swapchain independent of the mode in use. 80Constraints on these settings will be established by properties of the 81immutable objects. 82 83Note the resolution of this issue may affect issue 5 as well. 84 852) What properties of a display itself are useful? 86 87*PROPOSED RESOLUTION*: This issue is too broad. 88It was meant to prompt general discussion, but resolving this issue amounts 89to completing this specification. 90All interesting properties should be included. 91The issue will remain as a placeholder since removing it would make it hard 92to parse existing discussion notes that refer to issues by number. 93 943) How are multiple overlay planes within a display or mode enumerated? 95 96*PROPOSED RESOLUTION*: They are referred to by an index. 97Each display will report the number of overlay planes it contains. 98 994) Should swapchains be created relative to a mode or a display? 100 101*PROPOSED RESOLUTION*: When using this extension, swapchains are created 102relative to a mode and a plane. 103The mode implies the display object the swapchain will present to. 104If the specified mode is not the display's current mode, the new mode will 105be applied when the first image is presented to the swapchain, and the 106default operating system mode, if any, will be restored when the swapchain 107is destroyed. 108 1095) Should users query generic ranges from displays and construct their own 110modes explicitly using those constraints rather than querying a fixed set of 111modes (Most monitors only have one real "`mode`" these days, even though 112many support relatively arbitrary scaling, either on the monitor side or in 113the GPU display engine, making "`modes`" something of a relic/compatibility 114construct). 115 116*PROPOSED RESOLUTION*: Expose both. 117Display info structures will expose a set of predefined modes, as well as 118any attributes necessary to construct a customized mode. 119 1206) Is it fine if we return the display and display mode handles in the 121structure used to query their properties? 122 123*PROPOSED RESOLUTION*: Yes. 124 1257) Is there a possibility that not all displays of a device work with all of 126the present queues of a device? If yes, how do we determine which displays 127work with which present queues? 128 129*PROPOSED RESOLUTION*: No known hardware has such limitations, but 130determining such limitations is supported automatically using the existing 131`<<VK_KHR_surface>>` and `<<VK_KHR_swapchain>>` query mechanisms. 132 1338) Should all presentation need to be done relative to an overlay plane, or 134can a display mode + display be used alone to target an output? 135 136*PROPOSED RESOLUTION*: Require specifying a plane explicitly. 137 1389) Should displays have an associated window system display, such as an 139code:HDC or code:Display*? 140 141*PROPOSED RESOLUTION*: No. 142Displays are independent of any windowing system in use on the system. 143Further, neither code:HDC nor code:Display* refer to a physical display 144object. 145 14610) Are displays queried from a physical GPU or from a device instance? 147 148*PROPOSED RESOLUTION*: Developers prefer to query modes directly from the 149physical GPU so they can use display information as an input to their device 150selection algorithms prior to device creation. 151This avoids the need to create dummy device instances to enumerate displays. 152 153This preference must be weighed against the extra initialization that must 154be done by driver vendors prior to device instance creation to support this 155usage. 156 15711) Should displays and/or modes be dispatchable objects? If functions are 158to take displays, overlays, or modes as their first parameter, they must be 159dispatchable objects as defined in Khronos bug 13529. 160If they are not added to the list of dispatchable objects, functions 161operating on them must take some higher-level object as their first 162parameter. 163There is no performance case against making them dispatchable objects, but 164they would be the first extension objects to be dispatchable. 165 166*PROPOSED RESOLUTION*: Do not make displays or modes dispatchable. 167They will dispatch based on their associated physical device. 168 16912) Should hardware cursor capabilities be exposed? 170 171*PROPOSED RESOLUTION*: Defer. 172This could be a separate extension on top of the base WSI specs. 173 174ifdef::editing-notes[] 175[NOTE] 176.editing-note 177==== 178There appears to be a missing sentence for the first part of issue 13 here. 179==== 180endif::editing-notes[] 181 182if they are one physical display device to an end user, but may internally 183be implemented as two side-by-side displays using the same display engine 184(and sometimes cabling) resources as two physically separate display 185devices. 186 187*RESOLVED*: Tiled displays will appear as a single display object in this 188API. 189 19014) Should the raw EDID data be included in the display information? 191 192*RESOLVED*: No. 193A future extension could be added which reports the EDID if necessary. 194This may be complicated by the outcome of issue 13. 195 19615) Should min and max scaling factor capabilities of overlays be exposed? 197 198*RESOLVED*: Yes. 199This is exposed indirectly by allowing applications to query the min/max 200position and extent of the source and destination regions from which image 201contents are fetched by the display engine when using a particular mode and 202overlay pair. 203 20416) Should devices be able to expose planes that can be moved between 205displays? If so, how? 206 207*RESOLVED*: Yes. 208Applications can determine which displays a given plane supports using 209flink:vkGetDisplayPlaneSupportedDisplaysKHR. 210 21117) Should there be a way to destroy display modes? If so, does it support 212destroying "`built in`" modes? 213 214*RESOLVED*: Not in this extension. 215A future extension could add this functionality. 216 21718) What should the lifetime of display and built-in display mode objects 218be? 219 220*RESOLVED*: The lifetime of the instance. 221These objects cannot be destroyed. 222A future extension may be added to expose a way to destroy these objects 223and/or support display hotplug. 224 22519) Should persistent mode for smart panels be enabled/disabled at swapchain 226creation time, or on a per-present basis. 227 228*RESOLVED*: On a per-present basis. 229 230=== Examples 231 232[NOTE] 233.Note 234==== 235The example code for the `VK_KHR_display` and `<<VK_KHR_display_swapchain>>` 236extensions was removed from the appendix after revision 1.0.43. 237The display enumeration example code was ported to the cube demo that is 238shipped with the official Khronos SDK, and is being kept up-to-date in that 239location (see: 240https://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. 380