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 KHX author ID is no longer used. All KHX extensions have been promoted to KHR status. Previously, this author ID was used to indicate that an extension was experimental, and is being considered for standardization in future KHR or core Vulkan API versions. We no longer use this mechanism for exposing experimental functionality.

Some vendors may use an alternate author ID ending in X for some of their extensions. The exact meaning of such an author ID is defined by each vendor, and may not be equivalent to KHX, but it is likely to indicate a lesser degree of interface stability than a non-X extension from the same vendor.

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
Contact
Last Modified Date

2018-02-05

IP Status

No known IP claims.

Interactions and External Dependencies
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

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
Contact
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

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_create_renderpass2

Name String

VK_KHR_create_renderpass2

Extension Type

Device extension

Registered Extension Number

110

Revision

1

Extension and Version Dependencies
Contact
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:

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

Version History

  • Revision 1, 2018-02-07 (Tobias Hector)

    • Internal revisions

VK_KHR_display

Name String

VK_KHR_display

Extension Type

Instance extension

Registered Extension Number

3

Revision

21

Extension and Version Dependencies
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

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 VK_KHR_display and VK_KHR_display_swapchain extensions was removed from the appendix after revision 1.0.43. The display enumeration example code was ported to the cube demo that is shipped with the official Khronos SDK, and is being kept up-to-date in that location (see: https://github.com/KhronosGroup/Vulkan-Tools/blob/master/cube/cube.c).

Version History

  • Revision 1, 2015-02-24 (James Jones)

    • Initial draft

  • Revision 2, 2015-03-12 (Norbert Nopper)

    • Added overlay enumeration for a display.

  • Revision 3, 2015-03-17 (Norbert Nopper)

    • Fixed typos and namings as discussed in Bugzilla.

    • Reordered and grouped functions.

    • Added functions to query count of display, mode and overlay.

    • Added native display handle, which is maybe needed on some platforms to create a native Window.

  • Revision 4, 2015-03-18 (Norbert Nopper)

    • Removed primary and virtualPostion members (see comment of James Jones in Bugzilla).

    • Added native overlay handle to info structure.

    • Replaced , with ; in struct.

  • Revision 6, 2015-03-18 (Daniel Rakos)

    • Added WSI extension suffix to all items.

    • Made the whole API more "Vulkanish".

    • Replaced all functions with a single vkGetDisplayInfoKHR function to better match the rest of the API.

    • Made the display, display mode, and overlay objects be first class objects, not subclasses of VkBaseObject as they do not support the common functions anyways.

    • Renamed *Info structures to *Properties.

    • Removed overlayIndex field from VkOverlayProperties as there is an implicit index already as a result of moving to a "Vulkanish" API.

    • Displays are not get through device, but through physical GPU to match the rest of the Vulkan API. Also this is something ISVs explicitly requested.

    • Added issue (6) and (7).

  • Revision 7, 2015-03-25 (James Jones)

    • Added an issues section

    • Added rotation and mirroring flags

  • Revision 8, 2015-03-25 (James Jones)

    • Combined the duplicate issues sections introduced in last change.

    • Added proposed resolutions to several issues.

  • Revision 9, 2015-04-01 (Daniel Rakos)

    • Rebased extension against Vulkan 0.82.0

  • Revision 10, 2015-04-01 (James Jones)

    • Added issues (10) and (11).

    • Added more straw-man issue resolutions, and cleaned up the proposed resolution for issue (4).

    • Updated the rotation and mirroring enums to have proper bitmask semantics.

  • Revision 11, 2015-04-15 (James Jones)

    • Added proposed resolution for issues (1) and (2).

    • Added issues (12), (13), (14), and (15)

    • Removed pNativeHandle field from overlay structure.

    • Fixed small compilation errors in example code.

  • Revision 12, 2015-07-29 (James Jones)

    • Rewrote the guts of the extension against the latest WSI swapchain specifications and the latest Vulkan API.

    • Address overlay planes by their index rather than an object handle and refer to them as "planes" rather than "overlays" to make it slightly clearer that even a display with no "overlays" still has at least one base "plane" that images can be displayed on.

    • Updated most of the issues.

    • Added an "extension type" section to the specification header.

    • Re-used the VK_EXT_KHR_surface surface transform enumerations rather than redefining them here.

    • Updated the example code to use the new semantics.

  • Revision 13, 2015-08-21 (Ian Elliott)

    • Renamed this extension and all of its enumerations, types, functions, etc. This makes it compliant with the proposed standard for Vulkan extensions.

    • Switched from "revision" to "version", including use of the VK_MAKE_VERSION macro in the header file.

  • Revision 14, 2015-09-01 (James Jones)

    • Restore single-field revision number.

  • Revision 15, 2015-09-08 (James Jones)

    • Added alpha flags enum.

    • Added premultiplied alpha support.

  • Revision 16, 2015-09-08 (James Jones)

    • Added description section to the spec.

    • Added issues 16 - 18.

  • Revision 17, 2015-10-02 (James Jones)

    • Planes are now a property of the entire device rather than individual displays. This allows planes to be moved between multiple displays on devices that support it.

    • Added a function to create a VkSurfaceKHR object describing a display plane and mode to align with the new per-platform surface creation conventions.

    • Removed detailed mode timing data. It was agreed that the mode extents and refresh rate are sufficient for current use cases. Other information could be added back2 in as an extension if it is needed in the future.

    • Added support for smart/persistent/buffered display devices.

  • Revision 18, 2015-10-26 (Ian Elliott)

    • Renamed from VK_EXT_KHR_display to VK_KHR_display.

  • Revision 19, 2015-11-02 (James Jones)

    • Updated example code to match revision 17 changes.

  • Revision 20, 2015-11-03 (Daniel Rakos)

    • Added allocation callbacks to creation functions.

  • Revision 21, 2015-11-10 (Jesse Hall)

    • Added VK_DISPLAY_PLANE_ALPHA_OPAQUE_BIT_KHR, and use VkDisplayPlaneAlphaFlagBitsKHR for VkDisplayPlanePropertiesKHR::alphaMode instead of VkDisplayPlaneAlphaFlagsKHR, since it only represents one mode.

    • Added reserved flags bitmask to VkDisplayPlanePropertiesKHR.

    • Use VkSurfaceTransformFlagBitsKHR instead of obsolete VkSurfaceTransformKHR.

    • Renamed vkGetDisplayPlaneSupportedDisplaysKHR parameters for clarity.

  • Revision 22, 2015-12-18 (James Jones)

    • Added missing "planeIndex" parameter to vkGetDisplayPlaneSupportedDisplaysKHR()

  • Revision 23, 2017-03-13 (James Jones)

    • Closed all remaining issues. The specification and implementations have been shipping with the proposed resolutions for some time now.

    • Removed the sample code and noted it has been integrated into the official Vulkan SDK cube demo.

VK_KHR_display_swapchain

Name String

VK_KHR_display_swapchain

Extension Type

Device extension

Registered Extension Number

4

Revision

9

Extension and Version Dependencies
Contact
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

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/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/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 an sType/pNext 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 VK_KHR_display and VK_KHR_display_swapchain extensions was removed from the appendix after revision 1.0.43. The display swapchain creation example code was ported to the cube demo that is shipped with the official Khronos SDK, and is being kept up-to-date in that location (see: https://github.com/KhronosGroup/Vulkan-Tools/blob/master/cube/cube.c).

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
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.

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
Contact
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 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
Contact
Last Modified Date

2017-05-08

IP Status

No known IP claims.

Contributors

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.

Issues

This extension borrows concepts, semantics, and language from VK_KHR_external_semaphore_fd. That extension’s issues apply equally to this extension.

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
Contact
Last Modified Date

2017-05-08

IP Status

No known IP claims.

Contributors

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.

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.

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
Contact
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.

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.

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
Contact
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.

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.

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
Contact
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.

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.

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
Contact
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.

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.

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
Contact
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.

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:

3) Should additional display query functions be extended?

RESOLVED:

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
Contact
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:

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
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 Functions

None.

Issues

VK_KHR_incremental_present

Name String

VK_KHR_incremental_present

Extension Type

Device extension

Registered Extension Number

85

Revision

1

Extension and Version Dependencies
Contact
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 haven’t changed.

This extension is leveraged from the EGL_KHR_swap_buffers_with_damage extension.

New Object Types

None.

New Enum Constants

New Enums

None.

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 that contains 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_push_descriptor

Name String

VK_KHR_push_descriptor

Extension Type

Device extension

Registered Extension Number

81

Revision

2

Extension and Version Dependencies
Contact
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

None.

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

1

Extension and Version Dependencies
  • Requires Vulkan 1.0

Contact
Last Modified Date

2016-02-16

Contributors
  • Tobias Hector, Imagination Technologies

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

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);

Version History

  • Revision 1, 2016-02-16 (Tobias Hector)

    • Initial draft

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
Contact
Last Modified Date

2018-07-05

Interactions and External Dependencies
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

Version History

  • Revision 1, 2018-07-05 (Aaron Hagan)

    • Internal revisions

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
Contact
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 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 an 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_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
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

Examples

Note

