mirror of
https://github.com/status-im/Vulkan-Docs.git
synced 2025-02-22 19:18:28 +00:00
ce60b9c887
* Vulkan 1.1 initial release. Bump API patch number and header version
number to 70 for this update. The patch number will be used for both
Vulkan 1.1 and Vulkan 1.0 updates, and continues to increment
continuously from the previous Vulkan 1.0.69 update.
NOTE: We are not publishing an updated 1.0.70 specification, or 1.1
reference pages, along with 1.1.70. There are still minor issues to work
out with those build targets. However, we will soon generate all three
types of documents as part of the regular spec update cycle.
NOTE: The GitHub KhronosGroup/Vulkan-Docs repository now maintains the
current specification in the `master` branch. The `1.0` branch is out of
date and will not be maintained, since we will be generating both 1.1
and 1.0 specifications from the `master` branch in the future.
Github Issues:
* Clarify how mapped memory ranges are flushed in
flink:vkFlushMappedMemoryRanges (public issue 127).
* Specify that <<synchronization-pipeline-stages, Pipeline Stages>> are a
list of tasks that each command performs, rather than necessarily being
discrete pieces of hardware that one task flows through. Add a
"`synchronization command`" pipeline type which all synchronization
command execute (it's just TOP + BOTTOM), with an explanatory note
(public issue 554).
Internal Issues:
* Regenerate all images used in the spec in Inkscape with a consistent
look-and-feel, and adjust image size attributes so they're all legible,
and not too large with respect to the spec body text (internal issue
701).
* Document in the <<extensions,extensions>> appendix and in the style
guide that `KHX` extensions are no longer supported or used in the
Vulkan 1.1 timeframe (internal issue 714).
* Remove the leftover equations_temp directory after PDF build completes
(internal issue 925).
* Update the <<credits, Credits (Informative)>> appendix to include
contributors to Vulkan 1.1, and to list them according to the API
version(s) they contributed to (internal issue 987).
* Add a NOTE to the introduction explaining that interfaces defined by
extensions which were promoted to Vulkan 1.1 are now expressed as
aliases of the Vulkan 1.1 type (internal issue 991).
* Instrument spec source conditionals so spec can be built with 1.1
features, extensions promoted to 1.1, or both (internal issues 992,
998).
* Modify the XML schema and tools to support explicit aliasing of types,
structures, and commands, and use this to express the promotion of 1.0
extensions to 1.1 core features, by making the extension interfaces
aliases of the core features they were promoted to. Mark up promoted
interfaces to allow still generating 1.0 + extension specifications
(internal issue 991).
* Platform names, along with corresponding preprocessor symbols to enable
extensions specific to those platforms, are now reserved in vk.xml using
the <platform> tag. Update the registry schema and schema specification
to match (internal issue 1011).
* Updated the <<textures-texel-replacement, Texel Replacement>> section to
clarify that reads from invalid texels for image resources result in
undefined values (internal issue 1014).
* Modify description of patch version so it continues to increment across
minor version changes (internal issue 1033).
* Clarify and unify language describing physical device-level core and
extension functionality in the <<fundamentals-validusage-extensions,
Valid Usage for Extensions>>, <<fundamentals-validusage-versions, Valid
Usage for Newer Core Versions>>, <<initialization-functionpointers
Command Function Pointers>>, <<initialization-phys-dev-extensions,
Extending Physical Device From Device Extensions>>
<<extended-functionality-instance-extensions-and-devices, Instance
Extensions and Device Extensions>> sections and for
flink:vkGetPhysicalDeviceImageFormatProperties2. This documents that
instance-level functionality is tied to the loader, and independent of
the ICD; physical device-level functionality is tied to the ICD, and
associated with device extensions; physical devices are treated more
uniformly between core and extensions; and instance and physical
versions can be different (internal issue 1048).
* Updated the <<commandbuffers-lifecycle, Command Buffer Lifecycle>>
section to clarify the ability for pending command buffers to transition
to the invalid state after submission, and add a command buffer
lifecycle diagram (internal issue 1050).
* Clarify that some flink:VkDescriptorUpdateTemplateCreateInfo parameters
are ignored when push descriptors are not supported (internal issue
1054).
* Specify that flink:vkCreateImage will return an error if the image is
too large, in a NOTE in the slink:VkImageFormatProperties description
(internal issue 1078).
* Remove near-duplicate NOTEs about when to query function pointers
dynamically in the <<initialization, Initialization>> chapter and
replace by extending the NOTE in the <<fundamentals-abi, Application
Binary Interface>> section (internal issue 1085).
* Restore missing references to "`Sparse Resource Features`" in the
flink:VkBufferCreateFlagBits description (internal issue 1086).
* Tidy up definitions of descriptor types in the `GL_KHR_vulkan_glsl`
specification, the <<descriptorsets, Resource Descriptors>> section and
its subsections, and the <<interfaces-resources-descset, Descriptor Set
Interface>> for consistency, reduction of duplicate information, and
removal of GLSL correspondance/examples (internal issue 1090).
* Correctly describe code:PrimitiveId as an Input for tessellation control
and evaluation shaders, not an Output (internal issue 1109).
* Relax the requirements on chroma offsets for nearest filtering in
<<textures-implict-reconstruction, Implicit Reconstruction>> (internal
issue 1116).
Other Issues:
* Clarify the intended relationship between specification language and
certain terms defined in the Khronos Intellectual Property Rights
policy. Specific changes include:
** Rewrote IP/Copyright preamble and introduction to better agree with
normative language both as laid out in the introduction, and the
Khronos IPR policy.
** Added notion of fully informative sections, which are now tagged with
"`(Informative)`" in their titles.
** Removed non-normative uses of the phrase "`not required`"
** Clarified the distinction between terms "`optional`" and "`not
required:`" as they relate to the IPR Policy, and updated specification
text to use terms consistent with the intent.
** Reduced additions to RFC 2119, and ensured the specification agreed
with the leaner language.
** Removed the terms "`hardware`", "`software`", "`CPU`", and "`GPU`" from
normative text.
** Moved several paragraphs that should not have been normative to
informative notes.
** Clarified a number of definitions in the Glossary.
** Updated the document writing guide to match new terminology changes.
* Explicitly state in the <<fundamentals-objectmodel-lifetime-acquire,
application memory lifetime>> language that that for objects other than
descriptor sets, a slink:VkDescriptorSetLayout object used in the
creation of another object (such as slink:VkPipelineLayout or
slink:VkDescriptorUpdateTemplateKHR) is only in use during the creation
of that object and can be safely destroyed afterwards.
* Updated the <<textures-scale-factor, Scale Factor Operation>> section to
use the ratio of anisotropy, rather than the integer sample rate, to
perform the LOD calculation. The spec still allows use of the sample
rate as the value used to calculate the LOD, but no longer requires it.
* Update `vulkan_ext.c` to include all platform-related definitions from
the Vulkan platform headers, following the split of the headers into
platform-specific and non-platform-specific files.
* Fix bogus anchor name in the <<commandbuffers, Command Buffers>> chapter
which accidentally duplicated an anchor in the pipelines chapter. There
were no reference to this anchor, fortunately.
* Add valid usage statement for slink:VkWriteDescriptorSet and
slink:VkCopyDescriptorSet requiring that the slink:VkDescriptorSetLayout
used to allocate the source and destination sets must not have been
destroyed at the time flink:vkUpdateDescriptorSets is called.
* Document mapping of subgroup barrier functions to SPIR-V, and clarify a
place where subgroupBarrier sounds like it's execution-only in the
standalone `GL_KHR_shader_subgroup` specification.
* Use an HTML stylesheet derived from the Asciidoctor `colony` theme, with
the default Arial font family replaced by the sans-serif Noto font
family.
* Numerous minor updates to README.adoc, build scripts, Makefiles, and
registry and style guide specifications to support Vulkan 1.1 outputs,
use them as defaults, and remove mention of `KHX` extensions, which are
no longer supported.
New Extensions:
* `VK_EXT_vertex_attrib_divisor`
573 lines
24 KiB
Plaintext
573 lines
24 KiB
Plaintext
// Copyright (c) 2014-2018 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::../../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::../../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[]
|
|
--
|
|
|
|
[open,refpage='VkDisplayPropertiesKHR',desc='Structure describing an available display device',type='structs']
|
|
--
|
|
|
|
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.
|
|
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 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[]
|
|
--
|
|
|
|
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::../../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[]
|
|
--
|
|
|
|
[open,refpage='VkDisplayPlanePropertiesKHR',desc='Structure describing display plane properties',type='structs']
|
|
--
|
|
|
|
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[]
|
|
--
|
|
|
|
[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::../../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::../../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::../../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::../../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[]
|
|
--
|
|
|
|
[open,refpage='VkDisplayModePropertiesKHR',desc='Structure describing display mode properties',type='structs']
|
|
--
|
|
|
|
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[]
|
|
--
|
|
|
|
[open,refpage='VkDisplayModeParametersKHR',desc='Structure describing display parameters associated with a display mode',type='structs']
|
|
--
|
|
|
|
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[]
|
|
--
|
|
|
|
[open,refpage='vkCreateDisplayModeKHR',desc='Create a display mode',type='protos']
|
|
--
|
|
|
|
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
|
|
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::../../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::../../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
|
|
****
|
|
* [[VUID-VkDisplayModeCreateInfoKHR-width-01250]]
|
|
The pname:width and pname:height members of the pname:visibleRegion
|
|
member of pname:parameters must: be greater than `0`
|
|
* [[VUID-VkDisplayModeCreateInfoKHR-refreshRate-01251]]
|
|
The pname:refreshRate member of pname:parameters must: be greater than
|
|
`0`
|
|
****
|
|
|
|
include::../../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::../../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[]
|
|
--
|
|
|
|
[open,refpage='VkDisplayPlaneCapabilitiesKHR',desc='Structure describing capabilities of a mode and plane combination',type='structs']
|
|
--
|
|
|
|
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
|
|
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::../../validity/structs/VkDisplayPlaneCapabilitiesKHR.txt[]
|
|
--
|
|
|
|
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::../../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[]
|
|
--
|
|
|
|
[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::../../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::../../validity/structs/VkDisplaySurfaceCreateInfoKHR.txt[]
|
|
--
|
|
|
|
[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::../../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='enums']
|
|
--
|
|
include::../../api/flags/VkDisplayPlaneAlphaFlagsKHR.txt[]
|
|
|
|
sname:VkDisplayPlaneAlphaFlagsKHR is a bitmask type for setting a mask of
|
|
zero or more slink:VkDisplayPlaneAlphaFlagBitsKHR.
|
|
--
|