395 lines
15 KiB
Plaintext
395 lines
15 KiB
Plaintext
// Copyright (c) 2014-2017 The Khronos Group Inc.
|
|
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
|
|
|
|
[[VK_KHR_display]]
|
|
== VK_KHR_display
|
|
|
|
*Name String*::
|
|
+VK_KHR_display+
|
|
*Extension Type*::
|
|
Instance extension
|
|
*Registered Extension Number*::
|
|
3
|
|
*Status*::
|
|
Draft.
|
|
*Last Modified Date*::
|
|
2017-03-13
|
|
*Revision*::
|
|
23
|
|
*IP Status*::
|
|
No known IP claims.
|
|
*Dependencies*::
|
|
- This extension is written against version 1.0 of the Vulkan API.
|
|
- Requires +VK_KHR_surface+.
|
|
*Contributors*::
|
|
- James Jones, NVIDIA
|
|
- Norbert Nopper, Freescale
|
|
- Jeff Vigil, Qualcomm
|
|
- Daniel Rakos, AMD
|
|
*Contacts*::
|
|
- James Jones (jajones 'at' nvidia.com)
|
|
- Norbert Nopper (Norbert.Nopper 'at' freescale.com)
|
|
|
|
This extension provides the API to enumerate displays and available modes on
|
|
a given device.
|
|
|
|
=== New Object Types
|
|
|
|
* slink:VkDisplayKHR
|
|
* slink:VkDisplayModeKHR
|
|
|
|
=== New Enum Constants
|
|
|
|
* Extending ename:VkStructureType:
|
|
** ename:VK_STRUCTURE_TYPE_DISPLAY_MODE_CREATE_INFO_KHR
|
|
** ename:VK_STRUCTURE_TYPE_DISPLAY_SURFACE_CREATE_INFO_KHR
|
|
|
|
=== New Enums
|
|
|
|
* ename:VkDisplayPlaneAlphaFlagBitsKHR
|
|
|
|
=== New Structures
|
|
|
|
* slink:VkDisplayPropertiesKHR
|
|
* slink:VkDisplayModeParametersKHR
|
|
* slink:VkDisplayModePropertiesKHR
|
|
* slink:VkDisplayModeCreateInfoKHR
|
|
* slink:VkDisplayPlanePropertiesKHR
|
|
* slink:VkDisplayPlaneCapabilitiesKHR
|
|
* slink:VkDisplaySurfaceCreateInfoKHR
|
|
|
|
=== New Functions
|
|
|
|
* flink:vkGetPhysicalDeviceDisplayPropertiesKHR
|
|
* flink:vkGetPhysicalDeviceDisplayPlanePropertiesKHR
|
|
* flink:vkGetDisplayPlaneSupportedDisplaysKHR
|
|
* flink:vkGetDisplayModePropertiesKHR
|
|
* flink:vkCreateDisplayModeKHR
|
|
* flink:vkGetDisplayPlaneCapabilitiesKHR
|
|
* flink:vkCreateDisplayPlaneSurfaceKHR
|
|
|
|
=== Issues
|
|
|
|
1) Which properties of a mode should be fixed in the mode info vs.
|
|
settable in some other function when setting the mode? E.g., do we need to
|
|
double the size of the mode pool to include both stereo and non-stereo
|
|
modes? YUV and RGB scanout even if they both take RGB input images? BGR vs.
|
|
RGB input? etc.
|
|
|
|
*PROPOSED RESOLUTION*: Many modern displays support at most a handful of
|
|
resolutions and timings natively.
|
|
Other "`modes`" are expected to be supported using scaling hardware on the
|
|
display engine or GPU.
|
|
Other properties, such as rotation and mirroring should not require
|
|
duplicating hardware modes just to express all combinations.
|
|
Further, these properties may be implemented on a per-display or per-overlay
|
|
granularity.
|
|
|
|
To avoid the exponential growth of modes as mutable properties are added, as
|
|
was the case with EGLConfig/WGL pixel formats/GLXFBConfig, this
|
|
specification should separate out hardware properties and configurable state
|
|
into separate objects.
|
|
Modes and overlay planes will express capabilities of the hardware, while a
|
|
separate structure will allow applications to configure scaling, rotation,
|
|
mirroring, color keys, LUT values, alpha masks, etc.
|
|
for a given swapchain independent of the mode in use.
|
|
Constraints on these settings will be established by properties of the
|
|
immutable objects.
|
|
|
|
Note the resolution of this issue may affect issue 5 as well.
|
|
|
|
2) What properties of a display itself are useful?
|
|
|
|
*PROPOSED RESOLUTION*: This issue is too broad.
|
|
It was meant to prompt general discussion, but resolving this issue amounts
|
|
to completing this specification.
|
|
All interesting properties should be included.
|
|
The issue will remain as a placeholder since removing it would make it hard
|
|
to parse existing discussion notes that refer to issues by number.
|
|
|
|
3) How are multiple overlay planes within a display or mode enumerated?
|
|
|
|
*PROPOSED RESOLUTION*: They are referred to by an index.
|
|
Each display will report the number of overlay planes it contains.
|
|
|
|
4) Should swapchains be created relative to a mode or a display?
|
|
|
|
*PROPOSED RESOLUTION*: When using this extension, swapchains are created
|
|
relative to a mode and a plane.
|
|
The mode implies the display object the swapchain will present to.
|
|
If the specified mode is not the display's current mode, the new mode will
|
|
be applied when the first image is presented to the swapchain, and the
|
|
default operating system mode, if any, will be restored when the swapchain
|
|
is destroyed.
|
|
|
|
5) Should users query generic ranges from displays and construct their own
|
|
modes explicitly using those constraints rather than querying a fixed set of
|
|
modes (Most monitors only have one real "`mode`" these days, even though
|
|
many support relatively arbitrary scaling, either on the monitor side or in
|
|
the GPU display engine, making "`modes`" something of a relic/compatibility
|
|
construct).
|
|
|
|
*PROPOSED RESOLUTION*: Expose both.
|
|
Display info structures will expose a set of predefined modes, as well as
|
|
any attributes necessary to construct a customized mode.
|
|
|
|
6) Is it fine if we return the display and display mode handles in the
|
|
structure used to query their properties?
|
|
|
|
*PROPOSED RESOLUTION*: Yes.
|
|
|
|
7) Is there a possibility that not all displays of a device work with all of
|
|
the present queues of a device? If yes, how do we determine which displays
|
|
work with which present queues?
|
|
|
|
*PROPOSED RESOLUTION*: No known hardware has such limitations, but
|
|
determining such limitations is supported automatically using the existing
|
|
+VK_KHR_surface+ and +VK_KHR_swapchain+ query mechanisms.
|
|
|
|
8) Should all presentation need to be done relative to an overlay plane, or
|
|
can a display mode + display be used alone to target an output?
|
|
|
|
*PROPOSED RESOLUTION*: Require specifying a plane explicitly.
|
|
|
|
9) Should displays have an associated window system display, such as an HDC
|
|
or Display*?
|
|
|
|
*PROPOSED RESOLUTION*: No.
|
|
Displays are independent of any windowing system in use on the system.
|
|
Further, neither HDC nor Display* refer to a physical display object.
|
|
|
|
10) Are displays queried from a physical GPU or from a device instance?
|
|
|
|
*PROPOSED RESOLUTION*: Developers prefer to query modes directly from the
|
|
physical GPU so they can use display information as an input to their device
|
|
selection algorithms prior to device creation.
|
|
This avoids the need to create dummy device instances to enumerate displays.
|
|
|
|
This preference must be weighed against the extra initialization that must
|
|
be done by driver vendors prior to device instance creation to support this
|
|
usage.
|
|
|
|
11) Should displays and/or modes be dispatchable objects? If functions are
|
|
to take displays, overlays, or modes as their first parameter, they must be
|
|
dispatchable objects as defined in Khronos bug 13529.
|
|
If they are not added to the list of dispatchable objects, functions
|
|
operating on them must take some higher-level object as their first
|
|
parameter.
|
|
There is no performance case against making them dispatchable objects, but
|
|
they would be the first extension objects to be dispatchable.
|
|
|
|
*PROPOSED RESOLUTION*: Do not make displays or modes dispatchable.
|
|
They will dispatch based on their associated physical device.
|
|
|
|
12) Should hardware cursor capabilities be exposed?
|
|
|
|
*PROPOSED RESOLUTION*: Defer.
|
|
This could be a separate extension on top of the base WSI specs.
|
|
|
|
ifdef::editing-notes[]
|
|
[NOTE]
|
|
.editing-note
|
|
==================
|
|
There appears to be a missing sentence for the first part of issue 13 here.
|
|
==================
|
|
endif::editing-notes[]
|
|
|
|
if they are one physical display device to an end user, but may internally
|
|
be implemented as two side-by-side displays using the same display engine
|
|
(and sometimes cabling) resources as two physically separate display
|
|
devices.
|
|
|
|
*RESOLVED*: Tiled displays will appear as a single display object in this
|
|
API.
|
|
|
|
14) Should the raw EDID data be included in the display information?
|
|
|
|
*RESOLVED*: No.
|
|
A future extension could be added which reports the EDID if necessary.
|
|
This may be complicated by the outcome of issue 13.
|
|
|
|
15) Should min and max scaling factor capabilities of overlays be exposed?
|
|
|
|
*RESOLVED*: Yes.
|
|
This is exposed indirectly by allowing applications to query the min/max
|
|
position and extent of the source and destination regions from which image
|
|
contents are fetched by the display engine when using a particular mode and
|
|
overlay pair.
|
|
|
|
16) Should devices be able to expose planes that can be moved between
|
|
displays? If so, how?
|
|
|
|
*RESOLVED*: Yes.
|
|
Applications can determine which displays a given plane supports using
|
|
vkGetDisplayPlaneSupportedDisplaysKHR.
|
|
|
|
17) Should there be a way to destroy display modes? If so, does it support
|
|
destroying "`built in`" modes?
|
|
|
|
*RESOLVED*: Not in this extension.
|
|
A future extension could add this functionality.
|
|
|
|
18) What should the lifetime of display and built-in display mode objects
|
|
be?
|
|
|
|
*RESOLVED*: The lifetime of the instance.
|
|
These objects can not be destroyed.
|
|
A future extension may be added to expose a way to destroy these objects
|
|
and/or support display hotplug.
|
|
|
|
19) Should persistent mode for smart panels be enabled/disabled at swap
|
|
chain creation time, or on a per-present basis.
|
|
|
|
*RESOLVED*: On a per-present basis.
|
|
|
|
=== Examples
|
|
|
|
[NOTE]
|
|
.Note
|
|
====
|
|
The example code for the +VK_KHR_display+ and +VK_KHR_display_swapchain+
|
|
extensions was removed from the appendix after revision 1.0.43.
|
|
The display enumeration example code was ported to the cube demo that is
|
|
shipped with the official Khronos SDK, and is being kept up-to-date in that
|
|
location (see:
|
|
https://github.com/KhronosGroup/Vulkan-LoaderAndValidationLayers/blob/master/demos/cube.c).
|
|
====
|
|
|
|
=== Version History
|
|
|
|
* Revision 1, 2015-02-24 (James Jones)
|
|
- Initial draft
|
|
|
|
* Revision 2, 2015-03-12 (Norbert Nopper)
|
|
- Added overlay enumeration for a display.
|
|
|
|
* Revision 3, 2015-03-17 (Norbert Nopper)
|
|
- Fixed typos and namings as discussed in Bugzilla.
|
|
- Reordered and grouped functions.
|
|
- Added functions to query count of display, mode and overlay.
|
|
- Added native display handle, which is maybe needed on some platforms to
|
|
create a native Window.
|
|
|
|
* Revision 4, 2015-03-18 (Norbert Nopper)
|
|
- Removed primary and virtualPostion members (see comment of James Jones
|
|
in Bugzilla).
|
|
- Added native overlay handle to info structure.
|
|
- Replaced , with ; in struct.
|
|
|
|
* Revision 6, 2015-03-18 (Daniel Rakos)
|
|
- Added WSI extension suffix to all items.
|
|
- Made the whole API more "Vulkanish".
|
|
- Replaced all functions with a single vkGetDisplayInfoKHR function to
|
|
better match the rest of the API.
|
|
- Made the display, display mode, and overlay objects be first class
|
|
objects, not subclasses of VkBaseObject as they do not support the
|
|
common functions anyways.
|
|
- Renamed *Info structures to *Properties.
|
|
- Removed overlayIndex field from VkOverlayProperties as there is an
|
|
implicit index already as a result of moving to a "Vulkanish" API.
|
|
- Displays are not get through device, but through physical GPU to match
|
|
the rest of the Vulkan API.
|
|
Also this is something ISVs explicitly requested.
|
|
- Added issue (6) and (7).
|
|
|
|
* Revision 7, 2015-03-25 (James Jones)
|
|
- Added an issues section
|
|
- Added rotation and mirroring flags
|
|
|
|
* Revision 8, 2015-03-25 (James Jones)
|
|
- Combined the duplicate issues sections introduced in last change.
|
|
- Added proposed resolutions to several issues.
|
|
|
|
* Revision 9, 2015-04-01 (Daniel Rakos)
|
|
- Rebased extension against Vulkan 0.82.0
|
|
|
|
* Revision 10, 2015-04-01 (James Jones)
|
|
- Added issues (10) and (11).
|
|
- Added more straw-man issue resolutions, and cleaned up the proposed
|
|
resolution for issue (4).
|
|
- Updated the rotation and mirroring enums to have proper bitmask
|
|
semantics.
|
|
|
|
* Revision 11, 2015-04-15 (James Jones)
|
|
- Added proposed resolution for issues (1) and (2).
|
|
- Added issues (12), (13), (14), and (15)
|
|
- Removed pNativeHandle field from overlay structure.
|
|
- Fixed small compilation errors in example code.
|
|
|
|
* Revision 12, 2015-07-29 (James Jones)
|
|
- Rewrote the guts of the extension against the latest WSI swapchain
|
|
specifications and the latest Vulkan API.
|
|
- Address overlay planes by their index rather than an object handle and
|
|
refer to them as "planes" rather than "overlays" to make it slightly
|
|
clearer that even a display with no "overlays" still has at least one
|
|
base "plane" that images can be displayed on.
|
|
- Updated most of the issues.
|
|
- Added an "extension type" section to the specification header.
|
|
- Re-used the VK_EXT_KHR_surface surface transform enumerations rather
|
|
than redefining them here.
|
|
- Updated the example code to use the new semantics.
|
|
|
|
* Revision 13, 2015-08-21 (Ian Elliott)
|
|
- Renamed this extension and all of its enumerations, types, functions,
|
|
etc.
|
|
This makes it compliant with the proposed standard for Vulkan
|
|
extensions.
|
|
- Switched from "revision" to "version", including use of the
|
|
VK_MAKE_VERSION macro in the header file.
|
|
|
|
* Revision 14, 2015-09-01 (James Jones)
|
|
- Restore single-field revision number.
|
|
|
|
* Revision 15, 2015-09-08 (James Jones)
|
|
- Added alpha flags enum.
|
|
- Added premultiplied alpha support.
|
|
|
|
* Revision 16, 2015-09-08 (James Jones)
|
|
- Added description section to the spec.
|
|
- Added issues 16 - 18.
|
|
|
|
* Revision 17, 2015-10-02 (James Jones)
|
|
- Planes are now a property of the entire device rather than individual
|
|
displays.
|
|
This allows planes to be moved between multiple displays on devices
|
|
that support it.
|
|
- Added a function to create a VkSurfaceKHR object describing a display
|
|
plane and mode to align with the new per-platform surface creation
|
|
conventions.
|
|
- Removed detailed mode timing data.
|
|
It was agreed that the mode extents and refresh rate are sufficient for
|
|
current use cases.
|
|
Other information could be added back2 in as an extension if it is
|
|
needed in the future.
|
|
- Added support for smart/persistent/buffered display devices.
|
|
|
|
* Revision 18, 2015-10-26 (Ian Elliott)
|
|
- Renamed from VK_EXT_KHR_display to VK_KHR_display.
|
|
|
|
* Revision 19, 2015-11-02 (James Jones)
|
|
- Updated example code to match revision 17 changes.
|
|
|
|
* Revision 20, 2015-11-03 (Daniel Rakos)
|
|
- Added allocation callbacks to creation functions.
|
|
|
|
* Revision 21, 2015-11-10 (Jesse Hall)
|
|
- Added VK_DISPLAY_PLANE_ALPHA_OPAQUE_BIT_KHR, and use
|
|
VkDisplayPlaneAlphaFlagBitsKHR for
|
|
VkDisplayPlanePropertiesKHR::alphaMode instead of
|
|
VkDisplayPlaneAlphaFlagsKHR, since it only represents one mode.
|
|
- Added reserved flags bitmask to VkDisplayPlanePropertiesKHR.
|
|
- Use VkSurfaceTransformFlagBitsKHR instead of obsolete
|
|
VkSurfaceTransformKHR.
|
|
- Renamed vkGetDisplayPlaneSupportedDisplaysKHR parameters for clarity.
|
|
|
|
* Revision 22, 2015-12-18 (James Jones)
|
|
- Added missing "planeIndex" parameter to
|
|
vkGetDisplayPlaneSupportedDisplaysKHR()
|
|
|
|
* Revision 23, 2017-03-13 (James Jones)
|
|
- Closed all remaining issues.
|
|
The specification and implementations have been shipping with the
|
|
proposed resolutions for some time now.
|
|
- Removed the sample code and noted it has been integrated into the
|
|
official Vulkan SDK cube demo.
|