Loading... please wait.

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_16bit_storage

Name String

VK_KHR_16bit_storage

Extension Type

Device extension

Registered Extension Number

84

Revision

1

Extension and Version Dependencies
Deprecation state
  • Promoted to Vulkan 1.1

Contact

Other Extension Metadata

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

Description

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.

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.

New Enum Constants

  • VK_KHR_16BIT_STORAGE_EXTENSION_NAME

  • VK_KHR_16BIT_STORAGE_SPEC_VERSION

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_16BIT_STORAGE_FEATURES_KHR

Version History

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

    • Initial draft

VK_KHR_8bit_storage

Name String

VK_KHR_8bit_storage

Extension Type

Device extension

Registered Extension Number

178

Revision

1

Extension and Version Dependencies
Deprecation state
  • Promoted to Vulkan 1.2

Contact

Other Extension Metadata

Last Modified Date

2018-02-05

Interactions and External Dependencies
  • Promoted to Vulkan 1.2 Core

IP Status

No known IP claims.

Interactions and External Dependencies
Contributors
  • Alexander Galazin, Arm

Description

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.

Promotion to Vulkan 1.2

Functionality in this extension is included in core Vulkan 1.2, with the KHR suffix omitted. However, if Vulkan 1.2 is supported and this extension is not, the StorageBuffer8BitAccess capability is optional. The original type, enum and command names are still available as aliases of the core functionality.

New Enum Constants

  • VK_KHR_8BIT_STORAGE_EXTENSION_NAME

  • VK_KHR_8BIT_STORAGE_SPEC_VERSION

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_8BIT_STORAGE_FEATURES_KHR

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

Other Extension Metadata

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

Description

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

  • ANativeWindow

New Enum Constants

  • VK_KHR_ANDROID_SURFACE_EXTENSION_NAME

  • VK_KHR_ANDROID_SURFACE_SPEC_VERSION

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_ANDROID_SURFACE_CREATE_INFO_KHR

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_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
  • Promoted to Vulkan 1.1

Contact

Other Extension Metadata

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

Description

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.

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.

New Enum Constants

  • VK_KHR_BIND_MEMORY_2_EXTENSION_NAME

  • VK_KHR_BIND_MEMORY_2_SPEC_VERSION

  • Extending VkImageCreateFlagBits:

    • VK_IMAGE_CREATE_ALIAS_BIT_KHR

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_BIND_BUFFER_MEMORY_INFO_KHR

    • VK_STRUCTURE_TYPE_BIND_IMAGE_MEMORY_INFO_KHR

Version History

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

    • Pulled bind memory functions into their own extension

VK_KHR_buffer_device_address

Name String

VK_KHR_buffer_device_address

Extension Type

Device extension

Registered Extension Number

258

Revision

1

Extension and Version Dependencies
Deprecation state
  • Promoted to Vulkan 1.2

Contact

Other Extension Metadata

Last Modified Date

2019-06-24

IP Status

No known IP claims.

Interactions and External Dependencies
  • Promoted to Vulkan 1.2 Core

Contributors
  • Jeff Bolz, NVIDIA

  • Neil Henning, AMD

  • Tobias Hector, AMD

  • Jason Ekstrand, Intel

  • Baldur Karlsson, Valve

  • Jan-Harald Fredriksen, Arm

Description

This extension allows the application to query a 64-bit buffer device address value for a buffer, which can be used to access the buffer memory via the PhysicalStorageBuffer storage class in the GL_EXT_buffer_reference GLSL extension and SPV_KHR_physical_storage_buffer SPIR-V extension.

This extension also allows opaque addresses for buffers and memory objects to be queried and later supplied by a trace capture and replay tool, so that addresses used at replay time match the addresses used when the trace was captured. To enable tools to insert these queries, new memory allocation flags must be specified for memory objects that will be bound to buffers accessed via the PhysicalStorageBuffer storage class.

Promotion to Vulkan 1.2

All functionality in this extension is included in core Vulkan 1.2, with the KHR suffix omitted. However, if Vulkan 1.2 is supported and this extension is not, the bufferDeviceAddress capability is optional. The original type, enum and command names are still available as aliases of the core functionality.

New Enum Constants

  • VK_KHR_BUFFER_DEVICE_ADDRESS_EXTENSION_NAME

  • VK_KHR_BUFFER_DEVICE_ADDRESS_SPEC_VERSION

  • Extending VkBufferCreateFlagBits:

    • VK_BUFFER_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT_KHR

  • Extending VkBufferUsageFlagBits:

    • VK_BUFFER_USAGE_SHADER_DEVICE_ADDRESS_BIT_KHR

  • Extending VkMemoryAllocateFlagBits:

    • VK_MEMORY_ALLOCATE_DEVICE_ADDRESS_BIT_KHR

    • VK_MEMORY_ALLOCATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT_KHR

  • Extending VkResult:

    • VK_ERROR_INVALID_OPAQUE_CAPTURE_ADDRESS_KHR

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_BUFFER_DEVICE_ADDRESS_INFO_KHR

    • VK_STRUCTURE_TYPE_BUFFER_OPAQUE_CAPTURE_ADDRESS_CREATE_INFO_KHR

    • VK_STRUCTURE_TYPE_DEVICE_MEMORY_OPAQUE_CAPTURE_ADDRESS_INFO_KHR

    • VK_STRUCTURE_TYPE_MEMORY_OPAQUE_CAPTURE_ADDRESS_ALLOCATE_INFO_KHR

    • VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_BUFFER_DEVICE_ADDRESS_FEATURES_KHR

New SPIR-V Capabilities

Version History

  • Revision 1, 2019-06-24 (Jan-Harald Fredriksen)

    • Internal revisions based on VK_EXT_buffer_device_address

VK_KHR_create_renderpass2

Name String

VK_KHR_create_renderpass2

Extension Type

Device extension

Registered Extension Number

110

Revision

1

Extension and Version Dependencies
Deprecation state
  • Promoted to Vulkan 1.2

Contact

Other Extension Metadata

Last Modified Date

2018-02-07

Interactions and External Dependencies
  • Promoted to Vulkan 1.2 Core

Contributors
  • Tobias Hector

  • Jeff Bolz

Description

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.

Promotion to Vulkan 1.2

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

New Enum Constants

  • VK_KHR_CREATE_RENDERPASS_2_EXTENSION_NAME

  • VK_KHR_CREATE_RENDERPASS_2_SPEC_VERSION

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_ATTACHMENT_DESCRIPTION_2_KHR

    • VK_STRUCTURE_TYPE_ATTACHMENT_REFERENCE_2_KHR

    • VK_STRUCTURE_TYPE_RENDER_PASS_CREATE_INFO_2_KHR

    • VK_STRUCTURE_TYPE_SUBPASS_BEGIN_INFO_KHR

    • VK_STRUCTURE_TYPE_SUBPASS_DEPENDENCY_2_KHR

    • VK_STRUCTURE_TYPE_SUBPASS_DESCRIPTION_2_KHR

    • VK_STRUCTURE_TYPE_SUBPASS_END_INFO_KHR

Version History

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

    • Internal revisions

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
  • Promoted to Vulkan 1.1

Contact

Other Extension Metadata

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

Description

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 a VkMemoryDedicatedRequirementsKHR structure to the pNext chain of the VkMemoryRequirements2 structure passed as the pMemoryRequirements parameter of 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.

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.

New Enum Constants

  • VK_KHR_DEDICATED_ALLOCATION_EXTENSION_NAME

  • VK_KHR_DEDICATED_ALLOCATION_SPEC_VERSION

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_MEMORY_DEDICATED_ALLOCATE_INFO_KHR

    • VK_STRUCTURE_TYPE_MEMORY_DEDICATED_REQUIREMENTS_KHR

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_depth_stencil_resolve

Name String

VK_KHR_depth_stencil_resolve

Extension Type

Device extension

Registered Extension Number

200

Revision

1

Extension and Version Dependencies
Deprecation state
  • Promoted to Vulkan 1.2

Contact

Other Extension Metadata

Last Modified Date

2018-04-09

Interactions and External Dependencies
  • Promoted to Vulkan 1.2 Core

Contributors
  • Jan-Harald Fredriksen, Arm

  • Andrew Garrard, Samsung Electronics

  • Soowan Park, Samsung Electronics

  • Jeff Bolz, NVIDIA

  • Daniel Rakos, AMD

Description

This extension adds support for automatically resolving multisampled depth/stencil attachments in a subpass in a similar manner as for color attachments.

Promotion to Vulkan 1.2

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

New Bitmasks

New Enum Constants

  • VK_KHR_DEPTH_STENCIL_RESOLVE_EXTENSION_NAME

  • VK_KHR_DEPTH_STENCIL_RESOLVE_SPEC_VERSION

  • Extending VkResolveModeFlagBits:

    • VK_RESOLVE_MODE_AVERAGE_BIT_KHR

    • VK_RESOLVE_MODE_MAX_BIT_KHR

    • VK_RESOLVE_MODE_MIN_BIT_KHR

    • VK_RESOLVE_MODE_NONE_KHR

    • VK_RESOLVE_MODE_SAMPLE_ZERO_BIT_KHR

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DEPTH_STENCIL_RESOLVE_PROPERTIES_KHR

    • VK_STRUCTURE_TYPE_SUBPASS_DESCRIPTION_DEPTH_STENCIL_RESOLVE_KHR

Version History

  • Revision 1, 2018-04-09 (Jan-Harald Fredriksen)

    • Initial revision

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
  • Promoted to Vulkan 1.1

Contact

Other Extension Metadata

Last Modified Date

2017-09-05

IP Status

No known IP claims.

Interactions and External Dependencies
Contributors
  • Jeff Bolz, NVIDIA

  • Michael Worcester, Imagination Technologies

Description

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 is required to rebuild descriptor sets for each frame. For those cases it is 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 describing the new descriptors.

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.

New Enum Constants

  • VK_KHR_DESCRIPTOR_UPDATE_TEMPLATE_EXTENSION_NAME

  • VK_KHR_DESCRIPTOR_UPDATE_TEMPLATE_SPEC_VERSION

  • Extending VkDescriptorUpdateTemplateType:

    • VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_DESCRIPTOR_SET_KHR

  • Extending VkObjectType:

    • VK_OBJECT_TYPE_DESCRIPTOR_UPDATE_TEMPLATE_KHR

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_DESCRIPTOR_UPDATE_TEMPLATE_CREATE_INFO_KHR

If VK_EXT_debug_report is supported:

If VK_KHR_push_descriptor is supported:

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

4

Extension and Version Dependencies
Deprecation state
  • Promoted to Vulkan 1.1

Contact

Other Extension Metadata

Last Modified Date

2017-10-10

IP Status

No known IP claims.

Interactions and External Dependencies
  • Promoted to Vulkan 1.1 Core

Contributors
  • Jeff Bolz, NVIDIA

  • Tobias Hector, Imagination Technologies

Description

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.

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.

New Enum Constants

  • VK_KHR_DEVICE_GROUP_EXTENSION_NAME

  • VK_KHR_DEVICE_GROUP_SPEC_VERSION

  • Extending VkDependencyFlagBits:

    • VK_DEPENDENCY_DEVICE_GROUP_BIT_KHR

  • Extending VkMemoryAllocateFlagBits:

    • VK_MEMORY_ALLOCATE_DEVICE_MASK_BIT_KHR

  • Extending VkPeerMemoryFeatureFlagBits:

    • VK_PEER_MEMORY_FEATURE_COPY_DST_BIT_KHR

    • VK_PEER_MEMORY_FEATURE_COPY_SRC_BIT_KHR

    • VK_PEER_MEMORY_FEATURE_GENERIC_DST_BIT_KHR

    • VK_PEER_MEMORY_FEATURE_GENERIC_SRC_BIT_KHR

  • Extending VkPipelineCreateFlagBits:

    • VK_PIPELINE_CREATE_DISPATCH_BASE_KHR

    • VK_PIPELINE_CREATE_VIEW_INDEX_FROM_DEVICE_INDEX_BIT_KHR

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_DEVICE_GROUP_BIND_SPARSE_INFO_KHR

    • VK_STRUCTURE_TYPE_DEVICE_GROUP_COMMAND_BUFFER_BEGIN_INFO_KHR

    • VK_STRUCTURE_TYPE_DEVICE_GROUP_RENDER_PASS_BEGIN_INFO_KHR

    • VK_STRUCTURE_TYPE_DEVICE_GROUP_SUBMIT_INFO_KHR

    • VK_STRUCTURE_TYPE_MEMORY_ALLOCATE_FLAGS_INFO_KHR

If VK_KHR_bind_memory2 is supported:

  • Extending VkImageCreateFlagBits:

    • VK_IMAGE_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT_KHR

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_BIND_BUFFER_MEMORY_DEVICE_GROUP_INFO_KHR

    • VK_STRUCTURE_TYPE_BIND_IMAGE_MEMORY_DEVICE_GROUP_INFO_KHR

If VK_KHR_surface is supported:

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_DEVICE_GROUP_PRESENT_CAPABILITIES_KHR

If VK_KHR_swapchain is supported:

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_ACQUIRE_NEXT_IMAGE_INFO_KHR

    • VK_STRUCTURE_TYPE_BIND_IMAGE_MEMORY_SWAPCHAIN_INFO_KHR

    • VK_STRUCTURE_TYPE_DEVICE_GROUP_PRESENT_INFO_KHR

    • VK_STRUCTURE_TYPE_DEVICE_GROUP_SWAPCHAIN_CREATE_INFO_KHR

    • VK_STRUCTURE_TYPE_IMAGE_SWAPCHAIN_CREATE_INFO_KHR

  • Extending VkSwapchainCreateFlagBitsKHR:

    • VK_SWAPCHAIN_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT_KHR

New Built-in Variables

New SPIR-V Capabilities

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
  • Promoted to Vulkan 1.1

Contact

Other Extension Metadata

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

Description

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.

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.

New Enum Constants

  • VK_KHR_DEVICE_GROUP_CREATION_EXTENSION_NAME

  • VK_KHR_DEVICE_GROUP_CREATION_SPEC_VERSION

  • VK_MAX_DEVICE_GROUP_SIZE_KHR

  • Extending VkMemoryHeapFlagBits:

    • VK_MEMORY_HEAP_MULTI_INSTANCE_BIT_KHR

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_DEVICE_GROUP_DEVICE_CREATE_INFO_KHR

    • VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_GROUP_PROPERTIES_KHR

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_display

Name String

VK_KHR_display

Extension Type

Instance extension

Registered Extension Number

3

Revision

23

Extension and Version Dependencies
Contact

Other Extension Metadata

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

Description

This extension provides the API to enumerate displays and available modes on a given device.

New Object Types

New Enum Constants

  • VK_KHR_DISPLAY_EXTENSION_NAME

  • VK_KHR_DISPLAY_SPEC_VERSION

  • Extending VkObjectType:

    • VK_OBJECT_TYPE_DISPLAY_KHR

    • VK_OBJECT_TYPE_DISPLAY_MODE_KHR

  • 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

10

Extension and Version Dependencies
Contact

Other Extension Metadata

Last Modified Date

2017-03-13

IP Status

No known IP claims.

Contributors
  • James Jones, NVIDIA

  • Jeff Vigil, Qualcomm

  • Jesse Hall, Google

Description

This extension provides an API to create a swapchain directly on a device’s display without any underlying window system.

New Structures

New Enum Constants

  • VK_KHR_DISPLAY_SWAPCHAIN_EXTENSION_NAME

  • VK_KHR_DISPLAY_SWAPCHAIN_SPEC_VERSION

  • Extending VkResult:

    • VK_ERROR_INCOMPATIBLE_DISPLAY_KHR

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_DISPLAY_PRESENT_INFO_KHR

Issues

1) Should swapchains sharing images each hold a reference to the images, or should it be up to the application to destroy the swapchains and images in an order that avoids the need for reference counting?

RESOLVED: Take a reference. The lifetime of presentable images is already complex enough.

2) Should the srcRect and dstRect parameters be specified as part of the present command, or at swapchain creation time?

RESOLVED: As part of the presentation command. This allows moving and scaling the image on the screen without the need to respecify the mode or create a new swapchain and presentable images.

3) Should srcRect and dstRect be specified as rects, or separate offset/extent values?

RESOLVED: As rects. Specifying them separately might make it easier for hardware to expose support for one but not the other, but in such cases applications must just take care to obey the reported capabilities and not use non-zero offsets or extents that require scaling, as appropriate.

4) How can applications create multiple swapchains that use the same images?

RESOLVED: By calling vkCreateSharedSwapchainsKHR.

An earlier resolution used vkCreateSwapchainKHR, chaining multiple VkSwapchainCreateInfoKHR structures through pNext. In order to allow each swapchain to also allow other extension structs, a level of indirection was used: VkSwapchainCreateInfoKHR::pNext pointed to a different structure, which had both sType and pNext members for additional extensions, and also had a pointer to the next VkSwapchainCreateInfoKHR structure. The number of swapchains to be created could only be found by walking this linked list of alternating structures, and the pSwapchains out parameter was reinterpreted to be an array of VkSwapchainKHR handles.

Another option considered was a method to specify a “shared” swapchain when creating a new swapchain, such that groups of swapchains using the same images could be built up one at a time. This was deemed unusable because drivers need to know all of the displays an image will be used on when determining which internal formats and layouts to use for that image.

Examples

Note

The example code for the 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

Deprecation state
  • Promoted to Vulkan 1.2

Contact

Other Extension Metadata

Last Modified Date

2017-08-25

Interactions and External Dependencies
  • Promoted to Vulkan 1.2 Core

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

Description

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.

Promotion to Vulkan 1.2

All functionality in this extension is included in core Vulkan 1.2, with the KHR suffix omitted. However, if Vulkan 1.2 is supported and this extension is not, the entry points vkCmdDrawIndirectCount and vkCmdDrawIndexedIndirectCount are optional. The original type, enum and command names are still available as aliases of the core functionality.

New Enum Constants

  • VK_KHR_DRAW_INDIRECT_COUNT_EXTENSION_NAME

  • VK_KHR_DRAW_INDIRECT_COUNT_SPEC_VERSION

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
Deprecation state
  • Promoted to Vulkan 1.2

Contact

Other Extension Metadata

Last Modified Date

2018-04-11

Interactions and External Dependencies
  • Promoted to Vulkan 1.2 Core

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

Description

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.

Promotion to Vulkan 1.2

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

New Enums

New Enum Constants

  • VK_KHR_DRIVER_PROPERTIES_EXTENSION_NAME

  • VK_KHR_DRIVER_PROPERTIES_SPEC_VERSION

  • VK_MAX_DRIVER_INFO_SIZE_KHR

  • VK_MAX_DRIVER_NAME_SIZE_KHR

  • Extending VkDriverId:

    • VK_DRIVER_ID_AMD_OPEN_SOURCE_KHR

    • VK_DRIVER_ID_AMD_PROPRIETARY_KHR

    • VK_DRIVER_ID_ARM_PROPRIETARY_KHR

    • VK_DRIVER_ID_BROADCOM_PROPRIETARY_KHR

    • VK_DRIVER_ID_GGP_PROPRIETARY_KHR

    • VK_DRIVER_ID_GOOGLE_SWIFTSHADER_KHR

    • VK_DRIVER_ID_IMAGINATION_PROPRIETARY_KHR

    • VK_DRIVER_ID_INTEL_OPEN_SOURCE_MESA_KHR

    • VK_DRIVER_ID_INTEL_PROPRIETARY_WINDOWS_KHR

    • VK_DRIVER_ID_MESA_RADV_KHR

    • VK_DRIVER_ID_NVIDIA_PROPRIETARY_KHR

    • VK_DRIVER_ID_QUALCOMM_PROPRIETARY_KHR

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DRIVER_PROPERTIES_KHR

Version History

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

    • 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
  • Promoted to Vulkan 1.1

Contact

Other Extension Metadata

Last Modified Date

2017-05-08

IP Status

No known IP claims.

Interactions and External Dependencies
  • Promoted to Vulkan 1.1 Core

Contributors

Description

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.

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.

New Structures

New Bitmasks

New Enum Constants

  • VK_KHR_EXTERNAL_FENCE_EXTENSION_NAME

  • VK_KHR_EXTERNAL_FENCE_SPEC_VERSION

  • Extending VkFenceImportFlagBits:

    • VK_FENCE_IMPORT_TEMPORARY_BIT_KHR

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_EXPORT_FENCE_CREATE_INFO_KHR

Issues

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

Version History

  • Revision 1, 2017-05-08 (Jesse Hall)

    • Initial revision

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
  • Promoted to Vulkan 1.1

Contact

Other Extension Metadata

Last Modified Date

2017-05-08

IP Status

No known IP claims.

Interactions and External Dependencies
  • Promoted to Vulkan 1.1 Core

Contributors

Description

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.

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.

New Enum Constants

  • VK_KHR_EXTERNAL_FENCE_CAPABILITIES_EXTENSION_NAME

  • VK_KHR_EXTERNAL_FENCE_CAPABILITIES_SPEC_VERSION

  • VK_LUID_SIZE_KHR

  • Extending VkExternalFenceFeatureFlagBits:

    • VK_EXTERNAL_FENCE_FEATURE_EXPORTABLE_BIT_KHR

    • VK_EXTERNAL_FENCE_FEATURE_IMPORTABLE_BIT_KHR

  • Extending VkExternalFenceHandleTypeFlagBits:

    • VK_EXTERNAL_FENCE_HANDLE_TYPE_OPAQUE_FD_BIT_KHR

    • VK_EXTERNAL_FENCE_HANDLE_TYPE_OPAQUE_WIN32_BIT_KHR

    • VK_EXTERNAL_FENCE_HANDLE_TYPE_OPAQUE_WIN32_KMT_BIT_KHR

    • VK_EXTERNAL_FENCE_HANDLE_TYPE_SYNC_FD_BIT_KHR

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_EXTERNAL_FENCE_PROPERTIES_KHR

    • VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_EXTERNAL_FENCE_INFO_KHR

    • VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_ID_PROPERTIES_KHR

Version History

  • Revision 1, 2017-05-08 (Jesse Hall)

    • Initial version

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

Other Extension Metadata

Last Modified Date

2017-05-08

IP Status

No known IP claims.

Contributors

Description

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

  • VK_KHR_EXTERNAL_FENCE_FD_EXTENSION_NAME

  • VK_KHR_EXTERNAL_FENCE_FD_SPEC_VERSION

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_FENCE_GET_FD_INFO_KHR

    • VK_STRUCTURE_TYPE_IMPORT_FENCE_FD_INFO_KHR

Issues

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

Version History

  • Revision 1, 2017-05-08 (Jesse Hall)

    • Initial revision

VK_KHR_external_fence_win32

Name String

VK_KHR_external_fence_win32

Extension Type

Device extension

Registered Extension Number

115

Revision

1

Extension and Version Dependencies
Contact

Other Extension Metadata

Last Modified Date

2017-05-08

IP Status

No known IP claims.

Contributors

Description

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

  • VK_KHR_EXTERNAL_FENCE_WIN32_EXTENSION_NAME

  • VK_KHR_EXTERNAL_FENCE_WIN32_SPEC_VERSION

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_EXPORT_FENCE_WIN32_HANDLE_INFO_KHR

    • VK_STRUCTURE_TYPE_FENCE_GET_WIN32_HANDLE_INFO_KHR

    • VK_STRUCTURE_TYPE_IMPORT_FENCE_WIN32_HANDLE_INFO_KHR

Issues

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

1) Should D3D12 fence handle types be supported, like they are for semaphores?

RESOLVED: No. Doing so would require extending the fence signal and wait operations to provide values to signal / wait for, like VkD3D12FenceSubmitInfoKHR does. A D3D12 fence can be signaled by importing it into a VkSemaphore instead of a VkFence, and applications can check status or wait on the D3D12 fence using non-Vulkan APIs. The convenience of being able to do these operations on VkFence objects doesn’t justify the extra API complexity.

Version History

  • Revision 1, 2017-05-08 (Jesse Hall)

    • Initial revision

VK_KHR_external_memory

Name String

VK_KHR_external_memory

Extension Type

Device extension

Registered Extension Number

73

Revision

1

Extension and Version Dependencies
Deprecation state
  • Promoted to Vulkan 1.1

Contact

Other Extension Metadata

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

Description

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.

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.

New Enum Constants

  • VK_KHR_EXTERNAL_MEMORY_EXTENSION_NAME

  • VK_KHR_EXTERNAL_MEMORY_SPEC_VERSION

  • VK_QUEUE_FAMILY_EXTERNAL_KHR

  • Extending VkResult:

    • VK_ERROR_INVALID_EXTERNAL_HANDLE_KHR

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_EXPORT_MEMORY_ALLOCATE_INFO_KHR

    • VK_STRUCTURE_TYPE_EXTERNAL_MEMORY_BUFFER_CREATE_INFO_KHR

    • VK_STRUCTURE_TYPE_EXTERNAL_MEMORY_IMAGE_CREATE_INFO_KHR

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 between external and 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.

Version History

  • Revision 1, 2016-10-20 (James Jones)

    • Initial version

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
  • Promoted to Vulkan 1.1

Contact

Other Extension Metadata

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

Description

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.

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.

