chapters/VK_KHR_display/display.adoc

// Copyright 2014-2023 The Khronos Group Inc.
//
// SPDX-License-Identifier: CC-BY-4.0

[[display]]
== Presenting Directly to Display Devices

In some environments applications can: also present Vulkan rendering
directly to display devices without using an intermediate windowing system.
This can: be useful for embedded applications, or implementing the
rendering/presentation backend of a windowing system using Vulkan.
The `apiext:VK_KHR_display` extension provides the functionality necessary
to enumerate display devices and create sname:VkSurfaceKHR objects that
target displays.


=== Display Enumeration

[open,refpage='VkDisplayKHR',desc='Opaque handle to a display object',type='handles']
--
Displays are represented by sname:VkDisplayKHR handles:

include::{generated}/api/handles/VkDisplayKHR.adoc[]
--

[open,refpage='vkGetPhysicalDeviceDisplayPropertiesKHR',desc='Query information about the available displays',type='protos']
--
:refpage: vkGetPhysicalDeviceDisplayPropertiesKHR

Various functions are provided for enumerating the available display devices
present on a Vulkan physical device.
To query information about the available displays, call:

include::{generated}/api/protos/vkGetPhysicalDeviceDisplayPropertiesKHR.adoc[]

  * pname:physicalDevice is a physical device.
  * pname:pPropertyCount is a pointer to an integer related to the number of
    display devices available or queried, as described below.
  * pname:pProperties is either `NULL` or a pointer to an array of
    sname:VkDisplayPropertiesKHR structures.

If pname:pProperties is `NULL`, then the number of display devices available
for pname:physicalDevice is returned in pname:pPropertyCount.
Otherwise, pname:pPropertyCount must: point to a variable set by the user to
the number of elements in the pname:pProperties array, and on return the
variable is overwritten with the number of structures actually written to
pname:pProperties.
If the value of pname:pPropertyCount is less than the number of display
devices for pname:physicalDevice, at most pname:pPropertyCount structures
will be written, and ename:VK_INCOMPLETE will be returned instead of
ename:VK_SUCCESS, to indicate that not all the available properties were
returned.

include::{chapters}/commonvalidity/no_dynamic_allocations_common.adoc[]

include::{generated}/validity/protos/vkGetPhysicalDeviceDisplayPropertiesKHR.adoc[]
--

[open,refpage='VkDisplayPropertiesKHR',desc='Structure describing an available display device',type='structs']
--
The sname:VkDisplayPropertiesKHR structure is defined as:

include::{generated}/api/structs/VkDisplayPropertiesKHR.adoc[]

  * pname:display is a handle that is used to refer to the display described
    here.
    This handle will be valid for the lifetime of the Vulkan instance.
  * pname:displayName is `NULL` or a pointer to a null-terminated UTF-8
    string containing the name of the display.
    Generally, this will be the name provided by the display's EDID.
    If `NULL`, no suitable name is available.
    If not `NULL`, the string pointed to must: remain accessible and
    unmodified as long as pname:display is valid.
  * pname:physicalDimensions describes the physical width and height of the
    visible portion of the display, in millimeters.
  * pname:physicalResolution describes the physical, native, or preferred
    resolution of the display.

[NOTE]
.Note
====
For devices which have no natural value to return here, implementations
should: return the maximum resolution supported.
====

  * pname:supportedTransforms is a bitmask of
    elink:VkSurfaceTransformFlagBitsKHR describing which transforms are
    supported by this display.
  * pname:planeReorderPossible tells whether the planes on this display can:
    have their z order changed.
    If this is ename:VK_TRUE, the application can: re-arrange the planes on
    this display in any order relative to each other.
  * pname:persistentContent tells whether the display supports
    self-refresh/internal buffering.
    If this is true, the application can: submit persistent present
    operations on swapchains created against this display.

[NOTE]
.Note
====
Persistent presents may: have higher latency, and may: use less power when
the screen content is updated infrequently, or when only a portion of the
screen needs to be updated in most frames.
====

include::{generated}/validity/structs/VkDisplayPropertiesKHR.adoc[]
--

