496 lines
22 KiB
Plaintext
496 lines
22 KiB
Plaintext
// Copyright (c) 2014-2016 The Khronos Group Inc.
|
|
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
|
|
|
|
[[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_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 [eq]#[0, 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.
|
|
|
|
.Valid Usage
|
|
****
|
|
* pname:planeIndex must: be less than the number of display planes
|
|
supported by the device as determined by calling
|
|
fname:vkGetPhysicalDeviceDisplayPlanePropertiesKHR
|
|
****
|
|
|
|
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 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.
|
|
====
|
|
|
|
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.
|
|
* 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.
|
|
|
|
.Valid Usage
|
|
****
|
|
* The pname:width and pname:height members of the pname:visibleRegion
|
|
member of pname:parameters must: be greater than `0`
|
|
* The pname:refreshRate member of pname:parameters must: be greater than
|
|
`0`
|
|
****
|
|
|
|
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 [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.
|
|
|
|
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 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.
|
|
* 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.
|
|
====
|
|
|
|
.Valid Usage
|
|
****
|
|
* pname:planeIndex must: be less than the number of display planes
|
|
supported by the device as determined by calling
|
|
fname:vkGetPhysicalDeviceDisplayPlanePropertiesKHR
|
|
* 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
|
|
* If pname:alphaMode is ename:VK_DISPLAY_PLANE_ALPHA_GLOBAL_BIT_KHR then
|
|
pname:globalAlpha must: be between `0` and `1`, inclusive
|
|
* pname:alphaMode must: be `0` or one of the bits present in the
|
|
pname:supportedAlpha member of sname:VkDisplayPlaneCapabilitiesKHR
|
|
returned by fname:vkGetDisplayPlaneCapabilitiesKHR for the display plane
|
|
corresponding to pname:displayMode
|
|
* The pname:width and pname:height members of pname:imageExtent must: be
|
|
less than the pname:maxImageDimensions2D member of
|
|
sname:VkPhysicalDeviceLimits
|
|
****
|
|
|
|
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
|