New Enum Constants

  • VK_KHR_EXTERNAL_MEMORY_CAPABILITIES_EXTENSION_NAME

  • VK_KHR_EXTERNAL_MEMORY_CAPABILITIES_SPEC_VERSION

  • VK_LUID_SIZE_KHR

  • Extending VkExternalMemoryFeatureFlagBits:

    • VK_EXTERNAL_MEMORY_FEATURE_DEDICATED_ONLY_BIT_KHR

    • VK_EXTERNAL_MEMORY_FEATURE_EXPORTABLE_BIT_KHR

    • VK_EXTERNAL_MEMORY_FEATURE_IMPORTABLE_BIT_KHR

  • Extending VkExternalMemoryHandleTypeFlagBits:

    • VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_BIT_KHR

    • VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_KMT_BIT_KHR

    • VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_HEAP_BIT_KHR

    • VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_RESOURCE_BIT_KHR

    • VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_FD_BIT_KHR

    • VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_BIT_KHR

    • VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_KMT_BIT_KHR

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_EXTERNAL_BUFFER_PROPERTIES_KHR

    • VK_STRUCTURE_TYPE_EXTERNAL_IMAGE_FORMAT_PROPERTIES_KHR

    • VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_EXTERNAL_BUFFER_INFO_KHR

    • VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_EXTERNAL_IMAGE_FORMAT_INFO_KHR

    • VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_ID_PROPERTIES_KHR

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.

Version History

  • Revision 1, 2016-10-17 (James Jones)

    • Initial version

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

Other Extension Metadata

Last Modified Date

2016-10-21

IP Status

No known IP claims.

Contributors
  • James Jones, NVIDIA

  • Jeff Juliano, NVIDIA

Description

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

  • VK_KHR_EXTERNAL_MEMORY_FD_EXTENSION_NAME

  • VK_KHR_EXTERNAL_MEMORY_FD_SPEC_VERSION

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_IMPORT_MEMORY_FD_INFO_KHR

    • VK_STRUCTURE_TYPE_MEMORY_FD_PROPERTIES_KHR

    • VK_STRUCTURE_TYPE_MEMORY_GET_FD_INFO_KHR

Issues

1) Does the application need to close the file descriptor returned by vkGetMemoryFdKHR?

RESOLVED: Yes, unless it is passed back in to a driver instance to import the memory. A successful get call transfers ownership of the file descriptor to the application, and a successful import transfers it back to the driver. Destroying the original memory object will not close the file descriptor or remove its reference to the underlying memory resource associated with it.

2) Do drivers ever need to expose multiple file descriptors per memory object?

RESOLVED: No. This would indicate there are actually multiple memory objects, rather than a single memory object.

3) How should the valid size and memory type for POSIX file descriptor memory handles created outside of Vulkan be specified?

RESOLVED: The valid memory types are queried directly from the external handle. The size will be specified by future extensions that introduce such external memory handle types.

Version History

  • Revision 1, 2016-10-21 (James Jones)

    • Initial revision

VK_KHR_external_memory_win32

Name String

VK_KHR_external_memory_win32

Extension Type

Device extension

Registered Extension Number

74

Revision

1

Extension and Version Dependencies
Contact

Other Extension Metadata

Last Modified Date

2016-10-21

IP Status

No known IP claims.

Contributors
  • James Jones, NVIDIA

  • Jeff Juliano, NVIDIA

  • Carsten Rohde, NVIDIA

Description

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

  • VK_KHR_EXTERNAL_MEMORY_WIN32_EXTENSION_NAME

  • VK_KHR_EXTERNAL_MEMORY_WIN32_SPEC_VERSION

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_EXPORT_MEMORY_WIN32_HANDLE_INFO_KHR

    • VK_STRUCTURE_TYPE_IMPORT_MEMORY_WIN32_HANDLE_INFO_KHR

    • VK_STRUCTURE_TYPE_MEMORY_GET_WIN32_HANDLE_INFO_KHR

    • VK_STRUCTURE_TYPE_MEMORY_WIN32_HANDLE_PROPERTIES_KHR

Issues

1) Do applications need to call CloseHandle() on the values returned from vkGetMemoryWin32HandleKHR when handleType is VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_BIT_KHR?

RESOLVED: Yes, unless it is passed back in to another driver instance to import the object. A successful get call transfers ownership of the handle to the application. Destroying the memory object will not destroy the handle or the handle’s reference to the underlying memory resource.

2) Should the language regarding KMT/Windows 7 handles be moved to a separate extension so that it can be deprecated over time?

RESOLVED: No. Support for them can be deprecated by drivers if they choose, by no longer returning them in the supported handle types of the instance level queries.

3) How should the valid size and memory type for windows memory handles created outside of Vulkan be specified?

RESOLVED: The valid memory types are queried directly from the external handle. The size is determined by the associated image or buffer memory requirements for external handle types that require dedicated allocations, and by the size specified when creating the object from which the handle was exported for other external handle types.

Version History

  • Revision 1, 2016-10-21 (James Jones)

    • Initial revision

VK_KHR_external_semaphore

Name String

VK_KHR_external_semaphore

Extension Type

Device extension

Registered Extension Number

78

Revision

1

Extension and Version Dependencies
Deprecation state
  • Promoted to Vulkan 1.1

Contact

Other Extension Metadata

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

Description

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.

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.

New Enum Constants

  • VK_KHR_EXTERNAL_SEMAPHORE_EXTENSION_NAME

  • VK_KHR_EXTERNAL_SEMAPHORE_SPEC_VERSION

  • Extending VkSemaphoreImportFlagBits:

    • VK_SEMAPHORE_IMPORT_TEMPORARY_BIT_KHR

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_EXPORT_SEMAPHORE_CREATE_INFO_KHR

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.

Version History

  • Revision 1, 2016-10-21 (James Jones)

    • Initial revision

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
  • Promoted to Vulkan 1.1

Contact

Other Extension Metadata

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

Description

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.

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.

New Enum Constants

  • VK_KHR_EXTERNAL_SEMAPHORE_CAPABILITIES_EXTENSION_NAME

  • VK_KHR_EXTERNAL_SEMAPHORE_CAPABILITIES_SPEC_VERSION

  • VK_LUID_SIZE_KHR

  • Extending VkExternalSemaphoreFeatureFlagBits:

    • VK_EXTERNAL_SEMAPHORE_FEATURE_EXPORTABLE_BIT_KHR

    • VK_EXTERNAL_SEMAPHORE_FEATURE_IMPORTABLE_BIT_KHR

  • Extending VkExternalSemaphoreHandleTypeFlagBits:

    • VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_D3D12_FENCE_BIT_KHR

    • VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_FD_BIT_KHR

    • VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32_BIT_KHR

    • VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32_KMT_BIT_KHR

    • VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_SYNC_FD_BIT_KHR

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_EXTERNAL_SEMAPHORE_PROPERTIES_KHR

    • VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_EXTERNAL_SEMAPHORE_INFO_KHR

    • VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_ID_PROPERTIES_KHR

Version History

  • Revision 1, 2016-10-20 (James Jones)

    • Initial revision

VK_KHR_external_semaphore_fd

Name String

VK_KHR_external_semaphore_fd

Extension Type

Device extension

Registered Extension Number

80

Revision

1

Extension and Version Dependencies
Contact

Other Extension Metadata

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

Description

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

  • VK_KHR_EXTERNAL_SEMAPHORE_FD_EXTENSION_NAME

  • VK_KHR_EXTERNAL_SEMAPHORE_FD_SPEC_VERSION

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_IMPORT_SEMAPHORE_FD_INFO_KHR

    • VK_STRUCTURE_TYPE_SEMAPHORE_GET_FD_INFO_KHR

Issues

1) Does the application need to close the file descriptor returned by vkGetSemaphoreFdKHR?

RESOLVED: Yes, unless it is passed back in to a driver instance to import the semaphore. A successful get call transfers ownership of the file descriptor to the application, and a successful import transfers it back to the driver. Destroying the original semaphore object will not close the file descriptor or remove its reference to the underlying semaphore resource associated with it.

Version History

  • Revision 1, 2016-10-21 (Jesse Hall)

    • Initial revision

VK_KHR_external_semaphore_win32

Name String

VK_KHR_external_semaphore_win32

Extension Type

Device extension

Registered Extension Number

79

Revision

1

Extension and Version Dependencies
Contact

Other Extension Metadata

Last Modified Date

2016-10-21

IP Status

No known IP claims.

Contributors
  • James Jones, NVIDIA

  • Jeff Juliano, NVIDIA

  • Carsten Rohde, NVIDIA

Description

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

  • VK_KHR_EXTERNAL_SEMAPHORE_WIN32_EXTENSION_NAME

  • VK_KHR_EXTERNAL_SEMAPHORE_WIN32_SPEC_VERSION

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_D3D12_FENCE_SUBMIT_INFO_KHR

    • VK_STRUCTURE_TYPE_EXPORT_SEMAPHORE_WIN32_HANDLE_INFO_KHR

    • VK_STRUCTURE_TYPE_IMPORT_SEMAPHORE_WIN32_HANDLE_INFO_KHR

    • VK_STRUCTURE_TYPE_SEMAPHORE_GET_WIN32_HANDLE_INFO_KHR

Issues

1) Do applications need to call CloseHandle() on the values returned from vkGetSemaphoreWin32HandleKHR when handleType is VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32_BIT_KHR?

RESOLVED: Yes, unless it is passed back in to another driver instance to import the object. A successful get call transfers ownership of the handle to the application. Destroying the semaphore object will not destroy the handle or the handle’s reference to the underlying semaphore resource.

2) Should the language regarding KMT/Windows 7 handles be moved to a separate extension so that it can be deprecated over time?

RESOLVED: No. Support for them can be deprecated by drivers if they choose, by no longer returning them in the supported handle types of the instance level queries.

3) Should applications be allowed to specify additional object attributes for shared handles?

RESOLVED: Yes. Applications will be allowed to provide similar attributes to those they would to any other handle creation API.

4) How do applications communicate the desired fence values to use with D3D12_FENCE-based Vulkan semaphores?

RESOLVED: There are a couple of options. The values for the signaled and reset states could be communicated up front when creating the object and remain static for the life of the Vulkan semaphore, or they could be specified using auxiliary structures when submitting semaphore signal and wait operations, similar to what is done with the keyed mutex extensions. The latter is more flexible and consistent with the keyed mutex usage, but the former is a much simpler API.

Since Vulkan tends to favor flexibility and consistency over simplicity, a new structure specifying D3D12 fence acquire and release values is added to the vkQueueSubmit function.

Version History

  • Revision 1, 2016-10-21 (James Jones)

    • Initial revision

VK_KHR_get_display_properties2

Name String

VK_KHR_get_display_properties2

Extension Type

Instance extension

Registered Extension Number

122

Revision

1

Extension and Version Dependencies
Contact

Other Extension Metadata

Last Modified Date

2017-02-21

IP Status

No known IP claims.

Contributors
  • Ian Elliott, Google

  • James Jones, NVIDIA

Description

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

  • VK_KHR_GET_DISPLAY_PROPERTIES_2_EXTENSION_NAME

  • VK_KHR_GET_DISPLAY_PROPERTIES_2_SPEC_VERSION

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_DISPLAY_MODE_PROPERTIES_2_KHR

    • VK_STRUCTURE_TYPE_DISPLAY_PLANE_CAPABILITIES_2_KHR

    • VK_STRUCTURE_TYPE_DISPLAY_PLANE_INFO_2_KHR

    • VK_STRUCTURE_TYPE_DISPLAY_PLANE_PROPERTIES_2_KHR

    • VK_STRUCTURE_TYPE_DISPLAY_PROPERTIES_2_KHR

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_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
  • Promoted to Vulkan 1.1

Contact

Other Extension Metadata

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

Description

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 sType and pNext members. This extension wraps them in new structures with these members, 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.

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.

New Enum Constants

  • VK_KHR_GET_MEMORY_REQUIREMENTS_2_EXTENSION_NAME

  • VK_KHR_GET_MEMORY_REQUIREMENTS_2_SPEC_VERSION

  • 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

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

2

Extension and Version Dependencies
  • Requires Vulkan 1.0

Deprecation state
  • Promoted to Vulkan 1.1

Contact

Other Extension Metadata

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

Description

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.

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.

New Enum Constants

  • VK_KHR_GET_PHYSICAL_DEVICE_PROPERTIES_2_EXTENSION_NAME

  • VK_KHR_GET_PHYSICAL_DEVICE_PROPERTIES_2_SPEC_VERSION

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_FORMAT_PROPERTIES_2_KHR

    • VK_STRUCTURE_TYPE_IMAGE_FORMAT_PROPERTIES_2_KHR

    • VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FEATURES_2_KHR

    • VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGE_FORMAT_INFO_2_KHR

    • VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MEMORY_PROPERTIES_2_KHR

    • VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PROPERTIES_2_KHR

    • VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SPARSE_IMAGE_FORMAT_INFO_2_KHR

    • VK_STRUCTURE_TYPE_QUEUE_FAMILY_PROPERTIES_2_KHR

    • VK_STRUCTURE_TYPE_SPARSE_IMAGE_FORMAT_PROPERTIES_2_KHR

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

Other Extension Metadata

Last Modified Date

2017-02-27

IP Status

No known IP claims.

Contributors
  • Ian Elliott, Google

  • James Jones, NVIDIA

  • Alon Or-bach, Samsung

Description

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

  • VK_KHR_GET_SURFACE_CAPABILITIES_2_EXTENSION_NAME

  • VK_KHR_GET_SURFACE_CAPABILITIES_2_SPEC_VERSION

  • 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

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

Deprecation state
  • Promoted to Vulkan 1.2

Contact

Other Extension Metadata

Last Modified Date

2017-03-20

Interactions and External Dependencies
  • Promoted to Vulkan 1.2 Core

IP Status

No known IP claims.

Contributors
  • Jason Ekstrand, Intel

  • Jan-Harald Fredriksen, ARM

  • Jeff Bolz, NVIDIA

  • Jeff Leger, Qualcomm

  • Neil Henning, Codeplay

Description

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.

Promotion to Vulkan 1.2

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

New Enum Constants

  • VK_KHR_IMAGE_FORMAT_LIST_EXTENSION_NAME

  • VK_KHR_IMAGE_FORMAT_LIST_SPEC_VERSION

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_IMAGE_FORMAT_LIST_CREATE_INFO_KHR

Version History

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

    • Initial revision

VK_KHR_imageless_framebuffer

Name String

VK_KHR_imageless_framebuffer

Extension Type

Device extension

Registered Extension Number

109

Revision

1

Extension and Version Dependencies
Deprecation state
  • Promoted to Vulkan 1.2

Contact

Other Extension Metadata

Last Modified Date

2018-12-14

Interactions and External Dependencies
  • Promoted to Vulkan 1.2 Core

Contributors
  • Tobias Hector

  • Graham Wihlidal

Description

This extension allows framebuffers to be created without the need for creating images first, allowing more flexibility in how they are used, and avoiding the need for many of the confusing compatibility rules.

Framebuffers are now created with a small amount of additional metadata about the image views that will be used in VkFramebufferAttachmentsCreateInfoKHR, and the actual image views are provided at render pass begin time via VkRenderPassAttachmentBeginInfoKHR.

Promotion to Vulkan 1.2

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

New Enum Constants

  • VK_KHR_IMAGELESS_FRAMEBUFFER_EXTENSION_NAME

  • VK_KHR_IMAGELESS_FRAMEBUFFER_SPEC_VERSION

  • Extending VkFramebufferCreateFlagBits:

    • VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT_KHR

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_FRAMEBUFFER_ATTACHMENTS_CREATE_INFO_KHR

    • VK_STRUCTURE_TYPE_FRAMEBUFFER_ATTACHMENT_IMAGE_INFO_KHR

    • VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGELESS_FRAMEBUFFER_FEATURES_KHR

    • VK_STRUCTURE_TYPE_RENDER_PASS_ATTACHMENT_BEGIN_INFO_KHR

Version History

  • Revision 1, 2018-12-14 (Tobias Hector)

    • Internal revisions

VK_KHR_incremental_present

Name String

VK_KHR_incremental_present

Extension Type

Device extension

Registered Extension Number

85

Revision

1

Extension and Version Dependencies
Contact

Other Extension Metadata

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

Description

This device extension extends vkQueuePresentKHR, from the VK_KHR_swapchain extension, allowing an application to specify a list of rectangular, modified regions of each image to present. This should be used in situations where an application is only changing a small portion of the presentable images within a swapchain, since it enables the presentation engine to avoid wasting time presenting parts of the surface that have not changed.

This extension is leveraged from the EGL_KHR_swap_buffers_with_damage extension.

New Enum Constants

  • VK_KHR_INCREMENTAL_PRESENT_EXTENSION_NAME

  • VK_KHR_INCREMENTAL_PRESENT_SPEC_VERSION

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_PRESENT_REGIONS_KHR

Issues

1) How should we handle steroescopic-3D swapchains? We need to add a layer for each rectangle. One approach is to create another struct containing the VkRect2D plus layer, and have VkPresentRegionsKHR point to an array of that struct. Another approach is to have two parallel arrays, pRectangles and pLayers, where pRectangles[i] and pLayers[i] must be used together. Which approach should we use, and if the array of a new structure, what should that be called?

RESOLVED: Create a new structure, which is a VkRect2D plus a layer, and will be called VkRectLayerKHR.

2) Where is the origin of the VkRectLayerKHR?

RESOLVED: The upper left corner of the presentable image(s) of the swapchain, per the definition of framebuffer coordinates.

3) Does the rectangular region, VkRectLayerKHR, specify pixels of the swapchain’s image(s), or of the surface?

RESOLVED: Of the image(s). Some presentation engines may scale the pixels of a swapchain’s image(s) to the size of the surface. The size of the swapchain’s image(s) will be consistent, where the size of the surface may vary over time.

4) What if all of the rectangles for a given swapchain contain a width and/or height of zero?

RESOLVED: The application is indicating that no pixels changed since the last present. The presentation engine may use such a hint and not update any pixels for the swapchain. However, all other semantics of vkQueuePresentKHR must still be honored, including waiting for semaphores to signal.

Version History

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

    • Internal revisions

VK_KHR_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
  • Promoted to Vulkan 1.1

Contact

Other Extension Metadata

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

Description

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.

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.

New Commands

New Enum Constants

  • VK_KHR_MAINTENANCE1_EXTENSION_NAME

  • VK_KHR_MAINTENANCE1_SPEC_VERSION

  • Extending VkFormatFeatureFlagBits:

    • VK_FORMAT_FEATURE_TRANSFER_DST_BIT_KHR

    • VK_FORMAT_FEATURE_TRANSFER_SRC_BIT_KHR

  • Extending VkImageCreateFlagBits:

    • VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT_KHR

  • Extending VkResult:

    • VK_ERROR_OUT_OF_POOL_MEMORY_KHR

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
  • Promoted to Vulkan 1.1

Contact

Other Extension Metadata

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

Description

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.

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.

New Enum Constants

  • VK_KHR_MAINTENANCE2_EXTENSION_NAME

  • VK_KHR_MAINTENANCE2_SPEC_VERSION

  • Extending VkImageCreateFlagBits:

    • VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT_KHR

    • VK_IMAGE_CREATE_EXTENDED_USAGE_BIT_KHR

  • Extending VkImageLayout:

    • VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL_KHR

    • VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL_KHR

  • Extending VkPointClippingBehavior:

    • VK_POINT_CLIPPING_BEHAVIOR_ALL_CLIP_PLANES_KHR

    • VK_POINT_CLIPPING_BEHAVIOR_USER_CLIP_PLANES_ONLY_KHR

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_IMAGE_VIEW_USAGE_CREATE_INFO_KHR

    • VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_POINT_CLIPPING_PROPERTIES_KHR

    • VK_STRUCTURE_TYPE_PIPELINE_TESSELLATION_DOMAIN_ORIGIN_STATE_CREATE_INFO_KHR

    • VK_STRUCTURE_TYPE_RENDER_PASS_INPUT_ATTACHMENT_ASPECT_CREATE_INFO_KHR

  • Extending VkTessellationDomainOrigin:

    • VK_TESSELLATION_DOMAIN_ORIGIN_LOWER_LEFT_KHR

    • VK_TESSELLATION_DOMAIN_ORIGIN_UPPER_LEFT_KHR

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
  • Promoted to Vulkan 1.1

Contact

Other Extension Metadata

Last Modified Date

2017-09-05

Interactions and External Dependencies
  • Promoted to Vulkan 1.1 Core

Contributors
  • Jeff Bolz, NVIDIA

Description

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

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.

New Enum Constants

  • VK_KHR_MAINTENANCE3_EXTENSION_NAME

  • VK_KHR_MAINTENANCE3_SPEC_VERSION

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_DESCRIPTOR_SET_LAYOUT_SUPPORT_KHR

    • VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MAINTENANCE_3_PROPERTIES_KHR

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
  • Promoted to Vulkan 1.1

Contact

Other Extension Metadata

Last Modified Date

2016-10-28

IP Status

No known IP claims.

Interactions and External Dependencies
Contributors
  • Jeff Bolz, NVIDIA

Description

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.

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.

New Enum Constants

  • VK_KHR_MULTIVIEW_EXTENSION_NAME

  • VK_KHR_MULTIVIEW_SPEC_VERSION

  • Extending VkDependencyFlagBits:

    • VK_DEPENDENCY_VIEW_LOCAL_BIT_KHR

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MULTIVIEW_FEATURES_KHR

    • VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MULTIVIEW_PROPERTIES_KHR

    • VK_STRUCTURE_TYPE_RENDER_PASS_MULTIVIEW_CREATE_INFO_KHR

New Built-In Variables

New SPIR-V Capabilities

Version History

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

    • Internal revisions

VK_KHR_performance_query

Name String

VK_KHR_performance_query

Extension Type

Device extension

Registered Extension Number

117

Revision

1

Extension and Version Dependencies
Contact

Other Extension Metadata

Last Modified Date

2019-10-08

IP Status

No known IP claims.

Contributors
  • Jesse Barker, Unity Technologies

  • Kenneth Benzie, Codeplay

  • Jan-Harald Fredriksen, ARM

  • Jeff Leger, Qualcomm

  • Jesse Hall, Google

  • Tobias Hector, AMD

  • Neil Henning, Codeplay

  • Baldur Karlsson

  • Lionel Landwerlin, Intel

  • Peter Lohrmann, AMD

  • Alon Or-bach, Samsung

  • Daniel Rakos, AMD

  • Niklas Smedberg, Unity Technologies

  • Igor Ostrowski, Intel

Description

The VK_KHR_performance_query extension adds a mechanism to allow querying of performance counters for use in applications and by profiling tools.

Each queue family may expose counters that can be enabled on a queue of that family. We extend VkQueryType to add a new query type for performance queries, and chain a structure on VkQueryPoolCreateInfo to specify the performance queries to enable.

New Enum Constants

  • VK_KHR_PERFORMANCE_QUERY_EXTENSION_NAME

  • VK_KHR_PERFORMANCE_QUERY_SPEC_VERSION

  • Extending VkQueryType:

    • VK_QUERY_TYPE_PERFORMANCE_QUERY_KHR

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_ACQUIRE_PROFILING_LOCK_INFO_KHR

    • VK_STRUCTURE_TYPE_PERFORMANCE_COUNTER_DESCRIPTION_KHR

    • VK_STRUCTURE_TYPE_PERFORMANCE_COUNTER_KHR

    • VK_STRUCTURE_TYPE_PERFORMANCE_QUERY_SUBMIT_INFO_KHR

    • VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PERFORMANCE_QUERY_FEATURES_KHR

    • VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PERFORMANCE_QUERY_PROPERTIES_KHR

    • VK_STRUCTURE_TYPE_QUERY_POOL_PERFORMANCE_CREATE_INFO_KHR

Issues

1) Should this extension include a mechanism to begin a query in command buffer A and end the query in command buffer B?

RESOLVED No - queries are tied to command buffer creation and thus have to be encapsulated within a single command buffer.

2) Should this extension include a mechanism to begin and end queries globally on the queue, not using the existing command buffer commands?

RESOLVED No - for the same reasoning as the resolution of 1).

3) Should this extension expose counters that require multiple passes?

RESOLVED Yes - users should re-submit a command buffer with the same commands in it multiple times, specifying the pass to count as the query parameter in VkPerformanceQuerySubmitInfoKHR.

4) How to handle counters across parallel workloads?

RESOLVED In the spirit of Vulkan, a counter description flag VK_PERFORMANCE_COUNTER_DESCRIPTION_CONCURRENTLY_IMPACTED_KHR denotes that the accuracy of a counter result is affected by parallel workloads.

5) How to handle secondary command buffers?

RESOLVED Secondary command buffers inherit any counter pass index specified in the parent primary command buffer. Note: this is no longer an issue after change from issue 10 resolution

6) What commands does the profiling lock have to be held for?

RESOLVED For any command buffer that is being queried with a performance query pool, the profiling lock must be held while that command buffer is in the recording, executable, or pending state.

7) Should we support vkCmdCopyQueryPoolResults?

RESOLVED Yes.

8) Should we allow performance queries to interact with multiview?

RESOLVED Yes, but the performance queries must be performed once for each pass per view.

9) Should a queryCount > 1 be usable for performance queries?

RESOLVED Yes. Some vendors will have costly performance counter query pool creation, and would rather if a certain set of counters were to be used multiple times that a queryCount > 1 can be used to amortize the instantiation cost.

10) Should we introduce an indirect mechanism to set the counter pass index?

RESOLVED Specify the counter pass index at submit time instead to avoid requiring re-recording of command buffers when multiple counter passes needed.

Examples

The following example shows how to find what performance counters a queue family supports, setup a query pool to record these performance counters, how to add the query pool to the command buffer to record information, and how to get the results from the query pool.