The example code for the VK_KHR_surface and VK_KHR_swapchain extensions was removed from the appendix after revision 1.0.29. This WSI example code was ported to the cube demo that is shipped with the official Khronos SDK, and is being kept up-to-date in that location (see: https://github.com/KhronosGroup/Vulkan-Tools/blob/master/cube/cube.c).

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_swapchain

Name String

VK_KHR_swapchain

Extension Type

Device extension

Registered Extension Number

2

Revision

70

Extension and Version Dependencies
Contact
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

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 VK_KHR_surface and VK_KHR_swapchain extensions was removed from the appendix after revision 1.0.29. This WSI example code was ported to the cube demo that is shipped with the official Khronos SDK, and is being kept up-to-date in that location (see: https://github.com/KhronosGroup/Vulkan-Tools/blob/master/cube/cube.c).

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_wayland_surface

Name String

VK_KHR_wayland_surface

Extension Type

Instance extension

Registered Extension Number

7

Revision

6

Extension and Version Dependencies
Contact
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

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
Contact
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 Functions

None.

Issues

None.

VK_KHR_win32_surface

Name String

VK_KHR_win32_surface

Extension Type

Instance extension

Registered Extension Number

10

Revision

6

Extension and Version Dependencies
Contact
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

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 for SetPixelFormat 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
Contact
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

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
Contact
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

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
Contact
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.

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
Contact
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
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 is VK_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 is VK_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 Functions

None.

Issues

None.

Version History

  • Revisions 1-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
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

  • 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

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

1

Extension and Version Dependencies
  • Requires Vulkan 1.0

Contact
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

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
Contact
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 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
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 or VkCommandBuffer 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 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)

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
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
Contact
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 and SPV_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 Functions

None.

Issues

None.

Version History

  • Revision 1, 2017-07-26 (Jeff Bolz)

    • Internal revisions

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
Contact
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
Contact
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

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
Contact
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

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
Contact
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

New Structures

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
Contact
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

Issues

1. How does the application, when creating a VkImage that it intends to bind to dma_buf VkDeviceMemory that contains 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_bufs 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
Contact
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.

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_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
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 predence 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 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

1

Extension and Version Dependencies
Contact
Last Modified Date

2017-03-04

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

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

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
Contact
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_modifiers2 and EGL_MESA_image_dma_buf_export3. 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’s format, drmFormatModifier, and extent; and each plane’s offset and rowPitch.

    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, and rowPitch 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 from pDrmFormatModifiers 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_import1 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_modifiers2 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_export3 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_cmd24, 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_modifiers1; and symmetrically allows exporting the same data from the gbm_bo. See the references to modifier and plane in gbm.h5.

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.

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_modifiers2, struct drm_mode_fb_cmd24, and struct gbm_import_fd_modifier_data5, 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_modifiers2, struct drm_mode_fb_cmd24, and struct gbm_import_fd_modifier_data5, 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:

Differences in Image Creation
  • Undedicated allocation by default. When importing or exporting a set of dma_bufs as an EGLImage or gbm_bo, common practice mandates that each dma_buf’s memory be dedicated (in the sense of VK_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 with VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT.

  • Separation of image creation and memory allocation. When importing a set of dma_bufs as an EGLImage or gbm_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 in VK_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:

Problematic Plane Size Calculations
  • 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 whose mipLevels, arrayLayers, or depth 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.

Version History
  • Revision 1.0, 2018-08-29 (Chad Versace)

    • First stable revision

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
Contact
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 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_pci_bus_info

Name String

VK_EXT_pci_bus_info

Extension Type

Device extension

Registered Extension Number

213

Revision

1

Extension and Version Dependencies
Contact
Last Modified Date

2018-10-11

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 Functions

None.

Issues

None.

Examples

None.

Version History

  • Revision 1, 2018-10-11 (Daniel Rakos)

    • 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
Last Modified Date

2017-07-17

Interactions and External Dependencies
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
Contact
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 for VK_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/from VK_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
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.

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

1

Extension and Version Dependencies
Contact
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 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_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
Last Modified Date

2017-07-19

IP Status

No known IP claims.

Interactions and External Dependencies
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
Last Modified Date

2016-11-28

IP Status

No known IP claims.

Interactions and External Dependencies
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 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
Last Modified Date

2016-11-28

IP Status

No known IP claims.

Interactions and External Dependencies
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
Last Modified Date

2017-08-08

Interactions and External Dependencies
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 ShaderViewportIndexLayerEXT capability is equivalent to the ShaderViewportIndexLayerNV capability added by VK_NV_viewport_array2.

New Object Types

None.

New Enum Constants

None.

New Enums

None.

New Structures

None.

New Functions

None.

New or Modified Built-In Variables

New Variable Decoration

None.

New SPIR-V Capabilities

Issues

None yet!

Version History

  • Revision 1, 2017-08-08 (Daniel Koch)

    • Internal drafts

VK_EXT_swapchain_colorspace

Name String

VK_EXT_swapchain_colorspace

Extension Type

Instance extension

Registered Extension Number

105

Revision

3

Extension and Version Dependencies
Contact
Last Modified Date

2017-03-15

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.

VK_EXT_transform_feedback

Name String

VK_EXT_transform_feedback

Extension Type

Device extension

Registered Extension Number

29

Revision

1

Extension and Version Dependencies
Contact
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

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
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

Issues

None.

Version History

  • Revision 1, 2017-08-29 (Cort Stratton)

    • Initial draft

VK_EXT_validation_flags

Name String

VK_EXT_validation_flags

Extension Type

Instance extension

Registered Extension Number

62

Revision

1

Extension and Version Dependencies
  • Requires Vulkan 1.0

Contact
Last Modified Date

2016-09-06

IP Status

No known IP claims.

Contributors
  • Tobin Ehlis, Google

  • Courtney Goeltzenleuchter, Google

This extension provides the VkValidationFlagsEXT struct that can be included in the pNext chain of the VkInstanceCreateInfo structure passed as the pCreateInfo parameter of vkCreateInstance. The new struct contains an array of VkValidationCheckEXT values that will be disabled by the validation layers.

New Enum Constants

New Structures

New Functions

None.

Issues

None.

Version History

  • Revision 1, 2016-08-26 (Courtney Goeltzenleuchter)

    • Initial draft

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
Contact
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 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 and firstInstance 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_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
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.

Examples

None.

Version History

  • Revision 1, 2018-01-26 (Jaakko Konttinen)

    • 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
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_gpu_shader_half_float

Name String

VK_AMD_gpu_shader_half_float

Extension Type

Device extension

Registered Extension Number

37

Revision

1

Extension and Version Dependencies
  • Requires Vulkan 1.0

Contact
Last Modified Date

2016-09-21

IP Status

No known IP claims.

Contributors
  • Daniel Rakos, AMD

  • Dominik Witczak, AMD

  • Donglin Wei, AMD

  • Graham Sellers, AMD

  • Qun Lin, AMD

  • Rex Xu, AMD

This extension adds support for the following SPIR-V extension in Vulkan:

Version History

  • Revision 1, 2019-09-21 (Dominik Witczak)

    • Initial draft

VK_AMD_gpu_shader_int16

Name String

VK_AMD_gpu_shader_int16

Extension Type

Device extension

Registered Extension Number

133

Revision

1

Extension and Version Dependencies
  • Requires Vulkan 1.0

Contact
Last Modified Date

2017-06-08

IP Status

No known IP claims.

Interactions and External Dependencies
Contributors
  • Daniel Rakos, AMD

  • Dominik Witczak, AMD

  • Matthaeus G. Chajdas, AMD

  • Rex Xu, AMD

  • Timothy Lottes, AMD

  • Zhi Cai, AMD

This extension adds support for the following SPIR-V extension in Vulkan:

  • SPV_AMD_gpu_shader_int16

Version History

  • Revision 1, 2017-06-18 (Dominik Witczak)

    • First version.

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
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 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
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_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
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, or VK_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 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
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

1

Extension and Version Dependencies
Contact
Last Modified Date

2018-02-15

IP Status

No known IP claims.

Contributors
  • Martin Dinkov, AMD

  • Matthaeus 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 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 1, 2018-02-15 (Martin Dinkov)

    • 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
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
Last Modified Date

2017-08-16

IP Status

No known IP claims.

Dependencies
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
Last Modified Date

2017-08-21

Interactions and External Dependencies
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
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 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
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
Contact
Last Modified Date

2017-03-21

IP Status

No known IP claims.

Interactions and External Dependencies
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 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
Contact
Last Modified Date

2018-03-04

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.

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.

VK_FUCHSIA_imagepipe_surface

Name String

VK_FUCHSIA_imagepipe_surface

Extension Type

Instance extension

Registered Extension Number

215

Revision

1

Extension and Version Dependencies
Contact
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

Issues

None

Version History

  • Revision 1, 2018-07-27 (Craig Stout)

    • Initial draft.

VK_GOOGLE_decorate_string

Name String

VK_GOOGLE_decorate_string

Extension Type

Device extension

Registered Extension Number

225

Revision

0

Extension and Version Dependencies
  • Requires Vulkan 1.0

Contact
Last Modified Date

2018-07-09

IP Status

No known IP claims.

Interactions and External Dependencies
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
Contact
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

New Enums

None.

Issues

None.

Examples

Note

The example code for the this extension (like the VK_KHR_surface and VK_GOOGLE_display_timing extensions) is contained in the cube demo that is shipped with the official Khronos SDK, and is being kept up-to-date in that location (see: https://github.com/KhronosGroup/Vulkan-Tools/blob/master/cube/cube.c ).

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

0

Extension and Version Dependencies
  • Requires Vulkan 1.0

Contact
Last Modified Date

2018-07-09

IP Status

No known IP claims.

Interactions and External Dependencies
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_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
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

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_MVK_ios_surface

Name String

VK_MVK_ios_surface

Extension Type

Instance extension

Registered Extension Number

123

Revision

2

Extension and Version Dependencies
Contact
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

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
Contact
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 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
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

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
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 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

  • VK_PIPELINE_STAGE_COMMAND_PROCESS_BIT_NVX

Extending VkAccessFlagBits:

  • VK_ACCESS_COMMAND_PROCESS_READ_BIT_NVX

  • VK_ACCESS_COMMAND_PROCESS_WRITE_BIT_NVX

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

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?

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

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_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
Contact
Last Modified Date

2017-01-13

IP Status

No known IP claims.

Interactions and External Dependencies
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 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
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.

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
Contact
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 Functions

None.

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_corner_sampled_image

Name String

VK_NV_corner_sampled_image

Extension Type

Device extension

Registered Extension Number

51

Revision

2

Extension and Version Dependencies
Contact
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:

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

New Enums

None.

New Functions

None.

New Built-In Variables

None.

New SPIR-V Capabilities

None.

Issues

  1. 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.

  2. 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.

  3. Do integer texel coordinates have a different range for corner-sampled images?

    RESOLVED: No, these are unchanged.

  4. 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.

  5. 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

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
Contact
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.

Issues

None yet!

Version History

  • Revision 1, 2018-07-16 (Nuno Subtil)

    • Internal revisions

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
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

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
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 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
Contact
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:

  • SPV_NV_fragment_shader_barycentric

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
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 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
Last Modified Date

2017-02-15

Interactions and External Dependencies
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

layout(points, max_vertices=1)

lines

layout(line_strip, max_vertices=2)

triangles

layout(triangle_strip, max_vertices=3)

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
Contact
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: * SPV_NV_mesh_shader

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 or Modified Built-In Variables

New SPIR-V Capability

Issues

  1. 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

  2. Do we need a new VkPrimitiveTopology?

    RESOLVED: NO, we skip the InputAssembler stage

  3. Should we allow Instancing?

    RESOLVED: NO, there is no fixed function input, other than the IDs. However, allow offsetting with a "first" value.

  4. 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.

  5. If new functions, how to name?

    RESOLVED: CmdDrawMeshTasks*

    Other options considered:

    • CmdDrawMeshed

    • CmdDrawTasked

    • CmdDrawGrouped

  6. 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

2

Extension and Version Dependencies
Contact
Last Modified Date

2018-09-11

Interactions and External Dependencies
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

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

VK_NV_representative_fragment_test

Name String

VK_NV_representative_fragment_test

Extension Type

Device extension

Registered Extension Number

167

Revision

1

Extension and Version Dependencies
  • Requires Vulkan 1.0

Contact
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 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
Last Modified Date

2016-12-08

IP Status

No known IP claims.

Interactions and External Dependencies
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
Contact
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 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

1

Extension and Version Dependencies
Contact
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 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_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
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

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
Contact
Last Modified Date

2018-09-13

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

  • 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

Issues

(1) When using shading rates that specify “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 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
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 and multiViewport 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.

This extension allows variables decorated with the Layer and ViewportIndex built-ins to be exported from vertex or tessellation shaders, using the ShaderViewportIndexLayerNV capability.

This extension adds a new ViewportMaskNV built-in decoration that is available for output variables in vertex, tessellation evaluation, and geometry shaders, and a new ViewportRelativeNV decoration that can be added on variables decorated with Layer when using the ShaderViewportMaskNV capability.

When using GLSL source-based shading languages, the gl_ViewportMask[] built-in output variable and viewport_relative layout qualifier from GL_NV_viewport_array2 map to the ViewportMaskNV and ViewportRelativeNV decorations, respectively. Behaviour is described in the GL_NV_viewport_array2 extension specificiation.

Note

The ShaderViewportIndexLayerNV capability is equivalent to the ShaderViewportIndexLayerEXT capability added by VK_EXT_shader_viewport_index_layer.

New Object Types

None.

New Enum Constants

None.

New Enums

None.

New Structures

None.

New Functions

None.

New or Modified Built-In Variables

New Variable Decoration

Issues

None yet!

Version History

  • Revision 1, 2017-02-15 (Daniel Koch)

    • Internal revisions

VK_NV_viewport_swizzle

Name String

VK_NV_viewport_swizzle

Extension Type

Device extension

Registered Extension Number

99

Revision

1

Extension and Version Dependencies
  • Requires Vulkan 1.0

Contact
Last Modified Date

2016-12-22

Interactions and External Dependencies
  • This extension requires multiViewport and geometryShader features to be useful.

Contributors
  • Daniel Koch, NVIDIA

  • Jeff Bolz, NVIDIA

This extension provides a new per-viewport swizzle that can modify the position of primitives sent to each viewport. New viewport swizzle state is added for each viewport, and a new position vector is computed for each vertex by selecting from and optionally negating any of the four components of the original position vector.

This new viewport swizzle is useful for a number of algorithms, including single-pass cubemap rendering (broadcasting a primitive to multiple faces and reorienting the vertex position for each face) and voxel rasterization. The per-viewport component remapping and negation provided by the swizzle allows application code to re-orient three-dimensional geometry with a view along any of the X, Y, or Z axes. If a perspective projection and depth buffering is required, 1/W buffering should be used, as described in the single-pass cubemap rendering example in the “Issues” section below.

New Object Types

None.

New Enum Constants

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_PIPELINE_VIEWPORT_SWIZZLE_STATE_CREATE_INFO_NV

New Functions

None.

Issues

1) Where does viewport swizzling occur in the pipeline?

RESOLVED: Despite being associated with the viewport, viewport swizzling must happen prior to the viewport transform. In particular, it needs to be performed before clipping and perspective division.

The viewport mask expansion (VK_NV_viewport_array2) and the viewport swizzle could potentially be performed before or after transform feedback, but feeding back several viewports worth of primitives with different swizzles doesn’t seem particularly useful. This specification applies the viewport mask and swizzle after transform feedback, and makes primitive queries only count each primitive once.

2) Any interesting examples of how this extension, VK_NV_viewport_array2, and VK_NV_geometry_shader_passthrough can be used together in practice?

RESOLVED: One interesting use case for this extension is for single-pass rendering to a cubemap. In this example, the application would attach a cubemap texture to a layered FBO where the six cube faces are treated as layers. Vertices are sent through the vertex shader without applying a projection matrix, where the gl_Position output is (x,y,z,1) and the center of the cubemap is at (0,0,0). With unextended Vulkan, one could have a conventional instanced geometry shader that looks something like the following:

layout(invocations = 6) in;     // separate invocation per face
layout(triangles) in;
layout(triangle_strip) out;
layout(max_vertices = 3) out;

in Inputs {
vec2 texcoord;
vec3 normal;
vec4 baseColor;
} v[];

    out Outputs {
    vec2 texcoord;
    vec3 normal;
    vec4 baseColor;
    };

    void main()
    {
    int face = gl_InvocationID;  // which face am I?

    // Project gl_Position for each vertex onto the cube map face.
    vec4 positions[3];
    for (int i = 0; i < 3; i++) {
        positions[i] = rotate(gl_in[i].gl_Position, face);
    }

    // If the primitive doesn't project onto this face, we're done.
    if (shouldCull(positions)) {
        return;
    }

    // Otherwise, emit a copy of the input primitive to the
    // appropriate face (using gl_Layer).
    for (int i = 0; i < 3; i++) {
        gl_Layer = face;
        gl_Position = positions[i];
        texcoord = v[i].texcoord;
        normal = v[i].normal;
        baseColor = v[i].baseColor;
        EmitVertex();
    }
}

With passthrough geometry shaders, this can be done using a much simpler shader:

layout(triangles) in;
layout(passthrough) in Inputs {
    vec2 texcoord;
    vec3 normal;
    vec4 baseColor;
}
layout(passthrough) in gl_PerVertex {
    vec4 gl_Position;
} gl_in[];
layout(viewport_relative) out int gl_Layer;

void main()
{
    // Figure out which faces the primitive projects onto and
    // generate a corresponding viewport mask.
    uint mask = 0;
    for (int i = 0; i < 6; i++) {
        if (!shouldCull(face)) {
        mask |= 1U << i;
        }
    }
    gl_ViewportMask = mask;
    gl_Layer = 0;
}

The application code is set up so that each of the six cube faces has a separate viewport (numbered 0 to 5). Each face also has a separate swizzle, programmed via the VkPipelineViewportSwizzleStateCreateInfoNV pipeline state. The viewport swizzle feature performs the coordinate transformation handled by the rotate() function in the original shader. The viewport_relative layout qualifier says that the viewport number (0 to 5) is added to the base gl_Layer value of 0 to determine which layer (cube face) the primitive should be sent to.

Note that the use of the passed through input normal in this example suggests that the fragment shader in this example would perform an operation like per-fragment lighting. The viewport swizzle would transform the position to be face-relative, but normal would remain in the original coordinate system. It seems likely that the fragment shader in either version of the example would want to perform lighting in the original coordinate system. It would likely do this by reconstructing the position of the fragment in the original coordinate system using gl_FragCoord, a constant or uniform holding the size of the cube face, and the input gl_ViewportIndex (or gl_Layer), which identifies the cube face. Since the value of normal is in the original coordinate system, it would not need to be modified as part of this coordinate transformation.

Note that while the rotate() operation in the regular geometry shader above could include an arbitrary post-rotation projection matrix, the viewport swizzle does not support arbitrary math. To get proper projection, 1/W buffering should be used. To do this:

  1. Program the viewport swizzles to move the pre-projection W eye coordinate (typically 1.0) into the Z coordinate of the swizzle output and the eye coordinate component used for depth into the W coordinate. For example, the viewport corresponding to the +Z face might use a swizzle of (+X, -Y, +W, +Z). The Z normalized device coordinate computed after swizzling would then be z'/w' = 1/Zeye.

  2. On NVIDIA implementations supporting floating-point depth buffers with values outside [0,1], prevent unwanted near plane clipping by enabling depthClampEnable. Ensure that the depth clamp doesn’t mess up depth testing by programming the depth range to very large values, such as minDepthBounds=-z, maxDepthBounds=+z, where z = 2127. It should be possible to use IEEE infinity encodings also (0xFF800000 for -INF, 0x7F800000 for +INF). Even when near/far clipping is disabled, primitives extending behind the eye will still be clipped because one or more vertices will have a negative W coordinate and fail X/Y clipping tests.

    On other implementations, scale X, Y, and Z eye coordinates so that vertices on the near plane have a post-swizzle W coordinate of 1.0. For example, if the near plane is at Zeye = 1/256, scale X, Y, and Z by 256.

  3. Adjust depth testing to reflect the fact that 1/W values are large near the eye and small away from the eye. Clear the depth buffer to zero (infinitely far away) and use a depth test of VK_COMPARE_OP_GREATER instead of VK_COMPARE_OP_LESS.

Version History

  • Revision 1, 2016-12-22 (Piers Daniell)

    • Internal revisions

List of Provisional Extensions

VK_KHR_vulkan_memory_model

Name String

VK_KHR_vulkan_memory_model

Extension Type

Device extension

Registered Extension Number

212

Revision

2

Extension and Version Dependencies
  • Requires Vulkan 1.0

Contact
Last Modified Date

2018-02-05

IP Status

No known IP claims.

Interactions and External Dependencies
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 SPIR-V Capabilities

Issues

Version History

  • Revision 1, 2018-06-24 (Jeff Bolz)

    • Initial draft

List of Deprecated Extensions

VK_KHR_16bit_storage

Name String

VK_KHR_16bit_storage

Extension Type

Device extension

Registered Extension Number

84

Revision

1

Extension and Version Dependencies
Deprecation state
Contact
Last Modified Date

2017-09-05

IP Status

No known IP claims.

Interactions and External Dependencies
Contributors
  • Alexander Galazin, ARM

  • Jan-Harald Fredriksen, ARM

  • Joerg Wagner, ARM

  • Neil Henning, Codeplay

  • Jeff Bolz, Nvidia

  • Daniel Koch, Nvidia

  • David Neto, Google

  • John Kessenich, Google

The VK_KHR_16bit_storage extension allows use of 16-bit types in shader input and output interfaces, and push constant blocks. This extension introduces several new optional features which map to SPIR-V capabilities and allow access to 16-bit data in Block-decorated objects in the Uniform and the StorageBuffer storage classes, and objects in the PushConstant storage class. This extension allows 16-bit variables to be declared and used as user-defined shader inputs and outputs but does not change location assignment and component assignment rules.

New Enum Constants

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_16BIT_STORAGE_FEATURES_KHR

Promotion to Vulkan 1.1

All functionality in this extension is included in core Vulkan 1.1, with the KHR suffix omitted. The original type, enum and command names are still available as aliases of the core functionality.

Issues

Version History

  • Revision 1, 2017-03-23 (Alexander Galazin)

    • Initial draft

VK_KHR_bind_memory2

Name String

VK_KHR_bind_memory2

Extension Type

Device extension

Registered Extension Number

158

Revision

1

Extension and Version Dependencies
  • Requires Vulkan 1.0

Deprecation state
Contact
Last Modified Date

2017-09-05

IP Status

No known IP claims.

Interactions and External Dependencies
  • Promoted to Vulkan 1.1 Core

Contributors
  • Jeff Bolz, NVIDIA

  • Tobias Hector, Imagination Technologies

This extension provides versions of vkBindBufferMemory and vkBindImageMemory that allow multiple bindings to be performed at once, and are extensible.

This extension also introduces VK_IMAGE_CREATE_ALIAS_BIT_KHR, which allows “identical” images that alias the same memory to interpret the contents consistently, even across image layout changes.

New Object Types

None.

New Enum Constants

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_BIND_BUFFER_MEMORY_INFO_KHR

    • VK_STRUCTURE_TYPE_BIND_IMAGE_MEMORY_INFO_KHR

  • Extending VkImageCreateFlagBits:

    • VK_IMAGE_CREATE_ALIAS_BIT_KHR

New Enums

None.

New Built-In Variables

None.

New SPIR-V Capabilities

None.

Promotion to Vulkan 1.1

All functionality in this extension is included in core Vulkan 1.1, with the KHR suffix omitted. The original type, enum and command names are still available as aliases of the core functionality.

Issues

None.

Version History

  • Revision 1, 2017-05-19 (Tobias Hector)

    • Pulled bind memory functions into their own extension

VK_KHR_dedicated_allocation

Name String

VK_KHR_dedicated_allocation

Extension Type

Device extension

Registered Extension Number

128

Revision

3

Extension and Version Dependencies
Deprecation state
Contact
Last Modified Date

2017-09-05

IP Status

No known IP claims.

Interactions and External Dependencies
  • Promoted to Vulkan 1.1 Core

Contributors
  • Jeff Bolz, NVIDIA

  • Jason Ekstrand, Intel

This extension enables resources to be bound to a dedicated allocation, rather than suballocated. For any particular resource, applications can query whether a dedicated allocation is recommended, in which case using a dedicated allocation may improve the performance of access to that resource. Normal device memory allocations must support multiple resources per allocation, memory aliasing and sparse binding, which could interfere with some optimizations. Applications should query the implementation for when a dedicated allocation may be beneficial by adding VkMemoryDedicatedRequirementsKHR to the pNext chain of the VkMemoryRequirements2 structure passed as the pMemoryRequirements parameter to a call to vkGetBufferMemoryRequirements2 or vkGetImageMemoryRequirements2. Certain external handle types and external images or buffers may also depend on dedicated allocations on implementations that associate image or buffer metadata with OS-level memory objects.

This extension adds a two small structures to memory requirements querying and memory allocation: a new structure that flags whether an image/buffer should have a dedicated allocation, and a structure indicating the image or buffer that an allocation will be bound to.

New Object Types

None.

New Enum Constants

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_MEMORY_DEDICATED_REQUIREMENTS_KHR

    • VK_STRUCTURE_TYPE_MEMORY_DEDICATED_ALLOCATE_INFO_KHR

New Enums

None.

New Functions

None.

Promotion to Vulkan 1.1

All functionality in this extension is included in core Vulkan 1.1, with the KHR suffix omitted. The original type, enum and command names are still available as aliases of the core functionality.

Issues

None.

Examples

    // Create an image with a dedicated allocation based on the
    // implementation's preference

    VkImageCreateInfo imageCreateInfo =
    {
        // Image creation parameters
    };

    VkImage image;
    VkResult result = vkCreateImage(
        device,
        &imageCreateInfo,
        NULL,                               // pAllocator
        &image);

    VkMemoryDedicatedRequirementsKHR dedicatedRequirements =
    {
        VK_STRUCTURE_TYPE_MEMORY_DEDICATED_REQUIREMENTS_KHR,
        NULL,                               // pNext
    };

    VkMemoryRequirements2 memoryRequirements =
    {
        VK_STRUCTURE_TYPE_MEMORY_REQUIREMENTS_2,
        &dedicatedRequirements,             // pNext
    };

    const VkImageMemoryRequirementsInfo2 imageRequirementsInfo =
    {
        VK_STRUCTURE_TYPE_IMAGE_MEMORY_REQUIREMENTS_INFO_2,
        NULL,                               // pNext
        image
    };

    vkGetImageMemoryRequirements2(
        device,
        &imageRequirementsInfo,
        &memoryRequirements);

    if (dedicatedRequirements.prefersDedicatedAllocation) {
        // Allocate memory with VkMemoryDedicatedAllocateInfoKHR::image
        // pointing to the image we are allocating the memory for

        VkMemoryDedicatedAllocateInfoKHR dedicatedInfo =
        {
            VK_STRUCTURE_TYPE_MEMORY_DEDICATED_ALLOCATE_INFO_KHR,   // sType
            NULL,                                                   // pNext
            image,                                                  // image
            VK_NULL_HANDLE,                                         // buffer
        };

        VkMemoryAllocateInfo memoryAllocateInfo =
        {
            VK_STRUCTURE_TYPE_MEMORY_ALLOCATE_INFO,                 // sType
            &dedicatedInfo,                                         // pNext
            memoryRequirements.size,                                // allocationSize
            FindMemoryTypeIndex(memoryRequirements.memoryTypeBits), // memoryTypeIndex
        };

        VkDeviceMemory memory;
        vkAllocateMemory(
            device,
            &memoryAllocateInfo,
            NULL,                       // pAllocator
            &memory);

        // Bind the image to the memory

        vkBindImageMemory(
            device,
            image,
            memory,
            0);
    } else {
        // Take the normal memory sub-allocation path
    }

Version History

  • Revision 1, 2017-02-27 (James Jones)

    • Copy content from VK_NV_dedicated_allocation

    • Add some references to external object interactions to the overview.

  • Revision 2, 2017-03-27 (Jason Ekstrand)

    • Rework the extension to be query-based

  • Revision 3, 2017-07-31 (Jason Ekstrand)

    • Clarify that memory objects created with VkMemoryDedicatedAllocateInfoKHR can only have the specified resource bound and no others.

VK_KHR_descriptor_update_template

Name String

VK_KHR_descriptor_update_template

Extension Type

Device extension

Registered Extension Number

86

Revision

1

Extension and Version Dependencies
  • Requires Vulkan 1.0

Deprecation state
Contact
Last Modified Date

2017-09-05

IP Status

No known IP claims.

Interactions and External Dependencies
Contributors
  • Jeff Bolz, NVIDIA

  • Michael Worcester, Imagination Technologies

Applications may wish to update a fixed set of descriptors in a large number of descriptors sets very frequently, i.e. during initializaton phase or if it’s required to rebuild descriptor sets for each frame. For those cases it’s also not unlikely that all information required to update a single descriptor set is stored in a single struct. This extension provides a way to update a fixed set of descriptors in a single VkDescriptorSet with a pointer to a user defined data structure which describes the new descriptors.

New Object Types

  • VkDescriptorUpdateTemplateKHR

New Enum Constants

Extending VkStructureType:

  • VK_STRUCTURE_TYPE_DESCRIPTOR_UPDATE_TEMPLATE_CREATE_INFO_KHR

Promotion to Vulkan 1.1

vkCmdPushDescriptorSetWithTemplateKHR is included as an interaction with VK_KHR_push_descriptor. If Vulkan 1.1 and VK_KHR_push_descriptor are supported, this is included by VK_KHR_push_descriptor.

The base functionality in this extension is included in core Vulkan 1.1, with the KHR suffix omitted. The original type, enum and command names are still available as aliases of the core functionality.

Version History

  • Revision 1, 2016-01-11 (Markus Tavenrath)

    • Initial draft

VK_KHR_device_group

Name String

VK_KHR_device_group

Extension Type

Device extension

Registered Extension Number

61

Revision

3

Extension and Version Dependencies
Deprecation state
Contact
Last Modified Date

2017-10-06

IP Status

No known IP claims.

Interactions and External Dependencies
  • Promoted to Vulkan 1.1 Core

Contributors
  • Jeff Bolz, NVIDIA

  • Tobias Hector, Imagination Technologies

This extension provides functionality to use a logical device that consists of multiple physical devices, as created with the VK_KHR_device_group_creation extension. A device group can allocate memory across the subdevices, bind memory from one subdevice to a resource on another subdevice, record command buffers where some work executes on an arbitrary subset of the subdevices, and potentially present a swapchain image from one or more subdevices.

New Object Types

None.

New Enum Constants

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_MEMORY_ALLOCATE_FLAGS_INFO_KHR

    • VK_STRUCTURE_TYPE_DEVICE_GROUP_RENDER_PASS_BEGIN_INFO_KHR

    • VK_STRUCTURE_TYPE_DEVICE_GROUP_COMMAND_BUFFER_BEGIN_INFO_KHR

    • VK_STRUCTURE_TYPE_DEVICE_GROUP_SUBMIT_INFO_KHR

    • VK_STRUCTURE_TYPE_DEVICE_GROUP_BIND_SPARSE_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

    • VK_STRUCTURE_TYPE_BIND_BUFFER_MEMORY_DEVICE_GROUP_INFO_KHR

    • VK_STRUCTURE_TYPE_BIND_IMAGE_MEMORY_DEVICE_GROUP_INFO_KHR

  • Extending VkImageCreateFlagBits

    • VK_IMAGE_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT_KHR

  • Extending VkPipelineCreateFlagBits

    • VK_PIPELINE_CREATE_VIEW_INDEX_FROM_DEVICE_INDEX_BIT_KHR

    • VK_PIPELINE_CREATE_DISPATCH_BASE_KHR

  • Extending VkDependencyFlagBits

    • VK_DEPENDENCY_DEVICE_GROUP_BIT_KHR

  • Extending VkSwapchainCreateFlagBitsKHR

    • VK_SWAPCHAIN_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT_KHR

New Built-In Variables

New SPIR-V Capabilities

Promotion to Vulkan 1.1

The following enums, types and commands are included as interactions with VK_KHR_swapchain:

If Vulkan 1.1 and VK_KHR_swapchain are supported, these are included by VK_KHR_swapchain.

The base functionality in this extension is included in core Vulkan 1.1, with the KHR suffix omitted. The original type, enum and command names are still available as aliases of the core functionality.

Issues

None.

Examples

TODO

Version History

  • Revision 1, 2016-10-19 (Jeff Bolz)

    • Internal revisions

  • Revision 2, 2017-05-19 (Tobias Hector)

    • Removed extended memory bind functions to VK_KHR_bind_memory2, added dependency on that extension, and device-group-specific structs for those functions.

  • Revision 3, 2017-10-06 (Ian Elliott)

    • Corrected Vulkan 1.1 interactions with the WSI extensions. All Vulkan 1.1 WSI interactions are with the VK_KHR_swapchain extension.

  • Revision 4, 2017-10-10 (Jeff Bolz)

    • Rename "SFR" bits and structure members to use the phrase "split instance bind regions".

VK_KHR_device_group_creation

Name String

VK_KHR_device_group_creation

Extension Type

Instance extension

Registered Extension Number

71

Revision

1

Extension and Version Dependencies
  • Requires Vulkan 1.0

Deprecation state
Contact
Last Modified Date

2016-10-19

IP Status

No known IP claims.

Interactions and External Dependencies
  • Promoted to Vulkan 1.1 Core

Contributors
  • Jeff Bolz, NVIDIA

This extension provides instance-level commands to enumerate groups of physical devices, and to create a logical device from a subset of one of those groups. Such a logical device can then be used with new features in the VK_KHR_device_group extension.

New Object Types

None.

New Enum Constants

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_GROUP_PROPERTIES_KHR

    • VK_STRUCTURE_TYPE_DEVICE_GROUP_DEVICE_CREATE_INFO_KHR

  • Extending VkMemoryHeapFlagBits

    • VK_MEMORY_HEAP_MULTI_INSTANCE_BIT_KHR

New Enums

None.

Promotion to Vulkan 1.1

All functionality in this extension is included in core Vulkan 1.1, with the KHR suffix omitted. The original type, enum and command names are still available as aliases of the core functionality.

Issues

None.

Examples

    VkDeviceCreateInfo devCreateInfo = { VK_STRUCTURE_TYPE_DEVICE_CREATE_INFO };
    // (not shown) fill out devCreateInfo as usual.
    uint32_t deviceGroupCount = 0;
    VkPhysicalDeviceGroupPropertiesKHR *props = NULL;

    // Query the number of device groups
    vkEnumeratePhysicalDeviceGroupsKHR(g_vkInstance, &deviceGroupCount, NULL);

    // Allocate and initialize structures to query the device groups
    props = (VkPhysicalDeviceGroupPropertiesKHR *)malloc(deviceGroupCount*sizeof(VkPhysicalDeviceGroupPropertiesKHR));
    for (i = 0; i < deviceGroupCount; ++i) {
        props[i].sType = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_GROUP_PROPERTIES_KHR;
        props[i].pNext = NULL;
    }
    vkEnumeratePhysicalDeviceGroupsKHR(g_vkInstance, &deviceGroupCount, props);

    // If the first device group has more than one physical device. create
    // a logical device using all of the physical devices.
    VkDeviceGroupDeviceCreateInfoKHR deviceGroupInfo = { VK_STRUCTURE_TYPE_DEVICE_GROUP_DEVICE_CREATE_INFO_KHR };
    if (props[0].physicalDeviceCount > 1) {
        deviceGroupInfo.physicalDeviceCount = props[0].physicalDeviceCount;
        deviceGroupInfo.pPhysicalDevices = props[0].physicalDevices;
        devCreateInfo.pNext = &deviceGroupInfo;
    }

    vkCreateDevice(props[0].physicalDevices[0], &devCreateInfo, NULL, &g_vkDevice);
    free(props);

Version History

  • Revision 1, 2016-10-19 (Jeff Bolz)

    • Internal revisions

VK_KHR_external_fence

Name String

VK_KHR_external_fence

Extension Type

Device extension

Registered Extension Number

114

Revision

1

Extension and Version Dependencies
Deprecation state
Contact
Last Modified Date

2017-05-08

IP Status

No known IP claims.

Interactions and External Dependencies
  • Promoted to Vulkan 1.1 Core

Contributors

An application using external memory may wish to synchronize access to that memory using fences. This extension enables an application to create fences from which non-Vulkan handles that reference the underlying synchronization primitive can be exported.

New Object Types

None.

New Enum Constants

  • VK_STRUCTURE_TYPE_EXPORT_FENCE_CREATE_INFO_KHR

New Functions

None.

Promotion to Vulkan 1.1

All functionality in this extension is included in core Vulkan 1.1, with the KHR suffix omitted. The original type, enum and command names are still available as aliases of the core functionality.

Issues

This extension borrows concepts, semantics, and language from VK_KHR_external_semaphore. That extension’s issues apply equally to this extension.

VK_KHR_external_fence_capabilities

Name String

VK_KHR_external_fence_capabilities

Extension Type

Instance extension

Registered Extension Number

113

Revision

1

Extension and Version Dependencies
Deprecation state
Contact
Last Modified Date

2017-05-08

IP Status

No known IP claims.

Interactions and External Dependencies
  • Promoted to Vulkan 1.1 Core

Contributors

An application may wish to reference device fences in multiple Vulkan logical devices or instances, in multiple processes, and/or in multiple APIs. This extension provides a set of capability queries and handle definitions that allow an application to determine what types of “external” fence handles an implementation supports for a given set of use cases.

New Object Types

None.

New Enum Constants

  • VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_EXTERNAL_FENCE_INFO_KHR

  • VK_STRUCTURE_TYPE_EXTERNAL_FENCE_PROPERTIES_KHR

  • VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_ID_PROPERTIES_KHR

  • VK_LUID_SIZE_KHR

Promotion to Vulkan 1.1

All functionality in this extension is included in core Vulkan 1.1, with the KHR suffix omitted. The original type, enum and command names are still available as aliases of the core functionality.

Issues

None.

VK_KHR_external_memory

Name String

VK_KHR_external_memory

Extension Type

Device extension

Registered Extension Number

73

Revision

1

Extension and Version Dependencies
Deprecation state
Contact
Last Modified Date

2016-10-20

IP Status

No known IP claims.

Interactions and External Dependencies
Contributors
  • Jason Ekstrand, Intel

  • Ian Elliot, Google

  • Jesse Hall, Google

  • Tobias Hector, Imagination Technologies

  • James Jones, NVIDIA

  • Jeff Juliano, NVIDIA

  • Matthew Netsch, Qualcomm Technologies, Inc.

  • Daniel Rakos, AMD

  • Carsten Rohde, NVIDIA

  • Ray Smith, ARM

  • Chad Versace, Google

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 non-Vulkan handles from Vulkan memory objects such that the underlying resources can be referenced outside the scope of the Vulkan logical device that created them.

New Object Types

None.

New Enum Constants

  • VK_STRUCTURE_TYPE_EXTERNAL_MEMORY_BUFFER_CREATE_INFO_KHR

  • VK_STRUCTURE_TYPE_EXTERNAL_MEMORY_IMAGE_CREATE_INFO_KHR

  • VK_STRUCTURE_TYPE_EXPORT_MEMORY_ALLOCATE_INFO_KHR

  • VK_QUEUE_FAMILY_EXTERNAL_KHR

  • VK_ERROR_INVALID_EXTERNAL_HANDLE_KHR

New Enums

None.

New Functions

None.

Promotion to Vulkan 1.1

All functionality in this extension is included in core Vulkan 1.1, with the KHR suffix omitted. The original type, enum and command names are still available as aliases of the core functionality.

Issues

1) How do applications correlate two physical devices across process or Vulkan instance boundaries?

