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 VkSurface
objects that target
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:
VkResult vkGetPhysicalDeviceDisplayPropertiesKHR( VkPhysicalDevice physicalDevice, uint32_t* pPropertyCount, VkDisplayPropertiesKHR* pProperties);
physicalDevice
is a physical device.
pPropertyCount
is a pointer to an integer related to the number of
display devices available or queried, as described below.
pProperties
is either NULL
or a pointer to an array of
VkDisplayPropertiesKHR
structures.
If pProperties
is NULL
, then the number of display devices available
for physicalDevice
is returned in pPropertyCount
.
Otherwise, pPropertyCount
must point to a variable set by the user to
the number of elements in the pProperties
array, and on return the
variable is overwritten with the number of structures actually written to
pProperties
.
If the value of pPropertyCount
is less than the number of display
devices for physicalDevice
, at most pPropertyCount
structures
will be written.
If pPropertyCount
is smaller than the number of display devices
available for physicalDevice
, VK_INCOMPLETE
will be returned
instead of VK_SUCCESS
to indicate that not all the available values
were returned.
The VkDisplayPropertiesKHR
structure is defined as:
typedef struct VkDisplayPropertiesKHR { VkDisplayKHR display; const char* displayName; VkExtent2D physicalDimensions; VkExtent2D physicalResolution; VkSurfaceTransformFlagsKHR supportedTransforms; VkBool32 planeReorderPossible; VkBool32 persistentContent; } VkDisplayPropertiesKHR;
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.
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.
physicalDimensions
describes the physical width and height of the
visible portion of the display, in millimeters.
physicalResolution
describes the physical, native, or preferred
resolution of the display.
![]() | Note |
---|---|
For devices which have no natural value to return here, implementations should return the maximum resolution supported. |
supportedTransforms
tells which transforms are supported by this
display.
This will contain one or more of the bits from
VkSurfaceTransformFlagsKHR
.
planeReorderPossible
tells whether the planes on this display can
have their z order changed.
If this is VK_TRUE
, the application can re-arrange the planes on
this display in any order relative to each other.
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 |
---|---|
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. |
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:
VkResult vkGetPhysicalDeviceDisplayPlanePropertiesKHR( VkPhysicalDevice physicalDevice, uint32_t* pPropertyCount, VkDisplayPlanePropertiesKHR* pProperties);
physicalDevice
is a physical device.
pPropertyCount
is a pointer to an integer related to the number of
display planes available or queried, as described below.
pProperties
is either NULL
or a pointer to an array of
VkDisplayPlanePropertiesKHR
structures.
If pProperties
is NULL
, then the number of display planes available
for physicalDevice
is returned in pPropertyCount
.
Otherwise, pPropertyCount
must point to a variable set by the user to
the number of elements in the pProperties
array, and on return the
variable is overwritten with the number of structures actually written to
pProperties
.
If the value of pPropertyCount
is less than the number of display
planes for physicalDevice
, at most pPropertyCount
structures
will be written.
The VkDisplayPlanePropertiesKHR
structure is defined as:
typedef struct VkDisplayPlanePropertiesKHR { VkDisplayKHR currentDisplay; uint32_t currentStackIndex; } VkDisplayPlanePropertiesKHR;
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
VK_NULL_HANDLE
.
currentStackIndex
is the current z-order of the plane.
This will be between 0 and the value returned by
vkGetPhysicalDeviceDisplayPlanePropertiesKHR
() in
pPropertyCount
.
To determine which displays a plane is usable with, call
VkResult vkGetDisplayPlaneSupportedDisplaysKHR( VkPhysicalDevice physicalDevice, uint32_t planeIndex, uint32_t* pDisplayCount, VkDisplayKHR* pDisplays);
physicalDevice
is a physical device.
planeIndex
is the plane which the application wishes to use, and
must be in the range [0, physical device plane count - 1].
pDisplayCount
is a pointer to an integer related to the number of
display planes available or queried, as described below.
pDisplays
is either NULL
or a pointer to an array of
VkDisplayKHR
structures.
If pDisplays
is NULL
, then the number of displays usable with the
specified planeIndex
for physicalDevice
is returned in
pDisplayCount
.
Otherwise, pDisplayCount
must point to a variable set by the user to
the number of elements in the pDisplays
array, and on return the
variable is overwritten with the number of structures actually written to
pDisplays
.
If the value of pDisplayCount
is less than the number of display
planes for physicalDevice
, at most pDisplayCount
structures will
be written.
If pDisplayCount
is smaller than the number of displays usable with
the specified planeIndex
for physicalDevice
, VK_INCOMPLETE
will be returned instead of VK_SUCCESS
to indicate that not all the
available values were returned.
Additional properties of displays are queried using specialized query functions.
Each display has one or more supported modes associated with it by default. These built-in modes are queried by calling:
VkResult vkGetDisplayModePropertiesKHR( VkPhysicalDevice physicalDevice, VkDisplayKHR display, uint32_t* pPropertyCount, VkDisplayModePropertiesKHR* pProperties);
physicalDevice
is the physical device associated with
display
.
display
is the display to query.
pPropertyCount
is a pointer to an integer related to the number of
display modes available or queried, as described below.
pProperties
is either NULL
or a pointer to an array of
VkDisplayModePropertiesKHR
structures.
If pProperties
is NULL
, then the number of display modes available
on the specified display
for physicalDevice
is returned in
pPropertyCount
.
Otherwise, pPropertyCount
must point to a variable set by the user to
the number of elements in the pProperties
array, and on return the
variable is overwritten with the number of structures actually written to
pProperties
.
If the value of pPropertyCount
is less than the number of display
modes for physicalDevice
, at most pPropertyCount
structures will
be written.
If pPropertyCount
is smaller than the number of display modes
available on the specified display
for physicalDevice
,
VK_INCOMPLETE
will be returned instead of VK_SUCCESS
to indicate
that not all the available values were returned.
The VkDisplayModePropertiesKHR
structure is defined as:
typedef struct VkDisplayModePropertiesKHR { VkDisplayModeKHR displayMode; VkDisplayModeParametersKHR parameters; } VkDisplayModePropertiesKHR;
displayMode
is a handle to the display mode described in this
structure.
This handle will be valid for the lifetime of the Vulkan instance.
parameters
is a VkDisplayModeParametersKHR
structure
describing the display parameters associated with displayMode
.
The VkDisplayModeParametersKHR
structure is defined as:
typedef struct VkDisplayModeParametersKHR { VkExtent2D visibleRegion; uint32_t refreshRate; } VkDisplayModeParametersKHR;
visibleRegion
is the 2D extents of the visible region.
refreshRate
is a uint32_t
that is the number of times the
display is refreshed each second multiplied by 1000.
![]() | Note |
---|---|
For example, a 60Hz display mode would report a |
Additional modes may also be created by calling:
VkResult vkCreateDisplayModeKHR( VkPhysicalDevice physicalDevice, VkDisplayKHR display, const VkDisplayModeCreateInfoKHR* pCreateInfo, const VkAllocationCallbacks* pAllocator, VkDisplayModeKHR* pMode);
physicalDevice
is the physical device associated with
display
.
display
is the display to create an additional mode for.
pCreateInfo
is a VkDisplayModeCreateInfoKHR
structure
describing the new mode to create.
pAllocator
is the allocator used for host memory allocated for the
surface object when there is no more specific allocator available (see
Memory Allocation).
pMode
returns the handle of the mode created.
The VkDisplayModeCreateInfoKHR
structure is defined as:
typedef struct VkDisplayModeCreateInfoKHR { VkStructureType sType; const void* pNext; VkDisplayModeCreateFlagsKHR flags; VkDisplayModeParametersKHR parameters; } VkDisplayModeCreateInfoKHR;
sType
is the type of this structure.
pNext
is NULL
or a pointer to an extension-specific structure.
flags
is reserved for future use, and must be zero.
parameters
is a 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 VK_ERROR_INITIALIZATION_FAILED
.
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:
VkResult vkGetDisplayPlaneCapabilitiesKHR( VkPhysicalDevice physicalDevice, VkDisplayModeKHR mode, uint32_t planeIndex, VkDisplayPlaneCapabilitiesKHR* pCapabilities);
physicalDevice
is the physical device associated with
display
mode
is the display mode the application intends to program when
using the specified plane.
Note this parameter also implicitly specifies a display.
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.
pCapabilities
is a pointer to a
VkDisplayPlaneCapabilitiesKHR
structure in which the capabilities
are returned.
The VkDisplayPlaneCapabilitiesKHR
structure is defined as:
typedef struct VkDisplayPlaneCapabilitiesKHR { VkDisplayPlaneAlphaFlagsKHR supportedAlpha; VkOffset2D minSrcPosition; VkOffset2D maxSrcPosition; VkExtent2D minSrcExtent; VkExtent2D maxSrcExtent; VkOffset2D minDstPosition; VkOffset2D maxDstPosition; VkExtent2D minDstExtent; VkExtent2D maxDstExtent; } VkDisplayPlaneCapabilitiesKHR;
supportedAlpha
is a bitmask of
VkDisplayPlaneAlphaFlagBitsKHR
describing the supported alpha
blending modes.
minSrcPosition
is the minimum source rectangle offset supported by
this plane using the specified mode.
maxSrcPosition
is the maximum source rectangle offset supported by
this plane using the specified mode.
The x
and y
components of maxSrcPosition
must each be
greater than or equal to the x
and y
components of
minSrcPosition
, respectively.
minSrcExtent
is the minimum source rectangle size supported by
this plane using the specified mode.
maxSrcExtent
is the maximum source rectangle size supported by
this plane using the specified mode.
minDstPosition
, maxDstPosition
, minDstExtent
,
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, minDstPosition
and 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 minSrcPosition
, maxSrcPosition
,
minSrcExtent
, and 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 minDstPosition
, maxDstPosition
,
minDstExtent
and 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 minSrcPosition
,
maxSrcPosition
, minDstPosition
, and maxDstPosition
, and
(display mode width, display mode height) for minSrcExtent
,
maxSrcExtent
, minDstExtent
, and 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 VkDisplayPlaneCapabilitiesKHR
are guaranteed to be supported.
Vendors may still fail presentation requests that specify unsupported
combinations.
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 VkSurfaceKHR
structure for a display surface, call:
VkResult vkCreateDisplayPlaneSurfaceKHR( VkInstance instance, const VkDisplaySurfaceCreateInfoKHR* pCreateInfo, const VkAllocationCallbacks* pAllocator, VkSurfaceKHR* pSurface);
instance
is the instance corresponding to the physical device the
targeted display is on.
pCreateInfo
is a pointer to an instance of the
VkDisplaySurfaceCreateInfoKHR
structure specifying which mode,
plane, and other parameters to use, as described below.
pAllocator
is the allocator used for host memory allocated for the
surface object when there is no more specific allocator available (see
Memory Allocation).
pSurface
points to a VkSurfaceKHR
handle in which the
created surface is returned.
The VkDisplaySurfaceCreateInfoKHR
structure is defined as:
typedef struct VkDisplaySurfaceCreateInfoKHR { VkStructureType sType; const void* pNext; VkDisplaySurfaceCreateFlagsKHR flags; VkDisplayModeKHR displayMode; uint32_t planeIndex; uint32_t planeStackIndex; VkSurfaceTransformFlagBitsKHR transform; float globalAlpha; VkDisplayPlaneAlphaFlagBitsKHR alphaMode; VkExtent2D imageExtent; } VkDisplaySurfaceCreateInfoKHR;
sType
is the type of this structure.
pNext
is NULL
or a pointer to an extension-specific structure.
flags
is reserved for future use, and must be zero.
displayMode
is the mode to use when displaying this surface.
planeIndex
is the plane on which this surface appears.
planeStackIndex
is the z-order of the plane.
transform
is the transform to apply to the images as part of the
scanout operation.
globalAlpha
is the global alpha value.
This value is ignored if alphaMode
is not
VK_DISPLAY_PLANE_ALPHA_GLOBAL_BIT_KHR
.
alphaMode
is the type of alpha blending to use.
imageSize
The size of the presentable images to use with the
surface.
![]() | 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. |
Types of alpha blending supported by or used on a display are defined by the
bitmask VkDisplayPlaneAlphaFlagBitsKHR
, which contains the following
values:
typedef enum VkDisplayPlaneAlphaFlagBitsKHR { VK_DISPLAY_PLANE_ALPHA_OPAQUE_BIT_KHR = 0x00000001, VK_DISPLAY_PLANE_ALPHA_GLOBAL_BIT_KHR = 0x00000002, VK_DISPLAY_PLANE_ALPHA_PER_PIXEL_BIT_KHR = 0x00000004, VK_DISPLAY_PLANE_ALPHA_PER_PIXEL_PREMULTIPLIED_BIT_KHR = 0x00000008, } VkDisplayPlaneAlphaFlagBitsKHR;
These values are described as follows:
VK_DISPLAY_PLANE_ALPHA_OPAQUE_BIT_KHR
: The source image will be
treated as opaque.
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.
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.
VK_DISPLAY_PLANE_ALPHA_PER_PIXEL_PREMULTIPLIED_BIT_KHR
: This is
equivalent to 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.