// A previously created physical device
VkPhysicalDevice physicalDevice;

// One of the queue families our device supports
uint32_t queueFamilyIndex;

uint32_t counterCount;

// Get the count of counters supported
vkEnumeratePhysicalDeviceQueueFamilyPerformanceQueryCountersKHR(
  physicalDevice,
  queueFamilyIndex,
  &counterCount,
  NULL,
  NULL);

VkPerformanceCounterKHR* counters =
  malloc(sizeof(VkPerformanceCounterKHR) * counterCount);
VkPerformanceCounterDescriptionKHR* counterDescriptions =
  malloc(sizeof(VkPerformanceCounterDescriptionKHR) * counterCount);

// Get the counters supported
vkEnumeratePhysicalDeviceQueueFamilyPerformanceQueryCountersKHR(
  physicalDevice,
  queueFamilyIndex,
  &counterCount,
  counters,
  counterDescriptions);

// Try to enable the first 8 counters
uint32_t enabledCounters[8];

const uint32_t enabledCounterCount = min(counterCount, 8));

for (uint32_t i = 0; i < enabledCounterCount; i++) {
  enabledCounters[i] = i;
}

// A previously created device that had the performanceCounterQueryPools feature
// set to VK_TRUE
VkDevice device;

VkQueryPoolPerformanceCreateInfoKHR performanceQueryCreateInfo = {
  VK_STRUCTURE_TYPE_QUERY_POOL_PERFORMANCE_CREATE_INFO_KHR,
  NULL,

  // Specify the queue family that this performance query is performed on
  queueFamilyIndex,

  // The number of counters to enable
  enabledCounterCount,

  // The array of indices of counters to enable
  enabledCounters
};


// Get the number of passes our counters will require.
uint32_t numPasses;

vkGetPhysicalDeviceQueueFamilyPerformanceQueryPassesKHR(
  physicalDevice,
  &performanceQueryCreateInfo,
  &numPasses);

VkQueryPoolCreateInfo queryPoolCreateInfo = {
  VK_STRUCTURE_TYPE_QUERY_POOL_CREATE_INFO,
  &performanceQueryCreateInfo,
  0,

  // Using our new query type here
  VK_QUERY_TYPE_PERFORMANCE_QUERY_KHR,

  1,

  0
};

VkQueryPool queryPool;

VkResult result = vkCreateQueryPool(
  device,
  &queryPoolCreateInfo,
  NULL,
  &queryPool);

assert(VK_SUCCESS == result);

// A queue from queueFamilyIndex
VkQueue queue;

// A command buffer we want to record counters on
VkCommandBuffer commandBuffer;

VkCommandBufferBeginInfo commandBufferBeginInfo = {
  VK_STRUCTURE_TYPE_COMMAND_BUFFER_BEGIN_INFO,
  NULL,
  0,
  NULL
};

VkAcquireProfilingLockInfoKHR lockInfo = {
  VK_STRUCTURE_TYPE_ACQUIRE_PROFILING_LOCK_INFO_KHR,
  NULL,
  0,
  UINT64_MAX // Wait forever for the lock
};

// Acquire the profiling lock before we record command buffers
// that will use performance queries

result = vkAcquireProfilingLockKHR(device, &lockInfo);

assert(VK_SUCCESS == result);

result = vkBeginCommandBuffer(commandBuffer, &commandBufferBeginInfo);

assert(VK_SUCCESS == result);

vkCmdResetQueryPool(
  commandBuffer,
  queryPool,
  0,
  1);

vkCmdBeginQuery(
  commandBuffer,
  queryPool,
  0,
  0);

// Perform the commands you want to get performance information on
// ...

// Perform a barrier to ensure all previous commands were complete before
// ending the query
vkCmdPipelineBarrier(commandBuffer,
  VK_PIPELINE_STAGE_BOTTOM_OF_PIPE_BIT,
  VK_PIPELINE_STAGE_BOTTOM_OF_PIPE_BIT,
  0,
  0,
  NULL,
  0,
  NULL,
  0,
  NULL);

vkCmdEndQuery(
  commandBuffer,
  queryPool,
  0);

result = vkEndCommandBuffer(commandBuffer);

assert(VK_SUCCESS == result);

for (uint32_t counterPass = 0; counterPass < numPasses; counterPass++) {

  VkPerformanceQuerySubmitInfoKHR performanceQuerySubmitInfo = {
    VK_STRUCTURE_TYPE_PERFORMANCE_QUERY_SUBMIT_INFO_KHR,
    NULL,
    counterPass
  };


  // Submit the command buffer and wait for its completion
  // ...
}

// Release the profiling lock after the command buffer is no longer in the
// pending state.
vkReleaseProfilingLockKHR(device);

result = vkResetCommandBuffer(commandBuffer, 0);

assert(VK_SUCCESS == result);

// Create an array to hold the results of all counters
VkPerformanceCounterResultKHR* recordedCounters = malloc(
  sizeof(VkPerformanceCounterResultKHR) * enabledCounterCount);

result = vkGetQueryPoolResults(
  device,
  queryPool,
  0,
  1,
  sizeof(VkPerformanceCounterResultKHR) * enabledCounterCount,
  recordedCounters,
  sizeof(VkPerformanceCounterResultKHR),
  NULL);

// recordedCounters is filled with our counters, we'll look at one for posterity
switch (counters[0].storage) {
  case VK_PERFORMANCE_COUNTER_STORAGE_INT32:
    // use recordCounters[0].int32 to get at the counter result!
    break;
  case VK_PERFORMANCE_COUNTER_STORAGE_INT64:
    // use recordCounters[0].int64 to get at the counter result!
    break;
  case VK_PERFORMANCE_COUNTER_STORAGE_UINT32:
    // use recordCounters[0].uint32 to get at the counter result!
    break;
  case VK_PERFORMANCE_COUNTER_STORAGE_UINT64:
    // use recordCounters[0].uint64 to get at the counter result!
    break;
  case VK_PERFORMANCE_COUNTER_STORAGE_FLOAT32:
    // use recordCounters[0].float32 to get at the counter result!
    break;
  case VK_PERFORMANCE_COUNTER_STORAGE_FLOAT64:
    // use recordCounters[0].float64 to get at the counter result!
    break;
}

Version History

  • Revision 1, 2019-10-08

VK_KHR_pipeline_executable_properties

Name String

VK_KHR_pipeline_executable_properties

Extension Type

Device extension

Registered Extension Number

270

Revision

1

Extension and Version Dependencies
  • Requires Vulkan 1.0

Contact

Other Extension Metadata

Last Modified Date

2019-05-28

IP Status

No known IP claims.

Interactions and External Dependencies
Contributors
  • Jason Ekstrand, Intel

  • Ian Romanick, Intel

  • Kenneth Graunke, Intel

  • Baldur Karlsson, Valve

  • Jesse Hall, Google

  • Jeff Bolz, Nvidia

  • Piers Daniel, Nvidia

  • Tobias Hector, AMD

  • Jan-Harald Fredriksen, ARM

  • Tom Olson, ARM

  • Daniel Koch, Nvidia

  • Spencer Fricke, Samsung

Description

When a pipeline is created, its state and shaders are compiled into zero or more device-specific executables, which are used when executing commands against that pipeline. This extension adds a mechanism to query properties and statistics about the different executables produced by the pipeline compilation process. This is intended to be used by debugging and performance tools to allow them to provide more detailed information to the user. Certain compile-time shader statistics provided through this extension may be useful to developers for debugging or performance analysis.

New Enum Constants

  • VK_KHR_PIPELINE_EXECUTABLE_PROPERTIES_EXTENSION_NAME

  • VK_KHR_PIPELINE_EXECUTABLE_PROPERTIES_SPEC_VERSION

  • Extending VkPipelineCreateFlagBits:

    • VK_PIPELINE_CREATE_CAPTURE_INTERNAL_REPRESENTATIONS_BIT_KHR

    • VK_PIPELINE_CREATE_CAPTURE_STATISTICS_BIT_KHR

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PIPELINE_EXECUTABLE_PROPERTIES_FEATURES_KHR

    • VK_STRUCTURE_TYPE_PIPELINE_EXECUTABLE_INFO_KHR

    • VK_STRUCTURE_TYPE_PIPELINE_EXECUTABLE_INTERNAL_REPRESENTATION_KHR

    • VK_STRUCTURE_TYPE_PIPELINE_EXECUTABLE_PROPERTIES_KHR

    • VK_STRUCTURE_TYPE_PIPELINE_EXECUTABLE_STATISTIC_KHR

    • VK_STRUCTURE_TYPE_PIPELINE_INFO_KHR

Issues

1) What should we call the pieces of the pipeline which are produced by the compilation process and about which you can query properties and statistics?

RESOLVED: Call them "executables". The name "binary" was used in early drafts of the extension but it was determined that "pipeline binary" could have a fairly broad meaning (such as a binary serialized form of an entire pipeline) and was too big of a namespace for the very specific needs of this extension.

Version History

  • Revision 1, 2019-05-28 (Jason Ekstrand)

    • Initial draft

VK_KHR_push_descriptor

Name String

VK_KHR_push_descriptor

Extension Type

Device extension

Registered Extension Number

81

Revision

2

Extension and Version Dependencies
Contact

Other Extension Metadata

Last Modified Date

2017-09-12

IP Status

No known IP claims.

Contributors
  • Jeff Bolz, NVIDIA

  • Michael Worcester, Imagination Technologies

Description

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

  • VK_KHR_PUSH_DESCRIPTOR_EXTENSION_NAME

  • VK_KHR_PUSH_DESCRIPTOR_SPEC_VERSION

  • Extending VkDescriptorSetLayoutCreateFlagBits:

    • VK_DESCRIPTOR_SET_LAYOUT_CREATE_PUSH_DESCRIPTOR_BIT_KHR

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PUSH_DESCRIPTOR_PROPERTIES_KHR

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_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
  • Promoted to Vulkan 1.1

Contact

Other Extension Metadata

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

Description

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.

New Enum Constants

  • VK_KHR_RELAXED_BLOCK_LAYOUT_EXTENSION_NAME

  • VK_KHR_RELAXED_BLOCK_LAYOUT_SPEC_VERSION

Version History

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

VK_KHR_sampler_mirror_clamp_to_edge

Name String

VK_KHR_sampler_mirror_clamp_to_edge

Extension Type

Device extension

Registered Extension Number

15

Revision

3

Extension and Version Dependencies
  • Requires Vulkan 1.0

Deprecation state
  • Promoted to Vulkan 1.2

Contact

Other Extension Metadata

Last Modified Date

2019-08-17

Interactions and External Dependencies
  • Promoted to Vulkan 1.2 Core

Contributors
  • Tobias Hector, Imagination Technologies

  • Jon Leech, Khronos

Description

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.

Promotion to Vulkan 1.2

All functionality in this extension is included in core Vulkan 1.2. However, if Vulkan 1.2 is supported and this extension is not, the VkSamplerAddressMode VK_SAMPLER_ADDRESS_MODE_MIRROR_CLAMP_TO_EDGE is optional. Since the original extension did not use an author suffix on the enum VK_SAMPLER_ADDRESS_MODE_MIRROR_CLAMP_TO_EDGE, it is used by both core and extension implementations.

New Enum Constants

  • VK_KHR_SAMPLER_MIRROR_CLAMP_TO_EDGE_EXTENSION_NAME

  • VK_KHR_SAMPLER_MIRROR_CLAMP_TO_EDGE_SPEC_VERSION

  • Extending VkSamplerAddressMode:

    • VK_SAMPLER_ADDRESS_MODE_MIRROR_CLAMP_TO_EDGE

Example

Creating a sampler with the new address mode in each dimension

    VkSamplerCreateInfo createInfo =
    {
        VK_STRUCTURE_TYPE_SAMPLER_CREATE_INFO // sType
        // Other members set to application-desired values
    };

    createInfo.addressModeU = VK_SAMPLER_ADDRESS_MODE_MIRROR_CLAMP_TO_EDGE;
    createInfo.addressModeV = VK_SAMPLER_ADDRESS_MODE_MIRROR_CLAMP_TO_EDGE;
    createInfo.addressModeW = VK_SAMPLER_ADDRESS_MODE_MIRROR_CLAMP_TO_EDGE;

    VkSampler sampler;
    VkResult result = vkCreateSampler(
        device,
        &createInfo,
        &sampler);

Issues

1) Why are both KHR and core versions of the VK_SAMPLER_ADDRESS_MODE_MIRROR_CLAMP_TO_EDGE token present?

RESOLVED: This functionality was intended to be required in Vulkan 1.0. We realized shortly before public release that not all implementations could support it, and moved the functionality into an optional extension, but did not apply the KHR extension suffix. Adding a KHR-suffixed alias of the non-suffixed enum has been done to comply with our own naming rules.

In a related change, before spec revision 1.1.121 this extension was hardwiring into the spec Makefile so it was always included with the Specification, even in the core-only versions. This has now been reverted, and it is treated as any other extension.

Version History

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

    • Initial draft

  • Revision 2, 2019-08-14 (Jon Leech)

    • Add KHR-suffixed alias of non-suffixed enum.

  • Revision 3, 2019-08-17 (Jon Leech)

    • Add an issue explaining the reason for the extension API not being suffixed with KHR.

VK_KHR_sampler_ycbcr_conversion

Name String

VK_KHR_sampler_ycbcr_conversion

Extension Type

Device extension

Registered Extension Number

157

Revision

14

Extension and Version Dependencies
Deprecation state
  • Promoted to Vulkan 1.1

Contact

Other Extension Metadata

Last Modified Date

2017-08-11

IP Status

No known IP claims.

Interactions and External Dependencies
  • Promoted to Vulkan 1.1 Core

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

Description

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.

Promotion to Vulkan 1.1

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

New Object Types

New Enum Constants

  • VK_KHR_SAMPLER_YCBCR_CONVERSION_EXTENSION_NAME

  • VK_KHR_SAMPLER_YCBCR_CONVERSION_SPEC_VERSION

  • Extending VkChromaLocation:

    • VK_CHROMA_LOCATION_COSITED_EVEN_KHR

    • VK_CHROMA_LOCATION_MIDPOINT_KHR

  • Extending VkDebugReportObjectTypeEXT:

    • VK_DEBUG_REPORT_OBJECT_TYPE_SAMPLER_YCBCR_CONVERSION_KHR_EXT

  • Extending VkFormat:

    • VK_FORMAT_B10X6G10X6R10X6G10X6_422_UNORM_4PACK16_KHR

    • VK_FORMAT_B12X4G12X4R12X4G12X4_422_UNORM_4PACK16_KHR

    • VK_FORMAT_B16G16R16G16_422_UNORM_KHR

    • VK_FORMAT_B8G8R8G8_422_UNORM_KHR

    • VK_FORMAT_G10X6B10X6G10X6R10X6_422_UNORM_4PACK16_KHR

    • VK_FORMAT_G10X6_B10X6R10X6_2PLANE_420_UNORM_3PACK16_KHR

    • VK_FORMAT_G10X6_B10X6R10X6_2PLANE_422_UNORM_3PACK16_KHR

    • VK_FORMAT_G10X6_B10X6_R10X6_3PLANE_420_UNORM_3PACK16_KHR

    • VK_FORMAT_G10X6_B10X6_R10X6_3PLANE_422_UNORM_3PACK16_KHR

    • VK_FORMAT_G10X6_B10X6_R10X6_3PLANE_444_UNORM_3PACK16_KHR

    • VK_FORMAT_G12X4B12X4G12X4R12X4_422_UNORM_4PACK16_KHR

    • VK_FORMAT_G12X4_B12X4R12X4_2PLANE_420_UNORM_3PACK16_KHR

    • VK_FORMAT_G12X4_B12X4R12X4_2PLANE_422_UNORM_3PACK16_KHR

    • VK_FORMAT_G12X4_B12X4_R12X4_3PLANE_420_UNORM_3PACK16_KHR

    • VK_FORMAT_G12X4_B12X4_R12X4_3PLANE_422_UNORM_3PACK16_KHR

    • VK_FORMAT_G12X4_B12X4_R12X4_3PLANE_444_UNORM_3PACK16_KHR

    • VK_FORMAT_G16B16G16R16_422_UNORM_KHR

    • VK_FORMAT_G16_B16R16_2PLANE_420_UNORM_KHR

    • VK_FORMAT_G16_B16R16_2PLANE_422_UNORM_KHR

    • VK_FORMAT_G16_B16_R16_3PLANE_420_UNORM_KHR

    • VK_FORMAT_G16_B16_R16_3PLANE_422_UNORM_KHR

    • VK_FORMAT_G16_B16_R16_3PLANE_444_UNORM_KHR

    • VK_FORMAT_G8B8G8R8_422_UNORM_KHR

    • VK_FORMAT_G8_B8R8_2PLANE_420_UNORM_KHR

    • VK_FORMAT_G8_B8R8_2PLANE_422_UNORM_KHR

    • VK_FORMAT_G8_B8_R8_3PLANE_420_UNORM_KHR

    • VK_FORMAT_G8_B8_R8_3PLANE_422_UNORM_KHR

    • VK_FORMAT_G8_B8_R8_3PLANE_444_UNORM_KHR

    • VK_FORMAT_R10X6G10X6B10X6A10X6_UNORM_4PACK16_KHR

    • VK_FORMAT_R10X6G10X6_UNORM_2PACK16_KHR

    • VK_FORMAT_R10X6_UNORM_PACK16_KHR

    • VK_FORMAT_R12X4G12X4B12X4A12X4_UNORM_4PACK16_KHR

    • VK_FORMAT_R12X4G12X4_UNORM_2PACK16_KHR

    • VK_FORMAT_R12X4_UNORM_PACK16_KHR

  • Extending VkFormatFeatureFlagBits:

    • VK_FORMAT_FEATURE_COSITED_CHROMA_SAMPLES_BIT_KHR

    • VK_FORMAT_FEATURE_DISJOINT_BIT_KHR

    • VK_FORMAT_FEATURE_MIDPOINT_CHROMA_SAMPLES_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_SAMPLED_IMAGE_YCBCR_CONVERSION_LINEAR_FILTER_BIT_KHR

    • VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_SEPARATE_RECONSTRUCTION_FILTER_BIT_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 VkObjectType:

    • VK_OBJECT_TYPE_SAMPLER_YCBCR_CONVERSION_KHR

  • Extending VkSamplerYcbcrModelConversion:

    • VK_SAMPLER_YCBCR_MODEL_CONVERSION_RGB_IDENTITY_KHR

    • VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_2020_KHR

    • VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_601_KHR

    • VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_709_KHR

    • VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_IDENTITY_KHR

  • Extending VkSamplerYcbcrRange:

    • VK_SAMPLER_YCBCR_RANGE_ITU_FULL_KHR

    • VK_SAMPLER_YCBCR_RANGE_ITU_NARROW_KHR

  • Extending VkStructureType:

    • 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

    • VK_STRUCTURE_TYPE_SAMPLER_YCBCR_CONVERSION_CREATE_INFO_KHR

    • VK_STRUCTURE_TYPE_SAMPLER_YCBCR_CONVERSION_IMAGE_FORMAT_PROPERTIES_KHR

    • VK_STRUCTURE_TYPE_SAMPLER_YCBCR_CONVERSION_INFO_KHR

If VK_EXT_debug_report is supported:

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

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

    • Tidying, incorporated new image query, restored transfer functions

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

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

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

    • Simplified further

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

    • Disjoint no more

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

    • Restored disjoint

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

    • Now Ycbcr conversion, and KHR

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

    • Added conversion to image view creation

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

    • Allowed cosited-only chroma samples for formats

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

    • Reflected quantization changes in BT.2100-1

VK_KHR_separate_depth_stencil_layouts

Name String

VK_KHR_separate_depth_stencil_layouts

Extension Type

Device extension

Registered Extension Number

242

Revision

1

Extension and Version Dependencies
Deprecation state
  • Promoted to Vulkan 1.2

Contact

Other Extension Metadata

Last Modified Date

2019-06-25

Interactions and External Dependencies
  • Promoted to Vulkan 1.2 Core

Contributors
  • Daniel Koch, NVIDIA

  • Jeff Bolz, NVIDIA

  • Jesse Barker, Unity

  • Tobias Hector, AMD

Description

This extension allows image memory barriers for depth/stencil images to have just one of the VK_IMAGE_ASPECT_DEPTH_BIT or VK_IMAGE_ASPECT_STENCIL_BIT aspect bits set, rather than require both. This allows their layouts to be set independently. To support depth/stencil images with different layouts for the depth and stencil aspects, the depth/stencil attachment interface has been updated to support a separate layout for stencil.

Promotion to Vulkan 1.2

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

New Enum Constants

  • VK_KHR_SEPARATE_DEPTH_STENCIL_LAYOUTS_EXTENSION_NAME

  • VK_KHR_SEPARATE_DEPTH_STENCIL_LAYOUTS_SPEC_VERSION

  • Extending VkImageLayout:

    • VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL_KHR

    • VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL_KHR

    • VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL_KHR

    • VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL_KHR

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_ATTACHMENT_DESCRIPTION_STENCIL_LAYOUT_KHR

    • VK_STRUCTURE_TYPE_ATTACHMENT_REFERENCE_STENCIL_LAYOUT_KHR

    • VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SEPARATE_DEPTH_STENCIL_LAYOUTS_FEATURES_KHR

Version History

  • Revision 1, 2019-06-25 (Piers Daniell)

    • Internal revisions

VK_KHR_shader_atomic_int64

Name String

VK_KHR_shader_atomic_int64

Extension Type

Device extension

Registered Extension Number

181

Revision

1

Extension and Version Dependencies
Deprecation state
  • Promoted to Vulkan 1.2

Contact

Other Extension Metadata

Last Modified Date

2018-07-05

Interactions and External Dependencies
  • Promoted to Vulkan 1.2 Core

Interactions and External Dependencies
Contributors
  • Aaron Hagan, AMD

  • Daniel Rakos, AMD

  • Jeff Bolz, NVIDIA

  • Neil Henning, Codeplay

Description

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.

Promotion to Vulkan 1.2

All functionality in this extension is included in core Vulkan 1.2, with the KHR suffix omitted. However, if Vulkan 1.2 is supported and this extension is not, the shaderBufferInt64Atomics capability is optional. The original type, enum and command names are still available as aliases of the core functionality.

New Enum Constants

  • VK_KHR_SHADER_ATOMIC_INT64_EXTENSION_NAME

  • VK_KHR_SHADER_ATOMIC_INT64_SPEC_VERSION

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

Name String

VK_KHR_shader_clock

Extension Type

Device extension

Registered Extension Number

182

Revision

1

Extension and Version Dependencies
Contact

Other Extension Metadata

Last Modified Date

2019-4-25

IP Status

No known IP claims.

Interactions and External Dependencies
Contributors
  • Aaron Hagan, AMD

  • Daniel Koch, NVIDIA

Description

This extension advertises the SPIR-V ShaderClockKHR capability for Vulkan, which allows a shader to query a real-time or monotonically incrementing counter at the subgroup level or across the device level. The two valid SPIR-V scopes for OpReadClockKHR are Subgroup and Device.

When using GLSL source-based shading languages, the clockRealtime*EXT() timing functions map to the OpReadClockKHR instruction with a scope of Device, and the clock*ARB() timing functions map to the OpReadClockKHR instruction with a scope of Subgroup.

New Enum Constants

  • VK_KHR_SHADER_CLOCK_EXTENSION_NAME

  • VK_KHR_SHADER_CLOCK_SPEC_VERSION

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_CLOCK_FEATURES_KHR

New SPIR-V Capabilities

Version History

  • Revision 1, 2019-4-25 (Aaron Hagan)

    • Initial revision

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
  • Promoted to Vulkan 1.1

Contact

Other Extension Metadata

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

Description

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

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 is actually available or not.

New Enum Constants

  • VK_KHR_SHADER_DRAW_PARAMETERS_EXTENSION_NAME

  • VK_KHR_SHADER_DRAW_PARAMETERS_SPEC_VERSION

New Built-In Variables

New SPIR-V Capabilities

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_shader_float16_int8

Name String

VK_KHR_shader_float16_int8

Extension Type

Device extension

Registered Extension Number

83

Revision

1

Extension and Version Dependencies
Deprecation state
  • Promoted to Vulkan 1.2

Contact

Other Extension Metadata

Last Modified Date

2018-03-07

Interactions and External Dependencies
  • Promoted to Vulkan 1.2 Core

IP Status

No known IP claims.

Interactions and External Dependencies
Contributors
  • Alexander Galazin, Arm

  • Jan-Harald Fredriksen, Arm

  • Jeff Bolz, NVIDIA

  • Graeme Leese, Broadcom

  • Daniel Rakos, AMD

Description

The VK_KHR_shader_float16_int8 extension allows use of 16-bit floating-point types and 8-bit integer types in shaders for arithmetic operations.

It introduces two new optional features shaderFloat16 and shaderInt8 which directly map to the Float16 and the Int8 SPIR-V capabilities. The VK_KHR_shader_float16_int8 extension also specifies precision requirements for half-precision floating-point SPIR-V operations. This extension does not enable use of 8-bit integer types or 16-bit floating-point types in any shader input and output interfaces and therefore does not supersede the VK_KHR_8bit_storage or VK_KHR_16bit_storage extensions.

Promotion to Vulkan 1.2

All functionality in this extension is included in core Vulkan 1.2, with the KHR suffix omitted. However, if Vulkan 1.2 is supported and this extension is not, both the shaderFloat16 and shaderInt8 capabilities are optional. The original type, enum and command names are still available as aliases of the core functionality.