RESOLVED: New device ID fields have been introduced by VK_KHR_external_memory_capabilities. These fields, combined with the existing VkPhysicalDeviceProperties::driverVersion field can be used to identify compatible devices across processes, drivers, and APIs. VkPhysicalDeviceProperties::pipelineCacheUUID is not sufficient for this purpose because despite its description in the specification, it need only identify a unique pipeline cache format in practice. Multiple devices may be able to use the same pipeline cache data, and hence it would be desirable for all of them to have the same pipeline cache UUID. However, only the same concrete physical device can be used when sharing memory, so an actual unique device ID was introduced. Further, the pipeline cache UUID was specific to Vulkan, but correlation with other, non-extensible APIs is required to enable interoperation with those APIs.

2) If memory objects are shared between processes and APIs, is this considered aliasing according to the rules outlined in the Memory Aliasing section?

RESOLVED: Yes. Applications must take care to obey all restrictions imposed on aliased resources when using memory across multiple Vulkan instances or other APIs.

3) Are new image layouts or metadata required to specify image layouts and layout transitions compatible with non-Vulkan APIs, or with other instances of the same Vulkan driver?

RESOLVED: Separate instances of the same Vulkan driver running on the same GPU should have identical internal layout semantics, so applications have the tools they need to ensure views of images are consistent between the two instances. Other APIs will fall into two categories: Those that are Vulkan- compatible, and those that are Vulkan-incompatible. Vulkan-incompatible APIs will require the image to be in the GENERAL layout whenever they are accessing them.

