777 lines
32 KiB
Plaintext
777 lines
32 KiB
Plaintext
// Copyright (c) 2014-2019 Khronos Group. This work is licensed under a
|
|
// Creative Commons Attribution 4.0 International License; see
|
|
// http://creativecommons.org/licenses/by/4.0/
|
|
|
|
[[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: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.txt[]
|
|
|
|
--
|
|
|
|
[open,refpage='vkGetPhysicalDeviceDisplayPropertiesKHR',desc='Query information about the available displays',type='protos']
|
|
--
|
|
|
|
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.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::{generated}/validity/protos/vkGetPhysicalDeviceDisplayPropertiesKHR.txt[]
|
|
--
|
|
|
|
[open,refpage='VkDisplayPropertiesKHR',desc='Structure describing an available display device',type='structs']
|
|
--
|
|
|
|
The sname:VkDisplayPropertiesKHR structure is defined as:
|
|
|
|
include::{generated}/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.
|
|
If not `NULL`, the memory it points to must: remain accessible 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.txt[]
|
|
--
|
|
|
|
ifdef::VK_KHR_get_display_properties2[]
|
|
|
|
[open,refpage='vkGetPhysicalDeviceDisplayProperties2KHR',desc='Query information about the available displays',type='protos']
|
|
--
|
|
|
|
To query information about the available displays, call:
|
|
|
|
include::{generated}/api/protos/vkGetPhysicalDeviceDisplayProperties2KHR.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:VkDisplayProperties2KHR structures.
|
|
|
|
fname:vkGetPhysicalDeviceDisplayProperties2KHR behaves similarly to
|
|
flink:vkGetPhysicalDeviceDisplayPropertiesKHR, with the ability to return
|
|
extended information via chained output structures.
|
|
|
|
include::{generated}/validity/protos/vkGetPhysicalDeviceDisplayProperties2KHR.txt[]
|
|
--
|
|
|
|
[open,refpage='VkDisplayProperties2KHR',desc='Structure describing an available display device',type='structs']
|
|
--
|
|
|
|
The sname:VkDisplayProperties2KHR structure is defined as:
|
|
|
|
include::{generated}/api/structs/VkDisplayProperties2KHR.txt[]
|
|
|
|
* pname:sType is the type of this structure.
|
|
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
|
|
* pname:displayProperties is an instance of the
|
|
slink:VkDisplayPropertiesKHR structure.
|
|
|
|
include::{generated}/validity/structs/VkDisplayProperties2KHR.txt[]
|
|
--
|
|
|
|
endif::VK_KHR_get_display_properties2[]
|
|
|
|
ifdef::VK_EXT_direct_mode_display[]
|
|
include::../VK_EXT_direct_mode_display/acquire_release_displays.txt[]
|
|
endif::VK_EXT_direct_mode_display[]
|
|
|
|
|
|
==== Display Planes
|
|
|
|
[open,refpage='vkGetPhysicalDeviceDisplayPlanePropertiesKHR',desc='Query the plane properties',type='protos']
|
|
--
|
|
|
|
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.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::{generated}/validity/protos/vkGetPhysicalDeviceDisplayPlanePropertiesKHR.txt[]
|
|
--
|
|
|
|
[open,refpage='VkDisplayPlanePropertiesKHR',desc='Structure describing display plane properties',type='structs']
|
|
--
|
|
|
|
The sname:VkDisplayPlanePropertiesKHR structure is defined as:
|
|
|
|
include::{generated}/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
|
|
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.txt[]
|
|
--
|
|
|
|
ifdef::VK_KHR_get_display_properties2[]
|
|
|
|
[open,refpage='vkGetPhysicalDeviceDisplayPlaneProperties2KHR',desc='Query information about the available display planes.',type='protos']
|
|
--
|
|
|
|
To query the properties of a device's display planes, call:
|
|
|
|
include::{generated}/api/protos/vkGetPhysicalDeviceDisplayPlaneProperties2KHR.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:VkDisplayPlaneProperties2KHR structures.
|
|
|
|
fname:vkGetPhysicalDeviceDisplayPlaneProperties2KHR behaves similarly to
|
|
flink:vkGetPhysicalDeviceDisplayPlanePropertiesKHR, with the ability to
|
|
return extended information via chained output structures.
|
|
|
|
include::{generated}/validity/protos/vkGetPhysicalDeviceDisplayPlaneProperties2KHR.txt[]
|
|
--
|
|
|
|
[open,refpage='VkDisplayPlaneProperties2KHR',desc='Structure describing an available display plane',type='structs']
|
|
--
|
|
|
|
The sname:VkDisplayPlaneProperties2KHR structure is defined as:
|
|
|
|
include::{generated}/api/structs/VkDisplayPlaneProperties2KHR.txt[]
|
|
|
|
* pname:sType is the type of this structure.
|
|
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
|
|
* pname:displayPlaneProperties is an instance of the
|
|
slink:VkDisplayPlanePropertiesKHR structure.
|
|
|
|
include::{generated}/validity/structs/VkDisplayPlaneProperties2KHR.txt[]
|
|
--
|
|
|
|
endif::VK_KHR_get_display_properties2[]
|
|
|
|
[open,refpage='vkGetDisplayPlaneSupportedDisplaysKHR',desc='Query the list of displays a plane supports',type='protos']
|
|
--
|
|
|
|
To determine which displays a plane is usable with, call
|
|
|
|
include::{generated}/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
|
|
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 display
|
|
planes for pname:physicalDevice, at most pname:pDisplayCount handles 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
|
|
****
|
|
* [[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.txt[]
|
|
--
|
|
|
|
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.txt[]
|
|
|
|
--
|
|
|
|
[open,refpage='vkGetDisplayModePropertiesKHR',desc='Query the set of mode properties supported by the display',type='protos']
|
|
--
|
|
|
|
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.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::{generated}/validity/protos/vkGetDisplayModePropertiesKHR.txt[]
|
|
--
|
|
|
|
[open,refpage='VkDisplayModePropertiesKHR',desc='Structure describing display mode properties',type='structs']
|
|
--
|
|
|
|
The sname:VkDisplayModePropertiesKHR structure is defined as:
|
|
|
|
include::{generated}/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 slink:VkDisplayModeParametersKHR structure
|
|
describing the display parameters associated with pname:displayMode.
|
|
|
|
include::{generated}/validity/structs/VkDisplayModePropertiesKHR.txt[]
|
|
--
|
|
|
|
[open,refpage='VkDisplayModeCreateFlagsKHR',desc='Reserved for future use',type='flags']
|
|
--
|
|
include::{generated}/api/flags/VkDisplayModeCreateFlagsKHR.txt[]
|
|
|
|
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']
|
|
--
|
|
|
|
To query the properties of a device's built-in display modes, call:
|
|
|
|
include::{generated}/api/protos/vkGetDisplayModeProperties2KHR.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:VkDisplayModeProperties2KHR structures.
|
|
|
|
fname:vkGetDisplayModeProperties2KHR behaves similarly to
|
|
flink:vkGetDisplayModePropertiesKHR, with the ability to return extended
|
|
information via chained output structures.
|
|
|
|
include::{generated}/validity/protos/vkGetDisplayModeProperties2KHR.txt[]
|
|
--
|
|
|
|
[open,refpage='VkDisplayModeProperties2KHR',desc='Structure describing an available display mode',type='structs']
|
|
--
|
|
|
|
The sname:VkDisplayModeProperties2KHR structure is defined as:
|
|
|
|
include::{generated}/api/structs/VkDisplayModeProperties2KHR.txt[]
|
|
|
|
* pname:sType is the type of this structure.
|
|
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
|
|
* pname:displayModeProperties is an instance of the
|
|
slink:VkDisplayModePropertiesKHR structure.
|
|
|
|
include::{generated}/validity/structs/VkDisplayModeProperties2KHR.txt[]
|
|
--
|
|
|
|
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.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.
|
|
====
|
|
|
|
.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.txt[]
|
|
--
|
|
|
|
[open,refpage='vkCreateDisplayModeKHR',desc='Create a display mode',type='protos']
|
|
--
|
|
|
|
Additional modes may: also be created by calling:
|
|
|
|
include::{generated}/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
|
|
display mode object when there is no more specific allocator available
|
|
(see <<memory-allocation,Memory Allocation>>).
|
|
* pname:pMode returns the handle of the mode created.
|
|
|
|
include::{generated}/validity/protos/vkCreateDisplayModeKHR.txt[]
|
|
--
|
|
|
|
[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.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 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.txt[]
|
|
--
|
|
|
|
[open,refpage='vkGetDisplayPlaneCapabilitiesKHR',desc='Query capabilities of a mode and plane combination',type='protos']
|
|
--
|
|
|
|
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.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::{generated}/validity/protos/vkGetDisplayPlaneCapabilitiesKHR.txt[]
|
|
--
|
|
|
|
[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.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
|
|
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 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 implementation'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::{generated}/validity/structs/VkDisplayPlaneCapabilitiesKHR.txt[]
|
|
--
|
|
|
|
ifdef::VK_KHR_get_display_properties2[]
|
|
|
|
[open,refpage='vkGetDisplayPlaneCapabilities2KHR',desc='Query capabilities of a mode and plane combination',type='protos']
|
|
--
|
|
|
|
To query the capabilities of a given mode and plane combination, call:
|
|
|
|
include::{generated}/api/protos/vkGetDisplayPlaneCapabilities2KHR.txt[]
|
|
|
|
* pname:physicalDevice is the physical device associated with
|
|
pname:pDisplayPlaneInfo.
|
|
* pname:pDisplayPlaneInfo is a pointer to an instance of the
|
|
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::{generated}/validity/protos/vkGetDisplayPlaneCapabilities2KHR.txt[]
|
|
--
|
|
|
|
[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.txt[]
|
|
|
|
* pname:sType is the type of this structure.
|
|
* pname:pNext is `NULL` or a pointer to an extension-specific 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.txt[]
|
|
--
|
|
|
|
[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.txt[]
|
|
|
|
* pname:sType is the type of this structure.
|
|
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
|
|
* pname:capabilities is an instance of the
|
|
slink:VkDisplayPlaneCapabilitiesKHR structure.
|
|
|
|
include::{generated}/validity/structs/VkDisplayPlaneCapabilities2KHR.txt[]
|
|
--
|
|
|
|
endif::VK_KHR_get_display_properties2[]
|
|
|
|
ifdef::VK_EXT_display_control[]
|
|
include::../VK_EXT_display_control/display_control.txt[]
|
|
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']
|
|
--
|
|
|
|
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::{generated}/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 slink:VkSurfaceKHR handle in which the
|
|
created surface is returned.
|
|
|
|
include::{generated}/validity/protos/vkCreateDisplayPlaneSurfaceKHR.txt[]
|
|
--
|
|
|
|
[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.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 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 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 `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
|
|
* [[VUID-VkDisplaySurfaceCreateInfoKHR-width-01256]]
|
|
The pname:width and pname:height members of pname:imageExtent must: be
|
|
less than the pname:maxImageDimensions2D member of
|
|
sname:VkPhysicalDeviceLimits
|
|
****
|
|
|
|
include::{generated}/validity/structs/VkDisplaySurfaceCreateInfoKHR.txt[]
|
|
--
|
|
|
|
[open,refpage='VkDisplaySurfaceCreateFlagsKHR',desc='Reserved for future use',type='flags']
|
|
--
|
|
include::{generated}/api/flags/VkDisplaySurfaceCreateFlagsKHR.txt[]
|
|
|
|
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']
|
|
--
|
|
|
|
Possible values of slink:VkDisplaySurfaceCreateInfoKHR::pname:alphaMode,
|
|
specifying the type of alpha blending to use on a display, are:
|
|
|
|
include::{generated}/api/enums/VkDisplayPlaneAlphaFlagBitsKHR.txt[]
|
|
|
|
* 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 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 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.
|
|
|
|
--
|
|
|
|
[open,refpage='VkDisplayPlaneAlphaFlagsKHR',desc='Bitmask of VkDisplayPlaneAlphaFlagBitsKHR',type='flags']
|
|
--
|
|
include::{generated}/api/flags/VkDisplayPlaneAlphaFlagsKHR.txt[]
|
|
|
|
tname:VkDisplayPlaneAlphaFlagsKHR is a bitmask type for setting a mask of
|
|
zero or more elink:VkDisplayPlaneAlphaFlagBitsKHR.
|
|
--
|