New Enum Constants

  • VK_KHR_SHADER_FLOAT16_INT8_EXTENSION_NAME

  • VK_KHR_SHADER_FLOAT16_INT8_SPEC_VERSION

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FLOAT16_INT8_FEATURES_KHR

    • VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_FLOAT16_INT8_FEATURES_KHR

Version History

  • Revision 1, 2018-03-07 (Alexander Galazin)

    • Initial draft

VK_KHR_shader_float_controls

Name String

VK_KHR_shader_float_controls

Extension Type

Device extension

Registered Extension Number

198

Revision

4

Extension and Version Dependencies
Deprecation state
  • Promoted to Vulkan 1.2

Contact

Other Extension Metadata

Last Modified Date

2018-09-11

Interactions and External Dependencies
  • Promoted to Vulkan 1.2 Core

IP Status

No known IP claims.

Interactions and External Dependencies
Contributors
  • Alexander Galazin, Arm

  • Jan-Harald Fredriksen, Arm

  • Jeff Bolz, NVIDIA

  • Graeme Leese, Broadcom

  • Daniel Rakos, AMD

Description

The VK_KHR_shader_float_controls extension enables efficient use of floating-point computations through the ability to query and override the implementation’s default behavior for rounding modes, denormals, signed zero, and infinity.

Promotion to Vulkan 1.2

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

New Enum Constants

  • VK_KHR_SHADER_FLOAT_CONTROLS_EXTENSION_NAME

  • VK_KHR_SHADER_FLOAT_CONTROLS_SPEC_VERSION

  • Extending VkShaderFloatControlsIndependence:

    • VK_SHADER_FLOAT_CONTROLS_INDEPENDENCE_32_BIT_ONLY_KHR

    • VK_SHADER_FLOAT_CONTROLS_INDEPENDENCE_ALL_KHR

    • VK_SHADER_FLOAT_CONTROLS_INDEPENDENCE_NONE_KHR

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FLOAT_CONTROLS_PROPERTIES_KHR

Issues

1) Which instructions must flush denorms?

RESOLVED: Only floating-point conversion, floating-point arithmetic, floating-point relational (except OpIsNaN, OpIsInf), and floating-point GLSL.std.450 extended instructions must flush denormals.

2) What is the denorm behavior for intermediate results?

RESOLVED: When a SPIR-V instruction is implemented as a sequence of other instructions: - in the DenormFlushToZero execution mode the intermediate instructions may flush denormals, the final result of the sequence must not be denormal. - in the DenormPreserve execution mode denormals must be preserved throughout the whole sequence.

3) Do denorm and rounding mode controls apply to OpSpecConstantOp?

RESOLVED: Yes, except when the opcode is OpQuantizeToF16.

4) The SPIR-V specification says that OpConvertFToU and OpConvertFToS unconditionally round towards zero. Do the rounding mode controls specified through the execution modes apply to them?

RESOLVED: No, these instructions unconditionally round towards zero.

5) Do any of the "Pack" GLSL.std.450 instructions count as conversion instructions and have the rounding mode apply?

RESOLVED: No, only instructions listed in the section "3.32.11. Conversion Instructions" of the SPIR-V specification count as conversion instructions.

6) When using inf/nan-ignore mode, what is expected of OpIsNan and OpIsInf?

RESOLVED: These instructions must always accurately detect inf/nan if it is passed to them.

Version 4 API incompatibility

The original versions of VK_KHR_shader_float_controls shipped with booleans named “separateDenormSettings” and “separateRoundingModeSettings”, which at first glance could have indicated “they can all independently set, or not”. However the spec language as written indicated that the 32-bit value could always be set independently, and only the 16- and 64-bit controls needed to be the same if these values were VK_FALSE.

As a result of this slight disparity, and lack of test coverage for this facet of the extension, we ended up with two different behaviors in the wild, where some implementations worked as written, and others worked based on the naming. As these are hard limits in hardware with reasons for exposure as written, it was not possible to standardise on a single way to make this work within the existing API.

No known users of this part of the extension exist in the wild, and as such the Vulkan WG took the unusual step of retroactively changing the once boolean value into a tri-state enum, breaking source compatibility. This was however done in such a way as to retain ABI compatibility, in case any code using this did exist; with the numerical values 0 and 1 retaining their original specified meaning, and a new value signifying the additional “all need to be set together” state. If any applications exist today, compiled binaries will continue to work as written in most cases, but will need changes before the code can be recompiled.

Version History

  • Revision 4, 2019-06-18 (Tobias Hector)

  • Revision 3, 2018-09-11 (Alexander Galazin)

    • Minor restructuring

  • Revision 2, 2018-04-17 (Alexander Galazin)

    • Added issues and resolutions

  • Revision 1, 2018-04-11 (Alexander Galazin)

    • Initial draft

VK_KHR_shader_non_semantic_info

Name String

VK_KHR_shader_non_semantic_info

Extension Type

Device extension

Registered Extension Number

294

Revision

1

Extension and Version Dependencies
  • Requires Vulkan 1.0

Contact

Other Extension Metadata

Last Modified Date

2019-10-16

IP Status

No known IP claims.

Interactions and External Dependencies
Contributors
  • Baldur Karlsson, Valve

Description

This extension allows the use of the SPV_KHR_non_semantic_info extension in SPIR-V shader modules.

New Enum Constants

  • VK_KHR_SHADER_NON_SEMANTIC_INFO_EXTENSION_NAME

  • VK_KHR_SHADER_NON_SEMANTIC_INFO_SPEC_VERSION

Version History

  • Revision 1, 2019-10-16 (Baldur Karlsson)

    • Initial revision

VK_KHR_shader_subgroup_extended_types

Name String

VK_KHR_shader_subgroup_extended_types

Extension Type

Device extension

Registered Extension Number

176

Revision

1

Extension and Version Dependencies
  • Requires Vulkan 1.1

Deprecation state
  • Promoted to Vulkan 1.2

Contact

Other Extension Metadata

Last Modified Date

2019-01-08

IP Status

No known IP claims.

Interactions and External Dependencies
  • Promoted to Vulkan 1.2 Core

Contributors
  • Jeff Bolz, NVIDIA

  • Jan-Harald Fredriksen, Arm

  • Neil Henning, AMD

  • Daniel Koch, NVIDIA

  • Jeff Leger, Qualcomm

  • Graeme Leese, Broadcom

  • David Neto, Google

  • Daniel Rakos, AMD

Description

This extension enables the Non Uniform Group Operations in SPIR-V to support 8-bit integer, 16-bit integer, 64-bit integer, 16-bit floating-point, and vectors of these types.

Promotion to Vulkan 1.2

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

New Enum Constants

  • VK_KHR_SHADER_SUBGROUP_EXTENDED_TYPES_EXTENSION_NAME

  • VK_KHR_SHADER_SUBGROUP_EXTENDED_TYPES_SPEC_VERSION

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_SUBGROUP_EXTENDED_TYPES_FEATURES_KHR

Version History

  • Revision 1, 2019-01-08 (Neil Henning)

    • Initial draft

VK_KHR_shared_presentable_image

Name String

VK_KHR_shared_presentable_image

Extension Type

Device extension

Registered Extension Number

112

Revision

1

Extension and Version Dependencies
Contact

Other Extension Metadata

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

Description

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

  • VK_KHR_SHARED_PRESENTABLE_IMAGE_EXTENSION_NAME

  • VK_KHR_SHARED_PRESENTABLE_IMAGE_SPEC_VERSION

  • Extending VkImageLayout:

    • VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR

  • Extending VkPresentModeKHR:

    • VK_PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR

    • VK_PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_SHARED_PRESENT_SURFACE_CAPABILITIES_KHR

Issues

1) Should we allow a Vulkan WSI swapchain to toggle between normal usage and shared presentation usage?

RESOLVED: No. WSI swapchains are typically recreated with new properties instead of having their properties changed. This can also save resources, assuming that fewer images are needed for shared presentation, and assuming that most VR applications do not need to switch between normal and shared usage.

2) Should we have a query for determining how the presentation engine refresh is triggered?

RESOLVED: Yes. This is done via which presentation modes a surface supports.

3) Should the object representing a shared presentable image be an extension of a VkSwapchainKHR or a separate object?

RESOLVED: Extension of a swapchain due to overlap in creation properties and to allow common functionality between shared and normal presentable images and swapchains.

4) What should we call the extension and the new structures it creates?

RESOLVED: Shared presentable image / shared present.

5) Should the minImageCount and presentMode values of the VkSwapchainCreateInfoKHR be ignored, or required to be compatible values?

RESOLVED: minImageCount must be set to 1, and presentMode should be set to either VK_PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR or VK_PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR.

6) What should the layout of the shared presentable image be?

RESOLVED: After acquiring the shared presentable image, the application must transition it to the VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR layout prior to it being used. After this initial transition, any image usage that was requested during swapchain creation can be performed on the image without layout transitions being performed.

7) Do we need a new API for the trigger to refresh new content?

RESOLVED: vkQueuePresentKHR to act as API to trigger a refresh, as will allow combination with other compatible extensions to vkQueuePresentKHR.

8) How should an application detect a VK_ERROR_OUT_OF_DATE_KHR error on a swapchain using the VK_PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR present mode?

RESOLVED: Introduce vkGetSwapchainStatusKHR to allow applications to query the status of a swapchain using a shared presentation mode.

9) What should subsequent calls to vkQueuePresentKHR for VK_PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR swapchains be defined to do?

RESOLVED: State that implementations may use it as a hint for updated content.

10) Can the ownership of a shared presentable image be transferred to a different queue?

RESOLVED: No. It is not possible to transfer ownership of a shared presentable image obtained from a swapchain created using VK_SHARING_MODE_EXCLUSIVE after it has been presented.

11) How should vkQueueSubmit behave if a command buffer uses an image from a VK_ERROR_OUT_OF_DATE_KHR swapchain?

RESOLVED: vkQueueSubmit is expected to return the VK_ERROR_DEVICE_LOST error.

12) Can Vulkan provide any guarantee on the order of rendering, to enable beam chasing?

RESOLVED: This could be achieved via use of render passes to ensure strip rendering.

Version History

  • Revision 1, 2017-03-20 (Alon Or-bach)

    • Internal revisions

VK_KHR_spirv_1_4

Name String

VK_KHR_spirv_1_4

Extension Type

Device extension

Registered Extension Number

237

Revision

1

Extension and Version Dependencies
Deprecation state
  • Promoted to Vulkan 1.2

Contact

Other Extension Metadata

Last Modified Date

2019-04-01

IP Status

No known IP claims.

Interactions and External Dependencies
  • Requires SPIR-V 1.4.

  • Promoted to Vulkan 1.2 Core

Contributors
  • Alexander Galazin, Arm

  • David Neto, Google

  • Jesse Hall, Google

  • John Kessenich, Google

  • Neil Henning, AMD

  • Tom Olson, Arm

Description

This extension allows the use of SPIR-V 1.4 shader modules. SPIR-V 1.4’s new features primarily make it an easier target for compilers from high-level languages, rather than exposing new hardware functionality.

SPIR-V 1.4 incorporates features that are also available separately as extensions. SPIR-V 1.4 shader modules do not need to enable those extensions with the OpExtension opcode, since they are integral parts of SPIR-V 1.4.

SPIR-V 1.4 introduces new floating point execution mode capabilities, also available via SPV_KHR_float_controls. Implementations are not required to support all of these new capabilities; support can be queried using VkPhysicalDeviceFloatControlsPropertiesKHR from the VK_KHR_shader_float_controls extension.

Promotion to Vulkan 1.2

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

New Enum Constants

  • VK_KHR_SPIRV_1_4_EXTENSION_NAME

  • VK_KHR_SPIRV_1_4_SPEC_VERSION

Issues

1. Should we have an extension specific to this SPIR-V version, or add a version-generic query for SPIR-V version? SPIR-V 1.4 doesn’t need any other API changes.

RESOLVED: Just expose SPIR-V 1.4.

Most new SPIR-V versions introduce optionally-required capabilities or have implementation-defined limits, and would need more API and specification changes specific to that version to make them available in Vulkan. For example, to support the subgroup capabilities added in SPIR-V 1.3 required introducing VkPhysicalDeviceSubgroupProperties to allow querying the supported group operation categories, maximum supported subgroup size, etc. While we could expose the parts of a new SPIR-V version that don’t need accompanying changes generically, we’ll still end up writing extensions specific to each version for the remaining parts. Thus the generic mechanism won’t reduce future spec-writing effort. In addition, making it clear which parts of a future version are supported by the generic mechanism and which can’t be used without specific support would be difficult to get right ahead of time.

2. Can different stages of the same pipeline use shaders with different SPIR-V versions?

RESOLVED: Yes.

Mixing SPIR-V versions 1.0-1.3 in the same pipeline has not been disallowed, so it would be inconsistent to disallow mixing 1.4 with previous versions.. SPIR-V 1.4 does not introduce anything that should cause new difficulties here.

3. Must Vulkan extensions corresponding to SPIR-V extensions that were promoted to core in 1.4 be enabled in order to use that functionality in a SPIR-V 1.4 module?

RESOLVED: No, with caveats.

The SPIR-V 1.4 module does not need to declare the SPIR-V extensions, since the functionality is now part of core, so there is no need to enable the Vulkan extension that allows SPIR-V modules to declare the SPIR-V extension. However, when the functionality that is now core in SPIR-V 1.4 is optionally supported, the query for support is provided by a Vulkan extension, and that query can only be used if the extension is enabled.

This applies to any SPIR-V version; specifically for SPIR-V 1.4 this only applies to the functionality from SPV_KHR_float_controls, which was made available in Vulkan by VK_KHR_shader_float_controls. Even though the extension was promoted in SPIR-V 1.4, the capabilities are still optional in implementations that support VK_KHR_spirv_1_4.

A SPIR-V 1.4 module doesn’t need to enable SPV_KHR_float_controls in order to use the capabilities, so if the application has a priori knowledge that the implementation supports the capabilities, it doesn’t need to enable VK_KHR_shader_float_controls. However, if it doesn’t have this knowledge and has to query for support at runtime, it must enable VK_KHR_shader_float_controls in order to use VkPhysicalDeviceFloatControlsPropertiesKHR.

Version History

  • Revision 1, 2019-04-01 (Jesse Hall)

    • Internal draft versions

VK_KHR_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
  • Promoted to Vulkan 1.1

Contact

Other Extension Metadata

Last Modified Date

2017-09-05

IP Status

No known IP claims.

Interactions and External Dependencies
Contributors
  • Alexander Galazin, ARM

  • David Neto, Google

Description

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.

Promotion to Vulkan 1.1

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

New Enum Constants

  • VK_KHR_STORAGE_BUFFER_STORAGE_CLASS_EXTENSION_NAME

  • VK_KHR_STORAGE_BUFFER_STORAGE_CLASS_SPEC_VERSION

Version History

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

    • Initial draft

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

Other Extension Metadata

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

Description

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

  • VK_KHR_SURFACE_EXTENSION_NAME

  • VK_KHR_SURFACE_SPEC_VERSION

  • Extending VkObjectType:

    • VK_OBJECT_TYPE_SURFACE_KHR

  • Extending VkResult:

    • VK_ERROR_NATIVE_WINDOW_IN_USE_KHR

    • VK_ERROR_SURFACE_LOST_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 be in this extension and operate on physical devices, rather than being in VK_KHR_swapchain (i.e. device extension) and being dependent on VkDevice?

RESOLVED: Yes. While it might be useful to depend on VkDevice (and therefore on enabled extensions and features) for the queries, Vulkan was released only with the VkPhysicalDevice versions. Many cases can be resolved by a Valid Usage. And\or by a separate pNext chain version of the query struct specific to a given extension or parameters, via extensible versions of the queries: vkGetPhysicalDeviceSurfaceCapabilities2KHR, vkGetPhysicalDeviceSurfaceFormats2KHR, and vkGetPhysicalDeviceSurfacePresentModes2EXT.

3) Should Vulkan include support Xlib or XCB as the API for accessing the X Window System platform?

RESOLVED: Both. XCB is a more modern and efficient API, but Xlib usage is deeply ingrained in many applications and likely will remain in use for the foreseeable future. Not all drivers necessarily need to support both, but including both as options in the core specification will probably encourage support, which should in turn ease adoption of the Vulkan API in older codebases. Additionally, the performance improvements possible with XCB likely will not have a measurable impact on the performance of Vulkan presentation and other minimal window system interactions defined here.

4) Should the GBM platform be included in the list of platform enums?

RESOLVED: Deferred, and will be addressed with a platform-specific extension to be written in the future.

Version History

  • Revision 1, 2015-05-20 (James Jones)

    • Initial draft, based on LunarG KHR spec, other KHR specs, patches attached to bugs.

  • Revision 2, 2015-05-22 (Ian Elliott)

    • Created initial Description section.

    • Removed query for whether a platform requires the use of a queue for presentation, since it was decided that presentation will always be modeled as being part of the queue.

    • Fixed typos and other minor mistakes.

  • Revision 3, 2015-05-26 (Ian Elliott)

    • Improved the Description section.

  • Revision 4, 2015-05-27 (James Jones)

    • Fixed compilation errors in example code.

  • Revision 5, 2015-06-01 (James Jones)

    • Added issues 1 and 2 and made related spec updates.

  • Revision 6, 2015-06-01 (James Jones)

    • Merged the platform type mappings table previously removed from VK_KHR_swapchain with the platform description table in this spec.

    • Added issues 3 and 4 documenting choices made when building the initial list of native platforms supported.

  • Revision 7, 2015-06-11 (Ian Elliott)

    • Updated table 1 per input from the KHR TSG.

    • Updated issue 4 (GBM) per discussion with Daniel Stone. He will create a platform-specific extension sometime in the future.

  • Revision 8, 2015-06-17 (James Jones)

    • Updated enum-extending values using new convention.

    • Fixed the value of VK_SURFACE_PLATFORM_INFO_TYPE_SUPPORTED_KHR.

  • Revision 9, 2015-06-17 (James Jones)

    • Rebased on Vulkan API version 126.

  • Revision 10, 2015-06-18 (James Jones)

    • Marked issues 2 and 3 resolved.

  • Revision 11, 2015-06-23 (Ian Elliott)

    • Examples now show use of function pointers for extension functions.

    • Eliminated extraneous whitespace.

  • Revision 12, 2015-07-07 (Daniel Rakos)

    • Added error section describing when each error is expected to be reported.

    • Replaced the term "queue node index" with "queue family index" in the spec as that is the agreed term to be used in the latest version of the core header and spec.

    • Replaced bool32_t with VkBool32.

  • Revision 13, 2015-08-06 (Daniel Rakos)

    • Updated spec against latest core API header version.

  • Revision 14, 2015-08-20 (Ian Elliott)

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

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

    • Did miscellaneous cleanup, etc.

  • Revision 15, 2015-08-20 (Ian Elliott—​porting a 2015-07-29 change from James Jones)

    • Moved the surface transform enums here from VK_WSI_swapchain so they could be re-used by VK_WSI_display.

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

    • Restore single-field revision number.

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

    • Fix example code compilation errors.

  • Revision 18, 2015-09-26 (Jesse Hall)

    • Replaced VkSurfaceDescriptionKHR with the VkSurfaceKHR object, which is created via layered extensions. Added VkDestroySurfaceKHR.

  • Revision 19, 2015-09-28 (Jesse Hall)

    • Renamed from VK_EXT_KHR_swapchain to VK_EXT_KHR_surface.

  • Revision 20, 2015-09-30 (Jeff Vigil)

    • Add error result VK_ERROR_SURFACE_LOST_KHR.

  • Revision 21, 2015-10-15 (Daniel Rakos)

    • Updated the resolution of issue #2 and include the surface capability queries in this extension.

    • Renamed SurfaceProperties to SurfaceCapabilities as it better reflects that the values returned are the capabilities of the surface on a particular device.

    • Other minor cleanup and consistency changes.

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

    • Renamed from VK_EXT_KHR_surface to VK_KHR_surface.

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

    • Added allocation callbacks to vkDestroySurfaceKHR.

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

    • Removed VkSurfaceTransformKHR. Use VkSurfaceTransformFlagBitsKHR instead.

    • Rename VkSurfaceCapabilitiesKHR member maxImageArraySize to maxImageArrayLayers.

  • Revision 25, 2016-01-14 (James Jones)

    • Moved VK_ERROR_NATIVE_WINDOW_IN_USE_KHR from the VK_KHR_android_surface to the VK_KHR_surface extension.

  • 2016-08-23 (Ian Elliott)

    • Update the example code, to not have so many characters per line, and to split out a new example to show how to obtain function pointers.

  • 2016-08-25 (Ian Elliott)

    • A note was added at the beginning of the example code, stating that it will be removed from future versions of the appendix.

VK_KHR_surface_protected_capabilities

Name String

VK_KHR_surface_protected_capabilities

Extension Type

Instance extension

Registered Extension Number

240

Revision

1

Extension and Version Dependencies
Contact

Other Extension Metadata

Last Modified Date

2018-12-18

IP Status

No known IP claims.

Contributors
  • Sandeep Shinde, NVIDIA

  • James Jones, NVIDIA

  • Daniel Koch, NVIDIA

Description

This extension extends VkSurfaceCapabilities2KHR, providing applications a way to query whether swapchains can be created with the VK_SWAPCHAIN_CREATE_PROTECTED_BIT_KHR flag set.

Vulkan 1.1 added (optional) support for protect memory and protected resources including buffers (VK_BUFFER_CREATE_PROTECTED_BIT), images (VK_IMAGE_CREATE_PROTECTED_BIT), and swapchains (VK_SWAPCHAIN_CREATE_PROTECTED_BIT_KHR). However, on implementations which support multiple windowing systems, not all window systems may be able to provide a protected display path.

This extension provides a way to query if a protected swapchain created for a surface (and thus a specific windowing system) can be displayed on screen. It extends the existing VkSurfaceCapabilities2KHR structure with a new VkSurfaceProtectedCapabilitiesKHR structure from which the application can obtain information about support for protected swapchain creation through vkGetPhysicalDeviceSurfaceCapabilities2KHR.

New Enum Constants

  • VK_KHR_SURFACE_PROTECTED_CAPABILITIES_EXTENSION_NAME

  • VK_KHR_SURFACE_PROTECTED_CAPABILITIES_SPEC_VERSION

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_SURFACE_PROTECTED_CAPABILITIES_KHR

Version History

  • Revision 1, 2018-12-18 (Sandeep Shinde, Daniel Koch)

    • Internal revisions.

VK_KHR_swapchain

Name String

VK_KHR_swapchain

Extension Type

Device extension

Registered Extension Number

2

Revision

70

Extension and Version Dependencies
Contact

Other Extension Metadata

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

Description

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

  • VK_KHR_SWAPCHAIN_EXTENSION_NAME

  • VK_KHR_SWAPCHAIN_SPEC_VERSION

  • Extending VkImageLayout:

    • VK_IMAGE_LAYOUT_PRESENT_SRC_KHR

  • Extending VkObjectType:

    • VK_OBJECT_TYPE_SWAPCHAIN_KHR

  • Extending VkResult:

    • VK_ERROR_OUT_OF_DATE_KHR

    • VK_SUBOPTIMAL_KHR

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_PRESENT_INFO_KHR

    • VK_STRUCTURE_TYPE_SWAPCHAIN_CREATE_INFO_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_swapchain_mutable_format

Name String

VK_KHR_swapchain_mutable_format

Extension Type

Device extension

Registered Extension Number

201

Revision

1

Extension and Version Dependencies
Contact

Other Extension Metadata

Last Modified Date

2018-03-28

IP Status

No known IP claims.

Contributors
  • Jason Ekstrand, Intel

  • Jan-Harald Fredriksen, ARM

  • Jesse Hall, Google

  • Daniel Rakos, AMD

  • Ray Smith, ARM

Description

This extension allows processing of swapchain images as different formats to that used by the window system, which is particularly useful for switching between sRGB and linear RGB formats.

It adds a new swapchain creation flag that enables creating image views from presentable images with a different format than the one used to create the swapchain.

New Enum Constants

  • VK_KHR_SWAPCHAIN_MUTABLE_FORMAT_EXTENSION_NAME

  • VK_KHR_SWAPCHAIN_MUTABLE_FORMAT_SPEC_VERSION

  • Extending VkSwapchainCreateFlagBitsKHR:

    • VK_SWAPCHAIN_CREATE_MUTABLE_FORMAT_BIT_KHR

Issues

1) Are there any new capabilities needed?

RESOLVED: No. It is expected that all implementations exposing this extension support swapchain image format mutability.

2) Do we need a separate VK_SWAPCHAIN_CREATE_EXTENDED_USAGE_BIT_KHR?

RESOLVED: No. This extension requires VK_KHR_maintenance2 and presentable images of swapchains created with VK_SWAPCHAIN_CREATE_MUTABLE_FORMAT_BIT_KHR are created internally in a way equivalent to specifying both VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT and VK_IMAGE_CREATE_EXTENDED_USAGE_BIT_KHR.

3) Do we need a separate structure to allow specifying an image format list for swapchains?

RESOLVED: No. We simply use the same VkImageFormatListCreateInfoKHR structure introduced by VK_KHR_image_format_list. The structure is required to be included in the pNext chain of VkSwapchainCreateInfoKHR for swapchains created with VK_SWAPCHAIN_CREATE_MUTABLE_FORMAT_BIT_KHR.