Note this does not attempt to address cross-device transitions, nor transitions to engines on the same device which are not visible within the Vulkan API. Both of these are beyond the scope of this extension.

4) Is a new barrier flag or operation of some type needed to prepare external memory for handoff to another Vulkan instance or API and/or receive it from another instance or API?

RESOLVED: Yes. Some implementations need to perform additional cache management when transitioning memory between address spaces, and other APIs, instances, or processes may operate in a separate address space. Options for defining this transition include:

A new structure has the advantage that the type of external transition can be described in as much detail as necessary. However, there is not currently a known need for anything beyond differentiating external vs. internal accesses, so this is likely an over-engineered solution. The access flag bit has the advantage that it can be applied at buffer, image, or global granularity, and semantically it maps pretty well to the operation being described. Additionally, the API already includes VK_ACCESS_MEMORY_READ_BIT and VK_ACCESS_MEMORY_WRITE_BIT which appear to be intended for this purpose. However, there is no obvious pipeline stage that would correspond to an external access, and therefore no clear way to use VK_ACCESS_MEMORY_READ_BIT or VK_ACCESS_MEMORY_WRITE_BIT. VkDependencyFlags and VkPipelineStageFlags operate at command granularity rather than image or buffer granularity, which would make an entire pipeline barrier an internal→external or external→internal barrier. This may not be a problem in practice, but seems like the wrong scope. Another downside of VkDependencyFlags is that it lacks inherent directionality: There are not src and dst variants of it in the barrier or dependency description semantics, so two bits might need to be added to describe both internal→external and external→internal transitions. Transitioning a resource to a special queue family corresponds well with the operation of transitioning to a separate Vulkan instance, in that both operations ideally include scheduling a barrier on both sides of the transition: Both the releasing and the acquiring queue or process. Using a special queue family requires adding an additional reserved queue family index. Re-using VK_QUEUE_FAMILY_IGNORED would have left it unclear how to transition a concurrent usage resource from one process to another, since the semantics would have likely been equivalent to the currently-ignored transition of VK_QUEUE_FAMILY_IGNORED → VK_QUEUE_FAMILY_IGNORED. Fortunately, creating a new reserved queue family index is not invasive.

Based on the above analysis, the approach of transitioning to a special “external” queue family was chosen.

5) Do internal driver memory arrangements and/or other internal driver image properties need to be exported and imported when sharing images across processes or APIs.

RESOLVED: Some vendors claim this is necessary on their implementations, but it was determined that the security risks of allowing opaque meta data to be passed from applications to the driver were too high. Therefore, implementations which require metadata will need to associate it with the objects represented by the external handles, and rely on the dedicated allocation mechanism to associate the exported and imported memory objects with a single image or buffer.

6) Most prior interoperation and cross-process sharing APIs have been based on image-level sharing. Should Vulkan sharing be based on memory-object sharing or image sharing?

RESOLVED: These extensions have assumed memory-level sharing is the correct granularity. Vulkan is a lower-level API than most prior APIs, and as such attempts to closely align with to the underlying primitives of the hardware and system-level drivers it abstracts. In general, the resource that holds the backing store for both images and buffers of various types is memory. Images and buffers are merely metadata containing brief descriptions of the layout of bits within that memory.

Because memory object-based sharing is aligned with the overall Vulkan API design, it exposes the full power of Vulkan on external objects. External memory can be used as backing for sparse images, for example, whereas such usage would be awkward at best with a sharing mechanism based on higher-level primitives such as images. Further, aligning the mechanism with the API in this way provides some hope of trivial compatibility with future API enhancements. If new objects backed by memory objects are added to the API, they too can be used across processes with minimal additions to the base external memory APIs.

Earlier APIs implemented interop at a higher level, and this necessitated entirely separate sharing APIs for images and buffers. To co-exist and interoperate with those APIs, the Vulkan external sharing mechanism must accommodate their model. However, if it can be agreed that memory-based sharing is the more desirable and forward-looking design, legacy interoperation considerations can be considered another reason to favor memory-based sharing: While native and legacy driver primitives that may be used to implement sharing may not be as low-level as the API here suggests, raw memory is still the least common denominator among the types. Image-based sharing can be cleanly derived from a set of base memory- object sharing APIs with minimal effort, whereas image-based sharing does not generalize well to buffer or raw-memory sharing. Therefore, following the general Vulkan design principle of minimalism, it is better to expose even interopability with image-based native and external primitives via the memory sharing API, and place sufficient limits on their usage to ensure they can be used only as backing for equivalent Vulkan images. This provides a consistent API for applications regardless of which platform or external API they are targeting, which makes development of multi-API and multi-platform applications simpler.

7) Should Vulkan define a common external handle type and provide Vulkan functions to facilitate cross-process sharing of such handles rather than relying on native handles to define the external objects?

RESOLVED: No. Cross-process sharing of resources is best left to native platforms. There are myriad security and extensibility issues with such a mechanism, and attempting to re-solve all those issues within Vulkan does not align with Vulkan’s purpose as a graphics API. If desired, such a mechanism could be built as a layer or helper library on top of the opaque native handle defined in this family of extensions.

8) Must implementations provide additional guarantees about state implicitly included in memory objects for those memory objects that may be exported?

RESOLVED: Implementations must ensure that sharing memory objects does not transfer any information between the exporting and importing instances and APIs other than that required to share the data contained in the memory objects explicitly shared. As specific examples, data from previously freed memory objects that used the same underlying physical memory, and data from memory obects using adjacent physical memory must not be visible to applications importing an exported memory object.

9) Must implementations validate external handles the application provides as input to memory import operations?

RESOLVED: Implementations must return an error to the application if the provided memory handle cannot be used to complete the requested import operation. However, implementations need not validate handles are of the exact type specified by the application.

VK_KHR_external_memory_capabilities

Name String

VK_KHR_external_memory_capabilities

Extension Type

Instance extension

Registered Extension Number

72

Revision

1

Extension and Version Dependencies
Deprecation state
Contact
Last Modified Date

2016-10-17

IP Status

No known IP claims.

Interactions and External Dependencies
Contributors
  • Ian Elliot, Google

  • Jesse Hall, Google

  • James Jones, 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 provides a set of capability queries and handle definitions that allow an application to determine what types of “external” memory handles an implementation supports for a given set of use cases.

New Object Types

None.

New Enum Constants

  • VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_EXTERNAL_IMAGE_FORMAT_INFO_KHR

  • VK_STRUCTURE_TYPE_EXTERNAL_IMAGE_FORMAT_PROPERTIES_KHR

  • VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_EXTERNAL_BUFFER_INFO_KHR

  • VK_STRUCTURE_TYPE_EXTERNAL_BUFFER_PROPERTIES_KHR

  • VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_ID_PROPERTIES_KHR

  • VK_LUID_SIZE_KHR

Promotion to Vulkan 1.1

All functionality in this extension is included in core Vulkan 1.1, with the KHR suffix omitted. The original type, enum and command names are still available as aliases of the core functionality.

Issues

1) Why do so many external memory capabilities need to be queried on a per-memory-handle-type basis?

PROPOSED RESOLUTION: This is because some handle types are based on OS-native objects that have far more limited capabilities than the very generic Vulkan memory objects. Not all memory handle types can name memory objects that support 3D images, for example. Some handle types cannot even support the deferred image and memory binding behavior of Vulkan and require specifying the image when allocating or importing the memory object.

2) Do the VkExternalImageFormatPropertiesKHR and VkExternalBufferPropertiesKHR structs need to include a list of memory type bits that support the given handle type?

PROPOSED RESOLUTION: No. The memory types that don’t support the handle types will simply be filtered out of the results returned by vkGetImageMemoryRequirements and vkGetBufferMemoryRequirements when a set of handle types was specified at image or buffer creation time.

3) Should the non-opaque handle types be moved to their own extension?

PROPOSED RESOLUTION: Perhaps. However, defining the handle type bits does very little and does not require any platform-specific types on its own, and it’s easier to maintain the bitfield values in a single extension for now. Presumably more handle types could be added by separate extensions though, and it would be midly weird to have some platform-specific ones defined in the core spec and some in extensions

4) Do we need a D3D11_TILEPOOL type?

PROPOSED RESOLUTION: No. This is technically possible, but the synchronization is awkward. D3D11 surfaces must be synchronized using shared mutexes, and these synchronization primitives are shared by the entire memory object, so D3D11 shared allocations divided among multiple buffer and image bindings may be difficult to synchronize.

5) Should the Windows 7-compatible handle types be named “KMT” handles or “GLOBAL_SHARE” handles?

PROPOSED RESOLUTION: KMT, simply because it is more concise.

6) How do applications identify compatible devices and drivers across instance, process, and API boundaries when sharing memory?

PROPOSED RESOLUTION: New device properties are exposed that allow applications to correctly correlate devices and drivers. A device and driver UUID that must both match to ensure sharing compatibility between two Vulkan instances, or a Vulkan instance and an extensible external API are added. To allow correlating with Direct3D devices, a device LUID is added that corresponds to a DXGI adapter LUID. A driver ID is not needed for Direct3D because mismatched driver component versions are not a currently supported configuration on the Windows OS. Should support for such configurations be introduced at the OS level, further Vulkan extensions would be needed to correlate userspace component builds.

VK_KHR_external_semaphore

Name String

VK_KHR_external_semaphore

Extension Type

Device extension

Registered Extension Number

78

Revision

1

Extension and Version Dependencies
Deprecation state
Contact
Last Modified Date

2016-10-21

IP Status

No known IP claims.

Interactions and External Dependencies
  • Promoted to Vulkan 1.1 Core

Contributors
  • Jason Ekstrand, Intel

  • Jesse Hall, Google

  • Tobias Hector, Imagination Technologies

  • James Jones, NVIDIA

  • Jeff Juliano, NVIDIA

  • Matthew Netsch, Qualcomm Technologies, Inc.

  • Ray Smith, ARM

  • Chad Versace, Google

An application using external memory may wish to synchronize access to that memory using semaphores. This extension enables an application to create semaphores from which non-Vulkan handles that reference the underlying synchronization primitive can be exported.

New Object Types

None.

New Enum Constants

  • VK_STRUCTURE_TYPE_EXPORT_SEMAPHORE_CREATE_INFO_KHR

  • VK_ERROR_INVALID_EXTERNAL_HANDLE_KHR

New Functions

None.

Promotion to Vulkan 1.1

All functionality in this extension is included in core Vulkan 1.1, with the KHR suffix omitted. The original type, enum and command names are still available as aliases of the core functionality.

Issues

1) Should there be restrictions on what side effects can occur when waiting on imported semaphores that are in an invalid state?

RESOLVED: Yes. Normally, validating such state would be the responsibility of the application, and the implementation would be free to enter an undefined state if valid usage rules were violated. However, this could cause security concerns when using imported semaphores, as it would require the importing application to trust the exporting application to ensure the state is valid. Requiring this level of trust is undesirable for many potential use cases.

2) Must implementations validate external handles the application provides as input to semaphore state import operations?

RESOLVED: Implementations must return an error to the application if the provided semaphore state handle cannot be used to complete the requested import operation. However, implementations need not validate handles are of the exact type specified by the application.

VK_KHR_external_semaphore_capabilities

Name String

VK_KHR_external_semaphore_capabilities

Extension Type

Instance extension

Registered Extension Number

77

Revision

1

Extension and Version Dependencies
Deprecation state
Contact
Last Modified Date

2016-10-20

IP Status

No known IP claims.

Interactions and External Dependencies
  • Promoted to Vulkan 1.1 Core

Contributors
  • Jesse Hall, Google

  • James Jones, NVIDIA

  • Jeff Juliano, NVIDIA

An application may wish to reference device semaphores in multiple Vulkan logical devices or instances, in multiple processes, and/or in multiple APIs. This extension provides a set of capability queries and handle definitions that allow an application to determine what types of “external” semaphore handles an implementation supports for a given set of use cases.

New Object Types

None.

New Enum Constants

  • VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_EXTERNAL_SEMAPHORE_INFO_KHR

  • VK_STRUCTURE_TYPE_EXTERNAL_SEMAPHORE_PROPERTIES_KHR

  • VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_ID_PROPERTIES_KHR

  • VK_LUID_SIZE_KHR

Promotion to Vulkan 1.1

All functionality in this extension is included in core Vulkan 1.1, with the KHR suffix omitted. The original type, enum and command names are still available as aliases of the core functionality.

Issues

VK_KHR_get_memory_requirements2

Name String

VK_KHR_get_memory_requirements2

Extension Type

Device extension

Registered Extension Number

147

Revision

1

Extension and Version Dependencies
  • Requires Vulkan 1.0

Deprecation state
Contact
Last Modified Date

2017-09-05

IP Status

No known IP claims.

Interactions and External Dependencies
  • Promoted to Vulkan 1.1 Core

Contributors
  • Jason Ekstrand, Intel

  • Jeff Bolz, NVIDIA

  • Jesse Hall, Google

This extension provides new entry points to query memory requirements of images and buffers in a way that can be easily extended by other extensions, without introducing any further entry points. The Vulkan 1.0 VkMemoryRequirements and VkSparseImageMemoryRequirements structures do not include a sType/pNext, this extension wraps them in new structures with sType/pNext so an application can query a chain of memory requirements structures by constructing the chain and letting the implementation fill them in. A new command is added for each vkGet*MemoryRequrements command in core Vulkan 1.0.

New Object Types

None.

New Enum Constants

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_BUFFER_MEMORY_REQUIREMENTS_INFO_2_KHR

    • VK_STRUCTURE_TYPE_IMAGE_MEMORY_REQUIREMENTS_INFO_2_KHR

    • VK_STRUCTURE_TYPE_IMAGE_SPARSE_MEMORY_REQUIREMENTS_INFO_2_KHR

    • VK_STRUCTURE_TYPE_MEMORY_REQUIREMENTS_2_KHR

    • VK_STRUCTURE_TYPE_SPARSE_IMAGE_MEMORY_REQUIREMENTS_2_KHR

New Enums

None.

Promotion to Vulkan 1.1

All functionality in this extension is included in core Vulkan 1.1, with the KHR suffix omitted. The original type, enum and command names are still available as aliases of the core functionality.

Issues

None.

Version History

  • Revision 1, 2017-03-23 (Jason Ekstrand)

    • Internal revisions

VK_KHR_get_physical_device_properties2

Name String

VK_KHR_get_physical_device_properties2

Extension Type

Instance extension

Registered Extension Number

60

Revision

1

Extension and Version Dependencies
  • Requires Vulkan 1.0

Deprecation state
Contact
Last Modified Date

2017-09-05

IP Status

No known IP claims.

Interactions and External Dependencies
  • Promoted to Vulkan 1.1 Core

Contributors
  • Jeff Bolz, NVIDIA

  • Ian Elliott, Google

This extension provides new entry points to query device features, device properties, and format properties in a way that can be easily extended by other extensions, without introducing any further entry points. The Vulkan 1.0 feature/limit/formatproperty structures do not include sType/pNext members. This extension wraps them in new structures with sType/pNext members, so an application can query a chain of feature/limit/formatproperty structures by constructing the chain and letting the implementation fill them in. A new command is added for each vkGetPhysicalDevice* command in core Vulkan 1.0. The new feature structure (and a chain of extension structures) can also be passed in to device creation to enable features.

This extension also allows applications to use the physical-device components of device extensions before vkCreateDevice is called.

New Object Types

None.

New Enum Constants

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FEATURES_2_KHR

    • VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PROPERTIES_2_KHR

    • VK_STRUCTURE_TYPE_FORMAT_PROPERTIES_2_KHR

    • VK_STRUCTURE_TYPE_IMAGE_FORMAT_PROPERTIES_2_KHR

    • VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGE_FORMAT_INFO_2_KHR

    • VK_STRUCTURE_TYPE_QUEUE_FAMILY_PROPERTIES_2_KHR

    • VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MEMORY_PROPERTIES_2_KHR

    • VK_STRUCTURE_TYPE_SPARSE_IMAGE_FORMAT_PROPERTIES_2_KHR

    • VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SPARSE_IMAGE_FORMAT_INFO_2_KHR

New Enums

None.

Promotion to Vulkan 1.1

All functionality in this extension is included in core Vulkan 1.1, with the KHR suffix omitted. The original type, enum and command names are still available as aliases of the core functionality.

Issues

None.