ifdef::VK_KHR_get_display_properties2[]
[open,refpage='vkGetPhysicalDeviceDisplayProperties2KHR',desc='Query information about the available displays',type='protos']
--
:refpage: vkGetPhysicalDeviceDisplayProperties2KHR

To query information about the available displays, call:

include::{generated}/api/protos/vkGetPhysicalDeviceDisplayProperties2KHR.adoc[]

  * pname:physicalDevice is a physical device.
  * pname:pPropertyCount is a pointer to an integer related to the number of
    display devices available or queried, as described below.
  * pname:pProperties is either `NULL` or a pointer to an array of
    sname:VkDisplayProperties2KHR structures.

fname:vkGetPhysicalDeviceDisplayProperties2KHR behaves similarly to
flink:vkGetPhysicalDeviceDisplayPropertiesKHR, with the ability to return
extended information via chained output structures.

include::{chapters}/commonvalidity/no_dynamic_allocations_common.adoc[]

include::{generated}/validity/protos/vkGetPhysicalDeviceDisplayProperties2KHR.adoc[]
--

[open,refpage='VkDisplayProperties2KHR',desc='Structure describing an available display device',type='structs']
--
The sname:VkDisplayProperties2KHR structure is defined as:

include::{generated}/api/structs/VkDisplayProperties2KHR.adoc[]

  * pname:sType is a elink:VkStructureType value identifying this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:displayProperties is a slink:VkDisplayPropertiesKHR structure.

include::{generated}/validity/structs/VkDisplayProperties2KHR.adoc[]
--
endif::VK_KHR_get_display_properties2[]

ifdef::VK_EXT_direct_mode_display[]
include::{chapters}/VK_EXT_direct_mode_display/acquire_release_displays.adoc[]
endif::VK_EXT_direct_mode_display[]


==== Display Planes

[open,refpage='vkGetPhysicalDeviceDisplayPlanePropertiesKHR',desc='Query the plane properties',type='protos']
--
:refpage: vkGetPhysicalDeviceDisplayPlanePropertiesKHR

Images are presented to individual planes on a display.
Devices must: support at least one plane on each display.
Planes can: be stacked and blended to composite multiple images on one
display.
Devices may: support only a fixed stacking order and fixed mapping between
planes and displays, or they may: allow arbitrary application specified
stacking orders and mappings between planes and displays.
To query the properties of device display planes, call:

include::{generated}/api/protos/vkGetPhysicalDeviceDisplayPlanePropertiesKHR.adoc[]

  * pname:physicalDevice is a physical device.
  * pname:pPropertyCount is a pointer to an integer related to the number of
    display planes available or queried, as described below.
  * pname:pProperties is either `NULL` or a pointer to an array of
    sname:VkDisplayPlanePropertiesKHR structures.

If pname:pProperties is `NULL`, then the number of display planes available
for pname:physicalDevice is returned in pname:pPropertyCount.
Otherwise, pname:pPropertyCount must: point to a variable set by the user to
the number of elements in the pname:pProperties array, and on return the
variable is overwritten with the number of structures actually written to
pname:pProperties.
If the value of pname:pPropertyCount is less than the number of display
planes for pname:physicalDevice, at most pname:pPropertyCount structures
will be written.

include::{chapters}/commonvalidity/no_dynamic_allocations_common.adoc[]

include::{generated}/validity/protos/vkGetPhysicalDeviceDisplayPlanePropertiesKHR.adoc[]
--

[open,refpage='VkDisplayPlanePropertiesKHR',desc='Structure describing display plane properties',type='structs']
--
The sname:VkDisplayPlanePropertiesKHR structure is defined as:

include::{generated}/api/structs/VkDisplayPlanePropertiesKHR.adoc[]

  * pname:currentDisplay is the handle of the display the plane is currently
    associated with.
    If the plane is not currently attached to any displays, this will be
    dlink:VK_NULL_HANDLE.
  * pname:currentStackIndex is the current z-order of the plane.
    This will be between 0 and the value returned by
    fname:vkGetPhysicalDeviceDisplayPlanePropertiesKHR in
    pname:pPropertyCount.

include::{generated}/validity/structs/VkDisplayPlanePropertiesKHR.adoc[]
--