Version History

  • Revision 1, 2018-03-28 (Daniel Rakos)

    • Internal revisions.

VK_KHR_timeline_semaphore

Name String

VK_KHR_timeline_semaphore

Extension Type

Device extension

Registered Extension Number

208

Revision

2

Extension and Version Dependencies
Deprecation state
  • Promoted to Vulkan 1.2

Contact

Other Extension Metadata

Last Modified Date

2019-06-12

IP Status

No known IP claims.

Interactions and External Dependencies
Contributors
  • Jeff Bolz, NVIDIA

  • Yuriy O’Donnell, Epic Games

  • Jason Ekstrand, Intel

  • Jesse Hall, Google

  • James Jones, NVIDIA

  • Jeff Juliano, NVIDIA

  • Daniel Rakos, AMD

  • Ray Smith, Arm

Description

This extension introduces a new type of semaphore that has an integer payload identifying a point in a timeline. Such timeline semaphores support the following operations:

  • Host query - A host operation that allows querying the payload of the timeline semaphore.

  • Host wait - A host operation that allows a blocking wait for a timeline semaphore to reach a specified value.

  • Host signal - A host operation that allows advancing the timeline semaphore to a specified value.

  • Device wait - A device operation that allows waiting for a timeline semaphore to reach a specified value.

  • Device signal - A device operation that allows advancing the timeline semaphore to a specified value.

Promotion to Vulkan 1.2

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

New Enum Constants

  • VK_KHR_TIMELINE_SEMAPHORE_EXTENSION_NAME

  • VK_KHR_TIMELINE_SEMAPHORE_SPEC_VERSION

  • Extending VkSemaphoreType:

    • VK_SEMAPHORE_TYPE_BINARY_KHR

    • VK_SEMAPHORE_TYPE_TIMELINE_KHR

  • Extending VkSemaphoreWaitFlagBits:

    • VK_SEMAPHORE_WAIT_ANY_BIT_KHR

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_TIMELINE_SEMAPHORE_FEATURES_KHR

    • VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_TIMELINE_SEMAPHORE_PROPERTIES_KHR

    • VK_STRUCTURE_TYPE_SEMAPHORE_SIGNAL_INFO_KHR

    • VK_STRUCTURE_TYPE_SEMAPHORE_TYPE_CREATE_INFO_KHR

    • VK_STRUCTURE_TYPE_SEMAPHORE_WAIT_INFO_KHR

    • VK_STRUCTURE_TYPE_TIMELINE_SEMAPHORE_SUBMIT_INFO_KHR

Issues

1) Do we need a new object type for this?

RESOLVED: No, we just introduce a new type of semaphore object, as VK_KHR_external_semaphore_win32 already uses semaphores as the destination for importing D3D12 fence objects, which are semantically close/identical to the proposed synchronization primitive.

2) What type of payload the new synchronization primitive has?

RESOLVED: A 64-bit unsigned integer that can only be set to monotonically increasing values by signal operations and is not changed by wait operations.

3) Does the new synchronization primitive have the same signal-before-wait requirement as the existing semaphores do?

RESOLVED: No. Timeline semaphores support signaling and waiting entirely asynchronously. It is the responsibility of the client to avoid deadlock.

4) Does the new synchronization primitive allow resetting its payload?

RESOLVED: No, allowing the payload value to "go backwards" is problematic. Applications looking for reset behavior should create a new instance of the sychronization primitive instead.

5) How do we enable host waits on the synchronization primitive?

RESOLVED: Both a non-blocking query of the current payload value of the synchronization primitive, and a blocking wait operation are provided.

6) How do we enable device waits and signals on the synchronization primitive?

RESOLVED: Similar to VK_KHR_external_semaphore_win32, this extension introduces a new structure that can be chained to VkSubmitInfo to specify the values signaled semaphores should be set to, and the values waited semaphores need to reach.

7) Can the new synchronization primitive be used to synchronize presentation and swapchain image acquisition operations?

RESOLVED: Some implementations may have problems with supporting that directly, thus it’s not allowed in this extension.

8) Do we want to support external sharing of the new synchronization primitive type?

RESOLVED: Yes. Timeline semaphore specific external sharing capabilities can be queried using vkGetPhysicalDeviceExternalSemaphoreProperties by chaining the new VkSemaphoreTypeCreateInfoKHR structure to its pExternalSemaphoreInfo structure. This allows having a different set of external semaphore handle types supported for timeline semaphores vs binary semaphores.

9) Do we need to add a host signal operation for the new synchronization primitive type?

RESOLVED: Yes. This helps in situations where one host thread submits a workload but another host thread has the information on when the workload is ready to be executed.

10) How should the new synchronization primitive interact with the ordering requirements of the original VkSemaphore?

RESOLVED: Prior to calling any command which may cause a wait operation on a binary semaphore, the client must ensure that the semaphore signal operation that has been submitted for execution and any semaphore signal operations on which it depends (if any) must have also been submitted for execution.

11) Should we have separate feature bits for different sub-features of timeline semaphores?

RESOLVED: No. The only feature which cannot be supported universally is timeline semaphore import/export. For import/export, the client is already required to query available external handle types via vkGetPhysicalDeviceExternalSemaphoreProperties and provide the semaphore type by adding a VkSemaphoreTypeCreateInfoKHR structure to the pNext chain of VkPhysicalDeviceExternalSemaphoreInfo so no new feature bit is required.

Version History

  • Revision 1, 2018-05-10 (Jason Ekstrand)

    • Initial version

  • Revision 2, 2019-06-12 (Jason Ekstrand)

    • Added an initialValue parameter to timeline semaphore creation

VK_KHR_uniform_buffer_standard_layout

Name String

VK_KHR_uniform_buffer_standard_layout

Extension Type

Device extension

Registered Extension Number

254

Revision

1

Extension and Version Dependencies
Deprecation state
  • Promoted to Vulkan 1.2

Contact

Other Extension Metadata

Last Modified Date

2019-01-25

Interactions and External Dependencies
  • Promoted to Vulkan 1.2 Core

Contributors
  • Graeme Leese, Broadcom

  • Jeff Bolz, NVIDIA

  • Tobias Hector, AMD

  • Jason Ekstrand, Intel

  • Neil Henning, AMD

Description

This extension enables tighter array and struct packing to be used with uniform buffers.

It modifies the alignment rules for uniform buffers, allowing for tighter packing of arrays and structures. This allows, for example, the std430 layout, as defined in GLSL to be supported in uniform buffers.

Promotion to Vulkan 1.2

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

New Enum Constants

  • VK_KHR_UNIFORM_BUFFER_STANDARD_LAYOUT_EXTENSION_NAME

  • VK_KHR_UNIFORM_BUFFER_STANDARD_LAYOUT_SPEC_VERSION

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_UNIFORM_BUFFER_STANDARD_LAYOUT_FEATURES_KHR

Version History

  • Revision 1, 2019-01-25 (Graeme Leese)

    • 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
  • Promoted to Vulkan 1.1

Contact

Other Extension Metadata

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

Description

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.

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.

New Enum Constants

  • VK_KHR_VARIABLE_POINTERS_EXTENSION_NAME

  • VK_KHR_VARIABLE_POINTERS_SPEC_VERSION

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VARIABLE_POINTERS_FEATURES_KHR

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_KHR_vulkan_memory_model

Name String

VK_KHR_vulkan_memory_model

Extension Type

Device extension

Registered Extension Number

212

Revision

3

Extension and Version Dependencies
  • Requires Vulkan 1.0

Deprecation state
  • Promoted to Vulkan 1.2

Contact

Other Extension Metadata

Last Modified Date

2018-12-10

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

Description

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.

Note

Version 3 of the spec added a member (vulkanMemoryModelAvailabilityVisibilityChains) to VkPhysicalDeviceVulkanMemoryModelFeaturesKHR, which is an incompatible change from version 2.

Promotion to Vulkan 1.2

All functionality in this extension is included in core Vulkan 1.2, with the KHR suffix omitted. However, if Vulkan 1.2 is supported and this extension is not, the vulkanMemoryModel capability is optional. The original type, enum and command names are still available as aliases of the core functionality.

New Enum Constants

  • VK_KHR_VULKAN_MEMORY_MODEL_EXTENSION_NAME

  • VK_KHR_VULKAN_MEMORY_MODEL_SPEC_VERSION

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VULKAN_MEMORY_MODEL_FEATURES_KHR

New SPIR-V Capabilities

Version History

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

    • Initial draft

  • Revision 3, 2018-12-10 (Jeff Bolz)

    • Add vulkanMemoryModelAvailabilityVisibilityChains member to the VkPhysicalDeviceVulkanMemoryModelFeaturesKHR structure.

VK_KHR_wayland_surface

Name String

VK_KHR_wayland_surface

Extension Type

Instance extension

Registered Extension Number

7

Revision

6

Extension and Version Dependencies
Contact

Other Extension Metadata

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

Description

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

  • VK_KHR_WAYLAND_SURFACE_EXTENSION_NAME

  • VK_KHR_WAYLAND_SURFACE_SPEC_VERSION

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_WAYLAND_SURFACE_CREATE_INFO_KHR

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

Other Extension Metadata

Last Modified Date

2016-10-21

IP Status

No known IP claims.

Contributors
  • James Jones, NVIDIA

  • Jeff Juliano, NVIDIA

  • Carsten Rohde, NVIDIA

Description

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

  • VK_KHR_WIN32_KEYED_MUTEX_EXTENSION_NAME

  • VK_KHR_WIN32_KEYED_MUTEX_SPEC_VERSION

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_WIN32_KEYED_MUTEX_ACQUIRE_RELEASE_INFO_KHR

Version History

  • Revision 1, 2016-10-21 (James Jones)

    • Initial revision

VK_KHR_win32_surface

Name String

VK_KHR_win32_surface

Extension Type

Instance extension

Registered Extension Number

10

Revision

6

Extension and Version Dependencies
Contact

Other Extension Metadata

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

Description

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

  • VK_KHR_WIN32_SURFACE_EXTENSION_NAME

  • VK_KHR_WIN32_SURFACE_SPEC_VERSION

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_WIN32_SURFACE_CREATE_INFO_KHR

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

Other Extension Metadata

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

Description

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 Structures

New Enum Constants

  • VK_KHR_XCB_SURFACE_EXTENSION_NAME

  • VK_KHR_XCB_SURFACE_SPEC_VERSION

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_XCB_SURFACE_CREATE_INFO_KHR

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

Other Extension Metadata

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

Description

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

  • VK_KHR_XLIB_SURFACE_EXTENSION_NAME

  • VK_KHR_XLIB_SURFACE_SPEC_VERSION

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_XLIB_SURFACE_CREATE_INFO_KHR

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

Other Extension Metadata

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

Description

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

  • VK_EXT_ACQUIRE_XLIB_DISPLAY_EXTENSION_NAME

  • VK_EXT_ACQUIRE_XLIB_DISPLAY_SPEC_VERSION

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

Other Extension Metadata

Last Modified Date

2018-08-07

Contributors
  • Jan-Harald Fredriksen, Arm

Description

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

  • VK_EXT_ASTC_DECODE_MODE_EXTENSION_NAME

  • VK_EXT_ASTC_DECODE_MODE_SPEC_VERSION

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_IMAGE_VIEW_ASTC_DECODE_MODE_EXT

    • VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_ASTC_DECODE_FEATURES_EXT

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

Other Extension Metadata

Last Modified Date

2017-06-12

Contributors
  • Jeff Bolz, NVIDIA

Description

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 Enums

New Enum Constants

  • VK_EXT_BLEND_OPERATION_ADVANCED_EXTENSION_NAME

  • VK_EXT_BLEND_OPERATION_ADVANCED_SPEC_VERSION

  • Extending VkAccessFlagBits:

    • VK_ACCESS_COLOR_ATTACHMENT_READ_NONCOHERENT_BIT_EXT

  • Extending VkBlendOp:

    • VK_BLEND_OP_BLUE_EXT

    • VK_BLEND_OP_COLORBURN_EXT

    • VK_BLEND_OP_COLORDODGE_EXT

    • VK_BLEND_OP_CONTRAST_EXT

    • VK_BLEND_OP_DARKEN_EXT

    • VK_BLEND_OP_DIFFERENCE_EXT

    • VK_BLEND_OP_DST_ATOP_EXT

    • VK_BLEND_OP_DST_EXT

    • VK_BLEND_OP_DST_IN_EXT

    • VK_BLEND_OP_DST_OUT_EXT

    • VK_BLEND_OP_DST_OVER_EXT

    • VK_BLEND_OP_EXCLUSION_EXT

    • VK_BLEND_OP_GREEN_EXT

    • VK_BLEND_OP_HARDLIGHT_EXT

    • VK_BLEND_OP_HARDMIX_EXT

    • VK_BLEND_OP_HSL_COLOR_EXT

    • VK_BLEND_OP_HSL_HUE_EXT

    • VK_BLEND_OP_HSL_LUMINOSITY_EXT

    • VK_BLEND_OP_HSL_SATURATION_EXT

    • VK_BLEND_OP_INVERT_EXT

    • VK_BLEND_OP_INVERT_OVG_EXT

    • VK_BLEND_OP_INVERT_RGB_EXT

    • VK_BLEND_OP_LIGHTEN_EXT

    • VK_BLEND_OP_LINEARBURN_EXT

    • VK_BLEND_OP_LINEARDODGE_EXT

    • VK_BLEND_OP_LINEARLIGHT_EXT

    • VK_BLEND_OP_MINUS_CLAMPED_EXT

    • VK_BLEND_OP_MINUS_EXT

    • VK_BLEND_OP_MULTIPLY_EXT

    • VK_BLEND_OP_OVERLAY_EXT

    • VK_BLEND_OP_PINLIGHT_EXT

    • VK_BLEND_OP_PLUS_CLAMPED_ALPHA_EXT

    • VK_BLEND_OP_PLUS_CLAMPED_EXT

    • VK_BLEND_OP_PLUS_DARKER_EXT

    • VK_BLEND_OP_PLUS_EXT

    • VK_BLEND_OP_RED_EXT

    • VK_BLEND_OP_SCREEN_EXT

    • VK_BLEND_OP_SOFTLIGHT_EXT

    • VK_BLEND_OP_SRC_ATOP_EXT

    • VK_BLEND_OP_SRC_EXT

    • VK_BLEND_OP_SRC_IN_EXT

    • VK_BLEND_OP_SRC_OUT_EXT

    • VK_BLEND_OP_SRC_OVER_EXT

    • VK_BLEND_OP_VIVIDLIGHT_EXT

    • VK_BLEND_OP_XOR_EXT

    • VK_BLEND_OP_ZERO_EXT

  • 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

Issues

None.

Version History

  • Revision 1, 2017-06-12 (Jeff Bolz)

    • Internal revisions

  • Revision 2, 2017-06-12 (Jeff Bolz)

    • Internal revisions

VK_EXT_calibrated_timestamps

Name String

VK_EXT_calibrated_timestamps

Extension Type

Device extension

Registered Extension Number

185

Revision

1

Extension and Version Dependencies
  • Requires Vulkan 1.0

Contact

Other Extension Metadata

Last Modified Date

2018-10-04

IP Status

No known IP claims.

Contributors
  • Matthaeus G. Chajdas, AMD

  • Alan Harrison, AMD

  • Derrick Owens, AMD

  • Daniel Rakos, AMD

  • Jason Ekstrand, Intel

  • Keith Packard, Valve

Description

This extension provides an interface to query calibrated timestamps obtained quasi simultaneously from two time domains.

New Enums

New Enum Constants

  • VK_EXT_CALIBRATED_TIMESTAMPS_EXTENSION_NAME

  • VK_EXT_CALIBRATED_TIMESTAMPS_SPEC_VERSION

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_CALIBRATED_TIMESTAMP_INFO_EXT

Issues

1) Is the device timestamp value returned in the same time domain as the timestamp values written by vkCmdWriteTimestamp?

RESOLVED: Yes.

2) What time domain is the host timestamp returned in?

RESOLVED: A query is provided to determine the calibrateable time domains. The expected host time domain used on Windows is that of QueryPerformanceCounter, and on Linux that of CLOCK_MONOTONIC.

3) Should we support other time domain combinations than just one host and the device time domain?

RESOLVED: Supporting that would need the application to query the set of supported time domains, while supporting only one host and the device time domain would only need a query for the host time domain type. The proposed API chooses the general approach for the sake of extensibility.

4) Shouldn’t we use CLOCK_MONOTONIC_RAW instead of CLOCK_MONOTONIC?

RESOLVED: CLOCK_MONOTONIC is usable in a wider set of situations, however, it is subject to NTP adjustments so some use cases may prefer CLOCK_MONOTONIC_RAW. Thus this extension allows both to be exposed.

5) How can the application extrapolate future device timestamp values from the calibrated timestamp value?

RESOLVED: VkPhysicalDeviceLimits::timestampPeriod makes it possible to calculate future device timestamps as follows:

futureTimestamp = calibratedTimestamp + deltaNanoseconds / timestampPeriod

6) Can the host and device timestamp values drift apart over longer periods of time?

RESOLVED: Yes, especially as some time domains by definition allow for that to happen (e.g. CLOCK_MONOTONIC is subject to NTP adjustments). Thus it’s recommended that applications re-calibrate from time to time.

7) Should we add a query for reporting the maximum deviation of the timestamp values returned by calibrated timestamp queries?

RESOLVED: A global query seems inappropriate and difficult to enforce. However, it’s possible to return the maximum deviation any single calibrated timestamp query can have by sampling one of the time domains twice as follows:

timestampX = timestampX_before = SampleTimeDomain(X)
for each time domain Y != X
    timestampY = SampleTimeDomain(Y)
timestampX_after = SampleTimeDomain(X)
maxDeviation = timestampX_after - timestampX_before

8) Can the maximum deviation reported ever be zero?

RESOLVED: Unless the tick of each clock corresponding to the set of time domains coincides and all clocks can literally be sampled simutaneously, there isn’t really a possibility for the maximum deviation to be zero, so by convention the maximum deviation is always at least the maximum of the length of the ticks of the set of time domains calibrated and thus can never be zero.

Version History

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

    • Internal revisions.

VK_EXT_conditional_rendering

Name String

VK_EXT_conditional_rendering

Extension Type

Device extension

Registered Extension Number

82

Revision

2

Extension and Version Dependencies
  • Requires Vulkan 1.0

Contact

Other Extension Metadata

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

Description

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

  • VK_EXT_CONDITIONAL_RENDERING_EXTENSION_NAME

  • VK_EXT_CONDITIONAL_RENDERING_SPEC_VERSION

  • 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

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_COMMAND_BUFFER_INHERITANCE_CONDITIONAL_RENDERING_INFO_EXT

    • VK_STRUCTURE_TYPE_CONDITIONAL_RENDERING_BEGIN_INFO_EXT

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

Other Extension Metadata

Last Modified Date

2017-08-28

Contributors
  • Daniel Koch, NVIDIA

  • Daniel Rakos, AMD

  • Jeff Bolz, NVIDIA

  • Slawomir Grajewski, Intel

  • Stu Smith, Imagination Technologies

Description

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

  • VK_EXT_CONSERVATIVE_RASTERIZATION_EXTENSION_NAME

  • VK_EXT_CONSERVATIVE_RASTERIZATION_SPEC_VERSION

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_CONSERVATIVE_RASTERIZATION_PROPERTIES_EXT

    • VK_STRUCTURE_TYPE_PIPELINE_RASTERIZATION_CONSERVATIVE_STATE_CREATE_INFO_EXT

Version History

  • Revision 1, 2017-08-28 (Piers Daniell)

    • Internal revisions

VK_EXT_custom_border_color

Name String

VK_EXT_custom_border_color

Extension Type

Device extension

Registered Extension Number

288

Revision

12

Extension and Version Dependencies
  • Requires Vulkan 1.0

Contact

Other Extension Metadata

Last Modified Date

2020-04-16

IP Status

No known IP claims.

Contributors
  • Joshua Ashton, Valve

  • Hans-Kristian Arntzen, Valve

  • Philip Rebohle, Valve

  • Liam Middlebrook, NVIDIA

  • Jeff Bolz, NVIDIA

  • Tobias Hector, AMD

  • Jason Ekstrand, Intel

  • Spencer Fricke, Samsung Electronics

  • Graeme Leese, Broadcom

  • Jesse Hall, Google

  • Jan-Harald Fredriksen, ARM

  • Tom Olson, ARM

  • Stuart Smith, Imagination Technologies

  • Donald Scorgie, Imagination Technologies

  • Alex Walters, Imagination Technologies

  • Peter Quayle, Imagination Technologies

Description

This extension provides cross-vendor functionality to specify a custom border color for use when the sampler address mode VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_BORDER is used.

To create a sampler which uses a custom border color set VkSamplerCreateInfo::borderColor to one of:

  • VK_BORDER_COLOR_FLOAT_CUSTOM_EXT

  • VK_BORDER_COLOR_INT_CUSTOM_EXT

When VK_BORDER_COLOR_FLOAT_CUSTOM_EXT or VK_BORDER_COLOR_INT_CUSTOM_EXT is used, applications must provide a VkSamplerCustomBorderColorCreateInfoEXT in the pNext chain for VkSamplerCreateInfo.

New Enum Constants

  • VK_EXT_CUSTOM_BORDER_COLOR_EXTENSION_NAME

  • VK_EXT_CUSTOM_BORDER_COLOR_SPEC_VERSION

  • Extending VkBorderColor:

    • VK_BORDER_COLOR_FLOAT_CUSTOM_EXT

    • VK_BORDER_COLOR_INT_CUSTOM_EXT

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_CUSTOM_BORDER_COLOR_FEATURES_EXT

    • VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_CUSTOM_BORDER_COLOR_PROPERTIES_EXT

    • VK_STRUCTURE_TYPE_SAMPLER_CUSTOM_BORDER_COLOR_CREATE_INFO_EXT

Issues

1) Should VkClearColorValue be used for the border color value, or should we have our own struct/union? Do we need to specify the type of the input values for the components? This is more of a concern if VkClearColorValue is used here because it provides a union of float,int,uint types.

RESOLVED: Will re-use existing VkClearColorValue structure in order to easily take advantage of float,int,uint borderColor types.

2) For hardware which supports a limited number of border colors what happens if that number is exceeded? Should this be handled by the driver unbeknownst to the application? In Revision 1 we had solved this issue using a new Object type, however that may have lead to additional system resource consumption which would otherwise not be required.

RESOLVED: Added VkPhysicalDeviceCustomBorderColorPropertiesEXT::maxCustomBorderColorSamplers for tracking implementation-specific limit, and Valid Usage statement handling overflow.

3) Should this be supported for immutable samplers at all, or by a feature bit? Some implementations may not be able to support custom border colors on immutable samplers — is it worthwhile enabling this to work on them for implementations that can support it, or forbidding it entirely.

RESOLVED: Samplers created with a custom border color are forbidden from being immutable. This resolves concerns for implementations where the custom border color is an index to a LUT instead of being directly embedded into sampler state.

4) Should UINT and SINT (unsigned integer and signed integer) border color types be separated or should they be combined into one generic INT (integer) type?

RESOLVED: Separating these doesn’t make much sense as the existing fixed border color types don’t have this distinction, and there is no reason in hardware to do so. This separation would also create unnecessary work and considerations for the application.

Version History

  • Revision 1, 2019-10-10 (Joshua Ashton)

    • Internal revisions.

  • Revision 2, 2019-10-11 (Liam Middlebrook)

    • Remove VkCustomBorderColor object and associated functions

    • Add issues concerning HW limitations for custom border color count

  • Revision 3, 2019-10-12 (Joshua Ashton)

    • Re-expose the limits for the maximum number of unique border colors

    • Add extra details about border color tracking

    • Fix typos

  • Revision 4, 2019-10-12 (Joshua Ashton)

    • Changed maxUniqueCustomBorderColors to a uint32_t from a VkDeviceSize

  • Revision 5, 2019-10-14 (Liam Middlebrook)

    • Added features bit

  • Revision 6, 2019-10-15 (Joshua Ashton)

    • Type-ize VK_BORDER_COLOR_CUSTOM

    • Fix const-ness on pNext of VkSamplerCustomBorderColorCreateInfoEXT

  • Revision 7, 2019-11-26 (Liam Middlebrook)

    • Renamed maxUniqueCustomBorderColors to maxCustomBorderColors

  • Revision 8, 2019-11-29 (Joshua Ashton)

    • Renamed borderColor member of VkSamplerCustomBorderColorCreateInfoEXT to customBorderColor

  • Revision 9, 2020-02-19 (Joshua Ashton)

    • Renamed maxCustomBorderColors to maxCustomBorderColorSamplers

  • Revision 10, 2020-02-21 (Joshua Ashton)

    • Added format to VkSamplerCustomBorderColorCreateInfoEXT and feature bit

  • Revision 11, 2020-04-07 (Joshua Ashton)

    • Dropped UINT/SINT border color differences, consolidated types

  • Revision 12, 2020-04-16 (Joshua Ashton)

    • Renamed VK_BORDER_COLOR_CUSTOM_FLOAT_EXT to VK_BORDER_COLOR_FLOAT_CUSTOM_EXT for consistency

VK_EXT_debug_utils

Name String

VK_EXT_debug_utils

Extension Type

Instance extension

Registered Extension Number

129

Revision

2

Extension and Version Dependencies
  • Requires Vulkan 1.0

Contact

Other Extension Metadata

Last Modified Date

2020-04-03

Revision

2

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

  • Piers Daniell, NVIDIA