Examples

    // Get features with a hypothetical future extension.
    VkHypotheticalExtensionFeaturesKHR hypotheticalFeatures =
    {
        VK_STRUCTURE_TYPE_HYPOTHETICAL_FEATURES_KHR,                            // sType
        NULL,                                                                   // pNext
    };

    VkPhysicalDeviceFeatures2KHR features =
    {
        VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FEATURES_2_KHR,                       // sType
        &hypotheticalFeatures,                                                  // pNext
    };

    // After this call, features and hypotheticalFeatures have been filled out.
    vkGetPhysicalDeviceFeatures2KHR(physicalDevice, &features);

    // Properties/limits can be chained and queried similarly.

    // Enable some features:
    VkHypotheticalExtensionFeaturesKHR enabledHypotheticalFeatures =
    {
        VK_STRUCTURE_TYPE_HYPOTHETICAL_FEATURES_KHR,                            // sType
        NULL,                                                                   // pNext
    };

    VkPhysicalDeviceFeatures2KHR enabledFeatures =
    {
        VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FEATURES_2_KHR,                       // sType
        &enabledHypotheticalFeatures,                                           // pNext
    };

    enabledFeatures.features.xyz = VK_TRUE;
    enabledHypotheticalFeatures.abc = VK_TRUE;

    VkDeviceCreateInfo deviceCreateInfo =
    {
        VK_STRUCTURE_TYPE_DEVICE_CREATE_INFO,                                   // sType
        &enabledFeatures,                                                       // pNext
        ...
        NULL,                                                                   // pEnabledFeatures
    }

    VkDevice device;
    vkCreateDevice(physicalDevice, &deviceCreateInfo, NULL, &device);

Version History

  • Revision 1, 2016-09-12 (Jeff Bolz)

    • Internal revisions

  • Revision 2, 2016-11-02 (Ian Elliott)

    • Added ability for applications to use the physical-device components of device extensions before vkCreateDevice is called.

VK_KHR_maintenance1

Name String

VK_KHR_maintenance1

Extension Type

Device extension

Registered Extension Number

70

Revision

2

Extension and Version Dependencies
  • Requires Vulkan 1.0

Deprecation state
Contact
Last Modified Date

2018-03-13

Interactions and External Dependencies
  • Promoted to Vulkan 1.1 Core

Contributors
  • Dan Ginsburg, Valve

  • Daniel Koch, NVIDIA

  • Daniel Rakos, AMD

  • Jan-Harald Fredriksen, ARM

  • Jason Ekstrand, Intel

  • Jeff Bolz, NVIDIA

  • Jesse Hall, Google

  • John Kessenich, Google

  • Michael Worcester, Imagination Technologies

  • Neil Henning, Codeplay Software Ltd.

  • Piers Daniell, NVIDIA

  • Slawomir Grajewski, Intel

  • Tobias Hector, Imagination Technologies

  • Tom Olson, ARM

VK_KHR_maintenance1 adds a collection of minor features that were intentionally left out or overlooked from the original Vulkan 1.0 release.

The new features are as follows:

  • Allow 2D and 2D array image views to be created from 3D images, which can then be used as color framebuffer attachments. This allows applications to render to slices of a 3D image.

  • Support vkCmdCopyImage between 2D array layers and 3D slices. This extension allows copying from layers of a 2D array image to slices of a 3D image and vice versa.

  • Allow negative height to be specified in the VkViewport::height field to perform y-inversion of the clip-space to framebuffer-space transform. This allows apps to avoid having to use gl_Position.y = -gl_Position.y in shaders also targeting other APIs.

  • Allow implementations to express support for doing just transfers and clears of image formats that they otherwise support no other format features for. This is done by adding new format feature flags VK_FORMAT_FEATURE_TRANSFER_SRC_BIT_KHR and VK_FORMAT_FEATURE_TRANSFER_DST_BIT_KHR.

  • Support vkCmdFillBuffer on transfer-only queues. Previously vkCmdFillBuffer was defined to only work on command buffers allocated from command pools which support graphics or compute queues. It is now allowed on queues that just support transfer operations.

  • Fix the inconsistency of how error conditions are returned between the vkCreateGraphicsPipelines and vkCreateComputePipelines functions and the vkAllocateDescriptorSets and vkAllocateCommandBuffers functions.

  • Add new VK_ERROR_OUT_OF_POOL_MEMORY_KHR error so implementations can give a more precise reason for vkAllocateDescriptorSets failures.

  • Add a new command vkTrimCommandPoolKHR which gives the implementation an opportunity to release any unused command pool memory back to the system.

New Object Types

None.

New Enum Constants

  • VK_ERROR_OUT_OF_POOL_MEMORY_KHR

  • VK_FORMAT_FEATURE_TRANSFER_SRC_BIT_KHR

  • VK_FORMAT_FEATURE_TRANSFER_DST_BIT_KHR

  • VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT_KHR

New Enums

None.

New Structures

None.

New Functions

Promotion to Vulkan 1.1

All functionality in this extension is included in core Vulkan 1.1, with the KHR suffix omitted. The original type, enum and command names are still available as aliases of the core functionality.

Issues

  1. Are viewports with zero height allowed?

    RESOLVED: Yes, although they have low utility.

Version History

  • Revision 1, 2016-10-26 (Piers Daniell)

    • Internal revisions

  • Revision 2, 2018-03-13 (Jon Leech)

    • Add issue for zero-height viewports

VK_KHR_maintenance2

Name String

VK_KHR_maintenance2

Extension Type

Device extension

Registered Extension Number

118

Revision

1

Extension and Version Dependencies
  • Requires Vulkan 1.0

Deprecation state
Contact
Last Modified Date

2017-09-05

Interactions and External Dependencies
  • Promoted to Vulkan 1.1 Core

Contributors
  • Michael Worcester, Imagination Technologies

  • Stuart Smith, Imagination Technologies

  • Jeff Bolz, NVIDIA

  • Daniel Koch, NVIDIA

  • Jan-Harald Fredriksen, ARM

  • Daniel Rakos, AMD

  • Neil Henning, Codeplay

  • Piers Daniell, NVIDIA

VK_KHR_maintenance2 adds a collection of minor features that were intentionally left out or overlooked from the original Vulkan 1.0 release.

The new features are as follows:

  • Allow the application to specify which aspect of an input attachment might be read for a given subpass.

  • Allow implementations to express the clipping behavior of points.

  • Allow creating images with usage flags that may not be supported for the base image’s format, but are supported for image views of the image that have a different but compatible format.

  • Allow creating uncompressed image views of compressed images.

  • Allow the application to select between an upper-left and lower-left origin for the tessellation domain space.

  • Adds two new image layouts for depth stencil images to allow either the depth or stencil aspect to be read-only while the other aspect is writable.

Input Attachment Specification

Input attachment specification allows an application to specify which aspect of a multi-aspect image (e.g. a combined depth stencil format) will be accessed via a subpassLoad operation.

On some implementations there may be a performance penalty if the implementation does not know (at vkCreateRenderPass time) which aspect(s) of multi-aspect images can be accessed as input attachments.

New Object Types

None.

New Enum Constants

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_RENDER_PASS_INPUT_ATTACHMENT_ASPECT_CREATE_INFO_KHR

    • VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_POINT_CLIPPING_PROPERTIES_KHR

    • VK_STRUCTURE_TYPE_IMAGE_VIEW_USAGE_CREATE_INFO_KHR

    • VK_STRUCTURE_TYPE_PIPELINE_TESSELLATION_DOMAIN_ORIGIN_STATE_CREATE_INFO_KHR

  • Extending VkImageCreateFlagBits:

    • VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT_KHR

    • VK_IMAGE_CREATE_EXTENDED_USAGE_BIT_KHR

  • Extending VkImageLayout

    • VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL_KHR

    • VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL_KHR

  • VK_POINT_CLIPPING_BEHAVIOR_ALL_CLIP_PLANES_KHR

  • VK_POINT_CLIPPING_BEHAVIOR_USER_CLIP_PLANES_ONLY_KHR

New Functions

None.

Promotion to Vulkan 1.1

All functionality in this extension is included in core Vulkan 1.1, with the KHR suffix omitted. The original type, enum and command names are still available as aliases of the core functionality.

Input Attachment Specification Example

Consider the case where a render pass has two subpasses and two attachments.

Attachment 0 has the format VK_FORMAT_D24_UNORM_S8_UINT, attachment 1 has some color format.

Subpass 0 writes to attachment 0, subpass 1 reads only the depth information from attachment 0 (using inputAttachmentRead) and writes to attachment 1.

    VkInputAttachmentAspectReferenceKHR references[] = {
        {
            .subpass = 1,
            .inputAttachmentIndex = 0,
            .aspectMask = VK_IMAGE_ASPECT_DEPTH_BIT
        }
    };

    VkRenderPassInputAttachmentAspectCreateInfoKHR specifyAspects = {
        .sType = VK_STRUCTURE_TYPE_RENDER_PASS_INPUT_ATTACHMENT_ASPECT_CREATE_INFO_KHR,
        .pNext = NULL,
        .aspectReferenceCount = 1,
        .pAspectReferences = references
    };


    VkRenderPassCreateInfo createInfo = {
        ...
        .pNext = &specifyAspects,
        ...
    }

    vkCreateRenderPass(...);

Issues

1) What is the default tessellation domain origin?

RESOLVED: Vulkan 1.0 originally inadvertently documented a lower-left origin, but the conformance tests and all implementations implemented an upper-left origin. This extension adds a control to select between lower-left (for compatibility with OpenGL) and upper-left, and we retroactively fix unextended Vulkan to have a default of an upper-left origin.

Version History

  • Revision 1, 2017-04-28

VK_KHR_maintenance3

Name String

VK_KHR_maintenance3

Extension Type

Device extension

Registered Extension Number

169

Revision

1

Extension and Version Dependencies
Deprecation state
Contact
Status

Draft

Last Modified Date

2017-09-05

Interactions and External Dependencies
  • Promoted to Vulkan 1.1 Core

Contributors
  • Jeff Bolz, NVIDIA

VK_KHR_maintenance3 adds a collection of minor features that were intentionally left out or overlooked from the original Vulkan 1.0 release.

The new features are as follows:

  • A limit on the maximum number of descriptors that are supported in a single descriptor set layout. Some implementations have a limit on the total size of descriptors in a set, which can’t be expressed in terms of the limits in Vulkan 1.0.

  • A limit on the maximum size of a single memory allocation. Some platforms have kernel interfaces that limit the maximum size of an allocation.

New Object Types

None.

New Enum Constants

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MAINTENANCE_3_PROPERTIES_KHR

    • VK_STRUCTURE_TYPE_DESCRIPTOR_SET_LAYOUT_SUPPORT_KHR

New Enums

None.

Promotion to Vulkan 1.1

All functionality in this extension is included in core Vulkan 1.1, with the KHR suffix omitted. The original type, enum and command names are still available as aliases of the core functionality.

Issues

None.

Version History

  • Revision 1, 2017-08-22

VK_KHR_multiview

Name String

VK_KHR_multiview

Extension Type

Device extension

Registered Extension Number

54

Revision

1

Extension and Version Dependencies
Deprecation state
Contact
Last Modified Date

2016-10-28

IP Status

No known IP claims.

Interactions and External Dependencies
  • Promoted to Vulkan 1.1 Core

Contributors
  • Jeff Bolz, NVIDIA

This extension has the same goal as the OpenGL ES GL_OVR_multiview extension - it enables rendering to multiple “views” by recording a single set of commands to be executed with slightly different behavior for each view. It includes a concise way to declare a render pass with multiple views, and gives implementations freedom to render the views in the most efficient way possible.

New Object Types

None.

New Enum Constants

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_RENDER_PASS_MULTIVIEW_CREATE_INFO_KHR

    • VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MULTIVIEW_FEATURES_KHR

    • VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MULTIVIEW_PROPERTIES_KHR

  • Extending VkDependencyFlagBits

    • VK_DEPENDENCY_VIEW_LOCAL_BIT_KHR

New Enums

None.

New Functions

None.

New Built-In Variables

New SPIR-V Capabilities

Promotion to Vulkan 1.1

All functionality in this extension is included in core Vulkan 1.1, with the KHR suffix omitted. The original type, enum and command names are still available as aliases of the core functionality.

Issues

None.

Examples

None.

Version History

  • Revision 1, 2016-10-28 (Jeff Bolz)

    • Internal revisions

VK_KHR_relaxed_block_layout

Name String

VK_KHR_relaxed_block_layout

Extension Type

Device extension

Registered Extension Number

145

Revision

1

Extension and Version Dependencies
  • Requires Vulkan 1.0

Deprecation state
Contact
Last Modified Date

2017-03-26

IP Status

No known IP claims.

Interactions and External Dependencies
  • Promoted to Vulkan 1.1 Core

Contributors
  • John Kessenich, Google

The VK_KHR_relaxed_block_layout extension allows implementations to indicate they can support more variation in block Offset decorations. For example, placing a vector of three floats at an offset of 16*N + 4.

See Offset and Stride Assignment for details.

Promotion to Vulkan 1.1

All functionality in this extension is included in core Vulkan 1.1, with the KHR suffix omitted. The original type, enum and command names are still available as aliases of the core functionality.

Version History

  • Revision 1, 2017-03-26 (JohnK)

VK_KHR_sampler_ycbcr_conversion

Name String

VK_KHR_sampler_ycbcr_conversion

Extension Type

Device extension

Registered Extension Number

157

Revision

1

Extension and Version Dependencies
Deprecation state
Contact
Last Modified Date

2017-08-11

IP Status

No known IP claims.

Interactions and External Dependencies
Contributors
  • Andrew Garrard, Samsung Electronics

  • Tobias Hector, Imagination Technologies

  • James Jones, NVIDIA

  • Daniel Koch, NVIDIA

  • Daniel Rakos, AMD

  • Romain Guy, Google

  • Jesse Hall, Google

  • Tom Cooksey, ARM Ltd

  • Jeff Leger, Qualcomm Technologies, Inc

  • Jan-Harald Fredriksen, ARM Ltd

  • Jan Outters, Samsung Electronics

  • Alon Or-bach, Samsung Electronics

  • Michael Worcester, Imagination Technologies

  • Jeff Bolz, NVIDIA

  • Tony Zlatinski, NVIDIA

  • Matthew Netsch, Qualcomm Technologies, Inc

This extension provides the ability to perform specified color space conversions during texture sampling operations. It also adds a selection of multi-planar formats, including the ability to bind memory to the planes of an image collectively or separately.