ifdef::VK_KHR_get_display_properties2[]
[open,refpage='vkGetPhysicalDeviceDisplayPlaneProperties2KHR',desc='Query information about the available display planes.',type='protos']
--
:refpage: vkGetPhysicalDeviceDisplayPlaneProperties2KHR

To query the properties of a device's display planes, call:

include::{generated}/api/protos/vkGetPhysicalDeviceDisplayPlaneProperties2KHR.adoc[]

  * pname:physicalDevice is a physical device.
  * pname:pPropertyCount is a pointer to an integer related to the number of
    display planes available or queried, as described below.
  * pname:pProperties is either `NULL` or a pointer to an array of
    sname:VkDisplayPlaneProperties2KHR structures.

fname:vkGetPhysicalDeviceDisplayPlaneProperties2KHR behaves similarly to
flink:vkGetPhysicalDeviceDisplayPlanePropertiesKHR, with the ability to
return extended information via chained output structures.

include::{chapters}/commonvalidity/no_dynamic_allocations_common.adoc[]

include::{generated}/validity/protos/vkGetPhysicalDeviceDisplayPlaneProperties2KHR.adoc[]
--

[open,refpage='VkDisplayPlaneProperties2KHR',desc='Structure describing an available display plane',type='structs']
--
The sname:VkDisplayPlaneProperties2KHR structure is defined as:

include::{generated}/api/structs/VkDisplayPlaneProperties2KHR.adoc[]

  * pname:sType is a elink:VkStructureType value identifying this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:displayPlaneProperties is a slink:VkDisplayPlanePropertiesKHR
    structure.

include::{generated}/validity/structs/VkDisplayPlaneProperties2KHR.adoc[]
--
endif::VK_KHR_get_display_properties2[]

[open,refpage='vkGetDisplayPlaneSupportedDisplaysKHR',desc='Query the list of displays a plane supports',type='protos']
--
:refpage: vkGetDisplayPlaneSupportedDisplaysKHR

To determine which displays a plane is usable with, call

include::{generated}/api/protos/vkGetDisplayPlaneSupportedDisplaysKHR.adoc[]

  * pname:physicalDevice is a physical device.
  * pname:planeIndex is the plane which the application wishes to use, and
    must: be in the range [eq]#[0, physical device plane count - 1]#.
  * pname:pDisplayCount is a pointer to an integer related to the number of
    displays available or queried, as described below.
  * pname:pDisplays is either `NULL` or a pointer to an array of
    sname:VkDisplayKHR handles.

If pname:pDisplays is `NULL`, then the number of displays usable with the
specified pname:planeIndex for pname:physicalDevice is returned in
pname:pDisplayCount.
Otherwise, pname:pDisplayCount must: point to a variable set by the user to
the number of elements in the pname:pDisplays array, and on return the
variable is overwritten with the number of handles actually written to
pname:pDisplays.
If the value of pname:pDisplayCount is less than the number of usable
display-plane pairs for pname:physicalDevice, at most pname:pDisplayCount
handles will be written, and ename:VK_INCOMPLETE will be returned instead of
ename:VK_SUCCESS, to indicate that not all the available pairs were
returned.

include::{chapters}/commonvalidity/no_dynamic_allocations_common.adoc[]

.Valid Usage
****
  * [[VUID-vkGetDisplayPlaneSupportedDisplaysKHR-planeIndex-01249]]
    pname:planeIndex must: be less than the number of display planes
    supported by the device as determined by calling
    fname:vkGetPhysicalDeviceDisplayPlanePropertiesKHR
****

include::{generated}/validity/protos/vkGetDisplayPlaneSupportedDisplaysKHR.adoc[]
--

Additional properties of displays are queried using specialized query
functions.


==== Display Modes

[open,refpage='VkDisplayModeKHR',desc='Opaque handle to a display mode object',type='handles']
--
Display modes are represented by sname:VkDisplayModeKHR handles:

include::{generated}/api/handles/VkDisplayModeKHR.adoc[]
--

[open,refpage='vkGetDisplayModePropertiesKHR',desc='Query the set of mode properties supported by the display',type='protos']
--
:refpage: vkGetDisplayModePropertiesKHR

Each display has one or more supported modes associated with it by default.
These built-in modes are queried by calling:

include::{generated}/api/protos/vkGetDisplayModePropertiesKHR.adoc[]

  * pname:physicalDevice is the physical device associated with
    pname:display.
  * pname:display is the display to query.
  * pname:pPropertyCount is a pointer to an integer related to the number of
    display modes available or queried, as described below.
  * pname:pProperties is either `NULL` or a pointer to an array of
    sname:VkDisplayModePropertiesKHR structures.

If pname:pProperties is `NULL`, then the number of display modes available
on the specified pname:display for pname:physicalDevice is returned in
pname:pPropertyCount.
Otherwise, pname:pPropertyCount must: point to a variable set by the user to
the number of elements in the pname:pProperties array, and on return the
variable is overwritten with the number of structures actually written to
pname:pProperties.
If the value of pname:pPropertyCount is less than the number of display
modes for pname:physicalDevice, at most pname:pPropertyCount structures will
be written, and ename:VK_INCOMPLETE will be returned instead of
ename:VK_SUCCESS, to indicate that not all the available display modes were
returned.

include::{chapters}/commonvalidity/no_dynamic_allocations_common.adoc[]

include::{generated}/validity/protos/vkGetDisplayModePropertiesKHR.adoc[]
--

[open,refpage='VkDisplayModePropertiesKHR',desc='Structure describing display mode properties',type='structs']
--
The sname:VkDisplayModePropertiesKHR structure is defined as:

include::{generated}/api/structs/VkDisplayModePropertiesKHR.adoc[]

  * pname:displayMode is a handle to the display mode described in this
    structure.
    This handle will be valid for the lifetime of the Vulkan instance.
  * pname:parameters is a slink:VkDisplayModeParametersKHR structure
    describing the display parameters associated with pname:displayMode.

include::{generated}/validity/structs/VkDisplayModePropertiesKHR.adoc[]
--

[open,refpage='VkDisplayModeCreateFlagsKHR',desc='Reserved for future use',type='flags']
--
include::{generated}/api/flags/VkDisplayModeCreateFlagsKHR.adoc[]

tname:VkDisplayModeCreateFlagsKHR is a bitmask type for setting a mask, but
is currently reserved for future use.
--

ifdef::VK_KHR_get_display_properties2[]
[open,refpage='vkGetDisplayModeProperties2KHR',desc='Query information about the available display modes.',type='protos']
--
:refpage: vkGetDisplayModeProperties2KHR

To query the properties of a device's built-in display modes, call:

include::{generated}/api/protos/vkGetDisplayModeProperties2KHR.adoc[]

  * pname:physicalDevice is the physical device associated with
    pname:display.
  * pname:display is the display to query.
  * pname:pPropertyCount is a pointer to an integer related to the number of
    display modes available or queried, as described below.
  * pname:pProperties is either `NULL` or a pointer to an array of
    sname:VkDisplayModeProperties2KHR structures.

fname:vkGetDisplayModeProperties2KHR behaves similarly to
flink:vkGetDisplayModePropertiesKHR, with the ability to return extended
information via chained output structures.

include::{chapters}/commonvalidity/no_dynamic_allocations_common.adoc[]

include::{generated}/validity/protos/vkGetDisplayModeProperties2KHR.adoc[]
--

[open,refpage='VkDisplayModeProperties2KHR',desc='Structure describing an available display mode',type='structs']
--
The sname:VkDisplayModeProperties2KHR structure is defined as:

include::{generated}/api/structs/VkDisplayModeProperties2KHR.adoc[]

  * pname:sType is a elink:VkStructureType value identifying this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:displayModeProperties is a slink:VkDisplayModePropertiesKHR
    structure.

include::{generated}/validity/structs/VkDisplayModeProperties2KHR.adoc[]
--
endif::VK_KHR_get_display_properties2[]

[open,refpage='VkDisplayModeParametersKHR',desc='Structure describing display parameters associated with a display mode',type='structs']
--
The sname:VkDisplayModeParametersKHR structure is defined as:

include::{generated}/api/structs/VkDisplayModeParametersKHR.adoc[]

  * pname:visibleRegion is the 2D extents of the visible region.
  * pname:refreshRate is a code:uint32_t that is the number of times the
    display is refreshed each second multiplied by 1000.

[NOTE]
.Note
====
For example, a 60Hz display mode would report a pname:refreshRate of 60,000.
====