Description

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

New Enum Constants

  • VK_EXT_DEBUG_UTILS_EXTENSION_NAME

  • VK_EXT_DEBUG_UTILS_SPEC_VERSION

  • Extending VkObjectType:

    • VK_OBJECT_TYPE_DEBUG_UTILS_MESSENGER_EXT

  • Extending VkStructureType:

    • 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

    • VK_STRUCTURE_TYPE_DEBUG_UTILS_OBJECT_NAME_INFO_EXT

    • VK_STRUCTURE_TYPE_DEBUG_UTILS_OBJECT_TAG_INFO_EXT

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)

  • Revision 2, 2020-04-03 (Mark Young and Piers Daniell)

    • Updated to allow either NULL or an empty string to be passed in for pObjectName in VkDebugUtilsObjectNameInfoEXT, because the loader and various drivers support NULL already.

VK_EXT_depth_clip_enable

Name String

VK_EXT_depth_clip_enable

Extension Type

Device extension

Registered Extension Number

103

Revision

1

Extension and Version Dependencies
  • Requires Vulkan 1.0

Contact

Other Extension Metadata

Last Modified Date

2018-12-20

Contributors
  • Daniel Rakos, AMD

  • Henri Verbeet, CodeWeavers

  • Jeff Bolz, NVIDIA

  • Philip Rebohle, DXVK

  • Tobias Hector, AMD

Description

This extension allows the depth clipping operation, that is normally implicitly controlled by VkPipelineRasterizationStateCreateInfo::depthClampEnable, to instead be controlled explicitly by VkPipelineRasterizationDepthClipStateCreateInfoEXT::depthClipEnable.

This is useful for translating DX content which assumes depth clamping is always enabled, but depth clip can be controlled by the DepthClipEnable rasterization state (D3D12_RASTERIZER_DESC).

New Enum Constants

  • VK_EXT_DEPTH_CLIP_ENABLE_EXTENSION_NAME

  • VK_EXT_DEPTH_CLIP_ENABLE_SPEC_VERSION

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DEPTH_CLIP_ENABLE_FEATURES_EXT

    • VK_STRUCTURE_TYPE_PIPELINE_RASTERIZATION_DEPTH_CLIP_STATE_CREATE_INFO_EXT

Version History

  • Revision 1, 2018-12-20 (Piers Daniell)

    • Internal revisions

VK_EXT_depth_range_unrestricted

Name String

VK_EXT_depth_range_unrestricted

Extension Type

Device extension

Registered Extension Number

14

Revision

1

Extension and Version Dependencies
  • Requires Vulkan 1.0

Contact

Other Extension Metadata

Last Modified Date

2017-06-22

Contributors
  • Daniel Koch, NVIDIA

  • Jeff Bolz, NVIDIA

Description

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

  • VK_EXT_DEPTH_RANGE_UNRESTRICTED_EXTENSION_NAME

  • VK_EXT_DEPTH_RANGE_UNRESTRICTED_SPEC_VERSION

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
Deprecation state
  • Promoted to Vulkan 1.2

Contact

Other Extension Metadata

Last Modified Date

2017-10-02

Interactions and External Dependencies
  • Promoted to Vulkan 1.2 Core

Contributors
  • Jeff Bolz, NVIDIA

  • Daniel Rakos, AMD

  • Slawomir Grajewski, Intel

  • Tobias Hector, Imagination Technologies

Description

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

  • VK_EXT_DESCRIPTOR_INDEXING_EXTENSION_NAME

  • VK_EXT_DESCRIPTOR_INDEXING_SPEC_VERSION

  • Extending VkDescriptorBindingFlagBits:

    • VK_DESCRIPTOR_BINDING_PARTIALLY_BOUND_BIT_EXT

    • VK_DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BIT_EXT

    • VK_DESCRIPTOR_BINDING_UPDATE_UNUSED_WHILE_PENDING_BIT_EXT

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

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_DESCRIPTOR_SET_LAYOUT_BINDING_FLAGS_CREATE_INFO_EXT

    • VK_STRUCTURE_TYPE_DESCRIPTOR_SET_VARIABLE_DESCRIPTOR_COUNT_ALLOCATE_INFO_EXT

    • VK_STRUCTURE_TYPE_DESCRIPTOR_SET_VARIABLE_DESCRIPTOR_COUNT_LAYOUT_SUPPORT_EXT

    • VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DESCRIPTOR_INDEXING_FEATURES_EXT

    • VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DESCRIPTOR_INDEXING_PROPERTIES_EXT

Promotion to Vulkan 1.2

Functionality in this extension is included in core Vulkan 1.2, with the EXT suffix omitted. However, if Vulkan 1.2 is supported and this extension is not, the descriptorIndexing capability is optional. The original type, enum and command names are still available as aliases of the core functionality.

Version History

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

    • Internal revisions

  • Revision 2, 2017-10-02 (Jeff Bolz)

    • ???

VK_EXT_direct_mode_display

Name String

VK_EXT_direct_mode_display

Extension Type

Instance extension

Registered Extension Number

89

Revision

1

Extension and Version Dependencies
Contact

Other Extension Metadata

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

Description

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 Commands

New Enum Constants

  • VK_EXT_DIRECT_MODE_DISPLAY_EXTENSION_NAME

  • VK_EXT_DIRECT_MODE_DISPLAY_SPEC_VERSION

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

Other Extension Metadata

Last Modified Date

2016-12-22

Interactions and External Dependencies
Contributors
  • Daniel Koch, NVIDIA

  • Jeff Bolz, NVIDIA

Description

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

  • VK_EXT_DISCARD_RECTANGLES_EXTENSION_NAME

  • VK_EXT_DISCARD_RECTANGLES_SPEC_VERSION

  • Extending VkDynamicState:

    • VK_DYNAMIC_STATE_DISCARD_RECTANGLE_EXT

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DISCARD_RECTANGLE_PROPERTIES_EXT

    • VK_STRUCTURE_TYPE_PIPELINE_DISCARD_RECTANGLE_STATE_CREATE_INFO_EXT

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

Other Extension Metadata

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

Description

This extension defines a set of utility functions for use with the VK_KHR_display and VK_KHR_display_swapchain extensions.

New Enum Constants

  • VK_EXT_DISPLAY_CONTROL_EXTENSION_NAME

  • VK_EXT_DISPLAY_CONTROL_SPEC_VERSION

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_DEVICE_EVENT_INFO_EXT

    • VK_STRUCTURE_TYPE_DISPLAY_EVENT_INFO_EXT

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

Other Extension Metadata

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

Description

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

New Enum Constants

  • VK_EXT_DISPLAY_SURFACE_COUNTER_EXTENSION_NAME

  • VK_EXT_DISPLAY_SURFACE_COUNTER_SPEC_VERSION

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_SURFACE_CAPABILITIES_2_EXT

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

Other Extension Metadata

Last Modified Date

2017-10-10

IP Status

No known IP claims.

Contributors
  • Chad Versace, Google

  • James Jones, NVIDIA

  • Jason Ekstrand, Intel

Description

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

  • VK_EXT_EXTERNAL_MEMORY_DMA_BUF_EXTENSION_NAME

  • VK_EXT_EXTERNAL_MEMORY_DMA_BUF_SPEC_VERSION

  • Extending VkExternalMemoryHandleTypeFlagBits:

    • VK_EXTERNAL_MEMORY_HANDLE_TYPE_DMA_BUF_BIT_EXT

Issues

1) How does the application, when creating a VkImage that it intends to bind to dma_buf VkDeviceMemory containing an externally produced image, specify the memory layout (such as row pitch and DRM format modifier) of the VkImage? In other words, how does the application achieve behavior comparable to that provided by EGL_EXT_image_dma_buf_import and EGL_EXT_image_dma_buf_import_modifiers ?

RESOLVED: Features comparable to those in EGL_EXT_image_dma_buf_import and EGL_EXT_image_dma_buf_import_modifiers will be provided by an extension layered atop this one.

2) Without the ability to specify the memory layout of external dma_buf images, how is this extension useful?

RESOLVED: This extension provides exactly one new feature: the ability to import/export between dma_buf and VkDeviceMemory. This feature, together with features provided by VK_KHR_external_memory_fd, is sufficient to bind a VkBuffer to dma_buf.

Version History

  • Revision 1, 2017-10-10 (Chad Versace)

    • Squashed internal revisions

VK_EXT_external_memory_host

Name String

VK_EXT_external_memory_host

Extension Type

Device extension

Registered Extension Number

179

Revision

1

Extension and Version Dependencies
Contact

Other Extension Metadata

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

Description

This extension enables an application to import host allocations and host mapped foreign device memory to Vulkan memory objects.

New Enum Constants

  • VK_EXT_EXTERNAL_MEMORY_HOST_EXTENSION_NAME

  • VK_EXT_EXTERNAL_MEMORY_HOST_SPEC_VERSION

  • Extending VkExternalMemoryHandleTypeFlagBits:

    • VK_EXTERNAL_MEMORY_HANDLE_TYPE_HOST_ALLOCATION_BIT_EXT

    • VK_EXTERNAL_MEMORY_HANDLE_TYPE_HOST_MAPPED_FOREIGN_MEMORY_BIT_EXT

  • 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

Issues

1) What memory type has to be used to import host pointers?

RESOLVED: Depends on the implementation. Applications have to use the new vkGetMemoryHostPointerPropertiesEXT command to query the supported memory types for a particular host pointer. The reported memory types may include memory types that come from a memory heap that is otherwise not usable for regular memory object allocation and thus such a heap’s size may be zero.

2) Can the application still access the contents of the host allocation after importing?

RESOLVED: Yes. However, usual synchronization requirements apply.

3) Can the application free the host allocation?

RESOLVED: No, it violates valid usage conditions. Using the memory object imported from a host allocation that’s already freed thus results in undefined behavior.

4) Is vkMapMemory expected to return the same host address which was specified when importing it to the memory object?

RESOLVED: No. Implementations are allowed to return the same address but it’s not required. Some implementations might return a different virtual mapping of the allocation, although the same physical pages will be used.

5) Is there any limitation on the alignment of the host pointer and/or size?

RESOLVED: Yes. Both the address and the size have to be an integer multiple of minImportedHostPointerAlignment. In addition, some platforms and foreign devices may have additional restrictions.

6) Can the same host allocation be imported multiple times into a given physical device?

RESOLVED: No, at least not guaranteed by this extension. Some platforms do not allow locking the same physical pages for device access multiple times, so attempting to do it may result in undefined behavior.

7) Does this extension support exporting the new handle type?

RESOLVED: No.

8) Should we include the possibility to import host mapped foreign device memory using this API?

RESOLVED: Yes, through a separate handle type. Implementations are still allowed to support only one of the handle types introduced by this extension by not returning import support for a particular handle type as returned in VkExternalMemoryPropertiesKHR.

Version History

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

    • Internal revisions

VK_EXT_filter_cubic

Name String

VK_EXT_filter_cubic

Extension Type

Device extension

Registered Extension Number

171

Revision

3

Extension and Version Dependencies
Contact
  • Bill Licea-Kane wwlk

Other Extension Metadata

Last Modified Date

2019-12-13

Contributors
  • Bill Licea-Kane, Qualcomm Technologies, Inc.

  • Andrew Garrard, Samsung

  • Daniel Koch, NVIDIA

  • Donald Scorgie, Imagination Technologies

  • Graeme Leese, Broadcom

  • Jan-Herald Fredericksen, ARM

  • Jeff Leger, Qualcomm Technologies, Inc.

  • Tobias Hector, AMD

  • Tom Olson, ARM

  • Stuart Smith, Imagination Technologies

Description

VK_EXT_filter_cubic extends VK_IMG_filter_cubic.

It documents cubic filtering of other image view types. It adds new structures that can be added to the pNext chain of VkPhysicalDeviceImageFormatInfo2 and VkImageFormatProperties2 that can be used to determine which image types and which image view types support cubic filtering.

New Enum Constants

  • VK_EXT_FILTER_CUBIC_EXTENSION_NAME

  • VK_EXT_FILTER_CUBIC_SPEC_VERSION

  • Extending VkFilter:

    • VK_FILTER_CUBIC_EXT

  • Extending VkFormatFeatureFlagBits:

    • VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_CUBIC_BIT_EXT

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_FILTER_CUBIC_IMAGE_VIEW_IMAGE_FORMAT_PROPERTIES_EXT

    • VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGE_VIEW_IMAGE_FORMAT_INFO_EXT

Version History

  • Revision 3, 2019-12-13 (wwlk)

    • Delete requirement to cubic filter the formats USCALED_PACKED32, SSCALED_PACKED32, UINT_PACK32, and SINT_PACK32 (cut/paste error)

  • Revision 2, 2019-06-05 (wwlk)

    • Clarify 1D optional

  • Revision 1, 2019-01-24 (wwlk)

    • Initial version

VK_EXT_fragment_density_map

Name String

VK_EXT_fragment_density_map

Extension Type

Device extension

Registered Extension Number

219

Revision

1

Extension and Version Dependencies
Contact

Other Extension Metadata

Last Modified Date

2018-09-25

Interactions and External Dependencies
Contributors
  • Matthew Netsch, Qualcomm Technologies, Inc.

  • Robert VanReenen, Qualcomm Technologies, Inc.

  • Jonathan Wicks, Qualcomm Technologies, Inc.

  • Tate Hornbeck, Qualcomm Technologies, Inc.

  • Sam Holmes, Qualcomm Technologies, Inc.

  • Jeff Leger, Qualcomm Technologies, Inc.

  • Jan-Harald Fredriksen, ARM

  • Jeff Bolz, NVIDIA

  • Pat Brown, NVIDIA

  • Daniel Rakos, AMD

  • Piers Daniell, NVIDIA

Description

This extension allows an application to specify areas of the render target where the fragment shader may be invoked fewer times. These fragments are broadcasted out to multiple pixels to cover the render target.

The primary use of this extension is to reduce workloads in areas where lower quality may not be perceived such as the distorted edges of a lens or the periphery of a user’s gaze.

New Enum Constants

  • VK_EXT_FRAGMENT_DENSITY_MAP_EXTENSION_NAME

  • VK_EXT_FRAGMENT_DENSITY_MAP_SPEC_VERSION

  • Extending VkAccessFlagBits:

    • VK_ACCESS_FRAGMENT_DENSITY_MAP_READ_BIT_EXT

  • Extending VkFormatFeatureFlagBits:

    • VK_FORMAT_FEATURE_FRAGMENT_DENSITY_MAP_BIT_EXT

  • Extending VkImageCreateFlagBits:

    • VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT

  • Extending VkImageLayout:

    • VK_IMAGE_LAYOUT_FRAGMENT_DENSITY_MAP_OPTIMAL_EXT

  • Extending VkImageUsageFlagBits:

    • VK_IMAGE_USAGE_FRAGMENT_DENSITY_MAP_BIT_EXT

  • Extending VkImageViewCreateFlagBits:

    • VK_IMAGE_VIEW_CREATE_FRAGMENT_DENSITY_MAP_DYNAMIC_BIT_EXT

  • Extending VkPipelineStageFlagBits:

    • VK_PIPELINE_STAGE_FRAGMENT_DENSITY_PROCESS_BIT_EXT

  • Extending VkSamplerCreateFlagBits:

    • VK_SAMPLER_CREATE_SUBSAMPLED_BIT_EXT

    • VK_SAMPLER_CREATE_SUBSAMPLED_COARSE_RECONSTRUCTION_BIT_EXT

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FRAGMENT_DENSITY_MAP_FEATURES_EXT

    • VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FRAGMENT_DENSITY_MAP_PROPERTIES_EXT

    • VK_STRUCTURE_TYPE_RENDER_PASS_FRAGMENT_DENSITY_MAP_CREATE_INFO_EXT

New or Modified Built-In Variables

New SPIR-V Capabilities

Version History

  • Revision 1, 2018-09-25 (Matthew Netsch)

    • Initial version

VK_EXT_fragment_shader_interlock

Name String

VK_EXT_fragment_shader_interlock

Extension Type

Device extension

Registered Extension Number

252

Revision

1

Extension and Version Dependencies
Contact

Other Extension Metadata

Last Modified Date

2019-05-02

Interactions and External Dependencies
Contributors
  • Daniel Koch, NVIDIA

  • Graeme Leese, Broadcom

  • Jan-Harald Fredriksen, Arm

  • Jason Ekstrand, Intel

  • Jeff Bolz, NVIDIA

  • Ruihao Zhang, Qualcomm

  • Slawomir Grajewski, Intel

  • Spencer Fricke, Samsung

Description

This extension adds support for the FragmentShaderPixelInterlockEXT, FragmentShaderSampleInterlockEXT, and FragmentShaderShadingRateInterlockEXT capabilities from the SPV_EXT_fragment_shader_interlock extension to Vulkan.

Enabling these capabilities provides a critical section for fragment shaders to avoid overlapping pixels being processed at the same time, and certain guarantees about the ordering of fragment shader invocations of fragments of overlapping pixels.

This extension can be useful for algorithms that need to access per-pixel data structures via shader loads and stores. Algorithms using this extension can access per-pixel data structures in critical sections without other invocations accessing the same per-pixel data. Additionally, the ordering guarantees are useful for cases where the API ordering of fragments is meaningful. For example, applications may be able to execute programmable blending operations in the fragment shader, where the destination buffer is read via image loads and the final value is written via image stores.

New Enum Constants

  • VK_EXT_FRAGMENT_SHADER_INTERLOCK_EXTENSION_NAME

  • VK_EXT_FRAGMENT_SHADER_INTERLOCK_SPEC_VERSION

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FRAGMENT_SHADER_INTERLOCK_FEATURES_EXT

Version History

  • Revision 1, 2019-05-24 (Piers Daniell)

    • Internal revisions

VK_EXT_full_screen_exclusive

Name String

VK_EXT_full_screen_exclusive

Extension Type

Device extension

Registered Extension Number

256

Revision

4

Extension and Version Dependencies
Contact

Other Extension Metadata

Last Modified Date

2019-03-12

IP Status

No known IP claims.

Interactions and External Dependencies
Contributors
  • Hans-Kristian Arntzen, ARM

  • Slawomir Grajewski, Intel

  • Tobias Hector, AMD

  • James Jones, NVIDIA

  • Daniel Rakos, AMD

  • Jeff Juliano, NVIDIA

  • Joshua Schnarr, NVIDIA

  • Aaron Hagan, AMD

Description

This extension allows applications to set the policy for swapchain creation and presentation mechanisms relating to full-screen access. Implementations may be able to acquire exclusive access to a particular display for an application window that covers the whole screen. This can increase performance on some systems by bypassing composition, however it can also result in disruptive or expensive transitions in the underlying windowing system when a change occurs.

Applications can choose between explicitly disallowing or allowing this behavior, letting the implementation decide, or managing this mode of operation directly using the new vkAcquireFullScreenExclusiveModeEXT and vkReleaseFullScreenExclusiveModeEXT commands.

New Enum Constants

  • VK_EXT_FULL_SCREEN_EXCLUSIVE_EXTENSION_NAME

  • VK_EXT_FULL_SCREEN_EXCLUSIVE_SPEC_VERSION

  • Extending VkResult:

    • VK_ERROR_FULL_SCREEN_EXCLUSIVE_MODE_LOST_EXT

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_SURFACE_CAPABILITIES_FULL_SCREEN_EXCLUSIVE_EXT

    • VK_STRUCTURE_TYPE_SURFACE_FULL_SCREEN_EXCLUSIVE_INFO_EXT

If VK_KHR_win32_surface is supported:

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_SURFACE_FULL_SCREEN_EXCLUSIVE_WIN32_INFO_EXT

Issues

1) What should the extension & flag be called?

RESOLVED: VK_EXT_full_screen_exclusive.

Other options considered (prior to the app-controlled mode) were:

  • VK_EXT_smooth_fullscreen_transition

  • VK_EXT_fullscreen_behavior

  • VK_EXT_fullscreen_preference

  • VK_EXT_fullscreen_hint

  • VK_EXT_fast_fullscreen_transition

  • VK_EXT_avoid_fullscreen_exclusive

2) Do we need more than a boolean toggle?

RESOLVED: Yes.

Using an enum with default/allowed/disallowed/app-controlled enables applications to accept driver default behavior, specifically override it in either direction without implying the driver is ever required to use full-screen exclusive mechanisms, or manage this mode explicitly.

3) Should this be a KHR or EXT extension?

RESOLVED: EXT, in order to allow it to be shipped faster.

4) Can the fullscreen hint affect the surface capabilities, and if so, should the hint also be specified as input when querying the surface capabilities?

RESOLVED: Yes on both accounts.

While the hint does not guarantee a particular fullscreen mode will be used when the swapchain is created, it can sometimes imply particular modes will NOT be used. If the driver determines that it will opt-out of using a particular mode based on the policy, and knows it can only support certain capabilities if that mode is used, it would be confusing at best to the application to report those capabilities in such cases. Not allowing implementations to report this state to applications could result in situations where applications are unable to determine why swapchain creation fails when they specify certain hint values, which could result in never- terminating surface creation loops.

5) Should full-screen be one word or two?

RESOLVED: Two words.

"Fullscreen" is not in my dictionary, and web searches did not turn up definitive proof that it is a colloquially accepted compound word. Documentation for the corresponding Windows API mechanisms dithers. The text consistently uses a hyphen, but none-the-less, there is a SetFullscreenState method in the DXGI swapchain object. Given this inconclusive external guidance, it is best to adhere to the Vulkan style guidelines and avoid inventing new compound words.

Version History

  • Revision 4, 2019-03-12 (Tobias Hector)

    • Added application-controlled mode, and related functions

    • Tidied up appendix

  • Revision 3, 2019-01-03 (James Jones)

    • Renamed to VK_EXT_full_screen_exclusive

    • Made related adjustments to the tri-state enumerant names.

  • Revision 2, 2018-11-27 (James Jones)

    • Renamed to VK_KHR_fullscreen_behavior

    • Switched from boolean flag to tri-state enum

  • Revision 1, 2018-11-06 (James Jones)

    • Internal revision

VK_EXT_global_priority

Name String

VK_EXT_global_priority

Extension Type

Device extension

Registered Extension Number

175

Revision

2

Extension and Version Dependencies
  • Requires Vulkan 1.0

Contact

Other Extension Metadata

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

Description

In Vulkan, users can specify device-scope queue priorities. In some cases it may be useful to extend this concept to a system-wide scope. This extension provides a mechanism for caller’s to set their system-wide priority. The default queue priority is VK_QUEUE_GLOBAL_PRIORITY_MEDIUM_EXT.

The driver implementation will attempt to skew hardware resource allocation in favour of the higher-priority task. Therefore, higher-priority work may retain similar latency and throughput characteristics even if the system is congested with lower priority work.

The global priority level of a queue shall take precedence over the per-process queue priority (VkDeviceQueueCreateInfo::pQueuePriorities).

Abuse of this feature may result in starving the rest of the system from hardware resources. Therefore, the driver implementation may deny requests to acquire a priority above the default priority (VK_QUEUE_GLOBAL_PRIORITY_MEDIUM_EXT) if the caller does not have sufficient privileges. In this scenario VK_ERROR_NOT_PERMITTED_EXT is returned.

The driver implementation may fail the queue allocation request if resources required to complete the operation have been exhausted (either by the same process or a different process). In this scenario VK_ERROR_INITIALIZATION_FAILED is returned.

New Enum Constants

  • VK_EXT_GLOBAL_PRIORITY_EXTENSION_NAME

  • VK_EXT_GLOBAL_PRIORITY_SPEC_VERSION

  • Extending VkResult:

    • VK_ERROR_NOT_PERMITTED_EXT

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_DEVICE_QUEUE_GLOBAL_PRIORITY_CREATE_INFO_EXT

Version History

  • Revision 2, 2017-11-03 (Andres Rodriguez)

    • Fixed VkQueueGlobalPriorityEXT missing _EXT suffix

  • Revision 1, 2017-10-06 (Andres Rodriguez)

    • First version.

VK_EXT_hdr_metadata

Name String

VK_EXT_hdr_metadata

Extension Type

Device extension

Registered Extension Number

106

Revision

2

Extension and Version Dependencies
Contact

Other Extension Metadata

Last Modified Date

2018-12-19

IP Status

No known IP claims.

Contributors
  • Courtney Goeltzenleuchter, Google

Description

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 Commands

New Enum Constants

  • VK_EXT_HDR_METADATA_EXTENSION_NAME

  • VK_EXT_HDR_METADATA_SPEC_VERSION

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_HDR_METADATA_EXT

Issues

1) Do we need a query function?

PROPOSED: No, Vulkan does not provide queries for state that the application can track on its own.

2) Should we specify default if not specified by the application?

PROPOSED: No, that leaves the default up to the display.

Version History

  • Revision 1, 2016-12-27 (Courtney Goeltzenleuchter)

    • Initial version

  • Revision 2, 2018-12-19 (Courtney Goeltzenleuchter)

    • Correct implicit validity for VkHdrMetadataEXT structure

VK_EXT_headless_surface

Name String

VK_EXT_headless_surface

Extension Type

Instance extension

Registered Extension Number

257

Revision

1

Extension and Version Dependencies
Contact

Other Extension Metadata

Last Modified Date

2019-03-21

IP Status

No known IP claims.

Contributors
  • Ray Smith, Arm

Description

The VK_EXT_headless_surface extension is an instance extension. It provides a mechanism to create VkSurfaceKHR objects independently of any window system or display device. The presentation operation for a swapchain created from a headless surface is by default a no-op, resulting in no externally-visible result.

