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 5[[display,display]] 6 7== Presenting Directly to Display Devices 8 9In some environments applications can: also present Vulkan rendering 10directly to display devices without using an intermediate windowing system. 11This can: be useful for embedded applications, or implementing the 12rendering/presentation backend of a windowing system using Vulkan. 13The `VK_KHR_display` extension provides the functionality necessary to 14enumerate display devices and create sname:VkSurfaceKHR objects that target 15displays. 16 17 18=== Display Enumeration 19 20[open,refpage='VkDisplayKHR',desc='Opaque handle to a display object',type='handles'] 21-- 22 23Displays are represented by sname:VkDisplayKHR handles: 24 25include::../../api/handles/VkDisplayKHR.txt[] 26 27-- 28 29[open,refpage='vkGetPhysicalDeviceDisplayPropertiesKHR',desc='Query information about the available displays',type='protos'] 30-- 31 32Various functions are provided for enumerating the available display devices 33present on a Vulkan physical device. 34To query information about the available displays, call: 35 36include::../../api/protos/vkGetPhysicalDeviceDisplayPropertiesKHR.txt[] 37 38 * pname:physicalDevice is a physical device. 39 * pname:pPropertyCount is a pointer to an integer related to the number of 40 display devices available or queried, as described below. 41 * pname:pProperties is either `NULL` or a pointer to an array of 42 sname:VkDisplayPropertiesKHR structures. 43 44If pname:pProperties is `NULL`, then the number of display devices available 45for pname:physicalDevice is returned in pname:pPropertyCount. 46Otherwise, pname:pPropertyCount must: point to a variable set by the user to 47the number of elements in the pname:pProperties array, and on return the 48variable is overwritten with the number of structures actually written to 49pname:pProperties. 50If the value of pname:pPropertyCount is less than the number of display 51devices for pname:physicalDevice, at most pname:pPropertyCount structures 52will be written. 53If pname:pPropertyCount is smaller than the number of display devices 54available for pname:physicalDevice, ename:VK_INCOMPLETE will be returned 55instead of ename:VK_SUCCESS to indicate that not all the available values 56were returned. 57 58include::../../validity/protos/vkGetPhysicalDeviceDisplayPropertiesKHR.txt[] 59-- 60 61[open,refpage='VkDisplayPropertiesKHR',desc='Structure describing an available display device',type='structs'] 62-- 63 64The sname:VkDisplayPropertiesKHR structure is defined as: 65 66include::../../api/structs/VkDisplayPropertiesKHR.txt[] 67 68 * pname:display is a handle that is used to refer to the display described 69 here. 70 This handle will be valid for the lifetime of the Vulkan instance. 71 * pname:displayName is a pointer to a NULL-terminated string containing 72 the name of the display. 73 Generally, this will be the name provided by the display's EDID. 74 It can: be `NULL` if no suitable name is available. 75 If not `NULL`, the memory it points to must: remain accessible as long 76 as pname:display is valid. 77 * pname:physicalDimensions describes the physical width and height of the 78 visible portion of the display, in millimeters. 79 * pname:physicalResolution describes the physical, native, or preferred 80 resolution of the display. 81 82[NOTE] 83.Note 84==== 85For devices which have no natural value to return here, implementations 86should: return the maximum resolution supported. 87==== 88 89 * pname:supportedTransforms tells which transforms are supported by this 90 display. 91 This will contain one or more of the bits from 92 sname:VkSurfaceTransformFlagsKHR. 93 * pname:planeReorderPossible tells whether the planes on this display can: 94 have their z order changed. 95 If this is ename:VK_TRUE, the application can: re-arrange the planes on 96 this display in any order relative to each other. 97 * pname:persistentContent tells whether the display supports 98 self-refresh/internal buffering. 99 If this is true, the application can: submit persistent present 100 operations on swapchains created against this display. 101 102[NOTE] 103.Note 104==== 105Persistent presents may: have higher latency, and may: use less power when 106the screen content is updated infrequently, or when only a portion of the 107screen needs to be updated in most frames. 108==== 109 110include::../../validity/structs/VkDisplayPropertiesKHR.txt[] 111-- 112 113ifdef::VK_KHR_get_display_properties2[] 114 115[open,refpage='vkGetPhysicalDeviceDisplayProperties2KHR',desc='Query information about the available displays',type='protos'] 116-- 117 118To query information about the available displays, call: 119 120include::../../api/protos/vkGetPhysicalDeviceDisplayProperties2KHR.txt[] 121 122 * pname:physicalDevice is a physical device. 123 * pname:pPropertyCount is a pointer to an integer related to the number of 124 display devices available or queried, as described below. 125 * pname:pProperties is either `NULL` or a pointer to an array of 126 sname:VkDisplayProperties2KHR structures. 127 128fname:vkGetPhysicalDeviceDisplayProperties2KHR behaves similarly to 129flink:vkGetPhysicalDeviceDisplayPropertiesKHR, with the ability to return 130extended information via chained output structures. 131 132include::../../validity/protos/vkGetPhysicalDeviceDisplayProperties2KHR.txt[] 133-- 134 135[open,refpage='VkDisplayProperties2KHR',desc='Structure describing an available display device',type='structs'] 136-- 137 138The sname:VkDisplayProperties2KHR structure is defined as: 139 140include::../../api/structs/VkDisplayProperties2KHR.txt[] 141 142 * pname:sType is the type of this structure. 143 * pname:pNext is `NULL` or a pointer to an extension-specific structure. 144 * pname:displayProperties is an instance of the 145 slink:VkDisplayPropertiesKHR structure. 146 147include::../../validity/structs/VkDisplayProperties2KHR.txt[] 148-- 149 150endif::VK_KHR_get_display_properties2[] 151 152ifdef::VK_EXT_direct_mode_display[] 153include::../VK_EXT_direct_mode_display/acquire_release_displays.txt[] 154endif::VK_EXT_direct_mode_display[] 155 156 157==== Display Planes 158 159[open,refpage='vkGetPhysicalDeviceDisplayPlanePropertiesKHR',desc='Query the plane properties',type='protos'] 160-- 161 162Images are presented to individual planes on a display. 163Devices must: support at least one plane on each display. 164Planes can: be stacked and blended to composite multiple images on one 165display. 166Devices may: support only a fixed stacking order and fixed mapping between 167planes and displays, or they may: allow arbitrary application specified 168stacking orders and mappings between planes and displays. 169To query the properties of device display planes, call: 170 171include::../../api/protos/vkGetPhysicalDeviceDisplayPlanePropertiesKHR.txt[] 172 173 * pname:physicalDevice is a physical device. 174 * pname:pPropertyCount is a pointer to an integer related to the number of 175 display planes available or queried, as described below. 176 * pname:pProperties is either `NULL` or a pointer to an array of 177 sname:VkDisplayPlanePropertiesKHR structures. 178 179If pname:pProperties is `NULL`, then the number of display planes available 180for pname:physicalDevice is returned in pname:pPropertyCount. 181Otherwise, pname:pPropertyCount must: point to a variable set by the user to 182the number of elements in the pname:pProperties array, and on return the 183variable is overwritten with the number of structures actually written to 184pname:pProperties. 185If the value of pname:pPropertyCount is less than the number of display 186planes for pname:physicalDevice, at most pname:pPropertyCount structures 187will be written. 188 189include::../../validity/protos/vkGetPhysicalDeviceDisplayPlanePropertiesKHR.txt[] 190-- 191 192[open,refpage='VkDisplayPlanePropertiesKHR',desc='Structure describing display plane properties',type='structs'] 193-- 194 195The sname:VkDisplayPlanePropertiesKHR structure is defined as: 196 197include::../../api/structs/VkDisplayPlanePropertiesKHR.txt[] 198 199 * pname:currentDisplay is the handle of the display the plane is currently 200 associated with. 201 If the plane is not currently attached to any displays, this will be 202 sname:VK_NULL_HANDLE. 203 * pname:currentStackIndex is the current z-order of the plane. 204 This will be between 0 and the value returned by 205 fname:vkGetPhysicalDeviceDisplayPlanePropertiesKHR in 206 pname:pPropertyCount. 207 208include::../../validity/structs/VkDisplayPlanePropertiesKHR.txt[] 209-- 210 211ifdef::VK_KHR_get_display_properties2[] 212 213[open,refpage='vkGetPhysicalDeviceDisplayPlaneProperties2KHR',desc='Query information about the available display planes.',type='protos'] 214-- 215 216To query the properties of a device's display planes, call: 217 218include::../../api/protos/vkGetPhysicalDeviceDisplayPlaneProperties2KHR.txt[] 219 220 * pname:physicalDevice is a physical device. 221 * pname:pPropertyCount is a pointer to an integer related to the number of 222 display planes available or queried, as described below. 223 * pname:pProperties is either `NULL` or a pointer to an array of 224 sname:VkDisplayPlaneProperties2KHR structures. 225 226fname:vkGetPhysicalDeviceDisplayPlaneProperties2KHR behaves similarly to 227flink:vkGetPhysicalDeviceDisplayPlanePropertiesKHR, with the ability to 228return extended information via chained output structures. 229 230include::../../validity/protos/vkGetPhysicalDeviceDisplayPlaneProperties2KHR.txt[] 231-- 232 233[open,refpage='VkDisplayPlaneProperties2KHR',desc='Structure describing an available display plane',type='structs'] 234-- 235 236The sname:VkDisplayPlaneProperties2KHR structure is defined as: 237 238include::../../api/structs/VkDisplayPlaneProperties2KHR.txt[] 239 240 * pname:sType is the type of this structure. 241 * pname:pNext is `NULL` or a pointer to an extension-specific structure. 242 * pname:displayPlaneProperties is an instance of the 243 slink:VkDisplayPlanePropertiesKHR structure. 244 245include::../../validity/structs/VkDisplayPlaneProperties2KHR.txt[] 246-- 247 248endif::VK_KHR_get_display_properties2[] 249 250[open,refpage='vkGetDisplayPlaneSupportedDisplaysKHR',desc='Query the list of displays a plane supports',type='protos'] 251-- 252 253To determine which displays a plane is usable with, call 254 255include::../../api/protos/vkGetDisplayPlaneSupportedDisplaysKHR.txt[] 256 257 * pname:physicalDevice is a physical device. 258 * pname:planeIndex is the plane which the application wishes to use, and 259 must: be in the range [eq]#[0, physical device plane count - 1]#. 260 * pname:pDisplayCount is a pointer to an integer related to the number of 261 displays available or queried, as described below. 262 * pname:pDisplays is either `NULL` or a pointer to an array of 263 sname:VkDisplayKHR handles. 264 265If pname:pDisplays is `NULL`, then the number of displays usable with the 266specified pname:planeIndex for pname:physicalDevice is returned in 267pname:pDisplayCount. 268Otherwise, pname:pDisplayCount must: point to a variable set by the user to 269the number of elements in the pname:pDisplays array, and on return the 270variable is overwritten with the number of handles actually written to 271pname:pDisplays. 272If the value of pname:pDisplayCount is less than the number of display 273planes for pname:physicalDevice, at most pname:pDisplayCount handles will be 274written. 275If pname:pDisplayCount is smaller than the number of displays usable with 276the specified pname:planeIndex for pname:physicalDevice, ename:VK_INCOMPLETE 277will be returned instead of ename:VK_SUCCESS to indicate that not all the 278available values were returned. 279 280.Valid Usage 281**** 282 * [[VUID-vkGetDisplayPlaneSupportedDisplaysKHR-planeIndex-01249]] 283 pname:planeIndex must: be less than the number of display planes 284 supported by the device as determined by calling 285 fname:vkGetPhysicalDeviceDisplayPlanePropertiesKHR 286**** 287 288include::../../validity/protos/vkGetDisplayPlaneSupportedDisplaysKHR.txt[] 289-- 290 291Additional properties of displays are queried using specialized query 292functions. 293 294 295==== Display Modes 296 297[open,refpage='VkDisplayModeKHR',desc='Opaque handle to a display mode object',type='handles'] 298-- 299 300Display modes are represented by sname:VkDisplayModeKHR handles: 301 302include::../../api/handles/VkDisplayModeKHR.txt[] 303 304-- 305 306[open,refpage='vkGetDisplayModePropertiesKHR',desc='Query the set of mode properties supported by the display',type='protos'] 307-- 308 309Each display has one or more supported modes associated with it by default. 310These built-in modes are queried by calling: 311 312include::../../api/protos/vkGetDisplayModePropertiesKHR.txt[] 313 314 * pname:physicalDevice is the physical device associated with 315 pname:display. 316 * pname:display is the display to query. 317 * pname:pPropertyCount is a pointer to an integer related to the number of 318 display modes available or queried, as described below. 319 * pname:pProperties is either `NULL` or a pointer to an array of 320 sname:VkDisplayModePropertiesKHR structures. 321 322If pname:pProperties is `NULL`, then the number of display modes available 323on the specified pname:display for pname:physicalDevice is returned in 324pname:pPropertyCount. 325Otherwise, pname:pPropertyCount must: point to a variable set by the user to 326the number of elements in the pname:pProperties array, and on return the 327variable is overwritten with the number of structures actually written to 328pname:pProperties. 329If the value of pname:pPropertyCount is less than the number of display 330modes for pname:physicalDevice, at most pname:pPropertyCount structures will 331be written. 332If pname:pPropertyCount is smaller than the number of display modes 333available on the specified pname:display for pname:physicalDevice, 334ename:VK_INCOMPLETE will be returned instead of ename:VK_SUCCESS to indicate 335that not all the available values were returned. 336 337include::../../validity/protos/vkGetDisplayModePropertiesKHR.txt[] 338-- 339 340[open,refpage='VkDisplayModePropertiesKHR',desc='Structure describing display mode properties',type='structs'] 341-- 342 343The sname:VkDisplayModePropertiesKHR structure is defined as: 344 345include::../../api/structs/VkDisplayModePropertiesKHR.txt[] 346 347 * pname:displayMode is a handle to the display mode described in this 348 structure. 349 This handle will be valid for the lifetime of the Vulkan instance. 350 * pname:parameters is a slink:VkDisplayModeParametersKHR structure 351 describing the display parameters associated with pname:displayMode. 352 353include::../../validity/structs/VkDisplayModePropertiesKHR.txt[] 354-- 355 356ifdef::VK_KHR_get_display_properties2[] 357 358[open,refpage='vkGetDisplayModeProperties2KHR',desc='Query information about the available display modes.',type='protos'] 359-- 360 361To query the properties of a device's built-in display modes, call: 362 363include::../../api/protos/vkGetDisplayModeProperties2KHR.txt[] 364 365 * pname:physicalDevice is the physical device associated with 366 pname:display. 367 * pname:display is the display to query. 368 * pname:pPropertyCount is a pointer to an integer related to the number of 369 display modes available or queried, as described below. 370 * pname:pProperties is either `NULL` or a pointer to an array of 371 sname:VkDisplayModeProperties2KHR structures. 372 373fname:vkGetDisplayModeProperties2KHR behaves similarly to 374flink:vkGetDisplayModePropertiesKHR, with the ability to return extended 375information via chained output structures. 376 377include::../../validity/protos/vkGetDisplayModeProperties2KHR.txt[] 378-- 379 380[open,refpage='VkDisplayModeProperties2KHR',desc='Structure describing an available display mode',type='structs'] 381-- 382 383The sname:VkDisplayModeProperties2KHR structure is defined as: 384 385include::../../api/structs/VkDisplayModeProperties2KHR.txt[] 386 387 * pname:sType is the type of this structure. 388 * pname:pNext is `NULL` or a pointer to an extension-specific structure. 389 * pname:displayModeProperties is an instance of the 390 slink:VkDisplayModePropertiesKHR structure. 391 392include::../../validity/structs/VkDisplayModeProperties2KHR.txt[] 393-- 394 395endif::VK_KHR_get_display_properties2[] 396 397[open,refpage='VkDisplayModeParametersKHR',desc='Structure describing display parameters associated with a display mode',type='structs'] 398-- 399 400The sname:VkDisplayModeParametersKHR structure is defined as: 401 402include::../../api/structs/VkDisplayModeParametersKHR.txt[] 403 404 * pname:visibleRegion is the 2D extents of the visible region. 405 * pname:refreshRate is a code:uint32_t that is the number of times the 406 display is refreshed each second multiplied by 1000. 407 408[NOTE] 409.Note 410==== 411For example, a 60Hz display mode would report a pname:refreshRate of 60,000. 412==== 413 414.Valid Usage 415**** 416 * [[VUID-VkDisplayModeParametersKHR-width-01990]] 417 The pname:width member of pname:visibleRegion must: be greater than `0` 418 * [[VUID-VkDisplayModeParametersKHR-height-01991]] 419 The pname:height member of pname:visibleRegion must: be greater than `0` 420 * [[VUID-VkDisplayModeParametersKHR-refreshRate-01992]] 421 pname:refreshRate must: be greater than `0` 422**** 423 424include::../../validity/structs/VkDisplayModeParametersKHR.txt[] 425-- 426 427[open,refpage='vkCreateDisplayModeKHR',desc='Create a display mode',type='protos'] 428-- 429 430Additional modes may: also be created by calling: 431 432include::../../api/protos/vkCreateDisplayModeKHR.txt[] 433 434 * pname:physicalDevice is the physical device associated with 435 pname:display. 436 * pname:display is the display to create an additional mode for. 437 * pname:pCreateInfo is a slink:VkDisplayModeCreateInfoKHR structure 438 describing the new mode to create. 439 * pname:pAllocator is the allocator used for host memory allocated for the 440 display mode object when there is no more specific allocator available 441 (see <<memory-allocation,Memory Allocation>>). 442 * pname:pMode returns the handle of the mode created. 443 444include::../../validity/protos/vkCreateDisplayModeKHR.txt[] 445-- 446 447[open,refpage='VkDisplayModeCreateInfoKHR',desc='Structure specifying parameters of a newly created display mode object',type='structs'] 448-- 449 450The sname:VkDisplayModeCreateInfoKHR structure is defined as: 451 452include::../../api/structs/VkDisplayModeCreateInfoKHR.txt[] 453 454 * pname:sType is the type of this structure. 455 * pname:pNext is `NULL` or a pointer to an extension-specific structure. 456 * pname:flags is reserved for future use, and must: be zero. 457 * pname:parameters is a slink:VkDisplayModeParametersKHR structure 458 describing the display parameters to use in creating the new mode. 459 If the parameters are not compatible with the specified display, the 460 implementation must: return ename:VK_ERROR_INITIALIZATION_FAILED. 461 462include::../../validity/structs/VkDisplayModeCreateInfoKHR.txt[] 463-- 464 465[open,refpage='vkGetDisplayPlaneCapabilitiesKHR',desc='Query capabilities of a mode and plane combination',type='protos'] 466-- 467 468Applications that wish to present directly to a display must: select which 469layer, or "`plane`" of the display they wish to target, and a mode to use 470with the display. 471Each display supports at least one plane. 472The capabilities of a given mode and plane combination are determined by 473calling: 474 475include::../../api/protos/vkGetDisplayPlaneCapabilitiesKHR.txt[] 476 477 * pname:physicalDevice is the physical device associated with 478 pname:display 479 * pname:mode is the display mode the application intends to program when 480 using the specified plane. 481 Note this parameter also implicitly specifies a display. 482 * pname:planeIndex is the plane which the application intends to use with 483 the display, and is less than the number of display planes supported by 484 the device. 485 * pname:pCapabilities is a pointer to a 486 slink:VkDisplayPlaneCapabilitiesKHR structure in which the capabilities 487 are returned. 488 489include::../../validity/protos/vkGetDisplayPlaneCapabilitiesKHR.txt[] 490-- 491 492[open,refpage='VkDisplayPlaneCapabilitiesKHR',desc='Structure describing capabilities of a mode and plane combination',type='structs'] 493-- 494 495The sname:VkDisplayPlaneCapabilitiesKHR structure is defined as: 496 497include::../../api/structs/VkDisplayPlaneCapabilitiesKHR.txt[] 498 499 * pname:supportedAlpha is a bitmask of 500 elink:VkDisplayPlaneAlphaFlagBitsKHR describing the supported alpha 501 blending modes. 502 * pname:minSrcPosition is the minimum source rectangle offset supported by 503 this plane using the specified mode. 504 * pname:maxSrcPosition is the maximum source rectangle offset supported by 505 this plane using the specified mode. 506 The pname:x and pname:y components of pname:maxSrcPosition must: each be 507 greater than or equal to the pname:x and pname:y components of 508 pname:minSrcPosition, respectively. 509 * pname:minSrcExtent is the minimum source rectangle size supported by 510 this plane using the specified mode. 511 * pname:maxSrcExtent is the maximum source rectangle size supported by 512 this plane using the specified mode. 513 * pname:minDstPosition, pname:maxDstPosition, pname:minDstExtent, 514 pname:maxDstExtent all have similar semantics to their corresponding 515 ptext:*Src* equivalents, but apply to the output region within the mode 516 rather than the input region within the source image. 517 Unlike the ptext:*Src* offsets, pname:minDstPosition and 518 pname:maxDstPosition may: contain negative values. 519 520The minimum and maximum position and extent fields describe the 521implementation limits, if any, as they apply to the specified display mode 522and plane. 523Vendors may: support displaying a subset of a swapchain's presentable images 524on the specified display plane. 525This is expressed by returning pname:minSrcPosition, pname:maxSrcPosition, 526pname:minSrcExtent, and pname:maxSrcExtent values that indicate a range of 527possible positions and sizes may: be used to specify the region within the 528presentable images that source pixels will be read from when creating a 529swapchain on the specified display mode and plane. 530 531Vendors may: also support mapping the presentable images`' content to a 532subset or superset of the visible region in the specified display mode. 533This is expressed by returning pname:minDstPosition, pname:maxDstPosition, 534pname:minDstExtent and pname:maxDstExtent values that indicate a range of 535possible positions and sizes may: be used to describe the region within the 536display mode that the source pixels will be mapped to. 537 538Other vendors may: support only a 1-1 mapping between pixels in the 539presentable images and the display mode. 540This may: be indicated by returning [eq]#(0,0)# for pname:minSrcPosition, 541pname:maxSrcPosition, pname:minDstPosition, and pname:maxDstPosition, and 542(display mode width, display mode height) for pname:minSrcExtent, 543pname:maxSrcExtent, pname:minDstExtent, and pname:maxDstExtent. 544 545These values indicate the limits of the implementation's individual fields. 546Not all combinations of values within the offset and extent ranges returned 547in sname:VkDisplayPlaneCapabilitiesKHR are guaranteed to be supported. 548Vendors may: still fail presentation requests that specify unsupported 549combinations. 550 551include::../../validity/structs/VkDisplayPlaneCapabilitiesKHR.txt[] 552-- 553 554ifdef::VK_KHR_get_display_properties2[] 555 556[open,refpage='vkGetDisplayPlaneCapabilities2KHR',desc='Query capabilities of a mode and plane combination',type='protos'] 557-- 558 559To query the capabilities of a given mode and plane combination, call: 560 561include::../../api/protos/vkGetDisplayPlaneCapabilities2KHR.txt[] 562 563 * pname:physicalDevice is the physical device associated with 564 pname:pDisplayPlaneInfo. 565 * pname:pDisplayPlaneInfo is a pointer to an instance of the 566 slink:VkDisplayPlaneInfo2KHR structure describing the plane and mode. 567 * pname:pCapabilities is a pointer to a 568 slink:VkDisplayPlaneCapabilities2KHR structure in which the capabilities 569 are returned. 570 571fname:vkGetDisplayPlaneCapabilities2KHR behaves similarly to 572flink:vkGetDisplayPlaneCapabilitiesKHR, with the ability to specify extended 573inputs via chained input structures, and to return extended information via 574chained output structures. 575 576include::../../validity/protos/vkGetDisplayPlaneCapabilities2KHR.txt[] 577-- 578 579[open,refpage='VkDisplayPlaneInfo2KHR',desc='Structure defining the intended configuration of a display plane',type='structs'] 580-- 581 582The sname:VkDisplayPlaneInfo2KHR structure is defined as: 583 584include::../../api/structs/VkDisplayPlaneInfo2KHR.txt[] 585 586 * pname:sType is the type of this structure. 587 * pname:pNext is `NULL` or a pointer to an extension-specific structure. 588 * pname:mode is the display mode the application intends to program when 589 using the specified plane. 590 591[NOTE] 592.Note 593==== 594This parameter also implicitly specifies a display. 595==== 596 597 * pname:planeIndex is the plane which the application intends to use with 598 the display. 599 600The members of sname:VkDisplayPlaneInfo2KHR correspond to the arguments to 601flink:vkGetDisplayPlaneCapabilitiesKHR, with pname:sType and pname:pNext 602added for extensibility. 603 604include::../../validity/structs/VkDisplayPlaneInfo2KHR.txt[] 605-- 606 607[open,refpage='VkDisplayPlaneCapabilities2KHR',desc='Structure describing the capabilities of a mode and plane combination',type='structs'] 608-- 609 610The sname:VkDisplayPlaneCapabilities2KHR structure is defined as: 611 612include::../../api/structs/VkDisplayPlaneCapabilities2KHR.txt[] 613 614 * pname:sType is the type of this structure. 615 * pname:pNext is `NULL` or a pointer to an extension-specific structure. 616 * pname:capabilities is an instance of the 617 slink:VkDisplayPlaneCapabilitiesKHR structure. 618 619include::../../validity/structs/VkDisplayPlaneCapabilities2KHR.txt[] 620-- 621 622endif::VK_KHR_get_display_properties2[] 623 624ifdef::VK_EXT_display_control[] 625include::../VK_EXT_display_control/display_control.txt[] 626endif::VK_EXT_display_control[] 627 628[[wsi-display-surfaces]] 629=== Display Surfaces 630 631[open,refpage='vkCreateDisplayPlaneSurfaceKHR',desc='Create a slink:VkSurfaceKHR structure representing a display plane and mode',type='protos'] 632-- 633 634A complete display configuration includes a mode, one or more display planes 635and any parameters describing their behavior, and parameters describing some 636aspects of the images associated with those planes. 637Display surfaces describe the configuration of a single plane within a 638complete display configuration. 639To create a sname:VkSurfaceKHR structure for a display surface, call: 640 641include::../../api/protos/vkCreateDisplayPlaneSurfaceKHR.txt[] 642 643 * pname:instance is the instance corresponding to the physical device the 644 targeted display is on. 645 * pname:pCreateInfo is a pointer to an instance of the 646 slink:VkDisplaySurfaceCreateInfoKHR structure specifying which mode, 647 plane, and other parameters to use, as described below. 648 * pname:pAllocator is the allocator used for host memory allocated for the 649 surface object when there is no more specific allocator available (see 650 <<memory-allocation,Memory Allocation>>). 651 * pname:pSurface points to a slink:VkSurfaceKHR handle in which the 652 created surface is returned. 653 654include::../../validity/protos/vkCreateDisplayPlaneSurfaceKHR.txt[] 655-- 656 657[open,refpage='VkDisplaySurfaceCreateInfoKHR',desc='Structure specifying parameters of a newly created display plane surface object',type='structs'] 658-- 659 660The sname:VkDisplaySurfaceCreateInfoKHR structure is defined as: 661 662include::../../api/structs/VkDisplaySurfaceCreateInfoKHR.txt[] 663 664 * pname:sType is the type of this structure. 665 * pname:pNext is `NULL` or a pointer to an extension-specific structure. 666 * pname:flags is reserved for future use, and must: be zero. 667 * pname:displayMode is a slink:VkDisplayModeKHR handle specifying the mode 668 to use when displaying this surface. 669 * pname:planeIndex is the plane on which this surface appears. 670 * pname:planeStackIndex is the z-order of the plane. 671 * pname:transform is a elink:VkSurfaceTransformFlagBitsKHR value 672 specifying the transformation to apply to images as part of the scanout 673 operation. 674 * pname:globalAlpha is the global alpha value. 675 This value is ignored if pname:alphaMode is not 676 ename:VK_DISPLAY_PLANE_ALPHA_GLOBAL_BIT_KHR. 677 * pname:alphaMode is a elink:VkDisplayPlaneAlphaFlagBitsKHR value 678 specifying the type of alpha blending to use. 679 * pname:imageExtent The size of the presentable images to use with the 680 surface. 681 682[NOTE] 683.Note 684==== 685Creating a display surface must: not modify the state of the displays, 686planes, or other resources it names. 687For example, it must: not apply the specified mode to be set on the 688associated display. 689Application of display configuration occurs as a side effect of presenting 690to a display surface. 691==== 692 693.Valid Usage 694**** 695 * [[VUID-VkDisplaySurfaceCreateInfoKHR-planeIndex-01252]] 696 pname:planeIndex must: be less than the number of display planes 697 supported by the device as determined by calling 698 fname:vkGetPhysicalDeviceDisplayPlanePropertiesKHR 699 * [[VUID-VkDisplaySurfaceCreateInfoKHR-planeReorderPossible-01253]] 700 If the pname:planeReorderPossible member of the 701 sname:VkDisplayPropertiesKHR structure returned by 702 fname:vkGetPhysicalDeviceDisplayPropertiesKHR for the display 703 corresponding to pname:displayMode is ename:VK_TRUE then 704 pname:planeStackIndex must: be less than the number of display planes 705 supported by the device as determined by calling 706 fname:vkGetPhysicalDeviceDisplayPlanePropertiesKHR; otherwise 707 pname:planeStackIndex must: equal the pname:currentStackIndex member of 708 sname:VkDisplayPlanePropertiesKHR returned by 709 fname:vkGetPhysicalDeviceDisplayPlanePropertiesKHR for the display plane 710 corresponding to pname:displayMode 711 * [[VUID-VkDisplaySurfaceCreateInfoKHR-alphaMode-01254]] 712 If pname:alphaMode is ename:VK_DISPLAY_PLANE_ALPHA_GLOBAL_BIT_KHR then 713 pname:globalAlpha must: be between `0` and `1`, inclusive 714 * [[VUID-VkDisplaySurfaceCreateInfoKHR-alphaMode-01255]] 715 pname:alphaMode must: be `0` or one of the bits present in the 716 pname:supportedAlpha member of sname:VkDisplayPlaneCapabilitiesKHR 717 returned by fname:vkGetDisplayPlaneCapabilitiesKHR for the display plane 718 corresponding to pname:displayMode 719 * [[VUID-VkDisplaySurfaceCreateInfoKHR-width-01256]] 720 The pname:width and pname:height members of pname:imageExtent must: be 721 less than the pname:maxImageDimensions2D member of 722 sname:VkPhysicalDeviceLimits 723**** 724 725include::../../validity/structs/VkDisplaySurfaceCreateInfoKHR.txt[] 726-- 727 728[open,refpage='VkDisplayPlaneAlphaFlagBitsKHR',desc='Alpha blending type',type='enums'] 729-- 730 731Possible values of slink:VkDisplaySurfaceCreateInfoKHR::pname:alphaMode, 732specifying the type of alpha blending to use on a display, are: 733 734include::../../api/enums/VkDisplayPlaneAlphaFlagBitsKHR.txt[] 735 736 * ename:VK_DISPLAY_PLANE_ALPHA_OPAQUE_BIT_KHR specifies that the source 737 image will be treated as opaque. 738 * ename:VK_DISPLAY_PLANE_ALPHA_GLOBAL_BIT_KHR specifies that a global 739 alpha value must: be specified that will be applied to all pixels in the 740 source image. 741 * ename:VK_DISPLAY_PLANE_ALPHA_PER_PIXEL_BIT_KHR specifies that the alpha 742 value will be determined by the alpha channel of the source image's 743 pixels. 744 If the source format contains no alpha values, no blending will be 745 applied. 746 The source alpha values are not premultiplied into the source image's 747 other color channels. 748 * ename:VK_DISPLAY_PLANE_ALPHA_PER_PIXEL_PREMULTIPLIED_BIT_KHR is 749 equivalent to ename:VK_DISPLAY_PLANE_ALPHA_PER_PIXEL_BIT_KHR, except the 750 source alpha values are assumed to be premultiplied into the source 751 image's other color channels. 752 753-- 754 755[open,refpage='VkDisplayPlaneAlphaFlagsKHR',desc='Bitmask of VkDisplayPlaneAlphaFlagBitsKHR',type='enums'] 756-- 757include::../../api/flags/VkDisplayPlaneAlphaFlagsKHR.txt[] 758 759sname:VkDisplayPlaneAlphaFlagsKHR is a bitmask type for setting a mask of 760zero or more slink:VkDisplayPlaneAlphaFlagBitsKHR. 761-- 762