New Enum Constants

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_SAMPLER_YCBCR_CONVERSION_CREATE_INFO_KHR

    • VK_STRUCTURE_TYPE_SAMPLER_YCBCR_CONVERSION_INFO_KHR

    • VK_STRUCTURE_TYPE_BIND_IMAGE_PLANE_MEMORY_INFO_KHR

    • VK_STRUCTURE_TYPE_IMAGE_PLANE_MEMORY_REQUIREMENTS_INFO_KHR

    • VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SAMPLER_YCBCR_CONVERSION_FEATURES_KHR

  • Extending VkFormat:

    • VK_FORMAT_G8B8G8R8_422_UNORM_KHR

    • VK_FORMAT_B8G8R8G8_422_UNORM_KHR

    • VK_FORMAT_G8_B8_R8_3PLANE_420_UNORM_KHR

    • VK_FORMAT_G8_B8R8_2PLANE_420_UNORM_KHR

    • VK_FORMAT_G8_B8_R8_3PLANE_422_UNORM_KHR

    • VK_FORMAT_G8_B8R8_2PLANE_422_UNORM_KHR

    • VK_FORMAT_G8_B8_R8_3PLANE_444_UNORM_KHR

    • VK_FORMAT_R10X6_UNORM_PACK16_KHR

    • VK_FORMAT_R10X6G10X6_UNORM_2PACK16_KHR

    • VK_FORMAT_R10X6G10X6B10X6A10X6_UNORM_4PACK16_KHR

    • VK_FORMAT_G10X6B10X6G10X6R10X6_422_UNORM_4PACK16_KHR

    • VK_FORMAT_B10X6G10X6R10X6G10X6_422_UNORM_4PACK16_KHR

    • VK_FORMAT_G10X6_B10X6_R10X6_3PLANE_420_UNORM_3PACK16_KHR

    • VK_FORMAT_G10X6_B10X6R10X6_2PLANE_420_UNORM_3PACK16_KHR

    • VK_FORMAT_G10X6_B10X6_R10X6_3PLANE_422_UNORM_3PACK16_KHR

    • VK_FORMAT_G10X6_B10X6R10X6_2PLANE_422_UNORM_3PACK16_KHR

    • VK_FORMAT_G10X6_B10X6_R10X6_3PLANE_444_UNORM_3PACK16_KHR

    • VK_FORMAT_R12X4_UNORM_PACK16_KHR

    • VK_FORMAT_R12X4G12X4_UNORM_2PACK16_KHR

    • VK_FORMAT_R12X4G12X4B12X4A12X4_UNORM_4PACK16_KHR

    • VK_FORMAT_G12X4B12X4G12X4R12X4_422_UNORM_4PACK16_KHR

    • VK_FORMAT_B12X4G12X4R12X4G12X4_422_UNORM_4PACK16_KHR

    • VK_FORMAT_G12X4_B12X4_R12X4_3PLANE_420_UNORM_3PACK16_KHR

    • VK_FORMAT_G12X4_B12X4R12X4_2PLANE_420_UNORM_3PACK16_KHR

    • VK_FORMAT_G12X4_B12X4_R12X4_3PLANE_422_UNORM_3PACK16_KHR

    • VK_FORMAT_G12X4_B12X4R12X4_2PLANE_422_UNORM_3PACK16_KHR

    • VK_FORMAT_G12X4_B12X4_R12X4_3PLANE_444_UNORM_3PACK16_KHR

    • VK_FORMAT_G16B16G16R16_422_UNORM_KHR

    • VK_FORMAT_B16G16R16G16_422_UNORM_KHR

    • VK_FORMAT_G16_B16_R16_3PLANE_420_UNORM_KHR

    • VK_FORMAT_G16_B16R16_2PLANE_420_UNORM_KHR

    • VK_FORMAT_G16_B16_R16_3PLANE_422_UNORM_KHR

    • VK_FORMAT_G16_B16R16_2PLANE_422_UNORM_KHR

    • VK_FORMAT_G16_B16_R16_3PLANE_444_UNORM_KHR

  • Extending VkImageAspectFlagBits:

    • VK_IMAGE_ASPECT_PLANE_0_BIT_KHR

    • VK_IMAGE_ASPECT_PLANE_1_BIT_KHR

    • VK_IMAGE_ASPECT_PLANE_2_BIT_KHR

  • Extending VkImageCreateFlagBits:

    • VK_IMAGE_CREATE_DISJOINT_BIT_KHR

  • Extending VkFormatFeatureFlagBits:

    • VK_FORMAT_FEATURE_MIDPOINT_CHROMA_SAMPLES_BIT_KHR

    • VK_FORMAT_FEATURE_COSITED_CHROMA_SAMPLES_BIT_KHR

    • VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_LINEAR_FILTER_BIT_KHR

    • VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_SEPARATE_RECONSTRUCTION_FILTER_BIT_KHR

    • VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_CHROMA_RECONSTRUCTION_EXPLICIT_BIT_KHR

    • VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_CHROMA_RECONSTRUCTION_EXPLICIT_FORCEABLE_BIT_KHR

    • VK_FORMAT_FEATURE_DISJOINT_BIT_KHR

Promotion to Vulkan 1.1

All functionality in this extension is included in core Vulkan 1.1, with the KHR suffix omitted. The original type, enum and command names are still available as aliases of the core functionality.

Version History

  • Revision 1, 2017-01-24 (Andrew Garrard)

    • Initial draft

  • Revision 2, 2017-01-25 (Andrew Garrard)

    • After initial feedback

  • Revision 3, 2017-01-27 (Andrew Garrard)

    • Higher bit depth formats, renaming, swizzle

  • Revision 4, 2017-02-22 (Andrew Garrard)

    • Added query function, formats as RGB, clarifications

  • Revision 5, 2017-04 (Andrew Garrard)

    • Simplified query and removed output conversions

  • Version 6, 2017-4-24 (Andrew Garrard)

    • Tidying, incorporated new image query, restored transfer functions

  • Version 7, 2017-04-25 (Andrew Garrard)

    • Added cosited option/midpoint requirement for formats, "bypassConversion"

  • Version 8, 2017-04-25 (Andrew Garrard)

    • Simplified further

  • Version 9, 2017-04-27 (Andrew Garrard)

    • Disjoint no more

  • Version 10, 2017-04-28 (Andrew Garrard)

    • Restored disjoint

  • Version 11, 2017-04-29 (Andrew Garrard)

    • Now Ycbcr conversion, and KHR

  • Version 12, 2017-06-06 (Andrew Garrard)

    • Added conversion to image view creation

  • Version 13, 2017-07-13 (Andrew Garrard)

    • Allowed cosited-only chroma samples for formats

  • Version 14, 2017-08-11 (Andrew Garrard)

    • Reflected quantization changes in BT.2100-1

VK_KHR_shader_draw_parameters

Name String

VK_KHR_shader_draw_parameters

Extension Type

Device extension

Registered Extension Number

64

Revision

1

Extension and Version Dependencies
  • Requires Vulkan 1.0

Deprecation state
Contact
Last Modified Date

2017-09-05

IP Status

No known IP claims.

Interactions and External Dependencies
Contributors
  • Daniel Koch, NVIDIA Corporation

  • Jeff Bolz, NVIDIA

  • Daniel Rakos, AMD

  • Jan-Harald Fredriksen, ARM

  • John Kessenich, Google

  • Stuart Smith, IMG

This extension adds support for the following SPIR-V extension in Vulkan:

  • SPV_KHR_shader_draw_parameters

The extension provides access to three additional built-in shader variables in Vulkan:

  • BaseInstance, which contains the firstInstance parameter passed to draw commands,

  • BaseVertex, which contains the firstVertex/vertexOffset parameter passed to draw commands, and

  • DrawIndex, which contains the index of the draw call currently being processed from an indirect draw call.

When using GLSL source-based shader languages, the following variables from GL_ARB_shader_draw_parameters can map to these SPIR-V built-in decorations:

  • in int gl_BaseInstanceARB;BaseInstance,

  • in int gl_BaseVertexARB;BaseVertex, and

  • in int gl_DrawIDARB;DrawIndex.

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

Promotion to Vulkan 1.1

All functionality in this extension is included in core Vulkan 1.1, however a feature bit was added to distinguish whether it’s actually available or not.

Issues

1) Is this the same functionality as GL_ARB_shader_draw_parameters?

RESOLVED: It’s actually a superset as it also adds in support for arrayed drawing commands.

In GL for GL_ARB_shader_draw_parameters, gl_BaseVertexARB holds the integer value passed to the parameter to the command that resulted in the current shader invocation. In the case where the command has no baseVertex parameter, the value of gl_BaseVertexARB is zero. This means that gl_BaseVertexARB = baseVertex (for glDrawElements commands with baseVertex) or 0. In particular there are no glDrawArrays commands that take a baseVertex parameter.

Now in Vulkan, we have BaseVertex = vertexOffset (for indexed drawing commands) or firstVertex (for arrayed drawing commands), and so Vulkan’s version is really a superset of GL functionality.

Version History

  • Revision 1, 2016-10-05 (Daniel Koch)

    • Internal revisions

VK_KHR_storage_buffer_storage_class

Name String

VK_KHR_storage_buffer_storage_class

Extension Type

Device extension

Registered Extension Number

132

Revision

1

Extension and Version Dependencies
  • Requires Vulkan 1.0

Deprecation state
Contact
Last Modified Date

2017-09-05

IP Status

No known IP claims.

Interactions and External Dependencies
Contributors
  • Alexander Galazin, ARM

  • David Neto, Google

This extension adds support for the following SPIR-V extension in Vulkan:

  • SPV_KHR_storage_buffer_storage_class

This extension provides a new SPIR-V StorageBuffer storage class. A Block-decorated object in this class is equivalent to a BufferBlock-decorated object in the Uniform storage class.

New Enum Constants

None.

New Structures

None.

Promotion to Vulkan 1.1

All functionality in this extension is included in core Vulkan 1.1.

Issues

None.

Version History

  • Revision 1, 2017-03-23 (Alexander Galazin)

    • Initial draft

VK_KHR_variable_pointers

Name String

VK_KHR_variable_pointers

Extension Type

Device extension

Registered Extension Number

121

Revision

1

Extension and Version Dependencies
Deprecation state
Contact
Last Modified Date

2017-09-05

IP Status

No known IP claims.

Interactions and External Dependencies
Contributors
  • John Kessenich, Google

  • Neil Henning, Codeplay

  • David Neto, Google

  • Daniel Koch, Nvidia

  • Graeme Leese, Broadcom

  • Weifeng Zhang, Qualcomm

  • Stephen Clarke, Imagination Technologies

  • Jason Ekstrand, Intel

  • Jesse Hall, Google

The VK_KHR_variable_pointers extension allows implementations to indicate their level of support for the SPV_KHR_variable_pointers SPIR-V extension. The SPIR-V extension allows shader modules to use invocation-private pointers into uniform and/or storage buffers, where the pointer values can be dynamic and non-uniform.

The SPV_KHR_variable_pointers extension introduces two capabilities. The first, VariablePointersStorageBuffer, must be supported by all implementations of this extension. The second, VariablePointers, is optional.

New Enum Constants

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VARIABLE_POINTER_FEATURES_KHR

Promotion to Vulkan 1.1

All functionality in this extension is included in core Vulkan 1.1, with the KHR suffix omitted, however support for the variablePointersStorageBuffer feature is made optional. The original type, enum and command names are still available as aliases of the core functionality.

Issues

1) Do we need an optional property for the SPIR-V VariablePointersStorageBuffer capability or should it be mandatory when this extension is advertised?

RESOLVED: Add it as a distinct feature, but make support mandatory. Adding it as a feature makes the extension easier to include in a future core API version. In the extension, the feature is mandatory, so that presence of the extension guarantees some functionality. When included in a core API version, the feature would be optional.

2) Can support for these capabilities vary between shader stages?

RESOLVED: No, if the capability is supported in any stage it must be supported in all stages.

3) Should the capabilities be features or limits?

RESOLVED: Features, primarily for consistency with other similar extensions.

Version History

  • Revision 1, 2017-03-14 (Jesse Hall and John Kessenich)

    • Internal revisions

VK_EXT_debug_marker

Name String

VK_EXT_debug_marker

Extension Type

Device extension

Registered Extension Number

23

Revision

4

Extension and Version Dependencies
Deprecation state
Contact
Last Modified Date

2017-01-31

IP Status

No known IP claims.

Contributors
  • Baldur Karlsson

  • Dan Ginsburg, Valve

  • Jon Ashburn, LunarG

  • Kyle Spagnoli, NVIDIA

The VK_EXT_debug_marker extension is a device extension. It introduces concepts of object naming and tagging, for better tracking of Vulkan objects, as well as additional commands for recording annotations of named sections of a workload to aid organization and offline analysis in external tools.

New Object Types

None

New Enum Constants

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_DEBUG_MARKER_OBJECT_NAME_INFO_EXT

    • VK_STRUCTURE_TYPE_DEBUG_MARKER_OBJECT_TAG_INFO_EXT

    • VK_STRUCTURE_TYPE_DEBUG_MARKER_MARKER_INFO_EXT

New Enums

None

Examples

Example 1

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_vkDebugMarkerSetObjectNameEXT pfnDebugMarkerSetObjectNameEXT = (PFN_vkDebugMarkerSetObjectNameEXT)vkGetDeviceProcAddr(device, "vkDebugMarkerSetObjectNameEXT");

    // Set a name on the image
    const VkDebugMarkerObjectNameInfoEXT imageNameInfo =
    {
        VK_STRUCTURE_TYPE_DEBUG_MARKER_OBJECT_NAME_INFO_EXT, // sType
        NULL,                                           // pNext
        VK_DEBUG_REPORT_OBJECT_TYPE_IMAGE_EXT,          // objectType
        (uint64_t)image,                                // object
        "Brick Diffuse Texture",                        // pObjectName
    };

    pfnDebugMarkerSetObjectNameEXT(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 2

Annotating regions of a workload with naming information so that offline analysis tools can display a more usable visualisation of the commands submitted.

    extern VkDevice device;
    extern VkCommandBuffer commandBuffer;

    // Must call extension functions through a function pointer:
    PFN_vkCmdDebugMarkerBeginEXT pfnCmdDebugMarkerBeginEXT = (PFN_vkCmdDebugMarkerBeginEXT)vkGetDeviceProcAddr(device, "vkCmdDebugMarkerBeginEXT");
    PFN_vkCmdDebugMarkerEndEXT pfnCmdDebugMarkerEndEXT = (PFN_vkCmdDebugMarkerEndEXT)vkGetDeviceProcAddr(device, "vkCmdDebugMarkerEndEXT");
    PFN_vkCmdDebugMarkerInsertEXT pfnCmdDebugMarkerInsertEXT = (PFN_vkCmdDebugMarkerInsertEXT)vkGetDeviceProcAddr(device, "vkCmdDebugMarkerInsertEXT");

    // Describe the area being rendered
    const VkDebugMarkerMarkerInfoEXT houseMarker =
    {
        VK_STRUCTURE_TYPE_DEBUG_MARKER_MARKER_INFO_EXT, // sType
        NULL,                                           // pNext
        "Brick House",                                  // pMarkerName
        { 1.0f, 0.0f, 0.0f, 1.0f },                     // color
    };

    // Start an annotated group of calls under the 'Brick House' name
    pfnCmdDebugMarkerBeginEXT(commandBuffer, &houseMarker);
    {
        // A mutable structure for each part being rendered
        VkDebugMarkerMarkerInfoEXT housePartMarker =
        {
            VK_STRUCTURE_TYPE_DEBUG_MARKER_MARKER_INFO_EXT, // sType
            NULL,                                           // pNext
            NULL,                                           // pMarkerName
            { 0.0f, 0.0f, 0.0f, 0.0f },                     // color
        };

        // Set the name and insert the marker
        housePartMarker.pMarkerName = "Walls";
        pfnCmdDebugMarkerInsertEXT(commandBuffer, &housePartMarker);

        // Insert the drawcall for the walls
        vkCmdDrawIndexed(commandBuffer, 1000, 1, 0, 0, 0);

        // Insert a recursive region for two sets of windows
        housePartMarker.pMarkerName = "Windows";
        pfnCmdDebugMarkerBeginEXT(commandBuffer, &housePartMarker);
        {
            vkCmdDrawIndexed(commandBuffer, 75, 6, 1000, 0, 0);
            vkCmdDrawIndexed(commandBuffer, 100, 2, 1450, 0, 0);
        }
        pfnCmdDebugMarkerEndEXT(commandBuffer);

        housePartMarker.pMarkerName = "Front Door";
        pfnCmdDebugMarkerInsertEXT(commandBuffer, &housePartMarker);

        vkCmdDrawIndexed(commandBuffer, 350, 1, 1650, 0, 0);

        housePartMarker.pMarkerName = "Roof";
        pfnCmdDebugMarkerInsertEXT(commandBuffer, &housePartMarker);

        vkCmdDrawIndexed(commandBuffer, 500, 1, 2000, 0, 0);
    }
    // End the house annotation started above
    pfnCmdDebugMarkerEndEXT(commandBuffer);

Issues

1) Should the tag or name for an object be specified using the pNext parameter in the object’s Vk*CreateInfo structure?

RESOLVED: No. While this fits with other Vulkan patterns and would allow more type safety and future proofing against future objects, it has notable downsides. In particular passing the name at Vk*CreateInfo time does not allow renaming, prevents late binding of naming information, and does not allow naming of implicitly created objects such as queues and swapchain images.

2) Should the command annotation functions vkCmdDebugMarkerBeginEXT and vkCmdDebugMarkerEndEXT support the ability to specify a color?

RESOLVED: Yes. The functions have been expanded to take an optional color which can be used at will by implementations consuming the command buffer annotations in their visualisation.

3) Should the functions added in this extension accept an extensible structure as their parameter for a more flexible API, as opposed to direct function parameters? If so, which functions?

RESOLVED: Yes. All functions have been modified to take a structure type with extensible pNext pointer, to allow future extensions to add additional annotation information in the same commands.

Version History

  • Revision 1, 2016-02-24 (Baldur Karlsson)

    • Initial draft, based on LunarG marker spec

  • Revision 2, 2016-02-26 (Baldur Karlsson)

    • Renamed Dbg to DebugMarker in function names

    • Allow markers in secondary command buffers under certain circumstances

    • Minor language tweaks and edits

  • Revision 3, 2016-04-23 (Baldur Karlsson)

    • Reorganise spec layout to closer match desired organisation

    • Added optional color to markers (both regions and inserted labels)

    • Changed functions to take extensible structs instead of direct function parameters

  • Revision 4, 2017-01-31 (Baldur Karlsson)

    • Added explicit dependency on VK_EXT_debug_report

    • Moved definition of VkDebugReportObjectTypeEXT to debug report chapter.

    • Fixed typo in dates in revision history

VK_EXT_debug_report

Name String

VK_EXT_debug_report

Extension Type

Instance extension

Registered Extension Number

12

Revision

9

Extension and Version Dependencies
  • Requires Vulkan 1.0

Deprecation state
Contact
Last Modified Date

2017-09-12

IP Status

No known IP claims.