Because there is no real presentation target, future extensions can layer on top of the headless surface to introduce arbitrary or customisable sets of restrictions or features. These could include features like saving to a file or restrictions to emulate a particular presentation target.

This functionality is expected to be useful for application and driver development because it allows any platform to expose an arbitrary or customisable set of restrictions and features of a presentation engine. This makes it a useful portable test target for applications targeting a wide range of presentation engines where the actual target presentation engines might be scarce, unavailable or otherwise undesirable or inconvenient to use for general Vulkan application development.

New Enum Constants

  • VK_EXT_HEADLESS_SURFACE_EXTENSION_NAME

  • VK_EXT_HEADLESS_SURFACE_SPEC_VERSION

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_HEADLESS_SURFACE_CREATE_INFO_EXT

Version History

  • Revision 1, 2019-03-21 (Ray Smith)

    • Initial draft

VK_EXT_host_query_reset

Name String

VK_EXT_host_query_reset

Extension Type

Device extension

Registered Extension Number

262

Revision

1

Extension and Version Dependencies
Deprecation state
  • Promoted to Vulkan 1.2

Contact

Other Extension Metadata

Last Modified Date

2019-03-06

IP Status

No known IP claims.

Interactions and External Dependencies
  • Promoted to Vulkan 1.2 Core

Contributors
  • Bas Nieuwenhuizen, Google

  • Jason Ekstrand, Intel

  • Jeff Bolz, NVIDIA

  • Piers Daniell, NVIDIA

Description

This extension adds a new function to reset queries from the host.

Promotion to Vulkan 1.2

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

New Commands

New Enum Constants

  • VK_EXT_HOST_QUERY_RESET_EXTENSION_NAME

  • VK_EXT_HOST_QUERY_RESET_SPEC_VERSION

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_HOST_QUERY_RESET_FEATURES_EXT

Version History

  • Revision 1, 2019-03-12 (Bas Nieuwenhuizen)

    • Initial draft

VK_EXT_image_drm_format_modifier

Name String

VK_EXT_image_drm_format_modifier

Extension Type

Device extension

Registered Extension Number

159

Revision

1

Extension and Version Dependencies
Contact

Other Extension Metadata

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

Description

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

  • VK_EXT_IMAGE_DRM_FORMAT_MODIFIER_EXTENSION_NAME

  • VK_EXT_IMAGE_DRM_FORMAT_MODIFIER_SPEC_VERSION

  • 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

  • Extending VkImageTiling:

    • VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT

  • Extending VkResult:

    • VK_ERROR_INVALID_DRM_FORMAT_MODIFIER_PLANE_LAYOUT_EXT

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_DRM_FORMAT_MODIFIER_PROPERTIES_EXT

    • VK_STRUCTURE_TYPE_DRM_FORMAT_MODIFIER_PROPERTIES_LIST_EXT

    • VK_STRUCTURE_TYPE_IMAGE_DRM_FORMAT_MODIFIER_EXPLICIT_CREATE_INFO_EXT

    • VK_STRUCTURE_TYPE_IMAGE_DRM_FORMAT_MODIFIER_LIST_CREATE_INFO_EXT

    • VK_STRUCTURE_TYPE_IMAGE_DRM_FORMAT_MODIFIER_PROPERTIES_EXT

    • VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGE_DRM_FORMAT_MODIFIER_INFO_EXT

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 entry point, 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, 2018-08-29 (Chad Versace)

    • First stable revision

VK_EXT_index_type_uint8

Name String

VK_EXT_index_type_uint8

Extension Type

Device extension

Registered Extension Number

266

Revision

1

Extension and Version Dependencies
  • Requires Vulkan 1.0

Contact

Other Extension Metadata

Last Modified Date

2019-05-02

IP Status

No known IP claims.

Contributors
  • Jeff Bolz, NVIDIA

Description

This extension allows uint8_t indices to be used with vkCmdBindIndexBuffer.

New Enum Constants

  • VK_EXT_INDEX_TYPE_UINT8_EXTENSION_NAME

  • VK_EXT_INDEX_TYPE_UINT8_SPEC_VERSION

  • Extending VkIndexType:

    • VK_INDEX_TYPE_UINT8_EXT

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_INDEX_TYPE_UINT8_FEATURES_EXT

Version History

  • Revision 1, 2019-05-02 (Piers Daniell)

    • Internal revisions

VK_EXT_inline_uniform_block

Name String

VK_EXT_inline_uniform_block

Extension Type

Device extension

Registered Extension Number

139

Revision

1

Extension and Version Dependencies
Contact

Other Extension Metadata

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

Description

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

  • VK_EXT_INLINE_UNIFORM_BLOCK_EXTENSION_NAME

  • VK_EXT_INLINE_UNIFORM_BLOCK_SPEC_VERSION

  • Extending VkDescriptorType:

    • VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK_EXT

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_DESCRIPTOR_POOL_INLINE_UNIFORM_BLOCK_CREATE_INFO_EXT

    • 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

Issues

1) Do we need a new storage class for inline uniform blocks vs uniform blocks?

RESOLVED: No. The Uniform storage class is used to allow the same syntax used for both uniform buffers and inline uniform blocks.

2) Is the descriptor array index and array size expressed in terms of bytes or dwords for inline uniform block descriptors?

RESOLVED: In bytes, but both must be a multiple of 4, similar to how push constant ranges are specified. The descriptorCount of VkDescriptorSetLayoutBinding thus provides the total number of bytes a particular binding with an inline uniform block descriptor type can hold, while the srcArrayElement, dstArrayElement, and descriptorCount members of VkWriteDescriptorSet, VkCopyDescriptorSet, and VkDescriptorUpdateTemplateEntry (where applicable) specify the byte offset and number of bytes to write/copy to the binding’s backing store. Additionally, the stride member of VkDescriptorUpdateTemplateEntry is ignored for inline uniform blocks and a default value of one is used, meaning that the data to update inline uniform block bindings with must be contiguous in memory.

3) What layout rules apply for uniform blocks corresponding to inline constants?

RESOLVED: They use the same layout rules as uniform buffers.

4) Do we need to add non-uniform indexing features/properties as introduced by VK_EXT_descriptor_indexing for inline uniform blocks?

RESOLVED: No, because inline uniform blocks are not allowed to be “arrayed”. A single binding with an inline uniform block descriptor type corresponds to a single uniform block instance and the array indices inside that binding refer to individual offsets within the uniform block (see issue #2). However, this extension does introduce new features/properties about the level of support for update-after-bind inline uniform blocks.

5) Is the descriptorBindingVariableDescriptorCount feature introduced by VK_EXT_descriptor_indexing supported for inline uniform blocks?

RESOLVED: Yes, as long as other inline uniform block specific limits are respected.

6) Do the robustness guarantees of robustBufferAccess apply to inline uniform block accesses?

RESOLVED: No, similarly to push constants, as they are not backed by buffer memory like uniform buffers.

Version History

  • Revision 1, 2018-08-01 (Daniel Rakos)

    • Internal revisions

VK_EXT_line_rasterization

Name String

VK_EXT_line_rasterization

Extension Type

Device extension

Registered Extension Number

260

Revision

1

Extension and Version Dependencies
Contact

Other Extension Metadata

Last Modified Date

2019-05-09

IP Status

No known IP claims.

Contributors
  • Jeff Bolz, NVIDIA

  • Allen Jensen, NVIDIA

  • Jason Ekstrand, Intel

Description

This extension adds some line rasterization features that are commonly used in CAD applications and supported in other APIs like OpenGL. Bresenham-style line rasterization is supported, smooth rectangular lines (coverage to alpha) are supported, and stippled lines are supported for all three line rasterization modes.

New Commands

New Enum Constants

  • VK_EXT_LINE_RASTERIZATION_EXTENSION_NAME

  • VK_EXT_LINE_RASTERIZATION_SPEC_VERSION

  • Extending VkDynamicState:

    • VK_DYNAMIC_STATE_LINE_STIPPLE_EXT

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_LINE_RASTERIZATION_FEATURES_EXT

    • VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_LINE_RASTERIZATION_PROPERTIES_EXT

    • VK_STRUCTURE_TYPE_PIPELINE_RASTERIZATION_LINE_STATE_CREATE_INFO_EXT

Issues

(1) Do we need to support Bresenham-style and smooth lines with more than
    one rasterization sample? i.e. the equivalent of
    glDisable(GL_MULTISAMPLE) in OpenGL when the framebuffer has more than
    one sample?
RESOLVED: Yes.
For simplicity, Bresenham line rasterization carries forward a few
restrictions from OpenGL, such as not supporting per-sample shading, alpha
to coverage, or alpha to one.

Version History

  • Revision 1, 2019-05-09 (Jeff Bolz)

    • Initial draft

VK_EXT_memory_budget

Name String

VK_EXT_memory_budget

Extension Type

Device extension

Registered Extension Number

238

Revision

1

Extension and Version Dependencies
Contact

Other Extension Metadata

Last Modified Date

2018-10-08

Contributors
  • Jeff Bolz, NVIDIA

  • Jeff Juliano, NVIDIA

Description

This extension adds support for querying the amount of memory used and the total memory budget for a memory heap. The values returned by this query are implementation-dependent and can depend on a variety of factors including operating system and system load.

The heapBudget values can be used as a guideline for how much total memory from each heap the process can use at any given time, before allocations may start failing or causing performance degradation. The values may change based on other activity in the system that is outside the scope and control of the Vulkan implementation.

New Enum Constants

  • VK_EXT_MEMORY_BUDGET_EXTENSION_NAME

  • VK_EXT_MEMORY_BUDGET_SPEC_VERSION

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MEMORY_BUDGET_PROPERTIES_EXT

Version History

  • Revision 1, 2018-10-08 (Jeff Bolz)

    • Initial revision

VK_EXT_memory_priority

Name String

VK_EXT_memory_priority

Extension Type

Device extension

Registered Extension Number

239

Revision

1

Extension and Version Dependencies
Contact

Other Extension Metadata

Last Modified Date

2018-10-08

Contributors
  • Jeff Bolz, NVIDIA

  • Jeff Juliano, NVIDIA

Description

This extension adds a priority value specified at memory allocation time. On some systems with both device-local and non-device-local memory heaps, the implementation may transparently move memory from one heap to another when a heap becomes full (for example, when the total memory used across all processes exceeds the size of the heap). In such a case, this priority value may be used to determine which allocations are more likely to remain in device-local memory.

New Enum Constants

  • VK_EXT_MEMORY_PRIORITY_EXTENSION_NAME

  • VK_EXT_MEMORY_PRIORITY_SPEC_VERSION

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_MEMORY_PRIORITY_ALLOCATE_INFO_EXT

    • VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MEMORY_PRIORITY_FEATURES_EXT

Version History

  • Revision 1, 2018-10-08 (Jeff Bolz)

    • Initial revision

VK_EXT_metal_surface

Name String

VK_EXT_metal_surface

Extension Type

Instance extension

Registered Extension Number

218

Revision

1

Extension and Version Dependencies
Contact

Other Extension Metadata

Last Modified Date

2018-10-01

IP Status

No known IP claims.

Contributors
  • Dzmitry Malyshau, Mozilla Corp.

Description

The VK_EXT_metal_surface extension is an instance extension. It provides a mechanism to create a VkSurfaceKHR object (defined by the VK_KHR_surface extension) from CAMetalLayer, which is the native rendering surface of Apple’s Metal framework.

New Enum Constants

  • VK_EXT_METAL_SURFACE_EXTENSION_NAME

  • VK_EXT_METAL_SURFACE_SPEC_VERSION

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_METAL_SURFACE_CREATE_INFO_EXT

Version History

  • Revision 1, 2018-10-01 (Dzmitry Malyshau)

    • Initial version

VK_EXT_pci_bus_info

Name String

VK_EXT_pci_bus_info

Extension Type

Device extension

Registered Extension Number

213

Revision

2

Extension and Version Dependencies
Contact

Other Extension Metadata

Last Modified Date

2018-12-10

IP Status

No known IP claims.

Contributors
  • Matthaeus G. Chajdas, AMD

  • Daniel Rakos, AMD

Description

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

  • VK_EXT_PCI_BUS_INFO_EXTENSION_NAME

  • VK_EXT_PCI_BUS_INFO_SPEC_VERSION

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PCI_BUS_INFO_PROPERTIES_EXT

Version History

  • Revision 2, 2018-12-10 (Daniel Rakos)

    • Changed all members of the new structure to have the uint32_t type

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

    • Initial revision

VK_EXT_pipeline_creation_cache_control

Name String

VK_EXT_pipeline_creation_cache_control

Extension Type

Device extension

Registered Extension Number

298

Revision

3

Extension and Version Dependencies
  • Requires Vulkan 1.0

Contact

Other Extension Metadata

Last Modified Date

2020-03-23

IP Status

No known IP claims.

Contributors
  • Gregory Grebe, AMD

  • Tobias Hector, AMD

  • Matthaeus Chajdas, AMD

  • Mitch Singer, AMD

  • Spencer Fricke, Samsung Electronics

  • Stuart Smith, Imagination Technologies

  • Jeff Bolz, NVIDIA Corporation

  • Daniel Koch, NVIDIA Corporation

  • Dan Ginsburg, Valve Corporation

  • Jeff Leger, QUALCOMM

  • Michal Pietrasiuk, Intel

  • Jan-Harald Fredriksen, Arm Limited

Description

This extension adds flags to Vk*PipelineCreateInfo and VkPipelineCacheCreateInfo structures with the aim of improving the predictability of pipeline creation cost. The goal is to provide information about potentially expensive hazards within the client driver during pipeline creation to the application before carrying them out rather than after.

Background

Pipeline creation is a costly operation, and the explicit nature of the Vulkan design means that cost is not hidden from the developer. Applications are also expected to schedule, prioritize, and load balance all calls for pipeline creation. It is strongly advised that applications create pipelines sufficiently ahead of their usage. Failure to do so will result in an unresponsive application, intermittent stuttering, or other poor user experiences. Proper usage of pipeline caches and/or derivative pipelines help mitigate this but is not assured to eliminate disruption in all cases. In the event that an ahead-of-time creation is not possible, considerations should be taken to ensure that the current execution context is suitable for the workload of pipeline creation including possible shader compilation.

Applications making API calls to create a pipeline must be prepared for any of the following to occur:

  • OS/kernel calls to be made by the ICD

  • Internal memory allocation not tracked by the pAllocator passed to vkCreate*Pipelines

  • Internal thread synchronization or yielding of the current thread’s core

  • Extremely long (multi-millisecond+), blocking, compilation times

  • Arbitrary call stacks depths and stack memory usage

The job or task based game engines that are being developed to take advantage of explicit graphics APIs like Vulkan may behave exceptionally poorly if any of the above scenarios occur. However, most game engines are already built to "stream" in assets dynamically as the user plays the game. By adding control by way of VkPipelineCreateFlags, we can require an ICD to report back a failure in critical execution paths rather than forcing an unexpected wait.

Applications can prevent unexpected compilation by setting VK_PIPELINE_CREATE_FAIL_ON_PIPELINE_COMPILE_REQUIRED_BIT_EXT on Vk*PipelineCreateInfo::flags. When set, an ICD must not attempt pipeline or shader compilation to create the pipeline object. The ICD will return the result VK_PIPELINE_COMPILE_REQUIRED_EXT. An ICD may still return a valid VkPipeline object by either re-using existing pre-compiled objects such as those from a pipeline cache, or derivative pipelines.

By default vkCreate*Pipelines calls must attempt to create all pipelines before returning. Setting VK_PIPELINE_CREATE_EARLY_RETURN_ON_FAILURE_BIT_EXT on Vk*PipelineCreateInfo::flags can be used as an escape hatch for batched pipeline creates.

Hidden locks also add to the unpredictability of the cost of pipeline creation. The most common case of locks inside the vkCreate*Pipelines is internal synchronization of the VkPipelineCache object. VK_PIPELINE_CACHE_CREATE_EXTERNALLY_SYNCHRONIZED_BIT_EXT can be set when calling vkCreatePipelineCache to state the cache is externally synchronized.

The hope is that armed with this information application and engine developers can leverage existing asset streaming systems to recover from "just-in-time" pipeline creation stalls.

New Enum Constants

  • VK_EXT_PIPELINE_CREATION_CACHE_CONTROL_EXTENSION_NAME

  • VK_EXT_PIPELINE_CREATION_CACHE_CONTROL_SPEC_VERSION

  • Extending VkPipelineCacheCreateFlagBits:

    • VK_PIPELINE_CACHE_CREATE_EXTERNALLY_SYNCHRONIZED_BIT_EXT

  • Extending VkPipelineCreateFlagBits:

    • VK_PIPELINE_CREATE_EARLY_RETURN_ON_FAILURE_BIT_EXT

    • VK_PIPELINE_CREATE_FAIL_ON_PIPELINE_COMPILE_REQUIRED_BIT_EXT

  • Extending VkResult:

    • VK_PIPELINE_COMPILE_REQUIRED_EXT

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PIPELINE_CREATION_CACHE_CONTROL_FEATURES_EXT

Version History

  • Revision 1, 2019-11-01 (Gregory Grebe)

    • Initial revision

  • Revision 2, 2020-02-24 (Gregory Grebe)

    • Initial public revision

  • Revision 3, 2020-03-23 (Tobias Hector)

    • Changed VK_PIPELINE_COMPILE_REQUIRED_EXT to a success code, adding an alias for the original VK_ERROR_PIPELINE_COMPILE_REQUIRED_EXT. Also updated the xml to include these codes as return values.

VK_EXT_pipeline_creation_feedback

Name String

VK_EXT_pipeline_creation_feedback

Extension Type

Device extension

Registered Extension Number

193

Revision

1

Extension and Version Dependencies
  • Requires Vulkan 1.0

Contact
  • Jean-Francois Roy jfroy

Other Extension Metadata

Last Modified Date

2019-03-12

IP Status

No known IP claims.

Contributors
  • Jean-Francois Roy, Google

  • Hai Nguyen, Google

  • Andrew Ellem, Google

  • Bob Fraser, Google

  • Sujeevan Rajayogam, Google

  • Jan-Harald Fredriksen, ARM

  • Jeff Leger, Qualcomm Technologies, Inc.

  • Jeff Bolz, NVIDIA

  • Daniel Koch, NVIDIA

  • Neil Henning, AMD

Description

This extension adds a mechanism to provide feedback to an application about pipeline creation, with the specific goal of allowing a feedback loop between build systems and in-the-field application executions to ensure effective pipeline caches are shipped to customers.

New Enum Constants

  • VK_EXT_PIPELINE_CREATION_FEEDBACK_EXTENSION_NAME

  • VK_EXT_PIPELINE_CREATION_FEEDBACK_SPEC_VERSION

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_PIPELINE_CREATION_FEEDBACK_CREATE_INFO_EXT

Version History

  • Revision 1, 2019-03-12 (Jean-Francois Roy)

    • Initial revision

VK_EXT_post_depth_coverage

Name String

VK_EXT_post_depth_coverage

Extension Type

Device extension

Registered Extension Number

156

Revision

1

Extension and Version Dependencies
  • Requires Vulkan 1.0

Contact

Other Extension Metadata

Last Modified Date

2017-07-17

Interactions and External Dependencies
Contributors
  • Jeff Bolz, NVIDIA

Description

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 early 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 Enum Constants

  • VK_EXT_POST_DEPTH_COVERAGE_EXTENSION_NAME

  • VK_EXT_POST_DEPTH_COVERAGE_SPEC_VERSION

New SPIR-V Capabilities

Version History

  • Revision 1, 2017-07-17 (Daniel Koch)

    • Internal revisions

VK_EXT_private_data

Name String

VK_EXT_private_data

Extension Type

Device extension

Registered Extension Number

296

Revision

1

Extension and Version Dependencies
  • Requires Vulkan 1.0

Contact

Other Extension Metadata

Status

Draft

Last Modified Date

2020-03-25

IP Status

No known IP claims.

Contributors
  • Matthew Rusch, NVIDIA

  • Nuno Subtil, NVIDIA

  • Piers Daniell, NVIDIA

  • Jeff Bolz, NVIDIA

Description

The 'VK_EXT_private_data' extension is a device extension which enables attaching arbitrary payloads to Vulkan objects. It introduces the idea of private data slots as a means of storing a 64-bit unsigned integer of application defined data. Private data slots can be created or destroyed any time an associated device is available. Private data slots can be reserved at device creation time, and limiting use to the amount reserved will allow the extension to exhibit better performance characteristics.

New Object Types

New Enum Constants

  • VK_EXT_PRIVATE_DATA_EXTENSION_NAME

  • VK_EXT_PRIVATE_DATA_SPEC_VERSION

  • Extending VkObjectType:

    • VK_OBJECT_TYPE_PRIVATE_DATA_SLOT_EXT

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_DEVICE_PRIVATE_DATA_CREATE_INFO_EXT

    • VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PRIVATE_DATA_FEATURES_EXT

    • VK_STRUCTURE_TYPE_PRIVATE_DATA_SLOT_CREATE_INFO_EXT

Examples

  • In progress

Version History

  • Revision 1, 2020-01-15 (Matthew Rusch)

    • Initial draft

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

Other Extension Metadata

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

Description

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

  • VK_EXT_QUEUE_FAMILY_FOREIGN_EXTENSION_NAME

  • VK_EXT_QUEUE_FAMILY_FOREIGN_SPEC_VERSION

  • VK_QUEUE_FAMILY_FOREIGN_EXT

Version History

  • Revision 1, 2017-11-01 (Chad Versace)

    • Squashed internal revisions

VK_EXT_robustness2

Name String

VK_EXT_robustness2

Extension Type

Device extension

Registered Extension Number

287

Revision

1

Extension and Version Dependencies
  • Requires Vulkan 1.0

Contact

Other Extension Metadata

Last Modified Date

2020-01-29

IP Status

No known IP claims.

Contributors
  • Liam Middlebrook, NVIDIA

  • Jeff Bolz, NVIDIA

Description

This extension adds stricter requirements for how out of bounds reads and writes are handled. Most accesses must be tightly bounds-checked, out of bounds writes must be discarded, out of bound reads must return zero. Rather than allowing multiple possible (0,0,0,x) vectors, the out of bounds values are treated as zero, and then missing components are inserted based on the format as described in Conversion to RGBA and vertex input attribute extraction.

These additional requirements may be expensive on some implementations, and should only be enabled when truly necessary.

This extension also adds support for "null descriptors", where VK_NULL_HANDLE can be used instead of a valid handle. Accesses to null descriptors have well-defined behavior, and don’t rely on robustness.

New Enum Constants

  • VK_EXT_ROBUSTNESS_2_EXTENSION_NAME

  • VK_EXT_ROBUSTNESS_2_SPEC_VERSION

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_ROBUSTNESS_2_FEATURES_EXT

    • VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_ROBUSTNESS_2_PROPERTIES_EXT

Issues

  1. Why do VkPhysicalDeviceRobustness2PropertiesEXT::robustUniformBufferAccessSizeAlignment and VkPhysicalDeviceRobustness2PropertiesEXT::robustStorageBufferAccessSizeAlignment exist?

RESOLVED: Some implementations can’t efficiently tightly bounds-check all buffer accesses. Rather, the size of the bound range is padded to some power of two multiple, up to 256 bytes for uniform buffers and up to 4 bytes for storage buffers, and that padded size is bounds-checked. This is sufficient to implement D3D-like behavior, because D3D only allows binding whole uniform buffers or ranges that are a multiple of 256 bytes, and D3D raw and structured buffers only support 32-bit accesses.

Examples

None.

Version History

  • Revision 1, 2019-11-01 (Jeff Bolz, Liam Middlebrook)

    • Initial draft

VK_EXT_sample_locations

Name String

VK_EXT_sample_locations

Extension Type

Device extension

Registered Extension Number

144

Revision

1

Extension and Version Dependencies
Contact

Other Extension Metadata

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

Description

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

  • VK_EXT_SAMPLE_LOCATIONS_EXTENSION_NAME

  • VK_EXT_SAMPLE_LOCATIONS_SPEC_VERSION

  • Extending VkDynamicState:

    • VK_DYNAMIC_STATE_SAMPLE_LOCATIONS_EXT

  • Extending VkImageCreateFlagBits:

    • VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_MULTISAMPLE_PROPERTIES_EXT

    • VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SAMPLE_LOCATIONS_PROPERTIES_EXT

    • VK_STRUCTURE_TYPE_PIPELINE_SAMPLE_LOCATIONS_STATE_CREATE_INFO_EXT

    • VK_STRUCTURE_TYPE_RENDER_PASS_SAMPLE_LOCATIONS_BEGIN_INFO_EXT

    • VK_STRUCTURE_TYPE_SAMPLE_LOCATIONS_INFO_EXT

Version History

  • Revision 1, 2017-08-02 (Daniel Rakos)

    • Internal revisions

VK_EXT_sampler_filter_minmax

Name String

VK_EXT_sampler_filter_minmax

Extension Type

Device extension

Registered Extension Number

131

Revision

2

Extension and Version Dependencies
Deprecation state
  • Promoted to Vulkan 1.2

Contact

Other Extension Metadata

Last Modified Date

2017-05-19

Interactions and External Dependencies
  • Promoted to Vulkan 1.2 Core

IP Status

No known IP claims.

Contributors
  • Jeff Bolz, NVIDIA

  • Piers Daniell, NVIDIA

Description

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.

Promotion to Vulkan 1.2

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

