mirror of
https://github.com/status-im/Vulkan-Docs.git
synced 2025-01-12 23:14:20 +00:00
82e0f83d43
* Bump API patch number and header version number to 40 for this update.
* There is a major build change in this release. We are now using the
Ruby-based ``asciidoctor'' implementation, rather than the Python-based
``asciidoc'' implementation, to process the specification. While the
actual specification markup changes were minimal, this requires a new
set of build tools and a very different installation process, especially
because we now use an experimental direct-to-PDF backend for Asciidoctor
instead of Docbook->dblatex->PDF. It is no longer possible to build the
Specification using asciidoc. See doc/specs/vulkan/README.adoc
for some guidance on installing the new toolchain components.
* There are some minor rendering issues in the PDF output due to teething
problems with the asciidoctor toolchain, especially with mathematical
equations. We are aware of these and working on them.
Github Issues:
* Updated sample code for the <<sparsememory-examples-basic,sparse
resource binding example>> (public issue 97).
* Modify line and point clipping behavior in the
<<vertexpostproc-clipping, Primitive Clipping>> section to allow for
pop-free behavior. The ability to check for which behavior is
implemented may be added a future feature or extension (public issue
113).
* Unify the discussions of implicit ordering throughout the spec, in
particular in the new sections <<drawing-primitive-order, Primitive
Order>>, <<primrast-order, Rasterization Order>>, and
<<synchronization-implicit, Implicit Synchronization Guarantees>>; the
discussion of <<synchronization-submission-order, submission order>>;
and references elsewhere to these sections (public issue 133).
* Clarify \<\<descriptorsets-compatibility,Pipeline Layout Compatibility>>
language and introduce the term ``identically defined'' (public issue
164).
* Add a dependency to the +VK_EXT_debug_marker+ extension that's needed to
reuse the object type enum from +VK_EXT_debug_report+, and moves the
definition of that enum into +VK_EXT_debug_report+ where it should be
(public issue 409).
* Remove redundant valid usage statement from slink:VkImageBlit (public
issue 421).
* Update GL_KHR_vulkan_glsl to allow the ternary operator to result in a
specialization constant (public issue 424).
* Fix valid usage for flink:VkPipelineShaderStageCreateInfo (public issue
426).
* Correct typo in New Objects list for <<VK_EXT_debug_report>> (public
issue 447).
Internal Issues:
* Moved to asciidoctor for spec builds (internal issue 121).
* Update style guide to describe where to put new extensions-specific
asciidoc files, and what to name them (internal issue 626).
* Add src/spec/indexExt.py to autogenerate registry index entries linking
into the 1.0-extensions specification, instead of maintaining the index
manually. (internal issue 642).
* Autogenerate extension dependencies and lists of all extensions and all
KHR extensions from the "supported" attributes in +vk.xml+. Execute
+make config/extDependency.sh+ from +doc/specs/vulkan+ when a supported
extension is added to vk.xml, to regenerate the dependency script. The
consequence is that specifying a single extension to the +makeExt+
script will automatically enable all extensions it depends on as well,
and that the +makeAllExts+ and +makeKHR+ scripts do not need to be
updated when a new extension is supported (internal issue 648).
* Put extension appendices all at the same asciidoc section level, so KHR
WSI extensions show up in the HTML index (internal issue 648).
Other Issues:
* Imbed images in the generated HTML specs instead of loading them from
the images/ directory.
* Fix missing EXT in extension name
(ename:VK_EXT_SWAPCHAIN_COLOR_SPACE_EXTENSION_NAME).
* Add new +VK_EXT_SMPTE_2086_metadata+ extension.
* In the <<platformCreateSurface_xlib,Xlib Surface>> section of the
+VK_KHR_xlib_surface+ specification, add language warning users that
they always need to call code:XinitThreads.
* Use the term "presentable image" (rather than "swapchain image")
consistently in +VK_KHR_swapchain+ and related extensions, and add a
glossary term defining it.
* Relocate the valid usage for samples of
flink:vkGetPhysicalDeviceSparseImageFormatProperties2KHR::pname:pFormatInfo
to be below the flink:VkPhysicalDeviceSparseImageFormatInfo2KHR
structure.
211 lines
7.5 KiB
Plaintext
211 lines
7.5 KiB
Plaintext
// Copyright (c) 2014-2017 The Khronos Group Inc.
|
|
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
|
|
|
|
[[VK_KHR_display_swapchain]]
|
|
== VK_KHR_display_swapchain
|
|
|
|
*Name String*::
|
|
+VK_KHR_display_swapchain+
|
|
*Extension Type*::
|
|
Device extension
|
|
*Registered Extension Number*::
|
|
4
|
|
*Status*::
|
|
Draft.
|
|
*Last Modified Date*::
|
|
2015-11-10
|
|
*Revision*::
|
|
9
|
|
*IP Status*::
|
|
No known IP claims.
|
|
*Dependencies*::
|
|
- This extension is written against version 1.0 of the Vulkan API.
|
|
- Requires +VK_KHR_swapchain+.
|
|
- Requires +VK_KHR_display+.
|
|
*Contributors*::
|
|
- James Jones, NVIDIA
|
|
- Jeff Vigil, Qualcomm
|
|
- Jesse Hall, Google
|
|
*Contacts*::
|
|
- James Jones (jajones 'at' nvidia.com)
|
|
|
|
This extension provides an API to create a swapchain directly on a device's
|
|
display without any underlying window system.
|
|
|
|
=== New Object Types
|
|
|
|
None
|
|
|
|
=== New Enum Constants
|
|
|
|
* Extending ename:VkStructureType:
|
|
** ename:VK_STRUCTURE_TYPE_DISPLAY_PRESENT_INFO_KHR
|
|
* Extending ename:VkResult:
|
|
** ename:VK_ERROR_INCOMPATIBLE_DISPLAY_KHR
|
|
|
|
=== New Enums
|
|
|
|
None
|
|
|
|
=== New Structures
|
|
|
|
* slink:VkDisplayPresentInfoKHR
|
|
|
|
=== New Functions
|
|
|
|
* flink:vkCreateSharedSwapchainsKHR
|
|
|
|
=== Issues
|
|
|
|
1) Should swapchains sharing images each hold a reference to the images, or
|
|
should it be up to the application to destroy the swapchains and images in
|
|
an order that avoids the need for reference counting?
|
|
|
|
*PROPOSED RESOLUTION*: Take a reference.
|
|
The lifetime of presentable images is already complex enough.
|
|
|
|
2) Should the srcRect/dstRect parameters be specified as part of the present
|
|
command, or at swapchain creation time?
|
|
|
|
*PROPOSED RESOLUTION*: As part of the presentation command.
|
|
This allows moving and scaling the image on the screen without the need to
|
|
respecify the mode or create a new swapchain presentable images.
|
|
|
|
3) Should srcRect/dstRect be specified as rects, or separate offset/extent
|
|
values?
|
|
|
|
*PROPOSED RESOLUTION*: As rects.
|
|
Specifying them separately might make it easier for hardware to expose
|
|
support for one but not the other, but in such cases applications must just
|
|
take care to obey the reported capabilities and not use non-zero offsets or
|
|
extents that require scaling, as appropriate.
|
|
|
|
4) How can applications create multiple swapchains that use the same images?
|
|
|
|
RESOLUTION: By calling flink:vkCreateSharedSwapchainsKHR.
|
|
|
|
An earlier resolution used flink:vkCreateSwapchainKHR, chaining multiple
|
|
slink:VkSwapchainCreateInfoKHR structures through pname:pNext.
|
|
In order to allow each swapchain to also allow other extension structs, a
|
|
level of indirection was used: slink:VkSwapchainCreateInfoKHR::pname:pNext
|
|
pointed to a different structure, which had both an pname:sType/pname:pNext
|
|
for additional extensions, and also had a pointer to the next
|
|
slink:VkSwapchainCreateInfoKHR structure.
|
|
The number of swapchains to be created could only be found by walking this
|
|
linked list of alternating structures, and the pSwapchains out parameter was
|
|
reinterpreted to be an array of slink:VkSwapchainKHR handles.
|
|
|
|
Another option considered was a method to specify a ``shared'' swapchain
|
|
when creating a new swapchain, such that groups of swapchains using the same
|
|
images could be built up one at a time.
|
|
This was deemed unusable because drivers need to know all of the displays an
|
|
image will be used on when determining which internal formats and layouts to
|
|
use for that image.
|
|
|
|
=== Examples
|
|
|
|
**Example 1**
|
|
|
|
Create a swapchain on a display mode and plane
|
|
|
|
[source,c++]
|
|
----------------------------------------
|
|
// See VK_KHR_display for an example of how to pick a display,
|
|
// display mode, plane, and how to create a VkSurfaceKHR for
|
|
// that plane.
|
|
extern VkPhysicalDevice physDevice;
|
|
extern VkDisplayModePropertiesKHR myModeProps;
|
|
extern VkSurfaceKHR mySurface;
|
|
extern VkDevice device;
|
|
|
|
uint32_t queueCount, i;
|
|
uint32_t presentQueueFamilyIndex = UINT32_MAX;
|
|
VkBool32 supportsPresent;
|
|
|
|
// Find a queue family that supports presenting to this surface
|
|
uint32_t familyCount;
|
|
vkGetPhysicalDeviceQueueFamilyProperties(physDevice, &familyCount, NULL);
|
|
|
|
for (i = 0; i < familyCount; ++i)
|
|
{
|
|
vkGetPhysicalDeviceSurfaceSupportKHR(physDevice, i, mySurface, &supportsPresent);
|
|
|
|
if (supportsPresent) {
|
|
// Found a queue family that supports present. See
|
|
// VK_KHR_surface for an example of how to find a queue that
|
|
// supports both presentation and graphics
|
|
presentQueueFamilyIndex = i;
|
|
break;
|
|
}
|
|
}
|
|
|
|
// Figure out which formats and present modes this surface supports.
|
|
uint32_t formatCount;
|
|
vkGetPhysicalDeviceSurfaceFormatsKHR(physDevice, mySurface, &formatCount, NULL);
|
|
|
|
VkSurfaceFormatKHR* formats = (VkSurfaceFormatKHR*)malloc(sizeof(VkSurfaceFormatKHR) * formatCount);
|
|
vkGetPhysicalDeviceSurfaceFormatsKHR(physDevice, mySurface, &formatCount, formats);
|
|
|
|
const VkSwapchainCreateInfoKHR createInfo =
|
|
{
|
|
VK_STRUCTURE_TYPE_SWAPCHAIN_CREATE_INFO_KHR, // sType
|
|
NULL, // pNext
|
|
0, // flags
|
|
mySurface, // surface
|
|
3, // minImageCount
|
|
formats[0].format, // imageFormat
|
|
formats[0].colorSpace, // imageColorSpace
|
|
myModeProps.parameters.visibleRegion, // imageExtent
|
|
1, // imageArrayLayers
|
|
VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT, // imageUsage
|
|
VK_SHARING_MODE_EXCLUSIVE, // imageSharingMode
|
|
0, // queueFamilyIndexCount
|
|
NULL, // pQueueFamilyIndices
|
|
VK_SURFACE_TRANSFORM_IDENTITY_BIT_KHR, // preTransform
|
|
VK_COMPOSITE_ALPHA_OPAQUE_BIT_KHR, // compositeAlpha
|
|
VK_PRESENT_MODE_FIFO_KHR, // presentMode
|
|
VK_TRUE, // clipped
|
|
VK_NULL_HANDLE // oldSwapchain
|
|
};
|
|
|
|
VkSwapchainKHR swapchain;
|
|
// This is equivalent to vkCreateSwapchainKHR.
|
|
vkCreateSharedSwapchainsKHR(device, 1, &createInfo, NULL, &swapchain);
|
|
----------------------------------------
|
|
|
|
=== Version History
|
|
|
|
* Revision 1, 2015-07-29 (James Jones)
|
|
- Initial draft
|
|
|
|
* Revision 2, 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 3, 2015-09-01 (James Jones)
|
|
- Restore single-field revision number.
|
|
|
|
* Revision 4, 2015-09-08 (James Jones)
|
|
- Allow creating multiple swap chains that share the same images using a
|
|
single call to vkCreateSwapChainKHR().
|
|
|
|
* Revision 5, 2015-09-10 (Alon Or-bach)
|
|
- Removed underscores from SWAP_CHAIN in two enums.
|
|
|
|
* Revision 6, 2015-10-02 (James Jones)
|
|
- Added support for smart panels/buffered displays.
|
|
|
|
* Revision 7, 2015-10-26 (Ian Elliott)
|
|
- Renamed from VK_EXT_KHR_display_swapchain to VK_KHR_display_swapchain.
|
|
|
|
* Revision 8, 2015-11-03 (Daniel Rakos)
|
|
- Updated sample code based on the changes to VK_KHR_swapchain.
|
|
|
|
* Revision 9, 2015-11-10 (Jesse Hall)
|
|
- Replaced ftext:VkDisplaySwapchainCreateInfoKHR with
|
|
vkCreateSharedSwapchainsKHR, changing resolution of issue #4.
|