.Valid Usage
****
  * [[VUID-VkDisplayModeParametersKHR-width-01990]]
    The pname:width member of pname:visibleRegion must: be greater than `0`
  * [[VUID-VkDisplayModeParametersKHR-height-01991]]
    The pname:height member of pname:visibleRegion must: be greater than `0`
  * [[VUID-VkDisplayModeParametersKHR-refreshRate-01992]]
    pname:refreshRate must: be greater than `0`
****

include::{generated}/validity/structs/VkDisplayModeParametersKHR.adoc[]
--

[open,refpage='vkCreateDisplayModeKHR',desc='Create a display mode',type='protos']
--
:refpage: vkCreateDisplayModeKHR

Additional modes may: also be created by calling:

include::{generated}/api/protos/vkCreateDisplayModeKHR.adoc[]

  * pname:physicalDevice is the physical device associated with
    pname:display.
  * pname:display is the display to create an additional mode for.
  * pname:pCreateInfo is a pointer to a slink:VkDisplayModeCreateInfoKHR
    structure describing the new mode to create.
  * pname:pAllocator is the allocator used for host memory allocated for the
    display mode object when there is no more specific allocator available
    (see <<memory-allocation,Memory Allocation>>).
  * pname:pMode is a pointer to a slink:VkDisplayModeKHR handle in which the
    mode created is returned.

include::{chapters}/commonvalidity/no_dynamic_allocations_common.adoc[]

include::{generated}/validity/protos/vkCreateDisplayModeKHR.adoc[]
--

[open,refpage='VkDisplayModeCreateInfoKHR',desc='Structure specifying parameters of a newly created display mode object',type='structs']
--
The sname:VkDisplayModeCreateInfoKHR structure is defined as:

include::{generated}/api/structs/VkDisplayModeCreateInfoKHR.adoc[]

  * pname:sType is a elink:VkStructureType value identifying this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:flags is reserved for future use, and must: be zero.
  * pname:parameters is a slink:VkDisplayModeParametersKHR structure
    describing the display parameters to use in creating the new mode.
    If the parameters are not compatible with the specified display, the
    implementation must: return ename:VK_ERROR_INITIALIZATION_FAILED.

include::{generated}/validity/structs/VkDisplayModeCreateInfoKHR.adoc[]
--

[open,refpage='vkGetDisplayPlaneCapabilitiesKHR',desc='Query capabilities of a mode and plane combination',type='protos']
--
:refpage: vkGetDisplayPlaneCapabilitiesKHR

Applications that wish to present directly to a display must: select which
layer, or "`plane`" of the display they wish to target, and a mode to use
with the display.
Each display supports at least one plane.
The capabilities of a given mode and plane combination are determined by
calling:

include::{generated}/api/protos/vkGetDisplayPlaneCapabilitiesKHR.adoc[]

  * pname:physicalDevice is the physical device associated with the display
    specified by pname:mode
  * pname:mode is the display mode the application intends to program when
    using the specified plane.
    Note this parameter also implicitly specifies a display.
  * pname:planeIndex is the plane which the application intends to use with
    the display, and is less than the number of display planes supported by
    the device.
  * pname:pCapabilities is a pointer to a
    slink:VkDisplayPlaneCapabilitiesKHR structure in which the capabilities
    are returned.

include::{chapters}/commonvalidity/no_dynamic_allocations_common.adoc[]

include::{generated}/validity/protos/vkGetDisplayPlaneCapabilitiesKHR.adoc[]
--

[open,refpage='VkDisplayPlaneCapabilitiesKHR',desc='Structure describing capabilities of a mode and plane combination',type='structs']
--
The sname:VkDisplayPlaneCapabilitiesKHR structure is defined as:

include::{generated}/api/structs/VkDisplayPlaneCapabilitiesKHR.adoc[]

  * pname:supportedAlpha is a bitmask of
    elink:VkDisplayPlaneAlphaFlagBitsKHR describing the supported alpha
    blending modes.
  * pname:minSrcPosition is the minimum source rectangle offset supported by
    this plane using the specified mode.
  * pname:maxSrcPosition is the maximum source rectangle offset supported by
    this plane using the specified mode.
    The pname:x and pname:y components of pname:maxSrcPosition must: each be
    greater than or equal to the pname:x and pname:y components of
    pname:minSrcPosition, respectively.
  * pname:minSrcExtent is the minimum source rectangle size supported by
    this plane using the specified mode.
  * pname:maxSrcExtent is the maximum source rectangle size supported by
    this plane using the specified mode.
  * pname:minDstPosition, pname:maxDstPosition, pname:minDstExtent,
    pname:maxDstExtent all have similar semantics to their corresponding
    ptext:*Src* equivalents, but apply to the output region within the mode
    rather than the input region within the source image.
    Unlike the ptext:*Src* offsets, pname:minDstPosition and
    pname:maxDstPosition may: contain negative values.

The minimum and maximum position and extent fields describe the
implementation limits, if any, as they apply to the specified display mode
and plane.
Vendors may: support displaying a subset of a swapchain's presentable images
on the specified display plane.
This is expressed by returning pname:minSrcPosition, pname:maxSrcPosition,
pname:minSrcExtent, and pname:maxSrcExtent values that indicate a range of
possible positions and sizes which may: be used to specify the region within
the presentable images that source pixels will be read from when creating a
swapchain on the specified display mode and plane.