New Enum Constants

  • VK_EXT_SAMPLER_FILTER_MINMAX_EXTENSION_NAME

  • VK_EXT_SAMPLER_FILTER_MINMAX_SPEC_VERSION

  • Extending VkFormatFeatureFlagBits:

    • VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_MINMAX_BIT_EXT

  • Extending VkSamplerReductionMode:

    • VK_SAMPLER_REDUCTION_MODE_MAX_EXT

    • VK_SAMPLER_REDUCTION_MODE_MIN_EXT

    • VK_SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE_EXT

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SAMPLER_FILTER_MINMAX_PROPERTIES_EXT

    • VK_STRUCTURE_TYPE_SAMPLER_REDUCTION_MODE_CREATE_INFO_EXT

Version History

  • Revision 2, 2017-05-19 (Piers Daniell)

    • Renamed to EXT

  • Revision 1, 2017-03-25 (Jeff Bolz)

    • Internal revisions

VK_EXT_scalar_block_layout

Name String

VK_EXT_scalar_block_layout

Extension Type

Device extension

Registered Extension Number

222

Revision

1

Extension and Version Dependencies
Deprecation state
  • Promoted to Vulkan 1.2

Contact

Other Extension Metadata

Last Modified Date

2018-11-14

Interactions and External Dependencies
  • Promoted to Vulkan 1.2 Core

Contributors
  • Jeff Bolz

  • Jan-Harald Fredriksen

  • Graeme Leese

  • Jason Ekstrand

  • John Kessenich

Description

This extension enables C-like structure layout for SPIR-V blocks. It modifies the alignment rules for uniform buffers, storage buffers and push constants, allowing non-scalar types to be aligned solely based on the size of their components, without additional requirements.

Promotion to Vulkan 1.2

Functionality in this extension is included in core Vulkan 1.2, with the EXT suffix omitted. However, if Vulkan 1.2 is supported and this extension is not, the scalarBlockLayout capability is optional. The original type, enum and command names are still available as aliases of the core functionality.

New Enum Constants

  • VK_EXT_SCALAR_BLOCK_LAYOUT_EXTENSION_NAME

  • VK_EXT_SCALAR_BLOCK_LAYOUT_SPEC_VERSION

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SCALAR_BLOCK_LAYOUT_FEATURES_EXT

Version History

  • Revision 1, 2018-11-14 (Tobias Hector)

    • Initial draft

VK_EXT_separate_stencil_usage

Name String

VK_EXT_separate_stencil_usage

Extension Type

Device extension

Registered Extension Number

247

Revision

1

Extension and Version Dependencies
  • Requires Vulkan 1.0

Deprecation state
  • Promoted to Vulkan 1.2

Contact

Other Extension Metadata

Last Modified Date

2018-11-08

Interactions and External Dependencies
  • Promoted to Vulkan 1.2 Core

IP Status

No known IP claims.

Contributors
  • Daniel Rakos, AMD

  • Jordan Logan, AMD

Description

This extension allows specifying separate usage flags for the stencil aspect of images with a depth-stencil format at image creation time.

Promotion to Vulkan 1.2

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

New Enum Constants

  • VK_EXT_SEPARATE_STENCIL_USAGE_EXTENSION_NAME

  • VK_EXT_SEPARATE_STENCIL_USAGE_SPEC_VERSION

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_IMAGE_STENCIL_USAGE_CREATE_INFO_EXT

Version History

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

    • Internal revisions.

VK_EXT_shader_demote_to_helper_invocation

Name String

VK_EXT_shader_demote_to_helper_invocation

Extension Type

Device extension

Registered Extension Number

277

Revision

1

Extension and Version Dependencies
Contact

Other Extension Metadata

Last Modified Date

2019-06-01

IP Status

No known IP claims.

Contributors
  • Jeff Bolz, NVIDIA

Description

This extension adds Vulkan support for the SPV_EXT_demote_to_helper_invocation SPIR-V extension. That SPIR-V extension provides a new instruction OpDemoteToHelperInvocationEXT allowing shaders to "demote" a fragment shader invocation to behave like a helper invocation for its duration. The demoted invocation will have no further side effects and will not output to the framebuffer, but remains active and can participate in computing derivatives and in group operations. This is a better match for the "discard" instruction in HLSL.

New Enum Constants

  • VK_EXT_SHADER_DEMOTE_TO_HELPER_INVOCATION_EXTENSION_NAME

  • VK_EXT_SHADER_DEMOTE_TO_HELPER_INVOCATION_SPEC_VERSION

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_DEMOTE_TO_HELPER_INVOCATION_FEATURES_EXT

New SPIR-V Capability

Version History

  • Revision 1, 2019-06-01 (Jeff Bolz)

    • Initial draft

VK_EXT_shader_stencil_export

Name String

VK_EXT_shader_stencil_export

Extension Type

Device extension

Registered Extension Number

141

Revision

1

Extension and Version Dependencies
  • Requires Vulkan 1.0

Contact

Other Extension Metadata

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

Description

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.

New Enum Constants

  • VK_EXT_SHADER_STENCIL_EXPORT_EXTENSION_NAME

  • VK_EXT_SHADER_STENCIL_EXPORT_SPEC_VERSION

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

Deprecation state
  • Deprecated by Vulkan 1.2

Contact

Other Extension Metadata

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

Description

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.

Deprecated by Vulkan 1.2

Most of the functionality in this extension is superseded by the core Vulkan 1.1 subgroup operations. However, Vulkan 1.1 required the OpGroupNonUniformBroadcast "Id" to be constant. This restriction was removed in Vulkan 1.2 with the addition of the subgroupBroadcastDynamicId feature.

New Enum Constants

  • VK_EXT_SHADER_SUBGROUP_BALLOT_EXTENSION_NAME

  • VK_EXT_SHADER_SUBGROUP_BALLOT_SPEC_VERSION

New SPIR-V Capabilities

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

Deprecation state
  • Deprecated by Vulkan 1.1

Contact

Other Extension Metadata

Last Modified Date

2016-11-28

IP Status

No known IP claims.

Interactions and External Dependencies
Contributors
  • Neil Henning, Codeplay

  • Daniel Koch, NVIDIA Corporation

Description

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

Deprecated by Vulkan 1.1

All functionality in this extension is superseded by the core Vulkan 1.1 subgroup operations.

New Enum Constants

  • VK_EXT_SHADER_SUBGROUP_VOTE_EXTENSION_NAME

  • VK_EXT_SHADER_SUBGROUP_VOTE_SPEC_VERSION

New SPIR-V Capabilities

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

Deprecation state
  • Promoted to Vulkan 1.2

Contact

Other Extension Metadata

Last Modified Date

2017-08-08

Interactions and External Dependencies
  • Promoted to Vulkan 1.2 Core

Interactions and External Dependencies
Contributors
  • Piers Daniell, NVIDIA

  • Jeff Bolz, NVIDIA

  • Jan-Harald Fredriksen, ARM

  • Daniel Rakos, AMD

  • Slawomir Grajeswki, Intel

Description

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.

Promotion to Vulkan 1.2

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

The single ShaderViewportIndexLayerEXT capability from the SPV_EXT_shader_viewport_index_layer extension is replaced by the ShaderViewportIndex and ShaderLayer capabilities from SPIR-V 1.5 which are enabled by the shaderOutputViewportIndex and shaderOutputLayer features, respectively. Additionally, if Vulkan 1.2 is supported but this extension is not, these capabilities are optional.

Enabling both features is equivalent to enabling the VK_EXT_shader_viewport_index_layer extension.

New Enum Constants

  • VK_EXT_SHADER_VIEWPORT_INDEX_LAYER_EXTENSION_NAME

  • VK_EXT_SHADER_VIEWPORT_INDEX_LAYER_SPEC_VERSION

New or Modified Built-In Variables

New SPIR-V Capabilities

Version History

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

    • Internal drafts

VK_EXT_subgroup_size_control

Name String

VK_EXT_subgroup_size_control

Extension Type

Device extension

Registered Extension Number

226

Revision

2

Extension and Version Dependencies
  • Requires Vulkan 1.1

Contact

Other Extension Metadata

Last Modified Date

2019-03-05

Contributors
  • Jeff Bolz, NVIDIA

  • Jason Ekstrand, Intel

  • Sławek Grajewski, Intel

  • Jesse Hall, Google

  • Neil Henning, AMD

  • Daniel Koch, NVIDIA

  • Jeff Leger, Qualcomm

  • Graeme Leese, Broadcom

  • Allan MacKinnon, Google

  • Mariusz Merecki, Intel

  • Graham Wihlidal, Electronic Arts

Description

This extension enables an implementation to control the subgroup size by allowing a varying subgroup size and also specifying a required subgroup size.

It extends the subgroup support in Vulkan 1.1 to allow an implementation to expose a varying subgroup size. Previously Vulkan exposed a single subgroup size per physical device, with the expectation that implementations will behave as if all subgroups have the same size. Some implementations may dispatch shaders with a varying subgroup size for different subgroups. As a result they could implicitly split a large subgroup into smaller subgroups or represent a small subgroup as a larger subgroup, some of whose invocations were inactive on launch.

To aid developers in understanding the performance characteristics of their programs, this extension exposes a minimum and maximum subgroup size that a physical device supports and a pipeline create flag to enable that pipeline to vary its subgroup size. If enabled, any SubgroupSize decorated variables in the SPIR-V shader modules provided to pipeline creation may vary between the minimum and maximum subgroup sizes.

An implementation is also optionally allowed to support specifying a required subgroup size for a given pipeline stage. Implementations advertise which stages support a required subgroup size, and any pipeline of a supported stage can be passed a VkPipelineShaderStageRequiredSubgroupSizeCreateInfoEXT structure to set the subgroup size for that shader stage of the pipeline. For compute shaders, this requires the developer to query the maxComputeWorkgroupSubgroups and ensure that:

Developers can also specify a new pipeline shader stage create flag that requires the implementation to have fully populated subgroups within local workgroups. This requires the workgroup size in the X dimension to be a multiple of the subgroup size.

New Enum Constants

  • VK_EXT_SUBGROUP_SIZE_CONTROL_EXTENSION_NAME

  • VK_EXT_SUBGROUP_SIZE_CONTROL_SPEC_VERSION

  • Extending VkPipelineShaderStageCreateFlagBits:

    • VK_PIPELINE_SHADER_STAGE_CREATE_ALLOW_VARYING_SUBGROUP_SIZE_BIT_EXT

    • VK_PIPELINE_SHADER_STAGE_CREATE_REQUIRE_FULL_SUBGROUPS_BIT_EXT

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SUBGROUP_SIZE_CONTROL_FEATURES_EXT

    • VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SUBGROUP_SIZE_CONTROL_PROPERTIES_EXT

    • VK_STRUCTURE_TYPE_PIPELINE_SHADER_STAGE_REQUIRED_SUBGROUP_SIZE_CREATE_INFO_EXT

Version History

VK_EXT_swapchain_colorspace

Name String

VK_EXT_swapchain_colorspace

Extension Type

Instance extension

Registered Extension Number

105

Revision

4

Extension and Version Dependencies
Contact

Other Extension Metadata

Last Modified Date

2019-04-26

IP Status

No known IP claims.

Contributors
  • Courtney Goeltzenleuchter, Google

Description

To be done.

New Enum Constants

  • VK_EXT_SWAPCHAIN_COLOR_SPACE_EXTENSION_NAME

  • VK_EXT_SWAPCHAIN_COLOR_SPACE_SPEC_VERSION

  • Extending VkColorSpaceKHR:

    • VK_COLOR_SPACE_ADOBERGB_LINEAR_EXT

    • VK_COLOR_SPACE_ADOBERGB_NONLINEAR_EXT

    • VK_COLOR_SPACE_BT2020_LINEAR_EXT

    • VK_COLOR_SPACE_BT709_LINEAR_EXT

    • VK_COLOR_SPACE_BT709_NONLINEAR_EXT

    • VK_COLOR_SPACE_DCI_P3_NONLINEAR_EXT

    • VK_COLOR_SPACE_DISPLAY_P3_LINEAR_EXT

    • VK_COLOR_SPACE_DISPLAY_P3_NONLINEAR_EXT

    • VK_COLOR_SPACE_DOLBYVISION_EXT

    • VK_COLOR_SPACE_EXTENDED_SRGB_LINEAR_EXT

    • VK_COLOR_SPACE_EXTENDED_SRGB_NONLINEAR_EXT

    • VK_COLOR_SPACE_HDR10_HLG_EXT

    • VK_COLOR_SPACE_HDR10_ST2084_EXT

    • VK_COLOR_SPACE_PASS_THROUGH_EXT

Issues

1) Does the spec need to specify which kinds of image formats support the color spaces?

RESOLVED: Pixel format is independent of color space (though some color spaces really want / need floating point color components to be useful). Therefore, do not plan on documenting what formats support which colorspaces. An application can call vkGetPhysicalDeviceSurfaceFormatsKHR to query what a particular implementation supports.

2) How does application determine if HW supports appropriate transfer function for a colorspace?

RESOLVED: Extension indicates that implementation must not do the OETF encoding if it is not sRGB. That responsibility falls to the application shaders. Any other native OETF / EOTF functions supported by an implementation can be described by separate extension.

Version History

  • Revision 1, 2016-12-27 (Courtney Goeltzenleuchter)

    • Initial version

  • Revision 2, 2017-01-19 (Courtney Goeltzenleuchter)

    • Add pass through and multiple options for BT2020.

    • Clean up some issues with equations not displaying properly.

  • Revision 3, 2017-06-23 (Courtney Goeltzenleuchter)

    • Add extended sRGB non-linear enum.

  • Revision 4, 2019-04-26 (Graeme Leese)

    • Clarify colorspace transfer function usage.

    • Refer to normative definitions in the Data Format Specification.

    • Clarify DCI-P3 and Display P3 usage.

VK_EXT_texel_buffer_alignment

Name String

VK_EXT_texel_buffer_alignment

Extension Type

Device extension

Registered Extension Number

282

Revision

1

Extension and Version Dependencies
Contact

Other Extension Metadata

Last Modified Date

2019-06-06

IP Status

No known IP claims.

Interactions and External Dependencies
Contributors
  • Jeff Bolz, NVIDIA

Description

This extension adds more expressive alignment requirements for uniform and storage texel buffers. Some implementations have single texel alignment requirements that can’t be expressed via VkPhysicalDeviceLimits::minTexelBufferOffsetAlignment.

New Enum Constants

  • VK_EXT_TEXEL_BUFFER_ALIGNMENT_EXTENSION_NAME

  • VK_EXT_TEXEL_BUFFER_ALIGNMENT_SPEC_VERSION

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_TEXEL_BUFFER_ALIGNMENT_FEATURES_EXT

    • VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_TEXEL_BUFFER_ALIGNMENT_PROPERTIES_EXT

Version History

  • Revision 1, 2019-06-06 (Jeff Bolz)

    • Initial draft

VK_EXT_texture_compression_astc_hdr

Name String

VK_EXT_texture_compression_astc_hdr

Extension Type

Device extension

Registered Extension Number

67

Revision

1

Extension and Version Dependencies
Contact

Other Extension Metadata

Last Modified Date

2019-05-28

IP Status

No known issues.

Contributors
  • Jan-Harald Fredriksen, Arm

Description

This extension adds support for textures compressed using the Adaptive Scalable Texture Compression (ASTC) High Dynamic Range (HDR) profile.

When this extension is enabled, the HDR profile is supported for all ASTC formats listed in ASTC Compressed Image Formats.

New Enum Constants

  • VK_EXT_TEXTURE_COMPRESSION_ASTC_HDR_EXTENSION_NAME

  • VK_EXT_TEXTURE_COMPRESSION_ASTC_HDR_SPEC_VERSION

  • Extending VkFormat:

    • VK_FORMAT_ASTC_10x10_SFLOAT_BLOCK_EXT

    • VK_FORMAT_ASTC_10x5_SFLOAT_BLOCK_EXT

    • VK_FORMAT_ASTC_10x6_SFLOAT_BLOCK_EXT

    • VK_FORMAT_ASTC_10x8_SFLOAT_BLOCK_EXT

    • VK_FORMAT_ASTC_12x10_SFLOAT_BLOCK_EXT

    • VK_FORMAT_ASTC_12x12_SFLOAT_BLOCK_EXT

    • VK_FORMAT_ASTC_4x4_SFLOAT_BLOCK_EXT

    • VK_FORMAT_ASTC_5x4_SFLOAT_BLOCK_EXT

    • VK_FORMAT_ASTC_5x5_SFLOAT_BLOCK_EXT

    • VK_FORMAT_ASTC_6x5_SFLOAT_BLOCK_EXT

    • VK_FORMAT_ASTC_6x6_SFLOAT_BLOCK_EXT

    • VK_FORMAT_ASTC_8x5_SFLOAT_BLOCK_EXT

    • VK_FORMAT_ASTC_8x6_SFLOAT_BLOCK_EXT

    • VK_FORMAT_ASTC_8x8_SFLOAT_BLOCK_EXT

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_TEXTURE_COMPRESSION_ASTC_HDR_FEATURES_EXT

Issues

1) Should we add a feature or limit for this functionality?

Yes. It is consistent with the ASTC LDR support to add a feature like textureCompressionASTC_HDR.

The feature is strictly speaking redundant as long as this is just an extension; it would be sufficient to just enable the extension. But adding the feature is more forward-looking if wanted to make this an optional core feature in the future.

2) Should we introduce new format enums for HDR?

Yes. Vulkan 1.0 describes the ASTC format enums as UNORM, e.g. VK_FORMAT_ASTC_4x4_UNORM_BLOCK, so it’s confusing to make these contain HDR data. Note that the OpenGL (ES) extensions did not make this distinction because a single ASTC HDR texture may contain both unorm and float blocks. Implementations may not be able to distinguish between LDR and HDR ASTC textures internally and just treat them as the same format, i.e. if this extension is supported then sampling from a VK_FORMAT_ASTC_4x4_UNORM_BLOCK image format may return HDR results. Applications can get predictable results by using the appropriate image format.

Version History

  • Revision 1, 2019-05-28 (Jan-Harald Fredriksen)

    • Initial version

VK_EXT_tooling_info

Name String

VK_EXT_tooling_info

Extension Type

Device extension

Registered Extension Number

246

Revision

1

Extension and Version Dependencies
  • Requires Vulkan 1.0

Contact

Other Extension Metadata

Last Modified Date

2018-11-05

Contributors
  • Rolando Caloca

  • Matthaeus Chajdas

  • Baldur Karlsson

  • Daniel Rakos

Description

When an error occurs during application development, a common question is "What tools are actually running right now?" This extension adds the ability to query that information directly from the Vulkan implementation.

Outdated versions of one tool might not play nicely with another, or perhaps a tool is not actually running when it should have been. Trying to figure that out can cause headaches as it is necessary to consult each known tool to figure out what is going on — in some cases the tool might not even be known.

Typically, the expectation is that developers will simply print out this information for visual inspection when an issue occurs, however a small amount of semantic information about what the tool is doing is provided to help identify it programmatically. For example, if the advertised limits or features of an implementation are unexpected, is there a tool active which modifies these limits? Or if an application is providing debug markers, but the implementation is not actually doing anything with that information, this can quickly point that out.

New Bitmasks

New Enum Constants

  • VK_EXT_TOOLING_INFO_EXTENSION_NAME

  • VK_EXT_TOOLING_INFO_SPEC_VERSION

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_TOOL_PROPERTIES_EXT

If VK_EXT_debug_marker is supported:

If VK_EXT_debug_report is supported:

If VK_EXT_debug_utils is supported:

Examples

Printing Tool Information
uint32_t num_tools;
VkPhysicalDeviceToolPropertiesEXT *pToolProperties;
vkGetPhysicalDeviceToolPropertiesEXT(physicalDevice, &num_tools, NULL);

pToolProperties = (VkPhysicalDeviceToolPropertiesEXT*)malloc(sizeof(VkPhysicalDeviceToolPropertiesEXT) * num_tools);

vkGetPhysicalDeviceToolPropertiesEXT(physicalDevice, &num_tools, pToolProperties);

for (int i = 0; i < num_tools; ++i) {
    printf("%s:\n", pToolProperties[i].name);
    printf("Version:\n");
    printf("%s:\n", pToolProperties[i].version);
    printf("Description:\n");
    printf("\t%s\n", pToolProperties[i].description);
    printf("Purposes:\n");
    printf("\t%s\n", VkToolPurposeFlagBitsEXT_to_string(pToolProperties[i].purposes));
    if (strnlen_s(pToolProperties[i].layer,VK_MAX_EXTENSION_NAME_SIZE) > 0) {
        printf("Corresponding Layer:\n");
        printf("\t%s\n", pToolProperties[i].layer);
    }
}

Issues

1) Why is this information separate from the layer mechanism?

Some tooling may be built into a driver, or be part of the Vulkan loader etc. - and so tying this information directly to layers would’ve been awkward at best.

Version History

  • Revision 1, 2018-11-05 (Tobias Hector)

    • Initial draft

VK_EXT_transform_feedback

Name String

VK_EXT_transform_feedback

Extension Type

Device extension

Registered Extension Number

29

Revision

1

Extension and Version Dependencies
Contact

Other Extension Metadata

Last Modified Date

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

Description

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

  • VK_EXT_TRANSFORM_FEEDBACK_EXTENSION_NAME

  • VK_EXT_TRANSFORM_FEEDBACK_SPEC_VERSION

  • Extending VkAccessFlagBits:

    • VK_ACCESS_TRANSFORM_FEEDBACK_COUNTER_READ_BIT_EXT

    • VK_ACCESS_TRANSFORM_FEEDBACK_COUNTER_WRITE_BIT_EXT

    • VK_ACCESS_TRANSFORM_FEEDBACK_WRITE_BIT_EXT

  • Extending VkBufferUsageFlagBits:

    • VK_BUFFER_USAGE_TRANSFORM_FEEDBACK_BUFFER_BIT_EXT

    • VK_BUFFER_USAGE_TRANSFORM_FEEDBACK_COUNTER_BUFFER_BIT_EXT

  • Extending VkPipelineStageFlagBits:

    • VK_PIPELINE_STAGE_TRANSFORM_FEEDBACK_BIT_EXT

  • Extending VkQueryType:

    • VK_QUERY_TYPE_TRANSFORM_FEEDBACK_STREAM_EXT

  • 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

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

Other Extension Metadata

Last Modified Date

2017-08-29

IP Status

No known IP claims.

Contributors
  • Cort Stratton, Google

  • Chris Forbes, Google

Description

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

  • VK_EXT_VALIDATION_CACHE_EXTENSION_NAME

  • VK_EXT_VALIDATION_CACHE_SPEC_VERSION

  • Extending VkObjectType:

    • VK_OBJECT_TYPE_VALIDATION_CACHE_EXT

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_SHADER_MODULE_VALIDATION_CACHE_CREATE_INFO_EXT

    • VK_STRUCTURE_TYPE_VALIDATION_CACHE_CREATE_INFO_EXT

Version History

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

    • Initial draft

VK_EXT_validation_features

Name String

VK_EXT_validation_features

Extension Type

Instance extension

Registered Extension Number

248

Revision

3

Extension and Version Dependencies
  • Requires Vulkan 1.0

Contact

Other Extension Metadata

Last Modified Date

2018-11-14

IP Status

No known IP claims.

Contributors
  • Karl Schultz, LunarG

  • Dave Houlton, LunarG

  • Mark Lobodzinski, LunarG

  • Camden Stocker, LunarG

  • Tony Barbour, LunarG

Description

This extension provides the VkValidationFeaturesEXT struct that can be included in the pNext chain of the VkInstanceCreateInfo structure passed as the pCreateInfo parameter of vkCreateInstance. The structure contains an array of VkValidationFeatureEnableEXT enum values that enable specific validation features that are disabled by default. The structure also contains an array of VkValidationFeatureDisableEXT enum values that disable specific validation layer features that are enabled by default.

Note

The VK_EXT_validation_features extension subsumes all the functionality provided in the VK_EXT_validation_flags extension.

New Structures

New Enum Constants

  • VK_EXT_VALIDATION_FEATURES_EXTENSION_NAME

  • VK_EXT_VALIDATION_FEATURES_SPEC_VERSION

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_VALIDATION_FEATURES_EXT

Version History

  • Revision 1, 2018-11-14 (Karl Schultz)

    • Initial revision

  • Revision 2, 2019-08-06 (Mark Lobodzinski)

    • Add Best Practices enable

  • Revision 3, 2020-03-04 (Tony Barbour)

    • Add Debug Printf enable

VK_EXT_vertex_attribute_divisor

Name String

VK_EXT_vertex_attribute_divisor

Extension Type

Device extension

Registered Extension Number

191

Revision

3

Extension and Version Dependencies
Contact

Other Extension Metadata

Last Modified Date

2018-08-03

IP Status

No known IP claims.

Contributors
  • Vikram Kushwaha, NVIDIA

  • Jason Ekstrand, Intel

Description

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

  • VK_EXT_VERTEX_ATTRIBUTE_DIVISOR_EXTENSION_NAME

  • VK_EXT_VERTEX_ATTRIBUTE_DIVISOR_SPEC_VERSION

  • Extending VkStructureType:

    • VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VERTEX_ATTRIBUTE_DIVISOR_FEATURES_EXT

    • VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VERTEX_ATTRIBUTE_DIVISOR_PROPERTIES_EXT

    • VK_STRUCTURE_TYPE_PIPELINE_VERTEX_INPUT_DIVISOR_STATE_CREATE_INFO_EXT

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,