437 lines
20 KiB
Plaintext
437 lines
20 KiB
Plaintext
[[display,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
|
|
VK_EXT_KHR_display extension provides the functionality necessary to
|
|
enumerate display devices and create sname:VkSurface objects that target
|
|
displays.
|
|
|
|
|
|
=== Display Enumeration
|
|
|
|
// refBegin vkGetPhysicalDeviceDisplayPropertiesKHR - Query information about the available displays
|
|
|
|
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::../../api/protos/vkGetPhysicalDeviceDisplayPropertiesKHR.txt[]
|
|
|
|
* 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.
|
|
If pname:pPropertyCount is smaller than the number of display devices
|
|
available for pname:physicalDevice, ename:VK_INCOMPLETE will be returned
|
|
instead of ename:VK_SUCCESS to indicate that not all the available values
|
|
were returned.
|
|
|
|
include::../../validity/protos/vkGetPhysicalDeviceDisplayPropertiesKHR.txt[]
|
|
|
|
// refBegin VkDisplayPropertiesKHR - Structure describing an available display device
|
|
|
|
The sname:VkDisplayPropertiesKHR structure is defined as:
|
|
|
|
include::../../api/structs/VkDisplayPropertiesKHR.txt[]
|
|
|
|
* 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 a pointer to a NULL-terminated string containing
|
|
the name of the display. Generally, this will be the name provided by
|
|
the display's EDID. It can: be `NULL` if no suitable name is available.
|
|
* 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 tells which transforms are supported by this
|
|
display. This will contain one or more of the bits from
|
|
sname:VkSurfaceTransformFlagsKHR.
|
|
* 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::../../validity/structs/VkDisplayPropertiesKHR.txt[]
|
|
|
|
|
|
==== Display Planes
|
|
|
|
// refBegin vkGetPhysicalDeviceDisplayPlanePropertiesKHR - Query the plane properties
|
|
|
|
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::../../api/protos/vkGetPhysicalDeviceDisplayPlanePropertiesKHR.txt[]
|
|
|
|
* 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::../../validity/protos/vkGetPhysicalDeviceDisplayPlanePropertiesKHR.txt[]
|
|
|
|
// refBegin VkDisplayPlanePropertiesKHR - Structure describing display plane properties
|
|
|
|
The sname:VkDisplayPlanePropertiesKHR structure is defined as:
|
|
|
|
include::../../api/structs/VkDisplayPlanePropertiesKHR.txt[]
|
|
|
|
* 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 sname: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::../../validity/structs/VkDisplayPlanePropertiesKHR.txt[]
|
|
|
|
// refBegin vkGetDisplayPlaneSupportedDisplaysKHR - Query the list of displays a plane supports
|
|
|
|
To determine which displays a plane is usable with, call
|
|
|
|
include::../../api/protos/vkGetDisplayPlaneSupportedDisplaysKHR.txt[]
|
|
|
|
* pname:physicalDevice is a physical device.
|
|
* pname:planeIndex is the plane which the application wishes to use, and
|
|
must: be in the range latexmath:[$[0, \mathit{physical device plane
|
|
count}-1\]$].
|
|
* pname:pDisplayCount is a pointer to an integer related to the number of
|
|
display planes available or queried, as described below.
|
|
* pname:pDisplays is either `NULL` or a pointer to an array of
|
|
sname:VkDisplayKHR structures.
|
|
|
|
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
|
|
structures actually written to pname:pDisplays. If the value of
|
|
pname:pDisplayCount is less than the number of display planes for
|
|
pname:physicalDevice, at most pname:pDisplayCount structures will be
|
|
written. If pname:pDisplayCount is smaller than the number of displays
|
|
usable with the specified pname:planeIndex for pname:physicalDevice,
|
|
ename:VK_INCOMPLETE will be returned instead of ename:VK_SUCCESS to indicate
|
|
that not all the available values were returned.
|
|
|
|
include::../../validity/protos/vkGetDisplayPlaneSupportedDisplaysKHR.txt[]
|
|
|
|
Additional properties of displays are queried using specialized query
|
|
functions.
|
|
|
|
|
|
==== Display Modes
|
|
|
|
// refBegin vkGetDisplayModePropertiesKHR - Query the set of mode properties supported by the display
|
|
|
|
Each display has one or more supported modes associated with it
|
|
by default. These built-in modes are queried by calling:
|
|
|
|
include::../../api/protos/vkGetDisplayModePropertiesKHR.txt[]
|
|
|
|
* 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. If pname:pPropertyCount is smaller than the number of display modes
|
|
available on the specified pname:display for pname:physicalDevice,
|
|
ename:VK_INCOMPLETE will be returned instead of ename:VK_SUCCESS to indicate
|
|
that not all the available values were returned.
|
|
|
|
include::../../validity/protos/vkGetDisplayModePropertiesKHR.txt[]
|
|
|
|
// refBegin VkDisplayModePropertiesKHR - Structure describing display mode properties
|
|
|
|
The sname:VkDisplayModePropertiesKHR structure is defined as:
|
|
|
|
include::../../api/structs/VkDisplayModePropertiesKHR.txt[]
|
|
|
|
* 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 sname:VkDisplayModeParametersKHR structure
|
|
describing the display parameters associated with pname:displayMode.
|
|
|
|
include::../../validity/structs/VkDisplayModePropertiesKHR.txt[]
|
|
|
|
// refBegin VkDisplayModeParametersKHR - Structure describing display parameters associated with a display mode
|
|
|
|
The sname:VkDisplayModeParametersKHR structure is defined as:
|
|
|
|
include::../../api/structs/VkDisplayModeParametersKHR.txt[]
|
|
|
|
* pname:visibleRegion is the 2D extents of the visible region.
|
|
* pname:refreshRate is a basetype: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.
|
|
====
|
|
|
|
include::../../validity/structs/VkDisplayModeParametersKHR.txt[]
|
|
|
|
// refBegin vkCreateDisplayModeKHR - Create a display mode
|
|
|
|
Additional modes may: also be created by calling:
|
|
|
|
include::../../api/protos/vkCreateDisplayModeKHR.txt[]
|
|
|
|
* 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 slink:VkDisplayModeCreateInfoKHR structure
|
|
describing the new mode to create.
|
|
* 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:pMode returns the handle of the mode created.
|
|
|
|
include::../../validity/protos/vkCreateDisplayModeKHR.txt[]
|
|
|
|
// refBegin VkDisplayModeCreateInfoKHR - Structure specifying parameters of a newly created display mode object
|
|
|
|
The sname:VkDisplayModeCreateInfoKHR structure is defined as:
|
|
|
|
include::../../api/structs/VkDisplayModeCreateInfoKHR.txt[]
|
|
|
|
* pname:sType is the type of this structure and must: be
|
|
ename:VK_STRUCTURE_TYPE_DISPLAY_MODE_CREATE_INFO_KHR.
|
|
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
|
|
* pname:flags is reserved for future use, and must: be zero.
|
|
* pname:parameters is a sname: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::../../validity/structs/VkDisplayModeCreateInfoKHR.txt[]
|
|
|
|
// refBegin vkGetDisplayPlaneCapabilitiesKHR - Query capabilities of a mode and plane combination
|
|
|
|
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::../../api/protos/vkGetDisplayPlaneCapabilitiesKHR.txt[]
|
|
|
|
* pname:physicalDevice is the physical device associated with
|
|
pname:display
|
|
* 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::../../validity/protos/vkGetDisplayPlaneCapabilitiesKHR.txt[]
|
|
|
|
// refBegin VkDisplayPlaneCapabilitiesKHR - Structure describing capabilities of a mode and plane combination
|
|
|
|
The sname:VkDisplayPlaneCapabilitiesKHR structure is defined as:
|
|
|
|
include::../../api/structs/VkDisplayPlaneCapabilitiesKHR.txt[]
|
|
|
|
* 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
|
|
"Src" equivalents, but apply to the output region within the mode rather
|
|
than the input region within the source image. Unlike the "Src" offsets,
|
|
pname:minDstPosition and pname:maxDstPosition may: contain negative
|
|
values.
|
|
|
|
The minimum and maximum position and extent fields describe the hardware
|
|
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 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 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
|
|
(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.
|
|
|
|
These values indicate the limits of the hardware's individual fields. Not
|
|
all combinations of values within the offset and extent ranges returned in
|
|
sname:VkDisplayPlaneCapabilitiesKHR are guaranteed to be supported. Vendors
|
|
may: still fail presentation requests that specify unsupported combinations.
|
|
|
|
include::../../validity/structs/VkDisplayPlaneCapabilitiesKHR.txt[]
|
|
|
|
|
|
=== Display Surfaces
|
|
|
|
// refBegin vkCreateDisplayPlaneSurfaceKHR - Create a slink:VkSurfaceKHR structure representing a display plane and mode
|
|
|
|
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 structure for a display surface, call:
|
|
|
|
include::../../api/protos/vkCreateDisplayPlaneSurfaceKHR.txt[]
|
|
|
|
* pname:instance is the instance corresponding to the physical device the
|
|
targeted display is on.
|
|
* pname:pCreateInfo:pCreateInfo is a pointer to an instance of the
|
|
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 points to a sname:VkSurfaceKHR handle in which the
|
|
created surface is returned.
|
|
|
|
include::../../validity/protos/vkCreateDisplayPlaneSurfaceKHR.txt[]
|
|
|
|
// refBegin VkDisplaySurfaceCreateInfoKHR - Structure specifying parameters of a newly created display plane surface object
|
|
|
|
The sname:VkDisplaySurfaceCreateInfoKHR structure is defined as:
|
|
|
|
include::../../api/structs/VkDisplaySurfaceCreateInfoKHR.txt[]
|
|
|
|
* pname:sType is the type of this structure and must: be
|
|
ename:VK_STRUCTURE_TYPE_DISPLAY_SURFACE_CREATE_INFO_KHR.
|
|
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
|
|
* pname:flags is reserved for future use, and must: be zero.
|
|
* pname:displayMode is 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 the transform to apply to the 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 the type of alpha blending to use.
|
|
* pname:imageSize 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.
|
|
====
|
|
|
|
include::../../validity/structs/VkDisplaySurfaceCreateInfoKHR.txt[]
|
|
|
|
// refBegin VkDisplayPlaneAlphaFlagBitsKHR - alpha blending type
|
|
|
|
Types of alpha blending supported by or used on a display are defined by the
|
|
bitmask ename:VkDisplayPlaneAlphaFlagBitsKHR, which contains the following
|
|
values:
|
|
|
|
include::../../api/enums/VkDisplayPlaneAlphaFlagBitsKHR.txt[]
|
|
|
|
These values are described as follows:
|
|
|
|
* ename:VK_DISPLAY_PLANE_ALPHA_OPAQUE_BIT_KHR: The source image will be
|
|
treated as opaque.
|
|
* ename:VK_DISPLAY_PLANE_ALPHA_GLOBAL_BIT_KHR: 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: The alpha value will be
|
|
determined by the alpha channel 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 channels.
|
|
* ename:VK_DISPLAY_PLANE_ALPHA_PER_PIXEL_PREMULTIPLIED_BIT_KHR: This 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 channels.
|
|
|
|
// refEnd VkDisplayPlaneAlphaFlagBitsKHR
|