Appendix E: Layers & Extensions (Informative)
Extensions to the Vulkan API can be defined by authors, groups of authors, and the Khronos Vulkan Working Group. In order not to compromise the readability of the Vulkan Specification, the core Specification does not incorporate most extensions. The online Registry of extensions is available at URL
and allows generating versions of the Specification incorporating different extensions.
Most of the content previously in this appendix does not specify use of specific Vulkan extensions and layers, but rather specifies the processes by which extensions and layers are created. As of version 1.0.21 of the Vulkan Specification, this content has been migrated to the Vulkan Documentation and Extensions document. Authors creating extensions and layers must follow the mandatory procedures in that document.
The remainder of this appendix documents a set of extensions chosen when this document was built. Versions of the Specification published in the Registry include:
-
Core API + mandatory extensions required of all Vulkan implementations.
-
Core API + all registered and published Khronos (
KHR
) extensions. -
Core API + all registered and published extensions.
Extensions are grouped as Khronos KHR
, multivendor EXT
, and then
alphabetically by author ID.
Within each group, extensions are listed in alphabetical order by their
name.
Note
As of the initial Vulkan 1.1 public release, the Some vendors may use an alternate author ID ending in |
List of Current Extensions
VK_KHR_8bit_storage
- Name String
-
VK_KHR_8bit_storage
- Extension Type
-
Device extension
- Registered Extension Number
-
178
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_KHR_storage_buffer_storage_class
-
- Contact
-
-
Alexander Galazin alegal-arm
-
- Last Modified Date
-
2018-02-05
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
This extension requires
SPV_KHR_8bit_storage
-
- Contributors
-
-
Alexander Galazin, Arm
-
The VK_KHR_8bit_storage
extension allows use of 8-bit types in uniform and
storage buffers, and push constant blocks.
This extension introduces several new optional features which map to SPIR-V
capabilities and allow access to 8-bit data in Block
-decorated objects
in the Uniform
and the StorageBuffer
storage classes, and objects
in the PushConstant
storage class.
The StorageBuffer8BitAccess
capability must be supported by all
implementations of this extension.
The other capabilities are optional.
New Enum Constants
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_8BIT_STORAGE_FEATURES_KHR
-
New Structures
New SPIR-V Capabilities
Issues
Version History
-
Revision 1, 2018-02-05 (Alexander Galazin)
-
Initial draft
-
VK_KHR_android_surface
- Name String
-
VK_KHR_android_surface
- Extension Type
-
Instance extension
- Registered Extension Number
-
9
- Revision
-
6
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_KHR_surface
-
- Contact
-
-
Jesse Hall critsec
-
- Last Modified Date
-
2016-01-14
- IP Status
-
No known IP claims.
- Contributors
-
-
Patrick Doane, Blizzard
-
Jason Ekstrand, Intel
-
Ian Elliott, LunarG
-
Courtney Goeltzenleuchter, LunarG
-
Jesse Hall, Google
-
James Jones, NVIDIA
-
Antoine Labour, Google
-
Jon Leech, Khronos
-
David Mao, AMD
-
Norbert Nopper, Freescale
-
Alon Or-bach, Samsung
-
Daniel Rakos, AMD
-
Graham Sellers, AMD
-
Ray Smith, ARM
-
Jeff Vigil, Qualcomm
-
Chia-I Wu, LunarG
-
The VK_KHR_android_surface
extension is an instance extension.
It provides a mechanism to create a VkSurfaceKHR object (defined by
the VK_KHR_surface
extension) that refers to an ANativeWindow,
Android’s native surface type.
The ANativeWindow represents the producer endpoint of any buffer
queue, regardless of consumer endpoint.
Common consumer endpoints for ANativeWindows
are the system window
compositor, video encoders, and application-specific compositors importing
the images through a SurfaceTexture
.
New Object Types
None
New Enum Constants
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_ANDROID_SURFACE_CREATE_INFO_KHR
-
New Enums
None
New Structures
New Functions
Issues
1) Does Android need a way to query for compatibility between a particular physical device (and queue family?) and a specific Android display?
RESOLVED: No. Currently on Android, any physical device is expected to be able to present to the system compositor, and all queue families must support the necessary image layout transitions and synchronization operations.
Version History
-
Revision 1, 2015-09-23 (Jesse Hall)
-
Initial draft.
-
-
Revision 2, 2015-10-26 (Ian Elliott)
-
Renamed from VK_EXT_KHR_android_surface to VK_KHR_android_surface.
-
-
Revision 3, 2015-11-03 (Daniel Rakos)
-
Added allocation callbacks to surface creation function.
-
-
Revision 4, 2015-11-10 (Jesse Hall)
-
Removed VK_ERROR_INVALID_ANDROID_WINDOW_KHR.
-
-
Revision 5, 2015-11-28 (Daniel Rakos)
-
Updated the surface create function to take a pCreateInfo structure.
-
-
Revision 6, 2016-01-14 (James Jones)
-
Moved VK_ERROR_NATIVE_WINDOW_IN_USE_KHR from the VK_KHR_android_surface to the VK_KHR_surface extension.
-
VK_KHR_buffer_device_address
- Name String
-
VK_KHR_buffer_device_address
- Extension Type
-
Device extension
- Registered Extension Number
-
258
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Jeff Bolz jeffbolznv
-
- Last Modified Date
-
2019-06-24
- IP Status
-
No known IP claims.
- Contributors
-
-
Jeff Bolz, NVIDIA
-
Neil Henning, AMD
-
Tobias Hector, AMD
-
Jason Ekstrand, Intel
-
Baldur Karlsson, Valve
-
Jan-Harald Fredriksen, Arm
-
This extension allows the application to query a 64-bit buffer device
address value for a buffer, which can be used to access the buffer memory
via the PhysicalStorageBuffer
storage class in the
GL_EXT_buffer_reference
GLSL extension and
SPV_KHR_physical_storage_buffer
SPIR-V extension.
This extension also allows opaque addresses for buffers and memory objects
to be queried and later supplied by a trace capture and replay tool, so that
addresses used at replay time match the addresses used when the trace was
captured.
To enable tools to insert these queries, new memory allocation flags must be
specified for memory objects that will be bound to buffers accessed via the
PhysicalStorageBuffer
storage class.
New Object Types
None
New Enum Constants
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_BUFFER_DEVICE_ADDRESS_FEATURES_KHR
-
VK_STRUCTURE_TYPE_BUFFER_DEVICE_ADDRESS_INFO_KHR
-
VK_STRUCTURE_TYPE_BUFFER_OPAQUE_CAPTURE_ADDRESS_CREATE_INFO_KHR
-
VK_STRUCTURE_TYPE_MEMORY_OPAQUE_CAPTURE_ADDRESS_ALLOCATE_INFO_KHR
-
VK_STRUCTURE_TYPE_DEVICE_MEMORY_OPAQUE_CAPTURE_ADDRESS_INFO_KHR
-
-
Extending VkBufferUsageFlagBits:
-
VK_BUFFER_USAGE_SHADER_DEVICE_ADDRESS_BIT_KHR
-
-
Extending VkBufferCreateFlagBits:
-
VK_BUFFER_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT_KHR
-
-
Extending VkMemoryAllocateFlagBits:
-
VK_MEMORY_ALLOCATE_DEVICE_ADDRESS_BIT_KHR
-
VK_MEMORY_ALLOCATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT_KHR
-
-
Extending VkResult:
-
VK_ERROR_INVALID_OPAQUE_CAPTURE_ADDRESS_KHR
-
New Enums
None
New Structures
New Functions
New Built-In Variables
None
New SPIR-V Capabilities
Issues
None
Version History
-
Revision 1, 2019-06-24 (Jan-Harald Fredriksen)
-
Internal revisions based on VK_EXT_buffer_device_address
-
VK_KHR_create_renderpass2
- Name String
-
VK_KHR_create_renderpass2
- Extension Type
-
Device extension
- Registered Extension Number
-
110
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_KHR_multiview
-
Requires
VK_KHR_maintenance2
-
- Contact
-
-
Tobias Hector tobias
-
- Last Modified Date
-
2018-02-07
- Contributors
-
-
Tobias Hector
-
Jeff Bolz
-
This extension provides a new entry point to create render passes in a way
that can be easily extended by other extensions through the substructures of
render pass creation.
The Vulkan 1.0 render pass creation sub-structures do not include
sType
/pNext
members.
Additionally, the renderpass begin/next/end commands have been augmented
with new extensible structures for passing additional subpass information.
The VkRenderPassMultiviewCreateInfo and VkInputAttachmentAspectReference structures that extended the original VkRenderPassCreateInfo are not accepted into the new creation functions, and instead their parameters are folded into this extension as follows:
-
Elements of VkRenderPassMultiviewCreateInfo::
pViewMasks
are now specified in VkSubpassDescription2KHR::viewMask
. -
Elements of VkRenderPassMultiviewCreateInfo::
pViewOffsets
are now specified in VkSubpassDependency2KHR::viewOffset
. -
VkRenderPassMultiviewCreateInfo::
correlationMaskCount
and VkRenderPassMultiviewCreateInfo::pCorrelationMasks
are directly specified in VkRenderPassCreateInfo2KHR. -
VkInputAttachmentAspectReference::
aspectMask
is now specified in the relevant input attachment description in VkAttachmentDescription2KHR::aspectMask
The details of these mappings are explained fully in the new structures.
New Enum Constants
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_ATTACHMENT_DESCRIPTION_2_KHR
-
VK_STRUCTURE_TYPE_ATTACHMENT_REFERENCE_2_KHR
-
VK_STRUCTURE_TYPE_SUBPASS_DESCRIPTION_2_KHR
-
VK_STRUCTURE_TYPE_SUBPASS_DEPENDENCY_2_KHR
-
VK_STRUCTURE_TYPE_RENDER_PASS_CREATE_INFO_2_KHR
-
VK_STRUCTURE_TYPE_SUBPASS_BEGIN_INFO_KHR
-
VK_STRUCTURE_TYPE_SUBPASS_END_INFO_KHR
-
New Structures
New Functions
Version History
-
Revision 1, 2018-02-07 (Tobias Hector)
-
Internal revisions
-
VK_KHR_depth_stencil_resolve
- Name String
-
VK_KHR_depth_stencil_resolve
- Extension Type
-
Device extension
- Registered Extension Number
-
200
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_KHR_create_renderpass2
-
- Contact
-
-
Jan-Harald Fredriksen janharald
-
- Last Modified Date
-
2018-04-09
- Contributors
-
-
Jan-Harald Fredriksen, Arm
-
Andrew Garrard, Samsung Electronics
-
Soowan Park, Samsung Electronics
-
Jeff Bolz, NVIDIA
-
Daniel Rakos, AMD
-
This extension adds support for automatically resolving multisampled depth/stencil attachments in a subpass in a similar manner as for color attachments.
New Enum Constants
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_SUBPASS_DESCRIPTION_DEPTH_STENCIL_RESOLVE_KHR
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DEPTH_STENCIL_RESOLVE_PROPERTIES_KHR
-
New Enums
New Structures
New Functions
None.
Version History
-
Revision 1, 2018-04-09 (Jan-Harald Fredriksen)
-
Initial revision
-
VK_KHR_display
- Name String
-
VK_KHR_display
- Extension Type
-
Instance extension
- Registered Extension Number
-
3
- Revision
-
23
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_KHR_surface
-
- Contact
- Last Modified Date
-
2017-03-13
- IP Status
-
No known IP claims.
- Contributors
-
-
James Jones, NVIDIA
-
Norbert Nopper, Freescale
-
Jeff Vigil, Qualcomm
-
Daniel Rakos, AMD
-
This extension provides the API to enumerate displays and available modes on a given device.
New Object Types
New Enum Constants
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_DISPLAY_MODE_CREATE_INFO_KHR
-
VK_STRUCTURE_TYPE_DISPLAY_SURFACE_CREATE_INFO_KHR
-
New Enums
New Structures
New Functions
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.
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 cannot 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 swapchain creation time, or on a per-present basis.
RESOLVED: On a per-present basis.
Examples
Note
The example code for the |
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.
-
VK_KHR_display_swapchain
- Name String
-
VK_KHR_display_swapchain
- Extension Type
-
Device extension
- Registered Extension Number
-
4
- Revision
-
10
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_KHR_swapchain
-
Requires
VK_KHR_display
-
- Contact
-
-
James Jones cubanismo
-
- Last Modified Date
-
2017-03-13
- IP Status
-
No known IP claims.
- Contributors
-
-
James Jones, NVIDIA
-
Jeff Vigil, Qualcomm
-
Jesse Hall, Google
-
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 VkStructureType:
-
VK_STRUCTURE_TYPE_DISPLAY_PRESENT_INFO_KHR
-
-
Extending VkResult:
-
VK_ERROR_INCOMPATIBLE_DISPLAY_KHR
-
New Enums
None
New Structures
New Functions
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?
RESOLVED: Take a reference. The lifetime of presentable images is already complex enough.
2) Should the srcRect
and dstRect
parameters be specified as
part of the present command, or at swapchain creation time?
RESOLVED: 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 and presentable images.
3) Should srcRect
and dstRect
be specified as rects, or separate
offset/extent values?
RESOLVED: 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?
RESOLVED: By calling vkCreateSharedSwapchainsKHR.
An earlier resolution used vkCreateSwapchainKHR, chaining multiple
VkSwapchainCreateInfoKHR structures through pNext
.
In order to allow each swapchain to also allow other extension structs, a
level of indirection was used: VkSwapchainCreateInfoKHR::pNext
pointed to a different structure, which had both sType
and pNext
members for additional extensions, and also had a pointer to the next
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 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
Note
The example code for the |
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 VkDisplaySwapchainCreateInfoKHR with vkCreateSharedSwapchainsKHR, changing resolution of issue #4.
-
-
Revision 10, 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.
-
VK_KHR_draw_indirect_count
- Name String
-
VK_KHR_draw_indirect_count
- Extension Type
-
Device extension
- Registered Extension Number
-
170
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Piers Daniell pdaniell-nv
-
- Status
-
Draft
- Last Modified Date
-
2017-08-25
- IP Status
-
No known IP claims.
- Contributors
-
-
Matthaeus G. Chajdas, AMD
-
Derrick Owens, AMD
-
Graham Sellers, AMD
-
Daniel Rakos, AMD
-
Dominik Witczak, AMD
-
Piers Daniell, NVIDIA
-
This extension is based off the VK_AMD_draw_indirect_count
extension.
This extension allows an application to source the number of draw calls for
indirect draw calls from a buffer.
This enables applications to generate arbitrary amounts of draw commands and
execute them without host intervention.
New Functions
Version History
-
Revision 1, 2017-08-25 (Piers Daniell)
-
Initial draft based off VK_AMD_draw_indirect_count
-
VK_KHR_driver_properties
- Name String
-
VK_KHR_driver_properties
- Extension Type
-
Device extension
- Registered Extension Number
-
197
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Daniel Rakos drakos-amd
-
- Last Modified Date
-
2018-04-11
- IP Status
-
No known IP claims.
- Contributors
-
-
Baldur Karlsson
-
Matthaeus G. Chajdas, AMD
-
Piers Daniell, NVIDIA
-
Alexander Galazin, Arm
-
Jesse Hall, Google
-
Daniel Rakos, AMD
-
This extension provides a new physical device query which allows retrieving information about the driver implementation, allowing applications to determine which physical device corresponds to which particular vendor’s driver, and which conformance test suite version the driver implementation is compliant with.
New Object Types
None.
New Enum Constants
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DRIVER_PROPERTIES_KHR
-
-
VK_MAX_DRIVER_NAME_SIZE_KHR
-
VK_MAX_DRIVER_INFO_SIZE_KHR
New Enums
None.
New Structures
New Functions
None.
Issues
None.
Examples
None.
Version History
-
Revision 1, 2018-04-11 (Daniel Rakos)
-
Internal revisions
-
VK_KHR_external_fence_fd
- Name String
-
VK_KHR_external_fence_fd
- Extension Type
-
Device extension
- Registered Extension Number
-
116
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_KHR_external_fence
-
- Contact
-
-
Jesse Hall critsec
-
- Last Modified Date
-
2017-05-08
- IP Status
-
No known IP claims.
- Contributors
-
-
Jesse Hall, Google
-
James Jones, NVIDIA
-
Jeff Juliano, NVIDIA
-
Cass Everitt, Oculus
-
Contributors to
VK_KHR_external_semaphore_fd
-
An application using external memory may wish to synchronize access to that memory using fences. This extension enables an application to export fence payload to and import fence payload from POSIX file descriptors.
New Object Types
None.
New Enum Constants
-
VK_STRUCTURE_TYPE_IMPORT_FENCE_FD_INFO_KHR
-
VK_STRUCTURE_TYPE_FENCE_GET_FD_INFO_KHR
New Enums
None.
New Structs
New Functions
Issues
This extension borrows concepts, semantics, and language from
VK_KHR_external_semaphore_fd
.
That extension’s issues apply equally to this extension.
Version History
-
Revision 1, 2017-05-08 (Jesse Hall)
-
Initial revision
-
VK_KHR_external_fence_win32
- Name String
-
VK_KHR_external_fence_win32
- Extension Type
-
Device extension
- Registered Extension Number
-
115
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_KHR_external_fence
-
- Contact
-
-
Jesse Hall critsec
-
- Last Modified Date
-
2017-05-08
- IP Status
-
No known IP claims.
- Contributors
-
-
Jesse Hall, Google
-
James Jones, NVIDIA
-
Jeff Juliano, NVIDIA
-
Cass Everitt, Oculus
-
Contributors to
VK_KHR_external_semaphore_win32
-
An application using external memory may wish to synchronize access to that memory using fences. This extension enables an application to export fence payload to and import fence payload from Windows handles.
New Object Types
None.
New Enum Constants
-
VK_STRUCTURE_TYPE_IMPORT_FENCE_WIN32_HANDLE_INFO_KHR
-
VK_STRUCTURE_TYPE_EXPORT_FENCE_WIN32_HANDLE_INFO_KHR
-
VK_STRUCTURE_TYPE_FENCE_GET_WIN32_HANDLE_INFO_KHR
New Enums
None.
New Structs
New Functions
Issues
This extension borrows concepts, semantics, and language from
VK_KHR_external_semaphore_win32
.
That extension’s issues apply equally to this extension.
1) Should D3D12 fence handle types be supported, like they are for semaphores?
RESOLVED: No.
Doing so would require extending the fence signal and wait operations to
provide values to signal / wait for, like VkD3D12FenceSubmitInfoKHR
does.
A D3D12 fence can be signaled by importing it into a VkSemaphore
instead of a VkFence, and applications can check status or wait on the
D3D12 fence using non-Vulkan APIs.
The convenience of being able to do these operations on VkFence
objects doesn’t justify the extra API complexity.
Version History
-
Revision 1, 2017-05-08 (Jesse Hall)
-
Initial revision
-
VK_KHR_external_memory_fd
- Name String
-
VK_KHR_external_memory_fd
- Extension Type
-
Device extension
- Registered Extension Number
-
75
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_KHR_external_memory
-
- Contact
-
-
James Jones cubanismo
-
- Last Modified Date
-
2016-10-21
- IP Status
-
No known IP claims.
- Contributors
-
-
James Jones, NVIDIA
-
Jeff Juliano, NVIDIA
-
An application may wish to reference device memory in multiple Vulkan logical devices or instances, in multiple processes, and/or in multiple APIs. This extension enables an application to export POSIX file descriptor handles from Vulkan memory objects and to import Vulkan memory objects from POSIX file descriptor handles exported from other Vulkan memory objects or from similar resources in other APIs.
New Object Types
None.
New Enum Constants
-
VK_STRUCTURE_TYPE_IMPORT_MEMORY_FD_INFO_KHR
-
VK_STRUCTURE_TYPE_MEMORY_FD_PROPERTIES_KHR
-
VK_STRUCTURE_TYPE_MEMORY_GET_FD_INFO_KHR
New Enums
None.
New Functions
Issues
1) Does the application need to close the file descriptor returned by vkGetMemoryFdKHR?
RESOLVED: Yes, unless it is passed back in to a driver instance to import the memory. A successful get call transfers ownership of the file descriptor to the application, and a successful import transfers it back to the driver. Destroying the original memory object will not close the file descriptor or remove its reference to the underlying memory resource associated with it.
2) Do drivers ever need to expose multiple file descriptors per memory object?
RESOLVED: No. This would indicate there are actually multiple memory objects, rather than a single memory object.
3) How should the valid size and memory type for POSIX file descriptor memory handles created outside of Vulkan be specified?
RESOLVED: The valid memory types are queried directly from the external handle. The size will be specified by future extensions that introduce such external memory handle types.
Version History
-
Revision 1, 2016-10-21 (James Jones)
-
Initial revision
-
VK_KHR_external_memory_win32
- Name String
-
VK_KHR_external_memory_win32
- Extension Type
-
Device extension
- Registered Extension Number
-
74
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_KHR_external_memory
-
- Contact
-
-
James Jones cubanismo
-
- Last Modified Date
-
2016-10-21
- IP Status
-
No known IP claims.
- Contributors
-
-
James Jones, NVIDIA
-
Jeff Juliano, NVIDIA
-
Carsten Rohde, NVIDIA
-
An application may wish to reference device memory in multiple Vulkan logical devices or instances, in multiple processes, and/or in multiple APIs. This extension enables an application to export Windows handles from Vulkan memory objects and to import Vulkan memory objects from Windows handles exported from other Vulkan memory objects or from similar resources in other APIs.
New Object Types
None.
New Enum Constants
-
VK_STRUCTURE_TYPE_IMPORT_MEMORY_WIN32_HANDLE_INFO_KHR
-
VK_STRUCTURE_TYPE_EXPORT_MEMORY_WIN32_HANDLE_INFO_KHR
-
VK_STRUCTURE_TYPE_MEMORY_WIN32_HANDLE_PROPERTIES_KHR
-
VK_STRUCTURE_TYPE_MEMORY_GET_WIN32_HANDLE_INFO_KHR
New Enums
None.
New Structs
New Functions
Issues
1) Do applications need to call CloseHandle
() on the values returned
from vkGetMemoryWin32HandleKHR when handleType
is
VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_BIT_KHR
?
RESOLVED: Yes, unless it is passed back in to another driver instance to import the object. A successful get call transfers ownership of the handle to the application. Destroying the memory object will not destroy the handle or the handle’s reference to the underlying memory resource.
2) Should the language regarding KMT/Windows 7 handles be moved to a separate extension so that it can be deprecated over time?
RESOLVED: No. Support for them can be deprecated by drivers if they choose, by no longer returning them in the supported handle types of the instance level queries.
3) How should the valid size and memory type for windows memory handles created outside of Vulkan be specified?
RESOLVED: The valid memory types are queried directly from the external handle. The size is determined by the associated image or buffer memory requirements for external handle types that require dedicated allocations, and by the size specified when creating the object from which the handle was exported for other external handle types.
Version History
-
Revision 1, 2016-10-21 (James Jones)
-
Initial revision
-
VK_KHR_external_semaphore_fd
- Name String
-
VK_KHR_external_semaphore_fd
- Extension Type
-
Device extension
- Registered Extension Number
-
80
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_KHR_external_semaphore
-
- Contact
-
-
James Jones cubanismo
-
- Last Modified Date
-
2016-10-21
- IP Status
-
No known IP claims.
- Contributors
-
-
Jesse Hall, Google
-
James Jones, NVIDIA
-
Jeff Juliano, NVIDIA
-
Carsten Rohde, NVIDIA
-
An application using external memory may wish to synchronize access to that memory using semaphores. This extension enables an application to export semaphore payload to and import semaphore payload from POSIX file descriptors.
New Object Types
None.
New Enum Constants
-
VK_STRUCTURE_TYPE_IMPORT_SEMAPHORE_FD_INFO_KHR
-
VK_STRUCTURE_TYPE_SEMAPHORE_GET_FD_INFO_KHR
New Enums
None.
New Structs
New Functions
Issues
1) Does the application need to close the file descriptor returned by vkGetSemaphoreFdKHR?
RESOLVED: Yes, unless it is passed back in to a driver instance to import the semaphore. A successful get call transfers ownership of the file descriptor to the application, and a successful import transfers it back to the driver. Destroying the original semaphore object will not close the file descriptor or remove its reference to the underlying semaphore resource associated with it.
Version History
-
Revision 1, 2016-10-21 (Jesse Hall)
-
Initial revision
-
VK_KHR_external_semaphore_win32
- Name String
-
VK_KHR_external_semaphore_win32
- Extension Type
-
Device extension
- Registered Extension Number
-
79
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_KHR_external_semaphore
-
- Contact
-
-
James Jones cubanismo
-
- Last Modified Date
-
2016-10-21
- IP Status
-
No known IP claims.
- Contributors
-
-
James Jones, NVIDIA
-
Jeff Juliano, NVIDIA
-
Carsten Rohde, NVIDIA
-
An application using external memory may wish to synchronize access to that memory using semaphores. This extension enables an application to export semaphore payload to and import semaphore payload from Windows handles.
New Object Types
None.
New Enum Constants
-
VK_STRUCTURE_TYPE_IMPORT_SEMAPHORE_WIN32_HANDLE_INFO_KHR
-
VK_STRUCTURE_TYPE_EXPORT_SEMAPHORE_WIN32_HANDLE_INFO_KHR
-
VK_STRUCTURE_TYPE_D3D12_FENCE_SUBMIT_INFO_KHR
-
VK_STRUCTURE_TYPE_SEMAPHORE_GET_WIN32_HANDLE_INFO_KHR
New Enums
None.
New Structs
New Functions
Issues
1) Do applications need to call CloseHandle
() on the values returned
from vkGetSemaphoreWin32HandleKHR when handleType
is
VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32_BIT_KHR
?
RESOLVED: Yes, unless it is passed back in to another driver instance to import the object. A successful get call transfers ownership of the handle to the application. Destroying the semaphore object will not destroy the handle or the handle’s reference to the underlying semaphore resource.
2) Should the language regarding KMT/Windows 7 handles be moved to a separate extension so that it can be deprecated over time?
RESOLVED: No. Support for them can be deprecated by drivers if they choose, by no longer returning them in the supported handle types of the instance level queries.
3) Should applications be allowed to specify additional object attributes for shared handles?
RESOLVED: Yes. Applications will be allowed to provide similar attributes to those they would to any other handle creation API.
4) How do applications communicate the desired fence values to use with
D3D12_FENCE
-based Vulkan semaphores?
RESOLVED: There are a couple of options. The values for the signaled and reset states could be communicated up front when creating the object and remain static for the life of the Vulkan semaphore, or they could be specified using auxiliary structures when submitting semaphore signal and wait operations, similar to what is done with the keyed mutex extensions. The latter is more flexible and consistent with the keyed mutex usage, but the former is a much simpler API.
Since Vulkan tends to favor flexibility and consistency over simplicity, a new structure specifying D3D12 fence acquire and release values is added to the vkQueueSubmit function.
Version History
-
Revision 1, 2016-10-21 (James Jones)
-
Initial revision
-
VK_KHR_get_display_properties2
- Name String
-
VK_KHR_get_display_properties2
- Extension Type
-
Instance extension
- Registered Extension Number
-
122
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_KHR_display
-
- Contact
-
-
James Jones cubanismo
-
- Last Modified Date
-
2017-02-21
- IP Status
-
No known IP claims.
- Contributors
-
-
Ian Elliott, Google
-
James Jones, NVIDIA
-
This extension provides new entry points to query device display properties
and capabilities in a way that can be easily extended by other extensions,
without introducing any further entry points.
This extension can be considered the VK_KHR_display
equivalent of the
VK_KHR_get_physical_device_properties2
extension.
New Object Types
None.
New Enum Constants
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_DISPLAY_PROPERTIES_2_KHR
-
VK_STRUCTURE_TYPE_DISPLAY_PLANE_PROPERTIES_2_KHR
-
VK_STRUCTURE_TYPE_DISPLAY_MODE_PROPERTIES_2_KHR
-
VK_STRUCTURE_TYPE_DISPLAY_PLANE_INFO_2_KHR
-
VK_STRUCTURE_TYPE_DISPLAY_PLANE_CAPABILITIES_2_KHR
-
New Enums
None.
New Structures
New Functions
Issues
1) What should this extension be named?
RESOLVED: VK_KHR_get_display_properties2
.
Other alternatives:
-
VK_KHR_display2
-
One extension, combined with
VK_KHR_surface_capabilites2
.
2) Should extensible input structs be added for these new functions:
RESOLVED:
-
vkGetPhysicalDeviceDisplayProperties2KHR: No. The only current input is a VkPhysicalDevice. Other inputs wouldn’t make sense.
-
vkGetPhysicalDeviceDisplayPlaneProperties2KHR: No. The only current input is a VkPhysicalDevice. Other inputs wouldn’t make sense.
-
vkGetDisplayModeProperties2KHR: No. The only current inputs are a VkPhysicalDevice and a VkDisplayModeKHR. Other inputs wouldn’t make sense.
3) Should additional display query functions be extended?
RESOLVED:
-
vkGetDisplayPlaneSupportedDisplaysKHR: No. Extensions should instead extend vkGetDisplayPlaneCapabilitiesKHR().
Version History
-
Revision 1, 2017-02-21 (James Jones)
-
Initial draft.
-
VK_KHR_get_surface_capabilities2
- Name String
-
VK_KHR_get_surface_capabilities2
- Extension Type
-
Instance extension
- Registered Extension Number
-
120
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_KHR_surface
-
- Contact
-
-
James Jones cubanismo
-
- Last Modified Date
-
2017-02-27
- IP Status
-
No known IP claims.
- Contributors
-
-
Ian Elliott, Google
-
James Jones, NVIDIA
-
Alon Or-bach, Samsung
-
This extension provides new entry points to query device surface
capabilities in a way that can be easily extended by other extensions,
without introducing any further entry points.
This extension can be considered the VK_KHR_surface
equivalent of the
VK_KHR_get_physical_device_properties2
extension.
New Object Types
None.
New Enum Constants
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SURFACE_INFO_2_KHR
-
VK_STRUCTURE_TYPE_SURFACE_CAPABILITIES_2_KHR
-
VK_STRUCTURE_TYPE_SURFACE_FORMAT_2_KHR
-
New Enums
None.
Issues
1) What should this extension be named?
RESOLVED: VK_KHR_get_surface_capabilities2
.
Other alternatives:
-
VK_KHR_surface2
-
One extension, combining a separate display-specific query extension.
2) Should additional WSI query functions be extended?
RESOLVED:
-
vkGetPhysicalDeviceSurfaceCapabilitiesKHR: Yes. The need for this motivated the extension.
-
vkGetPhysicalDeviceSurfaceSupportKHR: No. Currently only has boolean output. Extensions should instead extend vkGetPhysicalDeviceSurfaceCapabilities2KHR.
-
vkGetPhysicalDeviceSurfacePresentModesKHR: No. Recent discussion concluded this introduced too much variability for applications to deal with. Extensions should instead extend vkGetPhysicalDeviceSurfaceCapabilities2KHR.
-
vkGetPhysicalDeviceXlibPresentationSupportKHR: Not in this extension.
-
vkGetPhysicalDeviceXcbPresentationSupportKHR: Not in this extension.
-
vkGetPhysicalDeviceWaylandPresentationSupportKHR: Not in this extension.
-
vkGetPhysicalDeviceWin32PresentationSupportKHR: Not in this extension.
Version History
-
Revision 1, 2017-02-27 (James Jones)
-
Initial draft.
-
VK_KHR_image_format_list
- Name String
-
VK_KHR_image_format_list
- Extension Type
-
Device extension
- Registered Extension Number
-
148
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Jason Ekstrand jekstrand
-
- Last Modified Date
-
2017-03-20
- IP Status
-
No known IP claims.
- Contributors
-
-
Jason Ekstrand, Intel
-
Jan-Harald Fredriksen, ARM
-
Jeff Bolz, NVIDIA
-
Jeff Leger, Qualcomm
-
Neil Henning, Codeplay
-
On some implementations, setting the
VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT
on image creation can cause access
to that image to perform worse than an equivalent image created without
VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT
because the implementation does not
know what view formats will be paired with the image.
This extension allows an application to provide the list of all formats that can be used with an image when it is created. The implementation may then be able to create a more efficient image that supports the subset of formats required by the application without having to support all formats in the format compatibility class of the image format.
New Object Types
None.
New Enum Constants
-
VK_STRUCTURE_TYPE_IMAGE_FORMAT_LIST_CREATE_INFO_KHR
New Enums
None.
New Structs
New Functions
None.
Issues
Version History
-
Revision 1, 2017-03-20 (Jason Ekstrand)
-
Initial revision
-
VK_KHR_imageless_framebuffer
- Name String
-
VK_KHR_imageless_framebuffer
- Extension Type
-
Device extension
- Registered Extension Number
-
109
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_KHR_maintenance2
-
Requires
VK_KHR_image_format_list
-
- Contact
-
-
Tobias Hector tobias
-
- Last Modified Date
-
2018-12-14
- Contributors
-
-
Tobias Hector
-
Graham Wihlidal
-
This extension allows framebuffers to be created without the need for creating images first, allowing more flexibility in how they are used, and avoiding the need for many of the confusing compatibility rules.
Framebuffers are now created with a small amount of additional metadata about the image views that will be used in VkFramebufferAttachmentsCreateInfoKHR, and the actual image views are provided at render pass begin time via VkRenderPassAttachmentBeginInfoKHR.
New Enum Constants
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGELESS_FRAMEBUFFER_FEATURES_KHR
-
VK_STRUCTURE_TYPE_FRAMEBUFFER_ATTACHMENTS_CREATE_INFO_KHR
-
VK_STRUCTURE_TYPE_FRAMEBUFFER_ATTACHMENT_IMAGE_INFO_KHR
-
VK_STRUCTURE_TYPE_RENDER_PASS_ATTACHMENT_BEGIN_INFO_KHR
-
-
Extending VkFramebufferCreateFlagBits:
-
VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT_KHR
-
New Structures
Version History
-
Revision 1, 2018-12-14 (Tobias Hector)
-
Internal revisions
-
VK_KHR_incremental_present
- Name String
-
VK_KHR_incremental_present
- Extension Type
-
Device extension
- Registered Extension Number
-
85
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_KHR_swapchain
-
- Contact
-
-
Ian Elliott ianelliottus
-
- Last Modified Date
-
2016-11-02
- IP Status
-
No known IP claims.
- Contributors
-
-
Ian Elliott, Google
-
Jesse Hall, Google
-
Alon Or-bach, Samsung
-
James Jones, NVIDIA
-
Daniel Rakos, AMD
-
Ray Smith, ARM
-
Mika Isojarvi, Google
-
Jeff Juliano, NVIDIA
-
Jeff Bolz, NVIDIA
-
This device extension extends vkQueuePresentKHR, from the
VK_KHR_swapchain
extension, allowing an application to specify a list
of rectangular, modified regions of each image to present.
This should be used in situations where an application is only changing a
small portion of the presentable images within a swapchain, since it enables
the presentation engine to avoid wasting time presenting parts of the
surface that have not changed.
This extension is leveraged from the EGL_KHR_swap_buffers_with_damage
extension.
New Object Types
None.
New Enum Constants
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PRESENT_REGIONS_KHR
-
New Enums
None.
New Structures
New Functions
None.
Examples
None.
Issues
1) How should we handle steroescopic-3D swapchains? We need to add a layer
for each rectangle.
One approach is to create another struct containing the VkRect2D plus
layer, and have VkPresentRegionsKHR point to an array of that struct.
Another approach is to have two parallel arrays, pRectangles
and
pLayers
, where pRectangles
[i] and pLayers
[i] must be used
together.
Which approach should we use, and if the array of a new structure, what
should that be called?
RESOLVED: Create a new structure, which is a VkRect2D plus a layer, and will be called VkRectLayerKHR.
2) Where is the origin of the VkRectLayerKHR?
RESOLVED: The upper left corner of the presentable image(s) of the swapchain, per the definition of framebuffer coordinates.
3) Does the rectangular region, VkRectLayerKHR, specify pixels of the swapchain’s image(s), or of the surface?
RESOLVED: Of the image(s). Some presentation engines may scale the pixels of a swapchain’s image(s) to the size of the surface. The size of the swapchain’s image(s) will be consistent, where the size of the surface may vary over time.
4) What if all of the rectangles for a given swapchain contain a width and/or height of zero?
RESOLVED: The application is indicating that no pixels changed since the last present. The presentation engine may use such a hint and not update any pixels for the swapchain. However, all other semantics of vkQueuePresentKHR must still be honored, including waiting for semaphores to signal.
Version History
-
Revision 1, 2016-11-02 (Ian Elliott)
-
Internal revisions
-
VK_KHR_performance_query
- Name String
-
VK_KHR_performance_query
- Extension Type
-
Device extension
- Registered Extension Number
-
117
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Alon Or-bach alonorbach
-
- Last Modified Date
-
2019-10-08
- IP Status
-
No known IP claims.
- Contributors
-
-
Jesse Barker, Unity Technologies
-
Kenneth Benzie, Codeplay
-
Jan-Harald Fredriksen, ARM
-
Jeff Leger, Qualcomm
-
Jesse Hall, Google
-
Tobias Hector, AMD
-
Neil Henning, Codeplay
-
Baldur Karlsson
-
Lionel Landwerlin, Intel
-
Peter Lohrmann, AMD
-
Alon Or-bach, Samsung
-
Daniel Rakos, AMD
-
Niklas Smedberg, Unity Technologies
-
Igor Ostrowski, Intel
-
The VK_KHR_performance_query
extension adds a mechanism to allow querying
of performance counters for use in applications and by profiling tools.
Each queue family may expose counters that can be enabled on a queue of that family. We extend VkQueryType to add a new query type for performance queries, and chain a structure on VkQueryPoolCreateInfo to specify the performance queries to enable.
New Object Types
None.
New Enum Constants
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PERFORMANCE_QUERY_FEATURES_KHR
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PERFORMANCE_QUERY_PROPERTIES_KHR
-
VK_STRUCTURE_TYPE_PERFORMANCE_COUNTER_KHR
-
VK_STRUCTURE_TYPE_PERFORMANCE_COUNTER_DESCRIPTION_KHR
-
VK_STRUCTURE_TYPE_QUERY_POOL_PERFORMANCE_CREATE_INFO_KHR
-
VK_STRUCTURE_TYPE_PERFORMANCE_QUERY_SUBMIT_INFO_KHR
-
VK_STRUCTURE_TYPE_ACQUIRE_PROFILING_LOCK_INFO_KHR
-
-
Extending VkQueryType:
-
VK_QUERY_TYPE_PERFORMANCE_QUERY_KHR
-
New Enums
New Structures
New Functions
Issues
1) Should this extension include a mechanism to begin a query in command buffer A and end the query in command buffer B?
RESOLVED No - queries are tied to command buffer creation and thus have to be encapsulated within a single command buffer.
2) Should this extension include a mechanism to begin and end queries globally on the queue, not using the existing command buffer commands?
RESOLVED No - for the same reasoning as the resolution of 1).
3) Should this extension expose counters that require multiple passes?
RESOLVED Yes - users should re-submit a command buffer with the same commands in it multiple times, specifying the pass to count as the query parameter in VkPerformanceQuerySubmitInfoKHR.
4) How to handle counters across parallel workloads?
RESOLVED In the spirit of Vulkan, a counter description flag
VK_PERFORMANCE_COUNTER_DESCRIPTION_CONCURRENTLY_IMPACTED_KHR
denotes
that the accuracy of a counter result is affected by parallel workloads.
5) How to handle secondary command buffers?
RESOLVED Secondary command buffers inherit any counter pass index specified in the parent primary command buffer. Note: this is no longer an issue after change from issue 10 resolution
6) What commands does the profiling lock have to be held for?
RESOLVED For any command buffer that is being queried with a performance query pool, the profiling lock must be held while that command buffer is in the recording, executable, or pending state.
7) Should we support vkCmdCopyQueryPoolResults?
RESOLVED Yes.
8) Should we allow performance queries to interact with multiview?
RESOLVED Yes, but the performance queries must be performed once for each pass per view.
9) Should a queryCount > 1
be usable for performance queries?
RESOLVED Yes.
Some vendors will have costly performance counter query pool creation, and
would rather if a certain set of counters were to be used multiple times
that a queryCount > 1
can be used to amortize the instantiation cost.
10) Should we introduce an indirect mechanism to set the counter pass index?
RESOLVED Specify the counter pass index at submit time instead to avoid requiring re-recording of command buffers when multiple counter passes needed.
Examples
The following example shows how to find what performance counters a queue family supports, setup a query pool to record these performance counters, how to add the query pool to the command buffer to record information, and how to get the results from the query pool.
// A previously created physical device
VkPhysicalDevice physicalDevice;
// One of the queue families our device supports
uint32_t queueFamilyIndex;
uint32_t counterCount;
// Get the count of counters supported
vkEnumeratePhysicalDeviceQueueFamilyPerformanceQueryCountersKHR(
physicalDevice,
queueFamilyIndex,
&counterCount,
NULL,
NULL);
VkPerformanceCounterKHR* counters =
malloc(sizeof(VkPerformanceCounterKHR) * counterCount);
VkPerformanceCounterDescriptionKHR* counterDescriptions =
malloc(sizeof(VkPerformanceCounterDescriptionKHR) * counterCount);
// Get the counters supported
vkEnumeratePhysicalDeviceQueueFamilyPerformanceQueryCountersKHR(
physicalDevice,
queueFamilyIndex,
&counterCount,
counters,
counterDescriptions);
// Try to enable the first 8 counters
uint32_t enabledCounters[8];
const uint32_t enabledCounterCount = min(counterCount, 8));
for (uint32_t i = 0; i < enabledCounterCount; i++) {
enabledCounters[i] = i;
}
// A previously created device that had the performanceCounterQueryPools feature
// set to VK_TRUE
VkDevice device;
VkQueryPoolPerformanceCreateInfoKHR performanceQueryCreateInfo = {
VK_STRUCTURE_TYPE_QUERY_POOL_PERFORMANCE_CREATE_INFO_KHR,
NULL,
// Specify the queue family that this performance query is performed on
queueFamilyIndex,
// The number of counters to enable
enabledCounterCount,
// The array of indices of counters to enable
enabledCounters
};
// Get the number of passes our counters will require.
uint32_t numPasses;
vkGetPhysicalDeviceQueueFamilyPerformanceQueryPassesKHR(
physicalDevice,
&performanceQueryCreateInfo,
&numPasses);
VkQueryPoolCreateInfo queryPoolCreateInfo = {
VK_STRUCTURE_TYPE_QUERY_POOL_CREATE_INFO,
&performanceQueryCreateInfo,
0,
// Using our new query type here
VK_QUERY_TYPE_PERFORMANCE_QUERY_KHR,
1,
0
};
VkQueryPool queryPool;
VkResult result = vkCreateQueryPool(
device,
&queryPoolCreateInfo,
NULL,
&queryPool);
assert(VK_SUCCESS == result);
// A queue from queueFamilyIndex
VkQueue queue;
// A command buffer we want to record counters on
VkCommandBuffer commandBuffer;
VkCommandBufferBeginInfo commandBufferBeginInfo = {
VK_STRUCTURE_TYPE_COMMAND_BUFFER_BEGIN_INFO,
NULL,
0,
NULL
};
VkAcquireProfilingLockInfoKHR lockInfo = {
VK_STRUCTURE_TYPE_ACQUIRE_PROFILING_LOCK_INFO_KHR,
NULL,
0,
UINT64_MAX // Wait forever for the lock
};
// Acquire the profiling lock before we record command buffers
// that will use performance queries
result = vkAcquireProfilingLockKHR(device, &lockInfo);
assert(VK_SUCCESS == result);
result = vkBeginCommandBuffer(commandBuffer, &commandBufferBeginInfo);
assert(VK_SUCCESS == result);
vkCmdResetQueryPool(
commandBuffer,
queryPool,
0,
1);
vkCmdBeginQuery(
commandBuffer,
queryPool,
0,
0);
// Perform the commands you want to get performance information on
// ...
// Perform a barrier to ensure all previous commands were complete before
// ending the query
vkCmdPipelineBarrier(commandBuffer,
VK_PIPELINE_STAGE_BOTTOM_OF_PIPE_BIT,
VK_PIPELINE_STAGE_BOTTOM_OF_PIPE_BIT,
0,
0,
NULL,
0,
NULL,
0,
NULL);
vkCmdEndQuery(
commandBuffer,
queryPool,
0);
result = vkEndCommandBuffer(commandBuffer);
assert(VK_SUCCESS == result);
for (uint32_t counterPass = 0; counterPass < numPasses; counterPass++) {
VkPerformanceQuerySubmitInfoKHR performanceQuerySubmitInfo = {
VK_STRUCTURE_TYPE_PERFORMANCE_QUERY_SUBMIT_INFO_KHR,
NULL,
counterPass
};
// Submit the command buffer and wait for its completion
// ...
}
// Release the profiling lock after the command buffer is no longer in the
// pending state.
vkReleaseProfilingLockKHR(device);
result = vkResetCommandBuffer(commandBuffer, 0);
assert(VK_SUCCESS == result);
// Create an array to hold the results of all counters
VkPerformanceCounterResultKHR* recordedCounters = malloc(
sizeof(VkPerformanceCounterResultKHR) * enabledCounterCount);
result = vkGetQueryPoolResults(
device,
queryPool,
0,
1,
sizeof(VkPerformanceCounterResultKHR) * enabledCounterCount,
recordedCounters,
sizeof(VkPerformanceCounterResultKHR),
NULL);
// recordedCounters is filled with our counters, we'll look at one for posterity
switch (counters[0].storage) {
case VK_PERFORMANCE_COUNTER_STORAGE_INT32:
// use recordCounters[0].int32 to get at the counter result!
break;
case VK_PERFORMANCE_COUNTER_STORAGE_INT64:
// use recordCounters[0].int64 to get at the counter result!
break;
case VK_PERFORMANCE_COUNTER_STORAGE_UINT32:
// use recordCounters[0].uint32 to get at the counter result!
break;
case VK_PERFORMANCE_COUNTER_STORAGE_UINT64:
// use recordCounters[0].uint64 to get at the counter result!
break;
case VK_PERFORMANCE_COUNTER_STORAGE_FLOAT32:
// use recordCounters[0].float32 to get at the counter result!
break;
case VK_PERFORMANCE_COUNTER_STORAGE_FLOAT64:
// use recordCounters[0].float64 to get at the counter result!
break;
}
Version History
-
Revision 1, 2019-10-08
VK_KHR_pipeline_executable_properties
- Name String
-
VK_KHR_pipeline_executable_properties
- Extension Type
-
Device extension
- Registered Extension Number
-
270
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Jason Ekstrand jekstrand
-
- Last Modified Date
-
2019-05-28
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
- Contributors
-
-
Jason Ekstrand, Intel
-
Ian Romanick, Intel
-
Kenneth Graunke, Intel
-
Baldur Karlsson, Valve
-
Jesse Hall, Google
-
Jeff Bolz, Nvidia
-
Piers Daniel, Nvidia
-
Tobias Hector, AMD
-
Jan-Harald Fredriksen, ARM
-
Tom Olson, ARM
-
Daniel Koch, Nvidia
-
Spencer Fricke, Samsung
-
When a pipeline is created, its state and shaders are compiled into zero or more device-specific executables, which are used when executing commands against that pipeline. This extension adds a mechanism to query properties and statistics about the different executables produced by the pipeline compilation process. This is intended to be used by debugging and performance tools to allow them to provide more detailed information to the user. Certain compile-time shader statistics provided through this extension may be useful to developers for debugging or performance analysis.
New Enum Constants
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PIPELINE_EXECUTABLE_PROPERTIES_FEATURES_KHR
-
VK_STRUCTURE_TYPE_PIPELINE_INFO_KHR
-
VK_STRUCTURE_TYPE_PIPELINE_EXECUTABLE_PROPERTIES_KHR
-
VK_STRUCTURE_TYPE_PIPELINE_EXECUTABLE_INFO_KHR
-
VK_STRUCTURE_TYPE_PIPELINE_EXECUTABLE_STATISTIC_KHR
-
VK_STRUCTURE_TYPE_PIPELINE_EXECUTABLE_INTERNAL_REPRESENTATION_KHR
-
-
Extending VkPipelineCreateFlagBits:
-
VK_PIPELINE_CREATE_CAPTURE_STATISTICS_BIT_KHR
-
VK_PIPELINE_CREATE_CAPTURE_INTERNAL_REPRESENTATIONS_BIT_KHR
-
New Enums
New Structures
New Functions
Issues
1) What should we call the pieces of the pipeline which are produced by the compilation process and about which you can query properties and statistics?
RESOLVED: Call them "executables". The name "binary" was used in early drafts of the extension but it was determined that "pipeline binary" could have a fairly broad meaning (such as a binary serialized form of an entire pipeline) and was too big of a namespace for the very specific needs of this extension.
Version History
-
Revision 1, 2019-05-28 (Jason Ekstrand)
-
Initial draft
-
VK_KHR_push_descriptor
- Name String
-
VK_KHR_push_descriptor
- Extension Type
-
Device extension
- Registered Extension Number
-
81
- Revision
-
2
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Jeff Bolz jeffbolznv
-
- Last Modified Date
-
2017-09-12
- IP Status
-
No known IP claims.
- Contributors
-
-
Jeff Bolz, NVIDIA
-
Michael Worcester, Imagination Technologies
-
This extension allows descriptors to be written into the command buffer, while the implementation is responsible for managing their memory. Push descriptors may enable easier porting from older APIs and in some cases can be more efficient than writing descriptors into descriptor sets.
New Object Types
None.
New Enum Constants
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PUSH_DESCRIPTOR_PROPERTIES_KHR
-
-
Extending VkDescriptorSetLayoutCreateFlagBits
-
VK_DESCRIPTOR_SET_LAYOUT_CREATE_PUSH_DESCRIPTOR_BIT_KHR
-
-
Extending VkDescriptorUpdateTemplateType
-
VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_PUSH_DESCRIPTORS_KHR
-
New Enums
None.
New Structures
Issues
None.
Examples
None.
Version History
-
Revision 1, 2016-10-15 (Jeff Bolz)
-
Internal revisions
-
-
Revision 2, 2017-09-12 (Tobias Hector)
-
Added interactions with Vulkan 1.1
-
VK_KHR_sampler_mirror_clamp_to_edge
- Name String
-
VK_KHR_sampler_mirror_clamp_to_edge
- Extension Type
-
Device extension
- Registered Extension Number
-
15
- Revision
-
3
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Tobias Hector tobski
-
- Last Modified Date
-
2019-08-17
- Contributors
-
-
Tobias Hector, Imagination Technologies
-
Jon Leech, Khronos
-
VK_KHR_sampler_mirror_clamp_to_edge
extends the set of sampler address
modes to include an additional mode
(VK_SAMPLER_ADDRESS_MODE_MIRROR_CLAMP_TO_EDGE
) that effectively uses a
texture map twice as large as the original image in which the additional
half of the new image is a mirror image of the original image.
This new mode relaxes the need to generate images whose opposite edges match by using the original image to generate a matching “mirror image”. This mode allows the texture to be mirrored only once in the negative s, t, and r directions.
New Enum Constants
-
Extending VkSamplerAddressMode:
-
VK_SAMPLER_ADDRESS_MODE_MIRROR_CLAMP_TO_EDGE
-
Example
Creating a sampler with the new address mode in each dimension
VkSamplerCreateInfo createInfo =
{
VK_STRUCTURE_TYPE_SAMPLER_CREATE_INFO // sType
// Other members set to application-desired values
};
createInfo.addressModeU = VK_SAMPLER_ADDRESS_MODE_MIRROR_CLAMP_TO_EDGE;
createInfo.addressModeV = VK_SAMPLER_ADDRESS_MODE_MIRROR_CLAMP_TO_EDGE;
createInfo.addressModeW = VK_SAMPLER_ADDRESS_MODE_MIRROR_CLAMP_TO_EDGE;
VkSampler sampler;
VkResult result = vkCreateSampler(
device,
&createInfo,
&sampler);
Issues
1) Why are both KHR and core versions of the
VK_SAMPLER_ADDRESS_MODE_MIRROR_CLAMP_TO_EDGE
token present?
RESOLVED: This functionality was intended to be required in Vulkan 1.0. We realized shortly before public release that not all implementations could support it, and moved the functionality into an optional extension, but did not apply the KHR extension suffix. Adding a KHR-suffixed alias of the non-suffixed enum has been done to comply with our own naming rules.
In a related change, before spec revision 1.1.121 this extension was hardwiring into the spec Makefile so it was always included with the Specification, even in the core-only versions. This has now been reverted, and it is treated as any other extension.
Version History
-
Revision 1, 2016-02-16 (Tobias Hector)
-
Initial draft
-
-
Revision 2, 2019-08-14 (Jon Leech)
-
Add KHR-suffixed alias of non-suffixed enum.
-
-
Revision 3, 2019-08-17 (Jon Leech)
-
Add an issue explaining the reason for the extension API not being suffixed with KHR.
-
VK_KHR_separate_depth_stencil_layouts
- Name String
-
VK_KHR_separate_depth_stencil_layouts
- Extension Type
-
Device extension
- Registered Extension Number
-
242
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_KHR_create_renderpass2
-
- Contact
-
-
Piers Daniell pdaniell-nv
-
- Last Modified Data
-
2019-06-25
- Contributors
-
-
Daniel Koch, NVIDIA
-
Jeff Bolz, NVIDIA
-
Jesse Barker, Unity
-
Tobias Hector, AMD
-
This extension allows image memory barriers for depth/stencil images to have
just one of the VK_IMAGE_ASPECT_DEPTH_BIT
or
VK_IMAGE_ASPECT_STENCIL_BIT
aspect bits set, rather than require both.
This allows their layouts to be set independently.
To support depth/stencil images with different layouts for the depth and
stencil aspects, the depth/stencil attachment interface has been updated to
support a separate layout for stencil.
New Object Types
None.
New Enum Constants
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SEPARATE_DEPTH_STENCIL_LAYOUTS_FEATURES_KHR
-
VK_STRUCTURE_TYPE_ATTACHMENT_REFERENCE_STENCIL_LAYOUT_KHR
-
VK_STRUCTURE_TYPE_ATTACHMENT_DESCRIPTION_STENCIL_LAYOUT_KHR
-
-
Extending VkImageLayout:
-
VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL_KHR
-
VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL_KHR
-
VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL_KHR
-
VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL_KHR
-
New Enums
None.
New Structures
New Functions
None.
New SPIR-V Capabilities
None.
Issues
None.
Version History
-
Revision 1, 2019-06-25 (Piers Daniell)
-
Internal revisions
-
VK_KHR_shader_atomic_int64
- Name String
-
VK_KHR_shader_atomic_int64
- Extension Type
-
Device extension
- Registered Extension Number
-
181
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Aaron Hagan ahagan
-
- Last Modified Date
-
2018-07-05
- Interactions and External Dependencies
-
-
This extension requires the
GL_ARB_gpu_shader_int64
andGL_EXT_shader_atomic_int64
extensions for GLSL source languages.
-
- Contributors
-
-
Aaron Hagan, AMD
-
Daniel Rakos, AMD
-
Jeff Bolz, NVIDIA
-
Neil Henning, Codeplay
-
This extension advertises the SPIR-V Int64Atomics capability for Vulkan, which allows a shader to contain 64-bit atomic operations on signed and unsigned integers. The supported operations include OpAtomicMin, OpAtomicMax, OpAtomicAnd, OpAtomicOr, OpAtomicXor, OpAtomicAdd, OpAtomicExchange, and OpAtomicCompareExchange.
New Enum Constants
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_ATOMIC_INT64_FEATURES_KHR
-
New SPIR-V Capabilities
New Structures
Version History
-
Revision 1, 2018-07-05 (Aaron Hagan)
-
Internal revisions
-
VK_KHR_shader_clock
- Name String
-
VK_KHR_shader_clock
- Extension Type
-
Device extension
- Registered Extension Number
-
182
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Aaron Hagan ahagan
-
- Last Modified Date
-
2019-4-25
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
This extension requires
SPV_KHR_shader_clock
. -
This extension enables
ARB_shader_clock
for GLSL source languages. -
This extension enables
EXT_shader_realtime_clock
for GLSL source languages.
-
- Contributors
-
-
Aaron Hagan, AMD
-
Daniel Koch, NVIDIA
-
This extension advertises the SPIR-V ShaderClockKHR
capability for
Vulkan, which allows a shader to query a real-time or monotonically
incrementing counter at the subgroup level or across the device level.
The two valid SPIR-V scopes for OpReadClockKHR
are Subgroup
and
Device
.
When using GLSL source-based shading languages, the
clockRealtime
*EXT
() timing functions map to the
OpReadClockKHR
instruction with a scope of Device
, and the
clock
*ARB
() timing functions map to the OpReadClockKHR
instruction with a scope of Subgroup
.
New Object Types
None.
New Enum Constants
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_CLOCK_FEATURES_KHR
-
New SPIR-V Capabilities
New Structures
Version History
-
Revision 1, 2019-4-25 (Aaron Hagan)
-
Initial revision
-
VK_KHR_shader_float16_int8
- Name String
-
VK_KHR_shader_float16_int8
- Extension Type
-
Device extension
- Registered Extension Number
-
83
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Alexander Galazin alegal-arm
-
- Last Modified Date
-
2018-03-07
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
This extension interacts with
VK_KHR_8bit_storage
-
This extension interacts with
VK_KHR_16bit_storage
-
This extension interacts with
VK_KHR_shader_float_controls
-
- Contributors
-
-
Alexander Galazin, Arm
-
Jan-Harald Fredriksen, Arm
-
Jeff Bolz, NVIDIA
-
Graeme Leese, Broadcom
-
Daniel Rakos, AMD
-
Description
The VK_KHR_shader_float16_int8
extension allows use of 16-bit
floating-point types and 8-bit integer types in shaders for arithmetic
operations.
It introduces two new optional features shaderFloat16
and
shaderInt8
which directly map to the Float16
and the Int8
SPIR-V capabilities.
The VK_KHR_shader_float16_int8
extension also specifies precision
requirements for half-precision floating-point SPIR-V operations.
This extension does not enable use of 8-bit integer types or 16-bit
floating-point types in any shader input and
output interfaces and therefore does not supersede the
VK_KHR_8bit_storage
or VK_KHR_16bit_storage
extensions.
New Enum Constants
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_FLOAT16_INT8_FEATURES_KHR
-
New Structures
New Functions
-
None
Version History
-
Revision 1, 2018-03-07 (Alexander Galazin)
-
Initial draft
-
VK_KHR_shader_float_controls
- Name String
-
VK_KHR_shader_float_controls
- Extension Type
-
Device extension
- Registered Extension Number
-
198
- Revision
-
4
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Alexander Galazin alegal-arm
-
- Last Modified Date
-
2018-09-11
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
This extension requires
SPV_KHR_float_controls
-
- Contributors
-
-
Alexander Galazin, Arm
-
Jan-Harald Fredriksen, Arm
-
Jeff Bolz, NVIDIA
-
Graeme Leese, Broadcom
-
Daniel Rakos, AMD
-
Description
The VK_KHR_shader_float_controls
extension enables efficient use of
floating-point computations through the ability to query and override the
implementation’s default behavior for rounding modes, denormals, signed
zero, and infinity.
New Enum Constants
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FLOAT_CONTROLS_PROPERTIES_KHR
-
New Enums
-
None
New Structures
New Functions
-
None
New SPIR-V Capabilities
Issues
1) Which instructions must flush denorms?
RESOLVED: Only floating-point conversion, floating-point arithmetic,
floating-point relational (except OpIsNaN
, OpIsInf
), and
floating-point GLSL.std.450 extended instructions must flush denormals.
2) What is the denorm behavior for intermediate results?
RESOLVED: When a SPIR-V instruction is implemented as a sequence of other
instructions:
- in the DenormFlushToZero
execution mode the intermediate
instructions may flush denormals, the final result of the sequence must
not be denormal.
- in the DenormPreserve
execution mode denormals must be preserved
throughout the whole sequence.
3) Do denorm and rounding mode controls apply to OpSpecConstantOp
?
RESOLVED: Yes, except when the opcode is OpQuantizeToF16
.
4) The SPIR-V specification says that OpConvertFToU
and
OpConvertFToS
unconditionally round towards zero.
Do the rounding mode controls specified through the execution modes apply to
them?
RESOLVED: No, these instructions unconditionally round towards zero.
5) Do any of the "Pack" GLSL.std.450 instructions count as conversion instructions and have the rounding mode apply?
RESOLVED: No, only instructions listed in the section "3.32.11. Conversion Instructions" of the SPIR-V specification count as conversion instructions.
6) When using inf/nan-ignore mode, what is expected of OpIsNan
and
OpIsInf
?
RESOLVED: These instructions must always accurately detect inf/nan if it is passed to them.
Version 4 API incompatiblity
The original versions of VK_KHR_shader_float_controls
shipped with
booleans named “separateDenormSettings” and
“separateRoundingModeSettings”, which at first glance could have indicated
“they can all independently set, or not”.
However the spec language as written indicated that the 32-bit value could
always be set independently, and only the 16- and 64-bit controls needed to
be the same if these values were VK_FALSE
.
As a result of this slight disparity, and lack of test coverage for this facet of the extension, we ended up with two different behaviors in the wild, where some implementations worked as written, and others worked based on the naming. As these are hard limits in hardware with reasons for exposure as written, it was not possible to standardise on a single way to make this work within the existing API.
No known users of this part of the extension exist in the wild, and as such the Vulkan WG took the unusual step of retroactively changing the once boolean value into a tri-state enum, breaking source compatibility. This was however done in such a way as to retain ABI compatibility, in case any code using this did exist; with the numerical values 0 and 1 retaining their original specified meaning, and a new value signifying the additional “all need to be set together” state. If any applications exist today, compiled binaries will continue to work as written in most cases, but will need changes before the code can be recompiled.
Version History
-
Revision 4, 2019-06-18 (Tobias Hector)
-
Modified settings restrictions, see Version 4 API incompatiblity
-
-
Revision 3, 2018-09-11 (Alexander Galazin)
-
Minor restructuring
-
-
Revision 2, 2018-04-17 (Alexander Galazin)
-
Added issues and resolutions
-
-
Revision 1, 2018-04-11 (Alexander Galazin)
-
Initial draft
-
VK_KHR_shader_subgroup_extended_types
- Name String
-
VK_KHR_shader_subgroup_extended_types
- Extension Type
-
Device extension
- Registered Extension Number
-
176
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.1
-
- Contact
-
-
Neil Henning sheredom
-
- Last Modified Date
-
2019-01-08
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
None.
- Contributors
-
-
Jeff Bolz, NVIDIA
-
Jan-Harald Fredriksen, Arm
-
Neil Henning, AMD
-
Daniel Koch, NVIDIA
-
Jeff Leger, Qualcomm
-
Graeme Leese, Broadcom
-
David Neto, Google
-
Daniel Rakos, AMD
-
This extension enables the Non Uniform Group Operations in SPIR-V to support 8-bit integer, 16-bit integer, 64-bit integer, 16-bit floating-point, and vectors of these types.
New Object Types
None.
New Enum Constants
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_SUBGROUP_EXTENDED_TYPES_FEATURES_KHR
-
New Enums
None.
New Structures
New Functions
None.
New Built-In Variables
None.
New SPIR-V Capabilities
None.
Issues
None.
Version History
-
Revision 1, 2019-01-08 (Neil Henning)
-
Initial draft
-
VK_KHR_shared_presentable_image
- Name String
-
VK_KHR_shared_presentable_image
- Extension Type
-
Device extension
- Registered Extension Number
-
112
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_KHR_swapchain
-
Requires
VK_KHR_get_surface_capabilities2
-
- Contact
-
-
Alon Or-bach alonorbach
-
- Last Modified Date
-
2017-03-20
- IP Status
-
No known IP claims.
- Contributors
-
-
Alon Or-bach, Samsung Electronics
-
Ian Elliott, Google
-
Jesse Hall, Google
-
Pablo Ceballos, Google
-
Chris Forbes, Google
-
Jeff Juliano, NVIDIA
-
James Jones, NVIDIA
-
Daniel Rakos, AMD
-
Tobias Hector, Imagination Technologies
-
Graham Connor, Imagination Technologies
-
Michael Worcester, Imagination Technologies
-
Cass Everitt, Oculus
-
Johannes Van Waveren, Oculus
-
This extension extends VK_KHR_swapchain
to enable creation of a shared
presentable image.
This allows the application to use the image while the presention engine is
accessing it, in order to reduce the latency between rendering and
presentation.
New Object Types
None.
New Enum Constants
-
Extending VkPresentModeKHR:
-
VK_PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR
-
VK_PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR
-
-
Extending VkImageLayout:
-
VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_SHARED_PRESENT_SURFACE_CAPABILITIES_KHR
-
New Enums
None.
New Structures
New Functions
Issues
1) Should we allow a Vulkan WSI swapchain to toggle between normal usage and shared presentation usage?
RESOLVED: No. WSI swapchains are typically recreated with new properties instead of having their properties changed. This can also save resources, assuming that fewer images are needed for shared presentation, and assuming that most VR applications do not need to switch between normal and shared usage.
2) Should we have a query for determining how the presentation engine refresh is triggered?
RESOLVED: Yes. This is done via which presentation modes a surface supports.
3) Should the object representing a shared presentable image be an extension of a VkSwapchainKHR or a separate object?
RESOLVED: Extension of a swapchain due to overlap in creation properties and to allow common functionality between shared and normal presentable images and swapchains.
4) What should we call the extension and the new structures it creates?
RESOLVED: Shared presentable image / shared present.
5) Should the minImageCount
and presentMode
values of the
VkSwapchainCreateInfoKHR be ignored, or required to be compatible
values?
RESOLVED: minImageCount
must be set to 1, and presentMode
should be set to either VK_PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR
or
VK_PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR
.
6) What should the layout of the shared presentable image be?
RESOLVED: After acquiring the shared presentable image, the application
must transition it to the VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR
layout
prior to it being used.
After this initial transition, any image usage that was requested during
swapchain creation can be performed on the image without layout transitions
being performed.
7) Do we need a new API for the trigger to refresh new content?
RESOLVED: vkQueuePresentKHR to act as API to trigger a refresh, as will allow combination with other compatible extensions to vkQueuePresentKHR.
8) How should an application detect a VK_ERROR_OUT_OF_DATE_KHR
error
on a swapchain using the VK_PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR
present mode?
RESOLVED: Introduce vkGetSwapchainStatusKHR to allow applications to query the status of a swapchain using a shared presentation mode.
9) What should subsequent calls to vkQueuePresentKHR for
VK_PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR
swapchains be defined to
do?
RESOLVED: State that implementations may use it as a hint for updated content.
10) Can the ownership of a shared presentable image be transferred to a different queue?
RESOLVED: No.
It is not possible to transfer ownership of a shared presentable image
obtained from a swapchain created using VK_SHARING_MODE_EXCLUSIVE
after it has been presented.
11) How should vkQueueSubmit behave if a command buffer uses an image
from a VK_ERROR_OUT_OF_DATE_KHR
swapchain?
RESOLVED: vkQueueSubmit is expected to return the
VK_ERROR_DEVICE_LOST
error.
12) Can Vulkan provide any guarantee on the order of rendering, to enable beam chasing?
RESOLVED: This could be achieved via use of render passes to ensure strip rendering.
Version History
-
Revision 1, 2017-03-20 (Alon Or-bach)
-
Internal revisions
-
VK_KHR_spirv_1_4
- Name String
-
VK_KHR_spirv_1_4
- Extension Type
-
Device extension
- Registered Extension Number
-
237
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.1
-
Requires
VK_KHR_shader_float_controls
-
- Contact
-
-
Jesse Hall critsec
-
- Last Modified Date
-
2019-04-01
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
Requires SPIR-V 1.4.
-
- Contributors
-
-
Alexander Galazin, Arm
-
David Neto, Google
-
Jesse Hall, Google
-
John Kessenich, Google
-
Neil Henning, AMD
-
Tom Olson, Arm
-
This extension allows the use of SPIR-V 1.4 shader modules. SPIR-V 1.4’s new features primarily make it an easier target for compilers from high-level languages, rather than exposing new hardware functionality.
SPIR-V 1.4 incorporates features that are also available separately as
extensions.
SPIR-V 1.4 shader modules do not need to enable those extensions with the
OpExtension
opcode, since they are integral parts of SPIR-V 1.4.
SPIR-V 1.4 introduces new floating point execution mode capabilities, also
available via SPV_KHR_float_controls
.
Implementations are not required to support all of these new capabilities;
support can be queried using
VkPhysicalDeviceFloatControlsPropertiesKHR from the
VK_KHR_shader_float_controls
extension.
New Object Types
None.
New Enum Constants
None.
New Enums
None.
New Structures
None.
New Functions
None.
Issues
1. Should we have an extension specific to this SPIR-V version, or add a version-generic query for SPIR-V version? SPIR-V 1.4 doesn’t need any other API changes.
RESOLVED: Just expose SPIR-V 1.4.
Most new SPIR-V versions introduce optionally-required capabilities or have implementation-defined limits, and would need more API and specification changes specific to that version to make them available in Vulkan. For example, to support the subgroup features added in SPIR-V 1.3 required introducing VkPhysicalDeviceSubgroupProperties to allow querying the supported subgroup operation categories, maximum supported subgroup size, etc. While we could expose the parts of a new SPIR-V version that don’t need accompanying changes generically, we’ll still end up writing extensions specific to each version for the remaining parts. Thus the generic mechanism won’t reduce future spec-writing effort. In addition, making it clear which parts of a future version are supported by the generic mechanism and which can’t be used without specific support would be difficult to get right ahead of time.
2. Can different stages of the same pipeline use shaders with different SPIR-V versions?
RESOLVED: Yes.
Mixing SPIR-V versions 1.0-1.3 in the same pipeline has not been disallowed, so it would be inconsistent to disallow mixing 1.4 with previous versions.. SPIR-V 1.4 does not introduce anything that should cause new difficulties here.
3. Must Vulkan extensions corresponding to SPIR-V extensions that were promoted to core in 1.4 be enabled in order to use that functionality in a SPIR-V 1.4 module?
RESOLVED: No, with caveats.
The SPIR-V 1.4 module does not need to declare the SPIR-V extensions, since the functionality is now part of core, so there is no need to enable the Vulkan extension that allows SPIR-V modules to declare the SPIR-V extension. However, when the functionality that is now core in SPIR-V 1.4 is optionally supported, the query for support is provided by a Vulkan extension, and that query can only be used if the extension is enabled.
This applies to any SPIR-V version; specifically for SPIR-V 1.4 this only
applies to the functionality from SPV_KHR_float_controls
, which was made
available in Vulkan by VK_KHR_shader_float_controls
.
Even though the extension was promoted in SPIR-V 1.4, the capabilities are
still optional in implementations that support VK_KHR_spirv_1_4
.
A SPIR-V 1.4 module doesn’t need to enable SPV_KHR_float_controls
in order
to use the capabilities, so if the application has a priori knowledge that
the implementation supports the capabilities, it doesn’t need to enable
VK_KHR_shader_float_controls
.
However, if it doesn’t have this knowledge and has to query for support at
runtime, it must enable VK_KHR_shader_float_controls
in order to use
VkPhysicalDeviceFloatControlsPropertiesKHR.
Version History
-
Revision 1, 2019-04-01 (Jesse Hall)
-
Internal draft versions
-
VK_KHR_surface
- Name String
-
VK_KHR_surface
- Extension Type
-
Instance extension
- Registered Extension Number
-
1
- Revision
-
25
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
James Jones cubanismo
-
Ian Elliott ianelliottus
-
- Last Modified Date
-
2016-08-25
- IP Status
-
No known IP claims.
- Contributors
-
-
Patrick Doane, Blizzard
-
Ian Elliott, LunarG
-
Jesse Hall, Google
-
James Jones, NVIDIA
-
David Mao, AMD
-
Norbert Nopper, Freescale
-
Alon Or-bach, Samsung
-
Daniel Rakos, AMD
-
Graham Sellers, AMD
-
Jeff Vigil, Qualcomm
-
Chia-I Wu, LunarG
-
Jason Ekstrand, Intel
-
The VK_KHR_surface
extension is an instance extension.
It introduces VkSurfaceKHR objects, which abstract native platform
surface or window objects for use with Vulkan.
It also provides a way to determine whether a queue family in a physical
device supports presenting to particular surface.
Separate extensions for each platform provide the mechanisms for creating
VkSurfaceKHR objects, but once created they may be used in this and
other platform-independent extensions, in particular the
VK_KHR_swapchain
extension.
New Object Types
New Enum Constants
-
Extending VkResult:
-
VK_ERROR_SURFACE_LOST_KHR
-
VK_ERROR_NATIVE_WINDOW_IN_USE_KHR
-
New Enums
New Structures
New Functions
Examples
Note
The example code for the |
Issues
1) Should this extension include a method to query whether a physical device supports presenting to a specific window or native surface on a given platform?
RESOLVED: Yes. Without this, applications would need to create a device instance to determine whether a particular window can be presented to. Knowing that a device supports presentation to a platform in general is not sufficient, as a single machine might support multiple seats, or instances of the platform that each use different underlying physical devices. Additionally, on some platforms, such as the X Window System, different drivers and devices might be used for different windows depending on which section of the desktop they exist on.
2) Should the vkGetPhysicalDeviceSurfaceCapabilitiesKHR,
vkGetPhysicalDeviceSurfaceFormatsKHR, and
vkGetPhysicalDeviceSurfacePresentModesKHR functions from
VK_KHR_swapchain
be modified to operate on physical devices and moved
to this extension to implement the resolution of issue 1?
RESOLVED: No, separate query functions are needed, as the purposes served
are similar but incompatible.
The vkGetPhysicalDeviceSurface*KHR
functions return information that
could potentially depend on an initialized device.
For example, the formats supported for presentation to the surface might
vary depending on which device extensions are enabled.
The query introduced to resolve issue 1 should be used only to query generic
driver or platform properties.
The physical device parameter is intended to serve only as an identifier
rather than a stateful object.
3) Should Vulkan include support Xlib or XCB as the API for accessing the X Window System platform?
RESOLVED: Both. XCB is a more modern and efficient API, but Xlib usage is deeply ingrained in many applications and likely will remain in use for the foreseeable future. Not all drivers necessarily need to support both, but including both as options in the core specification will probably encourage support, which should in turn ease adoption of the Vulkan API in older codebases. Additionally, the performance improvements possible with XCB likely will not have a measurable impact on the performance of Vulkan presentation and other minimal window system interactions defined here.
4) Should the GBM platform be included in the list of platform enums?
RESOLVED: Deferred, and will be addressed with a platform-specific extension to be written in the future.
Version History
-
Revision 1, 2015-05-20 (James Jones)
-
Initial draft, based on LunarG KHR spec, other KHR specs, patches attached to bugs.
-
-
Revision 2, 2015-05-22 (Ian Elliott)
-
Created initial Description section.
-
Removed query for whether a platform requires the use of a queue for presentation, since it was decided that presentation will always be modeled as being part of the queue.
-
Fixed typos and other minor mistakes.
-
-
Revision 3, 2015-05-26 (Ian Elliott)
-
Improved the Description section.
-
-
Revision 4, 2015-05-27 (James Jones)
-
Fixed compilation errors in example code.
-
-
Revision 5, 2015-06-01 (James Jones)
-
Added issues 1 and 2 and made related spec updates.
-
-
Revision 6, 2015-06-01 (James Jones)
-
Merged the platform type mappings table previously removed from VK_KHR_swapchain with the platform description table in this spec.
-
Added issues 3 and 4 documenting choices made when building the initial list of native platforms supported.
-
-
Revision 7, 2015-06-11 (Ian Elliott)
-
Updated table 1 per input from the KHR TSG.
-
Updated issue 4 (GBM) per discussion with Daniel Stone. He will create a platform-specific extension sometime in the future.
-
-
Revision 8, 2015-06-17 (James Jones)
-
Updated enum-extending values using new convention.
-
Fixed the value of VK_SURFACE_PLATFORM_INFO_TYPE_SUPPORTED_KHR.
-
-
Revision 9, 2015-06-17 (James Jones)
-
Rebased on Vulkan API version 126.
-
-
Revision 10, 2015-06-18 (James Jones)
-
Marked issues 2 and 3 resolved.
-
-
Revision 11, 2015-06-23 (Ian Elliott)
-
Examples now show use of function pointers for extension functions.
-
Eliminated extraneous whitespace.
-
-
Revision 12, 2015-07-07 (Daniel Rakos)
-
Added error section describing when each error is expected to be reported.
-
Replaced the term "queue node index" with "queue family index" in the spec as that is the agreed term to be used in the latest version of the core header and spec.
-
Replaced bool32_t with VkBool32.
-
-
Revision 13, 2015-08-06 (Daniel Rakos)
-
Updated spec against latest core API header version.
-
-
Revision 14, 2015-08-20 (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.
-
Did miscellaneous cleanup, etc.
-
-
Revision 15, 2015-08-20 (Ian Elliott—porting a 2015-07-29 change from James Jones)
-
Moved the surface transform enums here from VK_WSI_swapchain so they could be re-used by VK_WSI_display.
-
-
Revision 16, 2015-09-01 (James Jones)
-
Restore single-field revision number.
-
-
Revision 17, 2015-09-01 (James Jones)
-
Fix example code compilation errors.
-
-
Revision 18, 2015-09-26 (Jesse Hall)
-
Replaced VkSurfaceDescriptionKHR with the VkSurfaceKHR object, which is created via layered extensions. Added VkDestroySurfaceKHR.
-
-
Revision 19, 2015-09-28 (Jesse Hall)
-
Renamed from VK_EXT_KHR_swapchain to VK_EXT_KHR_surface.
-
-
Revision 20, 2015-09-30 (Jeff Vigil)
-
Add error result VK_ERROR_SURFACE_LOST_KHR.
-
-
Revision 21, 2015-10-15 (Daniel Rakos)
-
Updated the resolution of issue #2 and include the surface capability queries in this extension.
-
Renamed SurfaceProperties to SurfaceCapabilities as it better reflects that the values returned are the capabilities of the surface on a particular device.
-
Other minor cleanup and consistency changes.
-
-
Revision 22, 2015-10-26 (Ian Elliott)
-
Renamed from VK_EXT_KHR_surface to VK_KHR_surface.
-
-
Revision 23, 2015-11-03 (Daniel Rakos)
-
Added allocation callbacks to vkDestroySurfaceKHR.
-
-
Revision 24, 2015-11-10 (Jesse Hall)
-
Removed VkSurfaceTransformKHR. Use VkSurfaceTransformFlagBitsKHR instead.
-
Rename VkSurfaceCapabilitiesKHR member maxImageArraySize to maxImageArrayLayers.
-
-
Revision 25, 2016-01-14 (James Jones)
-
Moved VK_ERROR_NATIVE_WINDOW_IN_USE_KHR from the VK_KHR_android_surface to the VK_KHR_surface extension.
-
-
2016-08-23 (Ian Elliott)
-
Update the example code, to not have so many characters per line, and to split out a new example to show how to obtain function pointers.
-
-
2016-08-25 (Ian Elliott)
-
A note was added at the beginning of the example code, stating that it will be removed from future versions of the appendix.
-
VK_KHR_surface_protected_capabilities
- Name String
-
VK_KHR_surface_protected_capabilities
- Extension Type
-
Instance extension
- Registered Extension Number
-
240
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.1
-
Requires
VK_KHR_get_surface_capabilities2
-
- Contact
-
-
Sandeep Shinde sashinde
-
- Last Modified Date
-
2018-12-18
- IP Status
-
No known IP claims.
- Contributors
-
-
Sandeep Shinde, NVIDIA
-
James Jones, NVIDIA
-
Daniel Koch, NVIDIA
-
This extension extends VkSurfaceCapabilities2KHR, providing
applications a way to query whether swapchains can be created with the
VK_SWAPCHAIN_CREATE_PROTECTED_BIT_KHR
flag set.
Vulkan 1.1 added (optional) support for protect memory and protected
resources including buffers (VK_BUFFER_CREATE_PROTECTED_BIT
), images
(VK_IMAGE_CREATE_PROTECTED_BIT
), and swapchains
(VK_SWAPCHAIN_CREATE_PROTECTED_BIT_KHR
).
However, on implementations which support multiple windowing systems, not
all window systems may be able to provide a protected display path.
This extension provides a way to query if a protected swapchain created for a surface (and thus a specific windowing system) can be displayed on screen. It extends the existing VkSurfaceCapabilities2KHR structure with a new VkSurfaceProtectedCapabilitiesKHR structure from which the application can obtain information about support for protected swapchain creation through vkGetPhysicalDeviceSurfaceCapabilities2KHR.
New Object Types
None.
New Enum Constants
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_SURFACE_PROTECTED_CAPABILITIES_KHR
-
New Enums
None.
New Structures
New Functions
None.
Issues
None.
Version History
-
Revision 1, 2018-12-18 (Sandeep Shinde, Daniel Koch)
-
Internal revisions.
-
VK_KHR_swapchain
- Name String
-
VK_KHR_swapchain
- Extension Type
-
Device extension
- Registered Extension Number
-
2
- Revision
-
70
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_KHR_surface
-
- Contact
-
-
James Jones cubanismo
-
Ian Elliott ianelliottus
-
- Last Modified Date
-
2017-10-06
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
Interacts with Vulkan 1.1
-
- Contributors
-
-
Patrick Doane, Blizzard
-
Ian Elliott, LunarG
-
Jesse Hall, Google
-
Mathias Heyer, NVIDIA
-
James Jones, NVIDIA
-
David Mao, AMD
-
Norbert Nopper, Freescale
-
Alon Or-bach, Samsung
-
Daniel Rakos, AMD
-
Graham Sellers, AMD
-
Jeff Vigil, Qualcomm
-
Chia-I Wu, LunarG
-
Jason Ekstrand, Intel
-
Matthaeus G. Chajdas, AMD
-
Ray Smith, ARM
-
The VK_KHR_swapchain
extension is the device-level companion to the
VK_KHR_surface
extension.
It introduces VkSwapchainKHR objects, which provide the ability to
present rendering results to a surface.
New Object Types
New Enum Constants
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_SWAPCHAIN_CREATE_INFO_KHR
-
VK_STRUCTURE_TYPE_PRESENT_INFO_KHR
-
VK_STRUCTURE_TYPE_DEVICE_GROUP_PRESENT_CAPABILITIES_KHR
-
VK_STRUCTURE_TYPE_IMAGE_SWAPCHAIN_CREATE_INFO_KHR
-
VK_STRUCTURE_TYPE_BIND_IMAGE_MEMORY_SWAPCHAIN_INFO_KHR
-
VK_STRUCTURE_TYPE_ACQUIRE_NEXT_IMAGE_INFO_KHR
-
VK_STRUCTURE_TYPE_DEVICE_GROUP_PRESENT_INFO_KHR
-
VK_STRUCTURE_TYPE_DEVICE_GROUP_SWAPCHAIN_CREATE_INFO_KHR
-
-
Extending VkImageLayout:
-
VK_IMAGE_LAYOUT_PRESENT_SRC_KHR
-
-
Extending VkResult:
-
VK_SUBOPTIMAL_KHR
-
VK_ERROR_OUT_OF_DATE_KHR
-
New Structures
New Functions
Issues
1) Does this extension allow the application to specify the memory backing of the presentable images?
RESOLVED: No. Unlike standard images, the implementation will allocate the memory backing of the presentable image.
2) What operations are allowed on presentable images?
RESOLVED: This is determined by the image usage flags specified when creating the presentable image’s swapchain.
3) Does this extension support MSAA presentable images?
RESOLVED: No. Presentable images are always single-sampled. Multi-sampled rendering must use regular images. To present the rendering results the application must manually resolve the multi- sampled image to a single-sampled presentable image prior to presentation.
4) Does this extension support stereo/multi-view presentable images?
RESOLVED: Yes.
The number of views associated with a presentable image is determined by the
imageArrayLayers
specified when creating a swapchain.
All presentable images in a given swapchain use the same array size.
5) Are the layers of stereo presentable images half-sized?
RESOLVED: No. The image extents always match those requested by the application.
6) Do the “present” and “acquire next image” commands operate on a queue? If not, do they need to include explicit semaphore objects to interlock them with queue operations?
RESOLVED: The present command operates on a queue. The image ownership operation it represents happens in order with other operations on the queue, so no explicit semaphore object is required to synchronize its actions.
Applications may want to acquire the next image in separate threads from those in which they manage their queue, or in multiple threads. To make such usage easier, the acquire next image command takes a semaphore to signal as a method of explicit synchronization. The application must later queue a wait for this semaphore before queuing execution of any commands using the image.
7) Does vkAcquireNextImageKHR block if no images are available?
RESOLVED: The command takes a timeout parameter.
Special values for the timeout are 0, which makes the call a non-blocking
operation, and UINT64_MAX
, which blocks indefinitely.
Values in between will block for up to the specified time.
The call will return when an image becomes available or an error occurs.
It may, but is not required to, return before the specified timeout expires
if the swapchain becomes out of date.
8) Can multiple presents be queued using one vkQueuePresentKHR call?
RESOLVED: Yes. VkPresentInfoKHR contains a list of swapchains and corresponding image indices that will be presented. When supported, all presentations queued with a single vkQueuePresentKHR call will be applied atomically as one operation. The same swapchain must not appear in the list more than once. Later extensions may provide applications stronger guarantees of atomicity for such present operations, and/or allow them to query whether atomic presentation of a particular group of swapchains is possible.
9) How do the presentation and acquire next image functions notify the application the targeted surface has changed?
RESOLVED: Two new result codes are introduced for this purpose:
-
VK_SUBOPTIMAL_KHR
- Presentation will still succeed, subject to the window resize behavior, but the swapchain is no longer configured optimally for the surface it targets. Applications should query updated surface information and recreate their swapchain at the next convenient opportunity. -
VK_ERROR_OUT_OF_DATE_KHR
- Failure. The swapchain is no longer compatible with the surface it targets. The application must query updated surface information and recreate the swapchain before presentation will succeed.
These can be returned by both vkAcquireNextImageKHR and vkQueuePresentKHR.
10) Does the vkAcquireNextImageKHR command return a semaphore to the application via an output parameter, or accept a semaphore to signal from the application as an object handle parameter?
RESOLVED: Accept a semaphore to signal as an object handle. This avoids the need to specify whether the application must destroy the semaphore or whether it is owned by the swapchain, and if the latter, what its lifetime is and whether it can be re-used for other operations once it is received from vkAcquireNextImageKHR.
11) What types of swapchain queuing behavior should be exposed? Options include swap interval specification, mailbox/most recent vs. FIFO queue management, targeting specific vertical blank intervals or absolute times for a given present operation, and probably others. For some of these, whether they are specified at swapchain creation time or as per-present parameters needs to be decided as well.
RESOLVED: The base swapchain extension will expose 3 possible behaviors (of which, FIFO will always be supported):
-
Immediate present: Does not wait for vertical blanking period to update the current image, likely resulting in visible tearing. No internal queue is used. Present requests are applied immediately.
-
Mailbox queue: Waits for the next vertical blanking period to update the current image. No tearing should be observed. An internal single-entry queue is used to hold pending presentation requests. If the queue is full when a new presentation request is received, the new request replaces the existing entry, and any images associated with the prior entry become available for re-use by the application.
-
FIFO queue: Waits for the next vertical blanking period to update the current image. No tearing should be observed. An internal queue containing
numSwapchainImages
- 1 entries is used to hold pending presentation requests. New requests are appended to the end of the queue, and one request is removed from the beginning of the queue and processed during each vertical blanking period in which the queue is non-empty
Not all surfaces will support all of these modes, so the modes supported will be returned using a surface info query. All surfaces must support the FIFO queue mode. Applications must choose one of these modes up front when creating a swapchain. Switching modes can be accomplished by recreating the swapchain.
12) Can VK_PRESENT_MODE_MAILBOX_KHR
provide non-blocking guarantees
for vkAcquireNextImageKHR? If so, what is the proper criteria?
RESOLVED: Yes. The difficulty is not immediately obvious here. Naively, if at least 3 images are requested, mailbox mode should always have an image available for the application if the application does not own any images when the call to vkAcquireNextImageKHR was made. However, some presentation engines may have more than one “current” image, and would still need to block in some cases. The right requirement appears to be that if the application allocates the surface’s minimum number of images + 1 then it is guaranteed non-blocking behavior when it does not currently own any images.
13) Is there a way to create and initialize a new swapchain for a surface
that has generated a VK_SUBOPTIMAL_KHR
return code while still using
the old swapchain?
RESOLVED: Not as part of this specification. This could be useful to allow the application to create an “optimal” replacement swapchain and rebuild all its command buffers using it in a background thread at a low priority while continuing to use the “suboptimal” swapchain in the main thread. It could probably use the same “atomic replace” semantics proposed for recreating direct-to-device swapchains without incurring a mode switch. However, after discussion, it was determined some platforms probably could not support concurrent swapchains for the same surface though, so this will be left out of the base KHR extensions. A future extension could add this for platforms where it is supported.
14) Should there be a special value for
VkSurfaceCapabilitiesKHR::maxImageCount
to indicate there are no
practical limits on the number of images in a swapchain?
RESOLVED: Yes. There where often be cases where there is no practical limit to the number of images in a swapchain other than the amount of available resources (I.e., memory) in the system. Trying to derive a hard limit from things like memory size is prone to failure. It is better in such cases to leave it to applications to figure such soft limits out via trial/failure iterations.
15) Should there be a special value for
VkSurfaceCapabilitiesKHR::currentExtent
to indicate the size of
the platform surface is undefined?
RESOLVED: Yes. On some platforms (Wayland, for example), the surface size is defined by the images presented to it rather than the other way around.
16) Should there be a special value for
VkSurfaceCapabilitiesKHR::maxImageExtent
to indicate there is no
practical limit on the surface size?
RESOLVED: No. It seems unlikely such a system would exist. 0 could be used to indicate the platform places no limits on the extents beyond those imposed by Vulkan for normal images, but this query could just as easily return those same limits, so a special “unlimited” value does not seem useful for this field.
17) How should surface rotation and mirroring be exposed to applications? How do they specify rotation and mirroring transforms applied prior to presentation?
RESOLVED: Applications can query both the supported and current transforms
of a surface.
Both are specified relative to the device’s “natural” display rotation and
direction.
The supported transforms indicates which orientations the presentation
engine accepts images in.
For example, a presentation engine that does not support transforming
surfaces as part of presentation, and which is presenting to a surface that
is displayed with a 90-degree rotation, would return only one supported
transform bit: VK_SURFACE_TRANSFORM_ROTATE_90_BIT_KHR
.
Applications must transform their rendering by the transform they specify
when creating the swapchain in preTransform
field.
18) Can surfaces ever not support VK_MIRROR_NONE
? Can they support
vertical and horizontal mirroring simultaneously? Relatedly, should
VK_MIRROR_NONE
[_BIT] be zero, or bit one, and should applications be
allowed to specify multiple pre and current mirror transform bits, or
exactly one?
RESOLVED: Since some platforms may not support presenting with a transform
other than the native window’s current transform, and prerotation/mirroring
are specified relative to the device’s natural rotation and direction,
rather than relative to the surface’s current rotation and direction, it is
necessary to express lack of support for no mirroring.
To allow this, the MIRROR_NONE
enum must occupy a bit in the flags.
Since MIRROR_NONE
must be a bit in the bitmask rather than a bitmask
with no values set, allowing more than one bit to be set in the bitmask
would make it possible to describe undefined transforms such as
VK_MIRROR_NONE_BIT
| VK_MIRROR_HORIZONTAL_BIT
, or a transform
that includes both “no mirroring” and “horizontal mirroring”
simultaneously.
Therefore, it is desirable to allow specifying all supported mirroring
transforms using only one bit.
The question then becomes, should there be a
VK_MIRROR_HORIZONTAL_AND_VERTICAL_BIT
to represent a simultaneous
horizontal and vertical mirror transform? However, such a transform is
equivalent to a 180 degree rotation, so presentation engines and
applications that wish to support or use such a transform can express it
through rotation instead.
Therefore, 3 exclusive bits are sufficient to express all needed mirroring
transforms.
19) Should support for sRGB be required?
RESOLVED: In the advent of UHD and HDR display devices, proper color space information is vital to the display pipeline represented by the swapchain. The app can discover the supported format/color-space pairs and select a pair most suited to its rendering needs. Currently only the sRGB color space is supported, future extensions may provide support for more color spaces. See issues 23 and 24.
20) Is there a mechanism to modify or replace an existing swapchain with one targeting the same surface?
RESOLVED: Yes. This is described above in the text.
21) Should there be a way to set prerotation and mirroring using native APIs when presenting using a Vulkan swapchain?
RESOLVED: Yes.
The transforms that can be expressed in this extension are a subset of those
possible on native platforms.
If a platform exposes a method to specify the transform of presented images
for a given surface using native methods and exposes more transforms or
other properties for surfaces than Vulkan supports, it might be impossible,
difficult, or inconvenient to set some of those properties using Vulkan KHR
extensions and some using the native interfaces.
To avoid overwriting properties set using native commands when presenting
using a Vulkan swapchain, the application can set the pretransform to
“inherit”, in which case the current native properties will be used, or if
none are available, a platform-specific default will be used.
Platforms that do not specify a reasonable default or do not provide native
mechanisms to specify such transforms should not include the inherit bits in
the supportedTransforms
bitmask they return in
VkSurfaceCapabilitiesKHR.
22) Should the content of presentable images be clipped by objects obscuring their target surface?
RESOLVED: Applications can choose which behavior they prefer. Allowing the content to be clipped could enable more optimal presentation methods on some platforms, but some applications might rely on the content of presentable images to perform techniques such as partial updates or motion blurs.
23) What is the purpose of specifying a VkColorSpaceKHR along with VkFormat when creating a swapchain?
RESOLVED: While Vulkan itself is color space agnostic (e.g. even the
meaning of R, G, B and A can be freely defined by the rendering
application), the swapchain eventually will have to present the images on a
display device with specific color reproduction characteristics.
If any color space transformations are necessary before an image can be
displayed, the color space of the presented image must be known to the
swapchain.
A swapchain will only support a restricted set of color format and -space
pairs.
This set can be discovered via vkGetPhysicalDeviceSurfaceFormatsKHR.
As it can be expected that most display devices support the sRGB color
space, at least one format/color-space pair has to be exposed, where the
color space is VK_COLOR_SPACE_SRGB_NONLINEAR_KHR
.
24) How are sRGB formats and the sRGB color space related?
RESOLVED: While Vulkan exposes a number of SRGB texture formats, using
such formats does not guarantee working in a specific color space.
It merely means that the hardware can directly support applying the
non-linear transfer functions defined by the sRGB standard color space when
reading from or writing to images of that these formats.
Still, it is unlikely that a swapchain will expose a *_SRGB
format
along with any color space other than
VK_COLOR_SPACE_SRGB_NONLINEAR_KHR
.
On the other hand, non-*_SRGB
formats will be very likely exposed in
pair with a SRGB color space.
This means, the hardware will not apply any transfer function when reading
from or writing to such images, yet they will still be presented on a device
with sRGB display characteristics.
In this case the application is responsible for applying the transfer
function, for instance by using shader math.
25) How are the lifetime of surfaces and swapchains targeting them related?
RESOLVED: A surface must outlive any swapchains targeting it. A VkSurfaceKHR owns the binding of the native window to the Vulkan driver.
26) How can the client control the way the alpha channel of swapchain images is treated by the presentation engine during compositing?
RESOLVED: We should add new enum values to allow the client to negotiate
with the presentation engine on how to treat image alpha values during the
compositing process.
Since not all platforms can practically control this through the Vulkan
driver, a value of VK_COMPOSITE_ALPHA_INHERIT_BIT_KHR
is provided like
for surface transforms.
27) Is vkCreateSwapchainKHR the right function to return
VK_ERROR_NATIVE_WINDOW_IN_USE_KHR
, or should the various
platform-specific VkSurfaceKHR factory functions catch this error
earlier?
RESOLVED: For most platforms, the VkSurfaceKHR structure is a simple container holding the data that identifies a native window or other object representing a surface on a particular platform. For the surface factory functions to return this error, they would likely need to register a reference on the native objects with the native display server somehow, and ensure no other such references exist. Surfaces were not intended to be that heavyweight.
Swapchains are intended to be the objects that directly manipulate native windows and communicate with the native presentation mechanisms. Swapchains will already need to communicate with the native display server to negotiate allocation and/or presentation of presentable images for a native surface. Therefore, it makes more sense for swapchain creation to be the point at which native object exclusivity is enforced. Platforms may choose to enforce further restrictions on the number of VkSurfaceKHR objects that may be created for the same native window if such a requirement makes sense on a particular platform, but a global requirement is only sensible at the swapchain level.
Examples
Note
The example code for the |
Version History
-
Revision 1, 2015-05-20 (James Jones)
-
Initial draft, based on LunarG KHR spec, other KHR specs, patches attached to bugs.
-
-
Revision 2, 2015-05-22 (Ian Elliott)
-
Made many agreed-upon changes from 2015-05-21 KHR TSG meeting. This includes using only a queue for presentation, and having an explicit function to acquire the next image.
-
Fixed typos and other minor mistakes.
-
-
Revision 3, 2015-05-26 (Ian Elliott)
-
Improved the Description section.
-
Added or resolved issues that were found in improving the Description. For example, pSurfaceDescription is used consistently, instead of sometimes using pSurface.
-
-
Revision 4, 2015-05-27 (James Jones)
-
Fixed some grammatical errors and typos
-
Filled in the description of imageUseFlags when creating a swapchain.
-
Added a description of swapInterval.
-
Replaced the paragraph describing the order of operations on a queue for image ownership and presentation.
-
-
Revision 5, 2015-05-27 (James Jones)
-
Imported relevant issues from the (abandoned) vk_wsi_persistent_swapchain_images extension.
-
Added issues 6 and 7, regarding behavior of the acquire next image and present commands with respect to queues.
-
Updated spec language and examples to align with proposed resolutions to issues 6 and 7.
-
-
Revision 6, 2015-05-27 (James Jones)
-
Added issue 8, regarding atomic presentation of multiple swapchains
-
Updated spec language and examples to align with proposed resolution to issue 8.
-
-
Revision 7, 2015-05-27 (James Jones)
-
Fixed compilation errors in example code, and made related spec fixes.
-
-
Revision 8, 2015-05-27 (James Jones)
-
Added issue 9, and the related VK_SUBOPTIMAL_KHR result code.
-
Renamed VK_OUT_OF_DATE_KHR to VK_ERROR_OUT_OF_DATE_KHR.
-
-
Revision 9, 2015-05-27 (James Jones)
-
Added inline proposed resolutions (marked with [JRJ]) to some XXX questions/issues. These should be moved to the issues section in a subsequent update if the proposals are adopted.
-
-
Revision 10, 2015-05-28 (James Jones)
-
Converted vkAcquireNextImageKHR back to a non-queue operation that uses a VkSemaphore object for explicit synchronization.
-
Added issue 10 to determine whether vkAcquireNextImageKHR generates or returns semaphores, or whether it operates on a semaphore provided by the application.
-
-
Revision 11, 2015-05-28 (James Jones)
-
Marked issues 6, 7, and 8 resolved.
-
Renamed VkSurfaceCapabilityPropertiesKHR to VkSurfacePropertiesKHR to better convey the mutable nature of the info it contains.
-
-
Revision 12, 2015-05-28 (James Jones)
-
Added issue 11 with a proposed resolution, and the related issue 12.
-
Updated various sections of the spec to match the proposed resolution to issue 11.
-
-
Revision 13, 2015-06-01 (James Jones)
-
Moved some structures to VK_EXT_KHR_swap_chain to resolve the spec’s issues 1 and 2.
-
-
Revision 14, 2015-06-01 (James Jones)
-
Added code for example 4 demonstrating how an application might make use of the two different present and acquire next image KHR result codes.
-
Added issue 13.
-
-
Revision 15, 2015-06-01 (James Jones)
-
Added issues 14 - 16 and related spec language.
-
Fixed some spelling errors.
-
Added language describing the meaningful return values for vkAcquireNextImageKHR and vkQueuePresentKHR.
-
-
Revision 16, 2015-06-02 (James Jones)
-
Added issues 17 and 18, as well as related spec language.
-
Removed some erroneous text added by mistake in the last update.
-
-
Revision 17, 2015-06-15 (Ian Elliott)
-
Changed special value from "-1" to "0" so that the data types can be unsigned.
-
-
Revision 18, 2015-06-15 (Ian Elliott)
-
Clarified the values of VkSurfacePropertiesKHR::minImageCount and the timeout parameter of the vkAcquireNextImageKHR function.
-
-
Revision 19, 2015-06-17 (James Jones)
-
Misc. cleanup. Removed resolved inline issues and fixed typos.
-
Fixed clarification of VkSurfacePropertiesKHR::minImageCount made in version 18.
-
Added a brief "Image Ownership" definition to the list of terms used in the spec.
-
-
Revision 20, 2015-06-17 (James Jones)
-
Updated enum-extending values using new convention.
-
-
Revision 21, 2015-06-17 (James Jones)
-
Added language describing how to use VK_IMAGE_LAYOUT_PRESENT_SOURCE_KHR.
-
Cleaned up an XXX comment regarding the description of which queues vkQueuePresentKHR can be used on.
-
-
Revision 22, 2015-06-17 (James Jones)
-
Rebased on Vulkan API version 126.
-
-
Revision 23, 2015-06-18 (James Jones)
-
Updated language for issue 12 to read as a proposed resolution.
-
Marked issues 11, 12, 13, 16, and 17 resolved.
-
Temporarily added links to the relevant bugs under the remaining unresolved issues.
-
Added issues 19 and 20 as well as proposed resolutions.
-
-
Revision 24, 2015-06-19 (Ian Elliott)
-
Changed special value for VkSurfacePropertiesKHR::currentExtent back to "-1" from "0". This value will never need to be unsigned, and "0" is actually a legal value.
-
-
Revision 25, 2015-06-23 (Ian Elliott)
-
Examples now show use of function pointers for extension functions.
-
Eliminated extraneous whitespace.
-
-
Revision 26, 2015-06-25 (Ian Elliott)
-
Resolved Issues 9 & 10 per KHR TSG meeting.
-
-
Revision 27, 2015-06-25 (James Jones)
-
Added oldSwapchain member to VkSwapchainCreateInfoKHR.
-
-
Revision 28, 2015-06-25 (James Jones)
-
Added the "inherit" bits to the rotation and mirroring flags and the associated issue 21.
-
-
Revision 29, 2015-06-25 (James Jones)
-
Added the "clipped" flag to VkSwapchainCreateInfoKHR, and the associated issue 22.
-
Specified that presenting an image does not modify it.
-
-
Revision 30, 2015-06-25 (James Jones)
-
Added language to the spec that clarifies the behavior of vkCreateSwapchainKHR() when the oldSwapchain field of VkSwapchainCreateInfoKHR is not NULL.
-
-
Revision 31, 2015-06-26 (Ian Elliott)
-
Example of new VkSwapchainCreateInfoKHR members, "oldSwapchain" and "clipped".
-
Example of using VkSurfacePropertiesKHR::{min|max}ImageCount to set VkSwapchainCreateInfoKHR::minImageCount.
-
Rename vkGetSurfaceInfoKHR()'s 4th parameter to "pDataSize", for consistency with other functions.
-
Add macro with C-string name of extension (just to header file).
-
-
Revision 32, 2015-06-26 (James Jones)
-
Minor adjustments to the language describing the behavior of "oldSwapchain"
-
Fixed the version date on my previous two updates.
-
-
Revision 33, 2015-06-26 (Jesse Hall)
-
Add usage flags to VkSwapchainCreateInfoKHR
-
-
Revision 34, 2015-06-26 (Ian Elliott)
-
Rename vkQueuePresentKHR()'s 2nd parameter to "pPresentInfo", for consistency with other functions.
-
-
Revision 35, 2015-06-26 (Jason Ekstrand)
-
Merged the VkRotationFlagBitsKHR and VkMirrorFlagBitsKHR enums into a single VkSurfaceTransformFlagBitsKHR enum.
-
-
Revision 36, 2015-06-26 (Jason Ekstrand)
-
Added a VkSurfaceTransformKHR enum that is not a bitmask. Each value in VkSurfaceTransformKHR corresponds directly to one of the bits in VkSurfaceTransformFlagBitsKHR so transforming from one to the other is easy. Having a separate enum means that currentTransform and preTransform are now unambiguous by definition.
-
-
Revision 37, 2015-06-29 (Ian Elliott)
-
Corrected one of the signatures of vkAcquireNextImageKHR, which had the last two parameters switched from what it is elsewhere in the specification and header files.
-
-
Revision 38, 2015-06-30 (Ian Elliott)
-
Corrected a typo in description of the vkGetSwapchainInfoKHR() function.
-
Corrected a typo in header file comment for VkPresentInfoKHR::sType.
-
-
Revision 39, 2015-07-07 (Daniel Rakos)
-
Added error section describing when each error is expected to be reported.
-
Replaced bool32_t with VkBool32.
-
-
Revision 40, 2015-07-10 (Ian Elliott)
-
Updated to work with version 138 of the "vulkan.h" header. This includes declaring the VkSwapchainKHR type using the new VK_DEFINE_NONDISP_HANDLE macro, and no longer extending VkObjectType (which was eliminated).
-
-
Revision 41 2015-07-09 (Mathias Heyer)
-
Added color space language.
-
-
Revision 42, 2015-07-10 (Daniel Rakos)
-
Updated query mechanism to reflect the convention changes done in the core spec.
-
Removed "queue" from the name of VK_STRUCTURE_TYPE_QUEUE_PRESENT_INFO_KHR to be consistent with the established naming convention.
-
Removed reference to the no longer existing VkObjectType enum.
-
-
Revision 43, 2015-07-17 (Daniel Rakos)
-
Added support for concurrent sharing of swapchain images across queue families.
-
Updated sample code based on recent changes
-
-
Revision 44, 2015-07-27 (Ian Elliott)
-
Noted that support for VK_PRESENT_MODE_FIFO_KHR is required. That is ICDs may optionally support IMMEDIATE and MAILBOX, but must support FIFO.
-
-
Revision 45, 2015-08-07 (Ian Elliott)
-
Corrected a typo in spec file (type and variable name had wrong case for the imageColorSpace member of the VkSwapchainCreateInfoKHR struct).
-
Corrected a typo in header file (last parameter in PFN_vkGetSurfacePropertiesKHR was missing "KHR" at the end of type: VkSurfacePropertiesKHR).
-
-
Revision 46, 2015-08-20 (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.
-
Made improvements to several descriptions.
-
Changed the status of several issues from PROPOSED to RESOLVED, leaving no unresolved issues.
-
Resolved several TODOs, did miscellaneous cleanup, etc.
-
-
Revision 47, 2015-08-20 (Ian Elliott—porting a 2015-07-29 change from James Jones)
-
Moved the surface transform enums to VK_WSI_swapchain so they could be re-used by VK_WSI_display.
-
-
Revision 48, 2015-09-01 (James Jones)
-
Various minor cleanups.
-
-
Revision 49, 2015-09-01 (James Jones)
-
Restore single-field revision number.
-
-
Revision 50, 2015-09-01 (James Jones)
-
Update Example #4 to include code that illustrates how to use the oldSwapchain field.
-
-
Revision 51, 2015-09-01 (James Jones)
-
Fix example code compilation errors.
-
-
Revision 52, 2015-09-08 (Matthaeus G. Chajdas)
-
Corrected a typo.
-
-
Revision 53, 2015-09-10 (Alon Or-bach)
-
Removed underscore from SWAP_CHAIN left in VK_STRUCTURE_TYPE_SWAPCHAIN_CREATE_INFO_KHR.
-
-
Revision 54, 2015-09-11 (Jesse Hall)
-
Described the execution and memory coherence requirements for image transitions to and from VK_IMAGE_LAYOUT_PRESENT_SOURCE_KHR.
-
-
Revision 55, 2015-09-11 (Ray Smith)
-
Added errors for destroying and binding memory to presentable images
-
-
Revision 56, 2015-09-18 (James Jones)
-
Added fence argument to vkAcquireNextImageKHR
-
Added example of how to meter a host thread based on presentation rate.
-
-
Revision 57, 2015-09-26 (Jesse Hall)
-
Replace VkSurfaceDescriptionKHR with VkSurfaceKHR.
-
Added issue 25 with agreed resolution.
-
-
Revision 58, 2015-09-28 (Jesse Hall)
-
Renamed from VK_EXT_KHR_device_swapchain to VK_EXT_KHR_swapchain.
-
-
Revision 59, 2015-09-29 (Ian Elliott)
-
Changed vkDestroySwapchainKHR() to return void.
-
-
Revision 60, 2015-10-01 (Jeff Vigil)
-
Added error result VK_ERROR_SURFACE_LOST_KHR.
-
-
Revision 61, 2015-10-05 (Jason Ekstrand)
-
Added the VkCompositeAlpha enum and corresponding structure fields.
-
-
Revision 62, 2015-10-12 (Daniel Rakos)
-
Added VK_PRESENT_MODE_FIFO_RELAXED_KHR.
-
-
Revision 63, 2015-10-15 (Daniel Rakos)
-
Moved surface capability queries to VK_EXT_KHR_surface.
-
-
Revision 64, 2015-10-26 (Ian Elliott)
-
Renamed from VK_EXT_KHR_swapchain to VK_KHR_swapchain.
-
-
Revision 65, 2015-10-28 (Ian Elliott)
-
Added optional pResult member to VkPresentInfoKHR, so that per-swapchain results can be obtained from vkQueuePresentKHR().
-
-
Revision 66, 2015-11-03 (Daniel Rakos)
-
Added allocation callbacks to create and destroy functions.
-
Updated resource transition language.
-
Updated sample code.
-
-
Revision 67, 2015-11-10 (Jesse Hall)
-
Add reserved flags bitmask to VkSwapchainCreateInfoKHR.
-
Modify naming and member ordering to match API style conventions, and so the VkSwapchainCreateInfoKHR image property members mirror corresponding VkImageCreateInfo members but with an 'image' prefix.
-
Make VkPresentInfoKHR::pResults non-const; it is an output array parameter.
-
Make pPresentInfo parameter to vkQueuePresentKHR const.
-
-
Revision 68, 2016-04-05 (Ian Elliott)
-
Moved the "validity" include for vkAcquireNextImage to be in its proper place, after the prototype and list of parameters.
-
Clarified language about presentable images, including how they are acquired, when applications can and cannot use them, etc. As part of this, removed language about "ownership" of presentable images, and replaced it with more-consistent language about presentable images being "acquired" by the application.
-
-
2016-08-23 (Ian Elliott)
-
Update the example code, to use the final API command names, to not have so many characters per line, and to split out a new example to show how to obtain function pointers. This code is more similar to the LunarG "cube" demo program.
-
-
2016-08-25 (Ian Elliott)
-
A note was added at the beginning of the example code, stating that it will be removed from future versions of the appendix.
-
-
Revision 69, 2017-09-07 (Tobias Hector)
-
Added interactions with Vulkan 1.1
-
-
Revision 70, 2017-10-06 (Ian Elliott)
-
Corrected interactions with Vulkan 1.1
-
VK_KHR_swapchain_mutable_format
- Name String
-
VK_KHR_swapchain_mutable_format
- Extension Type
-
Device extension
- Registered Extension Number
-
201
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_KHR_swapchain
-
Requires
VK_KHR_maintenance2
-
Requires
VK_KHR_image_format_list
-
- Contact
-
-
Daniel Rakos drakos-arm
-
- Last Modified Date
-
2018-03-28
- IP Status
-
No known IP claims.
- Contributors
-
-
Jason Ekstrand, Intel
-
Jan-Harald Fredriksen, ARM
-
Jesse Hall, Google
-
Daniel Rakos, AMD
-
Ray Smith, ARM
-
Short Description
Allows processing of swapchain images as different formats to that used by the window system, which is particularly useful for switching between sRGB and linear RGB formats.
Description
This extension adds a new swapchain creation flag that enables creating image views from presentable images with a different format than the one used to create the swapchain.
New Object Types
None.
New Enum Constants
-
Extending VkSwapchainCreateFlagBitsKHR:
-
VK_SWAPCHAIN_CREATE_MUTABLE_FORMAT_BIT_KHR
-
New Enums
None.
New Structures
None.
New Functions
None.
Issues
1) Are there any new capabilities needed?
RESOLVED: No. It is expected that all implementations exposing this extension support swapchain image format mutability.
2) Do we need a separate VK_SWAPCHAIN_CREATE_EXTENDED_USAGE_BIT_KHR
?
RESOLVED: No.
This extension requires VK_KHR_maintenance2
and presentable images of
swapchains created with VK_SWAPCHAIN_CREATE_MUTABLE_FORMAT_BIT_KHR
are
created internally in a way equivalent to specifying both
VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT
and
VK_IMAGE_CREATE_EXTENDED_USAGE_BIT_KHR
.
3) Do we need a separate structure to allow specifying an image format list for swapchains?
RESOLVED: No.
We simply use the same VkImageFormatListCreateInfoKHR structure
introduced by VK_KHR_image_format_list
.
The structure is required to be included in the pNext
chain of
VkSwapchainCreateInfoKHR for swapchains created with
VK_SWAPCHAIN_CREATE_MUTABLE_FORMAT_BIT_KHR
.
Version History
-
Revision 1, 2018-03-28 (Daniel Rakos)
-
Internal revisions.
-
VK_KHR_timeline_semaphore
- Name String
-
VK_KHR_timeline_semaphore
- Extension Type
-
Device extension
- Registered Extension Number
-
208
- Revision
-
2
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Jason Ekstrand jekstrand
-
- Last Modified Date
-
2019-06-12
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
This extension interacts with
VK_KHR_external_semaphore_capabilities
-
This extension interacts with
VK_KHR_external_semaphore
-
This extension interacts with
VK_KHR_external_semaphore_win32
-
- Contributors
-
-
Jeff Bolz, NVIDIA
-
Yuriy O’Donnell, Epic Games
-
Jason Ekstrand, Intel
-
Jesse Hall, Google
-
James Jones, NVIDIA
-
Jeff Juliano, NVIDIA
-
Daniel Rakos, AMD
-
Ray Smith, Arm
-
This extension introduces a new type of semaphore that has an integer payload identifying a point in a timeline. Such timeline semaphores support the following operations:
-
Host query - A host operation that allows querying the payload of the timeline semaphore.
-
Host wait - A host operation that allows a blocking wait for a timeline semaphore to reach a specified value.
-
Host signal - A host operation that allows advancing the timeline semaphore to a specified value.
-
Device wait - A device operation that allows waiting for a timeline semaphore to reach a specified value.
-
Device signal - A device operation that allows advancing the timeline semaphore to a specified value.
New Object Types
None
New Enum Constants
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_TIMELINE_SEMAPHORE_FEATURES_KHR
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_TIMELINE_SEMAPHORE_PROPERTIES_KHR
-
VK_STRUCTURE_TYPE_SEMAPHORE_TYPE_CREATE_INFO_KHR
-
VK_STRUCTURE_TYPE_TIMELINE_SEMAPHORE_SUBMIT_INFO_KHR
-
VK_STRUCTURE_TYPE_SEMAPHORE_WAIT_INFO_KHR
-
VK_STRUCTURE_TYPE_SEMAPHORE_SIGNAL_INFO_KHR
-
New Enums
New Structs
Issues
1) Do we need a new object type for this?
RESOLVED: No, we just introduce a new type of semaphore object, as
VK_KHR_external_semaphore_win32
already uses semaphores as the destination
for importing D3D12 fence objects, which are semantically close/identical to
the proposed synchronization primitive.
2) What type of payload the new synchronization primitive has?
RESOLVED: A 64-bit unsigned integer that can only be set to monotonically increasing values by signal operations and is not changed by wait operations.
3) Does the new synchronization primitive have the same signal-before-wait requirement as the existing semaphores do?
RESOLVED: No. Timeline semaphores support signaling and waiting entirely asynchronously. It is the responsibility of the client to avoid deadlock.
4) Does the new synchronization primitive allow resetting its payload?
RESOLVED: No, allowing the payload value to "go backwards" is problematic. Applications looking for reset behavior should create a new instance of the sychronization primitive instead.
5) How do we enable host waits on the synchronization primitive?
RESOLVED: Both a non-blocking query of the current payload value of the synchronization primitive, and a blocking wait operation are provided.
6) How do we enable device waits and signals on the synchronization primitive?
RESOLVED: Similar to VK_KHR_external_semaphore_win32
, this extension
introduces a new structure that can be chained to VkSubmitInfo to
specify the values signaled semaphores should be set to, and the values
waited semaphores need to reach.
7) Can the new synchronization primitive be used to synchronize presentation and swapchain image acquisition operations?
RESOLVED: Some implementations may have problems with supporting that directly, thus it’s not allowed in this extension.
8) Do we want to support external sharing of the new synchronization primitive type?
RESOLVED: Yes.
Timeline semaphore specific external sharing capabilities can be queried
using vkGetPhysicalDeviceExternalSemaphoreProperties by chaining the
new VkSemaphoreTypeCreateInfoKHR structure to its
pExternalSemaphoreInfo
structure.
This allows having a different set of external semaphore handle types
supported for timeline semaphores vs binary semaphores.
9) Do we need to add a host signal operation for the new synchronization primitive type?
RESOLVED: Yes. This helps in situations where one host thread submits a workload but another host thread has the information on when the workload is ready to be executed.
10) How should the new synchronization primitive interact with the ordering
requirements of the original VkSemaphore
?
RESOLVED: Prior to calling any command which may cause a wait operation on a binary semaphore, the client must ensure that the semaphore signal operation that has been submitted for execution and any semaphore signal operations on which it depends (if any) must have also been submitted for execution.
11) Should we have separate feature bits for different sub-features of timeline semaphores?
RESOLVED: No.
The only feature which cannot be supported universally is timeline semaphore
import/export.
For import/export, the client is already required to query available
external handle types via
vkGetPhysicalDeviceExternalSemaphoreProperties and provide the
semaphore type by adding a VkSemaphoreTypeCreateInfoKHR structure to
the pNext
chain of VkPhysicalDeviceExternalSemaphoreInfo so no
new feature bit is required.
Version History
-
Revision 1, 2018-05-10 (Jason Ekstrand)
-
Initial version
-
-
Revision 2, 2019-06-12 (Jason Ekstrand)
-
Added an initialValue parameter to timeline semaphore creation
-
VK_KHR_uniform_buffer_standard_layout
- Name String
-
VK_KHR_uniform_buffer_standard_layout
- Extension Type
-
Device extension
- Registered Extension Number
-
254
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Graeme Leese gnl21
-
- Last Modified Date
-
2019-01-25
- Contributors
-
-
Graeme Leese, Broadcom
-
Jeff Bolz, NVIDIA
-
Tobias Hector, AMD
-
Jason Ekstrand, Intel
-
Neil Henning, AMD
-
Short Description
Enables tighter array and struct packing to be used with uniform buffers.
Description
This extension modifies the alignment rules for uniform buffers, allowing for tighter packing of arrays and structures. This allows, for example, the std430 layout, as defined in GLSL to be supported in uniform buffers.
New Enum Constants
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_UNIFORM_BUFFER_STANDARD_LAYOUT_FEATURES_KHR
-
New Structures
Issues
None.
Version History
-
Revision 1, 2019-01-25 (Graeme Leese)
-
Initial draft
-
VK_KHR_vulkan_memory_model
- Name String
-
VK_KHR_vulkan_memory_model
- Extension Type
-
Device extension
- Registered Extension Number
-
212
- Revision
-
3
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Jeff Bolz jeffbolznv
-
- Last Modified Date
-
2018-12-10
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
This extension requires
SPV_KHR_vulkan_memory_model
-
- Contributors
-
-
Jeff Bolz, NVIDIA
-
Alan Baker, Google
-
Tobias Hector, AMD
-
David Neto, Google
-
Robert Simpson, Qualcomm Technologies, Inc.
-
Brian Sumner, AMD
-
The VK_KHR_vulkan_memory_model
extension allows use of the
Vulkan Memory Model, which formally defines how to
synchronize memory accesses to the same memory locations performed by
multiple shader invocations.
New Enum Constants
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VULKAN_MEMORY_MODEL_FEATURES_KHR
-
New Structures
Note
Version 3 of the spec added a member
( |
New SPIR-V Capabilities
Issues
Version History
-
Revision 1, 2018-06-24 (Jeff Bolz)
-
Initial draft
-
-
Revision 3, 2018-12-10 (Jeff Bolz)
-
Add vulkanMemoryModelAvailabilityVisibilityChains member to the VkPhysicalDeviceVulkanMemoryModelFeaturesKHR structure.
-
VK_KHR_wayland_surface
- Name String
-
VK_KHR_wayland_surface
- Extension Type
-
Instance extension
- Registered Extension Number
-
7
- Revision
-
6
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_KHR_surface
-
- Contact
-
-
Jesse Hall critsec
-
Ian Elliott ianelliottus
-
- Last Modified Date
-
2015-11-28
- IP Status
-
No known IP claims.
- Contributors
-
-
Patrick Doane, Blizzard
-
Jason Ekstrand, Intel
-
Ian Elliott, LunarG
-
Courtney Goeltzenleuchter, LunarG
-
Jesse Hall, Google
-
James Jones, NVIDIA
-
Antoine Labour, Google
-
Jon Leech, Khronos
-
David Mao, AMD
-
Norbert Nopper, Freescale
-
Alon Or-bach, Samsung
-
Daniel Rakos, AMD
-
Graham Sellers, AMD
-
Ray Smith, ARM
-
Jeff Vigil, Qualcomm
-
Chia-I Wu, LunarG
-
The VK_KHR_wayland_surface
extension is an instance extension.
It provides a mechanism to create a VkSurfaceKHR object (defined by
the VK_KHR_surface
extension) that refers to a Wayland
wl_surface
, as well as a query to determine support for rendering to a
Wayland compositor.
New Object Types
None
New Enum Constants
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_WAYLAND_SURFACE_CREATE_INFO_KHR
-
New Enums
None
New Structures
Issues
1) Does Wayland need a way to query for compatibility between a particular
physical device and a specific Wayland display? This would be a more general
query than vkGetPhysicalDeviceSurfaceSupportKHR: if the
Wayland-specific query returned VK_TRUE
for a (VkPhysicalDevice,
struct wl_display*
) pair, then the physical device could be assumed to
support presentation to any VkSurfaceKHR for surfaces on the display.
RESOLVED: Yes. vkGetPhysicalDeviceWaylandPresentationSupportKHR was added to address this issue.
2) Should we require surfaces created with vkCreateWaylandSurfaceKHR
to support the VK_PRESENT_MODE_MAILBOX_KHR
present mode?
RESOLVED: Yes.
Wayland is an inherently mailbox window system and mailbox support is
required for some Wayland compositor interactions to work as expected.
While handling these interactions may be possible with
VK_PRESENT_MODE_FIFO_KHR
, it is much more difficult to do without
deadlock and requiring all Wayland applications to be able to support
implementations which only support VK_PRESENT_MODE_FIFO_KHR
would be
an onerous restriction on application developers.
Version History
-
Revision 1, 2015-09-23 (Jesse Hall)
-
Initial draft, based on the previous contents of VK_EXT_KHR_swapchain (later renamed VK_EXT_KHR_surface).
-
-
Revision 2, 2015-10-02 (James Jones)
-
Added vkGetPhysicalDeviceWaylandPresentationSupportKHR() to resolve issue #1.
-
Adjusted wording of issue #1 to match the agreed-upon solution.
-
Renamed "window" parameters to "surface" to match Wayland conventions.
-
-
Revision 3, 2015-10-26 (Ian Elliott)
-
Renamed from VK_EXT_KHR_wayland_surface to VK_KHR_wayland_surface.
-
-
Revision 4, 2015-11-03 (Daniel Rakos)
-
Added allocation callbacks to vkCreateWaylandSurfaceKHR.
-
-
Revision 5, 2015-11-28 (Daniel Rakos)
-
Updated the surface create function to take a pCreateInfo structure.
-
-
Revision 6, 2017-02-08 (Jason Ekstrand)
-
Added the requirement that implementations support
VK_PRESENT_MODE_MAILBOX_KHR
. -
Added wording about interactions between vkQueuePresentKHR and the Wayland requests sent to the compositor.
-
VK_KHR_win32_keyed_mutex
- Name String
-
VK_KHR_win32_keyed_mutex
- Extension Type
-
Device extension
- Registered Extension Number
-
76
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_KHR_external_memory_win32
-
- Contact
-
-
Carsten Rohde crohde
-
- Last Modified Date
-
2016-10-21
- IP Status
-
No known IP claims.
- Contributors
-
-
James Jones, NVIDIA
-
Jeff Juliano, NVIDIA
-
Carsten Rohde, NVIDIA
-
Applications that wish to import Direct3D 11 memory objects into the Vulkan API may wish to use the native keyed mutex mechanism to synchronize access to the memory between Vulkan and Direct3D. This extension provides a way for an application to access the keyed mutex associated with an imported Vulkan memory object when submitting command buffers to a queue.
New Object Types
None.
New Enum Constants
-
VK_STRUCTURE_TYPE_WIN32_KEYED_MUTEX_ACQUIRE_RELEASE_INFO_KHR
New Enums
None.
New Structs
New Functions
None.
Issues
None.
Version History
-
Revision 1, 2016-10-21 (James Jones)
-
Initial revision
-
VK_KHR_win32_surface
- Name String
-
VK_KHR_win32_surface
- Extension Type
-
Instance extension
- Registered Extension Number
-
10
- Revision
-
6
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_KHR_surface
-
- Contact
-
-
Jesse Hall critsec
-
Ian Elliott ianelliottus
-
- Last Modified Date
-
2017-04-24
- IP Status
-
No known IP claims.
- Contributors
-
-
Patrick Doane, Blizzard
-
Jason Ekstrand, Intel
-
Ian Elliott, LunarG
-
Courtney Goeltzenleuchter, LunarG
-
Jesse Hall, Google
-
James Jones, NVIDIA
-
Antoine Labour, Google
-
Jon Leech, Khronos
-
David Mao, AMD
-
Norbert Nopper, Freescale
-
Alon Or-bach, Samsung
-
Daniel Rakos, AMD
-
Graham Sellers, AMD
-
Ray Smith, ARM
-
Jeff Vigil, Qualcomm
-
Chia-I Wu, LunarG
-
The VK_KHR_win32_surface
extension is an instance extension.
It provides a mechanism to create a VkSurfaceKHR object (defined by
the VK_KHR_surface
extension) that refers to a Win32 HWND
, as
well as a query to determine support for rendering to the windows desktop.
New Object Types
None
New Enum Constants
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_WIN32_SURFACE_CREATE_INFO_KHR
-
New Enums
None
New Structures
Issues
1) Does Win32 need a way to query for compatibility between a particular physical device and a specific screen? Compatibility between a physical device and a window generally only depends on what screen the window is on. However, there is not an obvious way to identify a screen without already having a window on the screen.
RESOLVED: No. While it may be useful, there is not a clear way to do this on Win32. However, a method was added to query support for presenting to the windows desktop as a whole.
2) If a native window object (HWND
) is used by one graphics API, and
then is later used by a different graphics API (one of which is Vulkan), can
these uses interfere with each other?
RESOLVED: Yes.
Uses of a window object by multiple graphics APIs results in undefined behavior. Such behavior may succeed when using one Vulkan implementation but fail when using a different Vulkan implementation. Potential failures include:
-
Creating then destroying a flip presentation model DXGI swapchain on a window object can prevent vkCreateSwapchainKHR from succeeding on the same window object.
-
Creating then destroying a VkSwapchainKHR on a window object can prevent creation of a bitblt model DXGI swapchain on the same window object.
-
Creating then destroying a VkSwapchainKHR on a window object can effectively
SetPixelFormat
to a different format than the format chosen by an OpenGL application. -
Creating then destroying a VkSwapchainKHR on a window object on one VkPhysicalDevice can prevent vkCreateSwapchainKHR from succeeding on the same window object, but on a different VkPhysicalDevice that is associated with a different Vulkan ICD.
In all cases the problem can be worked around by creating a new window object.
Technical details include:
-
Creating a DXGI swapchain over a window object can alter the object for the remainder of its lifetime. The alteration persists even after the DXGI swapchain has been destroyed. This alteration can make it impossible for a conformant Vulkan implementation to create a VkSwapchainKHR over the same window object. Mention of this alteration can be found in the remarks section of the MSDN documentation for
DXGI_SWAP_EFFECT
. -
Calling GDI’s
SetPixelFormat
(needed by OpenGL’s WGL layer) on a window object alters the object for the remainder of its lifetime. The MSDN documentation forSetPixelFormat
explains that a window object’s pixel format can be set only one time. -
Creating a VkSwapchainKHR over a window object can alter the object for the remaining life of its lifetime. Either of the above alterations may occur as a side-effect of VkSwapchainKHR.
Version History
-
Revision 1, 2015-09-23 (Jesse Hall)
-
Initial draft, based on the previous contents of VK_EXT_KHR_swapchain (later renamed VK_EXT_KHR_surface).
-
-
Revision 2, 2015-10-02 (James Jones)
-
Added presentation support query for win32 desktops.
-
-
Revision 3, 2015-10-26 (Ian Elliott)
-
Renamed from VK_EXT_KHR_win32_surface to VK_KHR_win32_surface.
-
-
Revision 4, 2015-11-03 (Daniel Rakos)
-
Added allocation callbacks to vkCreateWin32SurfaceKHR.
-
-
Revision 5, 2015-11-28 (Daniel Rakos)
-
Updated the surface create function to take a pCreateInfo structure.
-
-
Revision 6, 2017-04-24 (Jeff Juliano)
-
Add issue 2 addressing reuse of a native window object in a different Graphics API, or by a different Vulkan ICD.
-
VK_KHR_xcb_surface
- Name String
-
VK_KHR_xcb_surface
- Extension Type
-
Instance extension
- Registered Extension Number
-
6
- Revision
-
6
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_KHR_surface
-
- Contact
-
-
Jesse Hall critsec
-
Ian Elliott ianelliottus
-
- Last Modified Date
-
2015-11-28
- IP Status
-
No known IP claims.
- Contributors
-
-
Patrick Doane, Blizzard
-
Jason Ekstrand, Intel
-
Ian Elliott, LunarG
-
Courtney Goeltzenleuchter, LunarG
-
Jesse Hall, Google
-
James Jones, NVIDIA
-
Antoine Labour, Google
-
Jon Leech, Khronos
-
David Mao, AMD
-
Norbert Nopper, Freescale
-
Alon Or-bach, Samsung
-
Daniel Rakos, AMD
-
Graham Sellers, AMD
-
Ray Smith, ARM
-
Jeff Vigil, Qualcomm
-
Chia-I Wu, LunarG
-
The VK_KHR_xcb_surface
extension is an instance extension.
It provides a mechanism to create a VkSurfaceKHR object (defined by
the VK_KHR_surface
extension) that refers to an X11 Window
, using
the XCB client-side library, as well as a query to determine support for
rendering via XCB.
New Object Types
None
New Enum Constants
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_XCB_SURFACE_CREATE_INFO_KHR
-
New Enums
None
New Structures
Issues
1) Does XCB need a way to query for compatibility between a particular
physical device and a specific screen? This would be a more general query
than vkGetPhysicalDeviceSurfaceSupportKHR: If it returned
VK_TRUE
, then the physical device could be assumed to support
presentation to any window on that screen.
RESOLVED: Yes, this is needed for toolkits that want to create a VkDevice before creating a window. To ensure the query is reliable, it must be made against a particular X visual rather than the screen in general.
Version History
-
Revision 1, 2015-09-23 (Jesse Hall)
-
Initial draft, based on the previous contents of VK_EXT_KHR_swapchain (later renamed VK_EXT_KHR_surface).
-
-
Revision 2, 2015-10-02 (James Jones)
-
Added presentation support query for an (xcb_connection_t*, xcb_visualid_t) pair.
-
Removed "root" parameter from CreateXcbSurfaceKHR(), as it is redundant when a window on the same screen is specified as well.
-
Adjusted wording of issue #1 and added agreed upon resolution.
-
-
Revision 3, 2015-10-14 (Ian Elliott)
-
Removed "root" parameter from CreateXcbSurfaceKHR() in one more place.
-
-
Revision 4, 2015-10-26 (Ian Elliott)
-
Renamed from VK_EXT_KHR_xcb_surface to VK_KHR_xcb_surface.
-
-
Revision 5, 2015-10-23 (Daniel Rakos)
-
Added allocation callbacks to vkCreateXcbSurfaceKHR.
-
-
Revision 6, 2015-11-28 (Daniel Rakos)
-
Updated the surface create function to take a pCreateInfo structure.
-
VK_KHR_xlib_surface
- Name String
-
VK_KHR_xlib_surface
- Extension Type
-
Instance extension
- Registered Extension Number
-
5
- Revision
-
6
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_KHR_surface
-
- Contact
-
-
Jesse Hall critsec
-
Ian Elliott ianelliottus
-
- Last Modified Date
-
2015-11-28
- IP Status
-
No known IP claims.
- Contributors
-
-
Patrick Doane, Blizzard
-
Jason Ekstrand, Intel
-
Ian Elliott, LunarG
-
Courtney Goeltzenleuchter, LunarG
-
Jesse Hall, Google
-
James Jones, NVIDIA
-
Antoine Labour, Google
-
Jon Leech, Khronos
-
David Mao, AMD
-
Norbert Nopper, Freescale
-
Alon Or-bach, Samsung
-
Daniel Rakos, AMD
-
Graham Sellers, AMD
-
Ray Smith, ARM
-
Jeff Vigil, Qualcomm
-
Chia-I Wu, LunarG
-
The VK_KHR_xlib_surface
extension is an instance extension.
It provides a mechanism to create a VkSurfaceKHR object (defined by
the VK_KHR_surface
extension) that refers to an X11 Window
, using
the Xlib client-side library, as well as a query to determine support for
rendering via Xlib.
New Object Types
None
New Enum Constants
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_XLIB_SURFACE_CREATE_INFO_KHR
-
New Enums
None
New Structures
Issues
1) Does X11 need a way to query for compatibility between a particular
physical device and a specific screen? This would be a more general query
than vkGetPhysicalDeviceSurfaceSupportKHR; if it returned
VK_TRUE
, then the physical device could be assumed to support
presentation to any window on that screen.
RESOLVED: Yes, this is needed for toolkits that want to create a VkDevice before creating a window. To ensure the query is reliable, it must be made against a particular X visual rather than the screen in general.
Version History
-
Revision 1, 2015-09-23 (Jesse Hall)
-
Initial draft, based on the previous contents of VK_EXT_KHR_swapchain (later renamed VK_EXT_KHR_surface).
-
-
Revision 2, 2015-10-02 (James Jones)
-
Added presentation support query for (Display*, VisualID) pair.
-
Removed "root" parameter from CreateXlibSurfaceKHR(), as it is redundant when a window on the same screen is specified as well.
-
Added appropriate X errors.
-
Adjusted wording of issue #1 and added agreed upon resolution.
-
-
Revision 3, 2015-10-14 (Ian Elliott)
-
Renamed this extension from VK_EXT_KHR_x11_surface to VK_EXT_KHR_xlib_surface.
-
-
Revision 4, 2015-10-26 (Ian Elliott)
-
Renamed from VK_EXT_KHR_xlib_surface to VK_KHR_xlib_surface.
-
-
Revision 5, 2015-11-03 (Daniel Rakos)
-
Added allocation callbacks to vkCreateXlibSurfaceKHR.
-
-
Revision 6, 2015-11-28 (Daniel Rakos)
-
Updated the surface create function to take a pCreateInfo structure.
-
VK_EXT_acquire_xlib_display
- Name String
-
VK_EXT_acquire_xlib_display
- Extension Type
-
Instance extension
- Registered Extension Number
-
90
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_EXT_direct_mode_display
-
- Contact
-
-
James Jones cubanismo
-
- Last Modified Date
-
2016-12-13
- IP Status
-
No known IP claims.
- Contributors
-
-
Dave Airlie, Red Hat
-
Pierre Boudier, NVIDIA
-
James Jones, NVIDIA
-
Damien Leone, NVIDIA
-
Pierre-Loup Griffais, Valve
-
Liam Middlebrook, NVIDIA
-
Daniel Vetter, Intel
-
This extension allows an application to take exclusive control on a display currently associated with an X11 screen. When control is acquired, the display will be deassociated from the X11 screen until control is released or the specified display connection is closed. Essentially, the X11 screen will behave as if the monitor has been unplugged until control is released.
New Enum Constants
None.
New Enums
None.
New Structures
None.
New Functions
Issues
1) Should vkAcquireXlibDisplayEXT take an RandR display ID, or a Vulkan display handle as input?
RESOLVED: A Vulkan display handle. Otherwise there would be no way to specify handles to displays that had been “blacklisted” or prevented from being included in the X11 display list by some native platform or vendor-specific mechanism.
2) How does an application figure out which RandR display corresponds to a Vulkan display?
RESOLVED: A new function, vkGetRandROutputDisplayEXT, is introduced for this purpose.
3) Should vkGetRandROutputDisplayEXT be part of this extension, or a general Vulkan / RandR or Vulkan / Xlib extension?
RESOLVED: To avoid yet another extension, include it in this extension.
Version History
-
Revision 1, 2016-12-13 (James Jones)
-
Initial draft
-
VK_EXT_astc_decode_mode
- Name String
-
VK_EXT_astc_decode_mode
- Extension Type
-
Device extension
- Registered Extension Number
-
68
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Jan-Harald Fredriksen janharaldfredriksen-arm
-
- Last Modified Date
-
2018-08-07
- Contributors
-
-
Jan-Harald Fredriksen, Arm
-
The existing specification requires that low dynamic range (LDR) ASTC textures are decompressed to FP16 values per component. In many cases, decompressing LDR textures to a lower precision intermediate result gives acceptable image quality. Source material for LDR textures is typically authored as 8-bit UNORM values, so decoding to FP16 values adds little value. On the other hand, reducing precision of the decoded result reduces the size of the decompressed data, potentially improving texture cache performance and saving power.
The goal of this extension is to enable this efficiency gain on existing ASTC texture data. This is achieved by giving the application the ability to select the intermediate decoding precision.
Three decoding options are provided:
-
Decode to
VK_FORMAT_R16G16B16A16_SFLOAT
precision: This is the default, and matches the required behavior in the core API. -
Decode to
VK_FORMAT_R8G8B8A8_UNORM
precision: This is provided as an option in LDR mode. -
Decode to
VK_FORMAT_E5B9G9R9_UFLOAT_PACK32
precision: This is provided as an option in both LDR and HDR mode. In this mode, negative values cannot be represented and are clamped to zero. The alpha component is ignored, and the results are as if alpha was 1.0. This decode mode is optional and support can be queried via the physical device properties.
New Enum Constants
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_IMAGE_VIEW_ASTC_DECODE_MODE_EXT
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_ASTC_DECODE_FEATURES_EXT
-
New Enums
None.
New Functions
None.
Issues
1) Are implementations allowed to decode at a higher precision than what is requested?
RESOLUTION: No. If we allow this, then this extension could be exposed on all implementations that support ASTC. But developers would have no way of knowing what precision was actually used, and thus whether the image quality is sufficient at reduced precision.
2) Should the decode mode be image view state and/or sampler state?
RESOLUTION: Image view state only. Some implementations treat the different decode modes as different texture formats.
Example
Create an image view that decodes to VK_FORMAT_R8G8B8A8_UNORM
precision:
VkImageViewASTCDecodeModeEXT decodeMode =
{
VK_STRUCTURE_TYPE_IMAGE_VIEW_ASTC_DECODE_MODE_EXT, // sType
NULL, // pNext
VK_FORMAT_R8G8B8A8_UNORM // decode mode
};
VkImageViewCreateInfo createInfo =
{
VK_STRUCTURE_TYPE_IMAGE_VIEW_CREATE_INFO, // sType
&decodeMode, // pNext
// flags, image, viewType set to application-desired values
VK_FORMAT_ASTC_8x8_UNORM_BLOCK, // format
// components, subresourceRange set to application-desired values
};
VkImageView imageView;
VkResult result = vkCreateImageView(
device,
&createInfo,
NULL,
&imageView);
Version History
-
Revision 1, 2018-08-07 (Jan-Harald Fredriksen)
-
Initial revision
-
VK_EXT_blend_operation_advanced
- Name String
-
VK_EXT_blend_operation_advanced
- Extension Type
-
Device extension
- Registered Extension Number
-
149
- Revision
-
2
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Jeff Bolz jeffbolznv
-
- Last Modified Date
-
2017-06-12
- Contributors
-
-
Jeff Bolz, NVIDIA
-
This extension adds a number of “advanced” blending operations that can be used to perform new color blending operations, many of which are more complex than the standard blend modes provided by unextended Vulkan. This extension requires different styles of usage, depending on the level of hardware support and the enabled features:
-
If VkPhysicalDeviceBlendOperationAdvancedFeaturesEXT::
advancedBlendCoherentOperations
isVK_FALSE
, the new blending operations are supported, but a memory dependency must separate each advanced blend operation on a given sample.VK_ACCESS_COLOR_ATTACHMENT_READ_NONCOHERENT_BIT_EXT
is used to synchronize reads using advanced blend operations. -
If VkPhysicalDeviceBlendOperationAdvancedFeaturesEXT::
advancedBlendCoherentOperations
isVK_TRUE
, advanced blend operations obey primitive order just like basic blend operations.
In unextended Vulkan, the set of blending operations is limited, and can be
expressed very simply.
The VK_BLEND_OP_MIN
and VK_BLEND_OP_MAX
blend operations simply
compute component-wise minimums or maximums of source and destination color
components.
The VK_BLEND_OP_ADD
, VK_BLEND_OP_SUBTRACT
, and
VK_BLEND_OP_REVERSE_SUBTRACT
modes multiply the source and destination
colors by source and destination factors and either add the two products
together or subtract one from the other.
This limited set of operations supports many common blending operations but
precludes the use of more sophisticated transparency and blending operations
commonly available in many dedicated imaging APIs.
This extension provides a number of new “advanced” blending operations.
Unlike traditional blending operations using VK_BLEND_OP_ADD
, these
blending equations do not use source and destination factors specified by
VkBlendFactor.
Instead, each blend operation specifies a complete equation based on the
source and destination colors.
These new blend operations are used for both RGB and alpha components; they
must not be used to perform separate RGB and alpha blending (via different
values of color and alpha VkBlendOp).
These blending operations are performed using premultiplied colors, where
RGB colors can be considered premultiplied or non-premultiplied by alpha,
according to the srcPremultiplied
and dstPremultiplied
members
of VkPipelineColorBlendAdvancedStateCreateInfoEXT.
If a color is considered non-premultiplied, the (R,G,B) color components are
multiplied by the alpha component prior to blending.
For non-premultiplied color components in the range [0,1], the
corresponding premultiplied color component would have values in the range
[0 × A, 1 × A].
Many of these advanced blending equations are formulated where the result of
blending source and destination colors with partial coverage have three
separate contributions: from the portions covered by both the source and the
destination, from the portion covered only by the source, and from the
portion covered only by the destination.
The blend parameter
VkPipelineColorBlendAdvancedStateCreateInfoEXT::blendOverlap
can be used to specify a correlation between source and destination pixel
coverage.
If set to VK_BLEND_OVERLAP_CONJOINT_EXT
, the source and destination
are considered to have maximal overlap, as would be the case if drawing two
objects on top of each other.
If set to VK_BLEND_OVERLAP_DISJOINT_EXT
, the source and destination
are considered to have minimal overlap, as would be the case when rendering
a complex polygon tessellated into individual non-intersecting triangles.
If set to VK_BLEND_OVERLAP_UNCORRELATED_EXT
, the source and
destination coverage are assumed to have no spatial correlation within the
pixel.
In addition to the coherency issues on implementations not supporting
advancedBlendCoherentOperations
, this extension has several
limitations worth noting.
First, the new blend operations have a limit on the number of color
attachments they can be used with, as indicated by
VkPhysicalDeviceBlendOperationAdvancedPropertiesEXT::advancedBlendMaxColorAttachments
.
Additionally, blending precision may be limited to 16-bit floating-point,
which may result in a loss of precision and dynamic range for framebuffer
formats with 32-bit floating-point components, and in a loss of precision
for formats with 12- and 16-bit signed or unsigned normalized integer
components.
New Object Types
None.
New Enum Constants
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_BLEND_OPERATION_ADVANCED_FEATURES_EXT
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_BLEND_OPERATION_ADVANCED_PROPERTIES_EXT
-
VK_STRUCTURE_TYPE_PIPELINE_COLOR_BLEND_ADVANCED_STATE_CREATE_INFO_EXT
-
-
Extending VkAccessFlagBits:
-
VK_ACCESS_COLOR_ATTACHMENT_READ_NONCOHERENT_BIT_EXT
-
-
Extending VkBlendOp:
-
VK_BLEND_OP_ZERO_EXT
-
VK_BLEND_OP_SRC_EXT
-
VK_BLEND_OP_DST_EXT
-
VK_BLEND_OP_SRC_OVER_EXT
-
VK_BLEND_OP_DST_OVER_EXT
-
VK_BLEND_OP_SRC_IN_EXT
-
VK_BLEND_OP_DST_IN_EXT
-
VK_BLEND_OP_SRC_OUT_EXT
-
VK_BLEND_OP_DST_OUT_EXT
-
VK_BLEND_OP_SRC_ATOP_EXT
-
VK_BLEND_OP_DST_ATOP_EXT
-
VK_BLEND_OP_XOR_EXT
-
VK_BLEND_OP_MULTIPLY_EXT
-
VK_BLEND_OP_SCREEN_EXT
-
VK_BLEND_OP_OVERLAY_EXT
-
VK_BLEND_OP_DARKEN_EXT
-
VK_BLEND_OP_LIGHTEN_EXT
-
VK_BLEND_OP_COLORDODGE_EXT
-
VK_BLEND_OP_COLORBURN_EXT
-
VK_BLEND_OP_HARDLIGHT_EXT
-
VK_BLEND_OP_SOFTLIGHT_EXT
-
VK_BLEND_OP_DIFFERENCE_EXT
-
VK_BLEND_OP_EXCLUSION_EXT
-
VK_BLEND_OP_INVERT_EXT
-
VK_BLEND_OP_INVERT_RGB_EXT
-
VK_BLEND_OP_LINEARDODGE_EXT
-
VK_BLEND_OP_LINEARBURN_EXT
-
VK_BLEND_OP_VIVIDLIGHT_EXT
-
VK_BLEND_OP_LINEARLIGHT_EXT
-
VK_BLEND_OP_PINLIGHT_EXT
-
VK_BLEND_OP_HARDMIX_EXT
-
VK_BLEND_OP_HSL_HUE_EXT
-
VK_BLEND_OP_HSL_SATURATION_EXT
-
VK_BLEND_OP_HSL_COLOR_EXT
-
VK_BLEND_OP_HSL_LUMINOSITY_EXT
-
VK_BLEND_OP_PLUS_EXT
-
VK_BLEND_OP_PLUS_CLAMPED_EXT
-
VK_BLEND_OP_PLUS_CLAMPED_ALPHA_EXT
-
VK_BLEND_OP_PLUS_DARKER_EXT
-
VK_BLEND_OP_MINUS_EXT
-
VK_BLEND_OP_MINUS_CLAMPED_EXT
-
VK_BLEND_OP_CONTRAST_EXT
-
VK_BLEND_OP_INVERT_OVG_EXT
-
VK_BLEND_OP_RED_EXT
-
VK_BLEND_OP_GREEN_EXT
-
VK_BLEND_OP_BLUE_EXT
-
New Enums
New Structures
New Functions
None.
Issues
None.
Version History
-
Revision 1, 2017-06-12 (Jeff Bolz)
-
Internal revisions
-
-
Revision 2, 2017-06-12 (Jeff Bolz)
-
Internal revisions
-
VK_EXT_calibrated_timestamps
- Name String
-
VK_EXT_calibrated_timestamps
- Extension Type
-
Device extension
- Registered Extension Number
-
185
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Daniel Rakos drakos-amd
-
- Last Modified Date
-
2018-10-04
- IP Status
-
No known IP claims.
- Contributors
-
-
Matthaeus G. Chajdas, AMD
-
Alan Harrison, AMD
-
Derrick Owens, AMD
-
Daniel Rakos, AMD
-
Jason Ekstrand, Intel
-
Keith Packard, Valve
-
This extension provides an interface to query calibrated timestamps obtained quasi simultaneously from two time domains.
New Object Types
None.
New Enum Constants
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_CALIBRATED_TIMESTAMP_INFO_EXT
-
New Enums
New Structures
Issues
1) Is the device timestamp value returned in the same time domain as the timestamp values written by vkCmdWriteTimestamp?
RESOLVED: Yes.
2) What time domain is the host timestamp returned in?
RESOLVED: A query is provided to determine the calibrateable time domains. The expected host time domain used on Windows is that of QueryPerformanceCounter, and on Linux that of CLOCK_MONOTONIC.
3) Should we support other time domain combinations than just one host and the device time domain?
RESOLVED: Supporting that would need the application to query the set of supported time domains, while supporting only one host and the device time domain would only need a query for the host time domain type. The proposed API chooses the general approach for the sake of extensibility.
4) Shouldn’t we use CLOCK_MONOTONIC_RAW instead of CLOCK_MONOTONIC?
RESOLVED: CLOCK_MONOTONIC is usable in a wider set of situations, however, it is subject to NTP adjustments so some use cases may prefer CLOCK_MONOTONIC_RAW. Thus this extension allows both to be exposed.
5) How can the application extrapolate future device timestamp values from the calibrated timestamp value?
RESOLVED: VkPhysicalDeviceLimits::timestampPeriod
makes it
possible to calculate future device timestamps as follows:
futureTimestamp = calibratedTimestamp + deltaNanoseconds / timestampPeriod
6) Can the host and device timestamp values drift apart over longer periods of time?
RESOLVED: Yes, especially as some time domains by definition allow for that to happen (e.g. CLOCK_MONOTONIC is subject to NTP adjustments). Thus it’s recommended that applications re-calibrate from time to time.
7) Should we add a query for reporting the maximum deviation of the timestamp values returned by calibrated timestamp queries?
RESOLVED: A global query seems inappropriate and difficult to enforce. However, it’s possible to return the maximum deviation any single calibrated timestamp query can have by sampling one of the time domains twice as follows:
timestampX = timestampX_before = SampleTimeDomain(X)
for each time domain Y != X
timestampY = SampleTimeDomain(Y)
timestampX_after = SampleTimeDomain(X)
maxDeviation = timestampX_after - timestampX_before
8) Can the maximum deviation reported ever be zero?
RESOLVED: Unless the tick of each clock corresponding to the set of time domains coincides and all clocks can literally be sampled simutaneously, there isn’t really a possibility for the maximum deviation to be zero, so by convention the maximum deviation is always at least the maximum of the length of the ticks of the set of time domains calibrated and thus can never be zero.
Version History
-
Revision 1, 2018-10-04 (Daniel Rakos)
-
Internal revisions.
-
VK_EXT_conditional_rendering
- Name String
-
VK_EXT_conditional_rendering
- Extension Type
-
Device extension
- Registered Extension Number
-
82
- Revision
-
2
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Vikram Kushwaha vkushwaha
-
- Last Modified Date
-
2018-05-21
- IP Status
-
No known IP claims.
- Contributors
-
-
Vikram Kushwaha, NVIDIA
-
Daniel Rakos, AMD
-
Jesse Hall, Google
-
Jeff Bolz, NVIDIA
-
Piers Daniell, NVIDIA
-
Stuart Smith, Imagination Technologies
-
This extension allows the execution of one or more rendering commands to be conditional on a value in buffer memory. This may help an application reduce the latency by conditionally discarding rendering commands without application intervention. The conditional rendering commands are limited to draws, compute dispatches and clearing attachments within a conditional rendering block.
New Object Types
None.
New Enum Constants
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_COMMAND_BUFFER_INHERITANCE_CONDITIONAL_RENDERING_INFO_EXT
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_CONDITIONAL_RENDERING_FEATURES_EXT
-
VK_STRUCTURE_TYPE_CONDITIONAL_RENDERING_BEGIN_INFO_EXT
-
-
Extending VkAccessFlagBits:
-
VK_ACCESS_CONDITIONAL_RENDERING_READ_BIT_EXT
-
-
Extending VkBufferUsageFlagBits:
-
VK_BUFFER_USAGE_CONDITIONAL_RENDERING_BIT_EXT
-
-
Extending VkPipelineStageFlagBits:
-
VK_PIPELINE_STAGE_CONDITIONAL_RENDERING_BIT_EXT
-
New Enums
Issues
1) Should conditional rendering affect copy and blit commands?
RESOLVED: Conditional rendering should not affect copies and blits.
2) Should secondary command buffers be allowed to execute while conditional rendering is active in the primary command buffer?
RESOLVED: The rendering commands in secondary command buffer will be
affected by an active conditional rendering in primary command buffer if the
conditionalRenderingEnable
is set to VK_TRUE
.
Conditional rendering must not be active in the primary command buffer if
conditionalRenderingEnable
is VK_FALSE
.
Examples
None.
Version History
-
Revision 1, 2018-04-19 (Vikram Kushwaha)
-
First Version
-
-
Revision 2, 2018-05-21 (Vikram Kushwaha)
-
Add new pipeline stage, access flags and limit conditional rendering to a subpass or entire renderpass.
-
VK_EXT_conservative_rasterization
- Name String
-
VK_EXT_conservative_rasterization
- Extension Type
-
Device extension
- Registered Extension Number
-
102
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Piers Daniell pdaniell-nv
-
- Last Modified Data
-
2017-08-28
- Contributors
-
-
Daniel Koch, NVIDIA
-
Daniel Rakos, AMD
-
Jeff Bolz, NVIDIA
-
Slawomir Grajewski, Intel
-
Stu Smith, Imagination Technologies
-
This extension adds a new rasterization mode called conservative rasterization. There are two modes of conservative rasterization; overestimation and underestimation.
When overestimation is enabled, if any part of the primitive, including its edges, covers any part of the rectangular pixel area, including its sides, then a fragment is generated with all coverage samples turned on. This extension allows for some variation in implementations by accounting for differences in overestimation, where the generating primitive size is increased at each of its edges by some sub-pixel amount to further increase conservative pixel coverage. Implementations can allow the application to specify an extra overestimation beyond the base overestimation the implementation already does. It also allows implementations to either cull degenerate primitives or rasterize them.
When underestimation is enabled, fragments are only generated if the rectangular pixel area is fully covered by the generating primitive. If supported by the implementation, when a pixel rectangle is fully covered the fragment shader input variable builtin called FullyCoveredEXT is set to true. The shader variable works in either overestimation or underestimation mode.
Implementations can process degenerate triangles and lines by either discarding them or generating conservative fragments for them. Degenerate triangles are those that end up with zero area after the rasterizer quantizes them to the fixed-point pixel grid. Degenerate lines are those with zero length after quantization.
New Object Types
None.
New Enum Constants
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_CONSERVATIVE_RASTERIZATION_PROPERTIES_EXT
-
VK_STRUCTURE_TYPE_PIPELINE_RASTERIZATION_CONSERVATIVE_STATE_CREATE_INFO_EXT
-
New Structures
New Functions
None.
Issues
None.
Version History
-
Revision 1, 2017-08-28 (Piers Daniell)
-
Internal revisions
-
VK_EXT_debug_utils
- Name String
-
VK_EXT_debug_utils
- Extension Type
-
Instance extension
- Registered Extension Number
-
129
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Mark Young marky-lunarg
-
- Last Modified Date
-
2017-09-14
- Revision
-
1
- IP Status
-
No known IP claims.
- Dependencies
-
-
This extension is written against version 1.0 of the Vulkan API.
-
Requires VkObjectType
-
- Contributors
-
-
Mark Young, LunarG
-
Baldur Karlsson
-
Ian Elliott, Google
-
Courtney Goeltzenleuchter, Google
-
Karl Schultz, LunarG
-
Mark Lobodzinski, LunarG
-
Mike Schuchardt, LunarG
-
Jaakko Konttinen, AMD
-
Dan Ginsburg, Valve Software
-
Rolando Olivares, Epic Games
-
Dan Baker, Oxide Games
-
Kyle Spagnoli, NVIDIA
-
Jon Ashburn, LunarG
-
Due to the nature of the Vulkan interface, there is very little error
information available to the developer and application.
By using the VK_EXT_debug_utils
extension, developers can obtain more
information.
When combined with validation layers, even more detailed feedback on the
application’s use of Vulkan will be provided.
This extension provides the following capabilities:
-
The ability to create a debug messenger which will pass along debug messages to an application supplied callback.
-
The ability to identify specific Vulkan objects using a name or tag to improve tracking.
-
The ability to identify specific sections within a
VkQueue
orVkCommandBuffer
using labels to aid organization and offline analysis in external tools.
The main difference between this extension and VK_EXT_debug_report
and
VK_EXT_debug_marker
is that those extensions use
VkDebugReportObjectTypeEXT to identify objects.
This extension uses the core VkObjectType in place of
VkDebugReportObjectTypeEXT.
The primary reason for this move is that no future object type handle
enumeration values will be added to VkDebugReportObjectTypeEXT since
the creation of VkObjectType.
In addition, this extension combines the functionality of both
VK_EXT_debug_report
and VK_EXT_debug_marker
by allowing object
name and debug markers (now called labels) to be returned to the
application’s callback function.
This should assist in clarifying the details of a debug message including:
what objects are involved and potentially which location within a
VkQueue or VkCommandBuffer the message occurred.
New Object Types
New Enum Constants
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_DEBUG_UTILS_OBJECT_NAME_INFO_EXT
-
VK_STRUCTURE_TYPE_DEBUG_UTILS_OBJECT_TAG_INFO_EXT
-
VK_STRUCTURE_TYPE_DEBUG_UTILS_LABEL_EXT
-
VK_STRUCTURE_TYPE_DEBUG_UTILS_MESSENGER_CALLBACK_DATA_EXT
-
VK_STRUCTURE_TYPE_DEBUG_UTILS_MESSENGER_CREATE_INFO_EXT
-
-
Extending VkResult:
-
VK_ERROR_VALIDATION_FAILED_EXT
-
New Structures
New Functions
New Function Pointers
Examples
Example 1
VK_EXT_debug_utils
allows an application to register multiple callbacks
with any Vulkan component wishing to report debug information.
Some callbacks may log the information to a file, others may cause a debug
break point or other application defined behavior.
An application can register callbacks even when no validation layers are
enabled, but they will only be called for loader and, if implemented, driver
events.
To capture events that occur while creating or destroying an instance an
application can link a VkDebugUtilsMessengerCreateInfoEXT structure
to the pNext
element of the VkInstanceCreateInfo structure given
to vkCreateInstance.
This callback is only valid for the duration of the vkCreateInstance
and the vkDestroyInstance call.
Use vkCreateDebugUtilsMessengerEXT to create persistent callback
objects.
Example uses: Create three callback objects.
One will log errors and warnings to the debug console using Windows
OutputDebugString
.
The second will cause the debugger to break at that callback when an error
happens and the third will log warnings to stdout.
extern VkInstance instance;
VkResult res;
VkDebugUtilsMessengerEXT cb1, cb2, cb3;
// Must call extension functions through a function pointer:
PFN_vkCreateDebugUtilsMessengerEXT pfnCreateDebugUtilsMessengerEXT = (PFN_vkCreateDebugUtilsMessengerEXT)vkGetDeviceProcAddr(device, "vkCreateDebugUtilsMessengerEXT");
PFN_vkDestroyDebugUtilsMessengerEXT pfnDestroyDebugUtilsMessengerEXT = (PFN_vkDestroyDebugUtilsMessengerEXT)vkGetDeviceProcAddr(device, "vkDestroyDebugUtilsMessengerEXT");
VkDebugUtilsMessengeCreateInfoEXT callback1 = {
VK_STRUCTURE_TYPE_DEBUG_UTILS_MESSENGER_CREATE_INFO_EXT, // sType
NULL, // pNext
0, // flags
VK_DEBUG_UTILS_MESSAGE_SEVERITY_ERROR_BIT_EXT | // messageSeverity
VK_DEBUG_UTILS_MESSAGE_SEVERITY_WARNING_BIT_EXT,
VK_DEBUG_UTILS_MESSAGE_TYPE_GENERAL_BIT_EXT | // messageType
VK_DEBUG_UTILS_MESSAGE_TYPE_VALIDATION_BIT_EXT,
myOutputDebugString, // pfnUserCallback
NULL // pUserData
};
res = pfnCreateDebugUtilsMessengerEXT(instance, &callback1, NULL, &cb1);
if (res != VK_SUCCESS) {
// Do error handling for VK_ERROR_OUT_OF_MEMORY
}
callback1.messageSeverity = VK_DEBUG_UTILS_MESSAGE_SEVERITY_ERROR_BIT_EXT;
callback1.pfnCallback = myDebugBreak;
callback1.pUserData = NULL;
res = pfnCreateDebugUtilsMessengerEXT(instance, &callback1, NULL, &cb2);
if (res != VK_SUCCESS) {
// Do error handling for VK_ERROR_OUT_OF_MEMORY
}
VkDebugUtilsMessengerCreateInfoEXT callback3 = {
VK_STRUCTURE_TYPE_DEBUG_UTILS_MESSENGER_CREATE_INFO_EXT, // sType
NULL, // pNext
0, // flags
VK_DEBUG_UTILS_MESSAGE_SEVERITY_WARNING_BIT_EXT, // messageSeverity
VK_DEBUG_UTILS_MESSAGE_TYPE_GENERAL_BIT_EXT | // messageType
VK_DEBUG_UTILS_MESSAGE_TYPE_VALIDATION_BIT_EXT,
mystdOutLogger, // pfnUserCallback
NULL // pUserData
};
res = pfnCreateDebugUtilsMessengerEXT(instance, &callback3, NULL, &cb3);
if (res != VK_SUCCESS) {
// Do error handling for VK_ERROR_OUT_OF_MEMORY
}
...
// Remove callbacks when cleaning up
pfnDestroyDebugUtilsMessengerEXT(instance, cb1, NULL);
pfnDestroyDebugUtilsMessengerEXT(instance, cb2, NULL);
pfnDestroyDebugUtilsMessengerEXT(instance, cb3, NULL);
Example 2
Associate a name with an image, for easier debugging in external tools or with validation layers that can print a friendly name when referring to objects in error messages.
extern VkDevice device;
extern VkImage image;
// Must call extension functions through a function pointer:
PFN_vkSetDebugUtilsObjectNameEXT pfnSetDebugUtilsObjectNameEXT = (PFN_vkSetDebugUtilsObjectNameEXT)vkGetDeviceProcAddr(device, "vkSetDebugUtilsObjectNameEXT");
// Set a name on the image
const VkDebugUtilsObjectNameInfoEXT imageNameInfo =
{
VK_STRUCTURE_TYPE_DEBUG_UTILS_OBJECT_NAME_INFO_EXT, // sType
NULL, // pNext
VK_OBJECT_TYPE_IMAGE, // objectType
(uint64_t)image, // object
"Brick Diffuse Texture", // pObjectName
};
pfnSetDebugUtilsObjectNameEXT(device, &imageNameInfo);
// A subsequent error might print:
// Image 'Brick Diffuse Texture' (0xc0dec0dedeadbeef) is used in a
// command buffer with no memory bound to it.
Example 3
Annotating regions of a workload with naming information so that offline analysis tools can display a more usable visualization of the commands submitted.
extern VkDevice device;
extern VkCommandBuffer commandBuffer;
// Must call extension functions through a function pointer:
PFN_vkQueueBeginDebugUtilsLabelEXT pfnQueueBeginDebugUtilsLabelEXT = (PFN_vkQueueBeginDebugUtilsLabelEXT)vkGetDeviceProcAddr(device, "vkQueueBeginDebugUtilsLabelEXT");
PFN_vkQueueEndDebugUtilsLabelEXT pfnQueueEndDebugUtilsLabelEXT = (PFN_vkQueueEndDebugUtilsLabelEXT)vkGetDeviceProcAddr(device, "vkQueueEndDebugUtilsLabelEXT");
PFN_vkCmdBeginDebugUtilsLabelEXT pfnCmdBeginDebugUtilsLabelEXT = (PFN_vkCmdBeginDebugUtilsLabelEXT)vkGetDeviceProcAddr(device, "vkCmdBeginDebugUtilsLabelEXT");
PFN_vkCmdEndDebugUtilsLabelEXT pfnCmdEndDebugUtilsLabelEXT = (PFN_vkCmdEndDebugUtilsLabelEXT)vkGetDeviceProcAddr(device, "vkCmdEndDebugUtilsLabelEXT");
PFN_vkCmdInsertDebugUtilsLabelEXT pfnCmdInsertDebugUtilsLabelEXT = (PFN_vkCmdInsertDebugUtilsLabelEXT)vkGetDeviceProcAddr(device, "vkCmdInsertDebugUtilsLabelEXT");
// Describe the area being rendered
const VkDebugUtilsLabelEXT houseLabel =
{
VK_STRUCTURE_TYPE_DEBUG_UTILS_LABEL_EXT, // sType
NULL, // pNext
"Brick House", // pLabelName
{ 1.0f, 0.0f, 0.0f, 1.0f }, // color
};
// Start an annotated group of calls under the 'Brick House' name
pfnCmdBeginDebugUtilsLabelEXT(commandBuffer, &houseLabel);
{
// A mutable structure for each part being rendered
VkDebugUtilsLabelEXT housePartLabel =
{
VK_STRUCTURE_TYPE_DEBUG_UTILS_LABEL_EXT, // sType
NULL, // pNext
NULL, // pLabelName
{ 0.0f, 0.0f, 0.0f, 0.0f }, // color
};
// Set the name and insert the marker
housePartLabel.pLabelName = "Walls";
pfnCmdInsertDebugUtilsLabelEXT(commandBuffer, &housePartLabel);
// Insert the drawcall for the walls
vkCmdDrawIndexed(commandBuffer, 1000, 1, 0, 0, 0);
// Insert a recursive region for two sets of windows
housePartLabel.pLabelName = "Windows";
pfnCmdBeginDebugUtilsLabelEXT(commandBuffer, &housePartLabel);
{
vkCmdDrawIndexed(commandBuffer, 75, 6, 1000, 0, 0);
vkCmdDrawIndexed(commandBuffer, 100, 2, 1450, 0, 0);
}
pfnCmdEndDebugUtilsLabelEXT(commandBuffer);
housePartLabel.pLabelName = "Front Door";
pfnCmdInsertDebugUtilsLabelEXT(commandBuffer, &housePartLabel);
vkCmdDrawIndexed(commandBuffer, 350, 1, 1650, 0, 0);
housePartLabel.pLabelName = "Roof";
pfnCmdInsertDebugUtilsLabelEXT(commandBuffer, &housePartLabel);
vkCmdDrawIndexed(commandBuffer, 500, 1, 2000, 0, 0);
}
// End the house annotation started above
pfnCmdEndDebugUtilsLabelEXT(commandBuffer);
// Do other work
vkEndCommandBuffer(commandBuffer);
// Describe the queue being used
const VkDebugUtilsLabelEXT queueLabel =
{
VK_STRUCTURE_TYPE_DEBUG_UTILS_LABEL_EXT, // sType
NULL, // pNext
"Main Render Work", // pLabelName
{ 0.0f, 1.0f, 0.0f, 1.0f }, // color
};
// Identify the queue label region
pfnQueueBeginDebugUtilsLabelEXT(queue, &queueLabel);
// Submit the work for the main render thread
const VkCommandBuffer cmd_bufs[] = {commandBuffer};
VkSubmitInfo submit_info = {.sType = VK_STRUCTURE_TYPE_SUBMIT_INFO,
.pNext = NULL,
.waitSemaphoreCount = 0,
.pWaitSemaphores = NULL,
.pWaitDstStageMask = NULL,
.commandBufferCount = 1,
.pCommandBuffers = cmd_bufs,
.signalSemaphoreCount = 0,
.pSignalSemaphores = NULL};
vkQueueSubmit(queue, 1, &submit_info, fence);
// End the queue label region
pfnQueueEndDebugUtilsLabelEXT(queue);
Issues
1) Should we just name this extension VK_EXT_debug_report2
RESOLVED: No. There is enough additional changes to the structures to break backwards compatibility. So, a new name was decided that would not indicate any interaction with the previous extension.
2) Will validation layers immediately support all the new features.
RESOLVED: Not immediately.
As one can imagine, there is a lot of work involved with converting the
validation layer logging over to the new functionality.
Basic logging, as seen in the origin VK_EXT_debug_report
extension
will be made available immediately.
However, adding the labels and object names will take time.
Since the priority for Khronos at this time is to continue focusing on Valid
Usage statements, it may take a while before the new functionality is fully
exposed.
3) If the validation layers won’t expose the new functionality immediately, then what’s the point of this extension?
RESOLVED: We needed a replacement for VK_EXT_debug_report
because
the VkDebugReportObjectTypeEXT enumeration will no longer be updated
and any new objects will need to be debugged using the new functionality
provided by this extension.
4) Should this extension be split into two separate parts (1 extension that is an instance extension providing the callback functionality, and another device extension providing the general debug marker and annotation functionality)?
RESOLVED: No, the functionality for this extension is too closely related. If we did split up the extension, where would the structures and enums live, and how would you define that the device behavior in the instance extension is really only valid if the device extension is enabled, and the functionality is passed in. It’s cleaner to just define this all as an instance extension, plus it allows the application to enable all debug functionality provided with one enable string during vkCreateInstance.
Version History
-
Revision 1, 2017-09-14 (Mark Young and all listed Contributors)
-
Initial draft, based on
VK_EXT_debug_report
andVK_EXT_debug_marker
in addition to previous feedback supplied from various companies including Valve, Epic, and Oxide games.
-
VK_EXT_depth_clip_enable
- Name String
-
VK_EXT_depth_clip_enable
- Extension Type
-
Device extension
- Registered Extension Number
-
103
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Piers Daniell pdaniell-nv
-
- Last Modified Data
-
2018-12-20
- Contributors
-
-
Daniel Rakos, AMD
-
Henri Verbeet, CodeWeavers
-
Jeff Bolz, NVIDIA
-
Philip Rebohle, DXVK
-
Tobias Hector, AMD
-
This extension allows the depth clipping operation, that is normally
implicitly controlled by
VkPipelineRasterizationStateCreateInfo::depthClampEnable
, to
instead be controlled explicitly by
VkPipelineRasterizationDepthClipStateCreateInfoEXT::depthClipEnable
.
This is useful for translating DX content which assumes depth clamping is always enabled, but depth clip can be controlled by the DepthClipEnable rasterization state (D3D12_RASTERIZER_DESC).
New Object Types
None
New Enum Constants
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DEPTH_CLIP_ENABLE_FEATURES_EXT
-
VK_STRUCTURE_TYPE_PIPELINE_RASTERIZATION_DEPTH_CLIP_STATE_CREATE_INFO_EXT
-
New Structures
New Functions
None
Issues
None
Version History
-
Revision 1, 2018-12-20 (Piers Daniell)
-
Internal revisions
-
VK_EXT_depth_range_unrestricted
- Name String
-
VK_EXT_depth_range_unrestricted
- Extension Type
-
Device extension
- Registered Extension Number
-
14
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Piers Daniell pdaniell-nv
-
- Last Modified Date
-
2017-06-22
- Contributors
-
-
Daniel Koch, NVIDIA
-
Jeff Bolz, NVIDIA
-
This extension removes the VkViewport minDepth
and
maxDepth
restrictions that the values must be between 0.0
and 1.0
,
inclusive.
It also removes the same restriction on
VkPipelineDepthStencilStateCreateInfo minDepthBounds
and
maxDepthBounds
.
Finally it removes the restriction on the depth
value in
VkClearDepthStencilValue.
New Object Types
None.
New Enum Constants
None.
New Enums
None.
New Structures
None.
New Functions
None.
Issues
1) How do VkViewport minDepth
and maxDepth
values outside
of the 0.0
to 1.0
range interact with
Primitive Clipping?
RESOLVED: The behavior described in Primitive
Clipping still applies.
If depth clamping is disabled the depth values are still clipped to 0
≤ zc ≤ wc before the viewport transform.
If depth clamping is enabled the above equation is ignored and the depth
values are instead clamped to the VkViewport minDepth
and
maxDepth
values, which in the case of this extension can be outside of
the 0.0
to 1.0
range.
2) What happens if a resulting depth fragment is outside of the 0.0
to
1.0
range and the depth buffer is fixed-point rather than floating-point?
RESOLVED: The supported range of a fixed-point depth buffer is 0.0
to
1.0
and depth fragments are clamped to this range.
Version History
-
Revision 1, 2017-06-22 (Piers Daniell)
-
Internal revisions
-
VK_EXT_descriptor_indexing
- Name String
-
VK_EXT_descriptor_indexing
- Extension Type
-
Device extension
- Registered Extension Number
-
162
- Revision
-
2
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_KHR_maintenance3
-
- Contact
-
-
Jeff Bolz jeffbolznv
-
- Status
-
Complete
- Last Modified Data
-
2017-10-02
- Contributors
-
-
Jeff Bolz, NVIDIA
-
Daniel Rakos, AMD
-
Slawomir Grajewski, Intel
-
Tobias Hector, Imagination Technologies
-
This extension adds several small features which together enable
applications to create large descriptor sets containing substantially all of
their resources, and selecting amongst those resources with dynamic
(non-uniform) indexes in the shader.
There are feature enables and SPIR-V capabilities for non-uniform descriptor
indexing in the shader, and non-uniform indexing in the shader requires use
of a new NonUniformEXT
decoration defined in the
SPV_EXT_descriptor_indexing
SPIR-V extension.
There are descriptor set layout binding creation flags enabling several
features:
-
Descriptors can be updated after they are bound to a command buffer, such that the execution of the command buffer reflects the most recent update to the descriptors.
-
Descriptors that are not used by any pending command buffers can be updated, which enables writing new descriptors for frame N+1 while frame N is executing.
-
Relax the requirement that all descriptors in a binding that is “statically used” must be valid, such that descriptors that are not accessed by a submission need not be valid and can be updated while that submission is executing.
-
The final binding in a descriptor set layout can have a variable size (and unsized arrays of resources are allowed in the
GL_EXT_nonuniform_qualifier
andSPV_EXT_descriptor_indexing
extensions).
Note that it is valid for multiple descriptor arrays in a shader to use the same set and binding number, as long as they are all compatible with the descriptor type in the pipeline layout. This means a single array binding in the descriptor set can serve multiple texture dimensionalities, or an array of buffer descriptors can be used with multiple different block layouts.
There are new descriptor set layout and descriptor pool creation flags that
are required to opt in to the update-after-bind functionality, and there are
separate maxPerStage
* and maxDescriptorSet
* limits that apply to
these descriptor set layouts which may be much higher than the pre-existing
limits.
The old limits only count descriptors in non-updateAfterBind descriptor set
layouts, and the new limits count descriptors in all descriptor set layouts
in the pipeline layout.
New Object Types
None.
New Enum Constants
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_DESCRIPTOR_SET_LAYOUT_BINDING_FLAGS_CREATE_INFO_EXT
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DESCRIPTOR_INDEXING_FEATURES_EXT
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DESCRIPTOR_INDEXING_PROPERTIES_EXT
-
VK_STRUCTURE_TYPE_DESCRIPTOR_SET_VARIABLE_DESCRIPTOR_COUNT_ALLOCATE_INFO_EXT
-
VK_STRUCTURE_TYPE_DESCRIPTOR_SET_VARIABLE_DESCRIPTOR_COUNT_LAYOUT_SUPPORT_EXT
-
-
Extending VkDescriptorPoolCreateFlagBits:
-
VK_DESCRIPTOR_POOL_CREATE_UPDATE_AFTER_BIND_BIT_EXT
-
-
Extending VkDescriptorSetLayoutCreateFlagBits:
-
VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT_EXT
-
-
Extending VkResult:
-
VK_ERROR_FRAGMENTATION_EXT
-
New Enums
New Structures
New Functions
None.
Issues
None.
Version History
-
Revision 1, 2017-07-26 (Jeff Bolz)
-
Internal revisions
-
-
Revision 2, 2017-10-02 (Jeff Bolz)
-
???
-
VK_EXT_direct_mode_display
- Name String
-
VK_EXT_direct_mode_display
- Extension Type
-
Instance extension
- Registered Extension Number
-
89
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_KHR_display
-
- Contact
-
-
James Jones cubanismo
-
- Last Modified Date
-
2016-12-13
- IP Status
-
No known IP claims.
- Contributors
-
-
Pierre Boudier, NVIDIA
-
James Jones, NVIDIA
-
Damien Leone, NVIDIA
-
Pierre-Loup Griffais, Valve
-
Liam Middlebrook, NVIDIA
-
This is extension, along with related platform exentions, allows applications to take exclusive control of displays associated with a native windowing system. This is especially useful for virtual reality applications that wish to hide HMDs (head mounted displays) from the native platform’s display management system, desktop, and/or other applications.
New Enum Constants
None.
New Enums
None.
New Structures
None.
New Functions
Issues
1) Should this extension and its related platform-specific extensions
leverage VK_KHR_display
, or provide separate equivalent interfaces.
RESOLVED: Use VK_KHR_display
concepts and objects.
VK_KHR_display
can be used to enumerate all displays on the system,
including those attached to/in use by a window system or native platform,
but VK_KHR_display_swapchain
will fail to create a swapchain on in-use
displays.
This extension and its platform-specific children will allow applications to
grab in-use displays away from window systems and/or native platforms,
allowing them to be used with VK_KHR_display_swapchain
.
2) Are separate calls needed to acquire displays and enable direct mode?
RESOLVED: No, these operations happen in one combined command. Acquiring a display puts it into direct mode.
Version History
-
Revision 1, 2016-12-13 (James Jones)
-
Initial draft
-
VK_EXT_discard_rectangles
- Name String
-
VK_EXT_discard_rectangles
- Extension Type
-
Device extension
- Registered Extension Number
-
100
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Piers Daniell pdaniell-nv
-
- Last Modified Date
-
2016-12-22
- Interactions and External Dependencies
-
-
Interacts with
VK_KHR_device_group
-
Interacts with Vulkan 1.1
-
- Contributors
-
-
Daniel Koch, NVIDIA
-
Jeff Bolz, NVIDIA
-
This extension provides additional orthogonally aligned “discard rectangles” specified in framebuffer-space coordinates that restrict rasterization of all points, lines and triangles.
From zero to an implementation-dependent limit (specified by
maxDiscardRectangles
) number of discard rectangles can be operational
at once.
When one or more discard rectangles are active, rasterized fragments can
either survive if the fragment is within any of the operational discard
rectangles (VK_DISCARD_RECTANGLE_MODE_INCLUSIVE_EXT
mode) or be
rejected if the fragment is within any of the operational discard rectangles
(VK_DISCARD_RECTANGLE_MODE_EXCLUSIVE_EXT
mode).
These discard rectangles operate orthogonally to the existing scissor test functionality. The discard rectangles can be different for each physical device in a device group by specifying the device mask and setting discard rectangle dynamic state.
New Object Types
None.
New Enum Constants
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DISCARD_RECTANGLE_PROPERTIES_EXT
-
VK_STRUCTURE_TYPE_PIPELINE_DISCARD_RECTANGLE_STATE_CREATE_INFO_EXT
-
-
Extending VkDynamicState
-
VK_DYNAMIC_STATE_DISCARD_RECTANGLE_EXT
-
New Structures
New Functions
Issues
None.
Version History
-
Revision 1, 2016-12-22 (Piers Daniell)
-
Internal revisions
-
VK_EXT_display_control
- Name String
-
VK_EXT_display_control
- Extension Type
-
Device extension
- Registered Extension Number
-
92
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_EXT_display_surface_counter
-
Requires
VK_KHR_swapchain
-
- Contact
-
-
James Jones cubanismo
-
- Last Modified Date
-
2016-12-13
- IP Status
-
No known IP claims.
- Contributors
-
-
Pierre Boudier, NVIDIA
-
James Jones, NVIDIA
-
Damien Leone, NVIDIA
-
Pierre-Loup Griffais, Valve
-
Daniel Vetter, Intel
-
This extension defines a set of utility functions for use with the
VK_KHR_display
and VK_KHR_display_swapchain
extensions.
New Enum Constants
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_DISPLAY_POWER_INFO_EXT
-
VK_STRUCTURE_TYPE_DEVICE_EVENT_INFO_EXT
-
VK_STRUCTURE_TYPE_DISPLAY_EVENT_INFO_EXT
-
VK_STRUCTURE_TYPE_SWAPCHAIN_COUNTER_CREATE_INFO_EXT
-
New Structures
New Functions
Issues
1) Should this extension add an explicit “WaitForVsync” API or a fence signaled at vsync that the application can wait on?
RESOLVED: A fence. A separate API could later be provided that allows exporting the fence to a native object that could be inserted into standard run loops on POSIX and Windows systems.
2) Should callbacks be added for a vsync event, or in general to monitor events in Vulkan?
RESOLVED: No, fences should be used. Some events are generated by interrupts which are managed in the kernel. In order to use a callback provided by the application, drivers would need to have the userspace driver spawn threads that would wait on the kernel event, and hence the callbacks could be difficult for the application to synchronize with its other work given they would arrive on a foreign thread.
3) Should vblank or scanline events be exposed?
RESOLVED: Vblank events. Scanline events could be added by a separate extension, but the latency of processing an interrupt and waking up a userspace event is high enough that the accuracy of a scanline event would be rather low. Further, per-scanline interrupts are not supported by all hardware.
Version History
-
Revision 1, 2016-12-13 (James Jones)
-
Initial draft
-
VK_EXT_display_surface_counter
- Name String
-
VK_EXT_display_surface_counter
- Extension Type
-
Instance extension
- Registered Extension Number
-
91
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_KHR_display
-
- Contact
-
-
James Jones cubanismo
-
- Last Modified Date
-
2016-12-13
- IP Status
-
No known IP claims.
- Contributors
-
-
Pierre Boudier, NVIDIA
-
James Jones, NVIDIA
-
Damien Leone, NVIDIA
-
Pierre-Loup Griffais, Valve
-
Daniel Vetter, Intel
-
This is extension defines a vertical blanking period counter associated with display surfaces. It provides a mechanism to query support for such a counter from a VkSurfaceKHR object.
New Enum Constants
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_SURFACE_CAPABILITIES_2_EXT
-
New Structures
New Functions
Issues
None.
Version History
-
Revision 1, 2016-12-13 (James Jones)
-
Initial draft
-
VK_EXT_external_memory_dma_buf
- Name String
-
VK_EXT_external_memory_dma_buf
- Extension Type
-
Device extension
- Registered Extension Number
-
126
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_KHR_external_memory_fd
-
- Contact
-
-
Chad Versace chadversary
-
- Last Modified Date
-
2017-10-10
- IP Status
-
No known IP claims.
- Contributors
-
-
Chad Versace, Google
-
James Jones, NVIDIA
-
Jason Ekstrand, Intel
-
A dma_buf
is a type of file descriptor, defined by the Linux kernel,
that allows sharing memory across kernel device drivers and across
processes.
This extension enables applications to import a dma_buf
as
VkDeviceMemory, to export VkDeviceMemory as a dma_buf
, and
to create VkBuffer objects that can be bound to that memory.
New Enum Constants
-
Extending VkExternalMemoryHandleTypeFlagBitsKHR:
-
VK_EXTERNAL_MEMORY_HANDLE_TYPE_DMA_BUF_BIT_EXT
-
Issues
1) How does the application, when creating a VkImage that it intends
to bind to dma_buf
VkDeviceMemory containing an externally
produced image, specify the memory layout (such as row pitch and DRM format
modifier) of the VkImage? In other words, how does the application
achieve behavior comparable to that provided by
EGL_EXT_image_dma_buf_import
and
EGL_EXT_image_dma_buf_import_modifiers
?
RESOLVED: Features comparable to those in
EGL_EXT_image_dma_buf_import
and
EGL_EXT_image_dma_buf_import_modifiers
will be provided by an extension layered atop this one.
2) Without the ability to specify the memory layout of external dma_buf
images, how is this extension useful?
RESOLVED: This extension provides exactly one new feature: the ability to
import/export between dma_buf
and VkDeviceMemory.
This feature, together with features provided by
VK_KHR_external_memory_fd
, is sufficient to bind a VkBuffer to
dma_buf
.
Version History
-
Revision 1, 2017-10-10 (Chad Versace)
-
Squashed internal revisions
-
VK_EXT_external_memory_host
- Name String
-
VK_EXT_external_memory_host
- Extension Type
-
Device extension
- Registered Extension Number
-
179
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_KHR_external_memory
-
- Contact
-
-
Daniel Rakos drakos-amd
-
- Last Modified Date
-
2017-11-10
- IP Status
-
No known IP claims.
- Contributors
-
-
Jaakko Konttinen, AMD
-
David Mao, AMD
-
Daniel Rakos, AMD
-
Tobias Hector, Imagination Technologies
-
Jason Ekstrand, Intel
-
James Jones, NVIDIA
-
This extension enables an application to import host allocations and host mapped foreign device memory to Vulkan memory objects.
New Object Types
None.
New Enum Constants
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_IMPORT_MEMORY_HOST_POINTER_INFO_EXT
-
VK_STRUCTURE_TYPE_MEMORY_HOST_POINTER_PROPERTIES_EXT
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_EXTERNAL_MEMORY_HOST_PROPERTIES_EXT
-
-
Extending VkExternalMemoryHandleTypeFlagBitsKHR:
-
VK_EXTERNAL_MEMORY_HANDLE_TYPE_HOST_ALLOCATION_BIT_EXT
-
VK_EXTERNAL_MEMORY_HANDLE_TYPE_HOST_MAPPED_FOREIGN_MEMORY_BIT_EXT
-
New Enums
None.
New Structs
New Functions
Issues
1) What memory type has to be used to import host pointers?
RESOLVED: Depends on the implementation. Applications have to use the new vkGetMemoryHostPointerPropertiesEXT command to query the supported memory types for a particular host pointer. The reported memory types may include memory types that come from a memory heap that is otherwise not usable for regular memory object allocation and thus such a heap’s size may be zero.
2) Can the application still access the contents of the host allocation after importing?
RESOLVED: Yes. However, usual synchronization requirements apply.
3) Can the application free the host allocation?
RESOLVED: No, it violates valid usage conditions. Using the memory object imported from a host allocation that’s already freed thus results in undefined behavior.
4) Is vkMapMemory expected to return the same host address which was specified when importing it to the memory object?
RESOLVED: No. Implementations are allowed to return the same address but it’s not required. Some implementations might return a different virtual mapping of the allocation, although the same physical pages will be used.
5) Is there any limitation on the alignment of the host pointer and/or size?
RESOLVED: Yes.
Both the address and the size have to be an integer multiple of
minImportedHostPointerAlignment
.
In addition, some platforms and foreign devices may have additional
restrictions.
6) Can the same host allocation be imported multiple times into a given physical device?
RESOLVED: No, at least not guaranteed by this extension. Some platforms do not allow locking the same physical pages for device access multiple times, so attempting to do it may result in undefined behavior.
7) Does this extension support exporting the new handle type?
RESOLVED: No.
8) Should we include the possibility to import host mapped foreign device memory using this API?
RESOLVED: Yes, through a separate handle type. Implementations are still allowed to support only one of the handle types introduced by this extension by not returning import support for a particular handle type as returned in VkExternalMemoryPropertiesKHR.
Version History
-
Revision 1, 2017-11-10 (Daniel Rakos)
-
Internal revisions
-
VK_EXT_filter_cubic
- Name String
-
VK_EXT_filter_cubic
- Extension Type
-
Device extension
- Registered Extension Number
-
171
- Revision
-
2
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_IMG_filter_cubic
-
- Contact
-
-
Bill Licea-Kane wwlk
-
- Last Modified Date
-
2019-01-24
- Contributors
-
-
Bill Licea-Kane, Qualcomm Technologies, Inc.
-
Andrew Garrard, Samsung
-
Daniel Koch, NVIDIA
-
Donald Scorgie, Imagination Technologies
-
Graeme Leese, Broadcom
-
Jan-Herald Fredericksen, ARM
-
Jeff Leger, Qualcomm Technologies, Inc.
-
Tobias Hector, AMD
-
Tom Olson, ARM
-
Stuart Smith, Imagination Technologies
-
VK_EXT_filter_cubic
extends VK_IMG_filter_cubic
.
It documents cubic filtering of other image view types.
It adds new structures that can be added to the pNext
chain of
VkPhysicalDeviceImageFormatInfo2 and VkImageFormatProperties2
that can be used to determine which image types and which image view types
support cubic filtering.
New Structures
Version History
-
Revision 2, 2019-06-05 (wwlk)
-
Clarify 1D optional
-
-
Revision 1, 2019-01-24 (wwlk)
-
Initial version
-
VK_EXT_fragment_density_map
- Name String
-
VK_EXT_fragment_density_map
- Extension Type
-
Device extension
- Registered Extension Number
-
219
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Matthew Netsch mnetsch
-
- Last Modified Date
-
2018-09-25
- Interactions and External Dependencies
-
-
This extension requires the
SPV_EXT_fragment_invocation_density
SPIR-V extension.
-
- Contributors
-
-
Matthew Netsch, Qualcomm Technologies, Inc.
-
Robert VanReenen, Qualcomm Technologies, Inc.
-
Jonathan Wicks, Qualcomm Technologies, Inc.
-
Tate Hornbeck, Qualcomm Technologies, Inc.
-
Sam Holmes, Qualcomm Technologies, Inc.
-
Jeff Leger, Qualcomm Technologies, Inc.
-
Jan-Harald Fredriksen, ARM
-
Jeff Bolz, NVIDIA
-
Pat Brown, NVIDIA
-
Daniel Rakos, AMD
-
Piers Daniell, NVIDIA
-
This extension allows an application to specify areas of the render target where the fragment shader may be invoked fewer times. These fragments are broadcasted out to multiple pixels to cover the render target.
The primary use of this extension is to reduce workloads in areas where lower quality may not be perceived such as the distorted edges of a lens or the periphery of a user’s gaze.
New Object Types
None.
New Enum Constants
-
Extending VkAccessFlagBits:
-
VK_ACCESS_FRAGMENT_DENSITY_MAP_READ_BIT_EXT
-
-
Extending VkFormatFeatureFlagBits:
-
VK_FORMAT_FEATURE_FRAGMENT_DENSITY_MAP_BIT_EXT
-
-
Extending VkImageCreateFlagBits:
-
VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT
-
-
Extending VkImageLayout:
-
VK_IMAGE_LAYOUT_FRAGMENT_DENSITY_MAP_OPTIMAL_EXT
-
-
Extending VkImageUsageFlagBits:
-
VK_IMAGE_USAGE_FRAGMENT_DENSITY_MAP_BIT_EXT
-
-
Extending VkImageViewCreateFlagBits:
-
VK_IMAGE_VIEW_CREATE_FRAGMENT_DENSITY_MAP_DYNAMIC_BIT_EXT
-
-
Extending VkPipelineStageFlagBits:
-
VK_PIPELINE_STAGE_FRAGMENT_DENSITY_PROCESS_BIT_EXT
-
-
Extending VkSamplerCreateFlagBits:
-
VK_SAMPLER_CREATE_SUBSAMPLED_BIT_EXT
-
VK_SAMPLER_CREATE_SUBSAMPLED_COARSE_RECONSTRUCTION_BIT_EXT
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FRAGMENT_DENSITY_MAP_FEATURES_EXT
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FRAGMENT_DENSITY_MAP_PROPERTIES_EXT
-
VK_STRUCTURE_TYPE_RENDER_PASS_FRAGMENT_DENSITY_MAP_CREATE_INFO_EXT
-
New Enums
None.
New Structures
New Functions
None.
New or Modified Built-In Variables
New Variable Decorations
None.
New SPIR-V Capabilities
Version History
-
Revision 1, 2018-09-25 (Matthew Netsch)
-
Initial version
-
VK_EXT_fragment_shader_interlock
- Name String
-
VK_EXT_fragment_shader_interlock
- Extension Type
-
Device extension
- Registered Extension Number
-
252
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Piers Daniell pdaniell-nv
-
- Last Modified Data
-
2019-05-02
- Interactions and External Dependencies
-
-
This extension requires the
SPV_EXT_fragment_shader_interlock
SPIR-V extension. -
This extension requires the
GL_ARB_fragment_shader_interlock
, extensions for GLSL source languages.
-
- Contributors
-
-
Daniel Koch, NVIDIA
-
Graeme Leese, Broadcom
-
Jan-Harald Fredriksen, Arm
-
Jason Ekstrand, Intel
-
Jeff Bolz, NVIDIA
-
Ruihao Zhang, Qualcomm
-
Slawomir Grajewski, Intel
-
Spencer Fricke, Samsung
-
This extension adds support for the FragmentShaderPixelInterlockEXT
,
FragmentShaderSampleInterlockEXT
, and
FragmentShaderShadingRateInterlockEXT
capabilities from the
SPV_EXT_fragment_shader_interlock
extension to Vulkan.
Enabling these capabilities provides a critical section for fragment shaders to avoid overlapping pixels being processed at the same time, and certain guarantees about the ordering of fragment shader invocations of fragments of overlapping pixels.
This extension can be useful for algorithms that need to access per-pixel data structures via shader loads and stores. Algorithms using this extension can access per-pixel data structures in critical sections without other invocations accessing the same per-pixel data. Additionally, the ordering guarantees are useful for cases where the API ordering of fragments is meaningful. For example, applications may be able to execute programmable blending operations in the fragment shader, where the destination buffer is read via image loads and the final value is written via image stores.
New Object Types
None.
New Enum Constants
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FRAGMENT_SHADER_INTERLOCK_FEATURES_EXT
-
New Enums
None.
New Structures
New Functions
None.
New SPIR-V Capabilities
Issues
None.
Version History
-
Revision 1, 2019-05-24 (Piers Daniell)
-
Internal revisions
-
VK_EXT_full_screen_exclusive
- Name String
-
VK_EXT_full_screen_exclusive
- Extension Type
-
Device extension
- Registered Extension Number
-
256
- Revision
-
4
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_KHR_surface
-
Requires
VK_KHR_get_surface_capabilities2
-
Requires
VK_KHR_swapchain
-
- Contact
-
-
James Jones cubanismo
-
- Last Modified Date
-
2019-03-12
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
Interacts with Vulkan 1.1
-
Interacts with
VK_KHR_device_group
-
Interacts with
VK_KHR_win32_surface
-
- Contributors
-
-
Hans-Kristian Arntzen, ARM
-
Slawomir Grajewski, Intel
-
Tobias Hector, AMD
-
James Jones, NVIDIA
-
Daniel Rakos, AMD
-
Jeff Juliano, NVIDIA
-
Joshua Schnarr, NVIDIA
-
Aaron Hagan, AMD
-
This extension allows applications to set the policy for swapchain creation and presentation mechanisms relating to full-screen access. Implementations may be able to acquire exclusive access to a particular display for an application window that covers the whole screen. This can increase performance on some systems by bypassing composition, however it can also result in disruptive or expensive transitions in the underlying windowing system when a change occurs.
Applications can choose between explicitly disallowing or allowing this behavior, letting the implementation decide, or managing this mode of operation directly using the new vkAcquireFullScreenExclusiveModeEXT and vkReleaseFullScreenExclusiveModeEXT commands.
New Enum Constants
-
Extending VkResult
-
VK_ERROR_FULL_SCREEN_EXCLUSIVE_MODE_LOST_EXT
-
-
Extending VkStructureType
-
VK_STRUCTURE_TYPE_SURFACE_FULL_SCREEN_EXCLUSIVE_INFO_EXT
-
VK_STRUCTURE_TYPE_SURFACE_CAPABILITIES_FULL_SCREEN_EXCLUSIVE_EXT
-
VK_STRUCTURE_TYPE_SURFACE_FULL_SCREEN_EXCLUSIVE_WIN32_INFO_EXT
-
New Enums
New Structures
New Functions
Issues
1) What should the extension & flag be called?
RESOLVED: VK_EXT_full_screen_exclusive.
Other options considered (prior to the app-controlled mode) were:
-
VK_EXT_smooth_fullscreen_transition
-
VK_EXT_fullscreen_behavior
-
VK_EXT_fullscreen_preference
-
VK_EXT_fullscreen_hint
-
VK_EXT_fast_fullscreen_transition
-
VK_EXT_avoid_fullscreen_exclusive
2) Do we need more than a boolean toggle?
RESOLVED: Yes.
Using an enum with default/allowed/disallowed/app-controlled enables applications to accept driver default behavior, specifically override it in either direction without implying the driver is ever required to use full-screen exclusive mechanisms, or manage this mode explicitly.
3) Should this be a KHR or EXT extension?
RESOLVED: EXT, in order to allow it to be shipped faster.
4) Can the fullscreen hint affect the surface capabilities, and if so, should the hint also be specified as input when querying the surface capabilities?
RESOLVED: Yes on both accounts.
While the hint does not guarantee a particular fullscreen mode will be used when the swapchain is created, it can sometimes imply particular modes will NOT be used. If the driver determines that it will opt-out of using a particular mode based on the policy, and knows it can only support certain capabilities if that mode is used, it would be confusing at best to the application to report those capabilities in such cases. Not allowing implementations to report this state to applications could result in situations where applications are unable to determine why swapchain creation fails when they specify certain hint values, which could result in never- terminating surface creation loops.
5) Should full-screen be one word or two?
RESOLVED: Two words.
"Fullscreen" is not in my dictionary, and web searches did not turn up definitive proof that it is a colloquially accepted compound word. Documentation for the corresponding Windows API mechanisms dithers. The text consistently uses a hyphen, but none-the-less, there is a SetFullscreenState method in the DXGI swapchain object. Given this inconclusive external guidance, it is best to adhere to the Vulkan style guidelines and avoid inventing new compound words.
Version History
-
Revision 4, 2019-03-12 (Tobias Hector)
-
Added application-controlled mode, and related functions
-
Tidied up appendix
-
-
Revision 3, 2019-01-03 (James Jones)
-
Renamed to VK_EXT_full_screen_exclusive
-
Made related adjustments to the tri-state enumerant names.
-
-
Revision 2, 2018-11-27 (James Jones)
-
Renamed to VK_KHR_fullscreen_behavior
-
Switched from boolean flag to tri-state enum
-
-
Revision 1, 2018-11-06 (James Jones)
-
Internal revision
-
VK_EXT_global_priority
- Name String
-
VK_EXT_global_priority
- Extension Type
-
Device extension
- Registered Extension Number
-
175
- Revision
-
2
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Andres Rodriguez lostgoat
-
- Last Modified Date
-
2017-10-06
- IP Status
-
No known IP claims.
- Contributors
-
-
Andres Rodriguez, Valve
-
Pierre-Loup Griffais, Valve
-
Dan Ginsburg, Valve
-
Mitch Singer, AMD
-
In Vulkan, users can specify device-scope queue priorities.
In some cases it may be useful to extend this concept to a system-wide
scope.
This extension provides a mechanism for caller’s to set their system-wide
priority.
The default queue priority is VK_QUEUE_GLOBAL_PRIORITY_MEDIUM_EXT
.
The driver implementation will attempt to skew hardware resource allocation in favour of the higher-priority task. Therefore, higher-priority work may retain similar latency and throughput characteristics even if the system is congested with lower priority work.
The global priority level of a queue shall take precedence over the
per-process queue priority
(VkDeviceQueueCreateInfo
::pQueuePriorities
).
Abuse of this feature may result in starving the rest of the system from
hardware resources.
Therefore, the driver implementation may deny requests to acquire a priority
above the default priority (VK_QUEUE_GLOBAL_PRIORITY_MEDIUM_EXT
) if
the caller does not have sufficient privileges.
In this scenario VK_ERROR_NOT_PERMITTED_EXT
is returned.
The driver implementation may fail the queue allocation request if resources
required to complete the operation have been exhausted (either by the same
process or a different process).
In this scenario VK_ERROR_INITIALIZATION_FAILED
is returned.
New Object Types
None.
New Enum Constants
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_DEVICE_QUEUE_GLOBAL_PRIORITY_CREATE_INFO_EXT
-
-
Extending VkResult:
-
VK_ERROR_NOT_PERMITTED_EXT
-
New Enums
New Structures
New Functions
None.
Issues
None.
Version History
-
Revision 2, 2017-11-03 (Andres Rodriguez)
-
Fixed VkQueueGlobalPriorityEXT missing _EXT suffix
-
-
Revision 1, 2017-10-06 (Andres Rodriguez)
-
First version.
-
VK_EXT_hdr_metadata
- Name String
-
VK_EXT_hdr_metadata
- Extension Type
-
Device extension
- Registered Extension Number
-
106
- Revision
-
2
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_KHR_swapchain
-
- Contact
-
-
Courtney Goeltzenleuchter courtney-g
-
- Last Modified Date
-
2018-12-19
- IP Status
-
No known IP claims.
- Contributors
-
-
Courtney Goeltzenleuchter, Google
-
This extension defines two new structures and a function to assign SMPTE
(the Society of Motion Picture and Television Engineers) 2086 metadata and
CTA (Consumer Technology Association) 861.3 metadata to a swapchain.
The metadata includes the color primaries, white point, and luminance range
of the mastering display, which all together define the color volume that
contains all the possible colors the mastering display can produce.
The mastering display is the display where creative work is done and
creative intent is established.
To preserve such creative intent as much as possible and achieve consistent
color reproduction on different viewing displays, it is useful for the
display pipeline to know the color volume of the original mastering display
where content was created or tuned.
This avoids performing unnecessary mapping of colors that are not
displayable on the original mastering display.
The metadata also includes the maxContentLightLevel
and
maxFrameAverageLightLevel
as defined by CTA 861.3.
While the general purpose of the metadata is to assist in the transformation between different color volumes of different displays and help achieve better color reproduction, it is not in the scope of this extension to define how exactly the metadata should be used in such a process. It is up to the implementation to determine how to make use of the metadata.
New Enum Constants
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_HDR_METADATA_EXT
-
New Structures
New Functions
Issues
1) Do we need a query function?
PROPOSED: No, Vulkan does not provide queries for state that the application can track on its own.
2) Should we specify default if not specified by the application?
PROPOSED: No, that leaves the default up to the display.
Version History
-
Revision 1, 2016-12-27 (Courtney Goeltzenleuchter)
-
Initial version
-
-
Revision 2, 2018-12-19 (Courtney Goeltzenleuchter)
-
Correct implicit validity for VkHdrMetadataEXT structure
-
VK_EXT_headless_surface
- Name String
-
VK_EXT_headless_surface
- Extension Type
-
Instance extension
- Registered Extension Number
-
257
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_KHR_surface
-
- Contact
-
-
Lisa Wu chengtianww
-
- Last Modified Date
-
2019-03-21
- IP Status
-
No known IP claims.
- Contributors
-
-
Ray Smith, Arm
-
The VK_EXT_headless_surface
extension is an instance extension.
It provides a mechanism to create VkSurfaceKHR objects independently
of any window system or display device.
The presentation operation for a swapchain created from a headless surface
is by default a no-op, resulting in no externally-visible result.
Because there is no real presentation target, future extensions can layer on top of the headless surface to introduce arbitrary or customisable sets of restrictions or features. These could include features like saving to a file or restrictions to emulate a particular presentation target.
This functionality is expected to be useful for application and driver development because it allows any platform to expose an arbitrary or customisable set of restrictions and features of a presentation engine. This makes it a useful portable test target for applications targeting a wide range of presentation engines where the actual target presentation engines might be scarce, unavailable or otherwise undesirable or inconvenient to use for general Vulkan application development.
New Object Types
None
New Enum Constants
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_HEADLESS_SURFACE_CREATE_INFO_EXT
-
New Enums
None
New Structures
New Functions
Issues
None
Version History
-
Revision 1, 2019-03-21 (Ray Smith)
-
Initial draft
-
VK_EXT_host_query_reset
- Name String
-
VK_EXT_host_query_reset
- Extension Type
-
Device extension
- Registered Extension Number
-
262
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Bas Nieuwenhuizen BNieuwenhuizen
-
- Last Modified Date
-
2019-03-06
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
- Contributors
-
-
Bas Nieuwenhuizen, Google
-
Jason Ekstrand, Intel
-
Jeff Bolz, NVIDIA
-
Piers Daniell, NVIDIA
-
This extension adds a new function to reset queries from the host.
New Enum Constants
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_HOST_QUERY_RESET_FEATURES_EXT
-
New Enums
None.
New Structures
New Functions
Issues
Version History
-
Revision 1, 2019-03-12 (Bas Nieuwenhuizen)
-
Initial draft
-
VK_EXT_image_drm_format_modifier
- Name String
-
VK_EXT_image_drm_format_modifier
- Extension Type
-
Device extension
- Registered Extension Number
-
159
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_KHR_bind_memory2
-
Requires
VK_KHR_image_format_list
-
Requires
VK_KHR_sampler_ycbcr_conversion
-
- Contact
-
-
Chad Versace chadversary
-
- Last Modified Date
-
2018-08-29
- IP Status
-
No known IP claims.
- Contributors
-
-
Antoine Labour, Google
-
Bas Nieuwenhuizen, Google
-
Chad Versace, Google
-
James Jones, NVIDIA
-
Jason Ekstrand, Intel
-
Jőrg Wagner, ARM
-
Kristian Høgsberg Kristensen, Google
-
Ray Smith, ARM
-
Overview
Summary
This extension provides the ability to use DRM format modifiers with images, enabling Vulkan to better integrate with the Linux ecosystem of graphics, video, and display APIs.
Its functionality closely overlaps with
EGL_EXT_image_dma_buf_import_modifiers
2
and
EGL_MESA_image_dma_buf_export
3.
Unlike the EGL extensions, this extension does not require the use of a
specific handle type (such as a dma_buf) for external memory and provides
more explicit control of image creation.
Introduction to DRM Format Modifiers
A DRM format modifier is a 64-bit, vendor-prefixed, semi-opaque unsigned
integer.
Most modifiers represent a concrete, vendor-specific tiling format for
images.
Some exceptions are DRM_FORMAT_MOD_LINEAR
(which is not
vendor-specific); DRM_FORMAT_MOD_NONE
(which is an alias of
DRM_FORMAT_MOD_LINEAR
due to historical accident); and
DRM_FORMAT_MOD_INVALID
(which does not represent a tiling format).
The modifier’s vendor prefix consists of the 8 most significant bits.
The canonical list of modifiers and vendor prefixes is found in
drm_fourcc.h
in the Linux kernel source.
The other dominant source of modifiers are vendor kernel trees.
One goal of modifiers in the Linux ecosystem is to enumerate for each vendor a reasonably sized set of tiling formats that are appropriate for images shared across processes, APIs, and/or devices, where each participating component may possibly be from different vendors. A non-goal is to enumerate all tiling formats supported by all vendors. Some tiling formats used internally by vendors are inappropriate for sharing; no modifiers should be assigned to such tiling formats.
Modifier values typically do not describe memory layouts. More precisely, a modifier's lower 56 bits usually have no structure. Instead, modifiers name memory layouts; they name a small set of vendor-preferred layouts for image sharing. As a consequence, in each vendor namespace the modifier values are often sequentially allocated starting at 1.
Each modifier is usually supported by a single vendor and its name matches
the pattern {VENDOR}_FORMAT_MOD_*
or DRM_FORMAT_MOD_{VENDOR}_*
.
Examples are I915_FORMAT_MOD_X_TILED
and
DRM_FORMAT_MOD_BROADCOM_VC4_T_TILED
.
An exception is DRM_FORMAT_MOD_LINEAR
, which is supported by most
vendors.
Many APIs in Linux use modifiers to negotiate and specify the memory
layout of shared images.
For example, a Wayland compositor and Wayland client may, by relaying
modifiers over the Wayland protocol zwp_linux_dmabuf_v1
, negotiate a
vendor-specific tiling format for a shared wl_buffer
.
The client may allocate the underlying memory for the wl_buffer
with
GBM, providing the chosen modifier to gbm_bo_create_with_modifiers
.
The client may then import the wl_buffer
into Vulkan for producing
image content, providing the resource’s dma_buf to
VkImportMemoryFdInfoKHR and its modifier to
VkImageDrmFormatModifierExplicitCreateInfoEXT.
The compositor may then import the wl_buffer
into OpenGL for sampling,
providing the resource’s dma_buf and modifier to eglCreateImage
.
The compositor may also bypass OpenGL and submit the wl_buffer
directly
to the kernel’s display API, providing the dma_buf and modifier through
drm_mode_fb_cmd2
.
Format Translation
Modifier-capable APIs often pair modifiers with DRM formats, which are
defined in
drm_fourcc.h
.
However, VK_EXT_image_drm_format_modifier
uses VkFormat instead of
DRM formats.
The application must convert between VkFormat and DRM format when it
sends or receives a DRM format to or from an external API.
The mapping from VkFormat to DRM format is lossy. Therefore, when receiving a DRM format from an external API, often the application must use information from the external API to accurately map the DRM format to a VkFormat. For example, DRM formats do not distinguish between RGB and sRGB (as of 2018-03-28); external information is required to identify the image’s colorspace.
The mapping between VkFormat and DRM format is also incomplete. For some DRM formats there exist no corresponding Vulkan format, and for some Vulkan formats there exist no corresponding DRM format.
Usage Patterns
Three primary usage patterns are intended for this extension:
-
Negotiation. The application negotiates with modifier-aware, external components to determine sets of image creation parameters supported among all components.
In the Linux ecosystem, the negotiation usually assumes the image is a 2D, single-sampled, non-mipmapped, non-array image; this extension permits that assumption but does not require it. The result of the negotiation usually resembles a set of tuples such as (drmFormat, drmFormatModifier), where each participating component supports all tuples in the set.
Many details of this negotiation—such as the protocol used during negotiation, the set of image creation parameters expressable in the protocol, and how the protocol chooses which process and which API will create the image—are outside the scope of this specification.
In this extension, vkGetPhysicalDeviceFormatProperties2 with VkDrmFormatModifierPropertiesListEXT serves a primary role during the negotiation, and vkGetPhysicalDeviceImageFormatProperties2 with VkPhysicalDeviceImageDrmFormatModifierInfoEXT serves a secondary role.
-
Import. The application imports an image with a modifier.
In this pattern, the application receives from an external source the image’s memory and its creation parameters, which are often the result of the negotiation described above. Some image creation parameters are implicitly defined by the external source; for example,
VK_IMAGE_TYPE_2D
is often assumed. Some image creation parameters are usually explicit, such as the image’sformat
,drmFormatModifier
, andextent
; and each plane’soffset
androwPitch
.Before creating the image, the application first verifies that the physical device supports the received creation parameters by querying vkGetPhysicalDeviceFormatProperties2 with VkDrmFormatModifierPropertiesListEXT and vkGetPhysicalDeviceImageFormatProperties2 with VkPhysicalDeviceImageDrmFormatModifierInfoEXT. Then the application creates the image by chaining VkImageDrmFormatModifierExplicitCreateInfoEXT and VkExternalMemoryImageCreateInfo onto VkImageCreateInfo.
-
Export. The application creates an image and allocates its memory. Then the application exports to modifier-aware consumers the image’s memory handles; its creation parameters; its modifier; and the
offset
,size
, androwPitch
of each memory plane.In this pattern, the Vulkan device is the authority for the image; it is the allocator of the image’s memory and the decider of the image’s creation parameters. When choosing the image’s creation parameters, the application usually chooses a tuple (format, drmFormatModifier) from the result of the negotiation described above. The negotiation’s result often contains multiple tuples that share the same format but differ in their modifier. In this case, the application should defer the choice of the image’s modifier to the Vulkan implementation by providing all such modifiers to VkImageDrmFormatModifierListCreateInfoEXT::
pDrmFormatModifiers
; and the implementation should choose frompDrmFormatModifiers
the optimal modifier in consideration with the other image parameters.The application creates the image by chaining VkImageDrmFormatModifierListCreateInfoEXT and VkExternalMemoryImageCreateInfo onto VkImageCreateInfo. The protocol and APIs by which the application will share the image with external consumers will likely determine the value of VkExternalMemoryImageCreateInfo::
handleTypes
. The implementation chooses for the image an optimal modifier from VkImageDrmFormatModifierListCreateInfoEXT::pDrmFormatModifiers
. The application then queries the implementation-chosen modifier with vkGetImageDrmFormatModifierPropertiesEXT, and queries the memory layout of each plane with vkGetImageSubresourceLayout.The application then allocates the image’s memory with VkMemoryAllocateInfo, adding chained extension structures for external memory; binds it to the image; and exports the memory, for example, with vkGetMemoryFdKHR.
Finally, the application sends the image’s creation parameters, its modifier, its per-plane memory layout, and the exported memory handle to the external consumers. The details of how the application transmits this information to external consumers is outside the scope of this specification.
Prior Art
Extension
EGL_EXT_image_dma_buf_import
1
introduced the ability to create an EGLImage
by importing for each
plane a dma_buf, offset, and row pitch.
Later, extension
EGL_EXT_image_dma_buf_import_modifiers
2
introduced the ability to query which combination of formats and modifiers
the implementation supports and to specify modifiers during creation of
the EGLImage
.
Extension
EGL_MESA_image_dma_buf_export
3
is the inverse of EGL_EXT_image_dma_buf_import_modifiers
.
The Linux kernel modesetting API (KMS), when configuring the display’s
framebuffer with struct
drm_mode_fb_cmd2
4, allows one to
specify the frambuffer’s modifier as well as a per-plane memory handle,
offset, and row pitch.
GBM, a graphics buffer manager for Linux, allows creation of a gbm_bo
(that is, a graphics buffer object) by importing data similar to that in
EGL_EXT_image_dma_buf_import_modifiers
1;
and symmetrically allows exporting the same data from the gbm_bo
.
See the references to modifier and plane in
gbm.h
5.
New Object Types
None.
New Enum Constants
-
Extending VkResult:
-
VK_ERROR_INVALID_DRM_FORMAT_MODIFIER_PLANE_LAYOUT_EXT
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_DRM_FORMAT_MODIFIER_PROPERTIES_LIST_EXT
-
VK_STRUCTURE_TYPE_DRM_FORMAT_MODIFIER_PROPERTIES_EXT
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGE_DRM_FORMAT_MODIFIER_INFO_EXT
-
VK_STRUCTURE_TYPE_IMAGE_DRM_FORMAT_MODIFIER_LIST_CREATE_INFO_EXT
-
VK_STRUCTURE_TYPE_IMAGE_DRM_FORMAT_MODIFIER_EXPLICIT_CREATE_INFO_EXT
-
VK_STRUCTURE_TYPE_IMAGE_DRM_FORMAT_MODIFIER_PROPERTIES_EXT
-
-
Extending VkImageTiling:
-
VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT
-
-
Extending VkImageAspectFlagBits:
-
VK_IMAGE_ASPECT_MEMORY_PLANE_0_BIT_EXT
-
VK_IMAGE_ASPECT_MEMORY_PLANE_1_BIT_EXT
-
VK_IMAGE_ASPECT_MEMORY_PLANE_2_BIT_EXT
-
VK_IMAGE_ASPECT_MEMORY_PLANE_3_BIT_EXT
-
New Enums
None.
New Structures
-
Extends VkFormatProperties2:
-
Member of VkDrmFormatModifierPropertiesListEXT:
-
Extends VkPhysicalDeviceImageFormatInfo2:
-
Extends VkImageCreateInfo:
-
Parameter to vkGetImageDrmFormatModifierPropertiesEXT:
New Functions
Issues
1) Should this extension define a single DRM format modifier per
VkImage
? Or define one per plane?
+
RESOLVED: There exists a single DRM format modifier per VkImage
.
DISCUSSION: Prior art, such as
EGL_EXT_image_dma_buf_import_modifiers
2,
struct drm_mode_fb_cmd2
4, and
struct
gbm_import_fd_modifier_data
5,
allows defining one modifier per plane.
However, developers of the GBM and kernel APIs concede it was a mistake.
Beginning in Linux 4.10, the kernel requires that the application provide
the same DRM format modifier for each plane.
(See Linux commit
bae781b259269590109e8a4a8227331362b88212).
And GBM provides an entrypoint, gbm_bo_get_modifier
, for querying the
modifier of the image but does not provide one to query the modifier of
individual planes.
2) When creating an image with VkImageDrmFormatModifierExplicitCreateInfoEXT, which is typically used when importing an image, should the application explicitly provide the size of each plane?
+
RESOLVED: No.
The application must not provide the size.
To enforce this, the API requires that
VkImageDrmFormatModifierExplicitCreateInfoEXT::pPlaneLayouts
->size
must be 0.
DISCUSSION: Prior art, such as
EGL_EXT_image_dma_buf_import_modifiers
2,
struct drm_mode_fb_cmd2
4, and
struct
gbm_import_fd_modifier_data
5,
omits from the API the size of each plane.
Instead, the APIs infer each plane’s size from the import parameters, which
include the image’s pixel format and a dma_buf, offset, and row pitch for
each plane.
However, Vulkan differs from EGL and GBM with regards to image creation in the following ways:
-
Undedicated allocation by default. When importing or exporting a set of dma_bufs as an
EGLImage
orgbm_bo
, common practice mandates that each dma_buf’s memory be dedicated (in the sense ofVK_KHR_dedicated_allocation
) to the image (though not necessarily dedicated to a single plane). In particular, neither the GBM documentation nor the EGL extension specifications explicitly state this requirement, but in light of common practice this is likely due to under-specification rather than intentional omission. In contrast,VK_EXT_image_drm_format_modifier
permits, but does not require, the implementation to require dedicated allocations for images created withVK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT
. -
Separation of image creation and memory allocation. When importing a set of dma_bufs as an
EGLImage
orgbm_bo
, EGL and GBM create the image resource and bind it to memory (the dma_bufs) simultaneously. This allows EGL and GBM to query each dma_buf’s size during image creation. In Vulkan, image creation and memory allocation are independent unless a dedicated allocation is used (as inVK_KHR_dedicated_allocation
). Therefore, without requiring dedicated allocation, Vulkan cannot query the size of each dma_buf (or other external handle) when calculating the image’s memory layout. Even if dedication allocation were required, Vulkan cannot calculate the image’s memory layout until after the image is bound to its dma_ufs.
The above differences complicate the potential inference of plane size in Vulkan. Consider the following problematic cases:
-
Padding. Some plane of the image may require implementation-dependent padding.
-
Metadata. For some modifiers, the image may have a metadata plane which requires a non-trivial calculation to determine its size.
-
Mipmapped, array, and 3D images. The implementation may support
VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT
for images whosemipLevels
,arrayLayers
, ordepth
is greater than 1. For such images with certain modifiers, the calculation of each plane’s size may be non-trivial.
However, an application-provided plane size solves none of the above problems.
For simplicity, consider an external image with a single memory plane.
The implementation is obviously capable calculating the image’s size when
its tiling is VK_IMAGE_TILING_OPTIMAL
.
Likewise, any reasonable implementation is capable of calculating the
image’s size when its tiling uses a supported modifier.
Suppose that the external image’s size is smaller than the
implementation-calculated size.
If the application provided the external image’s size to
vkCreateImage, the implementation would observe the mismatched size
and recognize its inability to comprehend the external image’s layout
(unless the implementation used the application-provided size to select a
refinement of the tiling layout indicated by the modifier, which is
strongly discouraged).
The implementation would observe the conflict, and reject image creation
with VK_ERROR_INVALID_DRM_FORMAT_MODIFIER_PLANE_LAYOUT_EXT
.
On the other hand, if the application did not provide the external image’s
size to vkCreateImage, then the application would observe after
calling vkGetImageMemoryRequirements that the external image’s size is
less than the size required by the implementation.
The application would observe the conflict and refuse to bind the
VkImage
to the external memory.
In both cases, the result is explicit failure.
Suppose that the external image’s size is larger than the
implementation-calculated size.
If the application provided the external image’s size to
vkCreateImage, for reasons similar to above the implementation would
observe the mismatched size and recognize its inability to comprehend the
image data residing in the extra size.
The implementation, however, must assume that image data resides in the
entire size provided by the application.
The implementation would observe the conflict and reject image creation with
VK_ERROR_INVALID_DRM_FORMAT_MODIFIER_PLANE_LAYOUT_EXT
.
On the other hand, if the application did not provide the external image’s
size to vkCreateImage, then the application would observe after
calling vkGetImageMemoryRequirements that the external image’s size is
larger than the implementation-usable size.
The application would observe the conflict and refuse to bind the
VkImage
to the external memory.
In both cases, the result is explicit failure.
Therefore, an application-provided size provides no benefit, and this
extension should not require it.
This decision renders VkSubresourceLayout::size
an unused field
during image creation, and thus introduces a risk that implementations may
require applications to submit sideband creation parameters in the unused
field.
To prevent implementations from relying on sideband data, this extension
requires the application to set size
to 0.
References
Version History
-
Revision 1, 2018-08-29 (Chad Versace)
-
First stable revision
-
VK_EXT_index_type_uint8
- Name String
-
VK_EXT_index_type_uint8
- Extension Type
-
Device extension
- Registered Extension Number
-
266
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Piers Daniell pdaniell-nv
-
- Last Modified Date
-
2019-05-02
- IP Status
-
No known IP claims.
- Contributors
-
-
Jeff Bolz, NVIDIA
-
This extension allows uint8_t indices to be used with vkCmdBindIndexBuffer.
New Object Types
None
New Enum Constants
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_INDEX_TYPE_UINT8_FEATURES_EXT
-
-
Extending VkIndexType:
-
VK_INDEX_TYPE_UINT8_EXT
-
New Enums
None
New Structures
New Functions
None
New Built-In Variables
None
New SPIR-V Capabilities
None
Issues
None
Version History
-
Revision 1, 2019-05-02 (Piers Daniell)
-
Internal revisions
-
VK_EXT_inline_uniform_block
- Name String
-
VK_EXT_inline_uniform_block
- Extension Type
-
Device extension
- Registered Extension Number
-
139
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_KHR_maintenance1
-
- Contact
-
-
Daniel Rakos aqnuep
-
- Last Modified Date
-
2018-08-01
- IP Status
-
No known IP claims.
- Contributors
-
-
Daniel Rakos, AMD
-
Jeff Bolz, NVIDIA
-
Slawomir Grajewski, Intel
-
Neil Henning, Codeplay
-
This extension introduces the ability to back uniform blocks directly with descriptor sets by storing inline uniform data within descriptor pool storage. Compared to push constants this new construct allows uniform data to be reused across multiple disjoint sets of draw or dispatch commands and may enable uniform data to be accessed with less indirections compared to uniforms backed by buffer memory.
New Object Types
None
New Enum Constants
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_INLINE_UNIFORM_BLOCK_FEATURES_EXT
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_INLINE_UNIFORM_BLOCK_PROPERTIES_EXT
-
VK_STRUCTURE_TYPE_WRITE_DESCRIPTOR_SET_INLINE_UNIFORM_BLOCK_EXT
-
VK_STRUCTURE_TYPE_DESCRIPTOR_POOL_INLINE_UNIFORM_BLOCK_CREATE_INFO_EXT
-
-
Extending VkDescriptorType:
-
VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK_EXT
-
New Enums
None
New Structures
New Functions
None
New Built-In Variables
None
Issues
1) Do we need a new storage class for inline uniform blocks vs uniform blocks?
RESOLVED: No.
The Uniform
storage class is used to allow the same syntax used for
both uniform buffers and inline uniform blocks.
2) Is the descriptor array index and array size expressed in terms of bytes or dwords for inline uniform block descriptors?
RESOLVED: In bytes, but both must be a multiple of 4, similar to how push
constant ranges are specified.
The descriptorCount
of VkDescriptorSetLayoutBinding
thus
provides the total number of bytes a particular binding with an inline
uniform block descriptor type can hold, while the srcArrayElement
,
dstArrayElement
, and descriptorCount
members of
VkWriteDescriptorSet
, VkCopyDescriptorSet
, and
VkDescriptorUpdateTemplateEntry
(where applicable) specify the byte
offset and number of bytes to write/copy to the binding’s backing store.
Additionally, the stride
member of
VkDescriptorUpdateTemplateEntry
is ignored for inline uniform blocks
and a default value of one is used, meaning that the data to update inline
uniform block bindings with must be contiguous in memory.
3) What layout rules apply for uniform blocks corresponding to inline constants?
RESOLVED: They use the same layout rules as uniform buffers.
4) Do we need to add non-uniform indexing features/properties as introduced
by VK_EXT_descriptor_indexing
for inline uniform blocks?
RESOLVED: No, because inline uniform blocks are not allowed to be “arrayed”. A single binding with an inline uniform block descriptor type corresponds to a single uniform block instance and the array indices inside that binding refer to individual offsets within the uniform block (see issue #2). However, this extension does introduce new features/properties about the level of support for update-after-bind inline uniform blocks.
5) Is the descriptorBindingVariableDescriptorCount
feature introduced
by VK_EXT_descriptor_indexing
supported for inline uniform blocks?
RESOLVED: Yes, as long as other inline uniform block specific limits are respected.
6) Do the robustness guarantees of robustBufferAccess
apply to inline
uniform block accesses?
RESOLVED: No, similarly to push constants, as they are not backed by buffer memory like uniform buffers.
Version History
-
Revision 1, 2018-08-01 (Daniel Rakos)
-
Internal revisions
-
VK_EXT_line_rasterization
- Name String
-
VK_EXT_line_rasterization
- Extension Type
-
Device extension
- Registered Extension Number
-
260
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Jeff Bolz jeffbolznv
-
- Last Modified Date
-
2019-05-09
- IP Status
-
No known IP claims.
- Contributors
-
-
Jeff Bolz, NVIDIA
-
Allen Jensen, NVIDIA
-
Jason Ekstrand, Intel
-
This extension adds some line rasterization features that are commonly used in CAD applications and supported in other APIs like OpenGL. Bresenham-style line rasterization is supported, smooth rectangular lines (coverage to alpha) are supported, and stippled lines are supported for all three line rasterization modes.
New Enum Constants
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_LINE_RASTERIZATION_FEATURES_EXT
-
VK_STRUCTURE_TYPE_PIPELINE_RASTERIZATION_LINE_STATE_CREATE_INFO_EXT
-
-
Extending VkDynamicState:
-
VK_DYNAMIC_STATE_LINE_STIPPLE_EXT
-
New Enums
New Structures
New Functions
Issues
(1) Do we need to support Bresenham-style and smooth lines with more than one rasterization sample? i.e. the equivalent of glDisable(GL_MULTISAMPLE) in OpenGL when the framebuffer has more than one sample?
RESOLVED: Yes. For simplicity, Bresenham line rasterization carries forward a few restrictions from OpenGL, such as not supporting per-sample shading, alpha to coverage, or alpha to one.
Version History
-
Revision 1, 2019-05-09 (Jeff Bolz)
-
Initial draft
-
VK_EXT_memory_budget
- Name String
-
VK_EXT_memory_budget
- Extension Type
-
Device extension
- Registered Extension Number
-
238
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Jeff Bolz jeffbolznv
-
- Last Modified Date
-
2018-10-08
- Contributors
-
-
Jeff Bolz, NVIDIA
-
Jeff Juliano, NVIDIA
-
This extension adds support for querying the amount of memory used and the total memory budget for a memory heap. The values returned by this query are implementation-dependent and can depend on a variety of factors including operating system and system load.
The heapBudget
values can be used as a guideline for how much total
memory from each heap the process can use at any given time, before
allocations may start failing or causing performance degradation.
The values may change based on other activity in the system that is outside
the scope and control of the Vulkan implementation.
New Enum Constants
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MEMORY_BUDGET_PROPERTIES_EXT
-
New Enums
None.
New Structures
New Functions
None.
Version History
-
Revision 1, 2018-10-08 (Jeff Bolz)
-
Initial revision
-
VK_EXT_memory_priority
- Name String
-
VK_EXT_memory_priority
- Extension Type
-
Device extension
- Registered Extension Number
-
239
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Jeff Bolz jeffbolznv
-
- Last Modified Date
-
2018-10-08
- Contributors
-
-
Jeff Bolz, NVIDIA
-
Jeff Juliano, NVIDIA
-
This extension adds a priority
value specified at memory allocation
time.
On some systems with both device-local and non-device-local memory heaps,
the implementation may transparently move memory from one heap to another
when a heap becomes full (for example, when the total memory used across all
processes exceeds the size of the heap).
In such a case, this priority value may be used to determine which
allocations are more likely to remain in device-local memory.
New Enum Constants
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MEMORY_PRIORITY_FEATURES_EXT
-
VK_STRUCTURE_TYPE_MEMORY_PRIORITY_ALLOCATE_INFO_EXT
-
New Enums
None.
New Functions
None.
Version History
-
Revision 1, 2018-10-08 (Jeff Bolz)
-
Initial revision
-
VK_EXT_metal_surface
- Name String
-
VK_EXT_metal_surface
- Extension Type
-
Instance extension
- Registered Extension Number
-
218
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_KHR_surface
-
- Contact
-
-
Dzmitry Malyshau kvark
-
- Last Modified Date
-
2018-10-01
- IP Status
-
No known IP claims.
- Contributors
-
-
Dzmitry Malyshau, Mozilla Corp.
-
The VK_EXT_metal_surface
extension is an instance extension.
It provides a mechanism to create a VkSurfaceKHR object (defined by
the VK_KHR_surface
extension) from CAMetalLayer, which is the
native rendering surface of Apple’s Metal framework.
New Object Types
None.
New Enum Constants
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_METAL_SURFACE_CREATE_INFO_EXT
-
New Enums
None.
New Structures
New Functions
Issues
None.
Version History
-
Revision 1, 2018-10-01 (Dzmitry Malyshau)
-
Initial version
-
VK_EXT_pci_bus_info
- Name String
-
VK_EXT_pci_bus_info
- Extension Type
-
Device extension
- Registered Extension Number
-
213
- Revision
-
2
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Matthaeus G. Chajdas anteru
-
- Last Modified Date
-
2018-12-10
- IP Status
-
No known IP claims.
- Contributors
-
-
Matthaeus G. Chajdas, AMD
-
Daniel Rakos, AMD
-
This extension adds a new query to obtain PCI bus information about a physical device.
Not all physical devices have PCI bus information, either due to the device not being connected to the system through a PCI interface or due to platform specific restrictions and policies. Thus this extension is only expected to be supported by physical devices which can provide the information.
As a consequence, applications should always check for the presence of the extension string for each individual physical device for which they intend to issue the new query for and should not have any assumptions about the availability of the extension on any given platform.
New Object Types
None.
New Enum Constants
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PCI_BUS_INFO_PROPERTIES_EXT
-
New Enums
None.
New Structures
New Functions
None.
Issues
None.
Examples
None.
Version History
-
Revision 2, 2018-12-10 (Daniel Rakos)
-
Changed all members of the new structure to have the uint32_t type
-
-
Revision 1, 2018-10-11 (Daniel Rakos)
-
Initial revision
-
VK_EXT_pipeline_creation_feedback
- Name String
-
VK_EXT_pipeline_creation_feedback
- Extension Type
-
Device extension
- Registered Extension Number
-
193
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Jean-Francois Roy jfroy
-
- Last Modified Date
-
2019-03-12
- IP Status
-
No known IP claims.
- Contributors
-
-
Jean-Francois Roy, Google
-
Hai Nguyen, Google
-
Andrew Ellem, Google
-
Bob Fraser, Google
-
Sujeevan Rajayogam, Google
-
Jan-Harald Fredriksen, ARM
-
Jeff Leger, Qualcomm Technologies, Inc.
-
Jeff Bolz, NVIDIA
-
Daniel Koch, NVIDIA
-
Neil Henning, AMD
-
This extension adds a mechanism to provide feedback to an application about pipeline creation, with the specific goal of allowing a feedback loop between build systems and in-the-field application executions to ensure effective pipeline caches are shipped to customers.
New Object Types
None.
New Enum Constants
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PIPELINE_CREATION_FEEDBACK_CREATE_INFO_EXT
-
New Enums
New Functions
None.
Issues
None.
Examples
None.
Version History
-
Revision 1, 2019-03-12 (Jean-Francois Roy)
-
Initial revision
-
VK_EXT_post_depth_coverage
- Name String
-
VK_EXT_post_depth_coverage
- Extension Type
-
Device extension
- Registered Extension Number
-
156
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Daniel Koch dgkoch
-
- Last Modified Date
-
2017-07-17
- Interactions and External Dependencies
-
-
This extension requires the
SPV_KHR_post_depth_coverage
SPIR-V extension. -
This extension requires
GL_ARB_post_depth_coverage
orGL_EXT_post_depth_coverage
for GLSL-based source languages.
-
- Contributors
-
-
Jeff Bolz, NVIDIA
-
This extension adds support for the following SPIR-V extension in Vulkan:
-
SPV_KHR_post_depth_coverage
which allows the fragment shader to control whether values in the
SampleMask
built-in input variable reflect the coverage after the
early per-fragment depth and stencil tests are applied.
This extension adds a new PostDepthCoverage
execution mode under the
SampleMaskPostDepthCoverage
capability.
When this mode is specified along with EarlyFragmentTests
, the value of
an input variable decorated with the
SampleMask
built-in
reflects the coverage after the early fragment
tests are applied.
Otherwise, it reflects the coverage before the depth and stencil tests.
When using GLSL source-based shading languages, the post_depth_coverage
layout qualifier from GL_ARB_post_depth_coverage or
GL_EXT_post_depth_coverage maps to the PostDepthCoverage
execution
mode.
New Object Types
None.
New Enum Constants
None.
New Enums
None.
New Structures
None.
New Functions
None.
New Built-In Variables
None.
New Variable Decoration
None.
New SPIR-V Capabilities
Issues
None yet.
Version History
-
Revision 1, 2017-07-17 (Daniel Koch)
-
Internal revisions
-
VK_EXT_queue_family_foreign
- Name String
-
VK_EXT_queue_family_foreign
- Extension Type
-
Device extension
- Registered Extension Number
-
127
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_KHR_external_memory
-
- Contact
-
-
Chad Versace chadversary
-
- Last Modified Date
-
2017-11-01
- IP Status
-
No known IP claims.
- Contributors
-
-
Chad Versace, Google
-
James Jones, NVIDIA
-
Jason Ekstrand, Intel
-
Jesse Hall, Google
-
Daniel Rakos, AMD
-
Ray Smith, ARM
-
This extension defines a special queue family,
VK_QUEUE_FAMILY_FOREIGN_EXT
, which can be used to transfer ownership
of resources backed by external memory to foreign, external queues.
This is similar to VK_QUEUE_FAMILY_EXTERNAL_KHR
, defined in
VK_KHR_external_memory
.
The key differences between the two are:
-
The queues represented by
VK_QUEUE_FAMILY_EXTERNAL_KHR
must share the same physical device and the same driver version as the current VkInstance.VK_QUEUE_FAMILY_FOREIGN_EXT
has no such restrictions. It can represent devices and drivers from other vendors, and can even represent non-Vulkan-capable devices. -
All resources backed by external memory support
VK_QUEUE_FAMILY_EXTERNAL_KHR
. Support forVK_QUEUE_FAMILY_FOREIGN_EXT
is more restrictive. -
Applications should expect transitions to/from
VK_QUEUE_FAMILY_FOREIGN_EXT
to be more expensive than transitions to/fromVK_QUEUE_FAMILY_EXTERNAL_KHR
.
New Enum Constants
-
Special constants:
-
VK_QUEUE_FAMILY_FOREIGN_EXT
-
Version History
-
Revision 1, 2017-11-01 (Chad Versace)
-
Squashed internal revisions
-
VK_EXT_sample_locations
- Name String
-
VK_EXT_sample_locations
- Extension Type
-
Device extension
- Registered Extension Number
-
144
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Daniel Rakos drakos-amd
-
- Last Modified Date
-
2017-08-02
- Contributors
-
-
Mais Alnasser, AMD
-
Matthaeus G. Chajdas, AMD
-
Maciej Jesionowski, AMD
-
Daniel Rakos, AMD
-
Slawomir Grajewski, Intel
-
Jeff Bolz, NVIDIA
-
Bill Licea-Kane, Qualcomm
-
This extension allows an application to modify the locations of samples within a pixel used in rasterization. Additionally, it allows applications to specify different sample locations for each pixel in a group of adjacent pixels, which can increase antialiasing quality (particularly if a custom resolve shader is used that takes advantage of these different locations).
It is common for implementations to optimize the storage of depth values by storing values that can be used to reconstruct depth at each sample location, rather than storing separate depth values for each sample. For example, the depth values from a single triangle may be represented using plane equations. When the depth value for a sample is needed, it is automatically evaluated at the sample location. Modifying the sample locations causes the reconstruction to no longer evaluate the same depth values as when the samples were originally generated, thus the depth aspect of a depth/stencil attachment must be cleared before rendering to it using different sample locations.
Some implementations may need to evaluate depth image values while performing image layout transitions. To accommodate this, instances of the VkSampleLocationsInfoEXT structure can be specified for each situation where an explicit or automatic layout transition has to take place. VkSampleLocationsInfoEXT can be chained from VkImageMemoryBarrier structures to provide sample locations for layout transitions performed by vkCmdWaitEvents and vkCmdPipelineBarrier calls, and VkRenderPassSampleLocationsBeginInfoEXT can be chained from VkRenderPassBeginInfo to provide sample locations for layout transitions performed implicitly by a render pass instance.
New Object Types
None.
New Enum Constants
-
Extending VkImageCreateFlagBits:
-
VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_SAMPLE_LOCATIONS_INFO_EXT
-
VK_STRUCTURE_TYPE_RENDER_PASS_SAMPLE_LOCATIONS_BEGIN_INFO_EXT
-
VK_STRUCTURE_TYPE_PIPELINE_SAMPLE_LOCATIONS_STATE_CREATE_INFO_EXT
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SAMPLE_LOCATIONS_PROPERTIES_EXT
-
VK_STRUCTURE_TYPE_MULTISAMPLE_PROPERTIES_EXT
-
-
Extending VkDynamicState:
-
VK_DYNAMIC_STATE_SAMPLE_LOCATIONS_EXT
-
New Enums
None.
New Structures
Issues
None.
Version History
-
Revision 1, 2017-08-02 (Daniel Rakos)
-
Internal revisions
-
VK_EXT_sampler_filter_minmax
- Name String
-
VK_EXT_sampler_filter_minmax
- Extension Type
-
Device extension
- Registered Extension Number
-
131
- Revision
-
2
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Jeff Bolz jeffbolznv
-
- Last Modified Date
-
2017-05-19
- IP Status
-
No known IP claims.
- Contributors
-
-
Jeff Bolz, NVIDIA
-
Piers Daniell, NVIDIA
-
In unextended Vulkan, minification and magnification filters such as LINEAR allow sampled image lookups to return a filtered texel value produced by computing a weighted average of a collection of texels in the neighborhood of the texture coordinate provided.
This extension provides a new sampler parameter which allows applications to produce a filtered texel value by computing a component-wise minimum (MIN) or maximum (MAX) of the texels that would normally be averaged. The reduction mode is orthogonal to the minification and magnification filter parameters. The filter parameters are used to identify the set of texels used to produce a final filtered value; the reduction mode identifies how these texels are combined.
New Object Types
None.
New Enum Constants
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SAMPLER_FILTER_MINMAX_PROPERTIES_EXT
-
VK_STRUCTURE_TYPE_SAMPLER_REDUCTION_MODE_CREATE_INFO_EXT
-
-
Extending VkFormatFeatureFlagBits
-
VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_MINMAX_BIT_EXT
-
New Enums
New Functions
None.
New Built-In Variables
None.
New SPIR-V Capabilities
None.
Issues
None.
Examples
None.
Version History
-
Revision 2, 2017-05-19 (Piers Daniell)
-
Renamed to EXT
-
-
Revision 1, 2017-03-25 (Jeff Bolz)
-
Internal revisions
-
VK_EXT_scalar_block_layout
- Name String
-
VK_EXT_scalar_block_layout
- Extension Type
-
Device extension
- Registered Extension Number
-
222
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Tobias Hector tobski
-
- Last Modified Date
-
2018-11-14
- Contributors
-
-
Jeff Bolz
-
Jan-Harald Fredriksen
-
Graeme Leese
-
Jason Ekstrand
-
John Kessenich
-
Short Description
Enables C-like structure layout for SPIR-V blocks.
Description
This extension modifies the alignment rules for uniform buffers, storage buffers and push constants, allowing non-scalar types to be aligned solely based on the size of their components, without additional requirements.
New Enum Constants
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SCALAR_BLOCK_LAYOUT_FEATURES_EXT
-
New Structures
Issues
None.
Version History
-
Revision 1, 2018-11-14 (Tobias Hector)
-
Initial draft
-
VK_EXT_separate_stencil_usage
- Name String
-
VK_EXT_separate_stencil_usage
- Extension Type
-
Device extension
- Registered Extension Number
-
247
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Daniel Rakos drakos-amd
-
- Last Modified Date
-
2018-11-08
- IP Status
-
No known IP claims.
- Contributors
-
-
Daniel Rakos, AMD
-
Jordan Logan, AMD
-
This extension allows specifying separate usage flags for the stencil aspect of images with a depth-stencil format at image creation time.
New Object Types
None.
New Enum Constants
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_IMAGE_STENCIL_USAGE_CREATE_INFO_EXT
-
New Enums
None.
New Structures
New Functions
None.
Issues
None.
Version History
-
Revision 1, 2018-11-08 (Daniel Rakos)
-
Internal revisions.
-
VK_EXT_shader_demote_to_helper_invocation
- Name String
-
VK_EXT_shader_demote_to_helper_invocation
- Extension Type
-
Device extension
- Registered Extension Number
-
277
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Jeff Bolz jeffbolznv
-
- Last Modified Date
-
2019-06-01
- IP Status
-
No known IP claims.
- Contributors
-
-
Jeff Bolz, NVIDIA
-
This extension adds Vulkan support for the
SPV_EXT_demote_to_helper_invocation
SPIR-V extension.
That SPIR-V extension provides a new instruction
OpDemoteToHelperInvocationEXT
allowing shaders to "demote" a fragment
shader invocation to behave like a helper invocation for its duration.
The demoted invocation will have no further side effects and will not output
to the framebuffer, but remains active and can participate in computing
derivatives and in subgroup operations.
This is a better match for the "discard" instruction in HLSL.
New Object Types
None.
New Enum Constants
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_DEMOTE_TO_HELPER_INVOCATION_FEATURES_EXT
-
New Enums
None.
New Structures
New Functions
None.
New SPIR-V Capability
Issues
None.
Examples
None.
Version History
-
Revision 1, 2019-06-01 (Jeff Bolz)
-
Initial draft
-
VK_EXT_shader_stencil_export
- Name String
-
VK_EXT_shader_stencil_export
- Extension Type
-
Device extension
- Registered Extension Number
-
141
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Dominik Witczak dominikwitczakamd
-
- Last Modified Date
-
2017-07-19
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
Requires the
SPV_EXT_shader_stencil_export
SPIR-V extension.
-
- Contributors
-
-
Dominik Witczak, AMD
-
Daniel Rakos, AMD
-
Rex Xu, AMD
-
This extension adds support for the SPIR-V extension
SPV_EXT_shader_stencil_export
, providing a mechanism whereby a shader may
generate the stencil reference value per invocation.
When stencil testing is enabled, this allows the test to be performed
against the value generated in the shader.
Version History
-
Revision 1, 2017-07-19 (Dominik Witczak)
-
Initial draft
-
VK_EXT_shader_subgroup_ballot
- Name String
-
VK_EXT_shader_subgroup_ballot
- Extension Type
-
Device extension
- Registered Extension Number
-
65
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Daniel Koch dgkoch
-
- Last Modified Date
-
2016-11-28
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
This extension requires the
SPV_KHR_shader_ballot
SPIR-V extension. -
This extension requires the
GL_ARB_shader_ballot
extension for GLSL source languages.
-
- Contributors
-
-
Jeff Bolz, NVIDIA
-
Neil Henning, Codeplay
-
Daniel Koch, NVIDIA Corporation
-
This extension adds support for the following SPIR-V extension in Vulkan:
-
SPV_KHR_shader_ballot
This extension provides the ability for a group of invocations, which execute in parallel, to do limited forms of cross-invocation communication via a group broadcast of a invocation value, or broadcast of a bitarray representing a predicate value from each invocation in the group.
This extension provides access to a number of additional built-in shader variables in Vulkan:
-
SubgroupEqMaskKHR
, which contains the subgroup mask of the current subgroup invocation, -
SubgroupGeMaskKHR
, which contains the subgroup mask of the invocations greater than or equal to the current invocation, -
SubgroupGtMaskKHR
, which contains the subgroup mask of the invocations greater than the current invocation, -
SubgroupLeMaskKHR
, which contains the subgroup mask of the invocations less than or equal to the current invocation, -
SubgroupLtMaskKHR
, which contains the subgroup mask of the invocations less than the current invocation, -
SubgroupLocalInvocationId
, which contains the index of an invocation within a subgroup, and -
SubgroupSize
, which contains the maximum number of invocations in a subgroup.
Additionally, this extension provides access to the new SPIR-V instructions:
-
OpSubgroupBallotKHR
, -
OpSubgroupFirstInvocationKHR
, and -
OpSubgroupReadInvocationKHR
,
When using GLSL source-based shader languages, the following variables and shader functions from GL_ARB_shader_ballot can map to these SPIR-V built-in decorations and instructions:
-
in uint64_t gl_SubGroupEqMaskARB;
→SubgroupEqMaskKHR
, -
in uint64_t gl_SubGroupGeMaskARB;
→SubgroupGeMaskKHR
, -
in uint64_t gl_SubGroupGtMaskARB;
→SubgroupGtMaskKHR
, -
in uint64_t gl_SubGroupLeMaskARB;
→SubgroupLeMaskKHR
, -
in uint64_t gl_SubGroupLtMaskARB;
→SubgroupLtMaskKHR
, -
in uint gl_SubGroupInvocationARB;
→SubgroupLocalInvocationId
, -
uniform uint gl_SubGroupSizeARB;
→SubgroupSize
, -
ballotARB
() →OpSubgroupBallotKHR
, -
readFirstInvocationARB
() →OpSubgroupFirstInvocationKHR
, and -
readInvocationARB
() →OpSubgroupReadInvocationKHR
.
New Object Types
None.
New Enum Constants
None.
New Enums
None.
New Structures
None.
New Functions
None.
New Built-In Variables
New SPIR-V Capabilities
Issues
None.
Version History
-
Revision 1, 2016-11-28 (Daniel Koch)
-
Initial draft
-
VK_EXT_shader_subgroup_vote
- Name String
-
VK_EXT_shader_subgroup_vote
- Extension Type
-
Device extension
- Registered Extension Number
-
66
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Daniel Koch dgkoch
-
- Last Modified Date
-
2016-11-28
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
This extension requires the
SPV_KHR_subgroup_vote
SPIR-V extension. -
This extension requires the
GL_ARB_shader_group_vote
extension for GLSL source languages.
-
- Contributors
-
-
Neil Henning, Codeplay
-
Daniel Koch, NVIDIA Corporation
-
This extension adds support for the following SPIR-V extension in Vulkan:
-
SPV_KHR_subgroup_vote
This extension provides new SPIR-V instructions:
-
OpSubgroupAllKHR
, -
OpSubgroupAnyKHR
, and -
OpSubgroupAllEqualKHR
.
to compute the composite of a set of boolean conditions across a group of shader invocations that are running concurrently (a subgroup). These composite results may be used to execute shaders more efficiently on a VkPhysicalDevice.
When using GLSL source-based shader languages, the following shader functions from GL_ARB_shader_group_vote can map to these SPIR-V instructions:
-
anyInvocationARB
() →OpSubgroupAnyKHR
, -
allInvocationsARB
() →OpSubgroupAllKHR
, and -
allInvocationsEqualARB
() →OpSubgroupAllEqualKHR
.
The subgroup across which the boolean conditions are evaluated is implementation-dependent, and this extension provides no guarantee over how individual shader invocations are assigned to subgroups. In particular, a subgroup has no necessary relationship with the compute shader local workgroup — any pair of shader invocations in a compute local workgroup may execute in different subgroups as used by these instructions.
Compute shaders operate on an explicitly specified group of threads (a local workgroup), but many implementations will also group non-compute shader invocations and execute them concurrently. When executing code like
if (condition) {
result = do_fast_path();
} else {
result = do_general_path();
}
where condition
diverges between invocations, an implementation might
first execute do_fast_path
() for the invocations where condition
is true and leave the other invocations dormant.
Once do_fast_path
() returns, it might call do_general_path
() for
invocations where condition
is false
and leave the other
invocations dormant.
In this case, the shader executes both the fast and the general path and
might be better off just using the general path for all invocations.
This extension provides the ability to avoid divergent execution by evaluating a condition across an entire subgroup using code like:
if (allInvocationsARB(condition)) {
result = do_fast_path();
} else {
result = do_general_path();
}
The built-in function allInvocationsARB
() will return the same value
for all invocations in the group, so the group will either execute
do_fast_path
() or do_general_path
(), but never both.
For example, shader code might want to evaluate a complex function
iteratively by starting with an approximation of the result and then
refining the approximation.
Some input values may require a small number of iterations to generate an
accurate result (do_fast_path
) while others require a larger number
(do_general_path
).
In another example, shader code might want to evaluate a complex function
(do_general_path
) that can be greatly simplified when assuming a
specific value for one of its inputs (do_fast_path
).
New Object Types
None.
New Enum Constants
None.
New Enums
None.
New Structures
None.
New Functions
None.
New Built-In Variables
None.
New SPIR-V Capabilities
Issues
None.
Version History
-
Revision 1, 2016-11-28 (Daniel Koch)
-
Initial draft
-
VK_EXT_shader_viewport_index_layer
- Name String
-
VK_EXT_shader_viewport_index_layer
- Extension Type
-
Device extension
- Registered Extension Number
-
163
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Daniel Koch dgkoch
-
- Last Modified Date
-
2017-08-08
- Interactions and External Dependencies
-
-
This extension requires the
SPV_EXT_shader_viewport_index_layer
SPIR-V extension. -
This extension requires the
GL_ARB_shader_viewport_layer_array
,GL_AMD_vertex_shader_layer
,GL_AMD_vertex_shader_viewport_index
, orGL_NV_viewport_array2
extensions for GLSL source languages. -
This extension requires the
multiViewport
feature. -
This extension interacts with the
tessellationShader
feature.
-
- Contributors
-
-
Piers Daniell, NVIDIA
-
Jeff Bolz, NVIDIA
-
Jan-Harald Fredriksen, ARM
-
Daniel Rakos, AMD
-
Slawomir Grajeswki, Intel
-
This extension adds support for the ShaderViewportIndexLayerEXT
capability from the SPV_EXT_shader_viewport_index_layer
extension in
Vulkan.
This extension allows variables decorated with the Layer
and
ViewportIndex
built-ins to be exported from vertex or tessellation
shaders, using the ShaderViewportIndexLayerEXT
capability.
When using GLSL source-based shading languages, the gl_ViewportIndex
and gl_Layer
built-in variables map to the SPIR-V ViewportIndex
and Layer
built-in decorations, respectively.
Behaviour of these variables is extended as described in the
GL_ARB_shader_viewport_layer_array
(or the precursor
GL_AMD_vertex_shader_layer
, GL_AMD_vertex_shader_viewport_index
, and
GL_NV_viewport_array2
extensions).
Note
The |
New Object Types
None.
New Enum Constants
None.
New Enums
None.
New Structures
None.
New Functions
None.
New or Modified Built-In Variables
-
(modified)
Layer
-
(modified)
ViewportIndex
New Variable Decoration
None.
New SPIR-V Capabilities
Issues
None yet!
Version History
-
Revision 1, 2017-08-08 (Daniel Koch)
-
Internal drafts
-
VK_EXT_subgroup_size_control
- Name String
-
VK_EXT_subgroup_size_control
- Extension Type
-
Device extension
- Registered Extension Number
-
226
- Revision
-
2
- Extension and Version Dependencies
-
-
Requires Vulkan 1.1
-
- Contact
-
-
Neil Henning sheredom
-
- Last Modified Date
-
2019-03-05
- Contributors
-
-
Jeff Bolz, NVIDIA
-
Jason Ekstrand, Intel
-
Sławek Grajewski, Intel
-
Jesse Hall, Google
-
Neil Henning, AMD
-
Daniel Koch, NVIDIA
-
Jeff Leger, Qualcomm
-
Graeme Leese, Broadcom
-
Allan MacKinnon, Google
-
Mariusz Merecki, Intel
-
Graham Wihlidal, Electronic Arts
-
Short Description
Enables an implementation to control the subgroup size by allowing a varying subgroup size and also specifying a required subgroup size.
Description
This extension extends the subgroup support in Vulkan 1.1 to allow an implementation to expose a varying subgroup size. Previously Vulkan exposed a single subgroup size per physical device, with the expectation that implementations will behave as if all subgroups have the same size. Some implementations may dispatch shaders with a varying subgroup size for different subgroups. As a result they could implicitly split a large subgroup into smaller subgroups or represent a small subgroup as a larger subgroup, some of whose invocations were inactive on launch.
To aid developers in understanding the performance characteristics of their
programs, this extension exposes a minimum and maximum subgroup size that a
physical device supports and a pipeline create flag to enable that pipeline
to vary its subgroup size.
If enabled, any SubgroupSize
decorated variables in the SPIR-V shader
modules provided to pipeline creation may vary between the
minimum and
maximum subgroup sizes.
An implementation is also optionally allowed to support specifying a
required subgroup size for a given pipeline stage.
Implementations advertise which stages support a required subgroup size, and any pipeline of a supported
stage can be passed a
VkPipelineShaderStageRequiredSubgroupSizeCreateInfoEXT structure to
set the subgroup size for that shader stage of the pipeline.
For compute shaders, this requires the developer to query the
maxComputeWorkgroupSubgroups
and ensure that:
Developers can also specify a new pipeline shader stage create flag that requires the implementation to have fully populated subgroups within local workgroups. This requires the workgroup size in the X dimension to be a multiple of the subgroup size.
New Enum Constants
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SUBGROUP_SIZE_CONTROL_FEATURES_EXT
(added in version 2) -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SUBGROUP_SIZE_CONTROL_PROPERTIES_EXT
-
VK_STRUCTURE_TYPE_PIPELINE_SHADER_STAGE_REQUIRED_SUBGROUP_SIZE_CREATE_INFO_EXT
-
-
Extending VkPipelineShaderStageCreateFlagBits:
-
VK_PIPELINE_SHADER_STAGE_CREATE_ALLOW_VARYING_SUBGROUP_SIZE_BIT_EXT
-
VK_PIPELINE_SHADER_STAGE_CREATE_REQUIRE_FULL_SUBGROUPS_BIT_EXT
-
New Structures
Issues
None.
Version History
-
Revision 1, 2019-03-05 (Neil Henning)
-
Initial draft
-
-
Revision 2, 2019-07-26 (Jason Ekstrand)
-
Add the missing VkPhysicalDeviceSubgroupSizeControlFeaturesEXT for querying subgroup size control features.
-
VK_EXT_swapchain_colorspace
- Name String
-
VK_EXT_swapchain_colorspace
- Extension Type
-
Instance extension
- Registered Extension Number
-
105
- Revision
-
4
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_KHR_surface
-
- Contact
-
-
Courtney Goeltzenleuchter courtney-g
-
- Last Modified Date
-
2019-04-26
- IP Status
-
No known IP claims.
- Contributors
-
-
Courtney Goeltzenleuchter, Google
-
New Enum Constants
-
Extending VkColorSpaceKHR:
-
VK_COLOR_SPACE_DISPLAY_P3_NONLINEAR_EXT
- supports the Display-P3 color space and applies an sRGB-like transfer function. -
VK_COLOR_SPACE_EXTENDED_SRGB_LINEAR_EXT
- supports the extended sRGB color space and applies a linear transfer function. -
VK_COLOR_SPACE_EXTENDED_SRGB_NONLINEAR_EXT
- supports the extended sRGB color space with an sRGB nonlinear transfer function. -
VK_COLOR_SPACE_DCI_P3_LINEAR_EXT
- supports the DCI-P3 color space and applies a linear OETF. -
VK_COLOR_SPACE_DCI_P3_NONLINEAR_EXT
- supports the DCI-P3 color space and applies the Gamma 2.6 OETF. -
VK_COLOR_SPACE_BT709_LINEAR_EXT
- supports the BT709 color space and applies a linear transfer function. -
VK_COLOR_SPACE_BT709_NONLINEAR_EXT
- supports the BT709 color space and applies the SMPTE 170M OETF. -
VK_COLOR_SPACE_BT2020_LINEAR_EXT
- supports the BT2020 color space and applies a linear OETF. -
VK_COLOR_SPACE_HDR10_ST2084_EXT
- supports HDR10 (BT2020 color space and applies the SMPTE ST2084 Perceptual Quantizer (PQ) OETF). -
VK_COLOR_SPACE_DOLBYVISION_EXT
- supports Dolby Vision (BT2020 color space, proprietary encoding, and applies the SMPTE ST2084 OETF). -
VK_COLOR_SPACE_HDR10_HLG_EXT
- supports HDR10 (BT2020 color space and applies the Hybrid Log Gamma (HLG) OETF). -
VK_COLOR_SPACE_ADOBERGB_LINEAR_EXT
- supports the AdobeRGB color space and applies a linear OETF. -
VK_COLOR_SPACE_ADOBERGB_NONLINEAR_EXT
- supports the AdobeRGB color space and applies the Gamma 2.2 OETF. -
VK_COLOR_SPACE_PASS_THROUGH_EXT
- color components used “as is”. Intended to allow application to supply data for color spaces not described here.
-
Issues
1) Does the spec need to specify which kinds of image formats support the color spaces?
RESOLVED: Pixel format is independent of color space (though some color spaces really want / need floating point color components to be useful). Therefore, do not plan on documenting what formats support which colorspaces. An application can call vkGetPhysicalDeviceSurfaceFormatsKHR to query what a particular implementation supports.
2) How does application determine if HW supports appropriate transfer function for a colorspace?
RESOLVED: Extension indicates that implementation must not do the OETF encoding if it is not sRGB. That responsibility falls to the application shaders. Any other native OETF / EOTF functions supported by an implementation can be described by separate extension.
Version History
-
Revision 1, 2016-12-27 (Courtney Goeltzenleuchter)
-
Initial version
-
-
Revision 2, 2017-01-19 (Courtney Goeltzenleuchter)
-
Add pass through and multiple options for BT2020.
-
Clean up some issues with equations not displaying properly.
-
-
Revision 3, 2017-06-23 (Courtney Goeltzenleuchter)
-
Add extended sRGB non-linear enum.
-
-
Revision 4, 2019-04-26 (Graeme Leese)
-
Clarify colorspace transfer function usage.
-
Refer to normative definitions in the Data Format Specification.
-
Clarify DCI-P3 and Display P3 usage.
-
VK_EXT_texel_buffer_alignment
- Name String
-
VK_EXT_texel_buffer_alignment
- Extension Type
-
Device extension
- Registered Extension Number
-
282
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Jeff Bolz jeffbolznv
-
- Last Modified Date
-
2019-06-06
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
- Contributors
-
-
Jeff Bolz, NVIDIA
-
This extension adds more expressive alignment requirements for uniform and
storage texel buffers.
Some implementations have single texel alignment requirements that can’t be
expressed via
VkPhysicalDeviceLimits::minTexelBufferOffsetAlignment
.
New Enum Constants
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_TEXEL_BUFFER_ALIGNMENT_FEATURES_EXT
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_TEXEL_BUFFER_ALIGNMENT_PROPERTIES_EXT
-
New Enums
None.
New Structures
New Functions
None.
Issues
Version History
-
Revision 1, 2019-06-06 (Jeff Bolz)
-
Initial draft
-
VK_EXT_texture_compression_astc_hdr
- Name String
-
VK_EXT_texture_compression_astc_hdr
- Extension Type
-
Device extension
- Registered Extension Number
-
67
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Jan-Harald Fredriksen janharaldfredriksen-arm
-
- Last Modified Date
-
2019-05-28
- IP Status
-
No known issues.
- Contributors
-
-
Jan-Harald Fredriksen, Arm
-
This extension adds support for textures compressed using the Adaptive Scalable Texture Compression (ASTC) High Dynamic Range (HDR) profile.
When this extension is enabled, the HDR profile is supported for all ASTC formats listed in ASTC Compressed Image Formats.
New Object Types
None.
New Enum Constants
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_TEXTURE_COMPRESSION_ASTC_HDR_FEATURES_EXT
-
-
Extending VkFormat:
-
VK_FORMAT_ASTC_4x4_SFLOAT_BLOCK_EXT
-
VK_FORMAT_ASTC_5x4_SFLOAT_BLOCK_EXT
-
VK_FORMAT_ASTC_5x5_SFLOAT_BLOCK_EXT
-
VK_FORMAT_ASTC_6x5_SFLOAT_BLOCK_EXT
-
VK_FORMAT_ASTC_6x6_SFLOAT_BLOCK_EXT
-
VK_FORMAT_ASTC_8x5_SFLOAT_BLOCK_EXT
-
VK_FORMAT_ASTC_8x6_SFLOAT_BLOCK_EXT
-
VK_FORMAT_ASTC_8x8_SFLOAT_BLOCK_EXT
-
VK_FORMAT_ASTC_10x5_SFLOAT_BLOCK_EXT
-
VK_FORMAT_ASTC_10x6_SFLOAT_BLOCK_EXT
-
VK_FORMAT_ASTC_10x8_SFLOAT_BLOCK_EXT
-
VK_FORMAT_ASTC_10x10_SFLOAT_BLOCK_EXT
-
VK_FORMAT_ASTC_12x10_SFLOAT_BLOCK_EXT
-
VK_FORMAT_ASTC_12x12_SFLOAT_BLOCK_EXT
-
New Enums
None.
New Structures
New Functions
None.
Issues
1) Should we add a feature or limit for this functionality?
Yes. It is consistent with the ASTC LDR support to add a feature like textureCompressionASTC_HDR.
The feature is strictly speaking redundant as long as this is just an extension; it would be be sufficient to just enable the extension. But adding the feature is more forward-looking if wanted to make this an optional core feature in the future.
2) Should we introduce new format enums for HDR?
Yes.
Vulkan 1.0 describes the ASTC format enums as UNORM, e.g.
VK_FORMAT_ASTC_4x4_UNORM_BLOCK
, so it’s confusing to make these
contain HDR data.
Note that the OpenGL (ES) extensions did not make this distinction because a
single ASTC HDR texture may contain both unorm and float blocks.
Implementations may not be able to distinguish between LDR and HDR ASTC
textures internally and just treat them as the same format, i.e. if this
extension is supported then sampling from a
VK_FORMAT_ASTC_4x4_UNORM_BLOCK
image format may return HDR results.
Applications can get predictable results by using the appropriate image
format.
Version History
-
Revision 1, 2019-05-28 (Jan-Harald Fredriksen)
-
Initial version
-
VK_EXT_tooling_info
- Name String
-
VK_EXT_tooling_info
- Extension Type
-
Device extension
- Registered Extension Number
-
246
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Tobias Hector tobski
-
- Last Modified Date
-
2018-11-05
- Contributors
-
-
Rolando Caloca
-
Matthaeus Chajdas
-
Baldur Karlsson
-
Daniel Rakos
-
When an error occurs during application development, a common question is "What tools are actually running right now?" This extension adds the ability to query that information directly from the Vulkan implementation.
Outdated versions of one tool might not play nicely with another, or perhaps a tool is not actually running when it should have been. Trying to figure that out can cause headaches as it’s necessary to consult each known tool to figure out what’s going on - in some cases the tool might not even be known.
Typically, the expectation is that developers will simply print out this information for visual inspection when an issue occurs, however a small amount of semantic information about what the tool is doing is provided to help identify it programmatically. For example, if the advertised limits or features of an implementation are unexpected, is there a tool active which modifies these limits? Or if an application is providing debug markers, but the implementation is not actually doing anything with that information, this can quickly point that out.
New Enum Constants
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_TOOL_PROPERTIES_EXT
-
New Enums
New Structures
New Functions
Examples
uint32_t num_tools;
VkPhysicalDeviceToolPropertiesEXT *pToolProperties;
vkGetPhysicalDeviceToolPropertiesEXT(physicalDevice, &num_tools, NULL);
pToolProperties = (VkPhysicalDeviceToolPropertiesEXT*)malloc(sizeof(VkPhysicalDeviceToolPropertiesEXT) * num_tools);
vkGetPhysicalDeviceToolPropertiesEXT(physicalDevice, &num_tools, pToolProperties);
for (int i = 0; i < num_tools; ++i) {
printf("%s:\n", pToolProperties[i].name);
printf("Version:\n");
printf("%s:\n", pToolProperties[i].version);
printf("Description:\n");
printf("\t%s\n", pToolProperties[i].description);
printf("Purposes:\n");
printf("\t%s\n", VkToolPurposeFlagBitsEXT_to_string(pToolProperties[i].purposes));
if (strnlen_s(pToolProperties[i].layer,VK_MAX_EXTENSION_NAME_SIZE) > 0) {
printf("Corresponding Layer:\n");
printf("\t%s\n", pToolProperties[i].layer);
}
}
Issues
1) Why is this information separate from the layer mechanism?
Some tooling may be built into a driver, or be part of the Vulkan loader etc. - and so tying this information directly to layers would’ve been awkward at best.
Version History
-
Revision 1, 2018-11-05 (Tobias Hector)
-
Initial draft
-
VK_EXT_transform_feedback
- Name String
-
VK_EXT_transform_feedback
- Extension Type
-
Device extension
- Registered Extension Number
-
29
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Piers Daniell pdaniell-nv
-
- Last Modified Data
-
2018-10-09
- Contributors
-
-
Baldur Karlsson, Valve
-
Boris Zanin, Mobica
-
Daniel Rakos, AMD
-
Donald Scorgie, Imagination
-
Henri Verbeet, CodeWeavers
-
Jan-Harald Fredriksen, Arm
-
Jason Ekstrand, Intel
-
Jeff Bolz, NVIDIA
-
Jesse Barker, Unity
-
Jesse Hall, Google
-
Pierre-Loup Griffais, Valve
-
Philip Rebohle, DXVK
-
Ruihao Zhang, Qualcomm
-
Samuel Pitoiset, Valve
-
Slawomir Grajewski, Intel
-
Stu Smith, Imagination Technologies
-
This extension adds transform feedback to the Vulkan API by exposing the
SPIR-V TransformFeedback
and GeometryStreams
capabilities to
capture vertex, tessellation or geometry shader outputs to one or more
buffers.
It adds API functionality to bind transform feedback buffers to capture the
primitives emitted by the graphics pipeline from SPIR-V outputs decorated
for transform feedback.
The transform feedback capture can be paused and resumed by way of storing
and retrieving a byte counter.
The captured data can be drawn again where the vertex count is derived from
the byte counter without CPU intervention.
If the implementation is capable, a vertex stream other than zero can be
rasterized.
All these features are designed to match the full capabilities of OpenGL core transform feedback functionality and beyond. Many of the features are optional to allow base OpenGL ES GPUs to also implement this extension.
The primary purpose of the functionality exposed by this extension is to support translation layers from other 3D APIs. This functionality is not considered forward looking, and is not expected to be promoted to a KHR extension or to core Vulkan. Unless this is needed for translation, it is recommended that developers use alternative techniques of using the GPU to process and capture vertex data.
New Object Types
None.
New Enum Constants
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_TRANSFORM_FEEDBACK_FEATURES_EXT
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_TRANSFORM_FEEDBACK_PROPERTIES_EXT
-
VK_STRUCTURE_TYPE_PIPELINE_RASTERIZATION_STATE_STREAM_CREATE_INFO_EXT
-
-
Extending VkQueryType:
-
VK_QUERY_TYPE_TRANSFORM_FEEDBACK_STREAM_EXT
-
-
Extending VkBufferUsageFlagBits:
-
VK_BUFFER_USAGE_TRANSFORM_FEEDBACK_BUFFER_BIT_EXT
-
VK_BUFFER_USAGE_TRANSFORM_FEEDBACK_COUNTER_BUFFER_BIT_EXT
-
-
Extending VkAccessFlagBits:
-
VK_ACCESS_TRANSFORM_FEEDBACK_WRITE_BIT_EXT
-
VK_ACCESS_TRANSFORM_FEEDBACK_COUNTER_READ_BIT_EXT
-
VK_ACCESS_TRANSFORM_FEEDBACK_COUNTER_WRITE_BIT_EXT
-
-
Extending VkPipelineStageFlagBits:
-
VK_PIPELINE_STAGE_TRANSFORM_FEEDBACK_BIT_EXT
-
New Structures
New Functions
Issues
1) Should we include pause/resume functionality?
RESOLVED: Yes, this is needed to ease layering other APIs which have this
functionality.
To pause use vkCmdEndTransformFeedbackEXT
and provide valid buffer
handles in the pCounterBuffers
array and offsets in the
pCounterBufferOffsets
array for the implementation to save the resume
points.
Then to resume use vkCmdBeginTransformFeedbackEXT
with the previous
pCounterBuffers
and pCounterBufferOffsets
values.
Between the pause and resume there needs to be a memory barrier for the
counter buffers with a source access of
VK_ACCESS_TRANSFORM_FEEDBACK_COUNTER_WRITE_BIT_EXT
at pipeline stage
VK_PIPELINE_STAGE_TRANSFORM_FEEDBACK_BIT_EXT
to a destination access
of VK_ACCESS_TRANSFORM_FEEDBACK_COUNTER_READ_BIT_EXT
at pipeline stage
VK_PIPELINE_STAGE_DRAW_INDIRECT_BIT
.
2) How does this interact with multiview?
RESOLVED: Transform feedback cannot be made active in a render pass with multiview enabled.
3) How should queries be done?
RESOLVED: There is a new query type
VK_QUERY_TYPE_TRANSFORM_FEEDBACK_STREAM_EXT
.
A query pool created with this type will capture 2 integers -
numPrimitivesWritten and numPrimitivesNeeded - for the specified vertex
stream output from the last vertex processing stage.
The vertex stream output queried is zero by default, but can be specified
with the new vkCmdBeginQueryIndexedEXT
and
vkCmdEndQueryIndexedEXT
commands.
Version History
-
Revision 1, 2018-10-09 (Piers Daniell)
-
Internal revisions
-
VK_EXT_validation_cache
- Name String
-
VK_EXT_validation_cache
- Extension Type
-
Device extension
- Registered Extension Number
-
161
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Cort Stratton cdwfs
-
- Last Modified Date
-
2017-08-29
- IP Status
-
No known IP claims.
- Contributors
-
-
Cort Stratton, Google
-
Chris Forbes, Google
-
This extension provides a mechanism for caching the results of potentially expensive internal validation operations across multiple runs of a Vulkan application. At the core is the VkValidationCacheEXT object type, which is managed similarly to the existing VkPipelineCache.
The new struct VkShaderModuleValidationCacheCreateInfoEXT can be
included in the pNext
chain at vkCreateShaderModule time.
It contains a VkValidationCacheEXT to use when validating the
VkShaderModule.
New Object Types
New Enum Constants
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_VALIDATION_CACHE_CREATE_INFO_EXT
-
VK_STRUCTURE_TYPE_SHADER_MODULE_VALIDATION_CACHE_CREATE_INFO_EXT
-
New Functions
Issues
None.
Version History
-
Revision 1, 2017-08-29 (Cort Stratton)
-
Initial draft
-
VK_EXT_validation_features
- Name String
-
VK_EXT_validation_features
- Extension Type
-
Instance extension
- Registered Extension Number
-
248
- Revision
-
2
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Karl Schultz karl-lunarg
-
- Last Modified Date
-
2018-11-14
- IP Status
-
No known IP claims.
- Contributors
-
-
Karl Schultz, LunarG
-
Dave Houlton, LunarG
-
Mark Lobodzinski, LunarG
-
Camden Stocker, LunarG
-
This extension provides the VkValidationFeaturesEXT struct that can be
included in the pNext
chain of the VkInstanceCreateInfo
structure passed as the pCreateInfo
parameter of
vkCreateInstance.
The structure contains an array of VkValidationFeatureEnableEXT enum
values that enable specific validation features that are disabled by
default.
The structure also contains an array of VkValidationFeatureDisableEXT
enum values that disable specific validation layer features that are enabled
by default.
Note
The |
New Enum Constants
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_VALIDATION_FEATURES_EXT
-
New Structures
New Functions
None.
Issues
None.
Version History
-
Revision 1, 2018-11-14 (Karl Schultz)
-
Initial revision
-
-
Revision 2, 2019-08-06 (Mark Lobodzinski)
-
Add Best Practices enable
-
VK_EXT_vertex_attribute_divisor
- Name String
-
VK_EXT_vertex_attribute_divisor
- Extension Type
-
Device extension
- Registered Extension Number
-
191
- Revision
-
3
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Vikram Kushwaha vkushwaha
-
- Last Modified Date
-
2018-08-03
- IP Status
-
No known IP claims.
- Contributors
-
-
Vikram Kushwaha, NVIDIA
-
Jason Ekstrand, Intel
-
This extension allows instance-rate vertex attributes to be repeated for certain number of instances instead of advancing for every instance when instanced rendering is enabled.
New Object Types
None.
New Enum Constants
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VERTEX_ATTRIBUTE_DIVISOR_PROPERTIES_EXT
-
VK_STRUCTURE_TYPE_PIPELINE_VERTEX_INPUT_DIVISOR_STATE_CREATE_INFO_EXT
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VERTEX_ATTRIBUTE_DIVISOR_FEATURES_EXT
New Enums
None.
New Structures
New Functions
None.
Issues
1) What is the effect of a non-zero value for firstInstance
?
RESOLVED: The Vulkan API should follow the OpenGL convention and offset
attribute fetching by firstInstance
while computing vertex attribute
offsets.
2) Should zero be an allowed divisor?
RESOLVED: Yes. A zero divisor means the vertex attribute is repeated for all instances.
Examples
To create a vertex binding such that the first binding uses instanced rendering and the same attribute is used for every 4 draw instances, an application could use the following set of structures:
const VkVertexInputBindingDivisorDescriptionEXT divisorDesc =
{
0,
4
};
const VkPipelineVertexInputDivisorStateCreateInfoEXT divisorInfo =
{
VK_STRUCTURE_TYPE_PIPELINE_VERTEX_INPUT_DIVISOR_STATE_CREATE_INFO_EXT, // sType
NULL, // pNext
1, // vertexBindingDivisorCount
&divisorDesc // pVertexBindingDivisors
}
const VkVertexInputBindingDescription binding =
{
0, // binding
sizeof(Vertex), // stride
VK_VERTEX_INPUT_RATE_INSTANCE // inputRate
};
const VkPipelineVertexInputStateCreateInfo viInfo =
{
VK_STRUCTURE_TYPE_PIPELINE_VERTEX_INPUT_CREATE_INFO, // sType
&divisorInfo, // pNext
...
};
//...
Version History
-
Revision 1, 2017-12-04 (Vikram Kushwaha)
-
First Version
-
-
Revision 2, 2018-07-16 (Jason Ekstrand)
-
Adjust the interaction between
divisor
andfirstInstance
to match the OpenGL convention. -
Disallow divisors of zero.
-
-
Revision 3, 2018-08-03 (Vikram Kushwaha)
-
Allow a zero divisor.
-
Add a physical device features structure to query/enable this feature.
-
VK_EXT_ycbcr_image_arrays
- Name String
-
VK_EXT_ycbcr_image_arrays
- Extension Type
-
Device extension
- Registered Extension Number
-
253
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_KHR_sampler_ycbcr_conversion
-
- Contact
-
-
Piers Daniell pdaniell-nv
-
- Last Modified Date
-
2019-01-15
- Contributors
-
-
Piers Daniell, NVIDIA
-
This extension allows images of a format that requires Y’CBCR conversion to be created with multiple array layers, which is otherwise restricted.
New Enum Constants
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_YCBCR_IMAGE_ARRAYS_FEATURES_EXT
-
New Enums
None.
New Structures
New Functions
None.
Version History
-
Revision 1, 2019-01-15 (Piers Daniell)
-
Initial revision
-
VK_AMD_buffer_marker
- Name String
-
VK_AMD_buffer_marker
- Extension Type
-
Device extension
- Registered Extension Number
-
180
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Daniel Rakos drakos-amd
-
- Last Modified Date
-
2018-01-26
- IP Status
-
No known IP claims.
- Contributors
-
-
Matthaeus G. Chajdas, AMD
-
Jaakko Konttinen, AMD
-
Daniel Rakos, AMD
-
This extension adds a new operation to execute pipelined writes of small
marker values into a VkBuffer
object.
The primary purpose of these markers is to facilitate the development of debugging tools for tracking which pipelined command contributed to device loss.
New Object Types
None.
New Enum Constants
None.
New Enums
None.
New Structures
None.
New Functions
Examples
None.
Version History
-
Revision 1, 2018-01-26 (Jaakko Konttinen)
-
Initial revision
-
VK_AMD_device_coherent_memory
- Name String
-
VK_AMD_device_coherent_memory
- Extension Type
-
Device extension
- Registered Extension Number
-
230
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Tobias Hector tobski
-
- Last Modified Date
-
2019-02-04
- Contributors
-
-
Ping Fu, AMD
-
Timothy Lottes, AMD
-
Tobias Hector, AMD
-
This extension adds the device coherent and device uncached memory types. Any device accesses to device coherent memory are automatically made visible to any other device access. Device uncached memory indicates to applications that caches are disabled for a particular memory type, which guarantees device coherence.
Device coherent and uncached memory are expected to have lower performance for general access than non-device coherent memory, but can be useful in certain scenarios; particularly so for debugging.
New Enum Constants
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_COHERENT_MEMORY_FEATURES_AMD
-
-
Extending VkMemoryPropertyFlagBits:
-
VK_MEMORY_PROPERTY_DEVICE_COHERENT_BIT_AMD
-
VK_MEMORY_PROPERTY_DEVICE_UNCACHED_BIT_AMD
-
Version History
-
Revision 1, 2019-02-04 (Tobias Hector)
-
Initial revision
-
VK_AMD_display_native_hdr
- Name String
-
VK_AMD_display_native_hdr
- Extension Type
-
Device extension
- Registered Extension Number
-
214
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_KHR_get_surface_capabilities2
-
Requires
VK_KHR_swapchain
-
- Contact
-
-
Matthaeus G. Chajdas anteru
-
- Last Modified Date
-
2018-12-18
- IP Status
-
No known IP claims.
- Contributors
-
-
Matthaeus G. Chajdas, AMD
-
Aaron Hagan, AMD
-
Aric Cyr, AMD
-
Timothy Lottes, AMD
-
Derrick Owens, AMD
-
Daniel Rakos, AMD
-
This extension introduces the following display native HDR features to Vulkan:
-
A new VkColorSpaceKHR enum for setting the native display colorspace. For example, this color space would be set by the swapchain to use the native color space in Freesync2 displays.
-
Local dimming control
New Object Types
None.
New Enum Constants
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_DISPLAY_NATIVE_HDR_SURFACE_CAPABILITIES_AMD
-
VK_STRUCTURE_TYPE_SWAPCHAIN_DISPLAY_NATIVE_HDR_CREATE_INFO_AMD
-
-
Extending VkColorSpaceKHR:
-
VK_COLOR_SPACE_DISPLAY_NATIVE_AMD
-
New Enums
None.
New Functions
Issues
None.
Examples
None.
Version History
-
Revision 1, 2018-12-18 (Daniel Rakos)
-
Initial revision
-
VK_AMD_gcn_shader
- Name String
-
VK_AMD_gcn_shader
- Extension Type
-
Device extension
- Registered Extension Number
-
26
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Dominik Witczak dominikwitczakamd
-
- Last Modified Date
-
2016-05-30
- IP Status
-
No known IP claims.
- Contributors
-
-
Dominik Witczak, AMD
-
Daniel Rakos, AMD
-
Rex Xu, AMD
-
Graham Sellers, AMD
-
This extension adds support for the following SPIR-V extension in Vulkan:
Version History
-
Revision 1, 2016-05-30 (Dominik Witczak)
-
Initial draft
-
VK_AMD_memory_overallocation_behavior
- Name String
-
VK_AMD_memory_overallocation_behavior
- Extension Type
-
Device extension
- Registered Extension Number
-
190
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Martin Dinkov mdinkov
-
- Last Modified Date
-
2018-09-19
- IP Status
-
No known IP claims.
- Contributors
-
-
Martin Dinkov, AMD
-
Matthaeus Chajdas, AMD
-
Daniel Rakos, AMD
-
Jon Campbell, AMD
-
This extension allows controlling whether explicit overallocation beyond the device memory heap sizes (reported by VkPhysicalDeviceMemoryProperties) is allowed or not. Overallocation may lead to performance loss and is not supported for all platforms.
New Object Types
None.
New Enum Constants
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_DEVICE_MEMORY_OVERALLOCATION_CREATE_INFO_AMD
-
New Enums
New Structures
New Functions
None.
Examples
None.
Version History
-
Revision 1, 2018-09-19 (Martin Dinkov)
-
Initial draft.
-
VK_AMD_mixed_attachment_samples
- Name String
-
VK_AMD_mixed_attachment_samples
- Extension Type
-
Device extension
- Registered Extension Number
-
137
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Matthaeus G. Chajdas anteru
-
- Last Modified Date
-
2017-07-24
- Contributors
-
-
Mais Alnasser, AMD
-
Matthaeus G. Chajdas, AMD
-
Maciej Jesionowski, AMD
-
Daniel Rakos, AMD
-
This extension enables applications to use multisampled rendering with a depth/stencil sample count that is larger than the color sample count. Having a depth/stencil sample count larger than the color sample count allows maintaining geometry and coverage information at a higher sample rate than color information. All samples are depth/stencil tested, but only the first color sample count number of samples get a corresponding color output.
New Object Types
None.
New Enum Constants
None.
New Enums
None.
New Structures
None.
New Functions
None.
Issues
None.
Version History
-
Revision 1, 2017-07-24 (Daniel Rakos)
-
Internal revisions
-
VK_AMD_pipeline_compiler_control
- Name String
-
VK_AMD_pipeline_compiler_control
- Extension Type
-
Device extension
- Registered Extension Number
-
184
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Matthaeus G. Chajdas anteru
-
- Last Modified Date
-
2019-07-26
- IP Status
-
No known IP claims.
- Contributors
-
-
Matthaeus G. Chajdas, AMD
-
Daniel Rakos, AMD
-
Maciej Jesionowski, AMD
-
Tobias Hector, AMD
-
This extension introduces VkPipelineCompilerControlCreateInfoAMD structure that can be chained to a pipeline’s create info to specify additional flags that affect pipeline compilation.
New Object Types
None.
New Enum Constants
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PIPELINE_COMPILER_CONTROL_CREATE_INFO_AMD
-
New Enums
New Structures
New Functions
None.
Issues
None.
Examples
None.
Version History
-
Revision 1, 2019-07-26 (Tobias Hector)
-
Initial revision.
-
VK_AMD_rasterization_order
- Name String
-
VK_AMD_rasterization_order
- Extension Type
-
Device extension
- Registered Extension Number
-
19
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Daniel Rakos drakos-amd
-
- Last Modified Date
-
2016-04-25
- IP Status
-
No known IP claims.
- Contributors
-
-
Matthaeus G. Chajdas, AMD
-
Jaakko Konttinen, AMD
-
Daniel Rakos, AMD
-
Graham Sellers, AMD
-
Dominik Witczak, AMD
-
This extension introduces the possibility for the application to control the order of primitive rasterization. In unextended Vulkan, the following stages are guaranteed to execute in API order:
-
depth bounds test
-
stencil test, stencil op, and stencil write
-
depth test and depth write
-
occlusion queries
-
blending, logic op, and color write
This extension enables applications to opt into a relaxed, implementation defined primitive rasterization order that may allow better parallel processing of primitives and thus enabling higher primitive throughput. It is applicable in cases where the primitive rasterization order is known to not affect the output of the rendering or any differences caused by a different rasterization order are not a concern from the point of view of the application’s purpose.
A few examples of cases when using the relaxed primitive rasterization order would not have an effect on the final rendering:
-
If the primitives rendered are known to not overlap in framebuffer space.
-
If depth testing is used with a comparison operator of
VK_COMPARE_OP_LESS
,VK_COMPARE_OP_LESS_OR_EQUAL
,VK_COMPARE_OP_GREATER
, orVK_COMPARE_OP_GREATER_OR_EQUAL
, and the primitives rendered are known to not overlap in clip space. -
If depth testing is not used and blending is enabled for all attachments with a commutative blend operator.
New Object Types
None
New Enum Constants
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PIPELINE_RASTERIZATION_STATE_RASTERIZATION_ORDER_AMD
-
New Enums
New Structures
New Functions
None
Issues
1) How is this extension useful to application developers?
RESOLVED: Allows them to increase primitive throughput for cases when strict API order rasterization is not important due to the nature of the content, the configuration used, or the requirements towards the output of the rendering.
2) How does this extension interact with content optimizations aiming to reduce overdraw by appropriately ordering the input primitives?
RESOLVED: While the relaxed rasterization order might somewhat limit the effectiveness of such content optimizations, most of the benefits of it are expected to be retained even when the relaxed rasterization order is used, so applications should still apply these optimizations even if they intend to use the extension.
3) Are there any guarantees about the primitive rasterization order when using the new relaxed mode?
RESOLVED: No. In this case the rasterization order is completely implementation dependent, but in practice it is expected to partially still follow the order of incoming primitives.
4) Does the new relaxed rasterization order have any adverse effect on repeatability and other invariance rules of the API?
RESOLVED: Yes, in the sense that it extends the list of exceptions when the repeatability requirement does not apply.
Examples
None
Issues
None
Version History
-
Revision 1, 2016-04-25 (Daniel Rakos)
-
Initial draft.
-
VK_AMD_shader_ballot
- Name String
-
VK_AMD_shader_ballot
- Extension Type
-
Device extension
- Registered Extension Number
-
38
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Dominik Witczak dominikwitczakamd
-
- Last Modified Date
-
2016-09-19
- IP Status
-
No known IP claims.
- Contributors
-
-
Qun Lin, AMD
-
Graham Sellers, AMD
-
Daniel Rakos, AMD
-
Rex Xu, AMD
-
Dominik Witczak, AMD
-
Matthäus G. Chajdas, AMD
-
This extension adds support for the following SPIR-V extension in Vulkan:
Version History
-
Revision 1, 2016-09-19 (Dominik Witczak)
-
Initial draft
-
VK_AMD_shader_core_properties
- Name String
-
VK_AMD_shader_core_properties
- Extension Type
-
Device extension
- Registered Extension Number
-
186
- Revision
-
2
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Martin Dinkov mdinkov
-
- Last Modified Date
-
2019-06-25
- IP Status
-
No known IP claims.
- Contributors
-
-
Martin Dinkov, AMD
-
Matthaeus G. Chajdas, AMD
-
This extension exposes shader core properties for a target physical device
through the VK_KHR_get_physical_device_properties2
extension.
Please refer to the example below for proper usage.
New Object Types
None.
New Enum Constants
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_CORE_PROPERTIES_AMD
-
New Enums
None.
New Structures
New Functions
None.
Examples
This example retrieves the shader core properties for a physical device.
extern VkInstance instance;
PFN_vkGetPhysicalDeviceProperties2 pfnVkGetPhysicalDeviceProperties2 =
reinterpret_cast<PFN_vkGetPhysicalDeviceProperties2>
(vkGetInstanceProcAddr(instance, "vkGetPhysicalDeviceProperties2") );
VkPhysicalDeviceProperties2 general_props;
VkPhysicalDeviceShaderCorePropertiesAMD shader_core_properties;
shader_core_properties.pNext = nullptr;
shader_core_properties.sType = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_CORE_PROPERTIES_AMD;
general_props.pNext = &shader_core_properties;
general_props.sType = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PROPERTIES_2;
// After this call, shader_core_properties has been populated
pfnVkGetPhysicalDeviceProperties2(device, &general_props);
printf("Number of shader engines: %d\n",
m_shader_core_properties.shader_engine_count =
shader_core_properties.shaderEngineCount;
printf("Number of shader arrays: %d\n",
m_shader_core_properties.shader_arrays_per_engine_count =
shader_core_properties.shaderArraysPerEngineCount;
printf("Number of CUs per shader array: %d\n",
m_shader_core_properties.compute_units_per_shader_array =
shader_core_properties.computeUnitsPerShaderArray;
printf("Number of SIMDs per compute unit: %d\n",
m_shader_core_properties.simd_per_compute_unit =
shader_core_properties.simdPerComputeUnit;
printf("Number of wavefront slots in each SIMD: %d\n",
m_shader_core_properties.wavefronts_per_simd =
shader_core_properties.wavefrontsPerSimd;
printf("Number of threads per wavefront: %d\n",
m_shader_core_properties.wavefront_size =
shader_core_properties.wavefrontSize;
printf("Number of physical SGPRs per SIMD: %d\n",
m_shader_core_properties.sgprs_per_simd =
shader_core_properties.sgprsPerSimd;
printf("Minimum number of SGPRs that can be allocated by a wave: %d\n",
m_shader_core_properties.min_sgpr_allocation =
shader_core_properties.minSgprAllocation;
printf("Number of available SGPRs: %d\n",
m_shader_core_properties.max_sgpr_allocation =
shader_core_properties.maxSgprAllocation;
printf("SGPRs are allocated in groups of this size: %d\n",
m_shader_core_properties.sgpr_allocation_granularity =
shader_core_properties.sgprAllocationGranularity;
printf("Number of physical VGPRs per SIMD: %d\n",
m_shader_core_properties.vgprs_per_simd =
shader_core_properties.vgprsPerSimd;
printf("Minimum number of VGPRs that can be allocated by a wave: %d\n",
m_shader_core_properties.min_vgpr_allocation =
shader_core_properties.minVgprAllocation;
printf("Number of available VGPRs: %d\n",
m_shader_core_properties.max_vgpr_allocation =
shader_core_properties.maxVgprAllocation;
printf("VGPRs are allocated in groups of this size: %d\n",
m_shader_core_properties.vgpr_allocation_granularity =
shader_core_properties.vgprAllocationGranularity;
Version History
-
Revision 2, 2019-06-25 (Matthaeus G. Chajdas)
-
Clarified the meaning of a few fields.
-
-
Revision 1, 2018-02-15 (Martin Dinkov)
-
Initial draft.
-
VK_AMD_shader_core_properties2
- Name String
-
VK_AMD_shader_core_properties2
- Extension Type
-
Device extension
- Registered Extension Number
-
228
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_AMD_shader_core_properties
-
- Contact
-
-
Matthaeus G. Chajdas anteru
-
- Last Modified Date
-
2019-07-26
- IP Status
-
No known IP claims.
- Contributors
-
-
Matthaeus G. Chajdas, AMD
-
Tobias Hector, AMD
-
This extension exposes additional shader core properties for a target
physical device through the VK_KHR_get_physical_device_properties2
extension.
New Object Types
None.
New Enum Constants
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_CORE_PROPERTIES_2_AMD
-
New Enums
New Structures
New Functions
None.
Examples
None.
Version History
-
Revision 1, 2019-07-26 (Matthaeus G. Chajdas)
-
Initial draft.
-
VK_AMD_shader_explicit_vertex_parameter
- Name String
-
VK_AMD_shader_explicit_vertex_parameter
- Extension Type
-
Device extension
- Registered Extension Number
-
22
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Qun Lin linqun
-
- Last Modified Date
-
2016-05-10
- IP Status
-
No known IP claims.
- Contributors
-
-
Matthaeus G. Chajdas, AMD
-
Qun Lin, AMD
-
Daniel Rakos, AMD
-
Graham Sellers, AMD
-
Rex Xu, AMD
-
This extension adds support for the following SPIR-V extension in Vulkan:
Version History
-
Revision 1, 2016-05-10 (Daniel Rakos)
-
Initial draft
-
VK_AMD_shader_fragment_mask
- Name String
-
VK_AMD_shader_fragment_mask
- Extension Type
-
Device extension
- Registered Extension Number
-
138
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Aaron Hagan AaronHaganAMD
-
- Last Modified Date
-
2017-08-16
- IP Status
-
No known IP claims.
- Dependencies
-
-
Requires the
SPV_AMD_shader_fragment_mask
SPIR-V extension.
-
- Contributors
-
-
Aaron Hagan, AMD
-
Daniel Rakos, AMD
-
Timothy Lottes, AMD
-
This extension provides efficient read access to the fragment mask in compressed multisampled color surfaces. The fragment mask is a lookup table that associates color samples with color fragment values.
From a shader, the fragment mask can be fetched with a call to
fragmentMaskFetchAMD
, which returns a single uint
where each
subsequent four bits specify the color fragment index corresponding to the
color sample, starting from the least significant bit.
For example, when eight color samples are used, the color fragment index for
color sample 0 will be in bits 0-3 of the fragment mask, for color sample 7
the index will be in bits 28-31.
The color fragment for a particular color sample may then be fetched with
the corresponding fragment mask value using the fragmentFetchAMD
shader
function.
New Object Types
None.
New Enum Constants
None.
New Enums
None.
New SPIR-V Capabilities
New Structures
None.
New Functions
None.
Examples
This example shows a shader that queries the fragment mask from a multisampled compressed surface and uses it to query fragment values.
#version 450 core
#extension GL_AMD_shader_fragment_mask: enable
layout(binding = 0) uniform sampler2DMS s2DMS;
layout(binding = 1) uniform isampler2DMSArray is2DMSArray;
layout(binding = 2, input_attachment_index = 0) uniform usubpassInputMS usubpassMS;
layout(location = 0) out vec4 fragColor;
void main()
{
vec4 fragOne = vec4(0.0);
uint fragMask = fragmentMaskFetchAMD(s2DMS, ivec2(2, 3));
uint fragIndex = (fragMask & 0xF0) >> 4;
fragOne += fragmentFetchAMD(s2DMS, ivec2(2, 3), 1);
fragMask = fragmentMaskFetchAMD(is2DMSArray, ivec3(2, 3, 1));
fragIndex = (fragMask & 0xF0) >> 4;
fragOne += fragmentFetchAMD(is2DMSArray, ivec3(2, 3, 1), fragIndex);
fragMask = fragmentMaskFetchAMD(usubpassMS);
fragIndex = (fragMask & 0xF0) >> 4;
fragOne += fragmentFetchAMD(usubpassMS, fragIndex);
fragColor = fragOne;
}
Version History
-
Revision 1, 2017-08-16 (Aaron Hagan)
-
Initial draft
-
VK_AMD_shader_image_load_store_lod
- Name String
-
VK_AMD_shader_image_load_store_lod
- Extension Type
-
Device extension
- Registered Extension Number
-
47
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Dominik Witczak dominikwitczakamd
-
- Last Modified Date
-
2017-08-21
- Interactions and External Dependencies
-
-
This extension requires the
SPV_AMD_shader_image_load_store_lod
SPIR-V extension. -
This extension requires
GL_AMD_shader_image_load_store_lod
for GLSL-based source languages.
-
- IP Status
-
No known IP claims.
- Contributors
-
-
Dominik Witczak, AMD
-
Qun Lin, AMD
-
Rex Xu, AMD
-
This extension adds support for the following SPIR-V extension in Vulkan:
Version History
-
Revision 1, 2017-08-21 (Dominik Witczak)
-
Initial draft
-
VK_AMD_shader_info
- Name String
-
VK_AMD_shader_info
- Extension Type
-
Device extension
- Registered Extension Number
-
43
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Jaakko Konttinen jaakkoamd
-
- Last Modified Date
-
2017-10-09
- IP Status
-
No known IP claims.
- Contributors
-
-
Jaakko Konttinen, AMD
-
This extension adds a way to query certain information about a compiled shader which is part of a pipeline. This information may include shader disassembly, shader binary and various statistics about a shader’s resource usage.
While this extension provides a mechanism for extracting this information, the details regarding the contents or format of this information are not specified by this extension and may be provided by the vendor externally.
Furthermore, all information types are optionally supported, and users should not assume every implementation supports querying every type of information.
New Object Types
None.
New Enum Constants
None.
New Enums
New Structures
New Functions
Examples
This example extracts the register usage of a fragment shader within a particular graphics pipeline:
extern VkDevice device;
extern VkPipeline gfxPipeline;
PFN_vkGetShaderInfoAMD pfnGetShaderInfoAMD = (PFN_vkGetShaderInfoAMD)vkGetDeviceProcAddr(
device, "vkGetShaderInfoAMD");
VkShaderStatisticsInfoAMD statistics = {};
size_t dataSize = sizeof(statistics);
if (pfnGetShaderInfoAMD(device,
gfxPipeline,
VK_SHADER_STAGE_FRAGMENT_BIT,
VK_SHADER_INFO_TYPE_STATISTICS_AMD,
&dataSize,
&statistics) == VK_SUCCESS)
{
printf("VGPR usage: %d\n", statistics.resourceUsage.numUsedVgprs);
printf("SGPR usage: %d\n", statistics.resourceUsage.numUsedSgprs);
}
The following example continues the previous example by subsequently attempting to query and print shader disassembly about the fragment shader:
// Query disassembly size (if available)
if (pfnGetShaderInfoAMD(device,
gfxPipeline,
VK_SHADER_STAGE_FRAGMENT_BIT,
VK_SHADER_INFO_TYPE_DISASSEMBLY_AMD,
&dataSize,
nullptr) == VK_SUCCESS)
{
printf("Fragment shader disassembly:\n");
void* disassembly = malloc(dataSize);
// Query disassembly and print
if (pfnGetShaderInfoAMD(device,
gfxPipeline,
VK_SHADER_STAGE_FRAGMENT_BIT,
VK_SHADER_INFO_TYPE_DISASSEMBLY_AMD,
&dataSize,
disassembly) == VK_SUCCESS)
{
printf((char*)disassembly);
}
free(disassembly);
}
Version History
-
Revision 1, 2017-10-09 (Jaakko Konttinen)
-
Initial revision
-
VK_AMD_shader_trinary_minmax
- Name String
-
VK_AMD_shader_trinary_minmax
- Extension Type
-
Device extension
- Registered Extension Number
-
21
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Qun Lin linqun
-
- Last Modified Date
-
2016-05-10
- IP Status
-
No known IP claims.
- Contributors
-
-
Matthaeus G. Chajdas, AMD
-
Qun Lin, AMD
-
Daniel Rakos, AMD
-
Graham Sellers, AMD
-
Rex Xu, AMD
-
This extension adds support for the following SPIR-V extension in Vulkan:
Version History
-
Revision 1, 2016-05-10 (Daniel Rakos)
-
Initial draft
-
VK_AMD_texture_gather_bias_lod
- Name String
-
VK_AMD_texture_gather_bias_lod
- Extension Type
-
Device extension
- Registered Extension Number
-
42
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Rex Xu amdrexu
-
- Last Modified Date
-
2017-03-21
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
Requires the
SPV_AMD_texture_gather_bias_lod
SPIR-V extension.
-
- Contributors
-
-
Dominik Witczak, AMD
-
Daniel Rakos, AMD
-
Graham Sellers, AMD
-
Matthaeus G. Chajdas, AMD
-
Qun Lin, AMD
-
Rex Xu, AMD
-
Timothy Lottes, AMD
-
This extension adds two related features.
Firstly, support for the following SPIR-V extension in Vulkan is added:
-
SPV_AMD_texture_gather_bias_lod
Secondly, the extension allows the application to query which formats can be used together with the new function prototypes introduced by the SPIR-V extension.
New Object Types
None.
New Enum Constants
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_TEXTURE_LOD_GATHER_FORMAT_PROPERTIES_AMD
-
New Enums
None.
New SPIR-V Capabilities
New Structures
New Functions
None.
Examples
struct VkTextureLODGatherFormatPropertiesAMD
{
VkStructureType sType;
const void* pNext;
VkBool32 supportsTextureGatherLODBiasAMD;
};
// ----------------------------------------------------------------------------------------
// How to detect if an image format can be used with the new function prototypes.
VkPhysicalDeviceImageFormatInfo2 formatInfo;
VkImageFormatProperties2 formatProps;
VkTextureLODGatherFormatPropertiesAMD textureLODGatherSupport;
textureLODGatherSupport.sType = VK_STRUCTURE_TYPE_TEXTURE_LOD_GATHER_FORMAT_PROPERTIES_AMD;
textureLODGatherSupport.pNext = nullptr;
formatInfo.sType = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGE_FORMAT_INFO_2;
formatInfo.pNext = nullptr;
formatInfo.format = ...;
formatInfo.type = ...;
formatInfo.tiling = ...;
formatInfo.usage = ...;
formatInfo.flags = ...;
formatProps.sType = VK_STRUCTURE_TYPE_IMAGE_FORMAT_PROPERTIES_2;
formatProps.pNext = &textureLODGatherSupport;
vkGetPhysicalDeviceImageFormatProperties2(physical_device, &formatInfo, &formatProps);
if (textureLODGatherSupport.supportsTextureGatherLODBiasAMD == VK_TRUE)
{
// physical device supports SPV_AMD_texture_gather_bias_lod for the specified
// format configuration.
}
else
{
// physical device does not support SPV_AMD_texture_gather_bias_lod for the
// specified format configuration.
}
Version History
-
Revision 1, 2017-03-21 (Dominik Witczak)
-
Initial draft
-
VK_ANDROID_external_memory_android_hardware_buffer
- Name String
-
VK_ANDROID_external_memory_android_hardware_buffer
- Extension Type
-
Device extension
- Registered Extension Number
-
130
- Revision
-
3
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_KHR_sampler_ycbcr_conversion
-
Requires
VK_KHR_external_memory
-
Requires
VK_EXT_queue_family_foreign
-
- Contact
-
-
Jesse Hall critsec
-
- Last Modified Date
-
2019-08-27
- IP Status
-
No known IP claims.
- Contributors
-
-
Ray Smith, ARM
-
Chad Versace, Google
-
Jesse Hall, Google
-
Tobias Hector, Imagination
-
James Jones, NVIDIA
-
Tony Zlatinski, NVIDIA
-
Matthew Netsch, Qualcomm
-
Andrew Garrard, Samsung
-
This extension enables an application to import Android AHardwareBuffer objects created outside of the Vulkan device into Vulkan memory objects, where they can be bound to images and buffers. It also allows exporting an AHardwareBuffer from a Vulkan memory object for symmetry with other operating systems. But since not all AHardwareBuffer usages and formats have Vulkan equivalents, exporting from Vulkan provides strictly less functionality than creating the AHardwareBuffer externally and importing it.
Some AHardwareBuffer images have implementation-defined external formats that may not correspond to Vulkan formats. Sampler Y’CbCr conversion can be used to sample from these images and convert them to a known color space.
New Object Types
None.
New Enum Constants
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_ANDROID_HARDWARE_BUFFER_USAGE_ANDROID
-
VK_STRUCTURE_TYPE_ANDROID_HARDWARE_BUFFER_PROPERTIES_ANDROID
-
VK_STRUCTURE_TYPE_ANDROID_HARDWARE_BUFFER_FORMAT_PROPERTIES_ANDROID
-
VK_STRUCTURE_TYPE_IMPORT_ANDROID_HARDWARE_BUFFER_INFO_ANDROID
-
VK_STRUCTURE_TYPE_MEMORY_GET_ANDROID_HARDWARE_BUFFER_INFO_ANDROID
-
VK_STRUCTURE_TYPE_EXTERNAL_FORMAT_ANDROID
-
-
Extending VkExternalMemoryHandleTypeFlagBits:
-
VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID
-
New Enums
None.
New Structs
Issues
1) Other external memory objects are represented as weakly-typed handles
(e.g. Win32 HANDLE
or POSIX file descriptor), and require a handle type
parameter along with handles.
AHardwareBuffer is strongly typed, so naming the handle type is
redundant.
Does symmetry justify adding handle type parameters/fields anyway?
RESOLVED: No. The handle type is already provided in places that treat external memory objects generically. In the places we would add it, the application code that would have to provide the handle type value is already dealing with AHardwareBuffer-specific commands/structures; the extra symmetry would not be enough to make that code generic.
2) The internal layout and therefore size of a AHardwareBuffer image may depend on native usage flags that do not have corresponding Vulkan counterparts. Do we provide this info to vkCreateImage somehow, or allow the allocation size reported by vkGetImageMemoryRequirements to be approximate?
RESOLVED: Allow the allocation size to be unspecified when allocating the memory. It has to work this way for exported image memory anyway, since AHardwareBuffer allocation happens in vkAllocateMemory, and internally is performed by a separate HAL, not the Vulkan implementation itself. There is a similar issue with vkGetImageSubresourceLayout: the layout is determined by the allocator HAL, so it is not known until the image is bound to memory.
3) Should the result of sampling an external-format image with the suggested
Y’CbCr conversion parameters yield the same results as using a
samplerExternalOES
in OpenGL ES?
RESOLVED: This would be desirable, so that apps converting from OpenGL ES to Vulkan could get the same output given the same input. But since sampling and conversion from Y’CbCr images is so loosely defined in OpenGL ES, multiple implementations do it in a way that doesn’t conform to Vulkan’s requirements. Modifying the OpenGL ES implementation would be difficult, and would change the output of existing unmodified applications. Changing the output only for applications that are being modified gives developers the chance to notice and mitigate any problems. Implementations are encouraged to minimize differences as much as possible without causing compatibility problems for existing OpenGL ES applications or violating Vulkan requirements.
4) Should an AHardwareBuffer with AHARDWAREBUFFER_USAGE_CPU_
*
usage be mappable in Vulkan? Should it be possible to export an
AHardwareBuffers
with such usage?
RESOLVED: Optional, and mapping in Vulkan is not the same as
AHardwareBuffer_lock
.
The semantics of these are different: mapping in memory is persistent, just
gives a raw view of the memory contents, and does not involve ownership.
AHardwareBuffer_lock
gives the host exclusive access to the buffer, is
temporary, and allows for reformatting copy-in/copy-out.
Implementations are not required to support host-visible memory types for
imported Android hardware buffers or resources backed by them.
If a host-visible memory type is supported and used, the memory can be
mapped in Vulkan, but doing so follows Vulkan semantics: it is just a raw
view of the data and does not imply ownership (this means implementations
must not internally call AHardwareBuffer_lock
to implement
vkMapMemory, or assume the application has done so).
Implementations are not required to support linear-tiled images backed by
Android hardware buffers, even if the AHardwareBuffer has CPU usage.
There is no reliable way to allocate memory in Vulkan that can be exported
to a AHardwareBuffer with CPU usage.
5) Android may add new AHardwareBuffer formats and usage flags over time. Can reference to them be added to this extension, or do they need a new extension?
RESOLVED: This extension can document the interaction between the new AHB formats/usages and existing Vulkan features. No new Vulkan features or implementation requirements can be added. The extension version number will be incremented when this additional documentation is added, but the version number does not indicate that an implementaiton supports Vulkan memory or resources that map to the new AHardwareBuffer features: support for that must be queried with vkGetPhysicalDeviceImageFormatProperties2 or is implied by successfully allocating a AHardwareBuffer outside of Vulkan that uses the new feature and has a GPU usage flag.
In essence, these are new features added to a new Android API level, rather than new Vulkan features. The extension will only document how existing Vulkan features map to that new Android feature.
Version History
-
Revision 3, 2019-08-27 (Jon Leech)
-
Update revision history to correspond to XML version number
-
-
Revision 2, 2018-04-09 (Petr Kraus)
-
Markup fixes and remove incorrect Draft status
-
-
Revision 1, 2018-03-04 (Jesse Hall)
-
Initial version
-
VK_FUCHSIA_imagepipe_surface
- Name String
-
VK_FUCHSIA_imagepipe_surface
- Extension Type
-
Instance extension
- Registered Extension Number
-
215
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_KHR_surface
-
- Contact
-
-
Craig Stout cdotstout
-
- Last Modified Date
-
2018-07-27
- IP Status
-
No known IP claims.
- Contributors
-
-
Craig Stout, Google
-
Ian Elliott, Google
-
Jesse Hall, Google
-
The VK_FUCHSIA_imagepipe_surface
extension is an instance extension.
It provides a mechanism to create a VkSurfaceKHR object (defined by
the VK_KHR_surface
extension) that refers to a Fuchsia
imagePipeHandle
.
New Object Types
None
New Enum Constants
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_IMAGEPIPE_SURFACE_CREATE_INFO_FUCHSIA
-
New Enums
None
New Structures
New Functions
Issues
None
Version History
-
Revision 1, 2018-07-27 (Craig Stout)
-
Initial draft.
-
VK_GGP_frame_token
- Name String
-
VK_GGP_frame_token
- Extension Type
-
Device extension
- Registered Extension Number
-
192
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_KHR_swapchain
-
Requires
VK_GGP_stream_descriptor_surface
-
- Contact
-
-
Jean-Francois Roy jfroy
-
- Last Modified Date
-
2019-01-28
- IP Status
-
No known IP claims.
- Contributors
-
-
Jean-Francois Roy, Google
-
Richard O’Grady, Google
-
This extension allows an application that uses the VK_KHR_swapchain
extension in combination with a Google Games Platform surface provided by
the VK_GGP_stream_descriptor_surface
extension to associate a Google
Games Platform frame token with a present operation.
New Object Types
None.
New Enum Constants
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PRESENT_FRAME_TOKEN_GGP
-
New Enums
None.
New Structures
New Functions
None.
Issues
None.
Version History
-
Revision 1, 2018-11-26 (Jean-Francois Roy)
-
Initial revision.
-
VK_GGP_stream_descriptor_surface
- Name String
-
VK_GGP_stream_descriptor_surface
- Extension Type
-
Instance extension
- Registered Extension Number
-
50
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_KHR_surface
-
- Contact
-
-
Jean-Francois Roy jfroy
-
- Last Modified Date
-
2019-01-28
- IP Status
-
No known IP claims.
- Contributors
-
-
Jean-Francois Roy, Google
-
Brad Grantham, Google
-
Connor Smith, Google
-
Cort Stratton, Google
-
Hai Nguyen, Google
-
Ian Elliott, Google
-
Jesse Hall, Google
-
Jim Ray, Google
-
Katherine Wu, Google
-
Kaye Mason, Google
-
Kuangye Guo, Google
-
Mark Segal, Google
-
Nicholas Vining, Google
-
Paul Lalonde, Google
-
Richard O’Grady, Google
-
The VK_GGP_stream_descriptor_surface
extension is an instance extension.
It provides a mechanism to create a VkSurfaceKHR object (defined by
the VK_KHR_surface
extension) that refers to a Google Games Platform
GgpStreamDescriptor
.
New Object Types
None.
New Enum Constants
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_STREAM_DESCRIPTOR_SURFACE_CREATE_INFO_GGP
-
New Enums
None.
New Structures
New Functions
Issues
None.
Version History
-
Revision 1, 2018-11-26 (Jean-Francois Roy)
-
Initial revision.
-
VK_GOOGLE_decorate_string
- Name String
-
VK_GOOGLE_decorate_string
- Extension Type
-
Device extension
- Registered Extension Number
-
225
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Hai Nguyen chaoticbob
-
- Last Modified Date
-
2018-07-09
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
Requires the
SPV_GOOGLE_decorate_string
SPIR-V extension.
-
- Contributors
-
-
Hai Nguyen, Google
-
Neil Henning, AMD
-
The VK_GOOGLE_decorate_string
extension allows use of the
SPV_GOOGLE_decorate_string
extension in SPIR-V shader modules.
New Enum Constants
None.
New Structures
None.
New SPIR-V Capabilities
None.
Issues
Version History
-
Revision 1, 2018-07-09 (Neil Henning)
-
Initial draft
-
VK_GOOGLE_display_timing
- Name String
-
VK_GOOGLE_display_timing
- Extension Type
-
Device extension
- Registered Extension Number
-
93
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_KHR_swapchain
-
- Contact
-
-
Ian Elliott ianelliottus
-
- Last Modified Date
-
2017-02-14
- IP Status
-
No known IP claims.
- Contributors
-
-
Ian Elliott, Google
-
Jesse Hall, Google
-
This device extension allows an application that uses the
VK_KHR_swapchain
extension to obtain information about the
presentation engine’s display, to obtain timing information about each
present, and to schedule a present to happen no earlier than a desired time.
An application can use this to minimize various visual anomalies (e.g.
stuttering).
Traditional game and real-time animation applications need to correctly position their geometry for when the presentable image will be presented to the user. To accomplish this, applications need various timing information about the presentation engine’s display. They need to know when presentable images were actually presented, and when they could have been presented. Applications also need to tell the presentation engine to display an image no sooner than a given time. This allows the application to avoid stuttering, so the animation looks smooth to the user.
This extension treats variable-refresh-rate (VRR) displays as if they are fixed-refresh-rate (FRR) displays.
New Object Types
None.
New Enum Constants
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PRESENT_TIMES_INFO_GOOGLE
-
New Enums
None.
New Structures
Issues
None.
Examples
Note
The example code for the this extension (like the |
Version History
-
Revision 1, 2017-02-14 (Ian Elliott)
-
Internal revisions
-
VK_GOOGLE_hlsl_functionality1
- Name String
-
VK_GOOGLE_hlsl_functionality1
- Extension Type
-
Device extension
- Registered Extension Number
-
224
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Hai Nguyen chaoticbob
-
- Last Modified Date
-
2018-07-09
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
Requires the
SPV_GOOGLE_hlsl_functionality1
SPIR-V extension.
-
- Contributors
-
-
Hai Nguyen, Google
-
Neil Henning, AMD
-
The VK_GOOGLE_hlsl_functionality1
extension allows use of the
SPV_GOOGLE_hlsl_functionality1
extension in SPIR-V shader modules.
New Enum Constants
None.
New Structures
None.
New SPIR-V Capabilities
None.
Issues
Version History
-
Revision 1, 2018-07-09 (Neil Henning)
-
Initial draft
-
VK_GOOGLE_user_type
- Name String
-
VK_GOOGLE_user_type
- Extension Type
-
Device extension
- Registered Extension Number
-
290
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Kaye Mason chaleur
-
- Last Modified Date
-
2019-07-09
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
Requires the
SPV_GOOGLE_user_type
SPIR-V extension.
-
- Contributors
-
-
Kaye Mason, Google
-
Hai Nguyen, Google
-
The VK_GOOGLE_user_type
extension allows use of the SPV_GOOGLE_user_type
extension in SPIR-V shader modules.
New Enum Constants
None.
New Structures
None.
New SPIR-V Capabilities
None.
Issues
Version History
-
Revision 1, 2019-09-07 (Kaye Mason)
-
Initial draft
-
VK_IMG_filter_cubic
- Name String
-
VK_IMG_filter_cubic
- Extension Type
-
Device extension
- Registered Extension Number
-
16
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Tobias Hector tobski
-
- Last Modified Date
-
2016-02-23
- Contributors
-
-
Tobias Hector, Imagination Technologies
-
VK_IMG_filter_cubic
adds an additional, high quality cubic filtering mode
to Vulkan, using a Catmull-Rom bicubic filter.
Performing this kind of filtering can be done in a shader by using 16
samples and a number of instructions, but this can be inefficient.
The cubic filter mode exposes an optimized high quality texture sampling
using fixed texture sampling functionality.
New Enum Constants
-
Extending VkFilter:
-
VK_FILTER_CUBIC_IMG
-
-
Extending VkFormatFeatureFlagBits
-
VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_CUBIC_BIT_IMG
-
Example
Creating a sampler with the new filter for both magnification and minification
VkSamplerCreateInfo createInfo =
{
VK_STRUCTURE_TYPE_SAMPLER_CREATE_INFO // sType
// Other members set to application-desired values
};
createInfo.magFilter = VK_FILTER_CUBIC_IMG;
createInfo.minFilter = VK_FILTER_CUBIC_IMG;
VkSampler sampler;
VkResult result = vkCreateSampler(
device,
&createInfo,
&sampler);
Version History
-
Revision 1, 2016-02-23 (Tobias Hector)
-
Initial version
-
VK_IMG_format_pvrtc
- Name String
-
VK_IMG_format_pvrtc
- Extension Type
-
Device extension
- Registered Extension Number
-
55
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Stuart Smith
-
- Last Modified Date
-
2019-09-02
- IP Status
-
Imagination Technologies Proprietary
- Contributors
-
-
Stuart Smith, Imagination Technologies
-
VK_IMG_format_pvrtc
provides additional texture compression functionality
specific to Imagination Technologies PowerVR Texture compression format
(called PVRTC).
New Object Types
None.
New Enum Constants
-
Extending VkFormat:
-
VK_FORMAT_PVRTC1_2BPP_UNORM_BLOCK_IMG
-
VK_FORMAT_PVRTC1_4BPP_UNORM_BLOCK_IMG
-
VK_FORMAT_PVRTC2_2BPP_UNORM_BLOCK_IMG
-
VK_FORMAT_PVRTC2_4BPP_UNORM_BLOCK_IMG
-
VK_FORMAT_PVRTC1_2BPP_SRGB_BLOCK_IMG
-
VK_FORMAT_PVRTC1_4BPP_SRGB_BLOCK_IMG
-
VK_FORMAT_PVRTC2_2BPP_SRGB_BLOCK_IMG
-
VK_FORMAT_PVRTC2_4BPP_SRGB_BLOCK_IMG
-
New Enum Constants
None.
New Structures
None.
New Functions
None.
Issues
None.
Version History
-
Revision 1, 2019-09-02 (Stuart Smith)
-
Initial version
-
VK_INTEL_performance_query
- Name String
-
VK_INTEL_performance_query
- Extension Type
-
Device extension
- Registered Extension Number
-
211
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Lionel Landwerlin llandwerlin
-
- Last Modified Date
-
2018-05-16
- IP Status
-
No known IP claims.
- Contributors
-
-
Lionel Landwerlin, Intel
-
Piotr Maciejewski, Intel
-
This extension allows an application to capture performance data to be interpreted by a external application or library.
Such a library is available at : https://github.com/intel/metrics-discovery
Performance analysis tools such as GPA (https://software.intel.com/en-us/gpa) make use of this extension and the metrics-discovery library to present the data in a human readable way.
New Object Types
New Enum Constants
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_QUERY_POOL_CREATE_INFO_INTEL
-
VK_STRUCTURE_TYPE_INITIALIZE_PERFORMANCE_API_INFO_INTEL
-
VK_STRUCTURE_TYPE_PERFORMANCE_MARKER_INFO_INTEL
-
VK_STRUCTURE_TYPE_PERFORMANCE_STREAM_MARKER_INFO_INTEL
-
VK_STRUCTURE_TYPE_PERFORMANCE_OVERRIDE_INFO_INTEL
-
VK_STRUCTURE_TYPE_PERFORMANCE_CONFIGURATION_ACQUIRE_INFO_INTEL
-
-
Extending VkQueryType:
-
VK_QUERY_TYPE_PERFORMANCE_QUERY_INTEL
-
New Enums
New Structures
New Functions
Issues
None.
Example Code
// A previously created device
VkDevice device;
// A queue from from device
VkQueue queue;
VkInitializePerformanceApiInfoINTEL performanceApiInfoIntel = {
VK_STRUCTURE_TYPE_INITIALIZE_PERFORMANCE_API_INFO_INTEL,
NULL,
NULL
};
vkInitializePerformanceApiINTEL(
device,
&performanceApiInfoIntel);
VkQueryPoolCreateInfoINTEL queryPoolIntel = {
VK_STRUCTURE_TYPE_QUERY_POOL_CREATE_INFO_INTEL,
NULL,
VK_QUERY_POOL_SAMPLING_MODE_MANUAL_INTEL,
};
VkQueryPoolCreateInfo queryPoolCreateInfo = {
VK_STRUCTURE_TYPE_QUERY_POOL_CREATE_INFO,
&queryPoolIntel,
0,
VK_QUERY_TYPE_PERFORMANCE_QUERY_INTEL,
1,
0
};
VkQueryPool queryPool;
VkResult result = vkCreateQueryPool(
device,
&queryPoolCreateInfo,
NULL,
&queryPool);
assert(VK_SUCCESS == result);
// A command buffer we want to record counters on
VkCommandBuffer commandBuffer;
VkCommandBufferBeginInfo commandBufferBeginInfo = {
VK_STRUCTURE_TYPE_COMMAND_BUFFER_BEGIN_INFO,
NULL,
VK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT,
NULL
};
result = vkBeginCommandBuffer(commandBuffer, &commandBufferBeginInfo);
assert(VK_SUCCESS == result);
vkCmdResetQueryPool(
commandBuffer,
queryPool,
0,
1);
vkCmdBeginQuery(
commandBuffer,
queryPool,
0,
0);
// Perform the commands you want to get performance information on
// ...
// Perform a barrier to ensure all previous commands were complete before
// ending the query
vkCmdPipelineBarrier(commandBuffer,
VK_PIPELINE_STAGE_BOTTOM_OF_PIPE_BIT,
VK_PIPELINE_STAGE_BOTTOM_OF_PIPE_BIT,
0,
0,
NULL,
0,
NULL,
0,
NULL);
vkCmdEndQuery(
commandBuffer,
queryPool,
0);
result = vkEndCommandBuffer(commandBuffer);
assert(VK_SUCCESS == result);
VkPerformanceConfigurationAcquireInfoINTEL performanceConfigurationAcquireInfo = {
VK_STRUCTURE_TYPE_PERFORMANCE_CONFIGURATION_ACQUIRE_INFO_INTEL,
NULL,
VK_PERFORMANCE_CONFIGURATION_TYPE_COMMAND_QUEUE_METRICS_DISCOVERY_ACTIVATED_INTEL
};
VkPerformanceConfigurationINTEL performanceConfigurationIntel;
result = vkAcquirePerformanceConfigurationINTEL(
device,
&performanceConfigurationAcquireInfo,
&performanceConfigurationIntel);
vkQueueSetPerformanceConfigurationINTEL(queue, performanceConfigurationIntel);
assert(VK_SUCCESS == result);
// Submit the command buffer and wait for its completion
// ...
result = vkReleasePerformanceConfigurationINTEL(
device,
performanceConfigurationIntel);
assert(VK_SUCCESS == result);
// Get the report size from metrics-discovery's QueryReportSize
result = vkGetQueryPoolResults(
device,
queryPool,
0, 1, QueryReportSize,
data, QueryReportSize, 0);
assert(VK_SUCCESS == result);
// The data can then be passed back to metrics-discovery from which
// human readable values can be queried.
Version History
-
Revision 1, 2018-05-16 (Lionel Landwerlin)
-
Initial revision
-
VK_INTEL_shader_integer_functions2
- Name String
-
VK_INTEL_shader_integer_functions2
- Extension Type
-
Device extension
- Registered Extension Number
-
210
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Ian Romanick ianromanick
-
- Last Modified Date
-
2019-04-30
- IP Status
-
No known IP claims.
- Contributors
-
-
Ian Romanick, Intel
-
Ben Ashbaugh, Intel
-
This extension adds support for several new integer instructions in SPIR-V for use in graphics shaders. Many of these instructions have pre-existing counterparts in the Kernel environment.
The added integer functions are defined by the
SPV_INTEL_shader_integer_functions
SPIR-V extension and can be used with the GL_INTEL_shader_integer_functions2
GLSL extension.
New Object Types
None.
New Enum Constants
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_INTEGER_FUNCTIONS_2_FEATURES_INTEL
-
New Enums
None.
New Structures
New Functions
None.
New SPIR-V Capabilities
Issues
None.
Version History
-
Revision 1, 2019-04-30 (Ian Romanick)
-
Initial draft
-
VK_MVK_ios_surface
- Name String
-
VK_MVK_ios_surface
- Extension Type
-
Instance extension
- Registered Extension Number
-
123
- Revision
-
2
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_KHR_surface
-
- Contact
-
-
Bill Hollings billhollings
-
- Last Modified Date
-
2017-02-24
- IP Status
-
No known IP claims.
- Contributors
-
-
Bill Hollings, The Brenwill Workshop Ltd.
-
The VK_MVK_ios_surface
extension is an instance extension.
It provides a mechanism to create a VkSurfaceKHR object (defined by
the VK_KHR_surface
extension) that refers to a UIView
, the native
surface type of iOS, which is underpinned by a CAMetalLayer, to
support rendering to the surface using Apple’s Metal framework.
New Object Types
None.
New Enum Constants
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_IOS_SURFACE_CREATE_INFO_MVK
-
New Enums
None.
New Structures
New Functions
Issues
None.
Version History
-
Revision 1, 2017-02-15 (Bill Hollings)
-
Initial draft.
-
-
Revision 2, 2017-02-24 (Bill Hollings)
-
Minor syntax fix to emphasize firm requirement for UIView to be backed by a CAMetalLayer.
-
VK_MVK_macos_surface
- Name String
-
VK_MVK_macos_surface
- Extension Type
-
Instance extension
- Registered Extension Number
-
124
- Revision
-
2
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_KHR_surface
-
- Contact
-
-
Bill Hollings billhollings
-
- Last Modified Date
-
2017-02-24
- IP Status
-
No known IP claims.
- Contributors
-
-
Bill Hollings, The Brenwill Workshop Ltd.
-
The VK_MVK_macos_surface
extension is an instance extension.
It provides a mechanism to create a VkSurfaceKHR object (defined by
the VK_KHR_surface
extension) that refers to an NSView
, the
native surface type of macOS, which is underpinned by a CAMetalLayer,
to support rendering to the surface using Apple’s Metal framework.
New Object Types
None.
New Enum Constants
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_MACOS_SURFACE_CREATE_INFO_MVK
-
New Enums
None.
New Structures
New Functions
Issues
None.
Version History
-
Revision 1, 2017-02-15 (Bill Hollings)
-
Initial draft.
-
-
Revision 2, 2017-02-24 (Bill Hollings)
-
Minor syntax fix to emphasize firm requirement for NSView to be backed by a CAMetalLayer.
-
VK_NN_vi_surface
- Name String
-
VK_NN_vi_surface
- Extension Type
-
Instance extension
- Registered Extension Number
-
63
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_KHR_surface
-
- Contact
-
-
Mathias Heyer mheyer
-
- Last Modified Date
-
2016-12-02
- IP Status
-
No known IP claims.
- Contributors
-
-
Mathias Heyer, NVIDIA
-
Michael Chock, NVIDIA
-
Yasuhiro Yoshioka, Nintendo
-
Daniel Koch, NVIDIA
-
The VK_NN_vi_surface
extension is an instance extension.
It provides a mechanism to create a VkSurfaceKHR object (defined by
the VK_KHR_surface
extension) associated with an
nn
::vi
::Layer
.
New Object Types
None
New Enum Constants
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_VI_SURFACE_CREATE_INFO_NN
-
New Enums
None
New Structures
New Functions
Issues
1) Does VI need a way to query for compatibility between a particular physical device (and queue family?) and a specific VI display?
RESOLVED: No. It is currently always assumed that the device and display will always be compatible.
2) VkViSurfaceCreateInfoNN::pWindow
is intended to store an
nn
::vi
::NativeWindowHandle
, but its declared type is a bare
void
* to store the window handle.
Why the discrepancy?
RESOLVED: It is for C compatibility.
The definition for the VI native window handle type is defined inside the
nn
::vi
C++ namespace.
This prevents its use in C source files.
nn
::vi
::NativeWindowHandle
is always defined to be
void
*, so this extension uses void
* to match.
Version History
-
Revision 1, 2016-12-2 (Michael Chock)
-
Initial draft.
-
VK_NVX_device_generated_commands
- Name String
-
VK_NVX_device_generated_commands
- Extension Type
-
Device extension
- Registered Extension Number
-
87
- Revision
-
3
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Christoph Kubisch pixeljetstream
-
- Last Modified Date
-
2017-07-25
- Contributors
-
-
Pierre Boudier, NVIDIA
-
Christoph Kubisch, NVIDIA
-
Mathias Schott, NVIDIA
-
Jeff Bolz, NVIDIA
-
Eric Werness, NVIDIA
-
Detlef Roettger, NVIDIA
-
Daniel Koch, NVIDIA
-
Chris Hebert, NVIDIA
-
This extension allows the device to generate a number of critical commands for command buffers.
When rendering a large number of objects, the device can be leveraged to implement a number of critical functions, like updating matrices, or implementing occlusion culling, frustum culling, front to back sorting, etc. Implementing those on the device does not require any special extension, since an application is free to define its own data structure, and just process them using shaders.
However, if the application desires to quickly kick off the rendering of the final stream of objects, then unextended Vulkan forces the application to read back the processed stream and issue graphics command from the host. For very large scenes, the synchronization overhead, and cost to generate the command buffer can become the bottleneck. This extension allows an application to generate a device side stream of state changes and commands, and convert it efficiently into a command buffer without having to read it back on the host.
Furthermore, it allows incremental changes to such command buffers by manipulating only partial sections of a command stream — for example pipeline bindings. Unextended Vulkan requires re-creation of entire command buffers in such scenario, or updates synchronized on the host.
The intended usage for this extension is for the application to:
-
create its objects as in unextended Vulkan
-
create a VkObjectTableNVX, and register the various Vulkan objects that are needed to evaluate the input parameters.
-
create a VkIndirectCommandsLayoutNVX, which lists the VkIndirectCommandsTokenTypeNVX it wants to dynamically change as atomic command sequence. This step likely involves some internal device code compilation, since the intent is for the GPU to generate the command buffer in the pipeline.
-
fill the input buffers with the data for each of the inputs it needs. Each input is an array that will be filled with an index in the object table, instead of using CPU pointers.
-
set up a target secondary command buffer
-
reserve command buffer space via vkCmdReserveSpaceForCommandsNVX in a target command buffer at the position you want the generated commands to be executed.
-
call vkCmdProcessCommandsNVX to create the actual device commands for all sequences based on the array contents into a provided target command buffer.
-
execute the target command buffer like a regular secondary command buffer
For each draw/dispatch, the following can be specified:
-
a different pipeline state object
-
a number of descriptor sets, with dynamic offsets
-
a number of vertex buffer bindings, with an optional dynamic offset
-
a different index buffer, with an optional dynamic offset
Applications should register a small number of objects, and use dynamic offsets whenever possible.
While the GPU can be faster than a CPU to generate the commands, it may not happen asynchronously, therefore the primary use-case is generating “less” total work (occlusion culling, classification to use specialized shaders, etc.).
New Object Types
New Flag Types
New Enum Constants
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_OBJECT_TABLE_CREATE_INFO_NVX
-
VK_STRUCTURE_TYPE_INDIRECT_COMMANDS_LAYOUT_CREATE_INFO_NVX
-
VK_STRUCTURE_TYPE_CMD_PROCESS_COMMANDS_INFO_NVX
-
VK_STRUCTURE_TYPE_CMD_RESERVE_SPACE_FOR_COMMANDS_INFO_NVX
-
VK_STRUCTURE_TYPE_DEVICE_GENERATED_COMMANDS_LIMITS_NVX
-
VK_STRUCTURE_TYPE_DEVICE_GENERATED_COMMANDS_FEATURES_NVX
Extending VkPipelineStageFlagBits:
-
VK_PIPELINE_STAGE_COMMAND_PROCESS_BIT_NVX
Extending VkAccessFlagBits:
-
VK_ACCESS_COMMAND_PROCESS_READ_BIT_NVX
-
VK_ACCESS_COMMAND_PROCESS_WRITE_BIT_NVX
New Enums
New Structures
New Functions
Issues
1) How to name this extension ?
RESOLVED: VK_NVX_device_generated_commands
As usual, one of the hardest issues ;)
Alternatives: VK_gpu_commands
, VK_execute_commands
,
VK_device_commands
, VK_device_execute_commands
, VK_device_execute
,
VK_device_created_commands
, VK_device_recorded_commands
,
VK_device_generated_commands
2) Should we use serial tokens or redundant sequence description?
Similarly to VkPipeline, signatures have the most likelihood to be cross-vendor adoptable. They also benefit from being processable in parallel.
3) How to name sequence description
ExecuteCommandSignature
is a bit long.
Maybe just ExecuteSignature
, or actually more following Vulkan
nomenclature: VkIndirectCommandsLayoutNVX.
4) Do we want to provide indirectCommands
inputs with layout or at
indirectCommands
time?
Separate layout from data as Vulkan does.
Provide full flexibilty for indirectCommands
.
5) Should the input be provided as SoA or AoS?
It is desirable for the application to reuse the list of objects and render them with some kind of an override. This can be done by just selecting a different input for a push constant or a descriptor set, if they are defined as independent arrays. If the data was interleaved, this would not be as easily possible.
Allowing input divisors can also reduce the conservative command buffer allocation.
6) How do we know the size of the GPU command buffer generated by vkCmdProcessCommandsNVX ?
maxSequenceCount
can give an upper estimate, even if the actual count
is sourced from the gpu buffer at (buffer, countOffset).
As such maxSequenceCount
must always be set correctly.
Developers are encouraged to make well use the
VkIndirectCommandsLayoutNVX’s pTokens
[].divisor, as they allow
less conservative storage costs.
Especially pipeline changes on a per-draw basis can be costly memory wise.
7) How to deal with dynamic offsets in DescriptorSets?
Maybe additional token VK_EXECUTE_DESCRIPTOR_SET_OFFSET_COMMAND_NVX
that works for a “single dynamic buffer” descriptor set and then use (32
bit tableEntry + 32bit offset)
added dynamicCount field, variable sized input
8) Should we allow updates to the object table, similar to DescriptorSet?
Desired yes, people may change “material” shaders and not want to recreate the entire register table. However the developer must ensure to not overwrite a registered objectIndex while it is still being used.
9) Should we allow dynamic state changes?
Seems a bit excessive for “per-draw” type of scenario, but GPU could partition work itself with viewport/scissor…
10) How do we allow re-using already “filled” indirectCommands
buffers?
just use a VkCommandBuffer for the output, and it can be reused easily.
11) How portable should such re-use be?
Same as secondary command buffer
12) Should sequenceOrdered be part of IndirectCommandsLayout or vkCmdProcessCommandsNVX?
Seems better for IndirectCommandsLayout, as that is when most heavy lifting in terms of internal device code generation is done.
13) Under which conditions is vkCmdProcessCommandsNVX legal?
Options:
a) on the host command buffer like a regular draw call
b) vkCmdProcessCommandsNVX makes use VkCommandBufferBeginInfo and serves as vkBeginCommandBuffer / vkEndCommandBuffer implicitly.
c) The targetCommandbuffer
must be inside the “begin” state already
at the moment of being passed.
This very likely suggests a new VkCommandBufferUsageFlags
VK_COMMAND_BUFFER_USAGE_DEVICE_GENERATED_BIT
.
d) The targetCommandbuffer
must reserve space via a new function.
used a) and d).
14) What if different pipelines have different DescriptorSetLayouts at a
certain set unit that mismatches in token.dynamicCount
?
Considered legal, as long as the maximum dynamic count of all used DescriptorSetLayouts is provided.
15) Should we add “strides” to input arrays, so that “Array of Structures” type setups can be supported more easily?
Maybe provide a usage flag for packed tokens stream (all inputs from same buffer, implicit stride).
No, given performance test was worse.
16) Should we allow re-using the target command buffer directly, without need to reset command buffer?
YES: new api vkCmdReserveSpaceForCommandsNVX.
17) Is vkCmdProcessCommandsNVX copying the input data or referencing it ?
There are multiple implementations possible:
-
one could have some emulation code that parse the inputs, and generates an output command buffer, therefore copying the inputs.
-
one could just reference the inputs, and have the processing done in pipe at execution time.
If the data is mandated to be copied, then it puts a penalty on implementation that could process the inputs directly in pipe. If the data is “referenced”, then it allows both types of implementation
The inputs are “referenced”, and should not be modified after the call to vkCmdProcessCommandsNVX and until after the rendering of the target command buffer is finished.
18) Why is this NVX
and not NV
?
To allow early experimentation and feedback. We expect that a version with a refined design as multi-vendor variant will follow up.
19) Should we make the availability for each token type a device limit?
Only distinguish between graphics/compute for now, further splitting up may lead to too much fractioning.
20) When can the objectTable
be modified?
Similar to the other inputs for vkCmdProcessCommandsNVX, only when all device access via vkCmdProcessCommandsNVX or execution of target command buffer has completed can an object at a given objectIndex be unregistered or re-registered again.
21) Which buffer usage flags are required for the buffers referenced by vkCmdProcessCommandsNVX
reuse existing VK_BUFFER_USAGE_INDIRECT_BUFFER_BIT
-
VkCmdProcessCommandsInfoNVX::
sequencesCountBuffer
-
VkCmdProcessCommandsInfoNVX::
sequencesIndexBuffer
-
VkIndirectCommandsTokenNVX::
buffer
22) In which pipeline stage do the device generated command expansion happen?
vkCmdProcessCommandsNVX is treated as if it occurs in a separate
logical pipeline from either graphics or compute, and that pipeline only
includes VK_PIPELINE_STAGE_TOP_OF_PIPE_BIT
, a new stage
VK_PIPELINE_STAGE_COMMAND_PROCESS_BIT_NVX
, and
VK_PIPELINE_STAGE_BOTTOM_OF_PIPE_BIT
.
This new stage has two corresponding new access types,
VK_ACCESS_COMMAND_PROCESS_READ_BIT_NVX
and
VK_ACCESS_COMMAND_PROCESS_WRITE_BIT_NVX
, used to synchronize reading
the buffer inputs and writing the command buffer memory output.
The output written in the target command buffer is considered to be consumed
by the VK_PIPELINE_STAGE_DRAW_INDIRECT_BIT
pipeline stage.
Thus, to synchronize from writing the input buffers to executing vkCmdProcessCommandsNVX, use:
-
dstStageMask
=VK_PIPELINE_STAGE_COMMAND_PROCESS_BIT_NVX
-
dstAccessMask
=VK_ACCESS_COMMAND_PROCESS_READ_BIT_NVX
To synchronize from executing vkCmdProcessCommandsNVX to executing the generated commands, use
-
srcStageMask
=VK_PIPELINE_STAGE_COMMAND_PROCESS_BIT_NVX
-
srcAccessMask
=VK_ACCESS_COMMAND_PROCESS_WRITE_BIT_NVX
-
dstStageMask
=VK_PIPELINE_STAGE_DRAW_INDIRECT_BIT
-
dstAccessMask
=VK_ACCESS_INDIRECT_COMMAND_READ_BIT
When vkCmdProcessCommandsNVX is used with a targetCommandBuffer
of NULL
, the generated commands are immediately executed and there is
implicit synchronization between generation and execution.
23) What if most token data is “static”, but we frequently want to render a subsection?
added “sequencesIndexBuffer”. This allows to easier sort and filter what should actually be processed.
Example Code
Open-Source samples illustrating the usage of the extension can be found at the following locations:
// setup secondary command buffer
vkBeginCommandBuffer(generatedCmdBuffer, &beginInfo);
... setup its state as usual
// insert the reservation (there can only be one per command buffer)
// where the generated calls should be filled into
VkCmdReserveSpaceForCommandsInfoNVX reserveInfo = { VK_STRUCTURE_TYPE_CMD_RESERVE_SPACE_FOR_COMMANDS_INFO_NVX };
reserveInfo.objectTable = objectTable;
reserveInfo.indirectCommandsLayout = deviceGeneratedLayout;
reserveInfo.maxSequencesCount = myCount;
vkCmdReserveSpaceForCommandsNVX(generatedCmdBuffer, &reserveInfo);
vkEndCommandBuffer(generatedCmdBuffer);
// trigger the generation at some point in another primary command buffer
VkCmdProcessCommandsInfoNVX processInfo = { VK_STRUCTURE_TYPE_CMD_PROCESS_COMMANDS_INFO_NVX };
processInfo.objectTable = objectTable;
processInfo.indirectCommandsLayout = deviceGeneratedLayout;
processInfo.maxSequencesCount = myCount;
// set the target of the generation (if null we would directly execute with mainCmd)
processInfo.targetCommandBuffer = generatedCmdBuffer;
// provide input data
processInfo.indirectCommandsTokenCount = 3;
processInfo.pIndirectCommandsTokens = myTokens;
// If you modify the input buffer data referenced by VkCmdProcessCommandsInfoNVX,
// ensure you have added the appropriate barriers prior generation process.
// When regenerating the content of the same reserved space, ensure prior operations have completed
VkMemoryBarrier memoryBarrier = { VK_STRUCTURE_TYPE_MEMORY_BARRIER };
memoryBarrier.srcAccessMask = ...;
memoryBarrier.dstAccessMask = VK_ACCESS_COMMAND_PROCESS_READ_BIT_NVX;
vkCmdPipelineBarrier(mainCmd,
/*srcStageMask*/VK_PIPELINE_STAGE_ALL_COMMANDS_BIT,
/*dstStageMask*/VK_PIPELINE_STAGE_COMMAND_PROCESS_BIT_NVX,
/*dependencyFlags*/0,
/*memoryBarrierCount*/1,
/*pMemoryBarriers*/&memoryBarrier,
...);
vkCmdProcessCommandsNVX(mainCmd, &processInfo);
...
// execute the secondary command buffer and ensure the processing that modifies command-buffer content
// has completed
memoryBarrier.srcAccessMask = VK_ACCESS_COMMAND_PROCESS_WRITE_BIT_NVX;
memoryBarrier.dstAccessMask = VK_ACCESS_INDIRECT_COMMAND_READ_BIT;
vkCmdPipelineBarrier(mainCmd,
/*srcStageMask*/VK_PIPELINE_STAGE_COMMAND_PROCESS_BIT_NVX,
/*dstStageMask*/VK_PIPELINE_STAGE_DRAW_INDIRECT_BIT,
/*dependencyFlags*/0,
/*memoryBarrierCount*/1,
/*pMemoryBarriers*/&memoryBarrier,
...)
vkCmdExecuteCommands(mainCmd, 1, &generatedCmdBuffer);
Version History
-
Revision 3, 2017-07-25 (Chris Hebert)
-
Correction to specification of dynamicCount for push_constant token in VkIndirectCommandsLayoutNVX. Stride was incorrectly computed as dynamicCount was not treated as byte size.
-
-
Revision 2, 2017-06-01 (Christoph Kubisch)
-
header compatibility break: add missing _TYPE to VkIndirectCommandsTokenTypeNVX and VkObjectEntryTypeNVX enums to follow Vulkan naming convention
-
behavior clarification: only allow a single work provoking token per sequence when creating a VkIndirectCommandsLayoutNVX
-
-
Revision 1, 2016-10-31 (Christoph Kubisch)
-
Initial draft
-
VK_NVX_image_view_handle
- Name String
-
VK_NVX_image_view_handle
- Extension Type
-
Device extension
- Registered Extension Number
-
31
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Eric Werness ewerness
-
- Last Modified Date
-
2018-12-07
- Contributors
-
-
Eric Werness, NVIDIA
-
Jeff Bolz, NVIDIA
-
Daniel Koch, NVIDIA
-
This extension allows applications to query an opaque handle from an image view for use as a sampled image or storage image. This provides no direct functionality itself.
New Object Types
None.
New Enum Constants
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_IMAGE_VIEW_HANDLE_INFO_NVX
-
New Enums
None.
New Structures
New Functions
Issues
None.
Version History
-
Revision 1, 2018-12-07 (Eric Werness)
-
Internal revisions
-
VK_NVX_multiview_per_view_attributes
- Name String
-
VK_NVX_multiview_per_view_attributes
- Extension Type
-
Device extension
- Registered Extension Number
-
98
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_KHR_multiview
-
- Contact
-
-
Jeff Bolz jeffbolznv
-
- Last Modified Date
-
2017-01-13
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
This extension requires the
SPV_NVX_multiview_per_view_attributes
SPIR-V extension. -
This extension requires the
GL_NVX_multiview_per_view_attributes
extension for GLSL source languages. -
This extension interacts with
VK_NV_viewport_array2
.
-
- Contributors
-
-
Jeff Bolz, NVIDIA
-
Daniel Koch, NVIDIA
-
This extension adds a new way to write shaders to be used with multiview
subpasses, where the attributes for all views are written out by a single
invocation of the vertex processing stages.
Related SPIR-V and GLSL extensions SPV_NVX_multiview_per_view_attributes
and GL_NVX_multiview_per_view_attributes
introduce per-view position and
viewport mask attributes arrays, and this extension defines how those
per-view attribute arrays are interpreted by Vulkan.
Pipelines using per-view attributes may only execute the vertex processing
stages once for all views rather than once per-view, which reduces redundant
shading work.
A subpass creation flag controls whether the subpass uses this extension. A subpass must either exclusively use this extension or not use it at all.
Some Vulkan implementations only support the position attribute varying between views in the X component. A subpass can declare via a second creation flag whether all pipelines compiled for this subpass will obey this restriction.
Shaders that use the new per-view outputs (e.g. gl_PositionPerViewNV
)
must also write the non-per-view output (gl_Position
), and the values
written must be such that gl_Position =
gl_PositionPerViewNV[gl_ViewIndex]
for all views in the subpass.
Implementations are free to either use the per-view outputs or the
non-per-view outputs, whichever would be more efficient.
If VK_NV_viewport_array2
is not also supported and enabled, the
per-view viewport mask must not be used.
New Object Types
None.
New Enum Constants
-
Extending VkStructureType
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MULTIVIEW_PER_VIEW_ATTRIBUTES_PROPERTIES_NVX
-
-
Extending VkSubpassDescriptionFlagBits
-
VK_SUBPASS_DESCRIPTION_PER_VIEW_ATTRIBUTES_BIT_NVX
-
VK_SUBPASS_DESCRIPTION_PER_VIEW_POSITION_X_ONLY_BIT_NVX
-
New Enums
None.
New Structures
New Functions
None.
New Built-In Variables
New SPIR-V Capabilities
Issues
None.
Examples
#version 450 core
#extension GL_KHX_multiview : enable
#extension GL_NVX_multiview_per_view_attributes : enable
layout(location = 0) in vec4 position;
layout(set = 0, binding = 0) uniform Block { mat4 mvpPerView[2]; } buf;
void main()
{
// Output both per-view positions and gl_Position as a function
// of gl_ViewIndex
gl_PositionPerViewNV[0] = buf.mvpPerView[0] * position;
gl_PositionPerViewNV[1] = buf.mvpPerView[1] * position;
gl_Position = buf.mvpPerView[gl_ViewIndex] * position;
}
Version History
-
Revision 1, 2017-01-13 (Jeff Bolz)
-
Internal revisions
-
VK_NV_clip_space_w_scaling
- Name String
-
VK_NV_clip_space_w_scaling
- Extension Type
-
Device extension
- Registered Extension Number
-
88
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Eric Werness ewerness-nv
-
- Last Modified Date
-
2017-02-15
- Contributors
-
-
Eric Werness, NVIDIA
-
Kedarnath Thangudu, NVIDIA
-
Virtual Reality (VR) applications often involve a post-processing step to apply a “barrel” distortion to the rendered image to correct the “pincushion” distortion introduced by the optics in a VR device. The barrel distorted image has lower resolution along the edges compared to the center. Since the original image is rendered at high resolution, which is uniform across the complete image, a lot of pixels towards the edges do not make it to the final post-processed image.
This extension provides a mechanism to render VR scenes at a non-uniform resolution, in particular a resolution that falls linearly from the center towards the edges. This is achieved by scaling the w coordinate of the vertices in the clip space before perspective divide. The clip space w coordinate of the vertices can be offset as of a function of x and y coordinates as follows:
w' = w + Ax + By
In the intended use case for viewport position scaling, an application should use a set of four viewports, one for each of the four quadrants of a Cartesian coordinate system. Each viewport is set to the dimension of the image, but is scissored to the quadrant it represents. The application should specify A and B coefficients of the w-scaling equation above, that have the same value, but different signs, for each of the viewports. The signs of A and B should match the signs of x and y for the quadrant that they represent such that the value of w' will always be greater than or equal to the original w value for the entire image. Since the offset to w, (Ax + By), is always positive, and increases with the absolute values of x and y, the effective resolution will fall off linearly from the center of the image to its edges.
New Object Types
None.
New Enum Constants
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PIPELINE_VIEWPORT_W_SCALING_STATE_CREATE_INFO_NV
-
-
Extending VkDynamicState:
-
VK_DYNAMIC_STATE_VIEWPORT_W_SCALING_NV
-
New Enums
None.
New Structures
New Functions
Issues
1) Is the pipeline struct name too long?
RESOLVED: It fits with the naming convention.
2) Separate W scaling section or fold into coordinate transformations?
RESOLVED: Leaving it as its own section for now.
Examples
VkViewport viewports[4];
VkRect2D scissors[4];
VkViewportWScalingNV scalings[4];
for (int i = 0; i < 4; i++) {
int x = (i & 2) ? 0 : currentWindowWidth / 2;
int y = (i & 1) ? 0 : currentWindowHeight / 2;
viewports[i].x = 0;
viewports[i].y = 0;
viewports[i].width = currentWindowWidth;
viewports[i].height = currentWindowHeight;
viewports[i].minDepth = 0.0f;
viewports[i].maxDepth = 1.0f;
scissors[i].offset.x = x;
scissors[i].offset.y = y;
scissors[i].extent.width = currentWindowWidth/2;
scissors[i].extent.height = currentWindowHeight/2;
const float factor = 0.15;
scalings[i].xcoeff = ((i & 2) ? -1.0 : 1.0) * factor;
scalings[i].ycoeff = ((i & 1) ? -1.0 : 1.0) * factor;
}
VkPipelineViewportWScalingStateCreateInfoNV vpWScalingStateInfo = { VK_STRUCTURE_TYPE_PIPELINE_VIEWPORT_W_SCALING_STATE_CREATE_INFO_NV };
vpWScalingStateInfo.viewportWScalingEnable = VK_TRUE;
vpWScalingStateInfo.viewportCount = 4;
vpWScalingStateInfo.pViewportWScalings = &scalings[0];
VkPipelineViewportStateCreateInfo vpStateInfo = { VK_STRUCTURE_TYPE_PIPELINE_VIEWPORT_STATE_CREATE_INFO };
vpStateInfo.viewportCount = 4;
vpStateInfo.pViewports = &viewports[0];
vpStateInfo.scissorCount = 4;
vpStateInfo.pScissors = &scissors[0];
vpStateInfo.pNext = &vpWScalingStateInfo;
Example shader to read from a w-scaled texture:
// Vertex Shader
// Draw a triangle that covers the whole screen
const vec4 positions[3] = vec4[3](vec4(-1, -1, 0, 1),
vec4( 3, -1, 0, 1),
vec4(-1, 3, 0, 1));
out vec2 uv;
void main()
{
vec4 pos = positions[ gl_VertexID ];
gl_Position = pos;
uv = pos.xy;
}
// Fragment Shader
uniform sampler2D tex;
uniform float xcoeff;
uniform float ycoeff;
out vec4 Color;
in vec2 uv;
void main()
{
// Handle uv as if upper right quadrant
vec2 uvabs = abs(uv);
// unscale: transform w-scaled image into an unscaled image
// scale: transform unscaled image int a w-scaled image
float unscale = 1.0 / (1 + xcoeff * uvabs.x + xcoeff * uvabs.y);
//float scale = 1.0 / (1 - xcoeff * uvabs.x - xcoeff * uvabs.y);
vec2 P = vec2(unscale * uvabs.x, unscale * uvabs.y);
// Go back to the right quadrant
P *= sign(uv);
Color = texture(tex, P * 0.5 + 0.5);
}
Version History
-
Revision 1, 2017-02-15 (Eric Werness)
-
Internal revisions
-
VK_NV_compute_shader_derivatives
- Name String
-
VK_NV_compute_shader_derivatives
- Extension Type
-
Device extension
- Registered Extension Number
-
202
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Pat Brown nvpbrown
-
- Last Modified Date
-
2018-07-19
- IP Status
-
No known IP claims.
- Contributors
-
-
Pat Brown, NVIDIA
-
This extension adds Vulkan support for the
SPV_NV_compute_shader_derivatives
SPIR-V extension.
The SPIR-V extension provides two new execution modes, both of which allow
compute shaders to use built-ins that evaluate compute derivatives
explicitly or implicitly.
Derivatives will be computed via differencing over a 2x2 group of shader
invocations.
The DerivativeGroupQuadsNV
execution mode assembles shader invocations
into 2x2 groups, where each group has x and y coordinates of the local
invocation ID of the form (2m+{0,1}, 2n+{0,1}).
The DerivativeGroupLinearNV
execution mode assembles shader invocations
into 2x2 groups, where each group has local invocation index values of the
form 4m+{0,1,2,3}.
New Object Types
None.
New Enum Constants
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_COMPUTE_SHADER_DERIVATIVES_FEATURES_NV
-
New Enums
None.
New Structures
New Functions
None.
New SPIR-V Capability
Issues
(1) Should we specify that the groups of four shader invocations used for derivatives in a compute shader are the same groups of four invocations that form a “quad” in shader subgroups?
RESOLVED: Yes.
Examples
None.
Version History
-
Revision 1, 2018-07-19 (Pat Brown)
-
Initial draft
-
VK_NV_cooperative_matrix
- Name String
-
VK_NV_cooperative_matrix
- Extension Type
-
Device extension
- Registered Extension Number
-
250
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Jeff Bolz jeffbolznv
-
- Last Modified Data
-
2019-02-05
- Contributors
-
-
Jeff Bolz, NVIDIA
-
Markus Tavenrath, NVIDIA
-
Daniel Koch, NVIDIA
-
This extension adds support for using cooperative matrix types in SPIR-V. Cooperative matrix types are medium-sized matrices that are primarily supported in compute shaders, where the storage for the matrix is spread across all invocations in some scope (usually a subgroup) and those invocations cooperate to efficiently perform matrix multiplies.
Cooperative matrix types are defined by the
SPV_NV_cooperative_matrix
SPIR-V extension and can be used with the
GL_NV_cooperative_matrix
GLSL extension.
This extension includes support for enumerating the matrix types and dimensions that are supported by the implementation.
New Object Types
None.
New Enum Constants
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_COOPERATIVE_MATRIX_FEATURES_NV
-
VK_STRUCTURE_TYPE_COOPERATIVE_MATRIX_PROPERTIES_NV
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_COOPERATIVE_MATRIX_PROPERTIES_NV
-
New Enums
New Structures
New Functions
New SPIR-V Capabilities
Issues
(1) What matrix properties will be supported in practice?
RESOLVED: In NVIDIA’s initial implementation, we will support:
-
AType = BType = fp16 CType = DType = fp16 MxNxK = 16x8x16 scope = Subgroup
-
AType = BType = fp16 CType = DType = fp16 MxNxK = 16x8x8 scope = Subgroup
-
AType = BType = fp16 CType = DType = fp32 MxNxK = 16x8x16 scope = Subgroup
-
AType = BType = fp16 CType = DType = fp32 MxNxK = 16x8x8 scope = Subgroup
Version History
-
Revision 1, 2019-02-05 (Jeff Bolz)
-
Internal revisions
-
VK_NV_corner_sampled_image
- Name String
-
VK_NV_corner_sampled_image
- Extension Type
-
Device extension
- Registered Extension Number
-
51
- Revision
-
2
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Daniel Koch dgkoch
-
- Last Modified Date
-
2018-08-13
- Contributors
-
-
Jeff Bolz, NVIDIA
-
Pat Brown, NVIDIA
-
Chris Lentini, NVIDIA
-
This extension adds support for a new image organization, which this extension refers to as “corner-sampled” images. A corner-sampled image differs from a conventional image in the following ways:
-
Texels are centered on integer coordinates. See Unnormalized Texel Coordinate Operations
-
Normalized coordinates are scaled using coord * (dim - 1) rather than coord * dim, where dim is the size of one dimension of the image. See normalized texel coordinate transform.
-
Partial derivatives are scaled using coord * (dim - 1) rather than coord * dim. See Scale Factor Operation.
-
Calculation of the next higher lod size goes according to ⌈dim / 2⌉ rather than ⌊dim / 2⌋. See Image Miplevel Sizing.
-
The minimum level size is 2x2 for 2D images and 2x2x2 for 3D images. See Image Miplevel Sizing.
This image organization is designed to facilitate a system like Ptex with separate textures for each face of a subdivision or polygon mesh. Placing sample locations at pixel corners allows applications to maintain continuity between adjacent patches by duplicating values along shared edges. Additionally, using the modified mipmapping logic along with texture dimensions of the form 2n+1 allows continuity across shared edges even if the adjacent patches use different level-of-detail values.
New Object Types
None.
New Enum Constants
-
Extending VkStructureType
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_CORNER_SAMPLED_IMAGE_FEATURES_NV
-
-
Extending VkImageCreateFlagBits
-
VK_IMAGE_CREATE_CORNER_SAMPLED_BIT_NV
-
New Enums
None.
New Structures
New Functions
None.
New Built-In Variables
None.
New SPIR-V Capabilities
None.
Issues
-
What should this extension be named?
DISCUSSION: While naming this extension, we chose the most distinctive aspect of the image organization and referred to such images as “corner-sampled images”. As a result, we decided to name the extension NV_corner_sampled_image.
-
Do we need a format feature flag so formats can advertise if they support corner-sampling?
DISCUSSION: Currently NVIDIA supports this for all 2D and 3D formats, but not for cubemaps or depth-stencil formats. A format feature might be useful if other vendors would only support this on some formats.
-
Do integer texel coordinates have a different range for corner-sampled images?
RESOLVED: No, these are unchanged.
-
Do unnormalized sampler coordinates work with corner-sampled images? Are there any functional differences?
RESOLVED: Yes they work. Unnormalized coordinates are treated as already scaled for corner-sample usage.
-
Should we have a diagram in the “Image Operations” chapter demonstrating different texel sampling locations?
UNRESOLVED: Probaby, but later.
Version History
-
Revision 1, 2018-08-14 (Daniel Koch)
-
Internal revisions
-
-
Revision 2, 2018-08-14 (Daniel Koch)
-
???
-
VK_NV_coverage_reduction_mode
- Name String
-
VK_NV_coverage_reduction_mode
- Extension Type
-
Device extension
- Registered Extension Number
-
251
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_NV_framebuffer_mixed_samples
-
- Contact
-
-
Kedarnath Thangudu kthangudu
-
- Last Modified Date
-
2019-01-29
- Contributors
-
-
Kedarnath Thangudu, NVIDIA
-
Jeff Bolz, NVIDIA
-
When using a framebuffer with mixed samples, a per-fragment coverage reduction operation is performed which generates a color sample mask from the coverage mask. This extension defines the following modes to control how this reduction is performed.
-
Merge: When there are more raster samples than color samples, there is an implementation dependent association of each raster sample to a color sample. In the merge mode, the reduced color sample mask is computed such that the bit for each color sample is 1 if any of the associated bits in the fragment’s coverage is on, and 0 otherwise. This is the default mode.
-
Truncate: When there are more raster samples (N) than color samples(M), there is one to one association of the first M raster samples to the M color samples and the coverage bits for the other raster samples are ignored.
When the number of raster samples is equal to the color samples, there is a one to one mapping between them in either of the above modes.
The new command
vkGetPhysicalDeviceSupportedFramebufferMixedSamplesCombinationsNV can
be used to query the various raster, color, depth/stencil sample count and
reduction mode combinations that are supported by the implementation.
This extension would allow an implementation to support the behavior of both
VK_NV_framebuffer_mixed_samples
and VK_AMD_mixed_attachment_samples
extensions simultaneously.
New Object Types
None.
New Enum Constants
-
Extending VkStructureType
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_COVERAGE_REDUCTION_MODE_FEATURES_NV
-
VK_STRUCTURE_TYPE_PIPELINE_COVERAGE_REDUCTION_STATE_CREATE_INFO_NV
-
VK_STRUCTURE_TYPE_FRAMEBUFFER_MIXED_SAMPLES_COMBINATION_NV
-
New Structures
Issues
None.
Version History
-
Revision 1, 2019-01-29 (Kedarnath Thangudu)
-
Internal revisions
-
VK_NV_dedicated_allocation_image_aliasing
- Name String
-
VK_NV_dedicated_allocation_image_aliasing
- Extension Type
-
Device extension
- Registered Extension Number
-
241
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_KHR_dedicated_allocation
-
- Contact
-
-
Nuno Subtil nsubtil
-
- Last Modified Date
-
2019-01-04
- Contributors
-
-
Nuno Subtil, NVIDIA
-
Jeff Bolz, NVIDIA
-
Eric Werness, NVIDIA
-
Axel Gneiting, id Software
-
This extension allows applications to alias images on dedicated allocations, subject to specific restrictions: the extent and the number of layers in the image being aliased must be smaller than or equal to those of the original image for which the allocation was created, and every other image parameter must match.
New Object Types
None.
New Enum Constants
-
Extending VkStructureType
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DEDICATED_ALLOCATION_IMAGE_ALIASING_FEATURES_NV
-
New Enums
None.
New Structures
New Functions
None.
Issues
None.
Version History
-
Revision 1, 2019-01-04 (Nuno Subtil)
-
Internal revisions
-
VK_NV_device_diagnostic_checkpoints
- Name String
-
VK_NV_device_diagnostic_checkpoints
- Extension Type
-
Device extension
- Registered Extension Number
-
207
- Revision
-
2
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Nuno Subtil nsubtil
-
- Last Modified Date
-
2018-07-16
- Contributors
-
-
Oleg Kuznetsov, NVIDIA
-
Alex Dunn, NVIDIA
-
Jeff Bolz, NVIDIA
-
Eric Werness, NVIDIA
-
Daniel Koch, NVIDIA
-
This extension allows applications to insert markers in the command stream and associate them with custom data.
If a device lost error occurs, the application may then query the implementation for the last markers to cross specific implementation-defined pipeline stages, in order to narrow down which commands were executing at the time and might have caused the failure.
New Object Types
None.
New Enum Constants
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_CHECKPOINT_DATA_NV
-
VK_STRUCTURE_TYPE_QUEUE_FAMILY_CHECKPOINT_PROPERTIES_NV
New Enums
None.
New Structures
New Functions
Issues
None yet!
Version History
-
Revision 1, 2018-07-16 (Nuno Subtil)
-
Internal revisions
-
-
Revision 2, 2018-07-16 (Nuno Subtil)
-
???
-
VK_NV_fill_rectangle
- Name String
-
VK_NV_fill_rectangle
- Extension Type
-
Device extension
- Registered Extension Number
-
154
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Jeff Bolz jeffbolznv
-
- Last Modified Date
-
2017-05-22
- Contributors
-
-
Jeff Bolz, NVIDIA
-
This extension adds a new VkPolygonMode enum
where a triangle is
rasterized by computing and filling its axis-aligned screen-space bounding
box, disregarding the actual triangle edges.
This can be useful for drawing a rectangle without being split into two
triangles with an internal edge.
It is also useful to minimize the number of primitives that need to be
drawn, particularly for a user interface.
New Object Types
None.
New Enum Constants
-
Extending VkPolygonMode
-
VK_POLYGON_MODE_FILL_RECTANGLE_NV
-
New Enums
None.
New Structures
None.
New Functions
None.
Issues
None.
Version History
-
Revision 1, 2017-05-22 (Jeff Bolz)
-
Internal revisions
-
VK_NV_fragment_coverage_to_color
- Name String
-
VK_NV_fragment_coverage_to_color
- Extension Type
-
Device extension
- Registered Extension Number
-
150
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Jeff Bolz jeffbolznv
-
- Last Modified Date
-
2017-05-21
- Contributors
-
-
Jeff Bolz, NVIDIA
-
This extension allows the fragment coverage value, represented as an integer
bitmask, to be substituted for a color output being written to a
single-component color attachment with integer components (e.g.
VK_FORMAT_R8_UINT
).
The functionality provided by this extension is different from simply
writing the SampleMask
fragment shader output, in that the coverage
value written to the framebuffer is taken after stencil test and depth test,
as well as after fragment operations such as alpha-to-coverage.
This functionality may be useful for deferred rendering algorithms, where the second pass needs to know which samples belong to which original fragments.
New Object Types
None.
New Enum Constants
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PIPELINE_COVERAGE_TO_COLOR_STATE_CREATE_INFO_NV
-
New Structures
New Functions
None.
Issues
None.
Version History
-
Revision 1, 2017-05-21 (Jeff Bolz)
-
Internal revisions
-
VK_NV_fragment_shader_barycentric
- Name String
-
VK_NV_fragment_shader_barycentric
- Extension Type
-
Device extension
- Registered Extension Number
-
204
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Pat Brown nvpbrown
-
- Last Modified Date
-
2018-08-03
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
Requires the
SPV_NV_fragment_shader_barycentric
SPIR-V extension. -
Requires the
GL_NV_fragment_shader_barycentric
extension for GLSL source languages.
-
- Contributors
-
-
Pat Brown, NVIDIA
-
Daniel Koch, NVIDIA
-
This extension adds support for the following SPIR-V extension in Vulkan:
The extension provides access to three additional fragment shader variable decorations in SPIR-V:
-
PerVertexNV
, which indicates that a fragment shader input will not have interpolated values, but instead must be accessed with an extra array index that identifies one of the vertices of the primitive producing the fragment -
BaryCoordNV
, which indicates that the variable is a three-component floating-point vector holding barycentric weights for the fragment produced using perspective interpolation -
BaryCoordNoPerspNV
, which indicates that the variable is a three-component floating-point vector holding barycentric weights for the fragment produced using linear interpolation
When using GLSL source-based shader languages, the following variables from
GL_NV_fragment_shader_barycentric
maps to these SPIR-V built-in
decorations:
-
in vec3 gl_BaryCoordNV;
→BaryCoordNV
-
in vec3 gl_BaryCoordNoPerspNV;
→BaryCoordNoPerspNV
GLSL variables declared using the __pervertexNV
GLSL qualifier are
expected to be decorated with PerVertexNV
in SPIR-V.
New Object Types
None.
New Enum Constants
-
Extending VkStructureType
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FRAGMENT_SHADER_BARYCENTRIC_FEATURES_NV
-
New Enums
None.
New Structures
None.
New Functions
None.
New Built-In Variables
New SPIR-V Decorations
New SPIR-V Capabilities
Issues
(1) The AMD_shader_explicit_vertex_parameter extension provides similar functionality. Why write a new extension, and how is this extension different?
RESOLVED: For the purposes of Vulkan/SPIR-V, we chose to implement a separate extension due to several functional differences.
First, the hardware supporting this extension can provide a three-component
barycentric weight vector for variables decorated with BaryCoordNV
,
while variables decorated with BaryCoordSmoothAMD
provide only two
components.
In some cases, it may be more efficient to explicitly interpolate an
attribute via:
float value = (baryCoordNV.x * v[0].attrib + baryCoordNV.y * v[1].attrib + baryCoordNV.z * v[2].attrib);
instead of
float value = (baryCoordSmoothAMD.x * (v[0].attrib - v[2].attrib) + baryCoordSmoothAMD.y * (v[1].attrib - v[2].attrib) + v[2].attrib);
Additionally, the semantics of the decoration BaryCoordPullModelAMD
do
not appear to map to anything supported by the initial hardware
implementation of this extension.
This extension provides a smaller number of decorations than the AMD
extension, as we expect that shaders could derive variables decorated with
things like BaryCoordNoPerspCentroidAMD
with explicit attribute
interpolation instructions.
One other relevant difference is that explicit per-vertex attribute access
using this extension does not require a constant vertex number.
(2) Why do the built-in SPIR-V decorations for this extension include two
separate built-ins BaryCoordNV
and BaryCoordNoPerspNV
when a
“no perspective” variable could be decorated with BaryCoordNV
and
NoPerspective
?
RESOLVED: The SPIR-V extension for this feature chose to mirror the behavior of the GLSL extension, which provides two built-in variables. Additionally, it’s not clear that its a good idea (or even legal) to have two variables using the “same attribute”, but with different interpolation modifiers.
Version History
-
Revision 1, 2018-08-03 (Pat Brown)
-
Internal revisions
-
VK_NV_framebuffer_mixed_samples
- Name String
-
VK_NV_framebuffer_mixed_samples
- Extension Type
-
Device extension
- Registered Extension Number
-
153
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Jeff Bolz jeffbolznv
-
- Last Modified Date
-
2017-06-04
- Contributors
-
-
Jeff Bolz, NVIDIA
-
This extension allows multisample rendering with a raster and depth/stencil sample count that is larger than the color sample count. Rasterization and the results of the depth and stencil tests together determine the portion of a pixel that is “covered”. It can be useful to evaluate coverage at a higher frequency than color samples are stored. This coverage is then “reduced” to a collection of covered color samples, each having an opacity value corresponding to the fraction of the color sample covered. The opacity can optionally be blended into individual color samples.
Rendering with fewer color samples than depth/stencil samples greatly reduces the amount of memory and bandwidth consumed by the color buffer. However, converting the coverage values into opacity introduces artifacts where triangles share edges and may not be suitable for normal triangle mesh rendering.
One expected use case for this functionality is Stencil-then-Cover path rendering (similar to the OpenGL GL_NV_path_rendering extension). The stencil step determines the coverage (in the stencil buffer) for an entire path at the higher sample frequency, and then the cover step draws the path into the lower frequency color buffer using the coverage information to antialias path edges. With this two-step process, internal edges are fully covered when antialiasing is applied and there is no corruption on these edges.
The key features of this extension are:
-
It allows render pass and framebuffer objects to be created where the number of samples in the depth/stencil attachment in a subpass is a multiple of the number of samples in the color attachments in the subpass.
-
A coverage reduction step is added to Fragment Operations which converts a set of covered raster/depth/stencil samples to a set of color samples that perform blending and color writes. The coverage reduction step also includes an optional coverage modulation step, multiplying color values by a fractional opacity corresponding to the number of associated raster/depth/stencil samples covered.
New Object Types
None.
New Enum Constants
-
Extending VkStructureType
-
VK_STRUCTURE_TYPE_PIPELINE_COVERAGE_MODULATION_STATE_CREATE_INFO_NV
-
New Structures
New Functions
None.
Issues
None.
Version History
-
Revision 1, 2017-06-04 (Jeff Bolz)
-
Internal revisions
-
VK_NV_geometry_shader_passthrough
- Name String
-
VK_NV_geometry_shader_passthrough
- Extension Type
-
Device extension
- Registered Extension Number
-
96
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Daniel Koch dgkoch
-
- Last Modified Date
-
2017-02-15
- Interactions and External Dependencies
-
-
This extension requires the
SPV_NV_geometry_shader_passthrough
SPIR-V extension. -
This extension requires the
GL_NV_geometry_shader_passthrough
extension for GLSL source languages. -
This extension requires the
geometryShader
feature.
-
- Contributors
-
-
Piers Daniell, NVIDIA
-
Jeff Bolz, NVIDIA
-
This extension adds support for the following SPIR-V extension in Vulkan:
-
SPV_NV_geometry_shader_passthrough
Geometry shaders provide the ability for applications to process each
primitive sent through the graphics pipeline using a programmable shader.
However, one common use case treats them largely as a “passthrough”.
In this use case, the bulk of the geometry shader code simply copies inputs
from each vertex of the input primitive to corresponding outputs in the
vertices of the output primitive.
Such shaders might also compute values for additional built-in or
user-defined per-primitive attributes (e.g., Layer
) to be assigned to
all the vertices of the output primitive.
This extension provides access to the PassthroughNV
decoration under
the GeometryShaderPassthroughNV
capability.
Adding this to a geometry shader input variable specifies that the values of
this input are copied to the corresponding vertex of the output primitive.
When using GLSL source-based shading languages, the passthrough
layout
qualifier from GL_NV_geometry_shader_passthrough
maps to the
PassthroughNV
decoration.
To use the passthrough
layout, in GLSL the
GL_NV_geometry_shader_passthrough
extension must be enabled.
Behaviour is described in the GL_NV_geometry_shader_passthrough
extension
specification.
New Object Types
None.
New Enum Constants
None.
New Enums
None.
New Structures
None.
New Functions
None.
New Built-In Variables
None.
New Variable Decoration
New SPIR-V Capabilities
Issues
1) Should we require or allow a passthrough geometry shader to specify the output layout qualifiers for the output primitive type and maximum vertex count in the SPIR-V?
RESOLVED: Yes they should be required in the SPIR-V. Per GL_NV_geometry_shader_passthrough they are not permitted in the GLSL source shader, but SPIR-V is lower-level. It is straightforward for the GLSL compiler to infer them from the input primitive type and to explicitly emit them in the SPIR-V according to the following table.
Input Layout | Implied Output Layout |
---|---|
points |
|
lines |
|
triangles |
|
2) How does interface matching work with passthrough geometry shaders?
RESOLVED: This is described in Passthrough Interface Matching.
In GL when using passthough geometry shaders in separable mode, all inputs
must also be explicitly assigned location layout qualifiers.
In Vulkan all SPIR-V shader inputs (except built-ins) must also have
location decorations specified.
Redeclarations of built-in varables that add the passthrough layout
qualifier are exempted from the rule requiring location assignment because
built-in variables do not have locations and are matched by BuiltIn
decoration.
Sample Code
Consider the following simple geometry shader in unextended GLSL:
layout(triangles) in;
layout(triangle_strip) out;
layout(max_vertices=3) out;
in Inputs {
vec2 texcoord;
vec4 baseColor;
} v_in[];
out Outputs {
vec2 texcoord;
vec4 baseColor;
};
void main()
{
int layer = compute_layer();
for (int i = 0; i < 3; i++) {
gl_Position = gl_in[i].gl_Position;
texcoord = v_in[i].texcoord;
baseColor = v_in[i].baseColor;
gl_Layer = layer;
EmitVertex();
}
}
In this shader, the inputs gl_Position
, Inputs.texcoord
, and
Inputs.baseColor
are simply copied from the input vertex to the
corresponding output vertex.
The only “interesting” work done by the geometry shader is computing and
emitting a gl_Layer
value for the primitive.
The following geometry shader, using this extension, is equivalent:
#extension GL_NV_geometry_shader_passthrough : require
layout(triangles) in;
// No output primitive layout qualifiers required.
// Redeclare gl_PerVertex to pass through "gl_Position".
layout(passthrough) in gl_PerVertex {
vec4 gl_Position;
} gl_in[];
// Declare "Inputs" with "passthrough" to automatically copy members.
layout(passthrough) in Inputs {
vec2 texcoord;
vec4 baseColor;
} v_in[];
// No output block declaration required.
void main()
{
// The shader simply computes and writes gl_Layer. We don't
// loop over three vertices or call EmitVertex().
gl_Layer = compute_layer();
}
Version History
-
Revision 1, 2017-02-15 (Daniel Koch)
-
Internal revisions
-
VK_NV_mesh_shader
- Name String
-
VK_NV_mesh_shader
- Extension Type
-
Device extension
- Registered Extension Number
-
203
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Christoph Kubisch pixeljetstream
-
- Last Modified Date
-
2018-07-19
- Contributors
-
-
Pat Brown, NVIDIA
-
Jeff Bolz, NVIDIA
-
Daniel Koch, NVIDIA
-
Piers Daniell, NVIDIA
-
Pierre Boudier, NVIDIA
-
This extension provides a new mechanism allowing applications to generate collections of geometric primitives via programmable mesh shading. It is an alternative to the existing programmable primitive shading pipeline, which relied on generating input primitives by a fixed function assembler as well as fixed function vertex fetch.
There are new programmable shader types — the task and mesh shader — to generate these collections to be processed by fixed-function primitive assembly and rasterization logic. When the task and mesh shaders are dispatched, they replace the standard programmable vertex processing pipeline, including vertex array attribute fetching, vertex shader processing, tessellation, and the geometry shader processing.
This extension also adds support for the following SPIR-V extension in Vulkan:
New Object Types
None.
New Enum Constants
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MESH_SHADER_FEATURES_NV
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MESH_SHADER_PROPERTIES_NV
-
-
Extending VkShaderStageFlagBits
-
VK_SHADER_STAGE_TASK_BIT_NV
-
VK_SHADER_STAGE_MESH_BIT_NV
-
-
Extending VkPipelineStageFlagBits
-
VK_PIPELINE_STAGE_TASK_SHADER_BIT_NV
-
VK_PIPELINE_STAGE_MESH_SHADER_BIT_NV
-
New Enums
None.
New Structures
New or Modified Built-In Variables
-
(modified)
Position
-
(modified)
PointSize
-
(modified)
ClipDistance
-
(modified)
CullDistance
-
(modified)
PrimitiveId
-
(modified)
Layer
-
(modified)
ViewportIndex
-
(modified)
WorkgroupSize
-
(modified)
WorkgroupId
-
(modified)
LocalInvocationId
-
(modified)
GlobalInvocationId
-
(modified)
LocalInvocationIndex
-
(modified)
DrawIndex
-
(modified)
ViewportMaskNV
-
(modified)
PositionPerViewNV
-
(modified)
ViewportMaskPerViewNV
New SPIR-V Capability
Issues
-
How to name this extension?
RESOLVED: VK_NV_mesh_shader
Other options considered:
-
VK_NV_mesh_shading
-
VK_NV_programmable_mesh_shading
-
VK_NV_primitive_group_shading
-
VK_NV_grouped_drawing
-
-
Do we need a new VkPrimitiveTopology?
RESOLVED: NO, we skip the InputAssembler stage
-
Should we allow Instancing?
RESOLVED: NO, there is no fixed function input, other than the IDs. However, allow offsetting with a "first" value.
-
Should we use existing vkCmdDraw or introduce new functions?
RESOLVED: Introduce new functions.
New functions make it easier to separate from "programmable primitive shading" chapter, less "dual use" language about existing functions having alternative behavior. The text around the existing "draws" is heavily based around emitting vertices.
-
If new functions, how to name?
RESOLVED: CmdDrawMeshTasks*
Other options considered:
-
CmdDrawMeshed
-
CmdDrawTasked
-
CmdDrawGrouped
-
-
Should VK_SHADER_STAGE_ALL_GRAPHICS be updated to include the new stages?
RESOLVED: No. If an application were to be recompiled with headers that include additional shader stage bits in VK_SHADER_STAGE_ALL_GRAPHICS, then the previously valid application would no longer be valid on implementations that don’t support mesh or task shaders. This means the change would not be backwards compatible. It’s too bad VkShaderStageFlagBits doesn’t have a dedicated "all supported graphics stages" bit like VK_PIPELINE_STAGE_ALL_GRAPHICS_BIT, which would have avoided this problem.
Version History
-
Revision 1, 2018-07-19 (Christoph Kubisch, Daniel Koch)
-
Internal revisions
-
VK_NV_ray_tracing
- Name String
-
VK_NV_ray_tracing
- Extension Type
-
Device extension
- Registered Extension Number
-
166
- Revision
-
3
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_KHR_get_memory_requirements2
-
- Contact
-
-
Eric Werness ewerness
-
- Last Modified Date
-
2018-11-20
- Interactions and External Dependencies
-
-
This extension requires the
SPV_NV_ray_tracing
SPIR-V extension. -
This extension requires the
GL_NV_ray_tracing
extension for GLSL source languages.
-
- Contributors
-
-
Eric Werness, NVIDIA
-
Ashwin Lele, NVIDIA
-
Robert Stepinski, NVIDIA
-
Nuno Subtil, NVIDIA
-
Christoph Kubisch, NVIDIA
-
Martin Stich, NVIDIA
-
Daniel Koch, NVIDIA
-
Jeff Bolz, NVIDIA
-
Joshua Barczak, Intel
-
Tobias Hector, AMD
-
Henrik Rydgard, NVIDIA
-
Pascal Gautron, NVIDIA
-
Rasterization has been the dominant method to produce interactive graphics, but increasing performance of graphics hardware has made ray tracing a viable option for interactive rendering. Being able to integrate ray tracing with traditional rasterization makes it easier for applications to incrementally add ray traced effects to existing applications or to do hybrid approaches with rasterization for primary visibility and ray tracing for secondary queries.
To enable ray tracing, this extension adds a few different categories of new functionality:
-
Acceleration structure objects and build commands
-
A new pipeline type with new shader domains
-
An indirection table to link shader groups with acceleration structure items
This extension adds support for the following SPIR-V extension in Vulkan:
-
SPV_NV_ray_tracing
New Object Types
New Enum Constants
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_RAY_TRACING_PIPELINE_CREATE_INFO_NV
-
VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_CREATE_INFO_NV
-
VK_STRUCTURE_TYPE_GEOMETRY_NV
-
VK_STRUCTURE_TYPE_GEOMETRY_TRIANGLES_NV
-
VK_STRUCTURE_TYPE_GEOMETRY_AABB_NV
-
VK_STRUCTURE_TYPE_BIND_ACCELERATION_STRUCTURE_MEMORY_INFO_NV
-
VK_STRUCTURE_TYPE_WRITE_DESCRIPTOR_SET_ACCELERATION_STRUCTURE_NV
-
VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_INFO_NV
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_RAY_TRACING_PROPERTIES_NV
-
VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_INFO_NV
-
VK_STRUCTURE_TYPE_RAY_TRACING_SHADER_GROUP_CREATE_INFO_NV
-
-
Extending VkShaderStageFlagBits:
-
VK_SHADER_STAGE_RAYGEN_BIT_NV
-
VK_SHADER_STAGE_ANY_HIT_BIT_NV
-
VK_SHADER_STAGE_CLOSEST_HIT_BIT_NV
-
VK_SHADER_STAGE_MISS_BIT_NV
-
VK_SHADER_STAGE_INTERSECTION_BIT_NV
-
VK_SHADER_STAGE_CALLABLE_BIT_NV
-
-
Extending VkPipelineStageFlagBits:
-
VK_PIPELINE_STAGE_RAY_TRACING_SHADER_BIT_NV
-
VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_NV
-
-
Extending VkBufferUsageFlagBits:
-
VK_BUFFER_USAGE_RAY_TRACING_BIT_NV
-
-
Extending VkPipelineBindPoint:
-
VK_PIPELINE_BIND_POINT_RAY_TRACING_NV
-
-
Extending VkDescriptorType:
-
VK_DESCRIPTOR_TYPE_ACCELERATION_STRUCTURE_NV
-
-
Extending VkAccessFlagBits:
-
VK_ACCESS_ACCELERATION_STRUCTURE_READ_BIT_NV
-
VK_ACCESS_ACCELERATION_STRUCTURE_WRITE_BIT_NV
-
-
Extending VkQueryType:
-
VK_QUERY_TYPE_ACCELERATION_STRUCTURE_COMPACTED_SIZE_NV
-
-
Extending VkPipelineCreateFlagBits:
-
VK_PIPELINE_CREATE_DEFER_COMPILE_BIT_NV
-
-
Extending VkIndexType:
-
VK_INDEX_TYPE_NONE_NV
-
New Enums
New Structures
New Functions
New or Modified Built-In Variables
New SPIR-V Capabilities
Issues
1) Are there issues?
RESOLVED: Yes.
Sample Code
Example ray generation GLSL shader
#version 450 core
#extension GL_NV_ray_tracing : require
layout(set = 0, binding = 0, rgba8) uniform image2D image;
layout(set = 0, binding = 1) uniform accelerationStructureNV as;
layout(location = 0) rayPayloadNV float payload;
void main()
{
vec4 col = vec4(0, 0, 0, 1);
vec3 origin = vec3(float(gl_LaunchIDNV.x)/float(gl_LaunchSizeNV.x), float(gl_LaunchIDNV.y)/float(gl_LaunchSizeNV.y), 1.0);
vec3 dir = vec3(0.0, 0.0, -1.0);
traceNV(as, 0, 0xff, 0, 1, 0, origin, 0.0, dir, 1000.0, 0);
col.y = payload;
imageStore(image, ivec2(gl_LaunchIDNV.xy), col);
}
Version History
-
Revision 1, 2018-09-11 (Robert Stepinski, Nuno Subtil, Eric Werness)
-
Internal revisions
-
-
Revision 2, 2018-10-19 (Eric Werness)
-
rename to VK_NV_ray_tracing, add support for callables.
-
too many updates to list
-
-
Revision 3, 2018-11-20 (Daniel Koch)
-
update to use InstanceId instead of InstanceIndex as implemented.
-
VK_NV_representative_fragment_test
- Name String
-
VK_NV_representative_fragment_test
- Extension Type
-
Device extension
- Registered Extension Number
-
167
- Revision
-
2
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Kedarnath Thangudu kthangudu
-
- Last Modified Date
-
2018-09-13
- Contributors
-
-
Kedarnath Thangudu, NVIDIA
-
Christoph Kubisch, NVIDIA
-
Pierre Boudier, NVIDIA
-
Pat Brown, NVIDIA
-
Jeff Bolz, NVIDIA
-
Eric Werness, NVIDIA
-
This extension provides a new representative fragment test that allows implementations to reduce the amount of rasterization and fragment processing work performed for each point, line, or triangle primitive. For any primitive that produces one or more fragments that pass all other early fragment tests, the implementation is permitted to choose one or more “representative” fragments for processing and discard all other fragments. For draw calls rendering multiple points, lines, or triangles arranged in lists, strips, or fans, the representative fragment test is performed independently for each of those primitives.
This extension is useful for applications that use an early render pass to determine the full set of primitives that would be visible in the final scene. In this render pass, such applications would set up a fragment shader that enables early fragment tests and writes to an image or shader storage buffer to record the ID of the primitive that generated the fragment. Without this extension, the shader would record the ID separately for each visible fragment of each primitive. With this extension, fewer stores will be performed, particularly for large primitives.
The representative fragment test has no effect if early fragment tests are not enabled via the fragment shader. The set of fragments discarded by the representative fragment test is implementation-dependent and may vary from frame to frame. In some cases, the representative fragment test may not discard any fragments for a given primitive.
New Object Types
None.
New Enum Constants
-
Extending VkStructureType
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_REPRESENTATIVE_FRAGMENT_TEST_FEATURES_NV
-
VK_STRUCTURE_TYPE_PIPELINE_REPRESENTATIVE_FRAGMENT_TEST_STATE_CREATE_INFO_NV
-
New Enums
None.
New Structures
New Functions
None.
Issues
(1) Is the representative fragment test guaranteed to have any effect?
RESOLVED: No. As specified, we only guarantee that each primitive with at least one fragment that passes prior tests will have one fragment passing the representative fragment tests. We don’t guarantee that any particular fragment will fail the test.
In the initial implementation of this extension, the representative fragment test is treated as an optimization that may be completely disabled for some pipeline states. This feature was designed for a use case where the fragment shader records information on individual primitives using shader storage buffers or storage images, with no writes to color or depth buffers.
(2) Will the set of fragments that pass the representative fragment test be repeatable if you draw the same scene over and over again?
RESOLVED: No. The set of fragments that pass the representative fragment test is implementation-dependent and may vary due to the timing of operations performed by the GPU.
(3) What happens if you enable the representative fragment test with writes to color and/or depth render targets enabled?
RESOLVED: If writes to the color or depth buffer are enabled, they will be performed for any fragments that survive the relevant tests. Any fragments that fail the representative fragment test will not update color buffers. For the use cases intended for this feature, we don’t expect color or depth writes to be enabled.
(4) How do derivatives and automatic texture level of detail computations work with the representative fragment test enabled?
RESOLVED: If a fragment shader uses derivative functions or texture lookups using automatic level of detail computation, derivatives will be computed identically whether or not the representative fragment test is enabled. For the use cases intended for this feature, we don’t expect the use of derivatives in the fragment shader.
Version History
-
Revision 2, 2018-09-13 (pbrown)
-
Add issues.
-
-
Revision 1, 2018-08-22 (Kedarnath Thangudu)
-
Internal Revisions
-
VK_NV_sample_mask_override_coverage
- Name String
-
VK_NV_sample_mask_override_coverage
- Extension Type
-
Device extension
- Registered Extension Number
-
95
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Piers Daniell pdaniell-nv
-
- Last Modified Date
-
2016-12-08
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
This extension requires the
SPV_NV_sample_mask_override_coverage
SPIR-V extension. -
This extension requires the
GL_NV_sample_mask_override_coverage
extension for GLSL source languages.
-
- Contributors
-
-
Daniel Koch, NVIDIA
-
Jeff Bolz, NVIDIA
-
This extension adds support for the following SPIR-V extension in Vulkan:
-
SPV_NV_sample_mask_override_coverage
The extension provides access to the OverrideCoverageNV
decoration
under the SampleMaskOverrideCoverageNV
capability.
Adding this decoration to a variable with the SampleMask
builtin
decoration allows the shader to modify the coverage mask and affect which
samples are used to process the fragment.
When using GLSL source-based shader languages, the override_coverage
layout qualifier from GL_NV_sample_mask_override_coverage
maps to the
OverrideCoverageNV
decoration.
To use the override_coverage
layout qualifier in GLSL the
GL_NV_sample_mask_override_coverage
extension must be enabled.
Behavior is described in the GL_NV_sample_mask_override_coverage
extension
spec.
New Object Types
None.
New Enum Constants
None.
New Enums
None.
New Structures
None.
New Functions
None.
New Built-In Variables
None.
New Variable Decoration
New SPIR-V Capabilities
Issues
None.
Version History
-
Revision 1, 2016-12-08 (Piers Daniell)
-
Internal revisions
-
VK_NV_scissor_exclusive
- Name String
-
VK_NV_scissor_exclusive
- Extension Type
-
Device extension
- Registered Extension Number
-
206
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Pat Brown nvpbrown
-
- Last Modified Date
-
2018-07-31
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
None
- Contributors
-
-
Pat Brown, NVIDIA
-
Jeff Bolz, NVIDIA
-
Piers Daniell, NVIDIA
-
Daniel Koch, NVIDIA
-
This extension adds support for an exclusive scissor test to Vulkan. The exclusive scissor test behaves like the scissor test, except that the exclusive scissor test fails for pixels inside the corresponding rectangle and passes for pixels outside the rectangle. If the same rectangle is used for both the scissor and exclusive scissor tests, the exclusive scissor test will pass if and only if the scissor test fails.
New Object Types
None.
New Enum Constants
-
Extending VkStructureType
-
VK_STRUCTURE_TYPE_PIPELINE_VIEWPORT_EXCLUSIVE_SCISSOR_STATE_CREATE_INFO_NV
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_EXCLUSIVE_SCISSOR_FEATURES_NV
-
-
Extending VkDynamicState
-
VK_DYNAMIC_STATE_EXCLUSIVE_SCISSOR_NV
-
New Enums
None.
New Structures
New Functions
New Built-In Variables
None.
New SPIR-V Capabilities
None.
Issues
1) For the scissor test, the viewport state must be created with a matching number of scissor and viewport rectangles. Should we have the same requirement for exclusive scissors?
RESOLVED: For exclusive scissors, we relax this requirement and allow an exclusive scissor rectangle count that is either zero or equal to the number of viewport rectangles. If you pass in an exclusive scissor count of zero, the exclusive scissor test is treated as disabled.
Version History
-
Revision 1, 2018-07-31 (Pat Brown)
-
Internal revisions
-
VK_NV_shader_image_footprint
- Name String
-
VK_NV_shader_image_footprint
- Extension Type
-
Device extension
- Registered Extension Number
-
205
- Revision
-
2
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Pat Brown nvpbrown
-
- Last Modified Date
-
2018-09-13
- IP Status
-
No known IP claims.
- Contributors
-
-
Pat Brown, NVIDIA
-
Chris Lentini, NVIDIA
-
Daniel Koch, NVIDIA
-
Jeff Bolz, NVIDIA
-
This extension adds Vulkan support for the
SPV_NV_shader_image_footprint
SPIR-V extension.
That SPIR-V extension provides a new instruction
OpImageSampleFootprintNV
allowing shaders to determine the set of
texels that would be accessed by an equivalent filtered texture lookup.
Instead of returning a filtered texture value, the instruction returns a structure that can be interpreted by shader code to determine the footprint of a filtered texture lookup. This structure includes integer values that identify a small neighborhood of texels in the image being accessed and a bitfield that indicates which texels in that neighborhood would be used. The structure also includes a bitfield where each bit identifies whether any texel in a small aligned block of texels would be fetched by the texture lookup. The size of each block is specified by an access granularity provided by the shader. The minimum granularity supported by this extension is 2x2 (for 2D textures) and 2x2x2 (for 3D textures); the maximum granularity is 256x256 (for 2D textures) or 64x32x32 (for 3D textures). Each footprint query returns the footprint from a single texture level. When using minification filters that combine accesses from multiple mipmap levels, shaders must perform separate queries for the two levels accessed (“fine” and “coarse”). The footprint query also returns a flag indicating if the texture lookup would access texels from only one mipmap level or from two neighboring levels.
This extension should be useful for multi-pass rendering operations that do an initial expensive rendering pass to produce a first image that is then used as a texture for a second pass. If the second pass ends up accessing only portions of the first image (e.g., due to visbility), the work spent rendering the non-accessed portion of the first image was wasted. With this feature, an application can limit this waste using an initial pass over the geometry in the second image that performs a footprint query for each visible pixel to determine the set of pixels that it needs from the first image. This pass would accumulate an aggregate footprint of all visible pixels into a separate “footprint image” using shader atomics. Then, when rendering the first image, the application can kill all shading work for pixels not in this aggregate footprint.
This extension has a number of limitations.
The OpImageSampleFootprintNV
instruction only supports for two- and
three-dimensional textures.
Footprint evaluation only supports the CLAMP_TO_EDGE wrap mode; results are
undefined for all other wrap modes.
Only a limited set of granularity values and that set does not support
separate coverage information for each texel in the original image.
When using SPIR-V generated from the OpenGL Shading Language, the new
instruction will be generated from code using the new
textureFootprint
*NV built-in functions from the
GL_NV_shader_texture_footprint
shading language extension.
New Object Types
None.
New Enum Constants
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_IMAGE_FOOTPRINT_FEATURES_NV
-
New Enums
None.
New Structures
New Functions
None.
New SPIR-V Capability
Issues
(1) The footprint returned by the SPIR-V instruction is a structure that includes an anchor, an offset, and a mask that represents a 8x8 or 4x4x4 neighborhood of texel groups. But the bits of the mask are not stored in simple pitch order. Why is the footprint built this way?
RESOLVED: We expect that applications using this feature will want to use a fixed granularity and accumulate coverage information from the returned footprints into an aggregate “footprint image” that tracks the portions of an image that would be needed by regular texture filtering. If an application is using a two-dimensional image with 4x4 pixel granularity, we expect that the footprint image will use 64-bit texels where each bit in an 8x8 array of bits corresponds to coverage for a 4x4 block in the original image. Texel (0,0) in the footprint image would correspond to texels (0,0) through (31,31) in the original image.
In the usual case, the footprint for a single access will fully contained in a 32x32 aligned region of the original texture, which corresponds to a single 64-bit texel in the footprint image. In that case, the implementation will return an anchor coordinate pointing at the single footprint image texel, an offset vector of (0,0), and a mask whose bits are aligned with the bits in the footprint texel. For this case, the shader can simply atomically OR the mask bits into the contents of the footprint texel to accumulate footprint coverage.
In the worst case, the footprint for a single access spans multiple 32x32 aligned regions and may require updates to four separate footprint image texels. In this case, the implementation will return an anchor coordinate pointing at the lower right footprint image texel and an offset will identify how many “columns” and “rows” of the returned 8x8 mask correspond to footprint texels to the left and above the anchor texel. If the anchor is (2,3), the 64 bits of the returned mask are arranged spatially as follows, where each 4x4 block is assigned a bit number that matches its bit number in the footprint image texels:
+-------------------------+-------------------------+ | -- -- -- -- -- -- -- -- | -- -- -- -- -- -- -- -- | | -- -- -- -- -- -- -- -- | -- -- -- -- -- -- -- -- | | -- -- -- -- -- -- -- -- | -- -- -- -- -- -- -- -- | | -- -- -- -- -- -- -- -- | -- -- -- -- -- -- -- -- | | -- -- -- -- -- -- -- -- | -- -- -- -- -- -- -- -- | | -- -- -- -- -- -- 46 47 | 40 41 42 43 44 45 -- -- | | -- -- -- -- -- -- 54 55 | 48 49 50 51 52 53 -- -- | | -- -- -- -- -- -- 62 63 | 56 57 58 59 60 61 -- -- | +-------------------------+-------------------------+ | -- -- -- -- -- -- 06 07 | 00 01 02 03 04 05 -- -- | | -- -- -- -- -- -- 14 15 | 08 09 10 11 12 13 -- -- | | -- -- -- -- -- -- 22 23 | 16 17 18 19 20 21 -- -- | | -- -- -- -- -- -- 30 31 | 24 25 26 27 28 29 -- -- | | -- -- -- -- -- -- 38 39 | 32 33 34 35 36 37 -- -- | | -- -- -- -- -- -- -- -- | -- -- -- -- -- -- -- -- | | -- -- -- -- -- -- -- -- | -- -- -- -- -- -- -- -- | | -- -- -- -- -- -- -- -- | -- -- -- -- -- -- -- -- | +-------------------------+-------------------------+
To accumulate coverage for each of the four footprint image texels, a shader can AND the returned mask with simple masks derived from the x and y offset values and then atomically OR the updated mask bits into the contents of the corresponding footprint texel.
uint64_t returnedMask = (uint64_t(footprint.mask.x) | (uint64_t(footprint.mask.y) << 32));
uint64_t rightMask = ((0xFF >> footprint.offset.x) * 0x0101010101010101UL);
uint64_t bottomMask = 0xFFFFFFFFFFFFFFFFUL >> (8 * footprint.offset.y);
uint64_t bottomRight = returnedMask & bottomMask & rightMask;
uint64_t bottomLeft = returnedMask & bottomMask & (~rightMask);
uint64_t topRight = returnedMask & (~bottomMask) & rightMask;
uint64_t topLeft = returnedMask & (~bottomMask) & (~rightMask);
(2) What should an application do to ensure maximum performance when accumulating footprints into an aggregate footprint image?
RESOLVED: We expect that the most common usage of this feature will be to accumulate aggregate footprint coverage, as described in the previous issue. Even if you ignore the anisotropic filtering case where the implementation may return a granularity larger than that requested by the caller, each shader invocation will need to use atomic functions to update up to four footprint image texels for each level of detail accessed. Having each active shader invocation perform multiple atomic operations can be expensive, particularly when neighboring invocations will want to update the same footprint image texels.
Techniques can be used to reduce the number of atomic operations performed when accumulating coverage include:
-
Have logic that detects returned footprints where all components of the returned offset vector are zero. In that case, the mask returned by the footprint function is guaranteed to be aligned with the footprint image texels and affects only a single footprint image texel.
-
Have fragment shaders communicate using built-in functions from the
VK_NV_shader_subgroup_partitioned
extension or other shader subgroup extensions. If you have multiple invocations in a subgroup that need to update the same texel (x,y) in the footprint image, compute an aggregate footprint mask across all invocations in the subgroup updating that texel and have a single invocation perform an atomic operation using that aggregate mask. -
When the returned footprint spans multiple texels in the footprint image, each invocation need to perform four atomic operations. In the previous issue, we had an example that computed separate masks for “topLeft”, “topRight”, “bottomLeft”, and “bottomRight”. When the invocations in a subgroup have good locality, it might be the case the “top left” for some invocations might refer to footprint image texel (10,10), while neighbors might have their “top left” texels at (11,10), (10,11), and (11,11). If you compute separate masks for even/odd x and y values instead of left/right or top/bottom, the “odd/odd” mask for all invocations in the subgroup hold coverage for footprint image texel (11,11), which can be updated by a single atomic operation for the entire subgroup.
Examples
TBD
Version History
-
Revision 2, 2018-09-13 (Pat Brown)
-
Add issue (2) with performance tips.
-
-
Revision 1, 2018-08-12 (Pat Brown)
-
Initial draft
-
VK_NV_shader_sm_builtins
- Name String
-
VK_NV_shader_sm_builtins
- Extension Type
-
Device extension
- Registered Extension Number
-
155
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.1
-
- Contact
-
-
Daniel Koch dgkoch
-
- Last Modified Date
-
2019-05-28
- Interactions and External Dependencies
-
-
This extension requires
SPV_NV_shader_sm_builtins
. -
This extension enables
GL_NV_shader_sm_builtins
for GLSL source languages.
-
- Contributors
-
-
Jeff Bolz, NVIDIA
-
Eric Werness, NVIDIA
-
Description
This extension provides the ability to determine device-specific properties on NVIDIA GPUs. It provides the number of streaming multiprocessors (SMs), the maximum number of warps (subgroups) that can run on an SM, and shader builtins to enable invocations to identify which SM and warp a shader invocation is executing on.
This extension enables support for the SPIR-V ShaderSMBuiltinsNV
capability.
These properties and built-ins should typically only be used for debugging purposes.
New Object Types
None.
New Enum Constants
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_SM_BUILTINS_FEATURES_NV
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_SM_BUILTINS_PROPERTIES_NV
-
New Enums
None.
New Structures
New Functions
None.
New or Modified Built-In Variables
New SPIR-V Capabilities
Issues
-
What should we call this extension?
RESOLVED: Using NV_shader_sm_builtins. Other options considered included:
-
NV_shader_smid - but SMID is really easy to typo/confuse as SIMD.
-
NV_shader_sm_info - but Info is typically reserved for input structures
-
Version History
-
Revision 1, 2019-05-28 (Daniel Koch)
-
Internal revisions
-
VK_NV_shader_subgroup_partitioned
- Name String
-
VK_NV_shader_subgroup_partitioned
- Extension Type
-
Device extension
- Registered Extension Number
-
199
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.1
-
- Contact
-
-
Jeff Bolz jeffbolznv
-
- Last Modified Date
-
2018-03-17
- Contributors
-
-
Jeff Bolz, NVIDIA
-
This extension enables support for a new class of subgroup operations via
the
GL_NV_shader_subgroup_partitioned
GLSL extension and
SPV_NV_shader_subgroup_partitioned
SPIR-V extension.
Support for these new operations is advertised via the
VK_SUBGROUP_FEATURE_PARTITIONED_BIT_NV
bit.
This extension requires Vulkan 1.1, for general subgroup support.
New Object Types
None.
New Enum Constants
-
Extending VkSubgroupFeatureFlagBits:
-
VK_SUBGROUP_FEATURE_PARTITIONED_BIT_NV
-
New Enums
None.
New Structures
None.
New Functions
None.
Issues
None.
Version History
-
Revision 1, 2018-03-17 (Jeff Bolz)
-
Internal revisions
-
VK_NV_shading_rate_image
- Name String
-
VK_NV_shading_rate_image
- Extension Type
-
Device extension
- Registered Extension Number
-
165
- Revision
-
3
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Pat Brown nvpbrown
-
- Last Modified Date
-
2019-07-18
- Contributors
-
-
Pat Brown, NVIDIA
-
Carsten Rohde, NVIDIA
-
Jeff Bolz, NVIDIA
-
Daniel Koch, NVIDIA
-
Mathias Schott, NVIDIA
-
Matthew Netsch, Qualcomm Technologies, Inc.
-
This extension allows applications to use a variable shading rate when processing fragments of rasterized primitives. By default, Vulkan will spawn one fragment shader for each pixel covered by a primitive. In this extension, applications can bind a shading rate image that can be used to vary the number of fragment shader invocations across the framebuffer. Some portions of the screen may be configured to spawn up to 16 fragment shaders for each pixel, while other portions may use a single fragment shader invocation for a 4x4 block of pixels. This can be useful for use cases like eye tracking, where the portion of the framebuffer that the user is looking at directly can be processed at high frequency, while distant corners of the image can be processed at lower frequency. Each texel in the shading rate image represents a fixed-size rectangle in the framebuffer, covering 16x16 pixels in the initial implementation of this extension. When rasterizing a primitive covering one of these rectangles, the Vulkan implementation reads a texel in the bound shading rate image and looks up the fetched value in a palette to determine a base shading rate.
In addition to the API support controlling rasterization, this extension
also adds Vulkan support for the
SPV_NV_shading_rate
extension to
SPIR-V.
That extension provides two fragment shader variable decorations that allow
fragment shaders to determine the shading rate used for processing the
fragment:
-
FragmentSizeNV
, which indicates the width and height of the set of pixels processed by the fragment shader. -
InvocationsPerPixel
, which indicates the maximum number of fragment shader invocations that could be spawned for the pixel(s) covered by the fragment.
When using SPIR-V in conjunction with the OpenGL Shading Language (GLSL),
the fragment shader capabilities are provided by the
GL_NV_shading_rate_image
language extension and correspond to the built-in
variables gl_FragmentSizeNV
and gl_InvocationsPerPixelNV
,
respectively.
New Object Types
None.
New Enum Constants
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PIPELINE_VIEWPORT_SHADING_RATE_IMAGE_STATE_CREATE_INFO_NV
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADING_RATE_IMAGE_FEATURES_NV
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADING_RATE_IMAGE_PROPERTIES_NV
-
VK_STRUCTURE_TYPE_PIPELINE_VIEWPORT_COARSE_SAMPLE_ORDER_STATE_CREATE_INFO_NV
-
-
Extending VkImageLayout:
-
VK_IMAGE_LAYOUT_SHADING_RATE_OPTIMAL_NV
-
-
Extending VkDynamicState:
-
VK_DYNAMIC_STATE_VIEWPORT_SHADING_RATE_PALETTE_NV
-
VK_DYNAMIC_STATE_VIEWPORT_COARSE_SAMPLE_ORDER_NV
-
-
Extending VkAccessFlagBits:
-
VK_ACCESS_SHADING_RATE_IMAGE_READ_BIT_NV
-
-
Extending VkImageUsageFlagBits:
-
VK_IMAGE_USAGE_SHADING_RATE_IMAGE_BIT_NV
-
-
Extending VkPipelineStageFlagBits
-
VK_PIPELINE_STAGE_SHADING_RATE_IMAGE_BIT_NV
-
New Enums
-
VkShadingRatePaletteEntryNV, containing the following constants:
-
VK_SHADING_RATE_PALETTE_ENTRY_NO_INVOCATIONS_NV
-
VK_SHADING_RATE_PALETTE_ENTRY_16_INVOCATIONS_PER_PIXEL_NV
-
VK_SHADING_RATE_PALETTE_ENTRY_8_INVOCATIONS_PER_PIXEL_NV
-
VK_SHADING_RATE_PALETTE_ENTRY_4_INVOCATIONS_PER_PIXEL_NV
-
VK_SHADING_RATE_PALETTE_ENTRY_2_INVOCATIONS_PER_PIXEL_NV
-
VK_SHADING_RATE_PALETTE_ENTRY_1_INVOCATION_PER_PIXEL_NV
-
VK_SHADING_RATE_PALETTE_ENTRY_1_INVOCATION_PER_2X1_PIXELS_NV
-
VK_SHADING_RATE_PALETTE_ENTRY_1_INVOCATION_PER_1X2_PIXELS_NV
-
VK_SHADING_RATE_PALETTE_ENTRY_1_INVOCATION_PER_2X2_PIXELS_NV
-
VK_SHADING_RATE_PALETTE_ENTRY_1_INVOCATION_PER_4X2_PIXELS_NV
-
VK_SHADING_RATE_PALETTE_ENTRY_1_INVOCATION_PER_2X4_PIXELS_NV
-
VK_SHADING_RATE_PALETTE_ENTRY_1_INVOCATION_PER_4X4_PIXELS_NV
-
-
VkCoarseSampleOrderTypeNV, containing the following constants:
-
VK_COARSE_SAMPLE_ORDER_TYPE_DEFAULT_NV
-
VK_COARSE_SAMPLE_ORDER_TYPE_CUSTOM_NV
-
VK_COARSE_SAMPLE_ORDER_TYPE_PIXEL_MAJOR_NV
-
VK_COARSE_SAMPLE_ORDER_TYPE_SAMPLE_MAJOR_NV
-
New Structures
New Functions
Issues
(1) When using shading rates specifying “coarse” fragments covering multiple pixels, we will generate a combined coverage mask that combines the coverage masks of all pixels covered by the fragment. By default, these masks are combined in an implementation-dependent order. Should we provide a mechanism allowing applications to query or specify an exact order?
RESOLVED: Yes, this feature is useful for cases where most of the fragment shader can be evaluated once for an entire coarse fragment, but where some per-pixel computations are also required. For example, a per-pixel alpha test may want to kill all the samples for some pixels in a coarse fragment. This sort of test can be implemented using an output sample mask, but such a shader would need to know which bit in the mask corresponds to each sample in the coarse fragment. We are including a mechanism to allow aplications to specify the orders of coverage samples for each shading rate and sample count, either as static pipeline state or dynamically via a command buffer. This portion of the extension has its own feature bit.
We will not be providing a query to determine the implementation-dependent default ordering. The thinking here is that if an application cares enough about the coarse fragment sample ordering to perform such a query, it could instead just set its own order, also using custom per-pixel sample locations if required.
(2) For the pipeline stage
VK_PIPELINE_STAGE_SHADING_RATE_IMAGE_BIT_NV
, should we specify a
precise location in the pipeline the shading rate image is accessed
(after geometry shading, but before the early fragment tests) or leave
it under-specified in case there are other implementations that access
the image in a different pipeline location?
RESOLVED We are specifying the pipeline stage to be between the final
stage used for vertex processing
(VK_PIPELINE_STAGE_GEOMETRY_SHADER_BIT
) and before the first stage
used for fragment processing
(VK_PIPELINE_STAGE_EARLY_FRAGMENT_TESTS_BIT
), which seems to be the
natural place to access the shading rate image.
(3) How do centroid-sampled variables work with fragments larger than one pixel?
RESOLVED For single-pixel fragments, fragment shader inputs decorated with
Centroid
are sampled at an implementation-dependent location in the
intersection of the area of the primitive being rasterized and the area of
the pixel that corresponds to the fragment.
With multi-pixel fragments, we follow a similar pattern, using the
intersection of the primitive and the set of pixels corresponding to the
fragment.
One important thing to keep in mind when using such “coarse” shading rates is that fragment attributes are sampled at the center of the fragment by default, regardless of the set of pixels/samples covered by the fragment. For fragments with a size of 4x4 pixels, this center location will be more than two pixels (1.5 * sqrt(2)) away from the center of the pixels at the corners of the fragment. When rendering a primitive that covers only a small part of a coarse fragment, sampling a color outside the primitive can produce overly bright or dark color values if the color values have a large gradient. To deal with this, an application can use centroid sampling on attributes where “extrapolation” artifacts can lead to overly bright or dark pixels. Note that this same problem also exists for multisampling with single-pixel fragments, but is less severe because it only affects certain samples of a pixel and such bright/dark samples may be averaged with other samples that don’t have a similar problem.
Version History
-
Revision 3, 2019-07-18 (Mathias Schott)
-
Fully list extension interfaces in this appendix.
-
-
Revision 2, 2018-09-13 (Pat Brown)
-
Miscellaneous edits preparing the specification for publication.
-
-
Revision 1, 2018-08-08 (Pat Brown)
-
Internal revisions
-
VK_NV_viewport_array2
- Name String
-
VK_NV_viewport_array2
- Extension Type
-
Device extension
- Registered Extension Number
-
97
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Daniel Koch dgkoch
-
- Last Modified Date
-
2017-02-15
- Interactions and External Dependencies
-
-
This extension requires the
SPV_NV_viewport_array2
SPIR-V extension. -
This extension requires the
GL_NV_viewport_array2
extension for GLSL source languages. -
This extension requires the
geometryShader
andmultiViewport
features. -
This extension interacts with the
tessellationShader
feature.
-
- Contributors
-
-
Piers Daniell, NVIDIA
-
Jeff Bolz, NVIDIA
-
This extension adds support for the following SPIR-V extension in Vulkan:
-
SPV_NV_viewport_array2
which allows a single primitive to be broadcast to multiple viewports and/or
multiple layers.
A new shader built-in output ViewportMaskNV
is provided, which allows a
single primitive to be output to multiple viewports simultaneously.
Also, a new SPIR-V decoration is added to control whether the effective
viewport index is added into the variable decorated with the Layer
built-in decoration.
These capabilities allow a single primitive to be output to multiple layers
simultaneously.