Contributors
  • Courtney Goeltzenleuchter, LunarG

  • Dan Ginsburg, Valve

  • Jon Ashburn, LunarG

  • Mark Lobodzinski, LunarG

Due to the nature of the Vulkan interface, there is very little error information available to the developer and application. By enabling optional validation layers and using the VK_EXT_debug_report extension, developers can obtain much more detailed feedback on the application’s use of Vulkan. This extension defines a way for layers and the implementation to call back to the application for events of interest to the application.

New Object Types

New Enum Constants

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_DEBUG_REPORT_CALLBACK_CREATE_INFO_EXT

  • Extending VkResult:

    • VK_ERROR_VALIDATION_FAILED_EXT

New Function Pointers

Examples

VK_EXT_debug_report allows an application to register multiple callbacks with the validation layers. 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 VkDebugReportCallbackCreateInfoEXT 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 vkCreateDebugReportCallbackEXT 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.

    VkResult res;
    VkDebugReportCallbackEXT cb1, cb2, cb3;

    VkDebugReportCallbackCreateInfoEXT callback1 = {
            VK_STRUCTURE_TYPE_DEBUG_REPORT_CALLBACK_CREATE_INFO_EXT,    // sType
            NULL,                                                       // pNext
            VK_DEBUG_REPORT_ERROR_BIT_EXT |                             // flags
            VK_DEBUG_REPORT_WARNING_BIT_EXT,
            myOutputDebugString,                                        // pfnCallback
            NULL                                                        // pUserData
    };
    res = vkCreateDebugReportCallbackEXT(instance, &callback1, &cb1);
    if (res != VK_SUCCESS)
       /* Do error handling for VK_ERROR_OUT_OF_MEMORY */

    callback.flags = VK_DEBUG_REPORT_ERROR_BIT_EXT;
    callback.pfnCallback = myDebugBreak;
    callback.pUserData = NULL;
    res = vkCreateDebugReportCallbackEXT(instance, &callback, &cb2);
    if (res != VK_SUCCESS)
       /* Do error handling for VK_ERROR_OUT_OF_MEMORY */

    VkDebugReportCallbackCreateInfoEXT callback3 = {
            VK_STRUCTURE_TYPE_DEBUG_REPORT_CALLBACK_CREATE_INFO_EXT,    // sType
            NULL,                                                       // pNext
            VK_DEBUG_REPORT_WARNING_BIT_EXT,                            // flags
            mystdOutLogger,                                             // pfnCallback
            NULL                                                        // pUserData
    };
    res = vkCreateDebugReportCallbackEXT(instance, &callback3, &cb3);
    if (res != VK_SUCCESS)
       /* Do error handling for VK_ERROR_OUT_OF_MEMORY */

    ...

    /* remove callbacks when cleaning up */
    vkDestroyDebugReportCallbackEXT(instance, cb1);
    vkDestroyDebugReportCallbackEXT(instance, cb2);
    vkDestroyDebugReportCallbackEXT(instance, cb3);
Note

In the initial release of the VK_EXT_debug_report extension, the token VK_STRUCTURE_TYPE_DEBUG_REPORT_CREATE_INFO_EXT was used. Starting in version 2 of the extension branch, VK_STRUCTURE_TYPE_DEBUG_REPORT_CALLBACK_CREATE_INFO_EXT is used instead for consistency with Vulkan naming rules. The older enum is still available for backwards compatibility.

Note

In the initial release of the VK_EXT_debug_report extension, the token VK_DEBUG_REPORT_OBJECT_TYPE_DEBUG_REPORT_EXT was used. Starting in version 8 of the extension branch, VK_DEBUG_REPORT_OBJECT_TYPE_DEBUG_REPORT_CALLBACK_EXT_EXT is used instead for consistency with Vulkan naming rules. The older enum is still available for backwards compatibility.

Issues

1) What is the hierarchy / seriousness of the message flags? E.g. ERROR > WARN > PERF_WARN …​

RESOLVED: There is no specific hierarchy. Each bit is independent and should be checked via bitwise AND. For example:

    if (localFlags & VK_DEBUG_REPORT_ERROR_BIT_EXT) {
        process error message
    }
    if (localFlags & VK_DEBUG_REPORT_DEBUG_BIT_EXT) {
        process debug message
    }

The validation layers do use them in a hierarchical way (ERROR > WARN > PERF, WARN > DEBUG > INFO) and they (at least at the time of this writing) only set one bit at a time. But it is not a requirement of this extension.

It is possible that a layer may intercept and change, or augment the flags with extension values the application’s debug report handler may not be familiar with, so it is important to treat each flag independently.

2) Should there be a VU requiring VkDebugReportCallbackCreateInfoEXT::flags to be non-zero?

RESOLVED: It may not be very useful, but we do not need VU statement requiring the VkDebugReportCallbackCreateInfoEXT::msgFlags at create-time to be non-zero. One can imagine that apps may prefer it as it allows them to set the mask as desired - including nothing - at runtime without having to check.

3) What is the difference between VK_DEBUG_REPORT_DEBUG_BIT_EXT and VK_DEBUG_REPORT_INFORMATION_BIT_EXT?

RESOLVED: VK_DEBUG_REPORT_DEBUG_BIT_EXT specifies information that could be useful debugging the Vulkan implementation itself.

Version History

  • Revision 1, 2015-05-20 (Courtney Goetzenleuchter)

    • Initial draft, based on LunarG KHR spec, other KHR specs

  • Revision 2, 2016-02-16 (Courtney Goetzenleuchter)

    • Update usage, documentation

  • Revision 3, 2016-06-14 (Courtney Goetzenleuchter)

    • Update VK_EXT_DEBUG_REPORT_SPEC_VERSION to indicate added support for vkCreateInstance and vkDestroyInstance

  • Revision 4, 2016-12-08 (Mark Lobodzinski)

    • Added Display_KHR, DisplayModeKHR extension objects

    • Added ObjectTable_NVX, IndirectCommandsLayout_NVX extension objects

    • Bumped spec revision

    • Retroactively added version history

  • Revision 5, 2017-01-31 (Baldur Karlsson)

  • Revision 6, 2017-01-31 (Baldur Karlsson)

    • Added VK_DEBUG_REPORT_OBJECT_TYPE_DESCRIPTOR_UPDATE_TEMPLATE_KHR_EXT

  • Revision 7, 2017-04-20 (Courtney Goeltzenleuchter)

    • Clarify wording and address questions from developers.

  • Revision 8, 2017-04-21 (Courtney Goeltzenleuchter)

    • Remove unused enum VkDebugReportErrorEXT

  • Revision 9, 2017-09-12 (Tobias Hector)

    • Added interactions with Vulkan 1.1

VK_AMD_draw_indirect_count

Name String

VK_AMD_draw_indirect_count

Extension Type

Device extension

Registered Extension Number

34

Revision

1

Extension and Version Dependencies
  • Requires Vulkan 1.0

Deprecation state
Contact
Last Modified Date

2016-08-23

IP Status

No known IP claims.

Contributors
  • Matthaeus G. Chajdas, AMD

  • Derrick Owens, AMD

  • Graham Sellers, AMD

  • Daniel Rakos, AMD

  • Dominik Witczak, AMD

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.

Version History

  • Revision 2, 2016-08-23 (Dominik Witczak)

    • Minor fixes

  • Revision 1, 2016-07-21 (Matthaeus Chajdas)

    • Initial draft

VK_AMD_negative_viewport_height

Name String

VK_AMD_negative_viewport_height

Extension Type

Device extension

Registered Extension Number

36

Revision

1

Extension and Version Dependencies
  • Requires Vulkan 1.0

Deprecation state
Contact
Last Modified Date

2016-09-02

IP Status

No known IP claims.

Contributors
  • Matthaeus G. Chajdas, AMD

  • Graham Sellers, AMD

  • Baldur Karlsson

Interactions and External Dependencies
  • Obsoleted by VK_KHR_maintenance1

  • Obsoleted by Vulkan 1.1

This extension allows an application to specify a negative viewport height. The result is that the viewport transformation will flip along the y-axis.

  • Allow negative height to be specified in the VkViewport::height field to perform y-inversion of the clip-space to framebuffer-space transform. This allows apps to avoid having to use gl_Position.y = -gl_Position.y in shaders also targeting other APIs.

Obsoletion by VK_KHR_maintenance1 and Vulkan 1.1

Functionality in this extension is included in VK_KHR_maintenance1 and Vulkan 1.1. Due to some slight behavioral differences, this extension must not be enabled alongside VK_KHR_maintenance1, or in an instance created with version 1.1 or later requested in VkApplicationInfo::apiVersion.

Version History

  • Revision 1, 2016-09-02 (Matthaeus Chajdas)

    • Initial draft

VK_NV_dedicated_allocation

Name String

VK_NV_dedicated_allocation

Extension Type

Device extension

Registered Extension Number

27

Revision

1

Extension and Version Dependencies
  • Requires Vulkan 1.0

Deprecation state
Contact
Last Modified Date

2016-05-31

IP Status

No known IP claims.

Contributors
  • Jeff Bolz, NVIDIA

This extension allows device memory to be allocated for a particular buffer or image resource, which on some devices can significantly improve the performance of that resource. Normal device memory allocations must support memory aliasing and sparse binding, which could interfere with optimizations like framebuffer compression or efficient page table usage. This is important for render targets and very large resources, but need not (and probably should not) be used for smaller resources that can benefit from suballocation.

This extension adds a few small structures to resource creation and memory allocation: a new structure that flags whether am image/buffer will have a dedicated allocation, and a structure indicating the image or buffer that an allocation will be bound to.

New Object Types

None.

New Enum Constants

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_DEDICATED_ALLOCATION_IMAGE_CREATE_INFO_NV

    • VK_STRUCTURE_TYPE_DEDICATED_ALLOCATION_BUFFER_CREATE_INFO_NV

    • VK_STRUCTURE_TYPE_DEDICATED_ALLOCATION_MEMORY_ALLOCATE_INFO_NV

New Enums

None.

New Functions

None.

Issues

None.

Examples

    // Create an image with
    // VkDedicatedAllocationImageCreateInfoNV::dedicatedAllocation
    // set to VK_TRUE

    VkDedicatedAllocationImageCreateInfoNV dedicatedImageInfo =
    {
        VK_STRUCTURE_TYPE_DEDICATED_ALLOCATION_IMAGE_CREATE_INFO_NV,            // sType
        NULL,                                                                   // pNext
        VK_TRUE,                                                                // dedicatedAllocation
    };

    VkImageCreateInfo imageCreateInfo =
    {
        VK_STRUCTURE_TYPE_IMAGE_CREATE_INFO,    // sType
        &dedicatedImageInfo                     // pNext
        // Other members set as usual
    };

    VkImage image;
    VkResult result = vkCreateImage(
        device,
        &imageCreateInfo,
        NULL,                       // pAllocator
        &image);

    VkMemoryRequirements memoryRequirements;
    vkGetImageMemoryRequirements(
        device,
        image,
        &memoryRequirements);

    // Allocate memory with VkDedicatedAllocationMemoryAllocateInfoNV::image
    // pointing to the image we are allocating the memory for

    VkDedicatedAllocationMemoryAllocateInfoNV dedicatedInfo =
    {
        VK_STRUCTURE_TYPE_DEDICATED_ALLOCATION_MEMORY_ALLOCATE_INFO_NV,             // sType
        NULL,                                                                       // pNext
        image,                                                                      // image
        VK_NULL_HANDLE,                                                             // buffer
    };

    VkMemoryAllocateInfo memoryAllocateInfo =
    {
        VK_STRUCTURE_TYPE_MEMORY_ALLOCATE_INFO,                 // sType
        &dedicatedInfo,                                         // pNext
        memoryRequirements.size,                                // allocationSize
        FindMemoryTypeIndex(memoryRequirements.memoryTypeBits), // memoryTypeIndex
    };

    VkDeviceMemory memory;
    vkAllocateMemory(
        device,
        &memoryAllocateInfo,
        NULL,                       // pAllocator
        &memory);

    // Bind the image to the memory

    vkBindImageMemory(
        device,
        image,
        memory,
        0);

Version History

  • Revision 1, 2016-05-31 (Jeff Bolz)

    • Internal revisions

VK_NV_external_memory

Name String

VK_NV_external_memory

Extension Type

Device extension

Registered Extension Number

57

Revision

1

Extension and Version Dependencies
Deprecation state
Contact
Last Modified Date

2016-08-19

IP Status

No known IP claims.

Contributors
  • James Jones, NVIDIA

  • Carsten Rohde, NVIDIA

Applications may wish to export memory to other Vulkan instances or other APIs, or import memory from other Vulkan instances or other APIs to enable Vulkan workloads to be split up across application module, process, or API boundaries. This extension enables applications to create exportable Vulkan memory objects such that the underlying resources can be referenced outside the Vulkan instance that created them.

New Object Types

None.

New Enum Constants

Extending VkStructureType:

  • VK_STRUCTURE_TYPE_EXTERNAL_MEMORY_IMAGE_CREATE_INFO_NV

  • VK_STRUCTURE_TYPE_EXPORT_MEMORY_ALLOCATE_INFO_NV

New Enums

None.

New Functions

None.

Issues

1) If memory objects are shared between processes and APIs, is this considered aliasing according to the rules outlined in the Memory Aliasing section?

RESOLVED: Yes, but strict exceptions to the rules are added to allow some forms of aliasing in these cases. Further, other extensions may build upon these new aliasing rules to define specific support usage within Vulkan for imported native memory objects, or memory objects from other APIs.

2) Are new image layouts or metadata required to specify image layouts and layout transitions compatible with non-Vulkan APIs, or with other instances of the same Vulkan driver?

RESOLVED: No. Separate instances of the same Vulkan driver running on the same GPU should have identical internal layout semantics, so applictions have the tools they need to ensure views of images are consistent between the two instances. Other APIs will fall into two categories: Those that are Vulkan compatible (a term to be defined by subsequent interopability extensions), or Vulkan incompatible. When sharing images with Vulkan incompatible APIs, the Vulkan image must be transitioned to the VK_IMAGE_LAYOUT_GENERAL layout before handing it off to the external API.

Note this does not attempt to address cross-device transitions, nor transitions to engines on the same device which are not visible within the Vulkan API. Both of these are beyond the scope of this extension.

Examples

    // TODO: Write some sample code here.

Version History

  • Revision 1, 2016-08-19 (James Jones)

    • Initial draft

VK_NV_external_memory_capabilities

Name String

VK_NV_external_memory_capabilities

Extension Type

Instance extension

Registered Extension Number

56

Revision

1

Extension and Version Dependencies
  • Requires Vulkan 1.0

Deprecation state
Contact
Last Modified Date

2016-08-19

IP Status

No known IP claims.

Interactions and External Dependencies
Contributors
  • James Jones, NVIDIA

Applications may wish to import memory from the Direct 3D API, or export memory to other Vulkan instances. This extension provides a set of capability queries that allow applications determine what types of win32 memory handles an implementation supports for a given set of use cases.

New Object Types

None.

New Enum Constants

None.

Issues

1) Why do so many external memory capabilities need to be queried on a per-memory-handle-type basis?

RESOLVED: This is because some handle types are based on OS-native objects that have far more limited capabilities than the very generic Vulkan memory objects. Not all memory handle types can name memory objects that support 3D images, for example. Some handle types cannot even support the deferred image and memory binding behavior of Vulkan and require specifying the image when allocating or importing the memory object.

2) Does the VkExternalImageFormatPropertiesNV struct need to include a list of memory type bits that support the given handle type?

RESOLVED: No. The memory types that do not support the handle types will simply be filtered out of the results returned by vkGetImageMemoryRequirements when a set of handle types was specified at image creation time.

3) Should the non-opaque handle types be moved to their own extension?

RESOLVED: Perhaps. However, defining the handle type bits does very little and does not require any platform-specific types on its own, and it is easier to maintain the bitmask values in a single extension for now. Presumably more handle types could be added by separate extensions though, and it would be midly weird to have some platform-specific ones defined in the core spec and some in extensions

VK_NV_external_memory_win32

Name String

VK_NV_external_memory_win32

Extension Type

Device extension

Registered Extension Number

58

Revision

1

Extension and Version Dependencies
Deprecation state
Contact
Last Modified Date

2016-08-19

IP Status

No known IP claims.

Contributors
  • James Jones, NVIDIA

  • Carsten Rohde, NVIDIA

Applications may wish to export memory to other Vulkan instances or other APIs, or import memory from other Vulkan instances or other APIs to enable Vulkan workloads to be split up across application module, process, or API boundaries. This extension enables win32 applications to export win32 handles from Vulkan memory objects such that the underlying resources can be referenced outside the Vulkan instance that created them, and import win32 handles created in the Direct3D API to Vulkan memory objects.

New Object Types

None.