Vendors may: also support mapping the presentable images`' content to a
subset or superset of the visible region in the specified display mode.
This is expressed by returning pname:minDstPosition, pname:maxDstPosition,
pname:minDstExtent and pname:maxDstExtent values that indicate a range of
possible positions and sizes which may: be used to describe the region
within the display mode that the source pixels will be mapped to.

Other vendors may: support only a 1-1 mapping between pixels in the
presentable images and the display mode.
This may: be indicated by returning [eq]#(0,0)# for pname:minSrcPosition,
pname:maxSrcPosition, pname:minDstPosition, and pname:maxDstPosition, and
(display mode width, display mode height) for pname:minSrcExtent,
pname:maxSrcExtent, pname:minDstExtent, and pname:maxDstExtent.

The value pname:supportedAlpha must: contain at least one valid
elink:VkDisplayPlaneAlphaFlagBitsKHR bit.

These values indicate the limits of the implementation's individual fields.
Not all combinations of values within the offset and extent ranges returned
in sname:VkDisplayPlaneCapabilitiesKHR are guaranteed to be supported.
Presentation requests specifying unsupported combinations may: fail.

include::{generated}/validity/structs/VkDisplayPlaneCapabilitiesKHR.adoc[]
--

ifdef::VK_KHR_get_display_properties2[]
[open,refpage='vkGetDisplayPlaneCapabilities2KHR',desc='Query capabilities of a mode and plane combination',type='protos']
--
:refpage: vkGetDisplayPlaneCapabilities2KHR

To query the capabilities of a given mode and plane combination, call:

include::{generated}/api/protos/vkGetDisplayPlaneCapabilities2KHR.adoc[]

  * pname:physicalDevice is the physical device associated with
    pname:pDisplayPlaneInfo.
  * pname:pDisplayPlaneInfo is a pointer to a slink:VkDisplayPlaneInfo2KHR
    structure describing the plane and mode.
  * pname:pCapabilities is a pointer to a
    slink:VkDisplayPlaneCapabilities2KHR structure in which the capabilities
    are returned.

fname:vkGetDisplayPlaneCapabilities2KHR behaves similarly to
flink:vkGetDisplayPlaneCapabilitiesKHR, with the ability to specify extended
inputs via chained input structures, and to return extended information via
chained output structures.

include::{chapters}/commonvalidity/no_dynamic_allocations_common.adoc[]

include::{generated}/validity/protos/vkGetDisplayPlaneCapabilities2KHR.adoc[]
--

[open,refpage='VkDisplayPlaneInfo2KHR',desc='Structure defining the intended configuration of a display plane',type='structs']
--
The sname:VkDisplayPlaneInfo2KHR structure is defined as:

include::{generated}/api/structs/VkDisplayPlaneInfo2KHR.adoc[]

  * pname:sType is a elink:VkStructureType value identifying this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:mode is the display mode the application intends to program when
    using the specified plane.

[NOTE]
.Note
====
This parameter also implicitly specifies a display.
====

  * pname:planeIndex is the plane which the application intends to use with
    the display.

The members of sname:VkDisplayPlaneInfo2KHR correspond to the arguments to
flink:vkGetDisplayPlaneCapabilitiesKHR, with pname:sType and pname:pNext
added for extensibility.

include::{generated}/validity/structs/VkDisplayPlaneInfo2KHR.adoc[]
--

[open,refpage='VkDisplayPlaneCapabilities2KHR',desc='Structure describing the capabilities of a mode and plane combination',type='structs']
--
The sname:VkDisplayPlaneCapabilities2KHR structure is defined as:

include::{generated}/api/structs/VkDisplayPlaneCapabilities2KHR.adoc[]

  * pname:sType is a elink:VkStructureType value identifying this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:capabilities is a slink:VkDisplayPlaneCapabilitiesKHR structure.

include::{generated}/validity/structs/VkDisplayPlaneCapabilities2KHR.adoc[]
--
endif::VK_KHR_get_display_properties2[]

ifdef::VK_EXT_display_control[]
include::{chapters}/VK_EXT_display_control/display_control.adoc[]
endif::VK_EXT_display_control[]


[[wsi-display-surfaces]]
=== Display Surfaces

[open,refpage='vkCreateDisplayPlaneSurfaceKHR',desc='Create a slink:VkSurfaceKHR structure representing a display plane and mode',type='protos']
--
:refpage: vkCreateDisplayPlaneSurfaceKHR

A complete display configuration includes a mode, one or more display planes
and any parameters describing their behavior, and parameters describing some
aspects of the images associated with those planes.
Display surfaces describe the configuration of a single plane within a
complete display configuration.
To create a sname:VkSurfaceKHR object for a display plane, call:

include::{generated}/api/protos/vkCreateDisplayPlaneSurfaceKHR.adoc[]

  * pname:instance is the instance corresponding to the physical device the
    targeted display is on.
  * pname:pCreateInfo is a pointer to a slink:VkDisplaySurfaceCreateInfoKHR
    structure specifying which mode, plane, and other parameters to use, as
    described below.
  * pname:pAllocator is the allocator used for host memory allocated for the
    surface object when there is no more specific allocator available (see
    <<memory-allocation,Memory Allocation>>).
  * pname:pSurface is a pointer to a slink:VkSurfaceKHR handle in which the
    created surface is returned.

include::{generated}/validity/protos/vkCreateDisplayPlaneSurfaceKHR.adoc[]
--

[open,refpage='VkDisplaySurfaceCreateInfoKHR',desc='Structure specifying parameters of a newly created display plane surface object',type='structs']
--
The sname:VkDisplaySurfaceCreateInfoKHR structure is defined as:

include::{generated}/api/structs/VkDisplaySurfaceCreateInfoKHR.adoc[]

  * pname:sType is a elink:VkStructureType value identifying this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:flags is reserved for future use, and must: be zero.
  * pname:displayMode is a slink:VkDisplayModeKHR handle specifying the mode
    to use when displaying this surface.
  * pname:planeIndex is the plane on which this surface appears.
  * pname:planeStackIndex is the z-order of the plane.
  * pname:transform is a elink:VkSurfaceTransformFlagBitsKHR value
    specifying the transformation to apply to images as part of the scanout
    operation.
  * pname:globalAlpha is the global alpha value.
    This value is ignored if pname:alphaMode is not
    ename:VK_DISPLAY_PLANE_ALPHA_GLOBAL_BIT_KHR.
  * pname:alphaMode is a elink:VkDisplayPlaneAlphaFlagBitsKHR value
    specifying the type of alpha blending to use.
  * pname:imageExtent is the size of the presentable images to use with the
    surface.

[NOTE]
.Note
====
Creating a display surface must: not modify the state of the displays,
planes, or other resources it names.
For example, it must: not apply the specified mode to be set on the
associated display.
Application of display configuration occurs as a side effect of presenting
to a display surface.
====

.Valid Usage
****
  * [[VUID-VkDisplaySurfaceCreateInfoKHR-planeIndex-01252]]
    pname:planeIndex must: be less than the number of display planes
    supported by the device as determined by calling
    fname:vkGetPhysicalDeviceDisplayPlanePropertiesKHR
  * [[VUID-VkDisplaySurfaceCreateInfoKHR-planeReorderPossible-01253]]
    If the pname:planeReorderPossible member of the
    sname:VkDisplayPropertiesKHR structure returned by
    fname:vkGetPhysicalDeviceDisplayPropertiesKHR for the display
    corresponding to pname:displayMode is ename:VK_TRUE then
    pname:planeStackIndex must: be less than the number of display planes
    supported by the device as determined by calling
    fname:vkGetPhysicalDeviceDisplayPlanePropertiesKHR; otherwise
    pname:planeStackIndex must: equal the pname:currentStackIndex member of
    sname:VkDisplayPlanePropertiesKHR returned by
    fname:vkGetPhysicalDeviceDisplayPlanePropertiesKHR for the display plane
    corresponding to pname:displayMode
  * [[VUID-VkDisplaySurfaceCreateInfoKHR-alphaMode-01254]]
    If pname:alphaMode is ename:VK_DISPLAY_PLANE_ALPHA_GLOBAL_BIT_KHR then
    pname:globalAlpha must: be between `0` and `1`, inclusive
  * [[VUID-VkDisplaySurfaceCreateInfoKHR-alphaMode-01255]]
    pname:alphaMode must: be one of the bits present in the
    pname:supportedAlpha member of sname:VkDisplayPlaneCapabilitiesKHR for
    the display plane corresponding to pname:displayMode
  * [[VUID-VkDisplaySurfaceCreateInfoKHR-transform-06740]]
    pname:transform must: be one of the bits present in the
    pname:supportedTransforms member of sname:VkDisplayPropertiesKHR for the
    display corresponding to pname:displayMode
  * [[VUID-VkDisplaySurfaceCreateInfoKHR-width-01256]]
    The pname:width and pname:height members of pname:imageExtent must: be
    less than or equal to
    slink:VkPhysicalDeviceLimits::pname:maxImageDimension2D
****

include::{generated}/validity/structs/VkDisplaySurfaceCreateInfoKHR.adoc[]
--

[open,refpage='VkDisplaySurfaceCreateFlagsKHR',desc='Reserved for future use',type='flags']
--
include::{generated}/api/flags/VkDisplaySurfaceCreateFlagsKHR.adoc[]

tname:VkDisplaySurfaceCreateFlagsKHR is a bitmask type for setting a mask,
but is currently reserved for future use.
--

[open,refpage='VkDisplayPlaneAlphaFlagBitsKHR',desc='Alpha blending type',type='enums']
--
Bits which can: be set in
slink:VkDisplaySurfaceCreateInfoKHR::pname:alphaMode, specifying the type of
alpha blending to use on a display, are:

include::{generated}/api/enums/VkDisplayPlaneAlphaFlagBitsKHR.adoc[]

  * ename:VK_DISPLAY_PLANE_ALPHA_OPAQUE_BIT_KHR specifies that the source
    image will be treated as opaque.
  * ename:VK_DISPLAY_PLANE_ALPHA_GLOBAL_BIT_KHR specifies that a global
    alpha value must: be specified that will be applied to all pixels in the
    source image.
  * ename:VK_DISPLAY_PLANE_ALPHA_PER_PIXEL_BIT_KHR specifies that the alpha
    value will be determined by the alpha component of the source image's
    pixels.
    If the source format contains no alpha values, no blending will be
    applied.
    The source alpha values are not premultiplied into the source image's
    other color components.
  * ename:VK_DISPLAY_PLANE_ALPHA_PER_PIXEL_PREMULTIPLIED_BIT_KHR is
    equivalent to ename:VK_DISPLAY_PLANE_ALPHA_PER_PIXEL_BIT_KHR, except the
    source alpha values are assumed to be premultiplied into the source
    image's other color components.
--

[open,refpage='VkDisplayPlaneAlphaFlagsKHR',desc='Bitmask of VkDisplayPlaneAlphaFlagBitsKHR',type='flags']
--
include::{generated}/api/flags/VkDisplayPlaneAlphaFlagsKHR.adoc[]

tname:VkDisplayPlaneAlphaFlagsKHR is a bitmask type for setting a mask of
zero or more elink:VkDisplayPlaneAlphaFlagBitsKHR.
--