New Enum Constants

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_IMPORT_MEMORY_WIN32_HANDLE_INFO_NV

    • VK_STRUCTURE_TYPE_EXPORT_MEMORY_WIN32_HANDLE_INFO_NV

New Enums

None.

New Functions

Issues

1) If memory objects are shared between processes and APIs, is this considered aliasing according to the rules outlined in the Memory Aliasing section?

RESOLVED: Yes, but strict exceptions to the rules are added to allow some forms of aliasing in these cases. Further, other extensions may build upon these new aliasing rules to define specific support usage within Vulkan for imported native memory objects, or memory objects from other APIs.

2) Are new image layouts or metadata required to specify image layouts and layout transitions compatible with non-Vulkan APIs, or with other instances of the same Vulkan driver?

RESOLVED: No. Separate instances of the same Vulkan driver running on the same GPU should have identical internal layout semantics, so applictions have the tools they need to ensure views of images are consistent between the two instances. Other APIs will fall into two categories: Those that are Vulkan compatible (a term to be defined by subsequent interopability extensions), or Vulkan incompatible. When sharing images with Vulkan incompatible APIs, the Vulkan image must be transitioned to the VK_IMAGE_LAYOUT_GENERAL layout before handing it off to the external API.

Note this does not attempt to address cross-device transitions, nor transitions to engines on the same device which are not visible within the Vulkan API. Both of these are beyond the scope of this extension.

3) Do applications need to call CloseHandle() on the values returned from vkGetMemoryWin32HandleNV when handleType is VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_BIT_NV?

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, while an import transfers ownership to the associated driver. Destroying the memory object will not destroy the handle or the handle’s reference to the underlying memory resource.

Examples

    //
    // Create an exportable memory object and export an external
    // handle from it.
    //

    // Pick an external format and handle type.
    static const VkFormat format = VK_FORMAT_R8G8B8A8_UNORM;
    static const VkExternalMemoryHandleTypeFlagsNV handleType =
        VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_BIT_NV;

    extern VkPhysicalDevice physicalDevice;
    extern VkDevice device;

    VkPhysicalDeviceMemoryProperties memoryProperties;
    VkExternalImageFormatPropertiesNV properties;
    VkExternalMemoryImageCreateInfoNV externalMemoryImageCreateInfo;
    VkDedicatedAllocationImageCreateInfoNV dedicatedImageCreateInfo;
    VkImageCreateInfo imageCreateInfo;
    VkImage image;
    VkMemoryRequirements imageMemoryRequirements;
    uint32_t numMemoryTypes;
    uint32_t memoryType;
    VkExportMemoryAllocateInfoNV exportMemoryAllocateInfo;
    VkDedicatedAllocationMemoryAllocateInfoNV dedicatedAllocationInfo;
    VkMemoryAllocateInfo memoryAllocateInfo;
    VkDeviceMemory memory;
    VkResult result;
    HANDLE memoryHnd;

    // Figure out how many memory types the device supports
    vkGetPhysicalDeviceMemoryProperties(physicalDevice,
                                        &memoryProperties);
    numMemoryTypes = memoryProperties.memoryTypeCount;

    // Check the external handle type capabilities for the chosen format
    // Exportable 2D image support with at least 1 mip level, 1 array
    // layer, and VK_SAMPLE_COUNT_1_BIT using optimal tiling and supporting
    // texturing and color rendering is required.
    result = vkGetPhysicalDeviceExternalImageFormatPropertiesNV(
        physicalDevice,
        format,
        VK_IMAGE_TYPE_2D,
        VK_IMAGE_TILING_OPTIMAL,
        VK_IMAGE_USAGE_SAMPLED_BIT |
        VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT,
        0,
        handleType,
        &properties);

    if ((result != VK_SUCCESS) ||
        !(properties.externalMemoryFeatures &
          VK_EXTERNAL_MEMORY_FEATURE_EXPORTABLE_BIT_NV)) {
        abort();
    }

    // Set up the external memory image creation info
    memset(&externalMemoryImageCreateInfo,
           0, sizeof(externalMemoryImageCreateInfo));
    externalMemoryImageCreateInfo.sType =
        VK_STRUCTURE_TYPE_EXTERNAL_MEMORY_IMAGE_CREATE_INFO_NV;
    externalMemoryImageCreateInfo.handleTypes = handleType;
    if (properties.externalMemoryFeatures &
        VK_EXTERNAL_MEMORY_FEATURE_DEDICATED_ONLY_BIT_NV) {
        memset(&dedicatedImageCreateInfo, 0, sizeof(dedicatedImageCreateInfo));
        dedicatedImageCreateInfo.sType =
            VK_STRUCTURE_TYPE_DEDICATED_ALLOCATION_IMAGE_CREATE_INFO_NV;
        dedicatedImageCreateInfo.dedicatedAllocation = VK_TRUE;
        externalMemoryImageCreateInfo.pNext = &dedicatedImageCreateInfo;
    }
    // Set up the  core image creation info
    memset(&imageCreateInfo, 0, sizeof(imageCreateInfo));
    imageCreateInfo.sType = VK_STRUCTURE_TYPE_IMAGE_CREATE_INFO;
    imageCreateInfo.pNext = &externalMemoryImageCreateInfo;
    imageCreateInfo.format = format;
    imageCreateInfo.extent.width = 64;
    imageCreateInfo.extent.height = 64;
    imageCreateInfo.extent.depth = 1;
    imageCreateInfo.mipLevels = 1;
    imageCreateInfo.arrayLayers = 1;
    imageCreateInfo.samples = VK_SAMPLE_COUNT_1_BIT;
    imageCreateInfo.tiling = VK_IMAGE_TILING_OPTIMAL;
    imageCreateInfo.usage = VK_IMAGE_USAGE_SAMPLED_BIT |
        VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT;
    imageCreateInfo.sharingMode = VK_SHARING_MODE_EXCLUSIVE;
    imageCreateInfo.initialLayout = VK_IMAGE_LAYOUT_UNDEFINED;

    vkCreateImage(device, &imageCreateInfo, NULL, &image);

    vkGetImageMemoryRequirements(device,
                                 image,
                                 &imageMemoryRequirements);

    // For simplicity, just pick the first compatible memory type.
    for (memoryType = 0; memoryType < numMemoryTypes; memoryType++) {
        if ((1 << memoryType) & imageMemoryRequirements.memoryTypeBits) {
            break;
        }
    }

    // At least one memory type must be supported given the prior external
    // handle capability check.
    assert(memoryType < numMemoryTypes);

    // Allocate the external memory object.
    memset(&exportMemoryAllocateInfo, 0, sizeof(exportMemoryAllocateInfo));
    exportMemoryAllocateInfo.sType =
        VK_STRUCTURE_TYPE_EXPORT_MEMORY_ALLOCATE_INFO_NV;
    exportMemoryAllocateInfo.handleTypes = handleType;
    if (properties.externalMemoryFeatures &
        VK_EXTERNAL_MEMORY_FEATURE_DEDICATED_ONLY_BIT_NV) {
        memset(&dedicatedAllocationInfo, 0, sizeof(dedicatedAllocationInfo));
        dedicatedAllocationInfo.sType =
            VK_STRUCTURE_TYPE_DEDICATED_ALLOCATION_MEMORY_ALLOCATE_INFO_NV;
        dedicatedAllocationInfo.image = image;
        exportMemoryAllocateInfo.pNext = &dedicatedAllocationInfo;
    }
    memset(&memoryAllocateInfo, 0, sizeof(memoryAllocateInfo));
    memoryAllocateInfo.sType = VK_STRUCTURE_TYPE_MEMORY_ALLOCATE_INFO;
    memoryAllocateInfo.pNext = &exportMemoryAllocateInfo;
    memoryAllocateInfo.allocationSize = imageMemoryRequirements.size;
    memoryAllocateInfo.memoryTypeIndex = memoryType;

    vkAllocateMemory(device, &memoryAllocateInfo, NULL, &memory);

    if (!(properties.externalMemoryFeatures &
          VK_EXTERNAL_MEMORY_FEATURE_DEDICATED_ONLY_BIT_NV)) {
        vkBindImageMemory(device, image, memory, 0);
    }

    // Get the external memory opaque FD handle
    vkGetMemoryWin32HandleNV(device, memory, &memoryHnd);

Version History

  • Revision 1, 2016-08-11 (James Jones)

    • Initial draft

VK_NV_glsl_shader

Name String

VK_NV_glsl_shader

Extension Type

Device extension

Registered Extension Number

13

Revision

1

Extension and Version Dependencies
  • Requires Vulkan 1.0

Deprecation state
  • Deprecated without replacement

Contact
Last Modified Date

2016-02-14

IP Status

No known IP claims.

Contributors
  • Piers Daniell, NVIDIA

This extension allows GLSL shaders written to the GL_KHR_vulkan_glsl extension specification to be used instead of SPIR-V. The implementation will automatically detect whether the shader is SPIR-V or GLSL, and compile it appropriately.

New Object Types

New Enum Constants

  • Extending VkResult:

    • VK_ERROR_INVALID_SHADER_NV

New Enums

New Structures

New Functions

Issues

Examples

Example 1

Passing in GLSL code

    char const vss[] =
        "#version 450 core\n"
        "layout(location = 0) in vec2 aVertex;\n"
        "layout(location = 1) in vec4 aColor;\n"
        "out vec4 vColor;\n"
        "void main()\n"
        "{\n"
        "    vColor = aColor;\n"
        "    gl_Position = vec4(aVertex, 0, 1);\n"
        "}\n"
    ;
    VkShaderModuleCreateInfo vertexShaderInfo = { VK_STRUCTURE_TYPE_SHADER_MODULE_CREATE_INFO };
    vertexShaderInfo.codeSize = sizeof vss;
    vertexShaderInfo.pCode = vss;
    VkShaderModule vertexShader;
    vkCreateShaderModule(device, &vertexShaderInfo, 0, &vertexShader);

Version History

  • Revision 1, 2016-02-14 (Piers Daniell)

    • Initial draft

VK_NV_win32_keyed_mutex

Name String

VK_NV_win32_keyed_mutex

Extension Type

Device extension

Registered Extension Number

59

Revision

1

Extension and Version Dependencies
Deprecation state
Contact
Last Modified Date

2016-08-19

IP Status

No known IP claims.

Contributors
  • James Jones, 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

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_WIN32_KEYED_MUTEX_ACQUIRE_RELEASE_INFO_NV

New Enums

None.

New Functions

None.

Issues

None.

Examples

    //
    // Import a memory object from Direct3D 11, and synchronize
    // access to it in Vulkan using keyed mutex objects.
    //

    extern VkPhysicalDevice physicalDevice;
    extern VkDevice device;
    extern HANDLE sharedNtHandle;

    static const VkFormat format = VK_FORMAT_R8G8B8A8_UNORM;
    static const VkExternalMemoryHandleTypeFlagsNV handleType =
        VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_IMAGE_BIT_NV;

    VkPhysicalDeviceMemoryProperties memoryProperties;
    VkExternalImageFormatPropertiesNV properties;
    VkExternalMemoryImageCreateInfoNV externalMemoryImageCreateInfo;
    VkImageCreateInfo imageCreateInfo;
    VkImage image;
    VkMemoryRequirements imageMemoryRequirements;
    uint32_t numMemoryTypes;
    uint32_t memoryType;
    VkImportMemoryWin32HandleInfoNV importMemoryInfo;
    VkMemoryAllocateInfo memoryAllocateInfo;
    VkDeviceMemory mem;
    VkResult result;

    // Figure out how many memory types the device supports
    vkGetPhysicalDeviceMemoryProperties(physicalDevice,
                                        &memoryProperties);
    numMemoryTypes = memoryProperties.memoryTypeCount;

    // Check the external handle type capabilities for the chosen format
    // Importable 2D image support with at least 1 mip level, 1 array
    // layer, and VK_SAMPLE_COUNT_1_BIT using optimal tiling and supporting
    // texturing and color rendering is required.
    result = vkGetPhysicalDeviceExternalImageFormatPropertiesNV(
        physicalDevice,
        format,
        VK_IMAGE_TYPE_2D,
        VK_IMAGE_TILING_OPTIMAL,
        VK_IMAGE_USAGE_SAMPLED_BIT |
        VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT,
        0,
        handleType,
        &properties);

    if ((result != VK_SUCCESS) ||
        !(properties.externalMemoryFeatures &
          VK_EXTERNAL_MEMORY_FEATURE_IMPORTABLE_BIT_NV)) {
        abort();
    }

    // Set up the external memory image creation info
    memset(&externalMemoryImageCreateInfo,
           0, sizeof(externalMemoryImageCreateInfo));
    externalMemoryImageCreateInfo.sType =
        VK_STRUCTURE_TYPE_EXTERNAL_MEMORY_IMAGE_CREATE_INFO_NV;
    externalMemoryImageCreateInfo.handleTypes = handleType;
    // Set up the  core image creation info
    memset(&imageCreateInfo, 0, sizeof(imageCreateInfo));
    imageCreateInfo.sType = VK_STRUCTURE_TYPE_IMAGE_CREATE_INFO;
    imageCreateInfo.pNext = &externalMemoryImageCreateInfo;
    imageCreateInfo.format = format;
    imageCreateInfo.extent.width = 64;
    imageCreateInfo.extent.height = 64;
    imageCreateInfo.extent.depth = 1;
    imageCreateInfo.mipLevels = 1;
    imageCreateInfo.arrayLayers = 1;
    imageCreateInfo.samples = VK_SAMPLE_COUNT_1_BIT;
    imageCreateInfo.tiling = VK_IMAGE_TILING_OPTIMAL;
    imageCreateInfo.usage = VK_IMAGE_USAGE_SAMPLED_BIT |
        VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT;
    imageCreateInfo.sharingMode = VK_SHARING_MODE_EXCLUSIVE;
    imageCreateInfo.initialLayout = VK_IMAGE_LAYOUT_UNDEFINED;

    vkCreateImage(device, &imageCreateInfo, NULL, &image);
    vkGetImageMemoryRequirements(device,
                                 image,
                                 &imageMemoryRequirements);

    // For simplicity, just pick the first compatible memory type.
    for (memoryType = 0; memoryType < numMemoryTypes; memoryType++) {
        if ((1 << memoryType) & imageMemoryRequirements.memoryTypeBits) {
            break;
        }
    }

    // At least one memory type must be supported given the prior external
    // handle capability check.
    assert(memoryType < numMemoryTypes);

    // Allocate the external memory object.
    memset(&exportMemoryAllocateInfo, 0, sizeof(exportMemoryAllocateInfo));
    exportMemoryAllocateInfo.sType =
        VK_STRUCTURE_TYPE_EXPORT_MEMORY_ALLOCATE_INFO_NV;
    importMemoryInfo.handleTypes = handleType;
    importMemoryInfo.handle = sharedNtHandle;

    memset(&memoryAllocateInfo, 0, sizeof(memoryAllocateInfo));
    memoryAllocateInfo.sType = VK_STRUCTURE_TYPE_MEMORY_ALLOCATE_INFO;
    memoryAllocateInfo.pNext = &exportMemoryAllocateInfo;
    memoryAllocateInfo.allocationSize = imageMemoryRequirements.size;
    memoryAllocateInfo.memoryTypeIndex = memoryType;

    vkAllocateMemory(device, &memoryAllocateInfo, NULL, &mem);

    vkBindImageMemory(device, image, mem, 0);

    ...

    const uint64_t acquireKey = 1;
    const uint32_t timeout = INFINITE;
    const uint64_t releaseKey = 2;

    VkWin32KeyedMutexAcquireReleaseInfoNV keyedMutex =
        { VK_STRUCTURE_TYPE_WIN32_KEYED_MUTEX_ACQUIRE_RELEASE_INFO_NV };
    keyedMutex.acquireCount = 1;
    keyedMutex.pAcquireSyncs = &mem;
    keyedMutex.pAcquireKeys = &acquireKey;
    keyedMutex.pAcquireTimeoutMilliseconds = &timeout;
    keyedMutex.releaseCount = 1;
    keyedMutex.pReleaseSyncs = &mem;
    keyedMutex.pReleaseKeys = &releaseKey;

    VkSubmitInfo submit_info = { VK_STRUCTURE_TYPE_SUBMIT_INFO, &keyedMutex };
    submit_info.commandBufferCount = 1;
    submit_info.pCommandBuffers = &cmd_buf;
    vkQueueSubmit(queue, 1, &submit_info, VK_NULL_HANDLE);

Version History

  • Revision 2, 2016-08-11 (James Jones)

    • Updated sample code based on the NV external memory extensions.

    • Renamed from NVX to NV extension.

    • Added Overview and Description sections.

    • Updated sample code to use the NV external memory extensions.

  • Revision 1, 2016-06-14 (Carsten Rohde)

    • Initial draft.