Vulkan Logo

1. Preamble

Copyright 2014-2024 The Khronos Group Inc.

This Specification is protected by copyright laws and contains material proprietary to Khronos. Except as described by these terms, it or any components may not be reproduced, republished, distributed, transmitted, displayed, broadcast or otherwise exploited in any manner without the express prior written permission of Khronos.

Khronos grants a conditional copyright license to use and reproduce the unmodified Specification for any purpose, without fee or royalty, EXCEPT no licenses to any patent, trademark or other intellectual property rights are granted under these terms.

Khronos makes no, and expressly disclaims any, representations or warranties, express or implied, regarding this Specification, including, without limitation: merchantability, fitness for a particular purpose, non-infringement of any intellectual property, correctness, accuracy, completeness, timeliness, and reliability. Under no circumstances will Khronos, or any of its Promoters, Contributors or Members, or their respective partners, officers, directors, employees, agents or representatives be liable for any damages, whether direct, indirect, special or consequential damages for lost revenues, lost profits, or otherwise, arising from or in connection with these materials.

This document contains extensions which are not ratified by Khronos, and as such is not a ratified Specification, though it contains text from (and is a superset of) the ratified Vulkan Specification. The ratified versions of the Vulkan Specification can be found at https://registry.khronos.org/vulkan/specs/1.3/html/vkspec.html (core only) and https://registry.khronos.org/vulkan/specs/1.3-khr-extensions/html/vkspec.html (core with all ratified extensions) .

This Specification contains substantially unmodified functionality from, and is a successor to, Khronos specifications including OpenGL, OpenGL ES and OpenCL.

The Khronos Intellectual Property Rights Policy defines the terms 'Scope', 'Compliant Portion', and 'Necessary Patent Claims'.

Some parts of this Specification are purely informative and so are EXCLUDED the Scope of this Specification. The Document Conventions section of the Introduction defines how these parts of the Specification are identified.

Where this Specification uses technical terminology, defined in the Glossary or otherwise, that refer to enabling technologies that are not expressly set forth in this Specification, those enabling technologies are EXCLUDED from the Scope of this Specification. For clarity, enabling technologies not disclosed with particularity in this Specification (e.g. semiconductor manufacturing technology, hardware architecture, processor architecture or microarchitecture, memory architecture, compiler technology, object oriented technology, basic operating system technology, compression technology, algorithms, and so on) are NOT to be considered expressly set forth; only those application program interfaces and data structures disclosed with particularity are included in the Scope of this Specification.

For purposes of the Khronos Intellectual Property Rights Policy as it relates to the definition of Necessary Patent Claims, all recommended or optional features, behaviors and functionality set forth in this Specification, if implemented, are considered to be included as Compliant Portions.

Where this Specification identifies specific sections of external references, only those specifically identified sections define normative functionality. The Khronos Intellectual Property Rights Policy excludes external references to materials and associated enabling technology not created by Khronos from the Scope of this Specification, and any licenses that may be required to implement such referenced materials and associated technologies must be obtained separately and may involve royalty payments.

Khronos and Vulkan are registered trademarks, and SPIR-V is a trademark of The Khronos Group Inc. OpenCL is a trademark of Apple Inc., used under license by Khronos. OpenGL is a registered trademark and the OpenGL ES logo is a trademark of Hewlett Packard Enterprise, used under license by Khronos. ASTC is a trademark of ARM Holdings PLC. All other product names, trademarks, and/or company names are used solely for identification and belong to their respective owners.

2. Introduction

This document, referred to as the “Vulkan Specification” or just the “Specification” hereafter, describes the Vulkan Application Programming Interface (API). Vulkan is a C99 API designed for explicit control of low-level graphics and compute functionality.

The canonical version of the Specification is available in the official Vulkan Registry (https://registry.khronos.org/vulkan/). The source files used to generate the Vulkan specification are stored in the Vulkan Documentation Repository (https://github.com/KhronosGroup/Vulkan-Docs).

The source repository additionally has a public issue tracker and allows the submission of pull requests that improve the specification.

2.1. Document Conventions

The Vulkan specification is intended for use by both implementors of the API and application developers seeking to make use of the API, forming a contract between these parties. Specification text may address either party; typically the intended audience can be inferred from context, though some sections are defined to address only one of these parties. (For example, Valid Usage sections only address application developers). Any requirements, prohibitions, recommendations or options defined by normative terminology are imposed only on the audience of that text.

Note

Structure and enumerated types defined in extensions that were promoted to core in a later version of Vulkan are now defined in terms of the equivalent Vulkan core interfaces. This affects the Vulkan Specification, the Vulkan header files, and the corresponding XML Registry.

2.1.1. Ratification

Ratification of a Vulkan core version or extension is a status conferred by vote of the Khronos Board of Promoters, bringing that core version or extension under the umbrella of the Khronos IP Policy.

All Vulkan core versions and KHR extensions (including provisional specifications) are ratified, as are some multi-vendor EXT extensions. Ratification status of extensions is described in the Layers & Extensions (Informative) appendix.

Note

Ratification status is primarily of interest to IHVs developing GPU hardware and Vulkan implementations

For developers, ratification does not necessarily mean that an extension is “better”; has a more stable API; or is more widely supported than alternative ways of achieving that functionality.

Interactions between ratified and non-ratified extensions are not themselves ratified.

2.1.2. Informative Language

Some language in the specification is purely informative, intended to give background or suggestions to implementors or developers.

If an entire chapter or section contains only informative language, its title will be suffixed with “(Informative)”.

All NOTEs are implicitly informative.

2.1.3. Normative Terminology

Within this specification, the key words must, required, should, recommended, may, and optional are to be interpreted as described in RFC 2119 - Key words for use in RFCs to Indicate Requirement Levels (https://www.ietf.org/rfc/rfc2119.txt). The additional key word optionally is an alternate form of optional, for use where grammatically appropriate.

These key words are highlighted in the specification for clarity. In text addressing application developers, their use expresses requirements that apply to application behavior. In text addressing implementors, their use expresses requirements that apply to implementations.

In text addressing application developers, the additional key words can and cannot are to be interpreted as describing the capabilities of an application, as follows:

can

This word means that the application is able to perform the action described.

cannot

This word means that the API and/or the execution environment provide no mechanism through which the application can express or accomplish the action described.

These key words are never used in text addressing implementors.

Note

There is an important distinction between cannot and must not, as used in this Specification. Cannot means something the application literally is unable to express or accomplish through the API, while must not means something that the application is capable of expressing through the API, but that the consequences of doing so are undefined and potentially unrecoverable for the implementation (see Valid Usage).

Unless otherwise noted in the section heading, all sections and appendices in this document are normative.

2.1.4. Technical Terminology

The Vulkan Specification makes use of common engineering and graphics terms such as Pipeline, Shader, and Host to identify and describe Vulkan API constructs and their attributes, states, and behaviors. The Glossary defines the basic meanings of these terms in the context of the Specification. The Specification text provides fuller definitions of the terms and may elaborate, extend, or clarify the Glossary definitions. When a term defined in the Glossary is used in normative language within the Specification, the definitions within the Specification govern and supersede any meanings the terms may have in other technical contexts (i.e. outside the Specification).

2.1.5. Normative References

References to external documents are considered normative references if the Specification uses any of the normative terms defined in Normative Terminology to refer to them or their requirements, either as a whole or in part.

The following documents are referenced by normative sections of the specification:

IEEE. August, 2008. IEEE Standard for Floating-Point Arithmetic. IEEE Std 754-2008. https://dx.doi.org/10.1109/IEEESTD.2008.4610935 .

Andrew Garrard. Khronos Data Format Specification, version 1.3. https://registry.khronos.org/DataFormat/specs/1.3/dataformat.1.3.html .

John Kessenich. SPIR-V Extended Instructions for GLSL, Version 1.00 (February 10, 2016). https://registry.khronos.org/spir-v/ .

John Kessenich, Boaz Ouriel, and Raun Krisch. SPIR-V Specification, Version 1.5, Revision 3, Unified (April 24, 2020). https://registry.khronos.org/spir-v/ .

ITU-T. H.264 Advanced Video Coding for Generic Audiovisual Services (August, 2021). https://www.itu.int/rec/T-REC-H.264-202108-I/ .

ITU-T. H.265 High Efficiency Video Coding (August, 2021). https://www.itu.int/rec/T-REC-H.265-202108-S/ .

Alliance for Open Media. AV1 Bitstream & Decoding Process Specification (January 8, 2019). https://aomediacodec.github.io/av1-spec/av1-spec.pdf .

Jon Leech. The Khronos Vulkan API Registry (February 26, 2023). https://registry.khronos.org/vulkan/specs/1.3/registry.html .

Jon Leech and Tobias Hector. Vulkan Documentation and Extensions: Procedures and Conventions (February 26, 2023). https://registry.khronos.org/vulkan/specs/1.3/styleguide.html .

Architecture of the Vulkan Loader Interfaces (October, 2021). https://github.com/KhronosGroup/Vulkan-Loader/blob/main/docs/LoaderInterfaceArchitecture.md .

3. Fundamentals

This chapter introduces fundamental concepts including the Vulkan architecture and execution model, API syntax, queues, pipeline configurations, numeric representation, state and state queries, and the different types of objects and shaders. It provides a framework for interpreting more specific descriptions of commands and behavior in the remainder of the Specification.

3.1. Host and Device Environment

The Vulkan Specification assumes and requires: the following properties of the host environment with respect to Vulkan implementations:

  • The host must have runtime support for 8, 16, 32 and 64-bit signed and unsigned twos-complement integers, all addressable at the granularity of their size in bytes.

  • The host must have runtime support for 32- and 64-bit floating-point types satisfying the range and precision constraints in the Floating-Point Computation section.

  • The representation and endianness of these types on the host must match the representation and endianness of the same types on every physical device supported.

Note

Since a variety of data types and structures in Vulkan may be accessible by both host and physical device operations, the implementation should be able to access such data efficiently in both paths in order to facilitate writing portable and performant applications.

3.2. Execution Model

This section outlines the execution model of a Vulkan system.

Vulkan exposes one or more devices, each of which exposes one or more queues which may process work asynchronously to one another. The set of queues supported by a device is partitioned into families. Each family supports one or more types of functionality and may contain multiple queues with similar characteristics. Queues within a single family are considered compatible with one another, and work produced for a family of queues can be executed on any queue within that family. This specification defines the following types of functionality that queues may support: graphics, compute, video decode, video encode, protected memory management, sparse memory management, and transfer.

Note

A single device may report multiple similar queue families rather than, or as well as, reporting multiple members of one or more of those families. This indicates that while members of those families have similar capabilities, they are not directly compatible with one another.

Device memory is explicitly managed by the application. Each device may advertise one or more heaps, representing different areas of memory. Memory heaps are either device-local or host-local, but are always visible to the device. Further detail about memory heaps is exposed via memory types available on that heap. Examples of memory areas that may be available on an implementation include:

  • device-local is memory that is physically connected to the device.

  • device-local, host visible is device-local memory that is visible to the host.

  • host-local, host visible is memory that is local to the host and visible to the device and host.

On other architectures, there may only be a single heap that can be used for any purpose.

3.2.1. Queue Operation

Vulkan queues provide an interface to the execution engines of a device. Commands for these execution engines are recorded into command buffers ahead of execution time, and then submitted to a queue for execution. Once submitted to a queue, command buffers will begin and complete execution without further application intervention, though the order of this execution is dependent on a number of implicit and explicit ordering constraints.

Work is submitted to queues using queue submission commands that typically take the form vkQueue* (e.g. vkQueueSubmit , vkQueueBindSparse ), and can take a list of semaphores upon which to wait before work begins and a list of semaphores to signal once work has completed. The work itself, as well as signaling and waiting on the semaphores are all queue operations. Queue submission commands return control to the application once queue operations have been submitted - they do not wait for completion.

There are no implicit ordering constraints between queue operations on different queues, or between queues and the host, so these may operate in any order with respect to each other. Explicit ordering constraints between different queues or with the host can be expressed with semaphores and fences.

Command buffer submissions to a single queue respect submission order and other implicit ordering guarantees, but otherwise may overlap or execute out of order. Other types of batches and queue submissions against a single queue (e.g. sparse memory binding) have no implicit ordering constraints with any other queue submission or batch. Additional explicit ordering constraints between queue submissions and individual batches can be expressed with semaphores and fences.

Before a fence or semaphore is signaled, it is guaranteed that any previously submitted queue operations have completed execution, and that memory writes from those queue operations are available to future queue operations. Waiting on a signaled semaphore or fence guarantees that previous writes that are available are also visible to subsequent commands.

Command buffer boundaries, both between primary command buffers of the same or different batches or submissions as well as between primary and secondary command buffers, do not introduce any additional ordering constraints. In other words, submitting the set of command buffers (which can include executing secondary command buffers) between any semaphore or fence operations execute the recorded commands as if they had all been recorded into a single primary command buffer, except that the current state is reset on each boundary. Explicit ordering constraints can be expressed with explicit synchronization primitives.

There are a few implicit ordering guarantees between commands within a command buffer, but only covering a subset of execution. Additional explicit ordering constraints can be expressed with the various explicit synchronization primitives.

Note

Implementations have significant freedom to overlap execution of work submitted to a queue, and this is common due to deep pipelining and parallelism in Vulkan devices.

Commands recorded in command buffers can perform actions, set state that persists across commands, synchronize other commands, or indirectly launch other commands, with some commands fulfilling several of these roles. The “Command Properties” section for each such command lists which of these roles the command takes:

Action

Action commands perform operations that can update values in memory. E.g. draw commands, dispatch commands.

State

State setting commands update the current state of a command buffer, affecting the operation of future action commands.

Synchronization

Synchronization commands impose ordering constraints on action commands, by introducing explicit execution and memory dependencies.

Indirection

Indirection commands execute other commands which were not directly recorded in the same command buffer.

Note

In the absence of explicit synchronization or implicit ordering guarantees, action commands may overlap execution or execute out of order, potentially leading to data races. However, such reordering does not affect the current state observed by any action command. Each action command uses the state in effect at the point where the command occurs in the command buffer, regardless of when it is executed.

3.3. Object Model

The devices, queues, and other entities in Vulkan are represented by Vulkan objects. At the API level, all objects are referred to by handles. There are two classes of handles, dispatchable and non-dispatchable. Dispatchable handle types are a pointer to an opaque type. This pointer may be used by layers as part of intercepting API commands, and thus each API command takes a dispatchable type as its first parameter. Each object of a dispatchable type must have a unique handle value during its lifetime.

Non-dispatchable handle types are a 64-bit integer type whose meaning is implementation-dependent. If the privateData feature is enabled for a VkDevice, each object of a non-dispatchable type created on that device must have a handle value that is unique among objects created on that device, for the duration of the object’s lifetime. Otherwise, non-dispatchable handles may encode object information directly in the handle rather than acting as a reference to an underlying object, and thus may not have unique handle values. If handle values are not unique, then destroying one such handle must not cause identical handles of other types to become invalid, and must not cause identical handles of the same type to become invalid if that handle value has been created more times than it has been destroyed.

All objects created or allocated from a VkDevice (i.e. with a VkDevice as the first parameter) are private to that device, and must not be used on other devices.

3.3.1. Object Lifetime

Objects are created or allocated by vkCreate* and vkAllocate* commands, respectively. Once an object is created or allocated, its “structure” is considered to be immutable, though the contents of certain object types is still free to change. Objects are destroyed or freed by vkDestroy* and vkFree* commands, respectively.

Objects that are allocated (rather than created) take resources from an existing pool object or memory heap, and when freed return resources to that pool or heap. While object creation and destruction are generally expected to be low-frequency occurrences during runtime, allocating and freeing objects can occur at high frequency. Pool objects help accommodate improved performance of the allocations and frees.

It is an application’s responsibility to track the lifetime of Vulkan objects, and not to destroy them while they are still in use.

The ownership of application-owned memory is immediately acquired by any Vulkan command it is passed into. Ownership of such memory must be released back to the application at the end of the duration of the command, unless that command was deferred, so that the application can alter or free this memory as soon as all the commands that acquired it have returned. If the command was deferred, ownership of such memory is released back to the application when the deferred operation is complete.

The following object types are consumed when they are passed into a Vulkan command and not further accessed by the objects they are used to create. They must not be destroyed in the duration of any API command they are passed into:

  • VkShaderModule

  • VkPipelineCache

  • VkValidationCacheEXT

A VkRenderPass or VkPipelineLayout object passed as a parameter to create another object is not further accessed by that object after the duration of the command it is passed into. A VkRenderPass used in a command buffer follows the rules described below.

VkDescriptorSetLayout objects may be accessed by commands that operate on descriptor sets allocated using that layout, and those descriptor sets must not be updated with vkUpdateDescriptorSets after the descriptor set layout has been destroyed. Otherwise, a VkDescriptorSetLayout object is no longer referenced by an API command it is passed into once host execution of that command completes.

The application must not destroy any other type of Vulkan object until all uses of that object by the device (such as via command buffer execution) have completed.

The following Vulkan objects must not be destroyed while any command buffers using the object are in the pending state:

  • VkEvent

  • VkQueryPool

  • VkBuffer

  • VkBufferView

  • VkImage

  • VkImageView

  • VkPipeline

  • VkSampler

  • VkSamplerYcbcrConversion

  • VkDescriptorPool

  • VkFramebuffer

  • VkRenderPass

  • VkCommandBuffer

  • VkCommandPool

  • VkDeviceMemory

  • VkDescriptorSet

  • VkIndirectCommandsLayoutNV

  • VkIndirectCommandsLayoutEXT

  • VkIndirectExecutionSetEXT

  • VkAccelerationStructureNV

  • VkAccelerationStructureKHR

  • VkVideoSessionKHR

  • VkVideoSessionParametersKHR

Destroying these objects will move any command buffers that are in the recording or executable state, and are using those objects, to the invalid state.

The following Vulkan objects must not be destroyed while any queue is executing commands that use the object:

  • VkFence

  • VkSemaphore

  • VkCommandBuffer

  • VkCommandPool

In general, objects can be destroyed or freed in any order, even if the object being freed is involved in the use of another object (e.g. use of a resource in a view, use of a view in a descriptor set, use of a pipeline library in another pipeline, use of a referenced pipeline for additional graphics shader groups in another pipeline, use of a referenced object for additional shader-related states in a set, use of a bottom level acceleration structure in an instance referenced by a top level acceleration structure, use of an object in a command buffer, binding of a memory allocation to a resource), as long as any object that uses the freed object is not further used in any way except to be destroyed or to be reset in such a way that it no longer uses the other object (such as resetting a command buffer). If the object has been reset, then it can be used as if it never used the freed object. An exception to this is when there is a parent/child relationship between objects. In this case, the application must not destroy a parent object before its children, except when the parent is explicitly defined to free its children when it is destroyed (e.g. for pool objects, as defined below).

VkCommandPool objects are parents of VkCommandBuffer objects. VkDescriptorPool objects are parents of VkDescriptorSet objects. VkDevice objects are parents of many object types (all that take a VkDevice as a parameter to their creation).

The following Vulkan objects have specific restrictions for when they can be destroyed:

  • VkQueue objects cannot be explicitly destroyed. Instead, they are implicitly destroyed when the VkDevice object they are retrieved from is destroyed.

  • Destroying a pool object implicitly frees all objects allocated from that pool. Specifically, destroying VkCommandPool frees all VkCommandBuffer objects that were allocated from it, and destroying VkDescriptorPool frees all VkDescriptorSet objects that were allocated from it.

  • VkDevice objects can be destroyed when all VkQueue objects retrieved from them are idle, and all objects created from them have been destroyed.

    • This includes the following objects:

      • VkFence

      • VkSemaphore

      • VkEvent

      • VkQueryPool

      • VkBuffer

      • VkBufferView

      • VkImage

      • VkImageView

      • VkShaderModule

      • VkPipelineCache

      • VkPipeline

      • VkPipelineLayout

      • VkSampler

      • VkSamplerYcbcrConversion

      • VkDescriptorSetLayout

      • VkDescriptorPool

      • VkFramebuffer

      • VkRenderPass

      • VkCommandPool

      • VkCommandBuffer

      • VkDeviceMemory

      • VkValidationCacheEXT

      • VkAccelerationStructureNV

      • VkAccelerationStructureKHR

      • VkVideoSessionKHR

      • VkVideoSessionParametersKHR

  • VkPhysicalDevice objects cannot be explicitly destroyed. Instead, they are implicitly destroyed when the VkInstance object they are retrieved from is destroyed.

  • VkInstance objects can be destroyed once all VkDevice objects created from any of its VkPhysicalDevice objects have been destroyed.

3.3.2. External Object Handles

As defined above, the scope of object handles created or allocated from a VkDevice is limited to that logical device. Objects which are not in scope are said to be external. To bring an external object into scope, an external handle must be exported from the object in the source scope and imported into the destination scope.

Note

The scope of external handles and their associated resources may vary according to their type, but they can generally be shared across process and API boundaries.

3.4. Application Binary Interface

The mechanism by which Vulkan is made available to applications is platform- or implementation- defined. On many platforms the C interface described in this Specification is provided by a shared library. Since shared libraries can be changed independently of the applications that use them, they present particular compatibility challenges, and this Specification places some requirements on them.

Shared library implementations must use the default Application Binary Interface (ABI) of the standard C compiler for the platform, or provide customized API headers that cause application code to use the implementation’s non-default ABI. An ABI in this context means the size, alignment, and layout of C data types; the procedure calling convention; and the naming convention for shared library symbols corresponding to C functions. Customizing the calling convention for a platform is usually accomplished by defining calling convention macros appropriately in vk_platform.h.

On platforms where Vulkan is provided as a shared library, library symbols beginning with “vk” and followed by a digit or uppercase letter are reserved for use by the implementation. Applications which use Vulkan must not provide definitions of these symbols. This allows the Vulkan shared library to be updated with additional symbols for new API versions or extensions without causing symbol conflicts with existing applications.

Shared library implementations should provide library symbols for commands in the highest version of this Specification they support, and for Window System Integration extensions relevant to the platform. They may also provide library symbols for commands defined by additional extensions.

Note

These requirements and recommendations are intended to allow implementors to take advantage of platform-specific conventions for SDKs, ABIs, library versioning mechanisms, etc. while still minimizing the code changes necessary to port applications or libraries between platforms. Platform vendors, or providers of the de facto standard Vulkan shared library for a platform, are encouraged to document what symbols the shared library provides and how it will be versioned when new symbols are added.

Applications should only rely on shared library symbols for commands in the minimum core version required by the application. vkGetInstanceProcAddr and vkGetDeviceProcAddr should be used to obtain function pointers for commands in core versions beyond the application’s minimum required version.

3.5. Command Syntax and Duration

The Specification describes Vulkan commands as functions or procedures using C99 syntax. Language bindings for other languages such as C++ and JavaScript may allow for stricter parameter passing, or object-oriented interfaces.

Vulkan uses the standard C types for the base type of scalar parameters (e.g. types from <stdint.h>), with exceptions described below, or elsewhere in the text when appropriate:

VkBool32 represents boolean True and False values, since C does not have a sufficiently portable built-in boolean type:

// Provided by VK_VERSION_1_0
typedef uint32_t VkBool32;

VK_TRUE represents a boolean True (unsigned integer 1) value, and VK_FALSE a boolean False (unsigned integer 0) value.

All values returned from a Vulkan implementation in a VkBool32 will be either VK_TRUE or VK_FALSE.

Applications must not pass any other values than VK_TRUE or VK_FALSE into a Vulkan implementation where a VkBool32 is expected.

VK_TRUE is a constant representing a VkBool32 True value.

#define VK_TRUE                           1U

VK_FALSE is a constant representing a VkBool32 False value.

#define VK_FALSE                          0U

VkDeviceSize represents device memory size and offset values:

// Provided by VK_VERSION_1_0
typedef uint64_t VkDeviceSize;

VkDeviceAddress represents device buffer address values:

// Provided by VK_VERSION_1_0
typedef uint64_t VkDeviceAddress;

Commands that create Vulkan objects are of the form vkCreate* and take Vk*CreateInfo structures with the parameters needed to create the object. These Vulkan objects are destroyed with commands of the form vkDestroy*.

The last in-parameter to each command that creates or destroys a Vulkan object is pAllocator. The pAllocator parameter can be set to a non-NULL value such that allocations for the given object are delegated to an application provided callback; refer to the Memory Allocation chapter for further details.

Commands that allocate Vulkan objects owned by pool objects are of the form vkAllocate*, and take Vk*AllocateInfo structures. These Vulkan objects are freed with commands of the form vkFree*. These objects do not take allocators; if host memory is needed, they will use the allocator that was specified when their parent pool was created.

Commands are recorded into a command buffer by calling API commands of the form vkCmd*. Each such command may have different restrictions on where it can be used: in a primary and/or secondary command buffer, inside and/or outside a render pass, and in one or more of the supported queue types. These restrictions are documented together with the definition of each such command.

The duration of a Vulkan command refers to the interval between calling the command and its return to the caller.

3.5.1. Lifetime of Retrieved Results

Information is retrieved from the implementation with commands of the form vkGet* and vkEnumerate*.

Unless otherwise specified for an individual command, the results are invariant; that is, they will remain unchanged when retrieved again by calling the same command with the same parameters, so long as those parameters themselves all remain valid.

3.5.2. Array Results

Some query commands of the form vkGet* and vkEnumerate* enable retrieving multiple results in the form of a return array. Such commands typically have two pointer arguments as follows:

  • An element count pointer pointing to an integer variable, conventionally named as p*Count where * is the capitalized singular form of the name of the retrieved values.

  • A pointer to an array where the result array is retrieved, conventionally named as p* where * is the capitalized plural form of the name of the retrieved values.

If such commands are called with the array pointer set to NULL, then the number of retrievable elements is returned in the variable pointed to by the element count pointer. Otherwise, the element count pointer must point to a variable set by the application to the number of elements in the return array, and on return the variable is overwritten with the number of elements actually written to the return array. If the input element count is less than the number of retrievable array elements, the query will write only as many elements to the return array as specified by the element count variable set by the application, and the command will return VK_INCOMPLETE instead of VK_SUCCESS, to indicate that not all retrievable array elements were returned.

Note

In practice, this means that applications will typically call such query commands twice:

  • First, with the array pointer set to NULL, to retrieve the number of retrievable elements.

  • Second, with the array pointer pointing to an application allocated storage for at least as many elements as indicated by the variable pointed to by the element count pointer, to retrieve at most as many of the retrievable elements.

Query commands that return one or more structures, regardless of whether they return a single or an array of structures with or without a pNext chain, may also contain arrays within those structures. Such return arrays are typically defined in the form of two members as follows:

  • An integer value specifying the element count, conventionally named as *Count where * is the singular form of the name of the retrieved values.

  • A pointer to an array where the result array is retrieved, conventionally named as p* where * is the capitalized plural form of the name of the retrieved values.

Analogously to query commands that return multiple results, if the command is called with the array pointer member of the output structure in question set to NULL, then the number of retrievable elements is returned in the element count member of that output structure. Otherwise, the element count must specify the number of elements in the return array, and on return the element count member is overwritten with the number of elements actually written to the return array. If the input element count is less than the number of retrievable array elements, the query will write only as many elements to the return array as specified by the input element count, and the command will return VK_INCOMPLETE instead of VK_SUCCESS, if the query command has a VkResult return type, to indicate that not all retrievable array elements were returned.

Note

Applications need to separately track the value they provided as the input element count member for such arrays and compare those with the returned element counts in order to determine whether the actually returned element count is smaller than the size of the return array. Another side effect of this is that it is impossible for the application to determine if the number of retrievable elements has increased beyond the provided input element count so using return arrays in output structures should be limited to invariant array results. In practice, this means that applications will typically call such query commands multiple times:

  • First, with the array pointer member(s) set to NULL, to retrieve the number(s) of retrievable elements.

  • Second, with the array pointer(s) pointing to an application allocated storage for at least as many elements as indicated by the element count member(s), to retrieve at most as many of the retrievable elements.

  • Then the process may need to be repeated for all other newly introduced return arrays in any nested output structures indirectly specified through the previously retrieved result arrays.

Regardless of the type of query command, any array pointer member of an output structure must either be NULL, or point to an application-allocated array. Query commands must not return a pointer to implementation allocated storage in any output structure.

3.6. Threading Behavior

Vulkan is intended to provide scalable performance when used on multiple host threads. All commands support being called concurrently from multiple threads, but certain parameters, or components of parameters are defined to be externally synchronized. This means that the caller must guarantee that no more than one thread is using such a parameter at a given time.

More precisely, Vulkan commands use simple stores to update the state of Vulkan objects. A parameter declared as externally synchronized may have its contents updated at any time during the host execution of the command. If two commands operate on the same object and at least one of the commands declares the object to be externally synchronized, then the caller must guarantee not only that the commands do not execute simultaneously, but also that the two commands are separated by an appropriate memory barrier (if needed).

Note

Memory barriers are particularly relevant for hosts based on the ARM CPU architecture, which is more weakly ordered than many developers are accustomed to from x86/x64 programming. Fortunately, most higher-level synchronization primitives (like the pthread library) perform memory barriers as a part of mutual exclusion, so mutexing Vulkan objects via these primitives will have the desired effect.

Similarly the application must avoid any potential data hazard of application-owned memory that has its ownership temporarily acquired by a Vulkan command. While the ownership of application-owned memory remains acquired by a command the implementation may read the memory at any point, and it may write non-const qualified memory at any point. Parameters referring to non-const qualified application-owned memory are not marked explicitly as externally synchronized in the Specification.

If an application is using deferred host operations in a command, and that operation is successfully deferred, object parameters and application-owned memory passed to that command may be accessed at any time until the deferred operation is complete.

Many object types are immutable, meaning the objects cannot change once they have been created. These types of objects never need external synchronization, except that they must not be destroyed while they are in use on another thread. In certain special cases mutable object parameters are internally synchronized, making external synchronization unnecessary. Any command parameters that are not labeled as externally synchronized are either not mutated by the command or are internally synchronized. Additionally, certain objects related to a command’s parameters (e.g. command pools and descriptor pools) may be affected by a command, and must also be externally synchronized. These implicit parameters are documented as described below.

Parameters of commands that are externally synchronized are listed below.

Externally Synchronized Parameters

For VkPipelineCache objects created with flags containing VK_PIPELINE_CACHE_CREATE_EXTERNALLY_SYNCHRONIZED_BIT, the above table is extended with the pipelineCache parameter to vkCreate*Pipelines being externally synchronized.

There are also a few instances where a command can take in an application-allocated list whose contents are externally synchronized parameters. In these cases, the caller must guarantee that at most one thread is using a given element within the list at a given time. These parameters are listed below.

Externally Synchronized Parameter Lists

In addition, there are some implicit parameters that need to be externally synchronized. For example, when a commandBuffer parameter needs to be externally synchronized, it implies that the commandPool from which that command buffer was allocated also needs to be externally synchronized. The implicit parameters and their associated object are listed below.

Implicit Externally Synchronized Parameters

3.7. Valid Usage

Valid usage defines a set of conditions which must be met in order to achieve well-defined runtime behavior in an application. These conditions depend only on Vulkan state, and the parameters or objects whose usage is constrained by the condition.

The core layer assumes applications are using the API correctly. Except as documented elsewhere in the Specification, the behavior of the core layer to an application using the API incorrectly is undefined, and may include program termination. However, implementations must ensure that incorrect usage by an application does not affect the integrity of the operating system, the Vulkan implementation, or other applications in the system using Vulkan. In particular, any guarantees made by an operating system about whether memory from one process can be visible to another process or not must not be violated by a Vulkan implementation for any memory allocation. Vulkan implementations are not required to make additional security or integrity guarantees beyond those provided by the OS unless explicitly directed by the application’s use of a particular feature or extension.

Note

For instance, if an operating system guarantees that data in all its memory allocations are set to zero when newly allocated, the Vulkan implementation must make the same guarantees for any allocations it controls (e.g. VkDeviceMemory).

Similarly, if an operating system guarantees that use-after-free of host allocations will not result in values written by another process becoming visible, the same guarantees must be made by the Vulkan implementation for device memory.

If the protectedMemory feature is supported, the implementation provides additional guarantees when invalid usage occurs to prevent values in protected memory from being accessed or inferred outside of protected operations, as described in Protected Memory Access Rules.

Some valid usage conditions have dependencies on runtime limits or feature availability. It is possible to validate these conditions against Vulkan’s minimum supported values for these limits and features, or some subset of other known values.

Valid usage conditions do not cover conditions where well-defined behavior (including returning an error code) exists.

Valid usage conditions should apply to the command or structure where complete information about the condition would be known during execution of an application. This is such that a validation layer or linter can be written directly against these statements at the point they are specified.

Note

This does lead to some non-obvious places for valid usage statements. For instance, the valid values for a structure might depend on a separate value in the calling command. In this case, the structure itself will not reference this valid usage as it is impossible to determine validity from the structure that it is invalid - instead this valid usage would be attached to the calling command.

Another example is draw state - the state setters are independent, and can cause a legitimately invalid state configuration between draw calls; so the valid usage statements are attached to the place where all state needs to be valid - at the drawing command.

Valid usage conditions are described in a block labeled “Valid Usage” following each command or structure they apply to.

3.7.1. Usage Validation

Vulkan is a layered API. The lowest layer is the core Vulkan layer, as defined by this Specification. The application can use additional layers above the core for debugging, validation, and other purposes.

One of the core principles of Vulkan is that building and submitting command buffers should be highly efficient. Thus error checking and validation of state in the core layer is minimal, although more rigorous validation can be enabled through the use of layers.

Validation of correct API usage is left to validation layers. Applications should be developed with validation layers enabled, to help catch and eliminate errors. Once validated, released applications should not enable validation layers by default.

3.7.2. Implicit Valid Usage

Some valid usage conditions apply to all commands and structures in the API, unless explicitly denoted otherwise for a specific command or structure. These conditions are considered implicit, and are described in a block labeled “Valid Usage (Implicit)” following each command or structure they apply to. Implicit valid usage conditions are described in detail below.

Valid Usage for Object Handles

Any input parameter to a command that is an object handle must be a valid object handle, unless otherwise specified. An object handle is valid if:

  • It has been created or allocated by a previous, successful call to the API. Such calls are noted in the Specification.

  • It has not been deleted or freed by a previous call to the API. Such calls are noted in the Specification.

  • Any objects used by that object, either as part of creation or execution, must also be valid.

The reserved values VK_NULL_HANDLE and NULL can be used in place of valid non-dispatchable handles and dispatchable handles, respectively, when explicitly called out in the Specification. Any command that creates an object successfully must not return these values. It is valid to pass these values to vkDestroy* or vkFree* commands, which will silently ignore these values.

Valid Usage for Pointers

Any parameter that is a pointer must be a valid pointer only if it is explicitly called out by a Valid Usage statement.

A pointer is “valid” if it points at memory containing values of the number and type(s) expected by the command, and all fundamental types accessed through the pointer (e.g. as elements of an array or as members of a structure) satisfy the alignment requirements of the host processor.

Valid Usage for Strings

Any parameter that is a pointer to char must be a finite sequence of values terminated by a null character, or if explicitly called out in the Specification, can be NULL.

Strings specified as UTF-8 encoded must not contain invalid UTF-8 sequences. See String Representation for additional information about strings.

Valid Usage for Enumerated Types

Any parameter of an enumerated type must be a valid enumerant for that type. Use of an enumerant is valid if the following conditions are true:

  • The enumerant is defined as part of the enumerated type.

  • The enumerant is not a value suffixed with _MAX_ENUM.

    • This value exists only to ensure that C enum types are 32 bits in size and must not be used by applications.

  • If the enumerant is used in a function that has a VkInstance as its first parameter and either:

  • If the enumerant is used in a function that has a VkPhysicalDevice object as its first parameter and either:

  • If the enumerant is used in a function that has any other dispatchable object as its first parameter and either:

Additionally, if maintenance5 is supported, any integer value representable in the range valid for the defined type is valid when used in a function that has a VkPhysicalDevice object as its first parameter. Physical device queries will either return results indicating lack of support, or ignore unsupported values when used as a bit flag in a Vk*Flags* parameter.

Any enumerated type returned from a query command or otherwise output from Vulkan to the application must not have a reserved value. Reserved values are values not defined by any extension for that enumerated type.

Note

In some special cases, an enumerant is only meaningful if a feature defined by an extension is also enabled, as well as the extension itself. The global “valid enumerant” rule described here does not address such cases.
Note

This language is intended to accommodate cases such as “hidden” extensions known only to driver internals, or layers enabling extensions without knowledge of the application, without allowing return of values not defined by any extension.
Note

Application developers are encouraged to be careful when using switch statements with Vulkan API enums. This is because new extensions can add new values to existing enums. Using a default: statement within a switch may avoid future compilation issues.

This is particularly true for enums such as VkDriverId, which may have values added that do not belong to a corresponding new extension.
Valid Usage for Flags

A collection of flags is represented by a bitmask using the type VkFlags:

// Provided by VK_VERSION_1_0
typedef uint32_t VkFlags;

Bitmasks are passed to many commands and structures to compactly represent options, but VkFlags is not used directly in the API. Instead, a Vk*Flags type which is an alias of VkFlags, and whose name matches the corresponding Vk*FlagBits that are valid for that type, is used.

Any Vk*Flags member or parameter used in the API as an input must be a valid combination of bit flags. A valid combination is either zero or the bitwise OR of valid bit flags.

An individual bit flag is valid for a Vk*Flags type if it would be a valid enumerant when used with the equivalent Vk*FlagBits type, where the bits type is obtained by taking the flag type and replacing the trailing Flags with FlagBits. For example, a flag value of type VkColorComponentFlags must contain only bit flags defined by VkColorComponentFlagBits.

Any Vk*Flags member or parameter returned from a query command or otherwise output from Vulkan to the application may contain bit flags undefined in its corresponding Vk*FlagBits type. An application cannot rely on the state of these unspecified bits.

Only the low-order 31 bits (bit positions zero through 30) are available for use as flag bits.

Note

This restriction is due to poorly defined behavior by C compilers given a C enumerant value of 0x80000000. In some cases adding this enumerant value may increase the size of the underlying Vk*FlagBits type, breaking the ABI.

A collection of 64-bit flags is represented by a bitmask using the type VkFlags64:

// Provided by VK_VERSION_1_3, VK_KHR_synchronization2
typedef uint64_t VkFlags64;

When the 31 bits available in VkFlags are insufficient, the VkFlags64 type can be passed to commands and structures to represent up to 64 options. VkFlags64 is not used directly in the API. Instead, a Vk*Flags2 type which is an alias of VkFlags64, and whose name matches the corresponding Vk*FlagBits2 that are valid for that type, is used.

Any Vk*Flags2 member or parameter used in the API as an input must be a valid combination of bit flags. A valid combination is either zero or the bitwise OR of valid bit flags.

An individual bit flag is valid for a Vk*Flags2 type if it would be a valid enumerant when used with the equivalent Vk*FlagBits2 type, where the bits type is obtained by taking the flag type and replacing the trailing Flags2 with FlagBits2. For example, a flag value of type VkAccessFlags2KHR must contain only bit flags defined by VkAccessFlagBits2KHR.

Any Vk*Flags2 member or parameter returned from a query command or otherwise output from Vulkan to the application may contain bit flags undefined in its corresponding Vk*FlagBits2 type. An application cannot rely on the state of these unspecified bits.

Note

Both the Vk*FlagBits2 type, and the individual bits defined for that type, are defined as uint64_t integers in the C API. This is in contrast to the 32-bit types, where the Vk*FlagBits type is defined as a C enum and the individual bits as enumerants belonging to that enum. As a result, there is less compile time type checking possible for the 64-bit types. This is unavoidable since there is no sufficiently portable way to define a 64-bit enum type in C99.
Valid Usage for Structure Types

Any parameter that is a structure containing a sType member must have a value of sType which is a valid VkStructureType value matching the type of the structure.

Valid Usage for Structure Pointer Chains

Any parameter that is a structure containing a void* pNext member must have a value of pNext that is either NULL, or is a pointer to a valid extending structure, containing sType and pNext members as described in the Vulkan Documentation and Extensions document in the section “Extending Structures”. The set of structures connected by pNext pointers is referred to as a pNext chain.

Each structure included in the pNext chain must be defined at runtime by either:

  • a core version which is supported

  • an extension which is enabled

  • a supported device extension in the case of physical-device-level functionality added by the device extension

Each type of extending structure must not appear more than once in a pNext chain, including any aliases. This general rule may be explicitly overridden for specific structures.

Any component of the implementation (the loader, any enabled layers, and drivers) must skip over, without processing (other than reading the sType and pNext members) any extending structures in the chain not defined by core versions or extensions supported by that component.

As a convenience to implementations and layers needing to iterate through a structure pointer chain, the Vulkan API provides two base structures. These structures allow for some type safety, and can be used by Vulkan API functions that operate on generic inputs and outputs.

The VkBaseInStructure structure is defined as:

// Provided by VK_VERSION_1_0
typedef struct VkBaseInStructure {
    VkStructureType                    sType;
    const struct VkBaseInStructure*    pNext;
} VkBaseInStructure;

  • sType is the structure type of the structure being iterated through.

  • pNext is NULL or a pointer to the next structure in a structure chain.

VkBaseInStructure can be used to facilitate iterating through a read-only structure pointer chain.

The VkBaseOutStructure structure is defined as:

// Provided by VK_VERSION_1_0
typedef struct VkBaseOutStructure {
    VkStructureType               sType;
    struct VkBaseOutStructure*    pNext;
} VkBaseOutStructure;

  • sType is the structure type of the structure being iterated through.

  • pNext is NULL or a pointer to the next structure in a structure chain.

VkBaseOutStructure can be used to facilitate iterating through a structure pointer chain that returns data back to the application.

Valid Usage for Nested Structures

The above conditions also apply recursively to members of structures provided as input to a command, either as a direct argument to the command, or themselves a member of another structure.

Specifics on valid usage of each command are covered in their individual sections.

Valid Usage for Extensions

Instance-level functionality or behavior added by an instance extension to the API must not be used unless that extension is supported by the instance as determined by vkEnumerateInstanceExtensionProperties, and that extension is enabled in VkInstanceCreateInfo.

Physical-device-level functionality or behavior added by an instance extension to the API must not be used unless that extension is supported by the instance as determined by vkEnumerateInstanceExtensionProperties, and that extension is enabled in VkInstanceCreateInfo.

Physical-device-level functionality or behavior added by a device extension to the API must not be used unless the conditions described in Extending Physical Device From Device Extensions are met.

Device-level functionality added by a device extension that is dispatched from a VkDevice, or from a child object of a VkDevice must not be used unless that extension is supported by the device as determined by vkEnumerateDeviceExtensionProperties, and that extension is enabled in VkDeviceCreateInfo.

Valid Usage for Newer Core Versions

Instance-level functionality or behavior added by a new core version of the API must not be used unless it is supported by the instance as determined by vkEnumerateInstanceVersion and the specified version of VkApplicationInfo::apiVersion.

Physical-device-level functionality or behavior added by a new core version of the API must not be used unless it is supported by the physical device as determined by VkPhysicalDeviceProperties::apiVersion and the specified version of VkApplicationInfo::apiVersion.

Device-level functionality or behavior added by a new core version of the API must not be used unless it is supported by the device as determined by VkPhysicalDeviceProperties::apiVersion and the specified version of VkApplicationInfo::apiVersion.

3.8. VkResult Return Codes

While the core Vulkan API is not designed to capture incorrect usage, some circumstances still require return codes. Commands in Vulkan return their status via return codes that are in one of two categories:

  • Successful completion codes are returned when a command needs to communicate success or status information. All successful completion codes are non-negative values.

  • Runtime error codes are returned when a command needs to communicate a failure that could only be detected at runtime. All runtime error codes are negative values.

All return codes in Vulkan are reported via VkResult return values. The possible codes are:

// Provided by VK_VERSION_1_0
typedef enum VkResult {
    VK_SUCCESS = 0,
    VK_NOT_READY = 1,
    VK_TIMEOUT = 2,
    VK_EVENT_SET = 3,
    VK_EVENT_RESET = 4,
    VK_INCOMPLETE = 5,
    VK_ERROR_OUT_OF_HOST_MEMORY = -1,
    VK_ERROR_OUT_OF_DEVICE_MEMORY = -2,
    VK_ERROR_INITIALIZATION_FAILED = -3,
    VK_ERROR_DEVICE_LOST = -4,
    VK_ERROR_MEMORY_MAP_FAILED = -5,
    VK_ERROR_LAYER_NOT_PRESENT = -6,
    VK_ERROR_EXTENSION_NOT_PRESENT = -7,
    VK_ERROR_FEATURE_NOT_PRESENT = -8,
    VK_ERROR_INCOMPATIBLE_DRIVER = -9,
    VK_ERROR_TOO_MANY_OBJECTS = -10,
    VK_ERROR_FORMAT_NOT_SUPPORTED = -11,
    VK_ERROR_FRAGMENTED_POOL = -12,
    VK_ERROR_UNKNOWN = -13,
  // Provided by VK_VERSION_1_1
    VK_ERROR_OUT_OF_POOL_MEMORY = -1000069000,
  // Provided by VK_VERSION_1_1
    VK_ERROR_INVALID_EXTERNAL_HANDLE = -1000072003,
  // Provided by VK_VERSION_1_2
    VK_ERROR_FRAGMENTATION = -1000161000,
  // Provided by VK_VERSION_1_2
    VK_ERROR_INVALID_OPAQUE_CAPTURE_ADDRESS = -1000257000,
  // Provided by VK_VERSION_1_3
    VK_PIPELINE_COMPILE_REQUIRED = 1000297000,
  // Provided by VK_KHR_surface
    VK_ERROR_SURFACE_LOST_KHR = -1000000000,
  // Provided by VK_KHR_surface
    VK_ERROR_NATIVE_WINDOW_IN_USE_KHR = -1000000001,
  // Provided by VK_KHR_swapchain
    VK_SUBOPTIMAL_KHR = 1000001003,
  // Provided by VK_KHR_swapchain
    VK_ERROR_OUT_OF_DATE_KHR = -1000001004,
  // Provided by VK_KHR_display_swapchain
    VK_ERROR_INCOMPATIBLE_DISPLAY_KHR = -1000003001,
  // Provided by VK_EXT_debug_report
    VK_ERROR_VALIDATION_FAILED_EXT = -1000011001,
  // Provided by VK_NV_glsl_shader
    VK_ERROR_INVALID_SHADER_NV = -1000012000,
  // Provided by VK_KHR_video_queue
    VK_ERROR_IMAGE_USAGE_NOT_SUPPORTED_KHR = -1000023000,
  // Provided by VK_KHR_video_queue
    VK_ERROR_VIDEO_PICTURE_LAYOUT_NOT_SUPPORTED_KHR = -1000023001,
  // Provided by VK_KHR_video_queue
    VK_ERROR_VIDEO_PROFILE_OPERATION_NOT_SUPPORTED_KHR = -1000023002,
  // Provided by VK_KHR_video_queue
    VK_ERROR_VIDEO_PROFILE_FORMAT_NOT_SUPPORTED_KHR = -1000023003,
  // Provided by VK_KHR_video_queue
    VK_ERROR_VIDEO_PROFILE_CODEC_NOT_SUPPORTED_KHR = -1000023004,
  // Provided by VK_KHR_video_queue
    VK_ERROR_VIDEO_STD_VERSION_NOT_SUPPORTED_KHR = -1000023005,
  // Provided by VK_EXT_image_drm_format_modifier
    VK_ERROR_INVALID_DRM_FORMAT_MODIFIER_PLANE_LAYOUT_EXT = -1000158000,
  // Provided by VK_KHR_global_priority
    VK_ERROR_NOT_PERMITTED_KHR = -1000174001,
  // Provided by VK_EXT_full_screen_exclusive
    VK_ERROR_FULL_SCREEN_EXCLUSIVE_MODE_LOST_EXT = -1000255000,
  // Provided by VK_KHR_deferred_host_operations
    VK_THREAD_IDLE_KHR = 1000268000,
  // Provided by VK_KHR_deferred_host_operations
    VK_THREAD_DONE_KHR = 1000268001,
  // Provided by VK_KHR_deferred_host_operations
    VK_OPERATION_DEFERRED_KHR = 1000268002,
  // Provided by VK_KHR_deferred_host_operations
    VK_OPERATION_NOT_DEFERRED_KHR = 1000268003,
  // Provided by VK_KHR_video_encode_queue
    VK_ERROR_INVALID_VIDEO_STD_PARAMETERS_KHR = -1000299000,
  // Provided by VK_EXT_image_compression_control
    VK_ERROR_COMPRESSION_EXHAUSTED_EXT = -1000338000,
  // Provided by VK_EXT_shader_object
    VK_INCOMPATIBLE_SHADER_BINARY_EXT = 1000482000,
  // Provided by VK_KHR_pipeline_binary
    VK_PIPELINE_BINARY_MISSING_KHR = 1000483000,
  // Provided by VK_KHR_pipeline_binary
    VK_ERROR_NOT_ENOUGH_SPACE_KHR = -1000483000,
  // Provided by VK_KHR_maintenance1
    VK_ERROR_OUT_OF_POOL_MEMORY_KHR = VK_ERROR_OUT_OF_POOL_MEMORY,
  // Provided by VK_KHR_external_memory
    VK_ERROR_INVALID_EXTERNAL_HANDLE_KHR = VK_ERROR_INVALID_EXTERNAL_HANDLE,
  // Provided by VK_EXT_descriptor_indexing
    VK_ERROR_FRAGMENTATION_EXT = VK_ERROR_FRAGMENTATION,
  // Provided by VK_EXT_global_priority
    VK_ERROR_NOT_PERMITTED_EXT = VK_ERROR_NOT_PERMITTED_KHR,
  // Provided by VK_EXT_buffer_device_address
    VK_ERROR_INVALID_DEVICE_ADDRESS_EXT = VK_ERROR_INVALID_OPAQUE_CAPTURE_ADDRESS,
  // Provided by VK_KHR_buffer_device_address
    VK_ERROR_INVALID_OPAQUE_CAPTURE_ADDRESS_KHR = VK_ERROR_INVALID_OPAQUE_CAPTURE_ADDRESS,
  // Provided by VK_EXT_pipeline_creation_cache_control
    VK_PIPELINE_COMPILE_REQUIRED_EXT = VK_PIPELINE_COMPILE_REQUIRED,
  // Provided by VK_EXT_pipeline_creation_cache_control
    VK_ERROR_PIPELINE_COMPILE_REQUIRED_EXT = VK_PIPELINE_COMPILE_REQUIRED,
  // Provided by VK_EXT_shader_object
  // VK_ERROR_INCOMPATIBLE_SHADER_BINARY_EXT is a deprecated alias
    VK_ERROR_INCOMPATIBLE_SHADER_BINARY_EXT = VK_INCOMPATIBLE_SHADER_BINARY_EXT,
} VkResult;
Success Codes

  • VK_SUCCESS Command successfully completed

  • VK_NOT_READY A fence or query has not yet completed

  • VK_TIMEOUT A wait operation has not completed in the specified time

  • VK_EVENT_SET An event is signaled

  • VK_EVENT_RESET An event is unsignaled

  • VK_INCOMPLETE A return array was too small for the result

  • VK_SUBOPTIMAL_KHR A swapchain no longer matches the surface properties exactly, but can still be used to present to the surface successfully.

  • VK_THREAD_IDLE_KHR A deferred operation is not complete but there is currently no work for this thread to do at the time of this call.

  • VK_THREAD_DONE_KHR A deferred operation is not complete but there is no work remaining to assign to additional threads.

  • VK_OPERATION_DEFERRED_KHR A deferred operation was requested and at least some of the work was deferred.

  • VK_OPERATION_NOT_DEFERRED_KHR A deferred operation was requested and no operations were deferred.

  • VK_PIPELINE_COMPILE_REQUIRED A requested pipeline creation would have required compilation, but the application requested compilation to not be performed.

  • VK_PIPELINE_BINARY_MISSING_KHR The application attempted to create a pipeline binary by querying an internal cache, but the internal cache entry did not exist.

  • VK_INCOMPATIBLE_SHADER_BINARY_EXT The provided binary shader code is not compatible with this device.

    Note

    In the initial version of the VK_EXT_shader_object extension, this return code was named VK_ERROR_INCOMPATIBLE_SHADER_BINARY_EXT and improperly described as an error code. The name has been changed, but the old name is retained as an alias for compatibility with old code.
Error Codes

  • VK_ERROR_OUT_OF_HOST_MEMORY A host memory allocation has failed.

  • VK_ERROR_OUT_OF_DEVICE_MEMORY A device memory allocation has failed.

  • VK_ERROR_INITIALIZATION_FAILED Initialization of an object could not be completed for implementation-specific reasons.

  • VK_ERROR_DEVICE_LOST The logical or physical device has been lost. See Lost Device

  • VK_ERROR_MEMORY_MAP_FAILED Mapping of a memory object has failed.

  • VK_ERROR_LAYER_NOT_PRESENT A requested layer is not present or could not be loaded.

  • VK_ERROR_EXTENSION_NOT_PRESENT A requested extension is not supported.

  • VK_ERROR_FEATURE_NOT_PRESENT A requested feature is not supported.

  • VK_ERROR_INCOMPATIBLE_DRIVER The requested version of Vulkan is not supported by the driver or is otherwise incompatible for implementation-specific reasons.

  • VK_ERROR_TOO_MANY_OBJECTS Too many objects of the type have already been created.

  • VK_ERROR_FORMAT_NOT_SUPPORTED A requested format is not supported on this device.

  • VK_ERROR_FRAGMENTED_POOL A pool allocation has failed due to fragmentation of the pool’s memory. This must only be returned if no attempt to allocate host or device memory was made to accommodate the new allocation. This should be returned in preference to VK_ERROR_OUT_OF_POOL_MEMORY, but only if the implementation is certain that the pool allocation failure was due to fragmentation.

  • VK_ERROR_SURFACE_LOST_KHR A surface is no longer available.

  • VK_ERROR_NATIVE_WINDOW_IN_USE_KHR The requested window is already in use by Vulkan or another API in a manner which prevents it from being used again.

  • VK_ERROR_OUT_OF_DATE_KHR A surface has changed in such a way that it is no longer compatible with the swapchain, and further presentation requests using the swapchain will fail. Applications must query the new surface properties and recreate their swapchain if they wish to continue presenting to the surface.

  • VK_ERROR_INCOMPATIBLE_DISPLAY_KHR The display used by a swapchain does not use the same presentable image layout, or is incompatible in a way that prevents sharing an image.

  • VK_ERROR_INVALID_SHADER_NV One or more shaders failed to compile or link. More details are reported back to the application via VK_EXT_debug_report if enabled.

  • VK_ERROR_OUT_OF_POOL_MEMORY A pool memory allocation has failed. This must only be returned if no attempt to allocate host or device memory was made to accommodate the new allocation. If the failure was definitely due to fragmentation of the pool, VK_ERROR_FRAGMENTED_POOL should be returned instead.

  • VK_ERROR_INVALID_EXTERNAL_HANDLE An external handle is not a valid handle of the specified type.

  • VK_ERROR_FRAGMENTATION A descriptor pool creation has failed due to fragmentation.

  • VK_ERROR_INVALID_DEVICE_ADDRESS_EXT A buffer creation failed because the requested address is not available.

  • VK_ERROR_INVALID_OPAQUE_CAPTURE_ADDRESS A buffer creation or memory allocation failed because the requested address is not available. A shader group handle assignment failed because the requested shader group handle information is no longer valid.

  • VK_ERROR_FULL_SCREEN_EXCLUSIVE_MODE_LOST_EXT An operation on a swapchain created with VK_FULL_SCREEN_EXCLUSIVE_APPLICATION_CONTROLLED_EXT failed as it did not have exclusive full-screen access. This may occur due to implementation-dependent reasons, outside of the application’s control.

  • VK_ERROR_VALIDATION_FAILED_EXT A command failed because invalid usage was detected by the implementation or a validation-layer.

  • VK_ERROR_COMPRESSION_EXHAUSTED_EXT An image creation failed because internal resources required for compression are exhausted. This must only be returned when fixed-rate compression is requested.

  • VK_ERROR_IMAGE_USAGE_NOT_SUPPORTED_KHR The requested VkImageUsageFlags are not supported.

  • VK_ERROR_VIDEO_PICTURE_LAYOUT_NOT_SUPPORTED_KHR The requested video picture layout is not supported.

  • VK_ERROR_VIDEO_PROFILE_OPERATION_NOT_SUPPORTED_KHR A video profile operation specified via VkVideoProfileInfoKHR::videoCodecOperation is not supported.

  • VK_ERROR_VIDEO_PROFILE_FORMAT_NOT_SUPPORTED_KHR Format parameters in a requested VkVideoProfileInfoKHR chain are not supported.

  • VK_ERROR_VIDEO_PROFILE_CODEC_NOT_SUPPORTED_KHR Codec-specific parameters in a requested VkVideoProfileInfoKHR chain are not supported.

  • VK_ERROR_VIDEO_STD_VERSION_NOT_SUPPORTED_KHR The specified video Std header version is not supported.

  • VK_ERROR_INVALID_VIDEO_STD_PARAMETERS_KHR The specified Video Std parameters do not adhere to the syntactic or semantic requirements of the used video compression standard, or values derived from parameters according to the rules defined by the used video compression standard do not adhere to the capabilities of the video compression standard or the implementation.

  • VK_ERROR_NOT_PERMITTED_KHR The driver implementation has denied a request to acquire a priority above the default priority (VK_QUEUE_GLOBAL_PRIORITY_MEDIUM_EXT) because the application does not have sufficient privileges.

  • VK_ERROR_NOT_ENOUGH_SPACE_KHR The application did not provide enough space to return all the required data.

  • VK_ERROR_UNKNOWN An unknown error has occurred; either the application has provided invalid input, or an implementation failure has occurred.

If a command returns a runtime error, unless otherwise specified any output parameters will have undefined contents, except that if the output parameter is a structure with sType and pNext fields, those fields will be unmodified. Any structures chained from pNext will also have undefined contents, except that sType and pNext will be unmodified.

VK_ERROR_OUT_OF_*_MEMORY errors do not modify any currently existing Vulkan objects. Objects that have already been successfully created can still be used by the application.

Note

As a general rule, Free, Release, and Reset commands do not return VK_ERROR_OUT_OF_HOST_MEMORY, while any other command with a return code may return it. Any exceptions from this rule are described for those commands.

VK_ERROR_UNKNOWN will be returned by an implementation when an unexpected error occurs that cannot be attributed to valid behavior of the application and implementation. Under these conditions, it may be returned from any command returning a VkResult.

Note

VK_ERROR_UNKNOWN is not expected to ever be returned if the application behavior is valid, and if the implementation is bug-free. If VK_ERROR_UNKNOWN is received, the application should be checked against the latest validation layers to verify correct behavior as much as possible. If no issues are identified it could be an implementation issue, and the implementor should be contacted for support.

Any command returning a VkResult may return VK_ERROR_VALIDATION_FAILED_EXT if a violation of valid usage is detected, even though commands do not explicitly list this as a possible return code.

Performance-critical commands generally do not have return codes. If a runtime error occurs in such commands, the implementation will defer reporting the error until a specified point. For commands that record into command buffers (vkCmd*) runtime errors are reported by vkEndCommandBuffer.

3.9. Numeric Representation and Computation

Implementations normally perform computations in floating-point, and must meet the range and precision requirements defined under “Floating-Point Computation” below.

These requirements only apply to computations performed in Vulkan operations outside of shader execution, such as texture image specification and sampling, and per-fragment operations. Range and precision requirements during shader execution differ and are specified by the Precision and Operation of SPIR-V Instructions section.

In some cases, the representation and/or precision of operations is implicitly limited by the specified format of vertex or texel data consumed by Vulkan. Specific floating-point formats are described later in this section.

3.9.1. Floating-Point Computation

Most floating-point computation is performed in SPIR-V shader modules. The properties of computation within shaders are constrained as defined by the Precision and Operation of SPIR-V Instructions section.

Some floating-point computation is performed outside of shaders, such as viewport and depth range calculations. For these computations, we do not specify how floating-point numbers are to be represented, or the details of how operations on them are performed, but only place minimal requirements on representation and precision as described in the remainder of this section.

We require simply that numbers’ floating-point parts contain enough bits and that their exponent fields are large enough so that individual results of floating-point operations are accurate to about 1 part in 105. The maximum representable magnitude for all floating-point values must be at least 232.

x × 0 = 0 × x = 0 for any non-infinite and non-NaN x.

1 × x = x × 1 = x.

x + 0 = 0 + x = x.

00 = 1.

Occasionally, further requirements will be specified. Most single-precision floating-point formats meet these requirements.

The special values Inf and -Inf encode values with magnitudes too large to be represented; the special value NaN encodes “Not A Number” values resulting from undefined arithmetic operations such as 0 / 0. Implementations may support Inf and NaN in their floating-point computations. Any computation which does not support either Inf or NaN, for which that value is an input or output will yield an undefined value.

3.9.2. Floating-Point Format Conversions

When a value is converted to a defined floating-point representation, finite values falling between two representable finite values are rounded to one or the other. The rounding mode is not defined. Finite values whose magnitude is larger than that of any representable finite value may be rounded either to the closest representable finite value or to the appropriately signed infinity. For unsigned destination formats any negative values are converted to zero. Positive infinity is converted to positive infinity; negative infinity is converted to negative infinity in signed formats and to zero in unsigned formats; and any NaN is converted to a NaN.

3.9.3. 16-Bit Floating-Point Numbers

16-bit floating-point numbers are defined in the “16-bit floating-point numbers” section of the Khronos Data Format Specification.

3.9.4. Unsigned 11-Bit Floating-Point Numbers

Unsigned 11-bit floating-point numbers are defined in the “Unsigned 11-bit floating-point numbers” section of the Khronos Data Format Specification.

3.9.5. Unsigned 10-Bit Floating-Point Numbers

Unsigned 10-bit floating-point numbers are defined in the “Unsigned 10-bit floating-point numbers” section of the Khronos Data Format Specification.

3.9.6. General Requirements

Any representable floating-point value in the appropriate format is legal as input to a Vulkan command that requires floating-point data. The result of providing a value that is not a floating-point number to such a command is unspecified, but must not lead to Vulkan interruption or termination. For example, providing a negative zero (where applicable) or a denormalized number to a Vulkan command must yield deterministic results, while providing a NaN or Inf yields unspecified results.

Some calculations require division. In such cases (including implied divisions performed by vector normalization), division by zero produces an unspecified result but must not lead to Vulkan interruption or termination.

3.10. Fixed-Point Data Conversions

When generic vertex attributes and pixel color or depth components are represented as integers, they are often (but not always) considered to be normalized. Normalized integer values are treated specially when being converted to and from floating-point values, and are usually referred to as normalized fixed-point.

In the remainder of this section, b denotes the bit width of the fixed-point integer representation. When the integer is one of the types defined by the API, b is the bit width of that type. When the integer comes from an image containing color or depth component texels, b is the number of bits allocated to that component in its specified image format.

The signed and unsigned fixed-point representations are assumed to be b-bit binary two’s-complement integers and binary unsigned integers, respectively.

3.10.1. Conversion From Normalized Fixed-Point to Floating-Point

Unsigned normalized fixed-point integers represent numbers in the range [0,1]. The conversion from an unsigned normalized fixed-point value c to the corresponding floating-point value f is defined as

Signed normalized fixed-point integers represent numbers in the range [-1,1]. The conversion from a signed normalized fixed-point value c to the corresponding floating-point value f is performed using

Only the range [-2b-1 + 1, 2b-1 - 1] is used to represent signed fixed-point values in the range [-1,1]. For example, if b = 8, then the integer value -127 corresponds to -1.0 and the value 127 corresponds to 1.0. This equation is used everywhere that signed normalized fixed-point values are converted to floating-point.

Note that while zero is exactly expressible in this representation, one value (-128 in the example) is outside the representable range, and implementations must clamp it to -1.0. Where the value is subject to further processing by the implementation, e.g. during texture filtering, values less than -1.0 may be used but the result must be clamped before the value is returned to shaders.

3.10.2. Conversion From Floating-Point to Normalized Fixed-Point

The conversion from a floating-point value f to the corresponding unsigned normalized fixed-point value c is defined by first clamping f to the range [0,1], then computing

c = convertFloatToUint(f × (2b - 1), b)

where convertFloatToUint(r,b) returns one of the two unsigned binary integer values with exactly b bits which are closest to the floating-point value r. Implementations should round to nearest. If r is equal to an integer, then that integer value must be returned. In particular, if f is equal to 0.0 or 1.0, then c must be assigned 0 or 2b - 1, respectively.

The conversion from a floating-point value f to the corresponding signed normalized fixed-point value c is performed by clamping f to the range [-1,1], then computing

c = convertFloatToInt(f × (2b-1 - 1), b)

where convertFloatToInt(r,b) returns one of the two signed two’s-complement binary integer values with exactly b bits which are closest to the floating-point value r. Implementations should round to nearest. If r is equal to an integer, then that integer value must be returned. In particular, if f is equal to -1.0, 0.0, or 1.0, then c must be assigned -(2b-1 - 1), 0, or 2b-1 - 1, respectively.

This equation is used everywhere that floating-point values are converted to signed normalized fixed-point.

3.11. String Representation

Strings passed into and returned from Vulkan API commands are usually defined to be null-terminated and UTF-8 encoded.

Note

Exceptions to this rule exist only when strings are defined or used by operating system APIs where that OS has a different convention. For example, VkExportMemoryWin32HandleInfoKHR::name is a null-terminated UTF-16 encoded string used in conjunction with Windows handles.

When a UTF-8 string is returned from a Vulkan API query, it is returned in a fixed-length buffer of C char. For example, a string returned in VkPhysicalDeviceProperties::deviceName has maximum length VK_MAX_PHYSICAL_DEVICE_NAME_SIZE, and a string returned in VkExtensionProperties::extensionName has maximum length VK_MAX_EXTENSION_NAME_SIZE. The string, including its null terminator, will always fit completely within this buffer. If the string is shorter than the buffer size, the contents of char in the buffer following the null terminator are undefined.

When a UTF-8 string is passed into a Vulkan API, such as VkDeviceCreateInfo::ppEnabledExtensionNames, there is no explicit limit on the length of that string. However, the string must contain a valid UTF-8 encoded string and must be null-terminated.

3.12. Common Object Types

Some types of Vulkan objects are used in many different structures and command parameters, and are described here. These types include offsets, extents, and rectangles.

3.12.1. Offsets

Offsets are used to describe a pixel location within an image or framebuffer, as an (x,y) location for two-dimensional images, or an (x,y,z) location for three-dimensional images.

A two-dimensional offset is defined by the structure:

// Provided by VK_VERSION_1_0
typedef struct VkOffset2D {
    int32_t    x;
    int32_t    y;
} VkOffset2D;

  • x is the x offset.

  • y is the y offset.

A three-dimensional offset is defined by the structure:

// Provided by VK_VERSION_1_0
typedef struct VkOffset3D {
    int32_t    x;
    int32_t    y;
    int32_t    z;
} VkOffset3D;

  • x is the x offset.

  • y is the y offset.

  • z is the z offset.

3.12.2. Extents

Extents are used to describe the size of a rectangular region of pixels within an image or framebuffer, as (width,height) for two-dimensional images, or as (width,height,depth) for three-dimensional images.

A two-dimensional extent is defined by the structure:

// Provided by VK_VERSION_1_0
typedef struct VkExtent2D {
    uint32_t    width;
    uint32_t    height;
} VkExtent2D;

  • width is the width of the extent.

  • height is the height of the extent.

A three-dimensional extent is defined by the structure:

// Provided by VK_VERSION_1_0
typedef struct VkExtent3D {
    uint32_t    width;
    uint32_t    height;
    uint32_t    depth;
} VkExtent3D;

  • width is the width of the extent.

  • height is the height of the extent.

  • depth is the depth of the extent.

3.12.3. Rectangles

Rectangles are used to describe a specified rectangular region of pixels within an image or framebuffer. Rectangles include both an offset and an extent of the same dimensionality, as described above. Two-dimensional rectangles are defined by the structure

// Provided by VK_VERSION_1_0
typedef struct VkRect2D {
    VkOffset2D    offset;
    VkExtent2D    extent;
} VkRect2D;

  • offset is a VkOffset2D specifying the rectangle offset.

  • extent is a VkExtent2D specifying the rectangle extent.

3.12.4. Structure Types

Each value corresponds to a particular structure with a sType member with a matching name. As a general rule, the name of each VkStructureType value is obtained by taking the name of the structure, stripping the leading Vk, prefixing each capital letter with _, converting the entire resulting string to upper case, and prefixing it with VK_STRUCTURE_TYPE_. For example, structures of type VkImageCreateInfo correspond to a VkStructureType value of VK_STRUCTURE_TYPE_IMAGE_CREATE_INFO, and thus a structure of this type must have its sType member set to this value before it is passed to the API.

The values VK_STRUCTURE_TYPE_LOADER_INSTANCE_CREATE_INFO and VK_STRUCTURE_TYPE_LOADER_DEVICE_CREATE_INFO are reserved for internal use by the loader, and do not have corresponding Vulkan structures in this Specification.

Structure types supported by the Vulkan API include:

// Provided by VK_VERSION_1_0
typedef enum VkStructureType {
    VK_STRUCTURE_TYPE_APPLICATION_INFO = 0,
    VK_STRUCTURE_TYPE_INSTANCE_CREATE_INFO = 1,
    VK_STRUCTURE_TYPE_DEVICE_QUEUE_CREATE_INFO = 2,
    VK_STRUCTURE_TYPE_DEVICE_CREATE_INFO = 3,
    VK_STRUCTURE_TYPE_SUBMIT_INFO = 4,
    VK_STRUCTURE_TYPE_MEMORY_ALLOCATE_INFO = 5,
    VK_STRUCTURE_TYPE_MAPPED_MEMORY_RANGE = 6,
    VK_STRUCTURE_TYPE_BIND_SPARSE_INFO = 7,
    VK_STRUCTURE_TYPE_FENCE_CREATE_INFO = 8,
    VK_STRUCTURE_TYPE_SEMAPHORE_CREATE_INFO = 9,
    VK_STRUCTURE_TYPE_EVENT_CREATE_INFO = 10,
    VK_STRUCTURE_TYPE_QUERY_POOL_CREATE_INFO = 11,
    VK_STRUCTURE_TYPE_BUFFER_CREATE_INFO = 12,
    VK_STRUCTURE_TYPE_BUFFER_VIEW_CREATE_INFO = 13,
    VK_STRUCTURE_TYPE_IMAGE_CREATE_INFO = 14,
    VK_STRUCTURE_TYPE_IMAGE_VIEW_CREATE_INFO = 15,
    VK_STRUCTURE_TYPE_SHADER_MODULE_CREATE_INFO = 16,
    VK_STRUCTURE_TYPE_PIPELINE_CACHE_CREATE_INFO = 17,
    VK_STRUCTURE_TYPE_PIPELINE_SHADER_STAGE_CREATE_INFO = 18,
    VK_STRUCTURE_TYPE_PIPELINE_VERTEX_INPUT_STATE_CREATE_INFO = 19,
    VK_STRUCTURE_TYPE_PIPELINE_INPUT_ASSEMBLY_STATE_CREATE_INFO = 20,
    VK_STRUCTURE_TYPE_PIPELINE_TESSELLATION_STATE_CREATE_INFO = 21,
    VK_STRUCTURE_TYPE_PIPELINE_VIEWPORT_STATE_CREATE_INFO = 22,
    VK_STRUCTURE_TYPE_PIPELINE_RASTERIZATION_STATE_CREATE_INFO = 23,
    VK_STRUCTURE_TYPE_PIPELINE_MULTISAMPLE_STATE_CREATE_INFO = 24,
    VK_STRUCTURE_TYPE_PIPELINE_DEPTH_STENCIL_STATE_CREATE_INFO = 25,
    VK_STRUCTURE_TYPE_PIPELINE_COLOR_BLEND_STATE_CREATE_INFO = 26,
    VK_STRUCTURE_TYPE_PIPELINE_DYNAMIC_STATE_CREATE_INFO = 27,
    VK_STRUCTURE_TYPE_GRAPHICS_PIPELINE_CREATE_INFO = 28,
    VK_STRUCTURE_TYPE_COMPUTE_PIPELINE_CREATE_INFO = 29,
    VK_STRUCTURE_TYPE_PIPELINE_LAYOUT_CREATE_INFO = 30,
    VK_STRUCTURE_TYPE_SAMPLER_CREATE_INFO = 31,
    VK_STRUCTURE_TYPE_DESCRIPTOR_SET_LAYOUT_CREATE_INFO = 32,
    VK_STRUCTURE_TYPE_DESCRIPTOR_POOL_CREATE_INFO = 33,
    VK_STRUCTURE_TYPE_DESCRIPTOR_SET_ALLOCATE_INFO = 34,
    VK_STRUCTURE_TYPE_WRITE_DESCRIPTOR_SET = 35,
    VK_STRUCTURE_TYPE_COPY_DESCRIPTOR_SET = 36,
    VK_STRUCTURE_TYPE_FRAMEBUFFER_CREATE_INFO = 37,
    VK_STRUCTURE_TYPE_RENDER_PASS_CREATE_INFO = 38,
    VK_STRUCTURE_TYPE_COMMAND_POOL_CREATE_INFO = 39,
    VK_STRUCTURE_TYPE_COMMAND_BUFFER_ALLOCATE_INFO = 40,
    VK_STRUCTURE_TYPE_COMMAND_BUFFER_INHERITANCE_INFO = 41,
    VK_STRUCTURE_TYPE_COMMAND_BUFFER_BEGIN_INFO = 42,
    VK_STRUCTURE_TYPE_RENDER_PASS_BEGIN_INFO = 43,
    VK_STRUCTURE_TYPE_BUFFER_MEMORY_BARRIER = 44,
    VK_STRUCTURE_TYPE_IMAGE_MEMORY_BARRIER = 45,
    VK_STRUCTURE_TYPE_MEMORY_BARRIER = 46,
    VK_STRUCTURE_TYPE_LOADER_INSTANCE_CREATE_INFO = 47,
    VK_STRUCTURE_TYPE_LOADER_DEVICE_CREATE_INFO = 48,
  // Provided by VK_VERSION_1_1
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SUBGROUP_PROPERTIES = 1000094000,
  // Provided by VK_VERSION_1_1
    VK_STRUCTURE_TYPE_BIND_BUFFER_MEMORY_INFO = 1000157000,
  // Provided by VK_VERSION_1_1
    VK_STRUCTURE_TYPE_BIND_IMAGE_MEMORY_INFO = 1000157001,
  // Provided by VK_VERSION_1_1
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_16BIT_STORAGE_FEATURES = 1000083000,
  // Provided by VK_VERSION_1_1
    VK_STRUCTURE_TYPE_MEMORY_DEDICATED_REQUIREMENTS = 1000127000,
  // Provided by VK_VERSION_1_1
    VK_STRUCTURE_TYPE_MEMORY_DEDICATED_ALLOCATE_INFO = 1000127001,
  // Provided by VK_VERSION_1_1
    VK_STRUCTURE_TYPE_MEMORY_ALLOCATE_FLAGS_INFO = 1000060000,
  // Provided by VK_VERSION_1_1
    VK_STRUCTURE_TYPE_DEVICE_GROUP_RENDER_PASS_BEGIN_INFO = 1000060003,
  // Provided by VK_VERSION_1_1
    VK_STRUCTURE_TYPE_DEVICE_GROUP_COMMAND_BUFFER_BEGIN_INFO = 1000060004,
  // Provided by VK_VERSION_1_1
    VK_STRUCTURE_TYPE_DEVICE_GROUP_SUBMIT_INFO = 1000060005,
  // Provided by VK_VERSION_1_1
    VK_STRUCTURE_TYPE_DEVICE_GROUP_BIND_SPARSE_INFO = 1000060006,
  // Provided by VK_VERSION_1_1
    VK_STRUCTURE_TYPE_BIND_BUFFER_MEMORY_DEVICE_GROUP_INFO = 1000060013,
  // Provided by VK_VERSION_1_1
    VK_STRUCTURE_TYPE_BIND_IMAGE_MEMORY_DEVICE_GROUP_INFO = 1000060014,
  // Provided by VK_VERSION_1_1
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_GROUP_PROPERTIES = 1000070000,
  // Provided by VK_VERSION_1_1
    VK_STRUCTURE_TYPE_DEVICE_GROUP_DEVICE_CREATE_INFO = 1000070001,
  // Provided by VK_VERSION_1_1
    VK_STRUCTURE_TYPE_BUFFER_MEMORY_REQUIREMENTS_INFO_2 = 1000146000,
  // Provided by VK_VERSION_1_1
    VK_STRUCTURE_TYPE_IMAGE_MEMORY_REQUIREMENTS_INFO_2 = 1000146001,
  // Provided by VK_VERSION_1_1
    VK_STRUCTURE_TYPE_IMAGE_SPARSE_MEMORY_REQUIREMENTS_INFO_2 = 1000146002,
  // Provided by VK_VERSION_1_1
    VK_STRUCTURE_TYPE_MEMORY_REQUIREMENTS_2 = 1000146003,
  // Provided by VK_VERSION_1_1
    VK_STRUCTURE_TYPE_SPARSE_IMAGE_MEMORY_REQUIREMENTS_2 = 1000146004,
  // Provided by VK_VERSION_1_1
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FEATURES_2 = 1000059000,
  // Provided by VK_VERSION_1_1
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PROPERTIES_2 = 1000059001,
  // Provided by VK_VERSION_1_1
    VK_STRUCTURE_TYPE_FORMAT_PROPERTIES_2 = 1000059002,
  // Provided by VK_VERSION_1_1
    VK_STRUCTURE_TYPE_IMAGE_FORMAT_PROPERTIES_2 = 1000059003,
  // Provided by VK_VERSION_1_1
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGE_FORMAT_INFO_2 = 1000059004,
  // Provided by VK_VERSION_1_1
    VK_STRUCTURE_TYPE_QUEUE_FAMILY_PROPERTIES_2 = 1000059005,
  // Provided by VK_VERSION_1_1
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MEMORY_PROPERTIES_2 = 1000059006,
  // Provided by VK_VERSION_1_1
    VK_STRUCTURE_TYPE_SPARSE_IMAGE_FORMAT_PROPERTIES_2 = 1000059007,
  // Provided by VK_VERSION_1_1
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SPARSE_IMAGE_FORMAT_INFO_2 = 1000059008,
  // Provided by VK_VERSION_1_1
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_POINT_CLIPPING_PROPERTIES = 1000117000,
  // Provided by VK_VERSION_1_1
    VK_STRUCTURE_TYPE_RENDER_PASS_INPUT_ATTACHMENT_ASPECT_CREATE_INFO = 1000117001,
  // Provided by VK_VERSION_1_1
    VK_STRUCTURE_TYPE_IMAGE_VIEW_USAGE_CREATE_INFO = 1000117002,
  // Provided by VK_VERSION_1_1
    VK_STRUCTURE_TYPE_PIPELINE_TESSELLATION_DOMAIN_ORIGIN_STATE_CREATE_INFO = 1000117003,
  // Provided by VK_VERSION_1_1
    VK_STRUCTURE_TYPE_RENDER_PASS_MULTIVIEW_CREATE_INFO = 1000053000,
  // Provided by VK_VERSION_1_1
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MULTIVIEW_FEATURES = 1000053001,
  // Provided by VK_VERSION_1_1
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MULTIVIEW_PROPERTIES = 1000053002,
  // Provided by VK_VERSION_1_1
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VARIABLE_POINTERS_FEATURES = 1000120000,
  // Provided by VK_VERSION_1_1
    VK_STRUCTURE_TYPE_PROTECTED_SUBMIT_INFO = 1000145000,
  // Provided by VK_VERSION_1_1
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PROTECTED_MEMORY_FEATURES = 1000145001,
  // Provided by VK_VERSION_1_1
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PROTECTED_MEMORY_PROPERTIES = 1000145002,
  // Provided by VK_VERSION_1_1
    VK_STRUCTURE_TYPE_DEVICE_QUEUE_INFO_2 = 1000145003,
  // Provided by VK_VERSION_1_1
    VK_STRUCTURE_TYPE_SAMPLER_YCBCR_CONVERSION_CREATE_INFO = 1000156000,
  // Provided by VK_VERSION_1_1
    VK_STRUCTURE_TYPE_SAMPLER_YCBCR_CONVERSION_INFO = 1000156001,
  // Provided by VK_VERSION_1_1
    VK_STRUCTURE_TYPE_BIND_IMAGE_PLANE_MEMORY_INFO = 1000156002,
  // Provided by VK_VERSION_1_1
    VK_STRUCTURE_TYPE_IMAGE_PLANE_MEMORY_REQUIREMENTS_INFO = 1000156003,
  // Provided by VK_VERSION_1_1
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SAMPLER_YCBCR_CONVERSION_FEATURES = 1000156004,
  // Provided by VK_VERSION_1_1
    VK_STRUCTURE_TYPE_SAMPLER_YCBCR_CONVERSION_IMAGE_FORMAT_PROPERTIES = 1000156005,
  // Provided by VK_VERSION_1_1
    VK_STRUCTURE_TYPE_DESCRIPTOR_UPDATE_TEMPLATE_CREATE_INFO = 1000085000,
  // Provided by VK_VERSION_1_1
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_EXTERNAL_IMAGE_FORMAT_INFO = 1000071000,
  // Provided by VK_VERSION_1_1
    VK_STRUCTURE_TYPE_EXTERNAL_IMAGE_FORMAT_PROPERTIES = 1000071001,
  // Provided by VK_VERSION_1_1
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_EXTERNAL_BUFFER_INFO = 1000071002,
  // Provided by VK_VERSION_1_1
    VK_STRUCTURE_TYPE_EXTERNAL_BUFFER_PROPERTIES = 1000071003,
  // Provided by VK_VERSION_1_1
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_ID_PROPERTIES = 1000071004,
  // Provided by VK_VERSION_1_1
    VK_STRUCTURE_TYPE_EXTERNAL_MEMORY_BUFFER_CREATE_INFO = 1000072000,
  // Provided by VK_VERSION_1_1
    VK_STRUCTURE_TYPE_EXTERNAL_MEMORY_IMAGE_CREATE_INFO = 1000072001,
  // Provided by VK_VERSION_1_1
    VK_STRUCTURE_TYPE_EXPORT_MEMORY_ALLOCATE_INFO = 1000072002,
  // Provided by VK_VERSION_1_1
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_EXTERNAL_FENCE_INFO = 1000112000,
  // Provided by VK_VERSION_1_1
    VK_STRUCTURE_TYPE_EXTERNAL_FENCE_PROPERTIES = 1000112001,
  // Provided by VK_VERSION_1_1
    VK_STRUCTURE_TYPE_EXPORT_FENCE_CREATE_INFO = 1000113000,
  // Provided by VK_VERSION_1_1
    VK_STRUCTURE_TYPE_EXPORT_SEMAPHORE_CREATE_INFO = 1000077000,
  // Provided by VK_VERSION_1_1
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_EXTERNAL_SEMAPHORE_INFO = 1000076000,
  // Provided by VK_VERSION_1_1
    VK_STRUCTURE_TYPE_EXTERNAL_SEMAPHORE_PROPERTIES = 1000076001,
  // Provided by VK_VERSION_1_1
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MAINTENANCE_3_PROPERTIES = 1000168000,
  // Provided by VK_VERSION_1_1
    VK_STRUCTURE_TYPE_DESCRIPTOR_SET_LAYOUT_SUPPORT = 1000168001,
  // Provided by VK_VERSION_1_1
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_DRAW_PARAMETERS_FEATURES = 1000063000,
  // Provided by VK_VERSION_1_2
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VULKAN_1_1_FEATURES = 49,
  // Provided by VK_VERSION_1_2
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VULKAN_1_1_PROPERTIES = 50,
  // Provided by VK_VERSION_1_2
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VULKAN_1_2_FEATURES = 51,
  // Provided by VK_VERSION_1_2
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VULKAN_1_2_PROPERTIES = 52,
  // Provided by VK_VERSION_1_2
    VK_STRUCTURE_TYPE_IMAGE_FORMAT_LIST_CREATE_INFO = 1000147000,
  // Provided by VK_VERSION_1_2
    VK_STRUCTURE_TYPE_ATTACHMENT_DESCRIPTION_2 = 1000109000,
  // Provided by VK_VERSION_1_2
    VK_STRUCTURE_TYPE_ATTACHMENT_REFERENCE_2 = 1000109001,
  // Provided by VK_VERSION_1_2
    VK_STRUCTURE_TYPE_SUBPASS_DESCRIPTION_2 = 1000109002,
  // Provided by VK_VERSION_1_2
    VK_STRUCTURE_TYPE_SUBPASS_DEPENDENCY_2 = 1000109003,
  // Provided by VK_VERSION_1_2
    VK_STRUCTURE_TYPE_RENDER_PASS_CREATE_INFO_2 = 1000109004,
  // Provided by VK_VERSION_1_2
    VK_STRUCTURE_TYPE_SUBPASS_BEGIN_INFO = 1000109005,
  // Provided by VK_VERSION_1_2
    VK_STRUCTURE_TYPE_SUBPASS_END_INFO = 1000109006,
  // Provided by VK_VERSION_1_2
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_8BIT_STORAGE_FEATURES = 1000177000,
  // Provided by VK_VERSION_1_2
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DRIVER_PROPERTIES = 1000196000,
  // Provided by VK_VERSION_1_2
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_ATOMIC_INT64_FEATURES = 1000180000,
  // Provided by VK_VERSION_1_2
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_FLOAT16_INT8_FEATURES = 1000082000,
  // Provided by VK_VERSION_1_2
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FLOAT_CONTROLS_PROPERTIES = 1000197000,
  // Provided by VK_VERSION_1_2
    VK_STRUCTURE_TYPE_DESCRIPTOR_SET_LAYOUT_BINDING_FLAGS_CREATE_INFO = 1000161000,
  // Provided by VK_VERSION_1_2
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DESCRIPTOR_INDEXING_FEATURES = 1000161001,
  // Provided by VK_VERSION_1_2
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DESCRIPTOR_INDEXING_PROPERTIES = 1000161002,
  // Provided by VK_VERSION_1_2
    VK_STRUCTURE_TYPE_DESCRIPTOR_SET_VARIABLE_DESCRIPTOR_COUNT_ALLOCATE_INFO = 1000161003,
  // Provided by VK_VERSION_1_2
    VK_STRUCTURE_TYPE_DESCRIPTOR_SET_VARIABLE_DESCRIPTOR_COUNT_LAYOUT_SUPPORT = 1000161004,
  // Provided by VK_VERSION_1_2
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DEPTH_STENCIL_RESOLVE_PROPERTIES = 1000199000,
  // Provided by VK_VERSION_1_2
    VK_STRUCTURE_TYPE_SUBPASS_DESCRIPTION_DEPTH_STENCIL_RESOLVE = 1000199001,
  // Provided by VK_VERSION_1_2
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SCALAR_BLOCK_LAYOUT_FEATURES = 1000221000,
  // Provided by VK_VERSION_1_2
    VK_STRUCTURE_TYPE_IMAGE_STENCIL_USAGE_CREATE_INFO = 1000246000,
  // Provided by VK_VERSION_1_2
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SAMPLER_FILTER_MINMAX_PROPERTIES = 1000130000,
  // Provided by VK_VERSION_1_2
    VK_STRUCTURE_TYPE_SAMPLER_REDUCTION_MODE_CREATE_INFO = 1000130001,
  // Provided by VK_VERSION_1_2
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VULKAN_MEMORY_MODEL_FEATURES = 1000211000,
  // Provided by VK_VERSION_1_2
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGELESS_FRAMEBUFFER_FEATURES = 1000108000,
  // Provided by VK_VERSION_1_2
    VK_STRUCTURE_TYPE_FRAMEBUFFER_ATTACHMENTS_CREATE_INFO = 1000108001,
  // Provided by VK_VERSION_1_2
    VK_STRUCTURE_TYPE_FRAMEBUFFER_ATTACHMENT_IMAGE_INFO = 1000108002,
  // Provided by VK_VERSION_1_2
    VK_STRUCTURE_TYPE_RENDER_PASS_ATTACHMENT_BEGIN_INFO = 1000108003,
  // Provided by VK_VERSION_1_2
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_UNIFORM_BUFFER_STANDARD_LAYOUT_FEATURES = 1000253000,
  // Provided by VK_VERSION_1_2
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_SUBGROUP_EXTENDED_TYPES_FEATURES = 1000175000,
  // Provided by VK_VERSION_1_2
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SEPARATE_DEPTH_STENCIL_LAYOUTS_FEATURES = 1000241000,
  // Provided by VK_VERSION_1_2
    VK_STRUCTURE_TYPE_ATTACHMENT_REFERENCE_STENCIL_LAYOUT = 1000241001,
  // Provided by VK_VERSION_1_2
    VK_STRUCTURE_TYPE_ATTACHMENT_DESCRIPTION_STENCIL_LAYOUT = 1000241002,
  // Provided by VK_VERSION_1_2
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_HOST_QUERY_RESET_FEATURES = 1000261000,
  // Provided by VK_VERSION_1_2
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_TIMELINE_SEMAPHORE_FEATURES = 1000207000,
  // Provided by VK_VERSION_1_2
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_TIMELINE_SEMAPHORE_PROPERTIES = 1000207001,
  // Provided by VK_VERSION_1_2
    VK_STRUCTURE_TYPE_SEMAPHORE_TYPE_CREATE_INFO = 1000207002,
  // Provided by VK_VERSION_1_2
    VK_STRUCTURE_TYPE_TIMELINE_SEMAPHORE_SUBMIT_INFO = 1000207003,
  // Provided by VK_VERSION_1_2
    VK_STRUCTURE_TYPE_SEMAPHORE_WAIT_INFO = 1000207004,
  // Provided by VK_VERSION_1_2
    VK_STRUCTURE_TYPE_SEMAPHORE_SIGNAL_INFO = 1000207005,
  // Provided by VK_VERSION_1_2
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_BUFFER_DEVICE_ADDRESS_FEATURES = 1000257000,
  // Provided by VK_VERSION_1_2
    VK_STRUCTURE_TYPE_BUFFER_DEVICE_ADDRESS_INFO = 1000244001,
  // Provided by VK_VERSION_1_2
    VK_STRUCTURE_TYPE_BUFFER_OPAQUE_CAPTURE_ADDRESS_CREATE_INFO = 1000257002,
  // Provided by VK_VERSION_1_2
    VK_STRUCTURE_TYPE_MEMORY_OPAQUE_CAPTURE_ADDRESS_ALLOCATE_INFO = 1000257003,
  // Provided by VK_VERSION_1_2
    VK_STRUCTURE_TYPE_DEVICE_MEMORY_OPAQUE_CAPTURE_ADDRESS_INFO = 1000257004,
  // Provided by VK_VERSION_1_3
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VULKAN_1_3_FEATURES = 53,
  // Provided by VK_VERSION_1_3
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VULKAN_1_3_PROPERTIES = 54,
  // Provided by VK_VERSION_1_3
    VK_STRUCTURE_TYPE_PIPELINE_CREATION_FEEDBACK_CREATE_INFO = 1000192000,
  // Provided by VK_VERSION_1_3
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_TERMINATE_INVOCATION_FEATURES = 1000215000,
  // Provided by VK_VERSION_1_3
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_TOOL_PROPERTIES = 1000245000,
  // Provided by VK_VERSION_1_3
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_DEMOTE_TO_HELPER_INVOCATION_FEATURES = 1000276000,
  // Provided by VK_VERSION_1_3
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PRIVATE_DATA_FEATURES = 1000295000,
  // Provided by VK_VERSION_1_3
    VK_STRUCTURE_TYPE_DEVICE_PRIVATE_DATA_CREATE_INFO = 1000295001,
  // Provided by VK_VERSION_1_3
    VK_STRUCTURE_TYPE_PRIVATE_DATA_SLOT_CREATE_INFO = 1000295002,
  // Provided by VK_VERSION_1_3
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PIPELINE_CREATION_CACHE_CONTROL_FEATURES = 1000297000,
  // Provided by VK_VERSION_1_3
    VK_STRUCTURE_TYPE_MEMORY_BARRIER_2 = 1000314000,
  // Provided by VK_VERSION_1_3
    VK_STRUCTURE_TYPE_BUFFER_MEMORY_BARRIER_2 = 1000314001,
  // Provided by VK_VERSION_1_3
    VK_STRUCTURE_TYPE_IMAGE_MEMORY_BARRIER_2 = 1000314002,
  // Provided by VK_VERSION_1_3
    VK_STRUCTURE_TYPE_DEPENDENCY_INFO = 1000314003,
  // Provided by VK_VERSION_1_3
    VK_STRUCTURE_TYPE_SUBMIT_INFO_2 = 1000314004,
  // Provided by VK_VERSION_1_3
    VK_STRUCTURE_TYPE_SEMAPHORE_SUBMIT_INFO = 1000314005,
  // Provided by VK_VERSION_1_3
    VK_STRUCTURE_TYPE_COMMAND_BUFFER_SUBMIT_INFO = 1000314006,
  // Provided by VK_VERSION_1_3
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SYNCHRONIZATION_2_FEATURES = 1000314007,
  // Provided by VK_VERSION_1_3
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_ZERO_INITIALIZE_WORKGROUP_MEMORY_FEATURES = 1000325000,
  // Provided by VK_VERSION_1_3
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGE_ROBUSTNESS_FEATURES = 1000335000,
  // Provided by VK_VERSION_1_3
    VK_STRUCTURE_TYPE_COPY_BUFFER_INFO_2 = 1000337000,
  // Provided by VK_VERSION_1_3
    VK_STRUCTURE_TYPE_COPY_IMAGE_INFO_2 = 1000337001,
  // Provided by VK_VERSION_1_3
    VK_STRUCTURE_TYPE_COPY_BUFFER_TO_IMAGE_INFO_2 = 1000337002,
  // Provided by VK_VERSION_1_3
    VK_STRUCTURE_TYPE_COPY_IMAGE_TO_BUFFER_INFO_2 = 1000337003,
  // Provided by VK_VERSION_1_3
    VK_STRUCTURE_TYPE_BLIT_IMAGE_INFO_2 = 1000337004,
  // Provided by VK_VERSION_1_3
    VK_STRUCTURE_TYPE_RESOLVE_IMAGE_INFO_2 = 1000337005,
  // Provided by VK_VERSION_1_3
    VK_STRUCTURE_TYPE_BUFFER_COPY_2 = 1000337006,
  // Provided by VK_VERSION_1_3
    VK_STRUCTURE_TYPE_IMAGE_COPY_2 = 1000337007,
  // Provided by VK_VERSION_1_3
    VK_STRUCTURE_TYPE_IMAGE_BLIT_2 = 1000337008,
  // Provided by VK_VERSION_1_3
    VK_STRUCTURE_TYPE_BUFFER_IMAGE_COPY_2 = 1000337009,
  // Provided by VK_VERSION_1_3
    VK_STRUCTURE_TYPE_IMAGE_RESOLVE_2 = 1000337010,
  // Provided by VK_VERSION_1_3
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SUBGROUP_SIZE_CONTROL_PROPERTIES = 1000225000,
  // Provided by VK_VERSION_1_3
    VK_STRUCTURE_TYPE_PIPELINE_SHADER_STAGE_REQUIRED_SUBGROUP_SIZE_CREATE_INFO = 1000225001,
  // Provided by VK_VERSION_1_3
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SUBGROUP_SIZE_CONTROL_FEATURES = 1000225002,
  // Provided by VK_VERSION_1_3
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_INLINE_UNIFORM_BLOCK_FEATURES = 1000138000,
  // Provided by VK_VERSION_1_3
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_INLINE_UNIFORM_BLOCK_PROPERTIES = 1000138001,
  // Provided by VK_VERSION_1_3
    VK_STRUCTURE_TYPE_WRITE_DESCRIPTOR_SET_INLINE_UNIFORM_BLOCK = 1000138002,
  // Provided by VK_VERSION_1_3
    VK_STRUCTURE_TYPE_DESCRIPTOR_POOL_INLINE_UNIFORM_BLOCK_CREATE_INFO = 1000138003,
  // Provided by VK_VERSION_1_3
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_TEXTURE_COMPRESSION_ASTC_HDR_FEATURES = 1000066000,
  // Provided by VK_VERSION_1_3
    VK_STRUCTURE_TYPE_RENDERING_INFO = 1000044000,
  // Provided by VK_VERSION_1_3
    VK_STRUCTURE_TYPE_RENDERING_ATTACHMENT_INFO = 1000044001,
  // Provided by VK_VERSION_1_3
    VK_STRUCTURE_TYPE_PIPELINE_RENDERING_CREATE_INFO = 1000044002,
  // Provided by VK_VERSION_1_3
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DYNAMIC_RENDERING_FEATURES = 1000044003,
  // Provided by VK_VERSION_1_3
    VK_STRUCTURE_TYPE_COMMAND_BUFFER_INHERITANCE_RENDERING_INFO = 1000044004,
  // Provided by VK_VERSION_1_3
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_INTEGER_DOT_PRODUCT_FEATURES = 1000280000,
  // Provided by VK_VERSION_1_3
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_INTEGER_DOT_PRODUCT_PROPERTIES = 1000280001,
  // Provided by VK_VERSION_1_3
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_TEXEL_BUFFER_ALIGNMENT_PROPERTIES = 1000281001,
  // Provided by VK_VERSION_1_3
    VK_STRUCTURE_TYPE_FORMAT_PROPERTIES_3 = 1000360000,
  // Provided by VK_VERSION_1_3
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MAINTENANCE_4_FEATURES = 1000413000,
  // Provided by VK_VERSION_1_3
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MAINTENANCE_4_PROPERTIES = 1000413001,
  // Provided by VK_VERSION_1_3
    VK_STRUCTURE_TYPE_DEVICE_BUFFER_MEMORY_REQUIREMENTS = 1000413002,
  // Provided by VK_VERSION_1_3
    VK_STRUCTURE_TYPE_DEVICE_IMAGE_MEMORY_REQUIREMENTS = 1000413003,
  // Provided by VK_KHR_swapchain
    VK_STRUCTURE_TYPE_SWAPCHAIN_CREATE_INFO_KHR = 1000001000,
  // Provided by VK_KHR_swapchain
    VK_STRUCTURE_TYPE_PRESENT_INFO_KHR = 1000001001,
  // Provided by VK_VERSION_1_1 with VK_KHR_swapchain, VK_KHR_device_group with VK_KHR_surface
    VK_STRUCTURE_TYPE_DEVICE_GROUP_PRESENT_CAPABILITIES_KHR = 1000060007,
  // Provided by VK_VERSION_1_1 with VK_KHR_swapchain, VK_KHR_device_group with VK_KHR_swapchain
    VK_STRUCTURE_TYPE_IMAGE_SWAPCHAIN_CREATE_INFO_KHR = 1000060008,
  // Provided by VK_VERSION_1_1 with VK_KHR_swapchain, VK_KHR_device_group with VK_KHR_swapchain
    VK_STRUCTURE_TYPE_BIND_IMAGE_MEMORY_SWAPCHAIN_INFO_KHR = 1000060009,
  // Provided by VK_VERSION_1_1 with VK_KHR_swapchain, VK_KHR_device_group with VK_KHR_swapchain
    VK_STRUCTURE_TYPE_ACQUIRE_NEXT_IMAGE_INFO_KHR = 1000060010,
  // Provided by VK_VERSION_1_1 with VK_KHR_swapchain, VK_KHR_device_group with VK_KHR_swapchain
    VK_STRUCTURE_TYPE_DEVICE_GROUP_PRESENT_INFO_KHR = 1000060011,
  // Provided by VK_VERSION_1_1 with VK_KHR_swapchain, VK_KHR_device_group with VK_KHR_swapchain
    VK_STRUCTURE_TYPE_DEVICE_GROUP_SWAPCHAIN_CREATE_INFO_KHR = 1000060012,
  // Provided by VK_KHR_display
    VK_STRUCTURE_TYPE_DISPLAY_MODE_CREATE_INFO_KHR = 1000002000,
  // Provided by VK_KHR_display
    VK_STRUCTURE_TYPE_DISPLAY_SURFACE_CREATE_INFO_KHR = 1000002001,
  // Provided by VK_KHR_display_swapchain
    VK_STRUCTURE_TYPE_DISPLAY_PRESENT_INFO_KHR = 1000003000,
  // Provided by VK_KHR_xlib_surface
    VK_STRUCTURE_TYPE_XLIB_SURFACE_CREATE_INFO_KHR = 1000004000,
  // Provided by VK_KHR_xcb_surface
    VK_STRUCTURE_TYPE_XCB_SURFACE_CREATE_INFO_KHR = 1000005000,
  // Provided by VK_KHR_wayland_surface
    VK_STRUCTURE_TYPE_WAYLAND_SURFACE_CREATE_INFO_KHR = 1000006000,
  // Provided by VK_KHR_android_surface
    VK_STRUCTURE_TYPE_ANDROID_SURFACE_CREATE_INFO_KHR = 1000008000,
  // Provided by VK_KHR_win32_surface
    VK_STRUCTURE_TYPE_WIN32_SURFACE_CREATE_INFO_KHR = 1000009000,
  // Provided by VK_EXT_debug_report
    VK_STRUCTURE_TYPE_DEBUG_REPORT_CALLBACK_CREATE_INFO_EXT = 1000011000,
  // Provided by VK_AMD_rasterization_order
    VK_STRUCTURE_TYPE_PIPELINE_RASTERIZATION_STATE_RASTERIZATION_ORDER_AMD = 1000018000,
  // Provided by VK_EXT_debug_marker
    VK_STRUCTURE_TYPE_DEBUG_MARKER_OBJECT_NAME_INFO_EXT = 1000022000,
  // Provided by VK_EXT_debug_marker
    VK_STRUCTURE_TYPE_DEBUG_MARKER_OBJECT_TAG_INFO_EXT = 1000022001,
  // Provided by VK_EXT_debug_marker
    VK_STRUCTURE_TYPE_DEBUG_MARKER_MARKER_INFO_EXT = 1000022002,
  // Provided by VK_KHR_video_queue
    VK_STRUCTURE_TYPE_VIDEO_PROFILE_INFO_KHR = 1000023000,
  // Provided by VK_KHR_video_queue
    VK_STRUCTURE_TYPE_VIDEO_CAPABILITIES_KHR = 1000023001,
  // Provided by VK_KHR_video_queue
    VK_STRUCTURE_TYPE_VIDEO_PICTURE_RESOURCE_INFO_KHR = 1000023002,
  // Provided by VK_KHR_video_queue
    VK_STRUCTURE_TYPE_VIDEO_SESSION_MEMORY_REQUIREMENTS_KHR = 1000023003,
  // Provided by VK_KHR_video_queue
    VK_STRUCTURE_TYPE_BIND_VIDEO_SESSION_MEMORY_INFO_KHR = 1000023004,
  // Provided by VK_KHR_video_queue
    VK_STRUCTURE_TYPE_VIDEO_SESSION_CREATE_INFO_KHR = 1000023005,
  // Provided by VK_KHR_video_queue
    VK_STRUCTURE_TYPE_VIDEO_SESSION_PARAMETERS_CREATE_INFO_KHR = 1000023006,
  // Provided by VK_KHR_video_queue
    VK_STRUCTURE_TYPE_VIDEO_SESSION_PARAMETERS_UPDATE_INFO_KHR = 1000023007,
  // Provided by VK_KHR_video_queue
    VK_STRUCTURE_TYPE_VIDEO_BEGIN_CODING_INFO_KHR = 1000023008,
  // Provided by VK_KHR_video_queue
    VK_STRUCTURE_TYPE_VIDEO_END_CODING_INFO_KHR = 1000023009,
  // Provided by VK_KHR_video_queue
    VK_STRUCTURE_TYPE_VIDEO_CODING_CONTROL_INFO_KHR = 1000023010,
  // Provided by VK_KHR_video_queue
    VK_STRUCTURE_TYPE_VIDEO_REFERENCE_SLOT_INFO_KHR = 1000023011,
  // Provided by VK_KHR_video_queue
    VK_STRUCTURE_TYPE_QUEUE_FAMILY_VIDEO_PROPERTIES_KHR = 1000023012,
  // Provided by VK_KHR_video_queue
    VK_STRUCTURE_TYPE_VIDEO_PROFILE_LIST_INFO_KHR = 1000023013,
  // Provided by VK_KHR_video_queue
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VIDEO_FORMAT_INFO_KHR = 1000023014,
  // Provided by VK_KHR_video_queue
    VK_STRUCTURE_TYPE_VIDEO_FORMAT_PROPERTIES_KHR = 1000023015,
  // Provided by VK_KHR_video_queue
    VK_STRUCTURE_TYPE_QUEUE_FAMILY_QUERY_RESULT_STATUS_PROPERTIES_KHR = 1000023016,
  // Provided by VK_KHR_video_decode_queue
    VK_STRUCTURE_TYPE_VIDEO_DECODE_INFO_KHR = 1000024000,
  // Provided by VK_KHR_video_decode_queue
    VK_STRUCTURE_TYPE_VIDEO_DECODE_CAPABILITIES_KHR = 1000024001,
  // Provided by VK_KHR_video_decode_queue
    VK_STRUCTURE_TYPE_VIDEO_DECODE_USAGE_INFO_KHR = 1000024002,
  // Provided by VK_NV_dedicated_allocation
    VK_STRUCTURE_TYPE_DEDICATED_ALLOCATION_IMAGE_CREATE_INFO_NV = 1000026000,
  // Provided by VK_NV_dedicated_allocation
    VK_STRUCTURE_TYPE_DEDICATED_ALLOCATION_BUFFER_CREATE_INFO_NV = 1000026001,
  // Provided by VK_NV_dedicated_allocation
    VK_STRUCTURE_TYPE_DEDICATED_ALLOCATION_MEMORY_ALLOCATE_INFO_NV = 1000026002,
  // Provided by VK_EXT_transform_feedback
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_TRANSFORM_FEEDBACK_FEATURES_EXT = 1000028000,
  // Provided by VK_EXT_transform_feedback
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_TRANSFORM_FEEDBACK_PROPERTIES_EXT = 1000028001,
  // Provided by VK_EXT_transform_feedback
    VK_STRUCTURE_TYPE_PIPELINE_RASTERIZATION_STATE_STREAM_CREATE_INFO_EXT = 1000028002,
  // Provided by VK_NVX_binary_import
    VK_STRUCTURE_TYPE_CU_MODULE_CREATE_INFO_NVX = 1000029000,
  // Provided by VK_NVX_binary_import
    VK_STRUCTURE_TYPE_CU_FUNCTION_CREATE_INFO_NVX = 1000029001,
  // Provided by VK_NVX_binary_import
    VK_STRUCTURE_TYPE_CU_LAUNCH_INFO_NVX = 1000029002,
  // Provided by VK_NVX_image_view_handle
    VK_STRUCTURE_TYPE_IMAGE_VIEW_HANDLE_INFO_NVX = 1000030000,
  // Provided by VK_NVX_image_view_handle
    VK_STRUCTURE_TYPE_IMAGE_VIEW_ADDRESS_PROPERTIES_NVX = 1000030001,
  // Provided by VK_KHR_video_encode_h264
    VK_STRUCTURE_TYPE_VIDEO_ENCODE_H264_CAPABILITIES_KHR = 1000038000,
  // Provided by VK_KHR_video_encode_h264
    VK_STRUCTURE_TYPE_VIDEO_ENCODE_H264_SESSION_PARAMETERS_CREATE_INFO_KHR = 1000038001,
  // Provided by VK_KHR_video_encode_h264
    VK_STRUCTURE_TYPE_VIDEO_ENCODE_H264_SESSION_PARAMETERS_ADD_INFO_KHR = 1000038002,
  // Provided by VK_KHR_video_encode_h264
    VK_STRUCTURE_TYPE_VIDEO_ENCODE_H264_PICTURE_INFO_KHR = 1000038003,
  // Provided by VK_KHR_video_encode_h264
    VK_STRUCTURE_TYPE_VIDEO_ENCODE_H264_DPB_SLOT_INFO_KHR = 1000038004,
  // Provided by VK_KHR_video_encode_h264
    VK_STRUCTURE_TYPE_VIDEO_ENCODE_H264_NALU_SLICE_INFO_KHR = 1000038005,
  // Provided by VK_KHR_video_encode_h264
    VK_STRUCTURE_TYPE_VIDEO_ENCODE_H264_GOP_REMAINING_FRAME_INFO_KHR = 1000038006,
  // Provided by VK_KHR_video_encode_h264
    VK_STRUCTURE_TYPE_VIDEO_ENCODE_H264_PROFILE_INFO_KHR = 1000038007,
  // Provided by VK_KHR_video_encode_h264
    VK_STRUCTURE_TYPE_VIDEO_ENCODE_H264_RATE_CONTROL_INFO_KHR = 1000038008,
  // Provided by VK_KHR_video_encode_h264
    VK_STRUCTURE_TYPE_VIDEO_ENCODE_H264_RATE_CONTROL_LAYER_INFO_KHR = 1000038009,
  // Provided by VK_KHR_video_encode_h264
    VK_STRUCTURE_TYPE_VIDEO_ENCODE_H264_SESSION_CREATE_INFO_KHR = 1000038010,
  // Provided by VK_KHR_video_encode_h264
    VK_STRUCTURE_TYPE_VIDEO_ENCODE_H264_QUALITY_LEVEL_PROPERTIES_KHR = 1000038011,
  // Provided by VK_KHR_video_encode_h264
    VK_STRUCTURE_TYPE_VIDEO_ENCODE_H264_SESSION_PARAMETERS_GET_INFO_KHR = 1000038012,
  // Provided by VK_KHR_video_encode_h264
    VK_STRUCTURE_TYPE_VIDEO_ENCODE_H264_SESSION_PARAMETERS_FEEDBACK_INFO_KHR = 1000038013,
  // Provided by VK_KHR_video_encode_h265
    VK_STRUCTURE_TYPE_VIDEO_ENCODE_H265_CAPABILITIES_KHR = 1000039000,
  // Provided by VK_KHR_video_encode_h265
    VK_STRUCTURE_TYPE_VIDEO_ENCODE_H265_SESSION_PARAMETERS_CREATE_INFO_KHR = 1000039001,
  // Provided by VK_KHR_video_encode_h265
    VK_STRUCTURE_TYPE_VIDEO_ENCODE_H265_SESSION_PARAMETERS_ADD_INFO_KHR = 1000039002,
  // Provided by VK_KHR_video_encode_h265
    VK_STRUCTURE_TYPE_VIDEO_ENCODE_H265_PICTURE_INFO_KHR = 1000039003,
  // Provided by VK_KHR_video_encode_h265
    VK_STRUCTURE_TYPE_VIDEO_ENCODE_H265_DPB_SLOT_INFO_KHR = 1000039004,
  // Provided by VK_KHR_video_encode_h265
    VK_STRUCTURE_TYPE_VIDEO_ENCODE_H265_NALU_SLICE_SEGMENT_INFO_KHR = 1000039005,
  // Provided by VK_KHR_video_encode_h265
    VK_STRUCTURE_TYPE_VIDEO_ENCODE_H265_GOP_REMAINING_FRAME_INFO_KHR = 1000039006,
  // Provided by VK_KHR_video_encode_h265
    VK_STRUCTURE_TYPE_VIDEO_ENCODE_H265_PROFILE_INFO_KHR = 1000039007,
  // Provided by VK_KHR_video_encode_h265
    VK_STRUCTURE_TYPE_VIDEO_ENCODE_H265_RATE_CONTROL_INFO_KHR = 1000039009,
  // Provided by VK_KHR_video_encode_h265
    VK_STRUCTURE_TYPE_VIDEO_ENCODE_H265_RATE_CONTROL_LAYER_INFO_KHR = 1000039010,
  // Provided by VK_KHR_video_encode_h265
    VK_STRUCTURE_TYPE_VIDEO_ENCODE_H265_SESSION_CREATE_INFO_KHR = 1000039011,
  // Provided by VK_KHR_video_encode_h265
    VK_STRUCTURE_TYPE_VIDEO_ENCODE_H265_QUALITY_LEVEL_PROPERTIES_KHR = 1000039012,
  // Provided by VK_KHR_video_encode_h265
    VK_STRUCTURE_TYPE_VIDEO_ENCODE_H265_SESSION_PARAMETERS_GET_INFO_KHR = 1000039013,
  // Provided by VK_KHR_video_encode_h265
    VK_STRUCTURE_TYPE_VIDEO_ENCODE_H265_SESSION_PARAMETERS_FEEDBACK_INFO_KHR = 1000039014,
  // Provided by VK_KHR_video_decode_h264
    VK_STRUCTURE_TYPE_VIDEO_DECODE_H264_CAPABILITIES_KHR = 1000040000,
  // Provided by VK_KHR_video_decode_h264
    VK_STRUCTURE_TYPE_VIDEO_DECODE_H264_PICTURE_INFO_KHR = 1000040001,
  // Provided by VK_KHR_video_decode_h264
    VK_STRUCTURE_TYPE_VIDEO_DECODE_H264_PROFILE_INFO_KHR = 1000040003,
  // Provided by VK_KHR_video_decode_h264
    VK_STRUCTURE_TYPE_VIDEO_DECODE_H264_SESSION_PARAMETERS_CREATE_INFO_KHR = 1000040004,
  // Provided by VK_KHR_video_decode_h264
    VK_STRUCTURE_TYPE_VIDEO_DECODE_H264_SESSION_PARAMETERS_ADD_INFO_KHR = 1000040005,
  // Provided by VK_KHR_video_decode_h264
    VK_STRUCTURE_TYPE_VIDEO_DECODE_H264_DPB_SLOT_INFO_KHR = 1000040006,
  // Provided by VK_AMD_texture_gather_bias_lod
    VK_STRUCTURE_TYPE_TEXTURE_LOD_GATHER_FORMAT_PROPERTIES_AMD = 1000041000,
  // Provided by VK_KHR_dynamic_rendering with VK_KHR_fragment_shading_rate
    VK_STRUCTURE_TYPE_RENDERING_FRAGMENT_SHADING_RATE_ATTACHMENT_INFO_KHR = 1000044006,
  // Provided by VK_KHR_dynamic_rendering with VK_EXT_fragment_density_map
    VK_STRUCTURE_TYPE_RENDERING_FRAGMENT_DENSITY_MAP_ATTACHMENT_INFO_EXT = 1000044007,
  // Provided by VK_KHR_dynamic_rendering with VK_AMD_mixed_attachment_samples
    VK_STRUCTURE_TYPE_ATTACHMENT_SAMPLE_COUNT_INFO_AMD = 1000044008,
  // Provided by VK_KHR_dynamic_rendering with VK_NVX_multiview_per_view_attributes
    VK_STRUCTURE_TYPE_MULTIVIEW_PER_VIEW_ATTRIBUTES_INFO_NVX = 1000044009,
  // Provided by VK_GGP_stream_descriptor_surface
    VK_STRUCTURE_TYPE_STREAM_DESCRIPTOR_SURFACE_CREATE_INFO_GGP = 1000049000,
  // Provided by VK_NV_corner_sampled_image
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_CORNER_SAMPLED_IMAGE_FEATURES_NV = 1000050000,
  // Provided by VK_NV_external_memory
    VK_STRUCTURE_TYPE_EXTERNAL_MEMORY_IMAGE_CREATE_INFO_NV = 1000056000,
  // Provided by VK_NV_external_memory
    VK_STRUCTURE_TYPE_EXPORT_MEMORY_ALLOCATE_INFO_NV = 1000056001,
  // Provided by VK_NV_external_memory_win32
    VK_STRUCTURE_TYPE_IMPORT_MEMORY_WIN32_HANDLE_INFO_NV = 1000057000,
  // Provided by VK_NV_external_memory_win32
    VK_STRUCTURE_TYPE_EXPORT_MEMORY_WIN32_HANDLE_INFO_NV = 1000057001,
  // Provided by VK_NV_win32_keyed_mutex
    VK_STRUCTURE_TYPE_WIN32_KEYED_MUTEX_ACQUIRE_RELEASE_INFO_NV = 1000058000,
  // Provided by VK_EXT_validation_flags
    VK_STRUCTURE_TYPE_VALIDATION_FLAGS_EXT = 1000061000,
  // Provided by VK_NN_vi_surface
    VK_STRUCTURE_TYPE_VI_SURFACE_CREATE_INFO_NN = 1000062000,
  // Provided by VK_EXT_astc_decode_mode
    VK_STRUCTURE_TYPE_IMAGE_VIEW_ASTC_DECODE_MODE_EXT = 1000067000,
  // Provided by VK_EXT_astc_decode_mode
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_ASTC_DECODE_FEATURES_EXT = 1000067001,
  // Provided by VK_EXT_pipeline_robustness
    VK_STRUCTURE_TYPE_PIPELINE_ROBUSTNESS_CREATE_INFO_EXT = 1000068000,
  // Provided by VK_EXT_pipeline_robustness
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PIPELINE_ROBUSTNESS_FEATURES_EXT = 1000068001,
  // Provided by VK_EXT_pipeline_robustness
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PIPELINE_ROBUSTNESS_PROPERTIES_EXT = 1000068002,
  // Provided by VK_KHR_external_memory_win32
    VK_STRUCTURE_TYPE_IMPORT_MEMORY_WIN32_HANDLE_INFO_KHR = 1000073000,
  // Provided by VK_KHR_external_memory_win32
    VK_STRUCTURE_TYPE_EXPORT_MEMORY_WIN32_HANDLE_INFO_KHR = 1000073001,
  // Provided by VK_KHR_external_memory_win32
    VK_STRUCTURE_TYPE_MEMORY_WIN32_HANDLE_PROPERTIES_KHR = 1000073002,
  // Provided by VK_KHR_external_memory_win32
    VK_STRUCTURE_TYPE_MEMORY_GET_WIN32_HANDLE_INFO_KHR = 1000073003,
  // Provided by VK_KHR_external_memory_fd
    VK_STRUCTURE_TYPE_IMPORT_MEMORY_FD_INFO_KHR = 1000074000,
  // Provided by VK_KHR_external_memory_fd
    VK_STRUCTURE_TYPE_MEMORY_FD_PROPERTIES_KHR = 1000074001,
  // Provided by VK_KHR_external_memory_fd
    VK_STRUCTURE_TYPE_MEMORY_GET_FD_INFO_KHR = 1000074002,
  // Provided by VK_KHR_win32_keyed_mutex
    VK_STRUCTURE_TYPE_WIN32_KEYED_MUTEX_ACQUIRE_RELEASE_INFO_KHR = 1000075000,
  // Provided by VK_KHR_external_semaphore_win32
    VK_STRUCTURE_TYPE_IMPORT_SEMAPHORE_WIN32_HANDLE_INFO_KHR = 1000078000,
  // Provided by VK_KHR_external_semaphore_win32
    VK_STRUCTURE_TYPE_EXPORT_SEMAPHORE_WIN32_HANDLE_INFO_KHR = 1000078001,
  // Provided by VK_KHR_external_semaphore_win32
    VK_STRUCTURE_TYPE_D3D12_FENCE_SUBMIT_INFO_KHR = 1000078002,
  // Provided by VK_KHR_external_semaphore_win32
    VK_STRUCTURE_TYPE_SEMAPHORE_GET_WIN32_HANDLE_INFO_KHR = 1000078003,
  // Provided by VK_KHR_external_semaphore_fd
    VK_STRUCTURE_TYPE_IMPORT_SEMAPHORE_FD_INFO_KHR = 1000079000,
  // Provided by VK_KHR_external_semaphore_fd
    VK_STRUCTURE_TYPE_SEMAPHORE_GET_FD_INFO_KHR = 1000079001,
  // Provided by VK_KHR_push_descriptor
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PUSH_DESCRIPTOR_PROPERTIES_KHR = 1000080000,
  // Provided by VK_EXT_conditional_rendering
    VK_STRUCTURE_TYPE_COMMAND_BUFFER_INHERITANCE_CONDITIONAL_RENDERING_INFO_EXT = 1000081000,
  // Provided by VK_EXT_conditional_rendering
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_CONDITIONAL_RENDERING_FEATURES_EXT = 1000081001,
  // Provided by VK_EXT_conditional_rendering
    VK_STRUCTURE_TYPE_CONDITIONAL_RENDERING_BEGIN_INFO_EXT = 1000081002,
  // Provided by VK_KHR_incremental_present
    VK_STRUCTURE_TYPE_PRESENT_REGIONS_KHR = 1000084000,
  // Provided by VK_NV_clip_space_w_scaling
    VK_STRUCTURE_TYPE_PIPELINE_VIEWPORT_W_SCALING_STATE_CREATE_INFO_NV = 1000087000,
  // Provided by VK_EXT_display_surface_counter
    VK_STRUCTURE_TYPE_SURFACE_CAPABILITIES_2_EXT = 1000090000,
  // Provided by VK_EXT_display_control
    VK_STRUCTURE_TYPE_DISPLAY_POWER_INFO_EXT = 1000091000,
  // Provided by VK_EXT_display_control
    VK_STRUCTURE_TYPE_DEVICE_EVENT_INFO_EXT = 1000091001,
  // Provided by VK_EXT_display_control
    VK_STRUCTURE_TYPE_DISPLAY_EVENT_INFO_EXT = 1000091002,
  // Provided by VK_EXT_display_control
    VK_STRUCTURE_TYPE_SWAPCHAIN_COUNTER_CREATE_INFO_EXT = 1000091003,
  // Provided by VK_GOOGLE_display_timing
    VK_STRUCTURE_TYPE_PRESENT_TIMES_INFO_GOOGLE = 1000092000,
  // Provided by VK_NVX_multiview_per_view_attributes
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MULTIVIEW_PER_VIEW_ATTRIBUTES_PROPERTIES_NVX = 1000097000,
  // Provided by VK_NV_viewport_swizzle
    VK_STRUCTURE_TYPE_PIPELINE_VIEWPORT_SWIZZLE_STATE_CREATE_INFO_NV = 1000098000,
  // Provided by VK_EXT_discard_rectangles
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DISCARD_RECTANGLE_PROPERTIES_EXT = 1000099000,
  // Provided by VK_EXT_discard_rectangles
    VK_STRUCTURE_TYPE_PIPELINE_DISCARD_RECTANGLE_STATE_CREATE_INFO_EXT = 1000099001,
  // Provided by VK_EXT_conservative_rasterization
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_CONSERVATIVE_RASTERIZATION_PROPERTIES_EXT = 1000101000,
  // Provided by VK_EXT_conservative_rasterization
    VK_STRUCTURE_TYPE_PIPELINE_RASTERIZATION_CONSERVATIVE_STATE_CREATE_INFO_EXT = 1000101001,
  // Provided by VK_EXT_depth_clip_enable
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DEPTH_CLIP_ENABLE_FEATURES_EXT = 1000102000,
  // Provided by VK_EXT_depth_clip_enable
    VK_STRUCTURE_TYPE_PIPELINE_RASTERIZATION_DEPTH_CLIP_STATE_CREATE_INFO_EXT = 1000102001,
  // Provided by VK_EXT_hdr_metadata
    VK_STRUCTURE_TYPE_HDR_METADATA_EXT = 1000105000,
  // Provided by VK_IMG_relaxed_line_rasterization
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_RELAXED_LINE_RASTERIZATION_FEATURES_IMG = 1000110000,
  // Provided by VK_KHR_shared_presentable_image
    VK_STRUCTURE_TYPE_SHARED_PRESENT_SURFACE_CAPABILITIES_KHR = 1000111000,
  // Provided by VK_KHR_external_fence_win32
    VK_STRUCTURE_TYPE_IMPORT_FENCE_WIN32_HANDLE_INFO_KHR = 1000114000,
  // Provided by VK_KHR_external_fence_win32
    VK_STRUCTURE_TYPE_EXPORT_FENCE_WIN32_HANDLE_INFO_KHR = 1000114001,
  // Provided by VK_KHR_external_fence_win32
    VK_STRUCTURE_TYPE_FENCE_GET_WIN32_HANDLE_INFO_KHR = 1000114002,
  // Provided by VK_KHR_external_fence_fd
    VK_STRUCTURE_TYPE_IMPORT_FENCE_FD_INFO_KHR = 1000115000,
  // Provided by VK_KHR_external_fence_fd
    VK_STRUCTURE_TYPE_FENCE_GET_FD_INFO_KHR = 1000115001,
  // Provided by VK_KHR_performance_query
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PERFORMANCE_QUERY_FEATURES_KHR = 1000116000,
  // Provided by VK_KHR_performance_query
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PERFORMANCE_QUERY_PROPERTIES_KHR = 1000116001,
  // Provided by VK_KHR_performance_query
    VK_STRUCTURE_TYPE_QUERY_POOL_PERFORMANCE_CREATE_INFO_KHR = 1000116002,
  // Provided by VK_KHR_performance_query
    VK_STRUCTURE_TYPE_PERFORMANCE_QUERY_SUBMIT_INFO_KHR = 1000116003,
  // Provided by VK_KHR_performance_query
    VK_STRUCTURE_TYPE_ACQUIRE_PROFILING_LOCK_INFO_KHR = 1000116004,
  // Provided by VK_KHR_performance_query
    VK_STRUCTURE_TYPE_PERFORMANCE_COUNTER_KHR = 1000116005,
  // Provided by VK_KHR_performance_query
    VK_STRUCTURE_TYPE_PERFORMANCE_COUNTER_DESCRIPTION_KHR = 1000116006,
  // Provided by VK_KHR_get_surface_capabilities2
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SURFACE_INFO_2_KHR = 1000119000,
  // Provided by VK_KHR_get_surface_capabilities2
    VK_STRUCTURE_TYPE_SURFACE_CAPABILITIES_2_KHR = 1000119001,
  // Provided by VK_KHR_get_surface_capabilities2
    VK_STRUCTURE_TYPE_SURFACE_FORMAT_2_KHR = 1000119002,
  // Provided by VK_KHR_get_display_properties2
    VK_STRUCTURE_TYPE_DISPLAY_PROPERTIES_2_KHR = 1000121000,
  // Provided by VK_KHR_get_display_properties2
    VK_STRUCTURE_TYPE_DISPLAY_PLANE_PROPERTIES_2_KHR = 1000121001,
  // Provided by VK_KHR_get_display_properties2
    VK_STRUCTURE_TYPE_DISPLAY_MODE_PROPERTIES_2_KHR = 1000121002,
  // Provided by VK_KHR_get_display_properties2
    VK_STRUCTURE_TYPE_DISPLAY_PLANE_INFO_2_KHR = 1000121003,
  // Provided by VK_KHR_get_display_properties2
    VK_STRUCTURE_TYPE_DISPLAY_PLANE_CAPABILITIES_2_KHR = 1000121004,
  // Provided by VK_MVK_ios_surface
    VK_STRUCTURE_TYPE_IOS_SURFACE_CREATE_INFO_MVK = 1000122000,
  // Provided by VK_MVK_macos_surface
    VK_STRUCTURE_TYPE_MACOS_SURFACE_CREATE_INFO_MVK = 1000123000,
  // Provided by VK_EXT_debug_utils
    VK_STRUCTURE_TYPE_DEBUG_UTILS_OBJECT_NAME_INFO_EXT = 1000128000,
  // Provided by VK_EXT_debug_utils
    VK_STRUCTURE_TYPE_DEBUG_UTILS_OBJECT_TAG_INFO_EXT = 1000128001,
  // Provided by VK_EXT_debug_utils
    VK_STRUCTURE_TYPE_DEBUG_UTILS_LABEL_EXT = 1000128002,
  // Provided by VK_EXT_debug_utils
    VK_STRUCTURE_TYPE_DEBUG_UTILS_MESSENGER_CALLBACK_DATA_EXT = 1000128003,
  // Provided by VK_EXT_debug_utils
    VK_STRUCTURE_TYPE_DEBUG_UTILS_MESSENGER_CREATE_INFO_EXT = 1000128004,
  // Provided by VK_ANDROID_external_memory_android_hardware_buffer
    VK_STRUCTURE_TYPE_ANDROID_HARDWARE_BUFFER_USAGE_ANDROID = 1000129000,
  // Provided by VK_ANDROID_external_memory_android_hardware_buffer
    VK_STRUCTURE_TYPE_ANDROID_HARDWARE_BUFFER_PROPERTIES_ANDROID = 1000129001,
  // Provided by VK_ANDROID_external_memory_android_hardware_buffer
    VK_STRUCTURE_TYPE_ANDROID_HARDWARE_BUFFER_FORMAT_PROPERTIES_ANDROID = 1000129002,
  // Provided by VK_ANDROID_external_memory_android_hardware_buffer
    VK_STRUCTURE_TYPE_IMPORT_ANDROID_HARDWARE_BUFFER_INFO_ANDROID = 1000129003,
  // Provided by VK_ANDROID_external_memory_android_hardware_buffer
    VK_STRUCTURE_TYPE_MEMORY_GET_ANDROID_HARDWARE_BUFFER_INFO_ANDROID = 1000129004,
  // Provided by VK_ANDROID_external_memory_android_hardware_buffer
    VK_STRUCTURE_TYPE_EXTERNAL_FORMAT_ANDROID = 1000129005,
  // Provided by VK_ANDROID_external_memory_android_hardware_buffer with VK_KHR_format_feature_flags2 or VK_VERSION_1_3
    VK_STRUCTURE_TYPE_ANDROID_HARDWARE_BUFFER_FORMAT_PROPERTIES_2_ANDROID = 1000129006,
#ifdef VK_ENABLE_BETA_EXTENSIONS
  // Provided by VK_AMDX_shader_enqueue
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_ENQUEUE_FEATURES_AMDX = 1000134000,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
  // Provided by VK_AMDX_shader_enqueue
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_ENQUEUE_PROPERTIES_AMDX = 1000134001,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
  // Provided by VK_AMDX_shader_enqueue
    VK_STRUCTURE_TYPE_EXECUTION_GRAPH_PIPELINE_SCRATCH_SIZE_AMDX = 1000134002,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
  // Provided by VK_AMDX_shader_enqueue
    VK_STRUCTURE_TYPE_EXECUTION_GRAPH_PIPELINE_CREATE_INFO_AMDX = 1000134003,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
  // Provided by VK_AMDX_shader_enqueue
    VK_STRUCTURE_TYPE_PIPELINE_SHADER_STAGE_NODE_CREATE_INFO_AMDX = 1000134004,
#endif
  // Provided by VK_EXT_sample_locations
    VK_STRUCTURE_TYPE_SAMPLE_LOCATIONS_INFO_EXT = 1000143000,
  // Provided by VK_EXT_sample_locations
    VK_STRUCTURE_TYPE_RENDER_PASS_SAMPLE_LOCATIONS_BEGIN_INFO_EXT = 1000143001,
  // Provided by VK_EXT_sample_locations
    VK_STRUCTURE_TYPE_PIPELINE_SAMPLE_LOCATIONS_STATE_CREATE_INFO_EXT = 1000143002,
  // Provided by VK_EXT_sample_locations
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SAMPLE_LOCATIONS_PROPERTIES_EXT = 1000143003,
  // Provided by VK_EXT_sample_locations
    VK_STRUCTURE_TYPE_MULTISAMPLE_PROPERTIES_EXT = 1000143004,
  // Provided by VK_EXT_blend_operation_advanced
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_BLEND_OPERATION_ADVANCED_FEATURES_EXT = 1000148000,
  // Provided by VK_EXT_blend_operation_advanced
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_BLEND_OPERATION_ADVANCED_PROPERTIES_EXT = 1000148001,
  // Provided by VK_EXT_blend_operation_advanced
    VK_STRUCTURE_TYPE_PIPELINE_COLOR_BLEND_ADVANCED_STATE_CREATE_INFO_EXT = 1000148002,
  // Provided by VK_NV_fragment_coverage_to_color
    VK_STRUCTURE_TYPE_PIPELINE_COVERAGE_TO_COLOR_STATE_CREATE_INFO_NV = 1000149000,
  // Provided by VK_KHR_acceleration_structure
    VK_STRUCTURE_TYPE_WRITE_DESCRIPTOR_SET_ACCELERATION_STRUCTURE_KHR = 1000150007,
  // Provided by VK_KHR_acceleration_structure
    VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_BUILD_GEOMETRY_INFO_KHR = 1000150000,
  // Provided by VK_KHR_acceleration_structure
    VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_DEVICE_ADDRESS_INFO_KHR = 1000150002,
  // Provided by VK_KHR_acceleration_structure
    VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_GEOMETRY_AABBS_DATA_KHR = 1000150003,
  // Provided by VK_KHR_acceleration_structure
    VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_GEOMETRY_INSTANCES_DATA_KHR = 1000150004,
  // Provided by VK_KHR_acceleration_structure
    VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_GEOMETRY_TRIANGLES_DATA_KHR = 1000150005,
  // Provided by VK_KHR_acceleration_structure
    VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_GEOMETRY_KHR = 1000150006,
  // Provided by VK_KHR_acceleration_structure
    VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_VERSION_INFO_KHR = 1000150009,
  // Provided by VK_KHR_acceleration_structure
    VK_STRUCTURE_TYPE_COPY_ACCELERATION_STRUCTURE_INFO_KHR = 1000150010,
  // Provided by VK_KHR_acceleration_structure
    VK_STRUCTURE_TYPE_COPY_ACCELERATION_STRUCTURE_TO_MEMORY_INFO_KHR = 1000150011,
  // Provided by VK_KHR_acceleration_structure
    VK_STRUCTURE_TYPE_COPY_MEMORY_TO_ACCELERATION_STRUCTURE_INFO_KHR = 1000150012,
  // Provided by VK_KHR_acceleration_structure
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_ACCELERATION_STRUCTURE_FEATURES_KHR = 1000150013,
  // Provided by VK_KHR_acceleration_structure
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_ACCELERATION_STRUCTURE_PROPERTIES_KHR = 1000150014,
  // Provided by VK_KHR_acceleration_structure
    VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_CREATE_INFO_KHR = 1000150017,
  // Provided by VK_KHR_acceleration_structure
    VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_BUILD_SIZES_INFO_KHR = 1000150020,
  // Provided by VK_KHR_ray_tracing_pipeline
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_RAY_TRACING_PIPELINE_FEATURES_KHR = 1000347000,
  // Provided by VK_KHR_ray_tracing_pipeline
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_RAY_TRACING_PIPELINE_PROPERTIES_KHR = 1000347001,
  // Provided by VK_KHR_ray_tracing_pipeline
    VK_STRUCTURE_TYPE_RAY_TRACING_PIPELINE_CREATE_INFO_KHR = 1000150015,
  // Provided by VK_KHR_ray_tracing_pipeline
    VK_STRUCTURE_TYPE_RAY_TRACING_SHADER_GROUP_CREATE_INFO_KHR = 1000150016,
  // Provided by VK_KHR_ray_tracing_pipeline
    VK_STRUCTURE_TYPE_RAY_TRACING_PIPELINE_INTERFACE_CREATE_INFO_KHR = 1000150018,
  // Provided by VK_KHR_ray_query
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_RAY_QUERY_FEATURES_KHR = 1000348013,
  // Provided by VK_NV_framebuffer_mixed_samples
    VK_STRUCTURE_TYPE_PIPELINE_COVERAGE_MODULATION_STATE_CREATE_INFO_NV = 1000152000,
  // Provided by VK_NV_shader_sm_builtins
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_SM_BUILTINS_FEATURES_NV = 1000154000,
  // Provided by VK_NV_shader_sm_builtins
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_SM_BUILTINS_PROPERTIES_NV = 1000154001,
  // Provided by VK_EXT_image_drm_format_modifier
    VK_STRUCTURE_TYPE_DRM_FORMAT_MODIFIER_PROPERTIES_LIST_EXT = 1000158000,
  // Provided by VK_EXT_image_drm_format_modifier
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGE_DRM_FORMAT_MODIFIER_INFO_EXT = 1000158002,
  // Provided by VK_EXT_image_drm_format_modifier
    VK_STRUCTURE_TYPE_IMAGE_DRM_FORMAT_MODIFIER_LIST_CREATE_INFO_EXT = 1000158003,
  // Provided by VK_EXT_image_drm_format_modifier
    VK_STRUCTURE_TYPE_IMAGE_DRM_FORMAT_MODIFIER_EXPLICIT_CREATE_INFO_EXT = 1000158004,
  // Provided by VK_EXT_image_drm_format_modifier
    VK_STRUCTURE_TYPE_IMAGE_DRM_FORMAT_MODIFIER_PROPERTIES_EXT = 1000158005,
  // Provided by VK_EXT_image_drm_format_modifier with VK_KHR_format_feature_flags2 or VK_VERSION_1_3
    VK_STRUCTURE_TYPE_DRM_FORMAT_MODIFIER_PROPERTIES_LIST_2_EXT = 1000158006,
  // Provided by VK_EXT_validation_cache
    VK_STRUCTURE_TYPE_VALIDATION_CACHE_CREATE_INFO_EXT = 1000160000,
  // Provided by VK_EXT_validation_cache
    VK_STRUCTURE_TYPE_SHADER_MODULE_VALIDATION_CACHE_CREATE_INFO_EXT = 1000160001,
#ifdef VK_ENABLE_BETA_EXTENSIONS
  // Provided by VK_KHR_portability_subset
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PORTABILITY_SUBSET_FEATURES_KHR = 1000163000,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
  // Provided by VK_KHR_portability_subset
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PORTABILITY_SUBSET_PROPERTIES_KHR = 1000163001,
#endif
  // Provided by VK_NV_shading_rate_image
    VK_STRUCTURE_TYPE_PIPELINE_VIEWPORT_SHADING_RATE_IMAGE_STATE_CREATE_INFO_NV = 1000164000,
  // Provided by VK_NV_shading_rate_image
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADING_RATE_IMAGE_FEATURES_NV = 1000164001,
  // Provided by VK_NV_shading_rate_image
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADING_RATE_IMAGE_PROPERTIES_NV = 1000164002,
  // Provided by VK_NV_shading_rate_image
    VK_STRUCTURE_TYPE_PIPELINE_VIEWPORT_COARSE_SAMPLE_ORDER_STATE_CREATE_INFO_NV = 1000164005,
  // Provided by VK_NV_ray_tracing
    VK_STRUCTURE_TYPE_RAY_TRACING_PIPELINE_CREATE_INFO_NV = 1000165000,
  // Provided by VK_NV_ray_tracing
    VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_CREATE_INFO_NV = 1000165001,
  // Provided by VK_NV_ray_tracing
    VK_STRUCTURE_TYPE_GEOMETRY_NV = 1000165003,
  // Provided by VK_NV_ray_tracing
    VK_STRUCTURE_TYPE_GEOMETRY_TRIANGLES_NV = 1000165004,
  // Provided by VK_NV_ray_tracing
    VK_STRUCTURE_TYPE_GEOMETRY_AABB_NV = 1000165005,
  // Provided by VK_NV_ray_tracing
    VK_STRUCTURE_TYPE_BIND_ACCELERATION_STRUCTURE_MEMORY_INFO_NV = 1000165006,
  // Provided by VK_NV_ray_tracing
    VK_STRUCTURE_TYPE_WRITE_DESCRIPTOR_SET_ACCELERATION_STRUCTURE_NV = 1000165007,
  // Provided by VK_NV_ray_tracing
    VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_INFO_NV = 1000165008,
  // Provided by VK_NV_ray_tracing
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_RAY_TRACING_PROPERTIES_NV = 1000165009,
  // Provided by VK_NV_ray_tracing
    VK_STRUCTURE_TYPE_RAY_TRACING_SHADER_GROUP_CREATE_INFO_NV = 1000165011,
  // Provided by VK_NV_ray_tracing
    VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_INFO_NV = 1000165012,
  // Provided by VK_NV_representative_fragment_test
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_REPRESENTATIVE_FRAGMENT_TEST_FEATURES_NV = 1000166000,
  // Provided by VK_NV_representative_fragment_test
    VK_STRUCTURE_TYPE_PIPELINE_REPRESENTATIVE_FRAGMENT_TEST_STATE_CREATE_INFO_NV = 1000166001,
  // Provided by VK_EXT_filter_cubic
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGE_VIEW_IMAGE_FORMAT_INFO_EXT = 1000170000,
  // Provided by VK_EXT_filter_cubic
    VK_STRUCTURE_TYPE_FILTER_CUBIC_IMAGE_VIEW_IMAGE_FORMAT_PROPERTIES_EXT = 1000170001,
  // Provided by VK_EXT_external_memory_host
    VK_STRUCTURE_TYPE_IMPORT_MEMORY_HOST_POINTER_INFO_EXT = 1000178000,
  // Provided by VK_EXT_external_memory_host
    VK_STRUCTURE_TYPE_MEMORY_HOST_POINTER_PROPERTIES_EXT = 1000178001,
  // Provided by VK_EXT_external_memory_host
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_EXTERNAL_MEMORY_HOST_PROPERTIES_EXT = 1000178002,
  // Provided by VK_KHR_shader_clock
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_CLOCK_FEATURES_KHR = 1000181000,
  // Provided by VK_AMD_pipeline_compiler_control
    VK_STRUCTURE_TYPE_PIPELINE_COMPILER_CONTROL_CREATE_INFO_AMD = 1000183000,
  // Provided by VK_AMD_shader_core_properties
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_CORE_PROPERTIES_AMD = 1000185000,
  // Provided by VK_KHR_video_decode_h265
    VK_STRUCTURE_TYPE_VIDEO_DECODE_H265_CAPABILITIES_KHR = 1000187000,
  // Provided by VK_KHR_video_decode_h265
    VK_STRUCTURE_TYPE_VIDEO_DECODE_H265_SESSION_PARAMETERS_CREATE_INFO_KHR = 1000187001,
  // Provided by VK_KHR_video_decode_h265
    VK_STRUCTURE_TYPE_VIDEO_DECODE_H265_SESSION_PARAMETERS_ADD_INFO_KHR = 1000187002,
  // Provided by VK_KHR_video_decode_h265
    VK_STRUCTURE_TYPE_VIDEO_DECODE_H265_PROFILE_INFO_KHR = 1000187003,
  // Provided by VK_KHR_video_decode_h265
    VK_STRUCTURE_TYPE_VIDEO_DECODE_H265_PICTURE_INFO_KHR = 1000187004,
  // Provided by VK_KHR_video_decode_h265
    VK_STRUCTURE_TYPE_VIDEO_DECODE_H265_DPB_SLOT_INFO_KHR = 1000187005,
  // Provided by VK_KHR_global_priority
    VK_STRUCTURE_TYPE_DEVICE_QUEUE_GLOBAL_PRIORITY_CREATE_INFO_KHR = 1000174000,
  // Provided by VK_KHR_global_priority
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_GLOBAL_PRIORITY_QUERY_FEATURES_KHR = 1000388000,
  // Provided by VK_KHR_global_priority
    VK_STRUCTURE_TYPE_QUEUE_FAMILY_GLOBAL_PRIORITY_PROPERTIES_KHR = 1000388001,
  // Provided by VK_AMD_memory_overallocation_behavior
    VK_STRUCTURE_TYPE_DEVICE_MEMORY_OVERALLOCATION_CREATE_INFO_AMD = 1000189000,
  // Provided by VK_EXT_vertex_attribute_divisor
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VERTEX_ATTRIBUTE_DIVISOR_PROPERTIES_EXT = 1000190000,
  // Provided by VK_GGP_frame_token
    VK_STRUCTURE_TYPE_PRESENT_FRAME_TOKEN_GGP = 1000191000,
  // Provided by VK_NV_mesh_shader
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MESH_SHADER_FEATURES_NV = 1000202000,
  // Provided by VK_NV_mesh_shader
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MESH_SHADER_PROPERTIES_NV = 1000202001,
  // Provided by VK_NV_shader_image_footprint
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_IMAGE_FOOTPRINT_FEATURES_NV = 1000204000,
  // Provided by VK_NV_scissor_exclusive
    VK_STRUCTURE_TYPE_PIPELINE_VIEWPORT_EXCLUSIVE_SCISSOR_STATE_CREATE_INFO_NV = 1000205000,
  // Provided by VK_NV_scissor_exclusive
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_EXCLUSIVE_SCISSOR_FEATURES_NV = 1000205002,
  // Provided by VK_NV_device_diagnostic_checkpoints
    VK_STRUCTURE_TYPE_CHECKPOINT_DATA_NV = 1000206000,
  // Provided by VK_NV_device_diagnostic_checkpoints
    VK_STRUCTURE_TYPE_QUEUE_FAMILY_CHECKPOINT_PROPERTIES_NV = 1000206001,
  // Provided by VK_INTEL_shader_integer_functions2
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_INTEGER_FUNCTIONS_2_FEATURES_INTEL = 1000209000,
  // Provided by VK_INTEL_performance_query
    VK_STRUCTURE_TYPE_QUERY_POOL_PERFORMANCE_QUERY_CREATE_INFO_INTEL = 1000210000,
  // Provided by VK_INTEL_performance_query
    VK_STRUCTURE_TYPE_INITIALIZE_PERFORMANCE_API_INFO_INTEL = 1000210001,
  // Provided by VK_INTEL_performance_query
    VK_STRUCTURE_TYPE_PERFORMANCE_MARKER_INFO_INTEL = 1000210002,
  // Provided by VK_INTEL_performance_query
    VK_STRUCTURE_TYPE_PERFORMANCE_STREAM_MARKER_INFO_INTEL = 1000210003,
  // Provided by VK_INTEL_performance_query
    VK_STRUCTURE_TYPE_PERFORMANCE_OVERRIDE_INFO_INTEL = 1000210004,
  // Provided by VK_INTEL_performance_query
    VK_STRUCTURE_TYPE_PERFORMANCE_CONFIGURATION_ACQUIRE_INFO_INTEL = 1000210005,
  // Provided by VK_EXT_pci_bus_info
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PCI_BUS_INFO_PROPERTIES_EXT = 1000212000,
  // Provided by VK_AMD_display_native_hdr
    VK_STRUCTURE_TYPE_DISPLAY_NATIVE_HDR_SURFACE_CAPABILITIES_AMD = 1000213000,
  // Provided by VK_AMD_display_native_hdr
    VK_STRUCTURE_TYPE_SWAPCHAIN_DISPLAY_NATIVE_HDR_CREATE_INFO_AMD = 1000213001,
  // Provided by VK_FUCHSIA_imagepipe_surface
    VK_STRUCTURE_TYPE_IMAGEPIPE_SURFACE_CREATE_INFO_FUCHSIA = 1000214000,
  // Provided by VK_EXT_metal_surface
    VK_STRUCTURE_TYPE_METAL_SURFACE_CREATE_INFO_EXT = 1000217000,
  // Provided by VK_EXT_fragment_density_map
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FRAGMENT_DENSITY_MAP_FEATURES_EXT = 1000218000,
  // Provided by VK_EXT_fragment_density_map
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FRAGMENT_DENSITY_MAP_PROPERTIES_EXT = 1000218001,
  // Provided by VK_EXT_fragment_density_map
    VK_STRUCTURE_TYPE_RENDER_PASS_FRAGMENT_DENSITY_MAP_CREATE_INFO_EXT = 1000218002,
  // Provided by VK_KHR_fragment_shading_rate
    VK_STRUCTURE_TYPE_FRAGMENT_SHADING_RATE_ATTACHMENT_INFO_KHR = 1000226000,
  // Provided by VK_KHR_fragment_shading_rate
    VK_STRUCTURE_TYPE_PIPELINE_FRAGMENT_SHADING_RATE_STATE_CREATE_INFO_KHR = 1000226001,
  // Provided by VK_KHR_fragment_shading_rate
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FRAGMENT_SHADING_RATE_PROPERTIES_KHR = 1000226002,
  // Provided by VK_KHR_fragment_shading_rate
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FRAGMENT_SHADING_RATE_FEATURES_KHR = 1000226003,
  // Provided by VK_KHR_fragment_shading_rate
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FRAGMENT_SHADING_RATE_KHR = 1000226004,
  // Provided by VK_AMD_shader_core_properties2
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_CORE_PROPERTIES_2_AMD = 1000227000,
  // Provided by VK_AMD_device_coherent_memory
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_COHERENT_MEMORY_FEATURES_AMD = 1000229000,
  // Provided by VK_KHR_dynamic_rendering_local_read
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DYNAMIC_RENDERING_LOCAL_READ_FEATURES_KHR = 1000232000,
  // Provided by VK_KHR_dynamic_rendering_local_read
    VK_STRUCTURE_TYPE_RENDERING_ATTACHMENT_LOCATION_INFO_KHR = 1000232001,
  // Provided by VK_KHR_dynamic_rendering_local_read
    VK_STRUCTURE_TYPE_RENDERING_INPUT_ATTACHMENT_INDEX_INFO_KHR = 1000232002,
  // Provided by VK_EXT_shader_image_atomic_int64
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_IMAGE_ATOMIC_INT64_FEATURES_EXT = 1000234000,
  // Provided by VK_KHR_shader_quad_control
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_QUAD_CONTROL_FEATURES_KHR = 1000235000,
  // Provided by VK_EXT_memory_budget
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MEMORY_BUDGET_PROPERTIES_EXT = 1000237000,
  // Provided by VK_EXT_memory_priority
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MEMORY_PRIORITY_FEATURES_EXT = 1000238000,
  // Provided by VK_EXT_memory_priority
    VK_STRUCTURE_TYPE_MEMORY_PRIORITY_ALLOCATE_INFO_EXT = 1000238001,
  // Provided by VK_KHR_surface_protected_capabilities
    VK_STRUCTURE_TYPE_SURFACE_PROTECTED_CAPABILITIES_KHR = 1000239000,
  // Provided by VK_NV_dedicated_allocation_image_aliasing
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DEDICATED_ALLOCATION_IMAGE_ALIASING_FEATURES_NV = 1000240000,
  // Provided by VK_EXT_buffer_device_address
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_BUFFER_DEVICE_ADDRESS_FEATURES_EXT = 1000244000,
  // Provided by VK_EXT_buffer_device_address
    VK_STRUCTURE_TYPE_BUFFER_DEVICE_ADDRESS_CREATE_INFO_EXT = 1000244002,
  // Provided by VK_EXT_validation_features
    VK_STRUCTURE_TYPE_VALIDATION_FEATURES_EXT = 1000247000,
  // Provided by VK_KHR_present_wait
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PRESENT_WAIT_FEATURES_KHR = 1000248000,
  // Provided by VK_NV_cooperative_matrix
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_COOPERATIVE_MATRIX_FEATURES_NV = 1000249000,
  // Provided by VK_NV_cooperative_matrix
    VK_STRUCTURE_TYPE_COOPERATIVE_MATRIX_PROPERTIES_NV = 1000249001,
  // Provided by VK_NV_cooperative_matrix
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_COOPERATIVE_MATRIX_PROPERTIES_NV = 1000249002,
  // Provided by VK_NV_coverage_reduction_mode
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_COVERAGE_REDUCTION_MODE_FEATURES_NV = 1000250000,
  // Provided by VK_NV_coverage_reduction_mode
    VK_STRUCTURE_TYPE_PIPELINE_COVERAGE_REDUCTION_STATE_CREATE_INFO_NV = 1000250001,
  // Provided by VK_NV_coverage_reduction_mode
    VK_STRUCTURE_TYPE_FRAMEBUFFER_MIXED_SAMPLES_COMBINATION_NV = 1000250002,
  // Provided by VK_EXT_fragment_shader_interlock
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FRAGMENT_SHADER_INTERLOCK_FEATURES_EXT = 1000251000,
  // Provided by VK_EXT_ycbcr_image_arrays
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_YCBCR_IMAGE_ARRAYS_FEATURES_EXT = 1000252000,
  // Provided by VK_EXT_provoking_vertex
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PROVOKING_VERTEX_FEATURES_EXT = 1000254000,
  // Provided by VK_EXT_provoking_vertex
    VK_STRUCTURE_TYPE_PIPELINE_RASTERIZATION_PROVOKING_VERTEX_STATE_CREATE_INFO_EXT = 1000254001,
  // Provided by VK_EXT_provoking_vertex
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PROVOKING_VERTEX_PROPERTIES_EXT = 1000254002,
  // Provided by VK_EXT_full_screen_exclusive
    VK_STRUCTURE_TYPE_SURFACE_FULL_SCREEN_EXCLUSIVE_INFO_EXT = 1000255000,
  // Provided by VK_EXT_full_screen_exclusive
    VK_STRUCTURE_TYPE_SURFACE_CAPABILITIES_FULL_SCREEN_EXCLUSIVE_EXT = 1000255002,
  // Provided by VK_KHR_win32_surface with VK_EXT_full_screen_exclusive
    VK_STRUCTURE_TYPE_SURFACE_FULL_SCREEN_EXCLUSIVE_WIN32_INFO_EXT = 1000255001,
  // Provided by VK_EXT_headless_surface
    VK_STRUCTURE_TYPE_HEADLESS_SURFACE_CREATE_INFO_EXT = 1000256000,
  // Provided by VK_EXT_shader_atomic_float
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_ATOMIC_FLOAT_FEATURES_EXT = 1000260000,
  // Provided by VK_EXT_extended_dynamic_state
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_EXTENDED_DYNAMIC_STATE_FEATURES_EXT = 1000267000,
  // Provided by VK_KHR_pipeline_executable_properties
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PIPELINE_EXECUTABLE_PROPERTIES_FEATURES_KHR = 1000269000,
  // Provided by VK_KHR_pipeline_executable_properties
    VK_STRUCTURE_TYPE_PIPELINE_INFO_KHR = 1000269001,
  // Provided by VK_KHR_pipeline_executable_properties
    VK_STRUCTURE_TYPE_PIPELINE_EXECUTABLE_PROPERTIES_KHR = 1000269002,
  // Provided by VK_KHR_pipeline_executable_properties
    VK_STRUCTURE_TYPE_PIPELINE_EXECUTABLE_INFO_KHR = 1000269003,
  // Provided by VK_KHR_pipeline_executable_properties
    VK_STRUCTURE_TYPE_PIPELINE_EXECUTABLE_STATISTIC_KHR = 1000269004,
  // Provided by VK_KHR_pipeline_executable_properties
    VK_STRUCTURE_TYPE_PIPELINE_EXECUTABLE_INTERNAL_REPRESENTATION_KHR = 1000269005,
  // Provided by VK_EXT_host_image_copy
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_HOST_IMAGE_COPY_FEATURES_EXT = 1000270000,
  // Provided by VK_EXT_host_image_copy
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_HOST_IMAGE_COPY_PROPERTIES_EXT = 1000270001,
  // Provided by VK_EXT_host_image_copy
    VK_STRUCTURE_TYPE_MEMORY_TO_IMAGE_COPY_EXT = 1000270002,
  // Provided by VK_EXT_host_image_copy
    VK_STRUCTURE_TYPE_IMAGE_TO_MEMORY_COPY_EXT = 1000270003,
  // Provided by VK_EXT_host_image_copy
    VK_STRUCTURE_TYPE_COPY_IMAGE_TO_MEMORY_INFO_EXT = 1000270004,
  // Provided by VK_EXT_host_image_copy
    VK_STRUCTURE_TYPE_COPY_MEMORY_TO_IMAGE_INFO_EXT = 1000270005,
  // Provided by VK_EXT_host_image_copy
    VK_STRUCTURE_TYPE_HOST_IMAGE_LAYOUT_TRANSITION_INFO_EXT = 1000270006,
  // Provided by VK_EXT_host_image_copy
    VK_STRUCTURE_TYPE_COPY_IMAGE_TO_IMAGE_INFO_EXT = 1000270007,
  // Provided by VK_EXT_host_image_copy
    VK_STRUCTURE_TYPE_SUBRESOURCE_HOST_MEMCPY_SIZE_EXT = 1000270008,
  // Provided by VK_EXT_host_image_copy
    VK_STRUCTURE_TYPE_HOST_IMAGE_COPY_DEVICE_PERFORMANCE_QUERY_EXT = 1000270009,
  // Provided by VK_KHR_map_memory2
    VK_STRUCTURE_TYPE_MEMORY_MAP_INFO_KHR = 1000271000,
  // Provided by VK_KHR_map_memory2
    VK_STRUCTURE_TYPE_MEMORY_UNMAP_INFO_KHR = 1000271001,
  // Provided by VK_EXT_map_memory_placed
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MAP_MEMORY_PLACED_FEATURES_EXT = 1000272000,
  // Provided by VK_EXT_map_memory_placed
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MAP_MEMORY_PLACED_PROPERTIES_EXT = 1000272001,
  // Provided by VK_EXT_map_memory_placed
    VK_STRUCTURE_TYPE_MEMORY_MAP_PLACED_INFO_EXT = 1000272002,
  // Provided by VK_EXT_shader_atomic_float2
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_ATOMIC_FLOAT_2_FEATURES_EXT = 1000273000,
  // Provided by VK_EXT_surface_maintenance1
    VK_STRUCTURE_TYPE_SURFACE_PRESENT_MODE_EXT = 1000274000,
  // Provided by VK_EXT_surface_maintenance1
    VK_STRUCTURE_TYPE_SURFACE_PRESENT_SCALING_CAPABILITIES_EXT = 1000274001,
  // Provided by VK_EXT_surface_maintenance1
    VK_STRUCTURE_TYPE_SURFACE_PRESENT_MODE_COMPATIBILITY_EXT = 1000274002,
  // Provided by VK_EXT_swapchain_maintenance1
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SWAPCHAIN_MAINTENANCE_1_FEATURES_EXT = 1000275000,
  // Provided by VK_EXT_swapchain_maintenance1
    VK_STRUCTURE_TYPE_SWAPCHAIN_PRESENT_FENCE_INFO_EXT = 1000275001,
  // Provided by VK_EXT_swapchain_maintenance1
    VK_STRUCTURE_TYPE_SWAPCHAIN_PRESENT_MODES_CREATE_INFO_EXT = 1000275002,
  // Provided by VK_EXT_swapchain_maintenance1
    VK_STRUCTURE_TYPE_SWAPCHAIN_PRESENT_MODE_INFO_EXT = 1000275003,
  // Provided by VK_EXT_swapchain_maintenance1
    VK_STRUCTURE_TYPE_SWAPCHAIN_PRESENT_SCALING_CREATE_INFO_EXT = 1000275004,
  // Provided by VK_EXT_swapchain_maintenance1
    VK_STRUCTURE_TYPE_RELEASE_SWAPCHAIN_IMAGES_INFO_EXT = 1000275005,
  // Provided by VK_NV_device_generated_commands
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DEVICE_GENERATED_COMMANDS_PROPERTIES_NV = 1000277000,
  // Provided by VK_NV_device_generated_commands
    VK_STRUCTURE_TYPE_GRAPHICS_SHADER_GROUP_CREATE_INFO_NV = 1000277001,
  // Provided by VK_NV_device_generated_commands
    VK_STRUCTURE_TYPE_GRAPHICS_PIPELINE_SHADER_GROUPS_CREATE_INFO_NV = 1000277002,
  // Provided by VK_NV_device_generated_commands
    VK_STRUCTURE_TYPE_INDIRECT_COMMANDS_LAYOUT_TOKEN_NV = 1000277003,
  // Provided by VK_NV_device_generated_commands
    VK_STRUCTURE_TYPE_INDIRECT_COMMANDS_LAYOUT_CREATE_INFO_NV = 1000277004,
  // Provided by VK_NV_device_generated_commands
    VK_STRUCTURE_TYPE_GENERATED_COMMANDS_INFO_NV = 1000277005,
  // Provided by VK_NV_device_generated_commands
    VK_STRUCTURE_TYPE_GENERATED_COMMANDS_MEMORY_REQUIREMENTS_INFO_NV = 1000277006,
  // Provided by VK_NV_device_generated_commands
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DEVICE_GENERATED_COMMANDS_FEATURES_NV = 1000277007,
  // Provided by VK_NV_inherited_viewport_scissor
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_INHERITED_VIEWPORT_SCISSOR_FEATURES_NV = 1000278000,
  // Provided by VK_NV_inherited_viewport_scissor
    VK_STRUCTURE_TYPE_COMMAND_BUFFER_INHERITANCE_VIEWPORT_SCISSOR_INFO_NV = 1000278001,
  // Provided by VK_EXT_texel_buffer_alignment
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_TEXEL_BUFFER_ALIGNMENT_FEATURES_EXT = 1000281000,
  // Provided by VK_QCOM_render_pass_transform
    VK_STRUCTURE_TYPE_COMMAND_BUFFER_INHERITANCE_RENDER_PASS_TRANSFORM_INFO_QCOM = 1000282000,
  // Provided by VK_QCOM_render_pass_transform
    VK_STRUCTURE_TYPE_RENDER_PASS_TRANSFORM_BEGIN_INFO_QCOM = 1000282001,
  // Provided by VK_EXT_depth_bias_control
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DEPTH_BIAS_CONTROL_FEATURES_EXT = 1000283000,
  // Provided by VK_EXT_depth_bias_control
    VK_STRUCTURE_TYPE_DEPTH_BIAS_INFO_EXT = 1000283001,
  // Provided by VK_EXT_depth_bias_control
    VK_STRUCTURE_TYPE_DEPTH_BIAS_REPRESENTATION_INFO_EXT = 1000283002,
  // Provided by VK_EXT_device_memory_report
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DEVICE_MEMORY_REPORT_FEATURES_EXT = 1000284000,
  // Provided by VK_EXT_device_memory_report
    VK_STRUCTURE_TYPE_DEVICE_DEVICE_MEMORY_REPORT_CREATE_INFO_EXT = 1000284001,
  // Provided by VK_EXT_device_memory_report
    VK_STRUCTURE_TYPE_DEVICE_MEMORY_REPORT_CALLBACK_DATA_EXT = 1000284002,
  // Provided by VK_EXT_robustness2
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_ROBUSTNESS_2_FEATURES_EXT = 1000286000,
  // Provided by VK_EXT_robustness2
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_ROBUSTNESS_2_PROPERTIES_EXT = 1000286001,
  // Provided by VK_EXT_custom_border_color
    VK_STRUCTURE_TYPE_SAMPLER_CUSTOM_BORDER_COLOR_CREATE_INFO_EXT = 1000287000,
  // Provided by VK_EXT_custom_border_color
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_CUSTOM_BORDER_COLOR_PROPERTIES_EXT = 1000287001,
  // Provided by VK_EXT_custom_border_color
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_CUSTOM_BORDER_COLOR_FEATURES_EXT = 1000287002,
  // Provided by VK_KHR_pipeline_library
    VK_STRUCTURE_TYPE_PIPELINE_LIBRARY_CREATE_INFO_KHR = 1000290000,
  // Provided by VK_NV_present_barrier
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PRESENT_BARRIER_FEATURES_NV = 1000292000,
  // Provided by VK_NV_present_barrier
    VK_STRUCTURE_TYPE_SURFACE_CAPABILITIES_PRESENT_BARRIER_NV = 1000292001,
  // Provided by VK_NV_present_barrier
    VK_STRUCTURE_TYPE_SWAPCHAIN_PRESENT_BARRIER_CREATE_INFO_NV = 1000292002,
  // Provided by VK_KHR_present_id
    VK_STRUCTURE_TYPE_PRESENT_ID_KHR = 1000294000,
  // Provided by VK_KHR_present_id
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PRESENT_ID_FEATURES_KHR = 1000294001,
  // Provided by VK_KHR_video_encode_queue
    VK_STRUCTURE_TYPE_VIDEO_ENCODE_INFO_KHR = 1000299000,
  // Provided by VK_KHR_video_encode_queue
    VK_STRUCTURE_TYPE_VIDEO_ENCODE_RATE_CONTROL_INFO_KHR = 1000299001,
  // Provided by VK_KHR_video_encode_queue
    VK_STRUCTURE_TYPE_VIDEO_ENCODE_RATE_CONTROL_LAYER_INFO_KHR = 1000299002,
  // Provided by VK_KHR_video_encode_queue
    VK_STRUCTURE_TYPE_VIDEO_ENCODE_CAPABILITIES_KHR = 1000299003,
  // Provided by VK_KHR_video_encode_queue
    VK_STRUCTURE_TYPE_VIDEO_ENCODE_USAGE_INFO_KHR = 1000299004,
  // Provided by VK_KHR_video_encode_queue
    VK_STRUCTURE_TYPE_QUERY_POOL_VIDEO_ENCODE_FEEDBACK_CREATE_INFO_KHR = 1000299005,
  // Provided by VK_KHR_video_encode_queue
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VIDEO_ENCODE_QUALITY_LEVEL_INFO_KHR = 1000299006,
  // Provided by VK_KHR_video_encode_queue
    VK_STRUCTURE_TYPE_VIDEO_ENCODE_QUALITY_LEVEL_PROPERTIES_KHR = 1000299007,
  // Provided by VK_KHR_video_encode_queue
    VK_STRUCTURE_TYPE_VIDEO_ENCODE_QUALITY_LEVEL_INFO_KHR = 1000299008,
  // Provided by VK_KHR_video_encode_queue
    VK_STRUCTURE_TYPE_VIDEO_ENCODE_SESSION_PARAMETERS_GET_INFO_KHR = 1000299009,
  // Provided by VK_KHR_video_encode_queue
    VK_STRUCTURE_TYPE_VIDEO_ENCODE_SESSION_PARAMETERS_FEEDBACK_INFO_KHR = 1000299010,
  // Provided by VK_NV_device_diagnostics_config
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DIAGNOSTICS_CONFIG_FEATURES_NV = 1000300000,
  // Provided by VK_NV_device_diagnostics_config
    VK_STRUCTURE_TYPE_DEVICE_DIAGNOSTICS_CONFIG_CREATE_INFO_NV = 1000300001,
  // Provided by VK_NV_cuda_kernel_launch
    VK_STRUCTURE_TYPE_CUDA_MODULE_CREATE_INFO_NV = 1000307000,
  // Provided by VK_NV_cuda_kernel_launch
    VK_STRUCTURE_TYPE_CUDA_FUNCTION_CREATE_INFO_NV = 1000307001,
  // Provided by VK_NV_cuda_kernel_launch
    VK_STRUCTURE_TYPE_CUDA_LAUNCH_INFO_NV = 1000307002,
  // Provided by VK_NV_cuda_kernel_launch
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_CUDA_KERNEL_LAUNCH_FEATURES_NV = 1000307003,
  // Provided by VK_NV_cuda_kernel_launch
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_CUDA_KERNEL_LAUNCH_PROPERTIES_NV = 1000307004,
  // Provided by VK_NV_low_latency
    VK_STRUCTURE_TYPE_QUERY_LOW_LATENCY_SUPPORT_NV = 1000310000,
  // Provided by VK_EXT_metal_objects
    VK_STRUCTURE_TYPE_EXPORT_METAL_OBJECT_CREATE_INFO_EXT = 1000311000,
  // Provided by VK_EXT_metal_objects
    VK_STRUCTURE_TYPE_EXPORT_METAL_OBJECTS_INFO_EXT = 1000311001,
  // Provided by VK_EXT_metal_objects
    VK_STRUCTURE_TYPE_EXPORT_METAL_DEVICE_INFO_EXT = 1000311002,
  // Provided by VK_EXT_metal_objects
    VK_STRUCTURE_TYPE_EXPORT_METAL_COMMAND_QUEUE_INFO_EXT = 1000311003,
  // Provided by VK_EXT_metal_objects
    VK_STRUCTURE_TYPE_EXPORT_METAL_BUFFER_INFO_EXT = 1000311004,
  // Provided by VK_EXT_metal_objects
    VK_STRUCTURE_TYPE_IMPORT_METAL_BUFFER_INFO_EXT = 1000311005,
  // Provided by VK_EXT_metal_objects
    VK_STRUCTURE_TYPE_EXPORT_METAL_TEXTURE_INFO_EXT = 1000311006,
  // Provided by VK_EXT_metal_objects
    VK_STRUCTURE_TYPE_IMPORT_METAL_TEXTURE_INFO_EXT = 1000311007,
  // Provided by VK_EXT_metal_objects
    VK_STRUCTURE_TYPE_EXPORT_METAL_IO_SURFACE_INFO_EXT = 1000311008,
  // Provided by VK_EXT_metal_objects
    VK_STRUCTURE_TYPE_IMPORT_METAL_IO_SURFACE_INFO_EXT = 1000311009,
  // Provided by VK_EXT_metal_objects
    VK_STRUCTURE_TYPE_EXPORT_METAL_SHARED_EVENT_INFO_EXT = 1000311010,
  // Provided by VK_EXT_metal_objects
    VK_STRUCTURE_TYPE_IMPORT_METAL_SHARED_EVENT_INFO_EXT = 1000311011,
  // Provided by VK_KHR_synchronization2 with VK_NV_device_diagnostic_checkpoints
    VK_STRUCTURE_TYPE_QUEUE_FAMILY_CHECKPOINT_PROPERTIES_2_NV = 1000314008,
  // Provided by VK_KHR_synchronization2 with VK_NV_device_diagnostic_checkpoints
    VK_STRUCTURE_TYPE_CHECKPOINT_DATA_2_NV = 1000314009,
  // Provided by VK_EXT_descriptor_buffer
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DESCRIPTOR_BUFFER_PROPERTIES_EXT = 1000316000,
  // Provided by VK_EXT_descriptor_buffer
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DESCRIPTOR_BUFFER_DENSITY_MAP_PROPERTIES_EXT = 1000316001,
  // Provided by VK_EXT_descriptor_buffer
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DESCRIPTOR_BUFFER_FEATURES_EXT = 1000316002,
  // Provided by VK_EXT_descriptor_buffer
    VK_STRUCTURE_TYPE_DESCRIPTOR_ADDRESS_INFO_EXT = 1000316003,
  // Provided by VK_EXT_descriptor_buffer
    VK_STRUCTURE_TYPE_DESCRIPTOR_GET_INFO_EXT = 1000316004,
  // Provided by VK_EXT_descriptor_buffer
    VK_STRUCTURE_TYPE_BUFFER_CAPTURE_DESCRIPTOR_DATA_INFO_EXT = 1000316005,
  // Provided by VK_EXT_descriptor_buffer
    VK_STRUCTURE_TYPE_IMAGE_CAPTURE_DESCRIPTOR_DATA_INFO_EXT = 1000316006,
  // Provided by VK_EXT_descriptor_buffer
    VK_STRUCTURE_TYPE_IMAGE_VIEW_CAPTURE_DESCRIPTOR_DATA_INFO_EXT = 1000316007,
  // Provided by VK_EXT_descriptor_buffer
    VK_STRUCTURE_TYPE_SAMPLER_CAPTURE_DESCRIPTOR_DATA_INFO_EXT = 1000316008,
  // Provided by VK_EXT_descriptor_buffer
    VK_STRUCTURE_TYPE_OPAQUE_CAPTURE_DESCRIPTOR_DATA_CREATE_INFO_EXT = 1000316010,
  // Provided by VK_EXT_descriptor_buffer
    VK_STRUCTURE_TYPE_DESCRIPTOR_BUFFER_BINDING_INFO_EXT = 1000316011,
  // Provided by VK_EXT_descriptor_buffer
    VK_STRUCTURE_TYPE_DESCRIPTOR_BUFFER_BINDING_PUSH_DESCRIPTOR_BUFFER_HANDLE_EXT = 1000316012,
  // Provided by VK_EXT_descriptor_buffer with VK_KHR_acceleration_structure or VK_NV_ray_tracing
    VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_CAPTURE_DESCRIPTOR_DATA_INFO_EXT = 1000316009,
  // Provided by VK_EXT_graphics_pipeline_library
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_GRAPHICS_PIPELINE_LIBRARY_FEATURES_EXT = 1000320000,
  // Provided by VK_EXT_graphics_pipeline_library
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_GRAPHICS_PIPELINE_LIBRARY_PROPERTIES_EXT = 1000320001,
  // Provided by VK_EXT_graphics_pipeline_library
    VK_STRUCTURE_TYPE_GRAPHICS_PIPELINE_LIBRARY_CREATE_INFO_EXT = 1000320002,
  // Provided by VK_AMD_shader_early_and_late_fragment_tests
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_EARLY_AND_LATE_FRAGMENT_TESTS_FEATURES_AMD = 1000321000,
  // Provided by VK_KHR_fragment_shader_barycentric
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FRAGMENT_SHADER_BARYCENTRIC_FEATURES_KHR = 1000203000,
  // Provided by VK_KHR_fragment_shader_barycentric
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FRAGMENT_SHADER_BARYCENTRIC_PROPERTIES_KHR = 1000322000,
  // Provided by VK_KHR_shader_subgroup_uniform_control_flow
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_SUBGROUP_UNIFORM_CONTROL_FLOW_FEATURES_KHR = 1000323000,
  // Provided by VK_NV_fragment_shading_rate_enums
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FRAGMENT_SHADING_RATE_ENUMS_PROPERTIES_NV = 1000326000,
  // Provided by VK_NV_fragment_shading_rate_enums
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FRAGMENT_SHADING_RATE_ENUMS_FEATURES_NV = 1000326001,
  // Provided by VK_NV_fragment_shading_rate_enums
    VK_STRUCTURE_TYPE_PIPELINE_FRAGMENT_SHADING_RATE_ENUM_STATE_CREATE_INFO_NV = 1000326002,
  // Provided by VK_NV_ray_tracing_motion_blur
    VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_GEOMETRY_MOTION_TRIANGLES_DATA_NV = 1000327000,
  // Provided by VK_NV_ray_tracing_motion_blur
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_RAY_TRACING_MOTION_BLUR_FEATURES_NV = 1000327001,
  // Provided by VK_NV_ray_tracing_motion_blur
    VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_MOTION_INFO_NV = 1000327002,
  // Provided by VK_EXT_mesh_shader
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MESH_SHADER_FEATURES_EXT = 1000328000,
  // Provided by VK_EXT_mesh_shader
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MESH_SHADER_PROPERTIES_EXT = 1000328001,
  // Provided by VK_EXT_ycbcr_2plane_444_formats
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_YCBCR_2_PLANE_444_FORMATS_FEATURES_EXT = 1000330000,
  // Provided by VK_EXT_fragment_density_map2
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FRAGMENT_DENSITY_MAP_2_FEATURES_EXT = 1000332000,
  // Provided by VK_EXT_fragment_density_map2
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FRAGMENT_DENSITY_MAP_2_PROPERTIES_EXT = 1000332001,
  // Provided by VK_QCOM_rotated_copy_commands
    VK_STRUCTURE_TYPE_COPY_COMMAND_TRANSFORM_INFO_QCOM = 1000333000,
  // Provided by VK_KHR_workgroup_memory_explicit_layout
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_WORKGROUP_MEMORY_EXPLICIT_LAYOUT_FEATURES_KHR = 1000336000,
  // Provided by VK_EXT_image_compression_control
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGE_COMPRESSION_CONTROL_FEATURES_EXT = 1000338000,
  // Provided by VK_EXT_image_compression_control
    VK_STRUCTURE_TYPE_IMAGE_COMPRESSION_CONTROL_EXT = 1000338001,
  // Provided by VK_EXT_image_compression_control
    VK_STRUCTURE_TYPE_IMAGE_COMPRESSION_PROPERTIES_EXT = 1000338004,
  // Provided by VK_EXT_attachment_feedback_loop_layout
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_ATTACHMENT_FEEDBACK_LOOP_LAYOUT_FEATURES_EXT = 1000339000,
  // Provided by VK_EXT_4444_formats
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_4444_FORMATS_FEATURES_EXT = 1000340000,
  // Provided by VK_EXT_device_fault
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FAULT_FEATURES_EXT = 1000341000,
  // Provided by VK_EXT_device_fault
    VK_STRUCTURE_TYPE_DEVICE_FAULT_COUNTS_EXT = 1000341001,
  // Provided by VK_EXT_device_fault
    VK_STRUCTURE_TYPE_DEVICE_FAULT_INFO_EXT = 1000341002,
  // Provided by VK_EXT_rgba10x6_formats
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_RGBA10X6_FORMATS_FEATURES_EXT = 1000344000,
  // Provided by VK_EXT_directfb_surface
    VK_STRUCTURE_TYPE_DIRECTFB_SURFACE_CREATE_INFO_EXT = 1000346000,
  // Provided by VK_EXT_vertex_input_dynamic_state
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VERTEX_INPUT_DYNAMIC_STATE_FEATURES_EXT = 1000352000,
  // Provided by VK_EXT_shader_object, VK_EXT_vertex_input_dynamic_state
    VK_STRUCTURE_TYPE_VERTEX_INPUT_BINDING_DESCRIPTION_2_EXT = 1000352001,
  // Provided by VK_EXT_shader_object, VK_EXT_vertex_input_dynamic_state
    VK_STRUCTURE_TYPE_VERTEX_INPUT_ATTRIBUTE_DESCRIPTION_2_EXT = 1000352002,
  // Provided by VK_EXT_physical_device_drm
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DRM_PROPERTIES_EXT = 1000353000,
  // Provided by VK_EXT_device_address_binding_report
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_ADDRESS_BINDING_REPORT_FEATURES_EXT = 1000354000,
  // Provided by VK_EXT_device_address_binding_report
    VK_STRUCTURE_TYPE_DEVICE_ADDRESS_BINDING_CALLBACK_DATA_EXT = 1000354001,
  // Provided by VK_EXT_depth_clip_control
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DEPTH_CLIP_CONTROL_FEATURES_EXT = 1000355000,
  // Provided by VK_EXT_depth_clip_control
    VK_STRUCTURE_TYPE_PIPELINE_VIEWPORT_DEPTH_CLIP_CONTROL_CREATE_INFO_EXT = 1000355001,
  // Provided by VK_EXT_primitive_topology_list_restart
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PRIMITIVE_TOPOLOGY_LIST_RESTART_FEATURES_EXT = 1000356000,
  // Provided by VK_FUCHSIA_external_memory
    VK_STRUCTURE_TYPE_IMPORT_MEMORY_ZIRCON_HANDLE_INFO_FUCHSIA = 1000364000,
  // Provided by VK_FUCHSIA_external_memory
    VK_STRUCTURE_TYPE_MEMORY_ZIRCON_HANDLE_PROPERTIES_FUCHSIA = 1000364001,
  // Provided by VK_FUCHSIA_external_memory
    VK_STRUCTURE_TYPE_MEMORY_GET_ZIRCON_HANDLE_INFO_FUCHSIA = 1000364002,
  // Provided by VK_FUCHSIA_external_semaphore
    VK_STRUCTURE_TYPE_IMPORT_SEMAPHORE_ZIRCON_HANDLE_INFO_FUCHSIA = 1000365000,
  // Provided by VK_FUCHSIA_external_semaphore
    VK_STRUCTURE_TYPE_SEMAPHORE_GET_ZIRCON_HANDLE_INFO_FUCHSIA = 1000365001,
  // Provided by VK_FUCHSIA_buffer_collection
    VK_STRUCTURE_TYPE_BUFFER_COLLECTION_CREATE_INFO_FUCHSIA = 1000366000,
  // Provided by VK_FUCHSIA_buffer_collection
    VK_STRUCTURE_TYPE_IMPORT_MEMORY_BUFFER_COLLECTION_FUCHSIA = 1000366001,
  // Provided by VK_FUCHSIA_buffer_collection
    VK_STRUCTURE_TYPE_BUFFER_COLLECTION_IMAGE_CREATE_INFO_FUCHSIA = 1000366002,
  // Provided by VK_FUCHSIA_buffer_collection
    VK_STRUCTURE_TYPE_BUFFER_COLLECTION_PROPERTIES_FUCHSIA = 1000366003,
  // Provided by VK_FUCHSIA_buffer_collection
    VK_STRUCTURE_TYPE_BUFFER_CONSTRAINTS_INFO_FUCHSIA = 1000366004,
  // Provided by VK_FUCHSIA_buffer_collection
    VK_STRUCTURE_TYPE_BUFFER_COLLECTION_BUFFER_CREATE_INFO_FUCHSIA = 1000366005,
  // Provided by VK_FUCHSIA_buffer_collection
    VK_STRUCTURE_TYPE_IMAGE_CONSTRAINTS_INFO_FUCHSIA = 1000366006,
  // Provided by VK_FUCHSIA_buffer_collection
    VK_STRUCTURE_TYPE_IMAGE_FORMAT_CONSTRAINTS_INFO_FUCHSIA = 1000366007,
  // Provided by VK_FUCHSIA_buffer_collection
    VK_STRUCTURE_TYPE_SYSMEM_COLOR_SPACE_FUCHSIA = 1000366008,
  // Provided by VK_FUCHSIA_buffer_collection
    VK_STRUCTURE_TYPE_BUFFER_COLLECTION_CONSTRAINTS_INFO_FUCHSIA = 1000366009,
  // Provided by VK_HUAWEI_subpass_shading
    VK_STRUCTURE_TYPE_SUBPASS_SHADING_PIPELINE_CREATE_INFO_HUAWEI = 1000369000,
  // Provided by VK_HUAWEI_subpass_shading
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SUBPASS_SHADING_FEATURES_HUAWEI = 1000369001,
  // Provided by VK_HUAWEI_subpass_shading
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SUBPASS_SHADING_PROPERTIES_HUAWEI = 1000369002,
  // Provided by VK_HUAWEI_invocation_mask
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_INVOCATION_MASK_FEATURES_HUAWEI = 1000370000,
  // Provided by VK_NV_external_memory_rdma
    VK_STRUCTURE_TYPE_MEMORY_GET_REMOTE_ADDRESS_INFO_NV = 1000371000,
  // Provided by VK_NV_external_memory_rdma
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_EXTERNAL_MEMORY_RDMA_FEATURES_NV = 1000371001,
  // Provided by VK_EXT_pipeline_properties
    VK_STRUCTURE_TYPE_PIPELINE_PROPERTIES_IDENTIFIER_EXT = 1000372000,
  // Provided by VK_EXT_pipeline_properties
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PIPELINE_PROPERTIES_FEATURES_EXT = 1000372001,
  // Provided by VK_EXT_frame_boundary
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FRAME_BOUNDARY_FEATURES_EXT = 1000375000,
  // Provided by VK_EXT_frame_boundary
    VK_STRUCTURE_TYPE_FRAME_BOUNDARY_EXT = 1000375001,
  // Provided by VK_EXT_multisampled_render_to_single_sampled
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MULTISAMPLED_RENDER_TO_SINGLE_SAMPLED_FEATURES_EXT = 1000376000,
  // Provided by VK_EXT_multisampled_render_to_single_sampled
    VK_STRUCTURE_TYPE_SUBPASS_RESOLVE_PERFORMANCE_QUERY_EXT = 1000376001,
  // Provided by VK_EXT_multisampled_render_to_single_sampled
    VK_STRUCTURE_TYPE_MULTISAMPLED_RENDER_TO_SINGLE_SAMPLED_INFO_EXT = 1000376002,
  // Provided by VK_EXT_extended_dynamic_state2
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_EXTENDED_DYNAMIC_STATE_2_FEATURES_EXT = 1000377000,
  // Provided by VK_QNX_screen_surface
    VK_STRUCTURE_TYPE_SCREEN_SURFACE_CREATE_INFO_QNX = 1000378000,
  // Provided by VK_EXT_color_write_enable
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_COLOR_WRITE_ENABLE_FEATURES_EXT = 1000381000,
  // Provided by VK_EXT_color_write_enable
    VK_STRUCTURE_TYPE_PIPELINE_COLOR_WRITE_CREATE_INFO_EXT = 1000381001,
  // Provided by VK_EXT_primitives_generated_query
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PRIMITIVES_GENERATED_QUERY_FEATURES_EXT = 1000382000,
  // Provided by VK_KHR_ray_tracing_maintenance1
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_RAY_TRACING_MAINTENANCE_1_FEATURES_KHR = 1000386000,
  // Provided by VK_EXT_image_view_min_lod
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGE_VIEW_MIN_LOD_FEATURES_EXT = 1000391000,
  // Provided by VK_EXT_image_view_min_lod
    VK_STRUCTURE_TYPE_IMAGE_VIEW_MIN_LOD_CREATE_INFO_EXT = 1000391001,
  // Provided by VK_EXT_multi_draw
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MULTI_DRAW_FEATURES_EXT = 1000392000,
  // Provided by VK_EXT_multi_draw
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MULTI_DRAW_PROPERTIES_EXT = 1000392001,
  // Provided by VK_EXT_image_2d_view_of_3d
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGE_2D_VIEW_OF_3D_FEATURES_EXT = 1000393000,
  // Provided by VK_EXT_shader_tile_image
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_TILE_IMAGE_FEATURES_EXT = 1000395000,
  // Provided by VK_EXT_shader_tile_image
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_TILE_IMAGE_PROPERTIES_EXT = 1000395001,
  // Provided by VK_EXT_opacity_micromap
    VK_STRUCTURE_TYPE_MICROMAP_BUILD_INFO_EXT = 1000396000,
  // Provided by VK_EXT_opacity_micromap
    VK_STRUCTURE_TYPE_MICROMAP_VERSION_INFO_EXT = 1000396001,
  // Provided by VK_EXT_opacity_micromap
    VK_STRUCTURE_TYPE_COPY_MICROMAP_INFO_EXT = 1000396002,
  // Provided by VK_EXT_opacity_micromap
    VK_STRUCTURE_TYPE_COPY_MICROMAP_TO_MEMORY_INFO_EXT = 1000396003,
  // Provided by VK_EXT_opacity_micromap
    VK_STRUCTURE_TYPE_COPY_MEMORY_TO_MICROMAP_INFO_EXT = 1000396004,
  // Provided by VK_EXT_opacity_micromap
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_OPACITY_MICROMAP_FEATURES_EXT = 1000396005,
  // Provided by VK_EXT_opacity_micromap
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_OPACITY_MICROMAP_PROPERTIES_EXT = 1000396006,
  // Provided by VK_EXT_opacity_micromap
    VK_STRUCTURE_TYPE_MICROMAP_CREATE_INFO_EXT = 1000396007,
  // Provided by VK_EXT_opacity_micromap
    VK_STRUCTURE_TYPE_MICROMAP_BUILD_SIZES_INFO_EXT = 1000396008,
  // Provided by VK_EXT_opacity_micromap
    VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_TRIANGLES_OPACITY_MICROMAP_EXT = 1000396009,
#ifdef VK_ENABLE_BETA_EXTENSIONS
  // Provided by VK_NV_displacement_micromap
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DISPLACEMENT_MICROMAP_FEATURES_NV = 1000397000,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
  // Provided by VK_NV_displacement_micromap
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DISPLACEMENT_MICROMAP_PROPERTIES_NV = 1000397001,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
  // Provided by VK_NV_displacement_micromap
    VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_TRIANGLES_DISPLACEMENT_MICROMAP_NV = 1000397002,
#endif
  // Provided by VK_HUAWEI_cluster_culling_shader
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_CLUSTER_CULLING_SHADER_FEATURES_HUAWEI = 1000404000,
  // Provided by VK_HUAWEI_cluster_culling_shader
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_CLUSTER_CULLING_SHADER_PROPERTIES_HUAWEI = 1000404001,
  // Provided by VK_HUAWEI_cluster_culling_shader
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_CLUSTER_CULLING_SHADER_VRS_FEATURES_HUAWEI = 1000404002,
  // Provided by VK_EXT_border_color_swizzle
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_BORDER_COLOR_SWIZZLE_FEATURES_EXT = 1000411000,
  // Provided by VK_EXT_border_color_swizzle
    VK_STRUCTURE_TYPE_SAMPLER_BORDER_COLOR_COMPONENT_MAPPING_CREATE_INFO_EXT = 1000411001,
  // Provided by VK_EXT_pageable_device_local_memory
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PAGEABLE_DEVICE_LOCAL_MEMORY_FEATURES_EXT = 1000412000,
  // Provided by VK_ARM_shader_core_properties
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_CORE_PROPERTIES_ARM = 1000415000,
  // Provided by VK_KHR_shader_subgroup_rotate
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_SUBGROUP_ROTATE_FEATURES_KHR = 1000416000,
  // Provided by VK_ARM_scheduling_controls
    VK_STRUCTURE_TYPE_DEVICE_QUEUE_SHADER_CORE_CONTROL_CREATE_INFO_ARM = 1000417000,
  // Provided by VK_ARM_scheduling_controls
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SCHEDULING_CONTROLS_FEATURES_ARM = 1000417001,
  // Provided by VK_ARM_scheduling_controls
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SCHEDULING_CONTROLS_PROPERTIES_ARM = 1000417002,
  // Provided by VK_EXT_image_sliced_view_of_3d
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGE_SLICED_VIEW_OF_3D_FEATURES_EXT = 1000418000,
  // Provided by VK_EXT_image_sliced_view_of_3d
    VK_STRUCTURE_TYPE_IMAGE_VIEW_SLICED_CREATE_INFO_EXT = 1000418001,
  // Provided by VK_VALVE_descriptor_set_host_mapping
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DESCRIPTOR_SET_HOST_MAPPING_FEATURES_VALVE = 1000420000,
  // Provided by VK_VALVE_descriptor_set_host_mapping
    VK_STRUCTURE_TYPE_DESCRIPTOR_SET_BINDING_REFERENCE_VALVE = 1000420001,
  // Provided by VK_VALVE_descriptor_set_host_mapping
    VK_STRUCTURE_TYPE_DESCRIPTOR_SET_LAYOUT_HOST_MAPPING_INFO_VALVE = 1000420002,
  // Provided by VK_EXT_depth_clamp_zero_one
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DEPTH_CLAMP_ZERO_ONE_FEATURES_EXT = 1000421000,
  // Provided by VK_EXT_non_seamless_cube_map
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_NON_SEAMLESS_CUBE_MAP_FEATURES_EXT = 1000422000,
  // Provided by VK_ARM_render_pass_striped
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_RENDER_PASS_STRIPED_FEATURES_ARM = 1000424000,
  // Provided by VK_ARM_render_pass_striped
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_RENDER_PASS_STRIPED_PROPERTIES_ARM = 1000424001,
  // Provided by VK_ARM_render_pass_striped
    VK_STRUCTURE_TYPE_RENDER_PASS_STRIPE_BEGIN_INFO_ARM = 1000424002,
  // Provided by VK_ARM_render_pass_striped
    VK_STRUCTURE_TYPE_RENDER_PASS_STRIPE_INFO_ARM = 1000424003,
  // Provided by VK_ARM_render_pass_striped
    VK_STRUCTURE_TYPE_RENDER_PASS_STRIPE_SUBMIT_INFO_ARM = 1000424004,
  // Provided by VK_QCOM_fragment_density_map_offset
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FRAGMENT_DENSITY_MAP_OFFSET_FEATURES_QCOM = 1000425000,
  // Provided by VK_QCOM_fragment_density_map_offset
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FRAGMENT_DENSITY_MAP_OFFSET_PROPERTIES_QCOM = 1000425001,
  // Provided by VK_QCOM_fragment_density_map_offset
    VK_STRUCTURE_TYPE_SUBPASS_FRAGMENT_DENSITY_MAP_OFFSET_END_INFO_QCOM = 1000425002,
  // Provided by VK_NV_copy_memory_indirect
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_COPY_MEMORY_INDIRECT_FEATURES_NV = 1000426000,
  // Provided by VK_NV_copy_memory_indirect
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_COPY_MEMORY_INDIRECT_PROPERTIES_NV = 1000426001,
  // Provided by VK_NV_memory_decompression
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MEMORY_DECOMPRESSION_FEATURES_NV = 1000427000,
  // Provided by VK_NV_memory_decompression
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MEMORY_DECOMPRESSION_PROPERTIES_NV = 1000427001,
  // Provided by VK_NV_device_generated_commands_compute
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DEVICE_GENERATED_COMMANDS_COMPUTE_FEATURES_NV = 1000428000,
  // Provided by VK_NV_device_generated_commands_compute
    VK_STRUCTURE_TYPE_COMPUTE_PIPELINE_INDIRECT_BUFFER_INFO_NV = 1000428001,
  // Provided by VK_NV_device_generated_commands_compute
    VK_STRUCTURE_TYPE_PIPELINE_INDIRECT_DEVICE_ADDRESS_INFO_NV = 1000428002,
  // Provided by VK_NV_linear_color_attachment
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_LINEAR_COLOR_ATTACHMENT_FEATURES_NV = 1000430000,
  // Provided by VK_KHR_shader_maximal_reconvergence
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_MAXIMAL_RECONVERGENCE_FEATURES_KHR = 1000434000,
  // Provided by VK_EXT_image_compression_control_swapchain
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGE_COMPRESSION_CONTROL_SWAPCHAIN_FEATURES_EXT = 1000437000,
  // Provided by VK_QCOM_image_processing
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGE_PROCESSING_FEATURES_QCOM = 1000440000,
  // Provided by VK_QCOM_image_processing
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGE_PROCESSING_PROPERTIES_QCOM = 1000440001,
  // Provided by VK_QCOM_image_processing
    VK_STRUCTURE_TYPE_IMAGE_VIEW_SAMPLE_WEIGHT_CREATE_INFO_QCOM = 1000440002,
  // Provided by VK_EXT_nested_command_buffer
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_NESTED_COMMAND_BUFFER_FEATURES_EXT = 1000451000,
  // Provided by VK_EXT_nested_command_buffer
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_NESTED_COMMAND_BUFFER_PROPERTIES_EXT = 1000451001,
  // Provided by VK_EXT_external_memory_acquire_unmodified
    VK_STRUCTURE_TYPE_EXTERNAL_MEMORY_ACQUIRE_UNMODIFIED_EXT = 1000453000,
  // Provided by VK_EXT_extended_dynamic_state3
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_EXTENDED_DYNAMIC_STATE_3_FEATURES_EXT = 1000455000,
  // Provided by VK_EXT_extended_dynamic_state3
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_EXTENDED_DYNAMIC_STATE_3_PROPERTIES_EXT = 1000455001,
  // Provided by VK_EXT_subpass_merge_feedback
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SUBPASS_MERGE_FEEDBACK_FEATURES_EXT = 1000458000,
  // Provided by VK_EXT_subpass_merge_feedback
    VK_STRUCTURE_TYPE_RENDER_PASS_CREATION_CONTROL_EXT = 1000458001,
  // Provided by VK_EXT_subpass_merge_feedback
    VK_STRUCTURE_TYPE_RENDER_PASS_CREATION_FEEDBACK_CREATE_INFO_EXT = 1000458002,
  // Provided by VK_EXT_subpass_merge_feedback
    VK_STRUCTURE_TYPE_RENDER_PASS_SUBPASS_FEEDBACK_CREATE_INFO_EXT = 1000458003,
  // Provided by VK_LUNARG_direct_driver_loading
    VK_STRUCTURE_TYPE_DIRECT_DRIVER_LOADING_INFO_LUNARG = 1000459000,
  // Provided by VK_LUNARG_direct_driver_loading
    VK_STRUCTURE_TYPE_DIRECT_DRIVER_LOADING_LIST_LUNARG = 1000459001,
  // Provided by VK_EXT_shader_module_identifier
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_MODULE_IDENTIFIER_FEATURES_EXT = 1000462000,
  // Provided by VK_EXT_shader_module_identifier
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_MODULE_IDENTIFIER_PROPERTIES_EXT = 1000462001,
  // Provided by VK_EXT_shader_module_identifier
    VK_STRUCTURE_TYPE_PIPELINE_SHADER_STAGE_MODULE_IDENTIFIER_CREATE_INFO_EXT = 1000462002,
  // Provided by VK_EXT_shader_module_identifier
    VK_STRUCTURE_TYPE_SHADER_MODULE_IDENTIFIER_EXT = 1000462003,
  // Provided by VK_EXT_rasterization_order_attachment_access
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_RASTERIZATION_ORDER_ATTACHMENT_ACCESS_FEATURES_EXT = 1000342000,
  // Provided by VK_NV_optical_flow
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_OPTICAL_FLOW_FEATURES_NV = 1000464000,
  // Provided by VK_NV_optical_flow
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_OPTICAL_FLOW_PROPERTIES_NV = 1000464001,
  // Provided by VK_NV_optical_flow
    VK_STRUCTURE_TYPE_OPTICAL_FLOW_IMAGE_FORMAT_INFO_NV = 1000464002,
  // Provided by VK_NV_optical_flow
    VK_STRUCTURE_TYPE_OPTICAL_FLOW_IMAGE_FORMAT_PROPERTIES_NV = 1000464003,
  // Provided by VK_NV_optical_flow
    VK_STRUCTURE_TYPE_OPTICAL_FLOW_SESSION_CREATE_INFO_NV = 1000464004,
  // Provided by VK_NV_optical_flow
    VK_STRUCTURE_TYPE_OPTICAL_FLOW_EXECUTE_INFO_NV = 1000464005,
  // Provided by VK_NV_optical_flow
    VK_STRUCTURE_TYPE_OPTICAL_FLOW_SESSION_CREATE_PRIVATE_DATA_INFO_NV = 1000464010,
  // Provided by VK_EXT_legacy_dithering
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_LEGACY_DITHERING_FEATURES_EXT = 1000465000,
  // Provided by VK_EXT_pipeline_protected_access
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PIPELINE_PROTECTED_ACCESS_FEATURES_EXT = 1000466000,
  // Provided by VK_ANDROID_external_format_resolve
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_EXTERNAL_FORMAT_RESOLVE_FEATURES_ANDROID = 1000468000,
  // Provided by VK_ANDROID_external_format_resolve
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_EXTERNAL_FORMAT_RESOLVE_PROPERTIES_ANDROID = 1000468001,
  // Provided by VK_ANDROID_external_format_resolve
    VK_STRUCTURE_TYPE_ANDROID_HARDWARE_BUFFER_FORMAT_RESOLVE_PROPERTIES_ANDROID = 1000468002,
  // Provided by VK_KHR_maintenance5
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MAINTENANCE_5_FEATURES_KHR = 1000470000,
  // Provided by VK_KHR_maintenance5
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MAINTENANCE_5_PROPERTIES_KHR = 1000470001,
  // Provided by VK_KHR_maintenance5
    VK_STRUCTURE_TYPE_RENDERING_AREA_INFO_KHR = 1000470003,
  // Provided by VK_KHR_maintenance5
    VK_STRUCTURE_TYPE_DEVICE_IMAGE_SUBRESOURCE_INFO_KHR = 1000470004,
  // Provided by VK_KHR_maintenance5
    VK_STRUCTURE_TYPE_SUBRESOURCE_LAYOUT_2_KHR = 1000338002,
  // Provided by VK_KHR_maintenance5
    VK_STRUCTURE_TYPE_IMAGE_SUBRESOURCE_2_KHR = 1000338003,
  // Provided by VK_KHR_maintenance5
    VK_STRUCTURE_TYPE_PIPELINE_CREATE_FLAGS_2_CREATE_INFO_KHR = 1000470005,
  // Provided by VK_KHR_maintenance5
    VK_STRUCTURE_TYPE_BUFFER_USAGE_FLAGS_2_CREATE_INFO_KHR = 1000470006,
  // Provided by VK_AMD_anti_lag
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_ANTI_LAG_FEATURES_AMD = 1000476000,
  // Provided by VK_AMD_anti_lag
    VK_STRUCTURE_TYPE_ANTI_LAG_DATA_AMD = 1000476001,
  // Provided by VK_AMD_anti_lag
    VK_STRUCTURE_TYPE_ANTI_LAG_PRESENTATION_INFO_AMD = 1000476002,
  // Provided by VK_KHR_ray_tracing_position_fetch
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_RAY_TRACING_POSITION_FETCH_FEATURES_KHR = 1000481000,
  // Provided by VK_EXT_shader_object
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_OBJECT_FEATURES_EXT = 1000482000,
  // Provided by VK_EXT_shader_object
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_OBJECT_PROPERTIES_EXT = 1000482001,
  // Provided by VK_EXT_shader_object
    VK_STRUCTURE_TYPE_SHADER_CREATE_INFO_EXT = 1000482002,
  // Provided by VK_KHR_pipeline_binary
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PIPELINE_BINARY_FEATURES_KHR = 1000483000,
  // Provided by VK_KHR_pipeline_binary
    VK_STRUCTURE_TYPE_PIPELINE_BINARY_CREATE_INFO_KHR = 1000483001,
  // Provided by VK_KHR_pipeline_binary
    VK_STRUCTURE_TYPE_PIPELINE_BINARY_INFO_KHR = 1000483002,
  // Provided by VK_KHR_pipeline_binary
    VK_STRUCTURE_TYPE_PIPELINE_BINARY_KEY_KHR = 1000483003,
  // Provided by VK_KHR_pipeline_binary
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PIPELINE_BINARY_PROPERTIES_KHR = 1000483004,
  // Provided by VK_KHR_pipeline_binary
    VK_STRUCTURE_TYPE_RELEASE_CAPTURED_PIPELINE_DATA_INFO_KHR = 1000483005,
  // Provided by VK_KHR_pipeline_binary
    VK_STRUCTURE_TYPE_PIPELINE_BINARY_DATA_INFO_KHR = 1000483006,
  // Provided by VK_KHR_pipeline_binary
    VK_STRUCTURE_TYPE_PIPELINE_CREATE_INFO_KHR = 1000483007,
  // Provided by VK_KHR_pipeline_binary
    VK_STRUCTURE_TYPE_DEVICE_PIPELINE_BINARY_INTERNAL_CACHE_CONTROL_KHR = 1000483008,
  // Provided by VK_KHR_pipeline_binary
    VK_STRUCTURE_TYPE_PIPELINE_BINARY_HANDLES_INFO_KHR = 1000483009,
  // Provided by VK_QCOM_tile_properties
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_TILE_PROPERTIES_FEATURES_QCOM = 1000484000,
  // Provided by VK_QCOM_tile_properties
    VK_STRUCTURE_TYPE_TILE_PROPERTIES_QCOM = 1000484001,
  // Provided by VK_SEC_amigo_profiling
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_AMIGO_PROFILING_FEATURES_SEC = 1000485000,
  // Provided by VK_SEC_amigo_profiling
    VK_STRUCTURE_TYPE_AMIGO_PROFILING_SUBMIT_INFO_SEC = 1000485001,
  // Provided by VK_QCOM_multiview_per_view_viewports
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MULTIVIEW_PER_VIEW_VIEWPORTS_FEATURES_QCOM = 1000488000,
  // Provided by VK_NV_ray_tracing_invocation_reorder
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_RAY_TRACING_INVOCATION_REORDER_FEATURES_NV = 1000490000,
  // Provided by VK_NV_ray_tracing_invocation_reorder
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_RAY_TRACING_INVOCATION_REORDER_PROPERTIES_NV = 1000490001,
  // Provided by VK_NV_extended_sparse_address_space
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_EXTENDED_SPARSE_ADDRESS_SPACE_FEATURES_NV = 1000492000,
  // Provided by VK_NV_extended_sparse_address_space
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_EXTENDED_SPARSE_ADDRESS_SPACE_PROPERTIES_NV = 1000492001,
  // Provided by VK_EXT_mutable_descriptor_type
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MUTABLE_DESCRIPTOR_TYPE_FEATURES_EXT = 1000351000,
  // Provided by VK_EXT_mutable_descriptor_type
    VK_STRUCTURE_TYPE_MUTABLE_DESCRIPTOR_TYPE_CREATE_INFO_EXT = 1000351002,
  // Provided by VK_EXT_legacy_vertex_attributes
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_LEGACY_VERTEX_ATTRIBUTES_FEATURES_EXT = 1000495000,
  // Provided by VK_EXT_legacy_vertex_attributes
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_LEGACY_VERTEX_ATTRIBUTES_PROPERTIES_EXT = 1000495001,
  // Provided by VK_EXT_layer_settings
    VK_STRUCTURE_TYPE_LAYER_SETTINGS_CREATE_INFO_EXT = 1000496000,
  // Provided by VK_ARM_shader_core_builtins
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_CORE_BUILTINS_FEATURES_ARM = 1000497000,
  // Provided by VK_ARM_shader_core_builtins
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_CORE_BUILTINS_PROPERTIES_ARM = 1000497001,
  // Provided by VK_EXT_pipeline_library_group_handles
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PIPELINE_LIBRARY_GROUP_HANDLES_FEATURES_EXT = 1000498000,
  // Provided by VK_EXT_dynamic_rendering_unused_attachments
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DYNAMIC_RENDERING_UNUSED_ATTACHMENTS_FEATURES_EXT = 1000499000,
  // Provided by VK_NV_low_latency2
    VK_STRUCTURE_TYPE_LATENCY_SLEEP_MODE_INFO_NV = 1000505000,
  // Provided by VK_NV_low_latency2
    VK_STRUCTURE_TYPE_LATENCY_SLEEP_INFO_NV = 1000505001,
  // Provided by VK_NV_low_latency2
    VK_STRUCTURE_TYPE_SET_LATENCY_MARKER_INFO_NV = 1000505002,
  // Provided by VK_NV_low_latency2
    VK_STRUCTURE_TYPE_GET_LATENCY_MARKER_INFO_NV = 1000505003,
  // Provided by VK_NV_low_latency2
    VK_STRUCTURE_TYPE_LATENCY_TIMINGS_FRAME_REPORT_NV = 1000505004,
  // Provided by VK_NV_low_latency2
    VK_STRUCTURE_TYPE_LATENCY_SUBMISSION_PRESENT_ID_NV = 1000505005,
  // Provided by VK_NV_low_latency2
    VK_STRUCTURE_TYPE_OUT_OF_BAND_QUEUE_TYPE_INFO_NV = 1000505006,
  // Provided by VK_NV_low_latency2
    VK_STRUCTURE_TYPE_SWAPCHAIN_LATENCY_CREATE_INFO_NV = 1000505007,
  // Provided by VK_NV_low_latency2
    VK_STRUCTURE_TYPE_LATENCY_SURFACE_CAPABILITIES_NV = 1000505008,
  // Provided by VK_KHR_cooperative_matrix
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_COOPERATIVE_MATRIX_FEATURES_KHR = 1000506000,
  // Provided by VK_KHR_cooperative_matrix
    VK_STRUCTURE_TYPE_COOPERATIVE_MATRIX_PROPERTIES_KHR = 1000506001,
  // Provided by VK_KHR_cooperative_matrix
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_COOPERATIVE_MATRIX_PROPERTIES_KHR = 1000506002,
  // Provided by VK_QCOM_multiview_per_view_render_areas
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MULTIVIEW_PER_VIEW_RENDER_AREAS_FEATURES_QCOM = 1000510000,
  // Provided by VK_QCOM_multiview_per_view_render_areas
    VK_STRUCTURE_TYPE_MULTIVIEW_PER_VIEW_RENDER_AREAS_RENDER_PASS_BEGIN_INFO_QCOM = 1000510001,
  // Provided by VK_KHR_compute_shader_derivatives
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_COMPUTE_SHADER_DERIVATIVES_FEATURES_KHR = 1000201000,
  // Provided by VK_KHR_compute_shader_derivatives
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_COMPUTE_SHADER_DERIVATIVES_PROPERTIES_KHR = 1000511000,
  // Provided by VK_KHR_video_decode_av1
    VK_STRUCTURE_TYPE_VIDEO_DECODE_AV1_CAPABILITIES_KHR = 1000512000,
  // Provided by VK_KHR_video_decode_av1
    VK_STRUCTURE_TYPE_VIDEO_DECODE_AV1_PICTURE_INFO_KHR = 1000512001,
  // Provided by VK_KHR_video_decode_av1
    VK_STRUCTURE_TYPE_VIDEO_DECODE_AV1_PROFILE_INFO_KHR = 1000512003,
  // Provided by VK_KHR_video_decode_av1
    VK_STRUCTURE_TYPE_VIDEO_DECODE_AV1_SESSION_PARAMETERS_CREATE_INFO_KHR = 1000512004,
  // Provided by VK_KHR_video_decode_av1
    VK_STRUCTURE_TYPE_VIDEO_DECODE_AV1_DPB_SLOT_INFO_KHR = 1000512005,
  // Provided by VK_KHR_video_maintenance1
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VIDEO_MAINTENANCE_1_FEATURES_KHR = 1000515000,
  // Provided by VK_KHR_video_maintenance1
    VK_STRUCTURE_TYPE_VIDEO_INLINE_QUERY_INFO_KHR = 1000515001,
  // Provided by VK_NV_per_stage_descriptor_set
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PER_STAGE_DESCRIPTOR_SET_FEATURES_NV = 1000516000,
  // Provided by VK_QCOM_image_processing2
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGE_PROCESSING_2_FEATURES_QCOM = 1000518000,
  // Provided by VK_QCOM_image_processing2
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGE_PROCESSING_2_PROPERTIES_QCOM = 1000518001,
  // Provided by VK_QCOM_image_processing2
    VK_STRUCTURE_TYPE_SAMPLER_BLOCK_MATCH_WINDOW_CREATE_INFO_QCOM = 1000518002,
  // Provided by VK_QCOM_filter_cubic_weights
    VK_STRUCTURE_TYPE_SAMPLER_CUBIC_WEIGHTS_CREATE_INFO_QCOM = 1000519000,
  // Provided by VK_QCOM_filter_cubic_weights
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_CUBIC_WEIGHTS_FEATURES_QCOM = 1000519001,
  // Provided by VK_QCOM_filter_cubic_weights
    VK_STRUCTURE_TYPE_BLIT_IMAGE_CUBIC_WEIGHTS_INFO_QCOM = 1000519002,
  // Provided by VK_QCOM_ycbcr_degamma
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_YCBCR_DEGAMMA_FEATURES_QCOM = 1000520000,
  // Provided by VK_QCOM_ycbcr_degamma
    VK_STRUCTURE_TYPE_SAMPLER_YCBCR_CONVERSION_YCBCR_DEGAMMA_CREATE_INFO_QCOM = 1000520001,
  // Provided by VK_QCOM_filter_cubic_clamp
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_CUBIC_CLAMP_FEATURES_QCOM = 1000521000,
  // Provided by VK_EXT_attachment_feedback_loop_dynamic_state
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_ATTACHMENT_FEEDBACK_LOOP_DYNAMIC_STATE_FEATURES_EXT = 1000524000,
  // Provided by VK_KHR_vertex_attribute_divisor
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VERTEX_ATTRIBUTE_DIVISOR_PROPERTIES_KHR = 1000525000,
  // Provided by VK_KHR_vertex_attribute_divisor
    VK_STRUCTURE_TYPE_PIPELINE_VERTEX_INPUT_DIVISOR_STATE_CREATE_INFO_KHR = 1000190001,
  // Provided by VK_KHR_vertex_attribute_divisor
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VERTEX_ATTRIBUTE_DIVISOR_FEATURES_KHR = 1000190002,
  // Provided by VK_KHR_shader_float_controls2
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_FLOAT_CONTROLS_2_FEATURES_KHR = 1000528000,
  // Provided by VK_QNX_external_memory_screen_buffer
    VK_STRUCTURE_TYPE_SCREEN_BUFFER_PROPERTIES_QNX = 1000529000,
  // Provided by VK_QNX_external_memory_screen_buffer
    VK_STRUCTURE_TYPE_SCREEN_BUFFER_FORMAT_PROPERTIES_QNX = 1000529001,
  // Provided by VK_QNX_external_memory_screen_buffer
    VK_STRUCTURE_TYPE_IMPORT_SCREEN_BUFFER_INFO_QNX = 1000529002,
  // Provided by VK_QNX_external_memory_screen_buffer
    VK_STRUCTURE_TYPE_EXTERNAL_FORMAT_QNX = 1000529003,
  // Provided by VK_QNX_external_memory_screen_buffer
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_EXTERNAL_MEMORY_SCREEN_BUFFER_FEATURES_QNX = 1000529004,
  // Provided by VK_MSFT_layered_driver
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_LAYERED_DRIVER_PROPERTIES_MSFT = 1000530000,
  // Provided by VK_KHR_index_type_uint8
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_INDEX_TYPE_UINT8_FEATURES_KHR = 1000265000,
  // Provided by VK_KHR_line_rasterization
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_LINE_RASTERIZATION_FEATURES_KHR = 1000259000,
  // Provided by VK_KHR_line_rasterization
    VK_STRUCTURE_TYPE_PIPELINE_RASTERIZATION_LINE_STATE_CREATE_INFO_KHR = 1000259001,
  // Provided by VK_KHR_line_rasterization
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_LINE_RASTERIZATION_PROPERTIES_KHR = 1000259002,
  // Provided by VK_KHR_calibrated_timestamps
    VK_STRUCTURE_TYPE_CALIBRATED_TIMESTAMP_INFO_KHR = 1000184000,
  // Provided by VK_KHR_shader_expect_assume
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_EXPECT_ASSUME_FEATURES_KHR = 1000544000,
  // Provided by VK_KHR_maintenance6
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MAINTENANCE_6_FEATURES_KHR = 1000545000,
  // Provided by VK_KHR_maintenance6
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MAINTENANCE_6_PROPERTIES_KHR = 1000545001,
  // Provided by VK_KHR_maintenance6
    VK_STRUCTURE_TYPE_BIND_MEMORY_STATUS_KHR = 1000545002,
  // Provided by VK_KHR_maintenance6
    VK_STRUCTURE_TYPE_BIND_DESCRIPTOR_SETS_INFO_KHR = 1000545003,
  // Provided by VK_KHR_maintenance6
    VK_STRUCTURE_TYPE_PUSH_CONSTANTS_INFO_KHR = 1000545004,
  // Provided by VK_KHR_maintenance6 with VK_KHR_push_descriptor
    VK_STRUCTURE_TYPE_PUSH_DESCRIPTOR_SET_INFO_KHR = 1000545005,
  // Provided by VK_KHR_maintenance6 with VK_KHR_push_descriptor
    VK_STRUCTURE_TYPE_PUSH_DESCRIPTOR_SET_WITH_TEMPLATE_INFO_KHR = 1000545006,
  // Provided by VK_KHR_maintenance6 with VK_EXT_descriptor_buffer
    VK_STRUCTURE_TYPE_SET_DESCRIPTOR_BUFFER_OFFSETS_INFO_EXT = 1000545007,
  // Provided by VK_KHR_maintenance6 with VK_EXT_descriptor_buffer
    VK_STRUCTURE_TYPE_BIND_DESCRIPTOR_BUFFER_EMBEDDED_SAMPLERS_INFO_EXT = 1000545008,
  // Provided by VK_NV_descriptor_pool_overallocation
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DESCRIPTOR_POOL_OVERALLOCATION_FEATURES_NV = 1000546000,
  // Provided by VK_NV_raw_access_chains
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_RAW_ACCESS_CHAINS_FEATURES_NV = 1000555000,
  // Provided by VK_KHR_shader_relaxed_extended_instruction
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_RELAXED_EXTENDED_INSTRUCTION_FEATURES_KHR = 1000558000,
  // Provided by VK_NV_command_buffer_inheritance
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_COMMAND_BUFFER_INHERITANCE_FEATURES_NV = 1000559000,
  // Provided by VK_KHR_maintenance7
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MAINTENANCE_7_FEATURES_KHR = 1000562000,
  // Provided by VK_KHR_maintenance7
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MAINTENANCE_7_PROPERTIES_KHR = 1000562001,
  // Provided by VK_KHR_maintenance7
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_LAYERED_API_PROPERTIES_LIST_KHR = 1000562002,
  // Provided by VK_KHR_maintenance7
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_LAYERED_API_PROPERTIES_KHR = 1000562003,
  // Provided by VK_KHR_maintenance7
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_LAYERED_API_VULKAN_PROPERTIES_KHR = 1000562004,
  // Provided by VK_NV_shader_atomic_float16_vector
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_ATOMIC_FLOAT16_VECTOR_FEATURES_NV = 1000563000,
  // Provided by VK_EXT_shader_replicated_composites
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_REPLICATED_COMPOSITES_FEATURES_EXT = 1000564000,
  // Provided by VK_NV_ray_tracing_validation
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_RAY_TRACING_VALIDATION_FEATURES_NV = 1000568000,
  // Provided by VK_EXT_device_generated_commands
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DEVICE_GENERATED_COMMANDS_FEATURES_EXT = 1000572000,
  // Provided by VK_EXT_device_generated_commands
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DEVICE_GENERATED_COMMANDS_PROPERTIES_EXT = 1000572001,
  // Provided by VK_EXT_device_generated_commands
    VK_STRUCTURE_TYPE_GENERATED_COMMANDS_MEMORY_REQUIREMENTS_INFO_EXT = 1000572002,
  // Provided by VK_EXT_device_generated_commands
    VK_STRUCTURE_TYPE_INDIRECT_EXECUTION_SET_CREATE_INFO_EXT = 1000572003,
  // Provided by VK_EXT_device_generated_commands
    VK_STRUCTURE_TYPE_GENERATED_COMMANDS_INFO_EXT = 1000572004,
  // Provided by VK_EXT_device_generated_commands
    VK_STRUCTURE_TYPE_INDIRECT_COMMANDS_LAYOUT_CREATE_INFO_EXT = 1000572006,
  // Provided by VK_EXT_device_generated_commands
    VK_STRUCTURE_TYPE_INDIRECT_COMMANDS_LAYOUT_TOKEN_EXT = 1000572007,
  // Provided by VK_EXT_device_generated_commands
    VK_STRUCTURE_TYPE_WRITE_INDIRECT_EXECUTION_SET_PIPELINE_EXT = 1000572008,
  // Provided by VK_EXT_device_generated_commands
    VK_STRUCTURE_TYPE_WRITE_INDIRECT_EXECUTION_SET_SHADER_EXT = 1000572009,
  // Provided by VK_EXT_device_generated_commands
    VK_STRUCTURE_TYPE_INDIRECT_EXECUTION_SET_PIPELINE_INFO_EXT = 1000572010,
  // Provided by VK_EXT_device_generated_commands
    VK_STRUCTURE_TYPE_INDIRECT_EXECUTION_SET_SHADER_INFO_EXT = 1000572011,
  // Provided by VK_EXT_device_generated_commands
    VK_STRUCTURE_TYPE_INDIRECT_EXECUTION_SET_SHADER_LAYOUT_INFO_EXT = 1000572012,
  // Provided by VK_EXT_device_generated_commands
    VK_STRUCTURE_TYPE_GENERATED_COMMANDS_PIPELINE_INFO_EXT = 1000572013,
  // Provided by VK_EXT_device_generated_commands
    VK_STRUCTURE_TYPE_GENERATED_COMMANDS_SHADER_INFO_EXT = 1000572014,
  // Provided by VK_MESA_image_alignment_control
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGE_ALIGNMENT_CONTROL_FEATURES_MESA = 1000575000,
  // Provided by VK_MESA_image_alignment_control
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGE_ALIGNMENT_CONTROL_PROPERTIES_MESA = 1000575001,
  // Provided by VK_MESA_image_alignment_control
    VK_STRUCTURE_TYPE_IMAGE_ALIGNMENT_CONTROL_CREATE_INFO_MESA = 1000575002,
  // Provided by VK_EXT_depth_clamp_control
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DEPTH_CLAMP_CONTROL_FEATURES_EXT = 1000582000,
  // Provided by VK_EXT_depth_clamp_control
    VK_STRUCTURE_TYPE_PIPELINE_VIEWPORT_DEPTH_CLAMP_CONTROL_CREATE_INFO_EXT = 1000582001,
  // Provided by VK_VERSION_1_1
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VARIABLE_POINTER_FEATURES = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VARIABLE_POINTERS_FEATURES,
  // Provided by VK_VERSION_1_1
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_DRAW_PARAMETER_FEATURES = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_DRAW_PARAMETERS_FEATURES,
  // Provided by VK_EXT_debug_report
  // VK_STRUCTURE_TYPE_DEBUG_REPORT_CREATE_INFO_EXT is a deprecated alias
    VK_STRUCTURE_TYPE_DEBUG_REPORT_CREATE_INFO_EXT = VK_STRUCTURE_TYPE_DEBUG_REPORT_CALLBACK_CREATE_INFO_EXT,
  // Provided by VK_KHR_dynamic_rendering
    VK_STRUCTURE_TYPE_RENDERING_INFO_KHR = VK_STRUCTURE_TYPE_RENDERING_INFO,
  // Provided by VK_KHR_dynamic_rendering
    VK_STRUCTURE_TYPE_RENDERING_ATTACHMENT_INFO_KHR = VK_STRUCTURE_TYPE_RENDERING_ATTACHMENT_INFO,
  // Provided by VK_KHR_dynamic_rendering
    VK_STRUCTURE_TYPE_PIPELINE_RENDERING_CREATE_INFO_KHR = VK_STRUCTURE_TYPE_PIPELINE_RENDERING_CREATE_INFO,
  // Provided by VK_KHR_dynamic_rendering
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DYNAMIC_RENDERING_FEATURES_KHR = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DYNAMIC_RENDERING_FEATURES,
  // Provided by VK_KHR_dynamic_rendering
    VK_STRUCTURE_TYPE_COMMAND_BUFFER_INHERITANCE_RENDERING_INFO_KHR = VK_STRUCTURE_TYPE_COMMAND_BUFFER_INHERITANCE_RENDERING_INFO,
  // Provided by VK_KHR_dynamic_rendering with VK_NV_framebuffer_mixed_samples
    VK_STRUCTURE_TYPE_ATTACHMENT_SAMPLE_COUNT_INFO_NV = VK_STRUCTURE_TYPE_ATTACHMENT_SAMPLE_COUNT_INFO_AMD,
  // Provided by VK_KHR_multiview
    VK_STRUCTURE_TYPE_RENDER_PASS_MULTIVIEW_CREATE_INFO_KHR = VK_STRUCTURE_TYPE_RENDER_PASS_MULTIVIEW_CREATE_INFO,
  // Provided by VK_KHR_multiview
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MULTIVIEW_FEATURES_KHR = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MULTIVIEW_FEATURES,
  // Provided by VK_KHR_multiview
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MULTIVIEW_PROPERTIES_KHR = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MULTIVIEW_PROPERTIES,
  // Provided by VK_KHR_get_physical_device_properties2
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FEATURES_2_KHR = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FEATURES_2,
  // Provided by VK_KHR_get_physical_device_properties2
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PROPERTIES_2_KHR = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PROPERTIES_2,
  // Provided by VK_KHR_get_physical_device_properties2
    VK_STRUCTURE_TYPE_FORMAT_PROPERTIES_2_KHR = VK_STRUCTURE_TYPE_FORMAT_PROPERTIES_2,
  // Provided by VK_KHR_get_physical_device_properties2
    VK_STRUCTURE_TYPE_IMAGE_FORMAT_PROPERTIES_2_KHR = VK_STRUCTURE_TYPE_IMAGE_FORMAT_PROPERTIES_2,
  // Provided by VK_KHR_get_physical_device_properties2
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGE_FORMAT_INFO_2_KHR = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGE_FORMAT_INFO_2,
  // Provided by VK_KHR_get_physical_device_properties2
    VK_STRUCTURE_TYPE_QUEUE_FAMILY_PROPERTIES_2_KHR = VK_STRUCTURE_TYPE_QUEUE_FAMILY_PROPERTIES_2,
  // Provided by VK_KHR_get_physical_device_properties2
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MEMORY_PROPERTIES_2_KHR = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MEMORY_PROPERTIES_2,
  // Provided by VK_KHR_get_physical_device_properties2
    VK_STRUCTURE_TYPE_SPARSE_IMAGE_FORMAT_PROPERTIES_2_KHR = VK_STRUCTURE_TYPE_SPARSE_IMAGE_FORMAT_PROPERTIES_2,
  // Provided by VK_KHR_get_physical_device_properties2
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SPARSE_IMAGE_FORMAT_INFO_2_KHR = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SPARSE_IMAGE_FORMAT_INFO_2,
  // Provided by VK_KHR_device_group
    VK_STRUCTURE_TYPE_MEMORY_ALLOCATE_FLAGS_INFO_KHR = VK_STRUCTURE_TYPE_MEMORY_ALLOCATE_FLAGS_INFO,
  // Provided by VK_KHR_device_group
    VK_STRUCTURE_TYPE_DEVICE_GROUP_RENDER_PASS_BEGIN_INFO_KHR = VK_STRUCTURE_TYPE_DEVICE_GROUP_RENDER_PASS_BEGIN_INFO,
  // Provided by VK_KHR_device_group
    VK_STRUCTURE_TYPE_DEVICE_GROUP_COMMAND_BUFFER_BEGIN_INFO_KHR = VK_STRUCTURE_TYPE_DEVICE_GROUP_COMMAND_BUFFER_BEGIN_INFO,
  // Provided by VK_KHR_device_group
    VK_STRUCTURE_TYPE_DEVICE_GROUP_SUBMIT_INFO_KHR = VK_STRUCTURE_TYPE_DEVICE_GROUP_SUBMIT_INFO,
  // Provided by VK_KHR_device_group
    VK_STRUCTURE_TYPE_DEVICE_GROUP_BIND_SPARSE_INFO_KHR = VK_STRUCTURE_TYPE_DEVICE_GROUP_BIND_SPARSE_INFO,
  // Provided by VK_KHR_bind_memory2 with VK_KHR_device_group
    VK_STRUCTURE_TYPE_BIND_BUFFER_MEMORY_DEVICE_GROUP_INFO_KHR = VK_STRUCTURE_TYPE_BIND_BUFFER_MEMORY_DEVICE_GROUP_INFO,
  // Provided by VK_KHR_bind_memory2 with VK_KHR_device_group
    VK_STRUCTURE_TYPE_BIND_IMAGE_MEMORY_DEVICE_GROUP_INFO_KHR = VK_STRUCTURE_TYPE_BIND_IMAGE_MEMORY_DEVICE_GROUP_INFO,
  // Provided by VK_EXT_texture_compression_astc_hdr
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_TEXTURE_COMPRESSION_ASTC_HDR_FEATURES_EXT = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_TEXTURE_COMPRESSION_ASTC_HDR_FEATURES,
  // Provided by VK_KHR_device_group_creation
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_GROUP_PROPERTIES_KHR = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_GROUP_PROPERTIES,
  // Provided by VK_KHR_device_group_creation
    VK_STRUCTURE_TYPE_DEVICE_GROUP_DEVICE_CREATE_INFO_KHR = VK_STRUCTURE_TYPE_DEVICE_GROUP_DEVICE_CREATE_INFO,
  // Provided by VK_KHR_external_memory_capabilities
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_EXTERNAL_IMAGE_FORMAT_INFO_KHR = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_EXTERNAL_IMAGE_FORMAT_INFO,
  // Provided by VK_KHR_external_memory_capabilities
    VK_STRUCTURE_TYPE_EXTERNAL_IMAGE_FORMAT_PROPERTIES_KHR = VK_STRUCTURE_TYPE_EXTERNAL_IMAGE_FORMAT_PROPERTIES,
  // Provided by VK_KHR_external_memory_capabilities
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_EXTERNAL_BUFFER_INFO_KHR = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_EXTERNAL_BUFFER_INFO,
  // Provided by VK_KHR_external_memory_capabilities
    VK_STRUCTURE_TYPE_EXTERNAL_BUFFER_PROPERTIES_KHR = VK_STRUCTURE_TYPE_EXTERNAL_BUFFER_PROPERTIES,
  // Provided by VK_KHR_external_fence_capabilities, VK_KHR_external_memory_capabilities, VK_KHR_external_semaphore_capabilities
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_ID_PROPERTIES_KHR = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_ID_PROPERTIES,
  // Provided by VK_KHR_external_memory
    VK_STRUCTURE_TYPE_EXTERNAL_MEMORY_BUFFER_CREATE_INFO_KHR = VK_STRUCTURE_TYPE_EXTERNAL_MEMORY_BUFFER_CREATE_INFO,
  // Provided by VK_KHR_external_memory
    VK_STRUCTURE_TYPE_EXTERNAL_MEMORY_IMAGE_CREATE_INFO_KHR = VK_STRUCTURE_TYPE_EXTERNAL_MEMORY_IMAGE_CREATE_INFO,
  // Provided by VK_KHR_external_memory
    VK_STRUCTURE_TYPE_EXPORT_MEMORY_ALLOCATE_INFO_KHR = VK_STRUCTURE_TYPE_EXPORT_MEMORY_ALLOCATE_INFO,
  // Provided by VK_KHR_external_semaphore_capabilities
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_EXTERNAL_SEMAPHORE_INFO_KHR = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_EXTERNAL_SEMAPHORE_INFO,
  // Provided by VK_KHR_external_semaphore_capabilities
    VK_STRUCTURE_TYPE_EXTERNAL_SEMAPHORE_PROPERTIES_KHR = VK_STRUCTURE_TYPE_EXTERNAL_SEMAPHORE_PROPERTIES,
  // Provided by VK_KHR_external_semaphore
    VK_STRUCTURE_TYPE_EXPORT_SEMAPHORE_CREATE_INFO_KHR = VK_STRUCTURE_TYPE_EXPORT_SEMAPHORE_CREATE_INFO,
  // Provided by VK_KHR_shader_float16_int8
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_FLOAT16_INT8_FEATURES_KHR = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_FLOAT16_INT8_FEATURES,
  // Provided by VK_KHR_shader_float16_int8
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FLOAT16_INT8_FEATURES_KHR = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_FLOAT16_INT8_FEATURES,
  // Provided by VK_KHR_16bit_storage
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_16BIT_STORAGE_FEATURES_KHR = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_16BIT_STORAGE_FEATURES,
  // Provided by VK_KHR_descriptor_update_template
    VK_STRUCTURE_TYPE_DESCRIPTOR_UPDATE_TEMPLATE_CREATE_INFO_KHR = VK_STRUCTURE_TYPE_DESCRIPTOR_UPDATE_TEMPLATE_CREATE_INFO,
  // Provided by VK_EXT_display_surface_counter
  // VK_STRUCTURE_TYPE_SURFACE_CAPABILITIES2_EXT is a deprecated alias
    VK_STRUCTURE_TYPE_SURFACE_CAPABILITIES2_EXT = VK_STRUCTURE_TYPE_SURFACE_CAPABILITIES_2_EXT,
  // Provided by VK_KHR_imageless_framebuffer
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGELESS_FRAMEBUFFER_FEATURES_KHR = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGELESS_FRAMEBUFFER_FEATURES,
  // Provided by VK_KHR_imageless_framebuffer
    VK_STRUCTURE_TYPE_FRAMEBUFFER_ATTACHMENTS_CREATE_INFO_KHR = VK_STRUCTURE_TYPE_FRAMEBUFFER_ATTACHMENTS_CREATE_INFO,
  // Provided by VK_KHR_imageless_framebuffer
    VK_STRUCTURE_TYPE_FRAMEBUFFER_ATTACHMENT_IMAGE_INFO_KHR = VK_STRUCTURE_TYPE_FRAMEBUFFER_ATTACHMENT_IMAGE_INFO,
  // Provided by VK_KHR_imageless_framebuffer
    VK_STRUCTURE_TYPE_RENDER_PASS_ATTACHMENT_BEGIN_INFO_KHR = VK_STRUCTURE_TYPE_RENDER_PASS_ATTACHMENT_BEGIN_INFO,
  // Provided by VK_KHR_create_renderpass2
    VK_STRUCTURE_TYPE_ATTACHMENT_DESCRIPTION_2_KHR = VK_STRUCTURE_TYPE_ATTACHMENT_DESCRIPTION_2,
  // Provided by VK_KHR_create_renderpass2
    VK_STRUCTURE_TYPE_ATTACHMENT_REFERENCE_2_KHR = VK_STRUCTURE_TYPE_ATTACHMENT_REFERENCE_2,
  // Provided by VK_KHR_create_renderpass2
    VK_STRUCTURE_TYPE_SUBPASS_DESCRIPTION_2_KHR = VK_STRUCTURE_TYPE_SUBPASS_DESCRIPTION_2,
  // Provided by VK_KHR_create_renderpass2
    VK_STRUCTURE_TYPE_SUBPASS_DEPENDENCY_2_KHR = VK_STRUCTURE_TYPE_SUBPASS_DEPENDENCY_2,
  // Provided by VK_KHR_create_renderpass2
    VK_STRUCTURE_TYPE_RENDER_PASS_CREATE_INFO_2_KHR = VK_STRUCTURE_TYPE_RENDER_PASS_CREATE_INFO_2,
  // Provided by VK_KHR_create_renderpass2
    VK_STRUCTURE_TYPE_SUBPASS_BEGIN_INFO_KHR = VK_STRUCTURE_TYPE_SUBPASS_BEGIN_INFO,
  // Provided by VK_KHR_create_renderpass2
    VK_STRUCTURE_TYPE_SUBPASS_END_INFO_KHR = VK_STRUCTURE_TYPE_SUBPASS_END_INFO,
  // Provided by VK_KHR_external_fence_capabilities
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_EXTERNAL_FENCE_INFO_KHR = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_EXTERNAL_FENCE_INFO,
  // Provided by VK_KHR_external_fence_capabilities
    VK_STRUCTURE_TYPE_EXTERNAL_FENCE_PROPERTIES_KHR = VK_STRUCTURE_TYPE_EXTERNAL_FENCE_PROPERTIES,
  // Provided by VK_KHR_external_fence
    VK_STRUCTURE_TYPE_EXPORT_FENCE_CREATE_INFO_KHR = VK_STRUCTURE_TYPE_EXPORT_FENCE_CREATE_INFO,
  // Provided by VK_KHR_maintenance2
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_POINT_CLIPPING_PROPERTIES_KHR = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_POINT_CLIPPING_PROPERTIES,
  // Provided by VK_KHR_maintenance2
    VK_STRUCTURE_TYPE_RENDER_PASS_INPUT_ATTACHMENT_ASPECT_CREATE_INFO_KHR = VK_STRUCTURE_TYPE_RENDER_PASS_INPUT_ATTACHMENT_ASPECT_CREATE_INFO,
  // Provided by VK_KHR_maintenance2
    VK_STRUCTURE_TYPE_IMAGE_VIEW_USAGE_CREATE_INFO_KHR = VK_STRUCTURE_TYPE_IMAGE_VIEW_USAGE_CREATE_INFO,
  // Provided by VK_KHR_maintenance2
    VK_STRUCTURE_TYPE_PIPELINE_TESSELLATION_DOMAIN_ORIGIN_STATE_CREATE_INFO_KHR = VK_STRUCTURE_TYPE_PIPELINE_TESSELLATION_DOMAIN_ORIGIN_STATE_CREATE_INFO,
  // Provided by VK_KHR_variable_pointers
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VARIABLE_POINTERS_FEATURES_KHR = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VARIABLE_POINTERS_FEATURES,
  // Provided by VK_KHR_variable_pointers
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VARIABLE_POINTER_FEATURES_KHR = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VARIABLE_POINTERS_FEATURES_KHR,
  // Provided by VK_KHR_dedicated_allocation
    VK_STRUCTURE_TYPE_MEMORY_DEDICATED_REQUIREMENTS_KHR = VK_STRUCTURE_TYPE_MEMORY_DEDICATED_REQUIREMENTS,
  // Provided by VK_KHR_dedicated_allocation
    VK_STRUCTURE_TYPE_MEMORY_DEDICATED_ALLOCATE_INFO_KHR = VK_STRUCTURE_TYPE_MEMORY_DEDICATED_ALLOCATE_INFO,
  // Provided by VK_EXT_sampler_filter_minmax
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SAMPLER_FILTER_MINMAX_PROPERTIES_EXT = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SAMPLER_FILTER_MINMAX_PROPERTIES,
  // Provided by VK_EXT_sampler_filter_minmax
    VK_STRUCTURE_TYPE_SAMPLER_REDUCTION_MODE_CREATE_INFO_EXT = VK_STRUCTURE_TYPE_SAMPLER_REDUCTION_MODE_CREATE_INFO,
  // Provided by VK_EXT_inline_uniform_block
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_INLINE_UNIFORM_BLOCK_FEATURES_EXT = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_INLINE_UNIFORM_BLOCK_FEATURES,
  // Provided by VK_EXT_inline_uniform_block
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_INLINE_UNIFORM_BLOCK_PROPERTIES_EXT = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_INLINE_UNIFORM_BLOCK_PROPERTIES,
  // Provided by VK_EXT_inline_uniform_block
    VK_STRUCTURE_TYPE_WRITE_DESCRIPTOR_SET_INLINE_UNIFORM_BLOCK_EXT = VK_STRUCTURE_TYPE_WRITE_DESCRIPTOR_SET_INLINE_UNIFORM_BLOCK,
  // Provided by VK_EXT_inline_uniform_block
    VK_STRUCTURE_TYPE_DESCRIPTOR_POOL_INLINE_UNIFORM_BLOCK_CREATE_INFO_EXT = VK_STRUCTURE_TYPE_DESCRIPTOR_POOL_INLINE_UNIFORM_BLOCK_CREATE_INFO,
  // Provided by VK_KHR_get_memory_requirements2
    VK_STRUCTURE_TYPE_BUFFER_MEMORY_REQUIREMENTS_INFO_2_KHR = VK_STRUCTURE_TYPE_BUFFER_MEMORY_REQUIREMENTS_INFO_2,
  // Provided by VK_KHR_get_memory_requirements2
    VK_STRUCTURE_TYPE_IMAGE_MEMORY_REQUIREMENTS_INFO_2_KHR = VK_STRUCTURE_TYPE_IMAGE_MEMORY_REQUIREMENTS_INFO_2,
  // Provided by VK_KHR_get_memory_requirements2
    VK_STRUCTURE_TYPE_IMAGE_SPARSE_MEMORY_REQUIREMENTS_INFO_2_KHR = VK_STRUCTURE_TYPE_IMAGE_SPARSE_MEMORY_REQUIREMENTS_INFO_2,
  // Provided by VK_KHR_get_memory_requirements2
    VK_STRUCTURE_TYPE_MEMORY_REQUIREMENTS_2_KHR = VK_STRUCTURE_TYPE_MEMORY_REQUIREMENTS_2,
  // Provided by VK_KHR_get_memory_requirements2
    VK_STRUCTURE_TYPE_SPARSE_IMAGE_MEMORY_REQUIREMENTS_2_KHR = VK_STRUCTURE_TYPE_SPARSE_IMAGE_MEMORY_REQUIREMENTS_2,
  // Provided by VK_KHR_image_format_list
    VK_STRUCTURE_TYPE_IMAGE_FORMAT_LIST_CREATE_INFO_KHR = VK_STRUCTURE_TYPE_IMAGE_FORMAT_LIST_CREATE_INFO,
  // Provided by VK_KHR_sampler_ycbcr_conversion
    VK_STRUCTURE_TYPE_SAMPLER_YCBCR_CONVERSION_CREATE_INFO_KHR = VK_STRUCTURE_TYPE_SAMPLER_YCBCR_CONVERSION_CREATE_INFO,
  // Provided by VK_KHR_sampler_ycbcr_conversion
    VK_STRUCTURE_TYPE_SAMPLER_YCBCR_CONVERSION_INFO_KHR = VK_STRUCTURE_TYPE_SAMPLER_YCBCR_CONVERSION_INFO,
  // Provided by VK_KHR_sampler_ycbcr_conversion
    VK_STRUCTURE_TYPE_BIND_IMAGE_PLANE_MEMORY_INFO_KHR = VK_STRUCTURE_TYPE_BIND_IMAGE_PLANE_MEMORY_INFO,
  // Provided by VK_KHR_sampler_ycbcr_conversion
    VK_STRUCTURE_TYPE_IMAGE_PLANE_MEMORY_REQUIREMENTS_INFO_KHR = VK_STRUCTURE_TYPE_IMAGE_PLANE_MEMORY_REQUIREMENTS_INFO,
  // Provided by VK_KHR_sampler_ycbcr_conversion
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SAMPLER_YCBCR_CONVERSION_FEATURES_KHR = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SAMPLER_YCBCR_CONVERSION_FEATURES,
  // Provided by VK_KHR_sampler_ycbcr_conversion
    VK_STRUCTURE_TYPE_SAMPLER_YCBCR_CONVERSION_IMAGE_FORMAT_PROPERTIES_KHR = VK_STRUCTURE_TYPE_SAMPLER_YCBCR_CONVERSION_IMAGE_FORMAT_PROPERTIES,
  // Provided by VK_KHR_bind_memory2
    VK_STRUCTURE_TYPE_BIND_BUFFER_MEMORY_INFO_KHR = VK_STRUCTURE_TYPE_BIND_BUFFER_MEMORY_INFO,
  // Provided by VK_KHR_bind_memory2
    VK_STRUCTURE_TYPE_BIND_IMAGE_MEMORY_INFO_KHR = VK_STRUCTURE_TYPE_BIND_IMAGE_MEMORY_INFO,
  // Provided by VK_EXT_descriptor_indexing
    VK_STRUCTURE_TYPE_DESCRIPTOR_SET_LAYOUT_BINDING_FLAGS_CREATE_INFO_EXT = VK_STRUCTURE_TYPE_DESCRIPTOR_SET_LAYOUT_BINDING_FLAGS_CREATE_INFO,
  // Provided by VK_EXT_descriptor_indexing
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DESCRIPTOR_INDEXING_FEATURES_EXT = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DESCRIPTOR_INDEXING_FEATURES,
  // Provided by VK_EXT_descriptor_indexing
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DESCRIPTOR_INDEXING_PROPERTIES_EXT = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DESCRIPTOR_INDEXING_PROPERTIES,
  // Provided by VK_EXT_descriptor_indexing
    VK_STRUCTURE_TYPE_DESCRIPTOR_SET_VARIABLE_DESCRIPTOR_COUNT_ALLOCATE_INFO_EXT = VK_STRUCTURE_TYPE_DESCRIPTOR_SET_VARIABLE_DESCRIPTOR_COUNT_ALLOCATE_INFO,
  // Provided by VK_EXT_descriptor_indexing
    VK_STRUCTURE_TYPE_DESCRIPTOR_SET_VARIABLE_DESCRIPTOR_COUNT_LAYOUT_SUPPORT_EXT = VK_STRUCTURE_TYPE_DESCRIPTOR_SET_VARIABLE_DESCRIPTOR_COUNT_LAYOUT_SUPPORT,
  // Provided by VK_KHR_maintenance3
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MAINTENANCE_3_PROPERTIES_KHR = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MAINTENANCE_3_PROPERTIES,
  // Provided by VK_KHR_maintenance3
    VK_STRUCTURE_TYPE_DESCRIPTOR_SET_LAYOUT_SUPPORT_KHR = VK_STRUCTURE_TYPE_DESCRIPTOR_SET_LAYOUT_SUPPORT,
  // Provided by VK_EXT_global_priority
    VK_STRUCTURE_TYPE_DEVICE_QUEUE_GLOBAL_PRIORITY_CREATE_INFO_EXT = VK_STRUCTURE_TYPE_DEVICE_QUEUE_GLOBAL_PRIORITY_CREATE_INFO_KHR,
  // Provided by VK_KHR_shader_subgroup_extended_types
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_SUBGROUP_EXTENDED_TYPES_FEATURES_KHR = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_SUBGROUP_EXTENDED_TYPES_FEATURES,
  // Provided by VK_KHR_8bit_storage
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_8BIT_STORAGE_FEATURES_KHR = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_8BIT_STORAGE_FEATURES,
  // Provided by VK_KHR_shader_atomic_int64
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_ATOMIC_INT64_FEATURES_KHR = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_ATOMIC_INT64_FEATURES,
  // Provided by VK_EXT_calibrated_timestamps
    VK_STRUCTURE_TYPE_CALIBRATED_TIMESTAMP_INFO_EXT = VK_STRUCTURE_TYPE_CALIBRATED_TIMESTAMP_INFO_KHR,
  // Provided by VK_EXT_vertex_attribute_divisor
    VK_STRUCTURE_TYPE_PIPELINE_VERTEX_INPUT_DIVISOR_STATE_CREATE_INFO_EXT = VK_STRUCTURE_TYPE_PIPELINE_VERTEX_INPUT_DIVISOR_STATE_CREATE_INFO_KHR,
  // Provided by VK_EXT_vertex_attribute_divisor
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VERTEX_ATTRIBUTE_DIVISOR_FEATURES_EXT = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VERTEX_ATTRIBUTE_DIVISOR_FEATURES_KHR,
  // Provided by VK_EXT_pipeline_creation_feedback
    VK_STRUCTURE_TYPE_PIPELINE_CREATION_FEEDBACK_CREATE_INFO_EXT = VK_STRUCTURE_TYPE_PIPELINE_CREATION_FEEDBACK_CREATE_INFO,
  // Provided by VK_KHR_driver_properties
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DRIVER_PROPERTIES_KHR = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DRIVER_PROPERTIES,
  // Provided by VK_KHR_shader_float_controls
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FLOAT_CONTROLS_PROPERTIES_KHR = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FLOAT_CONTROLS_PROPERTIES,
  // Provided by VK_KHR_depth_stencil_resolve
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DEPTH_STENCIL_RESOLVE_PROPERTIES_KHR = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DEPTH_STENCIL_RESOLVE_PROPERTIES,
  // Provided by VK_KHR_depth_stencil_resolve
    VK_STRUCTURE_TYPE_SUBPASS_DESCRIPTION_DEPTH_STENCIL_RESOLVE_KHR = VK_STRUCTURE_TYPE_SUBPASS_DESCRIPTION_DEPTH_STENCIL_RESOLVE,
  // Provided by VK_NV_compute_shader_derivatives
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_COMPUTE_SHADER_DERIVATIVES_FEATURES_NV = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_COMPUTE_SHADER_DERIVATIVES_FEATURES_KHR,
  // Provided by VK_NV_fragment_shader_barycentric
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FRAGMENT_SHADER_BARYCENTRIC_FEATURES_NV = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FRAGMENT_SHADER_BARYCENTRIC_FEATURES_KHR,
  // Provided by VK_KHR_timeline_semaphore
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_TIMELINE_SEMAPHORE_FEATURES_KHR = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_TIMELINE_SEMAPHORE_FEATURES,
  // Provided by VK_KHR_timeline_semaphore
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_TIMELINE_SEMAPHORE_PROPERTIES_KHR = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_TIMELINE_SEMAPHORE_PROPERTIES,
  // Provided by VK_KHR_timeline_semaphore
    VK_STRUCTURE_TYPE_SEMAPHORE_TYPE_CREATE_INFO_KHR = VK_STRUCTURE_TYPE_SEMAPHORE_TYPE_CREATE_INFO,
  // Provided by VK_KHR_timeline_semaphore
    VK_STRUCTURE_TYPE_TIMELINE_SEMAPHORE_SUBMIT_INFO_KHR = VK_STRUCTURE_TYPE_TIMELINE_SEMAPHORE_SUBMIT_INFO,
  // Provided by VK_KHR_timeline_semaphore
    VK_STRUCTURE_TYPE_SEMAPHORE_WAIT_INFO_KHR = VK_STRUCTURE_TYPE_SEMAPHORE_WAIT_INFO,
  // Provided by VK_KHR_timeline_semaphore
    VK_STRUCTURE_TYPE_SEMAPHORE_SIGNAL_INFO_KHR = VK_STRUCTURE_TYPE_SEMAPHORE_SIGNAL_INFO,
  // Provided by VK_INTEL_performance_query
  // VK_STRUCTURE_TYPE_QUERY_POOL_CREATE_INFO_INTEL is a deprecated alias
    VK_STRUCTURE_TYPE_QUERY_POOL_CREATE_INFO_INTEL = VK_STRUCTURE_TYPE_QUERY_POOL_PERFORMANCE_QUERY_CREATE_INFO_INTEL,
  // Provided by VK_KHR_vulkan_memory_model
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VULKAN_MEMORY_MODEL_FEATURES_KHR = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VULKAN_MEMORY_MODEL_FEATURES,
  // Provided by VK_KHR_shader_terminate_invocation
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_TERMINATE_INVOCATION_FEATURES_KHR = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_TERMINATE_INVOCATION_FEATURES,
  // Provided by VK_EXT_scalar_block_layout
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SCALAR_BLOCK_LAYOUT_FEATURES_EXT = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SCALAR_BLOCK_LAYOUT_FEATURES,
  // Provided by VK_EXT_subgroup_size_control
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SUBGROUP_SIZE_CONTROL_PROPERTIES_EXT = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SUBGROUP_SIZE_CONTROL_PROPERTIES,
  // Provided by VK_EXT_subgroup_size_control
    VK_STRUCTURE_TYPE_PIPELINE_SHADER_STAGE_REQUIRED_SUBGROUP_SIZE_CREATE_INFO_EXT = VK_STRUCTURE_TYPE_PIPELINE_SHADER_STAGE_REQUIRED_SUBGROUP_SIZE_CREATE_INFO,
  // Provided by VK_EXT_subgroup_size_control
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SUBGROUP_SIZE_CONTROL_FEATURES_EXT = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SUBGROUP_SIZE_CONTROL_FEATURES,
  // Provided by VK_KHR_separate_depth_stencil_layouts
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SEPARATE_DEPTH_STENCIL_LAYOUTS_FEATURES_KHR = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SEPARATE_DEPTH_STENCIL_LAYOUTS_FEATURES,
  // Provided by VK_KHR_separate_depth_stencil_layouts
    VK_STRUCTURE_TYPE_ATTACHMENT_REFERENCE_STENCIL_LAYOUT_KHR = VK_STRUCTURE_TYPE_ATTACHMENT_REFERENCE_STENCIL_LAYOUT,
  // Provided by VK_KHR_separate_depth_stencil_layouts
    VK_STRUCTURE_TYPE_ATTACHMENT_DESCRIPTION_STENCIL_LAYOUT_KHR = VK_STRUCTURE_TYPE_ATTACHMENT_DESCRIPTION_STENCIL_LAYOUT,
  // Provided by VK_EXT_buffer_device_address
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_BUFFER_ADDRESS_FEATURES_EXT = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_BUFFER_DEVICE_ADDRESS_FEATURES_EXT,
  // Provided by VK_EXT_buffer_device_address
    VK_STRUCTURE_TYPE_BUFFER_DEVICE_ADDRESS_INFO_EXT = VK_STRUCTURE_TYPE_BUFFER_DEVICE_ADDRESS_INFO,
  // Provided by VK_EXT_tooling_info
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_TOOL_PROPERTIES_EXT = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_TOOL_PROPERTIES,
  // Provided by VK_EXT_separate_stencil_usage
    VK_STRUCTURE_TYPE_IMAGE_STENCIL_USAGE_CREATE_INFO_EXT = VK_STRUCTURE_TYPE_IMAGE_STENCIL_USAGE_CREATE_INFO,
  // Provided by VK_KHR_uniform_buffer_standard_layout
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_UNIFORM_BUFFER_STANDARD_LAYOUT_FEATURES_KHR = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_UNIFORM_BUFFER_STANDARD_LAYOUT_FEATURES,
  // Provided by VK_KHR_buffer_device_address
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_BUFFER_DEVICE_ADDRESS_FEATURES_KHR = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_BUFFER_DEVICE_ADDRESS_FEATURES,
  // Provided by VK_KHR_buffer_device_address
    VK_STRUCTURE_TYPE_BUFFER_DEVICE_ADDRESS_INFO_KHR = VK_STRUCTURE_TYPE_BUFFER_DEVICE_ADDRESS_INFO,
  // Provided by VK_KHR_buffer_device_address
    VK_STRUCTURE_TYPE_BUFFER_OPAQUE_CAPTURE_ADDRESS_CREATE_INFO_KHR = VK_STRUCTURE_TYPE_BUFFER_OPAQUE_CAPTURE_ADDRESS_CREATE_INFO,
  // Provided by VK_KHR_buffer_device_address
    VK_STRUCTURE_TYPE_MEMORY_OPAQUE_CAPTURE_ADDRESS_ALLOCATE_INFO_KHR = VK_STRUCTURE_TYPE_MEMORY_OPAQUE_CAPTURE_ADDRESS_ALLOCATE_INFO,
  // Provided by VK_KHR_buffer_device_address
    VK_STRUCTURE_TYPE_DEVICE_MEMORY_OPAQUE_CAPTURE_ADDRESS_INFO_KHR = VK_STRUCTURE_TYPE_DEVICE_MEMORY_OPAQUE_CAPTURE_ADDRESS_INFO,
  // Provided by VK_EXT_line_rasterization
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_LINE_RASTERIZATION_FEATURES_EXT = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_LINE_RASTERIZATION_FEATURES_KHR,
  // Provided by VK_EXT_line_rasterization
    VK_STRUCTURE_TYPE_PIPELINE_RASTERIZATION_LINE_STATE_CREATE_INFO_EXT = VK_STRUCTURE_TYPE_PIPELINE_RASTERIZATION_LINE_STATE_CREATE_INFO_KHR,
  // Provided by VK_EXT_line_rasterization
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_LINE_RASTERIZATION_PROPERTIES_EXT = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_LINE_RASTERIZATION_PROPERTIES_KHR,
  // Provided by VK_EXT_host_query_reset
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_HOST_QUERY_RESET_FEATURES_EXT = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_HOST_QUERY_RESET_FEATURES,
  // Provided by VK_EXT_index_type_uint8
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_INDEX_TYPE_UINT8_FEATURES_EXT = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_INDEX_TYPE_UINT8_FEATURES_KHR,
  // Provided by VK_EXT_shader_demote_to_helper_invocation
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_DEMOTE_TO_HELPER_INVOCATION_FEATURES_EXT = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_DEMOTE_TO_HELPER_INVOCATION_FEATURES,
  // Provided by VK_KHR_shader_integer_dot_product
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_INTEGER_DOT_PRODUCT_FEATURES_KHR = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_INTEGER_DOT_PRODUCT_FEATURES,
  // Provided by VK_KHR_shader_integer_dot_product
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_INTEGER_DOT_PRODUCT_PROPERTIES_KHR = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_INTEGER_DOT_PRODUCT_PROPERTIES,
  // Provided by VK_EXT_texel_buffer_alignment
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_TEXEL_BUFFER_ALIGNMENT_PROPERTIES_EXT = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_TEXEL_BUFFER_ALIGNMENT_PROPERTIES,
  // Provided by VK_EXT_private_data
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PRIVATE_DATA_FEATURES_EXT = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PRIVATE_DATA_FEATURES,
  // Provided by VK_EXT_private_data
    VK_STRUCTURE_TYPE_DEVICE_PRIVATE_DATA_CREATE_INFO_EXT = VK_STRUCTURE_TYPE_DEVICE_PRIVATE_DATA_CREATE_INFO,
  // Provided by VK_EXT_private_data
    VK_STRUCTURE_TYPE_PRIVATE_DATA_SLOT_CREATE_INFO_EXT = VK_STRUCTURE_TYPE_PRIVATE_DATA_SLOT_CREATE_INFO,
  // Provided by VK_EXT_pipeline_creation_cache_control
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PIPELINE_CREATION_CACHE_CONTROL_FEATURES_EXT = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PIPELINE_CREATION_CACHE_CONTROL_FEATURES,
  // Provided by VK_KHR_synchronization2
    VK_STRUCTURE_TYPE_MEMORY_BARRIER_2_KHR = VK_STRUCTURE_TYPE_MEMORY_BARRIER_2,
  // Provided by VK_KHR_synchronization2
    VK_STRUCTURE_TYPE_BUFFER_MEMORY_BARRIER_2_KHR = VK_STRUCTURE_TYPE_BUFFER_MEMORY_BARRIER_2,
  // Provided by VK_KHR_synchronization2
    VK_STRUCTURE_TYPE_IMAGE_MEMORY_BARRIER_2_KHR = VK_STRUCTURE_TYPE_IMAGE_MEMORY_BARRIER_2,
  // Provided by VK_KHR_synchronization2
    VK_STRUCTURE_TYPE_DEPENDENCY_INFO_KHR = VK_STRUCTURE_TYPE_DEPENDENCY_INFO,
  // Provided by VK_KHR_synchronization2
    VK_STRUCTURE_TYPE_SUBMIT_INFO_2_KHR = VK_STRUCTURE_TYPE_SUBMIT_INFO_2,
  // Provided by VK_KHR_synchronization2
    VK_STRUCTURE_TYPE_SEMAPHORE_SUBMIT_INFO_KHR = VK_STRUCTURE_TYPE_SEMAPHORE_SUBMIT_INFO,
  // Provided by VK_KHR_synchronization2
    VK_STRUCTURE_TYPE_COMMAND_BUFFER_SUBMIT_INFO_KHR = VK_STRUCTURE_TYPE_COMMAND_BUFFER_SUBMIT_INFO,
  // Provided by VK_KHR_synchronization2
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SYNCHRONIZATION_2_FEATURES_KHR = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SYNCHRONIZATION_2_FEATURES,
  // Provided by VK_KHR_zero_initialize_workgroup_memory
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_ZERO_INITIALIZE_WORKGROUP_MEMORY_FEATURES_KHR = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_ZERO_INITIALIZE_WORKGROUP_MEMORY_FEATURES,
  // Provided by VK_EXT_image_robustness
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGE_ROBUSTNESS_FEATURES_EXT = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGE_ROBUSTNESS_FEATURES,
  // Provided by VK_KHR_copy_commands2
    VK_STRUCTURE_TYPE_COPY_BUFFER_INFO_2_KHR = VK_STRUCTURE_TYPE_COPY_BUFFER_INFO_2,
  // Provided by VK_KHR_copy_commands2
    VK_STRUCTURE_TYPE_COPY_IMAGE_INFO_2_KHR = VK_STRUCTURE_TYPE_COPY_IMAGE_INFO_2,
  // Provided by VK_KHR_copy_commands2
    VK_STRUCTURE_TYPE_COPY_BUFFER_TO_IMAGE_INFO_2_KHR = VK_STRUCTURE_TYPE_COPY_BUFFER_TO_IMAGE_INFO_2,
  // Provided by VK_KHR_copy_commands2
    VK_STRUCTURE_TYPE_COPY_IMAGE_TO_BUFFER_INFO_2_KHR = VK_STRUCTURE_TYPE_COPY_IMAGE_TO_BUFFER_INFO_2,
  // Provided by VK_KHR_copy_commands2
    VK_STRUCTURE_TYPE_BLIT_IMAGE_INFO_2_KHR = VK_STRUCTURE_TYPE_BLIT_IMAGE_INFO_2,
  // Provided by VK_KHR_copy_commands2
    VK_STRUCTURE_TYPE_RESOLVE_IMAGE_INFO_2_KHR = VK_STRUCTURE_TYPE_RESOLVE_IMAGE_INFO_2,
  // Provided by VK_KHR_copy_commands2
    VK_STRUCTURE_TYPE_BUFFER_COPY_2_KHR = VK_STRUCTURE_TYPE_BUFFER_COPY_2,
  // Provided by VK_KHR_copy_commands2
    VK_STRUCTURE_TYPE_IMAGE_COPY_2_KHR = VK_STRUCTURE_TYPE_IMAGE_COPY_2,
  // Provided by VK_KHR_copy_commands2
    VK_STRUCTURE_TYPE_IMAGE_BLIT_2_KHR = VK_STRUCTURE_TYPE_IMAGE_BLIT_2,
  // Provided by VK_KHR_copy_commands2
    VK_STRUCTURE_TYPE_BUFFER_IMAGE_COPY_2_KHR = VK_STRUCTURE_TYPE_BUFFER_IMAGE_COPY_2,
  // Provided by VK_KHR_copy_commands2
    VK_STRUCTURE_TYPE_IMAGE_RESOLVE_2_KHR = VK_STRUCTURE_TYPE_IMAGE_RESOLVE_2,
  // Provided by VK_EXT_image_compression_control
    VK_STRUCTURE_TYPE_SUBRESOURCE_LAYOUT_2_EXT = VK_STRUCTURE_TYPE_SUBRESOURCE_LAYOUT_2_KHR,
  // Provided by VK_EXT_image_compression_control
    VK_STRUCTURE_TYPE_IMAGE_SUBRESOURCE_2_EXT = VK_STRUCTURE_TYPE_IMAGE_SUBRESOURCE_2_KHR,
  // Provided by VK_ARM_rasterization_order_attachment_access
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_RASTERIZATION_ORDER_ATTACHMENT_ACCESS_FEATURES_ARM = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_RASTERIZATION_ORDER_ATTACHMENT_ACCESS_FEATURES_EXT,
  // Provided by VK_VALVE_mutable_descriptor_type
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MUTABLE_DESCRIPTOR_TYPE_FEATURES_VALVE = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MUTABLE_DESCRIPTOR_TYPE_FEATURES_EXT,
  // Provided by VK_VALVE_mutable_descriptor_type
    VK_STRUCTURE_TYPE_MUTABLE_DESCRIPTOR_TYPE_CREATE_INFO_VALVE = VK_STRUCTURE_TYPE_MUTABLE_DESCRIPTOR_TYPE_CREATE_INFO_EXT,
  // Provided by VK_KHR_format_feature_flags2
    VK_STRUCTURE_TYPE_FORMAT_PROPERTIES_3_KHR = VK_STRUCTURE_TYPE_FORMAT_PROPERTIES_3,
  // Provided by VK_EXT_pipeline_properties
    VK_STRUCTURE_TYPE_PIPELINE_INFO_EXT = VK_STRUCTURE_TYPE_PIPELINE_INFO_KHR,
  // Provided by VK_EXT_global_priority_query
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_GLOBAL_PRIORITY_QUERY_FEATURES_EXT = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_GLOBAL_PRIORITY_QUERY_FEATURES_KHR,
  // Provided by VK_EXT_global_priority_query
    VK_STRUCTURE_TYPE_QUEUE_FAMILY_GLOBAL_PRIORITY_PROPERTIES_EXT = VK_STRUCTURE_TYPE_QUEUE_FAMILY_GLOBAL_PRIORITY_PROPERTIES_KHR,
  // Provided by VK_KHR_maintenance4
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MAINTENANCE_4_FEATURES_KHR = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MAINTENANCE_4_FEATURES,
  // Provided by VK_KHR_maintenance4
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MAINTENANCE_4_PROPERTIES_KHR = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MAINTENANCE_4_PROPERTIES,
  // Provided by VK_KHR_maintenance4
    VK_STRUCTURE_TYPE_DEVICE_BUFFER_MEMORY_REQUIREMENTS_KHR = VK_STRUCTURE_TYPE_DEVICE_BUFFER_MEMORY_REQUIREMENTS,
  // Provided by VK_KHR_maintenance4
    VK_STRUCTURE_TYPE_DEVICE_IMAGE_MEMORY_REQUIREMENTS_KHR = VK_STRUCTURE_TYPE_DEVICE_IMAGE_MEMORY_REQUIREMENTS,
  // Provided by VK_EXT_shader_object
    VK_STRUCTURE_TYPE_SHADER_REQUIRED_SUBGROUP_SIZE_CREATE_INFO_EXT = VK_STRUCTURE_TYPE_PIPELINE_SHADER_STAGE_REQUIRED_SUBGROUP_SIZE_CREATE_INFO,
} VkStructureType;

3.13. API Name Aliases

A small number of APIs did not follow the naming conventions when initially defined. For consistency, when we discover an API name that violates the naming conventions, we rename it in the Specification, XML, and header files. For backwards compatibility, the original (incorrect) name is retained as a “typo alias”. The alias is deprecated and should not be used, but will be retained indefinitely.

Note

VK_STENCIL_FRONT_AND_BACK is an example of a typo alias. It was initially defined as part of VkStencilFaceFlagBits. Once the naming inconsistency was noticed, it was renamed to VK_STENCIL_FACE_FRONT_AND_BACK, and the old name was aliased to the correct name.

4. Initialization

Before using Vulkan, an application must initialize it by loading the Vulkan commands, and creating a VkInstance object.

4.1. Command Function Pointers

Vulkan commands are not necessarily exposed by static linking on a platform. Commands to query function pointers for Vulkan commands are described below.

Note

When extensions are promoted or otherwise incorporated into another extension or Vulkan core version, command aliases may be included. Whilst the behavior of each command alias is identical, the behavior of retrieving each alias’s function pointer is not. A function pointer for a given alias can only be retrieved if the extension or version that introduced that alias is supported and enabled, irrespective of whether any other alias is available.

Function pointers for all Vulkan commands can be obtained by calling:

// Provided by VK_VERSION_1_0
PFN_vkVoidFunction vkGetInstanceProcAddr(
    VkInstance                                  instance,
    const char*                                 pName);

  • instance is the instance that the function pointer will be compatible with, or NULL for commands not dependent on any instance.

  • pName is the name of the command to obtain.

vkGetInstanceProcAddr itself is obtained in a platform- and loader- specific manner. Typically, the loader library will export this command as a function symbol, so applications can link against the loader library, or load it dynamically and look up the symbol using platform-specific APIs.

The table below defines the various use cases for vkGetInstanceProcAddr and expected return value (“fp” is “function pointer”) for each case. A valid returned function pointer (“fp”) must not be NULL.

The returned function pointer is of type PFN_vkVoidFunction, and must be cast to the type of the command being queried before use.

Table 1. vkGetInstanceProcAddr behavior
instance pName return value

*1

NULL

undefined

invalid non-NULL instance

*1

undefined

NULL

global command2

fp

NULL

vkGetInstanceProcAddr

fp5

instance

vkGetInstanceProcAddr

fp

instance

core dispatchable command

fp3

instance

enabled instance extension dispatchable command for instance

fp3

instance

available device extension4 dispatchable command for instance

fp3

any other case, not covered above

NULL
1

"*" means any representable value for the parameter (including valid values, invalid values, and NULL).

2

The global commands are: vkEnumerateInstanceVersion, vkEnumerateInstanceExtensionProperties, vkEnumerateInstanceLayerProperties, and vkCreateInstance. Dispatchable commands are all other commands which are not global.

3

The returned function pointer must only be called with a dispatchable object (the first parameter) that is instance or a child of instance, e.g. VkInstance, VkPhysicalDevice, VkDevice, VkQueue, or VkCommandBuffer.

4

An “available device extension” is a device extension supported by any physical device enumerated by instance.

5

Starting with Vulkan 1.2, vkGetInstanceProcAddr can resolve itself with a NULL instance pointer.

Valid Usage (Implicit)

  • VUID-vkGetInstanceProcAddr-instance-parameter
    If instance is not NULL, instance must be a valid VkInstance handle

  • VUID-vkGetInstanceProcAddr-pName-parameter
    pName must be a null-terminated UTF-8 string

In order to support systems with multiple Vulkan implementations, the function pointers returned by vkGetInstanceProcAddr may point to dispatch code that calls a different real implementation for different VkDevice objects or their child objects. The overhead of the internal dispatch for VkDevice objects can be avoided by obtaining device-specific function pointers for any commands that use a device or device-child object as their dispatchable object. Such function pointers can be obtained by calling:

// Provided by VK_VERSION_1_0
PFN_vkVoidFunction vkGetDeviceProcAddr(
    VkDevice                                    device,
    const char*                                 pName);

The table below defines the various use cases for vkGetDeviceProcAddr and expected return value (“fp” is “function pointer”) for each case. A valid returned function pointer (“fp”) must not be NULL.

The returned function pointer is of type PFN_vkVoidFunction, and must be cast to the type of the command being queried before use. The function pointer must only be called with a dispatchable object (the first parameter) that is device or a child of device.

Table 2. vkGetDeviceProcAddr behavior
device pName return value

NULL

*1

undefined

invalid device

*1

undefined

device

NULL

undefined

device

requested core version2 device-level dispatchable command3

fp4

device

enabled extension device-level dispatchable command3

fp4

any other case, not covered above

NULL
1

"*" means any representable value for the parameter (including valid values, invalid values, and NULL).

2

Device-level commands which are part of the core version specified by VkApplicationInfo::apiVersion when creating the instance will always return a valid function pointer. If the maintenance5 feature is enabled, core commands beyond that version which are supported by the implementation will return NULL, otherwise the implementation may either return NULL or a function pointer. If a function pointer is returned, it must not be called.

3

In this function, device-level excludes all physical-device-level commands.

4

The returned function pointer must only be called with a dispatchable object (the first parameter) that is device or a child of device e.g. VkDevice, VkQueue, or VkCommandBuffer.

Valid Usage (Implicit)

  • VUID-vkGetDeviceProcAddr-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkGetDeviceProcAddr-pName-parameter
    pName must be a null-terminated UTF-8 string

The definition of PFN_vkVoidFunction is:

// Provided by VK_VERSION_1_0
typedef void (VKAPI_PTR *PFN_vkVoidFunction)(void);

This type is returned from command function pointer queries, and must be cast to an actual command function pointer before use.

4.1.1. Extending Physical Device Core Functionality

New core physical-device-level functionality can be used when both VkPhysicalDeviceProperties::apiVersion and VkApplicationInfo::apiVersion are greater than or equal to the version of Vulkan that added the new functionality. The Vulkan version supported by a physical device can be obtained by calling vkGetPhysicalDeviceProperties.

4.1.2. Extending Physical Device From Device Extensions

When the VK_KHR_get_physical_device_properties2 extension is enabled, or when both the instance and the physical-device versions are at least 1.1, physical-device-level functionality of a device extension can be used with a physical device if the corresponding extension is enumerated by vkEnumerateDeviceExtensionProperties for that physical device, even before a logical device has been created.

To obtain a function pointer for a physical-device-level command from a device extension, an application can use vkGetInstanceProcAddr. This function pointer may point to dispatch code, which calls a different real implementation for different VkPhysicalDevice objects. Applications must not use a VkPhysicalDevice in any command added by an extension or core version that is not supported by that physical device.

Device extensions may define structures that can be added to the pNext chain of physical-device-level commands.

4.2. Instances

There is no global state in Vulkan and all per-application state is stored in a VkInstance object. Creating a VkInstance object initializes the Vulkan library and allows the application to pass information about itself to the implementation.

Instances are represented by VkInstance handles:

// Provided by VK_VERSION_1_0
VK_DEFINE_HANDLE(VkInstance)

To query the version of instance-level functionality supported by the implementation, call:

// Provided by VK_VERSION_1_1
VkResult vkEnumerateInstanceVersion(
    uint32_t*                                   pApiVersion);

  • pApiVersion is a pointer to a uint32_t, which is the version of Vulkan supported by instance-level functionality, encoded as described in Version Numbers.

Note

The intended behavior of vkEnumerateInstanceVersion is that an implementation should not need to perform memory allocations and should unconditionally return VK_SUCCESS. The loader, and any enabled layers, may return VK_ERROR_OUT_OF_HOST_MEMORY in the case of a failed memory allocation.
Valid Usage (Implicit)

  • VUID-vkEnumerateInstanceVersion-pApiVersion-parameter
    pApiVersion must be a valid pointer to a uint32_t value

Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

To create an instance object, call:

// Provided by VK_VERSION_1_0
VkResult vkCreateInstance(
    const VkInstanceCreateInfo*                 pCreateInfo,
    const VkAllocationCallbacks*                pAllocator,
    VkInstance*                                 pInstance);

  • pCreateInfo is a pointer to a VkInstanceCreateInfo structure controlling creation of the instance.

  • pAllocator controls host memory allocation as described in the Memory Allocation chapter.

  • pInstance points a VkInstance handle in which the resulting instance is returned.

vkCreateInstance verifies that the requested layers exist. If not, vkCreateInstance will return VK_ERROR_LAYER_NOT_PRESENT. Next vkCreateInstance verifies that the requested extensions are supported (e.g. in the implementation or in any enabled instance layer) and if any requested extension is not supported, vkCreateInstance must return VK_ERROR_EXTENSION_NOT_PRESENT. After verifying and enabling the instance layers and extensions the VkInstance object is created and returned to the application. If a requested extension is only supported by a layer, both the layer and the extension need to be specified at vkCreateInstance time for the creation to succeed.

Valid Usage
Valid Usage (Implicit)

  • VUID-vkCreateInstance-pCreateInfo-parameter
    pCreateInfo must be a valid pointer to a valid VkInstanceCreateInfo structure

  • VUID-vkCreateInstance-pAllocator-parameter
    If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure

  • VUID-vkCreateInstance-pInstance-parameter
    pInstance must be a valid pointer to a VkInstance handle

Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

  • VK_ERROR_INITIALIZATION_FAILED

  • VK_ERROR_LAYER_NOT_PRESENT

  • VK_ERROR_EXTENSION_NOT_PRESENT

  • VK_ERROR_INCOMPATIBLE_DRIVER

The VkInstanceCreateInfo structure is defined as:

// Provided by VK_VERSION_1_0
typedef struct VkInstanceCreateInfo {
    VkStructureType             sType;
    const void*                 pNext;
    VkInstanceCreateFlags       flags;
    const VkApplicationInfo*    pApplicationInfo;
    uint32_t                    enabledLayerCount;
    const char* const*          ppEnabledLayerNames;
    uint32_t                    enabledExtensionCount;
    const char* const*          ppEnabledExtensionNames;
} VkInstanceCreateInfo;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • flags is a bitmask of VkInstanceCreateFlagBits indicating the behavior of the instance.

  • pApplicationInfo is NULL or a pointer to a VkApplicationInfo structure. If not NULL, this information helps implementations recognize behavior inherent to classes of applications. VkApplicationInfo is defined in detail below.

  • enabledLayerCount is the number of global layers to enable.

  • ppEnabledLayerNames is a pointer to an array of enabledLayerCount null-terminated UTF-8 strings containing the names of layers to enable for the created instance. The layers are loaded in the order they are listed in this array, with the first array element being the closest to the application, and the last array element being the closest to the driver. See the Layers section for further details.

  • enabledExtensionCount is the number of global extensions to enable.

  • ppEnabledExtensionNames is a pointer to an array of enabledExtensionCount null-terminated UTF-8 strings containing the names of extensions to enable.

To capture events that occur while creating or destroying an instance, an application can link a VkDebugReportCallbackCreateInfoEXT structure or 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 vkCreateDebugReportCallbackEXT or vkCreateDebugUtilsMessengerEXT to create persistent callback objects.

An application can add additional drivers by including the VkDirectDriverLoadingListLUNARG struct to the pNext element of the VkInstanceCreateInfo structure given to vkCreateInstance.

Note

VkDirectDriverLoadingListLUNARG allows applications to ship drivers with themselves. Only drivers that are designed to work with it should be used, such as drivers that implement Vulkan in software or that implement Vulkan by translating it to a different API. Any driver that requires installation should not be used, such as hardware drivers.
Valid Usage

  • VUID-VkInstanceCreateInfo-pNext-04925
    If the pNext chain of VkInstanceCreateInfo includes a VkDebugReportCallbackCreateInfoEXT structure, the list of enabled extensions in ppEnabledExtensionNames must contain VK_EXT_debug_report

  • VUID-VkInstanceCreateInfo-pNext-04926
    If the pNext chain of VkInstanceCreateInfo includes a VkDebugUtilsMessengerCreateInfoEXT structure, the list of enabled extensions in ppEnabledExtensionNames must contain VK_EXT_debug_utils

  • VUID-VkInstanceCreateInfo-pNext-06779
    If the pNext chain includes a VkExportMetalObjectCreateInfoEXT structure, its exportObjectType member must be either VK_EXPORT_METAL_OBJECT_TYPE_METAL_DEVICE_BIT_EXT or VK_EXPORT_METAL_OBJECT_TYPE_METAL_COMMAND_QUEUE_BIT_EXT

  • VUID-VkInstanceCreateInfo-flags-06559
    If flags has the VK_INSTANCE_CREATE_ENUMERATE_PORTABILITY_BIT_KHR bit set, the list of enabled extensions in ppEnabledExtensionNames must contain VK_KHR_portability_enumeration

  • VUID-VkInstanceCreateInfo-pNext-09400
    If the pNext chain of VkInstanceCreateInfo includes a VkDirectDriverLoadingListLUNARG structure, the list of enabled extensions in ppEnabledExtensionNames must contain VK_LUNARG_direct_driver_loading

Valid Usage (Implicit)
// Provided by VK_VERSION_1_0
typedef enum VkInstanceCreateFlagBits {
  // Provided by VK_KHR_portability_enumeration
    VK_INSTANCE_CREATE_ENUMERATE_PORTABILITY_BIT_KHR = 0x00000001,
} VkInstanceCreateFlagBits;

  • VK_INSTANCE_CREATE_ENUMERATE_PORTABILITY_BIT_KHR specifies that the instance will enumerate available Vulkan Portability-compliant physical devices and groups in addition to the Vulkan physical devices and groups that are enumerated by default.

// Provided by VK_VERSION_1_0
typedef VkFlags VkInstanceCreateFlags;

VkInstanceCreateFlags is a bitmask type for setting a mask of zero or more VkInstanceCreateFlagBits.

When creating a Vulkan instance for which you wish to disable validation checks, add a VkValidationFlagsEXT structure to the pNext chain of the VkInstanceCreateInfo structure, specifying the checks to be disabled.

// Provided by VK_EXT_validation_flags
typedef struct VkValidationFlagsEXT {
    VkStructureType                sType;
    const void*                    pNext;
    uint32_t                       disabledValidationCheckCount;
    const VkValidationCheckEXT*    pDisabledValidationChecks;
} VkValidationFlagsEXT;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • disabledValidationCheckCount is the number of checks to disable.

  • pDisabledValidationChecks is a pointer to an array of VkValidationCheckEXT values specifying the validation checks to be disabled.

Valid Usage (Implicit)

  • VUID-VkValidationFlagsEXT-sType-sType
    sType must be VK_STRUCTURE_TYPE_VALIDATION_FLAGS_EXT

  • VUID-VkValidationFlagsEXT-pDisabledValidationChecks-parameter
    pDisabledValidationChecks must be a valid pointer to an array of disabledValidationCheckCount valid VkValidationCheckEXT values

  • VUID-VkValidationFlagsEXT-disabledValidationCheckCount-arraylength
    disabledValidationCheckCount must be greater than 0

Possible values of elements of the VkValidationFlagsEXT::pDisabledValidationChecks array, specifying validation checks to be disabled, are:

// Provided by VK_EXT_validation_flags
typedef enum VkValidationCheckEXT {
    VK_VALIDATION_CHECK_ALL_EXT = 0,
    VK_VALIDATION_CHECK_SHADERS_EXT = 1,
} VkValidationCheckEXT;

  • VK_VALIDATION_CHECK_ALL_EXT specifies that all validation checks are disabled.

  • VK_VALIDATION_CHECK_SHADERS_EXT specifies that shader validation is disabled.

When creating a Vulkan instance for which you wish to enable or disable specific validation features, add a VkValidationFeaturesEXT structure to the pNext chain of the VkInstanceCreateInfo structure, specifying the features to be enabled or disabled.

// Provided by VK_EXT_validation_features
typedef struct VkValidationFeaturesEXT {
    VkStructureType                         sType;
    const void*                             pNext;
    uint32_t                                enabledValidationFeatureCount;
    const VkValidationFeatureEnableEXT*     pEnabledValidationFeatures;
    uint32_t                                disabledValidationFeatureCount;
    const VkValidationFeatureDisableEXT*    pDisabledValidationFeatures;
} VkValidationFeaturesEXT;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • enabledValidationFeatureCount is the number of features to enable.

  • pEnabledValidationFeatures is a pointer to an array of VkValidationFeatureEnableEXT values specifying the validation features to be enabled.

  • disabledValidationFeatureCount is the number of features to disable.

  • pDisabledValidationFeatures is a pointer to an array of VkValidationFeatureDisableEXT values specifying the validation features to be disabled.

Valid Usage

  • VUID-VkValidationFeaturesEXT-pEnabledValidationFeatures-02967
    If the pEnabledValidationFeatures array contains VK_VALIDATION_FEATURE_ENABLE_GPU_ASSISTED_RESERVE_BINDING_SLOT_EXT, then it must also contain VK_VALIDATION_FEATURE_ENABLE_GPU_ASSISTED_EXT or VK_VALIDATION_FEATURE_ENABLE_DEBUG_PRINTF_EXT

  • VUID-VkValidationFeaturesEXT-pEnabledValidationFeatures-02968
    If the pEnabledValidationFeatures array contains VK_VALIDATION_FEATURE_ENABLE_DEBUG_PRINTF_EXT, then it must not contain VK_VALIDATION_FEATURE_ENABLE_GPU_ASSISTED_EXT

Valid Usage (Implicit)

  • VUID-VkValidationFeaturesEXT-sType-sType
    sType must be VK_STRUCTURE_TYPE_VALIDATION_FEATURES_EXT

  • VUID-VkValidationFeaturesEXT-pEnabledValidationFeatures-parameter
    If enabledValidationFeatureCount is not 0, pEnabledValidationFeatures must be a valid pointer to an array of enabledValidationFeatureCount valid VkValidationFeatureEnableEXT values

  • VUID-VkValidationFeaturesEXT-pDisabledValidationFeatures-parameter
    If disabledValidationFeatureCount is not 0, pDisabledValidationFeatures must be a valid pointer to an array of disabledValidationFeatureCount valid VkValidationFeatureDisableEXT values

Possible values of elements of the VkValidationFeaturesEXT::pEnabledValidationFeatures array, specifying validation features to be enabled, are:

// Provided by VK_EXT_validation_features
typedef enum VkValidationFeatureEnableEXT {
    VK_VALIDATION_FEATURE_ENABLE_GPU_ASSISTED_EXT = 0,
    VK_VALIDATION_FEATURE_ENABLE_GPU_ASSISTED_RESERVE_BINDING_SLOT_EXT = 1,
    VK_VALIDATION_FEATURE_ENABLE_BEST_PRACTICES_EXT = 2,
    VK_VALIDATION_FEATURE_ENABLE_DEBUG_PRINTF_EXT = 3,
    VK_VALIDATION_FEATURE_ENABLE_SYNCHRONIZATION_VALIDATION_EXT = 4,
} VkValidationFeatureEnableEXT;

  • VK_VALIDATION_FEATURE_ENABLE_GPU_ASSISTED_EXT specifies that GPU-assisted validation is enabled. Activating this feature instruments shader programs to generate additional diagnostic data. This feature is disabled by default.

  • VK_VALIDATION_FEATURE_ENABLE_GPU_ASSISTED_RESERVE_BINDING_SLOT_EXT specifies that the validation layers reserve a descriptor set binding slot for their own use. The layer reports a value for VkPhysicalDeviceLimits::maxBoundDescriptorSets that is one less than the value reported by the device. If the device supports the binding of only one descriptor set, the validation layer does not perform GPU-assisted validation. This feature is disabled by default.

  • VK_VALIDATION_FEATURE_ENABLE_BEST_PRACTICES_EXT specifies that Vulkan best-practices validation is enabled. Activating this feature enables the output of warnings related to common misuse of the API, but which are not explicitly prohibited by the specification. This feature is disabled by default.

  • VK_VALIDATION_FEATURE_ENABLE_DEBUG_PRINTF_EXT specifies that the layers will process debugPrintfEXT operations in shaders and send the resulting output to the debug callback. This feature is disabled by default.

  • VK_VALIDATION_FEATURE_ENABLE_SYNCHRONIZATION_VALIDATION_EXT specifies that Vulkan synchronization validation is enabled. This feature reports resource access conflicts due to missing or incorrect synchronization operations between actions (Draw, Copy, Dispatch, Blit) reading or writing the same regions of memory. This feature is disabled by default.

Possible values of elements of the VkValidationFeaturesEXT::pDisabledValidationFeatures array, specifying validation features to be disabled, are:

// Provided by VK_EXT_validation_features
typedef enum VkValidationFeatureDisableEXT {
    VK_VALIDATION_FEATURE_DISABLE_ALL_EXT = 0,
    VK_VALIDATION_FEATURE_DISABLE_SHADERS_EXT = 1,
    VK_VALIDATION_FEATURE_DISABLE_THREAD_SAFETY_EXT = 2,
    VK_VALIDATION_FEATURE_DISABLE_API_PARAMETERS_EXT = 3,
    VK_VALIDATION_FEATURE_DISABLE_OBJECT_LIFETIMES_EXT = 4,
    VK_VALIDATION_FEATURE_DISABLE_CORE_CHECKS_EXT = 5,
    VK_VALIDATION_FEATURE_DISABLE_UNIQUE_HANDLES_EXT = 6,
    VK_VALIDATION_FEATURE_DISABLE_SHADER_VALIDATION_CACHE_EXT = 7,
} VkValidationFeatureDisableEXT;

  • VK_VALIDATION_FEATURE_DISABLE_ALL_EXT specifies that all validation checks are disabled.

  • VK_VALIDATION_FEATURE_DISABLE_SHADERS_EXT specifies that shader validation, both runtime and standalone, is disabled. This validation occurs inside VkShaderCreateInfoEXT and VkShaderModuleCreateInfo. This feature is enabled by default.

  • VK_VALIDATION_FEATURE_DISABLE_THREAD_SAFETY_EXT specifies that thread safety validation is disabled. This feature is enabled by default.

  • VK_VALIDATION_FEATURE_DISABLE_API_PARAMETERS_EXT specifies that stateless parameter validation is disabled. This feature is enabled by default.

  • VK_VALIDATION_FEATURE_DISABLE_OBJECT_LIFETIMES_EXT specifies that object lifetime validation is disabled. This feature is enabled by default.

  • VK_VALIDATION_FEATURE_DISABLE_CORE_CHECKS_EXT specifies that core validation checks are disabled. This feature is enabled by default. If this feature is disabled, VK_VALIDATION_FEATURE_DISABLE_SHADERS_EXT is implied.

  • VK_VALIDATION_FEATURE_DISABLE_UNIQUE_HANDLES_EXT specifies that protection against duplicate non-dispatchable object handles is disabled. This feature is enabled by default.

  • VK_VALIDATION_FEATURE_DISABLE_SHADER_VALIDATION_CACHE_EXT specifies that there will be no caching of shader validation results and every shader will be validated on every application execution. Shader validation caching is enabled by default.

Note

Disabling checks such as parameter validation and object lifetime validation prevents the reporting of error conditions that can cause other validation checks to behave incorrectly or crash. Some validation checks assume that their inputs are already valid and do not always revalidate them.
Note

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

To create a Vulkan instance with a specific configuration of layer settings, add VkLayerSettingsCreateInfoEXT structures to the pNext chain of the VkInstanceCreateInfo structure, specifying the settings to be configured.

// Provided by VK_EXT_layer_settings
typedef struct VkLayerSettingsCreateInfoEXT {
    VkStructureType             sType;
    const void*                 pNext;
    uint32_t                    settingCount;
    const VkLayerSettingEXT*    pSettings;
} VkLayerSettingsCreateInfoEXT;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • settingCount is the number of settings to configure.

  • pSettings is a pointer to an array of settingCount VkLayerSettingEXT values specifying the settings to be configured.

Valid Usage (Implicit)

  • VUID-VkLayerSettingsCreateInfoEXT-sType-sType
    sType must be VK_STRUCTURE_TYPE_LAYER_SETTINGS_CREATE_INFO_EXT

  • VUID-VkLayerSettingsCreateInfoEXT-pSettings-parameter
    If settingCount is not 0, pSettings must be a valid pointer to an array of settingCount valid VkLayerSettingEXT structures

The values of elements of the VkLayerSettingsCreateInfoEXT::pSettings array, specifying layer settings to be configured, are:

// Provided by VK_EXT_layer_settings
typedef struct VkLayerSettingEXT {
    const char*              pLayerName;
    const char*              pSettingName;
    VkLayerSettingTypeEXT    type;
    uint32_t                 valueCount;
    const void*              pValues;
} VkLayerSettingEXT;

  • pLayerName is a pointer to a null-terminated UTF-8 string naming the layer to configure the setting from.

  • pSettingName is a pointer to a null-terminated UTF-8 string naming the setting to configure. Values of pSettingName that are unknown to the layer are ignored.

  • type is a VkLayerSettingTypeEXT value specifying the type of the pValues values.

  • valueCount is the number of values used to configure the layer setting.

  • pValues is a pointer to an array of valueCount values of the type indicated by type to configure the layer setting.

When multiple VkLayerSettingsCreateInfoEXT structures are chained and the same pSettingName is referenced for the same pLayerName, the value of the first reference of the layer setting is used.

Valid Usage

  • VUID-VkLayerSettingEXT-valueCount-10070
    If valueCount is not 0, pValues must be a valid pointer to an array of valueCount values of the type indicated by type

Valid Usage (Implicit)

  • VUID-VkLayerSettingEXT-pLayerName-parameter
    pLayerName must be a null-terminated UTF-8 string

  • VUID-VkLayerSettingEXT-pSettingName-parameter
    pSettingName must be a null-terminated UTF-8 string

  • VUID-VkLayerSettingEXT-type-parameter
    type must be a valid VkLayerSettingTypeEXT value

Possible values of VkLayerSettingEXT::type, specifying the type of the data returned in VkLayerSettingEXT::pValues, are:

// Provided by VK_EXT_layer_settings
typedef enum VkLayerSettingTypeEXT {
    VK_LAYER_SETTING_TYPE_BOOL32_EXT = 0,
    VK_LAYER_SETTING_TYPE_INT32_EXT = 1,
    VK_LAYER_SETTING_TYPE_INT64_EXT = 2,
    VK_LAYER_SETTING_TYPE_UINT32_EXT = 3,
    VK_LAYER_SETTING_TYPE_UINT64_EXT = 4,
    VK_LAYER_SETTING_TYPE_FLOAT32_EXT = 5,
    VK_LAYER_SETTING_TYPE_FLOAT64_EXT = 6,
    VK_LAYER_SETTING_TYPE_STRING_EXT = 7,
} VkLayerSettingTypeEXT;

  • VK_LAYER_SETTING_TYPE_BOOL32_EXT specifies that the layer setting’s type is VkBool32.

  • VK_LAYER_SETTING_TYPE_INT32_EXT specifies that the layer setting’s type is signed 32-bit integer.

  • VK_LAYER_SETTING_TYPE_INT64_EXT specifies that the layer setting’s type is signed 64-bit integer.

  • VK_LAYER_SETTING_TYPE_UINT32_EXT specifies that the layer setting’s type is unsigned 32-bit integer.

  • VK_LAYER_SETTING_TYPE_UINT64_EXT specifies that the layer setting’s type is unsigned 64-bit integer.

  • VK_LAYER_SETTING_TYPE_FLOAT32_EXT specifies that the layer setting’s type is 32-bit floating-point.

  • VK_LAYER_SETTING_TYPE_FLOAT64_EXT specifies that the layer setting’s type is 64-bit floating-point.

  • VK_LAYER_SETTING_TYPE_STRING_EXT specifies that the layer setting’s type is a pointer to a null-terminated UTF-8 string.

The VkDirectDriverLoadingListLUNARG structure is defined as:

// Provided by VK_LUNARG_direct_driver_loading
typedef struct VkDirectDriverLoadingListLUNARG {
    VkStructureType                           sType;
    const void*                               pNext;
    VkDirectDriverLoadingModeLUNARG           mode;
    uint32_t                                  driverCount;
    const VkDirectDriverLoadingInfoLUNARG*    pDrivers;
} VkDirectDriverLoadingListLUNARG;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • mode controls the mode in which to load the provided drivers.

  • driverCount is the number of driver manifest paths.

  • pDrivers is a pointer to an array of driverCount VkDirectDriverLoadingInfoLUNARG structures.

When creating a Vulkan instance for which additional drivers are to be included, add a VkDirectDriverLoadingListLUNARG structure to the pNext chain of the VkInstanceCreateInfo structure, and include in it the list of VkDirectDriverLoadingInfoLUNARG structures which contain the information necessary to load additional drivers.

Valid Usage (Implicit)

  • VUID-VkDirectDriverLoadingListLUNARG-sType-sType
    sType must be VK_STRUCTURE_TYPE_DIRECT_DRIVER_LOADING_LIST_LUNARG

  • VUID-VkDirectDriverLoadingListLUNARG-mode-parameter
    mode must be a valid VkDirectDriverLoadingModeLUNARG value

  • VUID-VkDirectDriverLoadingListLUNARG-pDrivers-parameter
    pDrivers must be a valid pointer to an array of driverCount valid VkDirectDriverLoadingInfoLUNARG structures

  • VUID-VkDirectDriverLoadingListLUNARG-driverCount-arraylength
    driverCount must be greater than 0

The VkDirectDriverLoadingInfoLUNARG structure is defined as:

// Provided by VK_LUNARG_direct_driver_loading
typedef struct VkDirectDriverLoadingInfoLUNARG {
    VkStructureType                     sType;
    void*                               pNext;
    VkDirectDriverLoadingFlagsLUNARG    flags;
    PFN_vkGetInstanceProcAddrLUNARG     pfnGetInstanceProcAddr;
} VkDirectDriverLoadingInfoLUNARG;
Valid Usage (Implicit)

  • VUID-VkDirectDriverLoadingInfoLUNARG-sType-sType
    sType must be VK_STRUCTURE_TYPE_DIRECT_DRIVER_LOADING_INFO_LUNARG

  • VUID-VkDirectDriverLoadingInfoLUNARG-flags-zerobitmask
    flags must be 0

Possible values of VkDirectDriverLoadingListLUNARG::mode, specifying the mode in which drivers are used, are:

// Provided by VK_LUNARG_direct_driver_loading
typedef enum VkDirectDriverLoadingModeLUNARG {
    VK_DIRECT_DRIVER_LOADING_MODE_EXCLUSIVE_LUNARG = 0,
    VK_DIRECT_DRIVER_LOADING_MODE_INCLUSIVE_LUNARG = 1,
} VkDirectDriverLoadingModeLUNARG;

  • VK_DIRECT_DRIVER_LOADING_MODE_EXCLUSIVE_LUNARG specifies that the provided drivers are used instead of the system-loaded drivers.

  • VK_DIRECT_DRIVER_LOADING_MODE_INCLUSIVE_LUNARG specifies that the provided drivers are used in addition to the system-loaded drivers.

// Provided by VK_LUNARG_direct_driver_loading
typedef VkFlags VkDirectDriverLoadingFlagsLUNARG;

VkDirectDriverLoadingFlagsLUNARG is a bitmask type for setting a mask, but is currently reserved for future use.

The type of PFN_vkGetInstanceProcAddrLUNARG is:

// Provided by VK_LUNARG_direct_driver_loading
typedef PFN_vkVoidFunction (VKAPI_PTR *PFN_vkGetInstanceProcAddrLUNARG)(
    VkInstance instance, const char* pName);

  • instance is a VkInstance handle.

  • pName is the name of a Vulkan command.

This type is compatible with the type of a pointer to the vkGetInstanceProcAddr command, but is used only to specify device driver addresses in VkDirectDriverLoadingInfoLUNARG::pfnGetInstanceProcAddr.

Note

This type exists only because of limitations in the XML schema and processing scripts, and its name may change in the future. Ideally we would use the PFN_vkGetInstanceProcAddr type generated in the vulkan_core.h header.

The VkApplicationInfo structure is defined as:

// Provided by VK_VERSION_1_0
typedef struct VkApplicationInfo {
    VkStructureType    sType;
    const void*        pNext;
    const char*        pApplicationName;
    uint32_t           applicationVersion;
    const char*        pEngineName;
    uint32_t           engineVersion;
    uint32_t           apiVersion;
} VkApplicationInfo;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • pApplicationName is NULL or is a pointer to a null-terminated UTF-8 string containing the name of the application.

  • applicationVersion is an unsigned integer variable containing the developer-supplied version number of the application.

  • pEngineName is NULL or is a pointer to a null-terminated UTF-8 string containing the name of the engine (if any) used to create the application.

  • engineVersion is an unsigned integer variable containing the developer-supplied version number of the engine used to create the application.

  • apiVersion must be the highest version of Vulkan that the application is designed to use, encoded as described in Version Numbers. The patch version number specified in apiVersion is ignored when creating an instance object. The variant version of the instance must match that requested in apiVersion.

Vulkan 1.0 implementations were required to return VK_ERROR_INCOMPATIBLE_DRIVER if apiVersion was larger than 1.0. Implementations that support Vulkan 1.1 or later must not return VK_ERROR_INCOMPATIBLE_DRIVER for any value of apiVersion .

Note

Because Vulkan 1.0 implementations may fail with VK_ERROR_INCOMPATIBLE_DRIVER, applications should determine the version of Vulkan available before calling vkCreateInstance. If the vkGetInstanceProcAddr returns NULL for vkEnumerateInstanceVersion, it is a Vulkan 1.0 implementation. Otherwise, the application can call vkEnumerateInstanceVersion to determine the version of Vulkan.

As long as the instance supports at least Vulkan 1.1, an application can use different versions of Vulkan with an instance than it does with a device or physical device.

Note

The Khronos validation layers will treat apiVersion as the highest API version the application targets, and will validate API usage against the minimum of that version and the implementation version (instance or device, depending on context). If an application tries to use functionality from a greater version than this, a validation error will be triggered.

For example, if the instance supports Vulkan 1.1 and three physical devices support Vulkan 1.0, Vulkan 1.1, and Vulkan 1.2, respectively, and if the application sets apiVersion to 1.2, the application can use the following versions of Vulkan:

  • Vulkan 1.0 can be used with the instance and with all physical devices.

  • Vulkan 1.1 can be used with the instance and with the physical devices that support Vulkan 1.1 and Vulkan 1.2.

  • Vulkan 1.2 can be used with the physical device that supports Vulkan 1.2.

If we modify the above example so that the application sets apiVersion to 1.1, then the application must not use Vulkan 1.2 functionality on the physical device that supports Vulkan 1.2.
Note

Providing a NULL VkInstanceCreateInfo::pApplicationInfo or providing an apiVersion of 0 is equivalent to providing an apiVersion of VK_MAKE_API_VERSION(0,1,0,0).
Valid Usage

  • VUID-VkApplicationInfo-apiVersion-04010
    If apiVersion is not 0, then it must be greater than or equal to VK_API_VERSION_1_0

Valid Usage (Implicit)

  • VUID-VkApplicationInfo-sType-sType
    sType must be VK_STRUCTURE_TYPE_APPLICATION_INFO

  • VUID-VkApplicationInfo-pNext-pNext
    pNext must be NULL

  • VUID-VkApplicationInfo-pApplicationName-parameter
    If pApplicationName is not NULL, pApplicationName must be a null-terminated UTF-8 string

  • VUID-VkApplicationInfo-pEngineName-parameter
    If pEngineName is not NULL, pEngineName must be a null-terminated UTF-8 string

To destroy an instance, call:

// Provided by VK_VERSION_1_0
void vkDestroyInstance(
    VkInstance                                  instance,
    const VkAllocationCallbacks*                pAllocator);

  • instance is the handle of the instance to destroy.

  • pAllocator controls host memory allocation as described in the Memory Allocation chapter.

Valid Usage

  • VUID-vkDestroyInstance-instance-00629
    All child objects created using instance must have been destroyed prior to destroying instance

  • VUID-vkDestroyInstance-instance-00630
    If VkAllocationCallbacks were provided when instance was created, a compatible set of callbacks must be provided here

  • VUID-vkDestroyInstance-instance-00631
    If no VkAllocationCallbacks were provided when instance was created, pAllocator must be NULL

Valid Usage (Implicit)

  • VUID-vkDestroyInstance-instance-parameter
    If instance is not NULL, instance must be a valid VkInstance handle

  • VUID-vkDestroyInstance-pAllocator-parameter
    If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure

Host Synchronization

  • Host access to instance must be externally synchronized

  • Host access to all VkPhysicalDevice objects enumerated from instance must be externally synchronized

5. Devices and Queues

Once Vulkan is initialized, devices and queues are the primary objects used to interact with a Vulkan implementation.

Vulkan separates the concept of physical and logical devices. A physical device usually represents a single complete implementation of Vulkan (excluding instance-level functionality) available to the host, of which there are a finite number. A logical device represents an instance of that implementation with its own state and resources independent of other logical devices.

Physical devices are represented by VkPhysicalDevice handles:

// Provided by VK_VERSION_1_0
VK_DEFINE_HANDLE(VkPhysicalDevice)

5.1. Physical Devices

To retrieve a list of physical device objects representing the physical devices installed in the system, call:

// Provided by VK_VERSION_1_0
VkResult vkEnumeratePhysicalDevices(
    VkInstance                                  instance,
    uint32_t*                                   pPhysicalDeviceCount,
    VkPhysicalDevice*                           pPhysicalDevices);

  • instance is a handle to a Vulkan instance previously created with vkCreateInstance.

  • pPhysicalDeviceCount is a pointer to an integer related to the number of physical devices available or queried, as described below.

  • pPhysicalDevices is either NULL or a pointer to an array of VkPhysicalDevice handles.

If pPhysicalDevices is NULL, then the number of physical devices available is returned in pPhysicalDeviceCount. Otherwise, pPhysicalDeviceCount must point to a variable set by the application to the number of elements in the pPhysicalDevices array, and on return the variable is overwritten with the number of handles actually written to pPhysicalDevices. If pPhysicalDeviceCount is less than the number of physical devices available, at most pPhysicalDeviceCount structures will be written, and VK_INCOMPLETE will be returned instead of VK_SUCCESS, to indicate that not all the available physical devices were returned.

Valid Usage (Implicit)

  • VUID-vkEnumeratePhysicalDevices-instance-parameter
    instance must be a valid VkInstance handle

  • VUID-vkEnumeratePhysicalDevices-pPhysicalDeviceCount-parameter
    pPhysicalDeviceCount must be a valid pointer to a uint32_t value

  • VUID-vkEnumeratePhysicalDevices-pPhysicalDevices-parameter
    If the value referenced by pPhysicalDeviceCount is not 0, and pPhysicalDevices is not NULL, pPhysicalDevices must be a valid pointer to an array of pPhysicalDeviceCount VkPhysicalDevice handles

Return Codes
Success

  • VK_SUCCESS

  • VK_INCOMPLETE

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

  • VK_ERROR_INITIALIZATION_FAILED

To query general properties of physical devices once enumerated, call:

// Provided by VK_VERSION_1_0
void vkGetPhysicalDeviceProperties(
    VkPhysicalDevice                            physicalDevice,
    VkPhysicalDeviceProperties*                 pProperties);

  • physicalDevice is the handle to the physical device whose properties will be queried.

  • pProperties is a pointer to a VkPhysicalDeviceProperties structure in which properties are returned.

Valid Usage (Implicit)

  • VUID-vkGetPhysicalDeviceProperties-physicalDevice-parameter
    physicalDevice must be a valid VkPhysicalDevice handle

  • VUID-vkGetPhysicalDeviceProperties-pProperties-parameter
    pProperties must be a valid pointer to a VkPhysicalDeviceProperties structure

The VkPhysicalDeviceProperties structure is defined as:

// Provided by VK_VERSION_1_0
typedef struct VkPhysicalDeviceProperties {
    uint32_t                            apiVersion;
    uint32_t                            driverVersion;
    uint32_t                            vendorID;
    uint32_t                            deviceID;
    VkPhysicalDeviceType                deviceType;
    char                                deviceName[VK_MAX_PHYSICAL_DEVICE_NAME_SIZE];
    uint8_t                             pipelineCacheUUID[VK_UUID_SIZE];
    VkPhysicalDeviceLimits              limits;
    VkPhysicalDeviceSparseProperties    sparseProperties;
} VkPhysicalDeviceProperties;

  • apiVersion is the version of Vulkan supported by the device, encoded as described in Version Numbers.

  • driverVersion is the vendor-specified version of the driver.

  • vendorID is a unique identifier for the vendor (see below) of the physical device.

  • deviceID is a unique identifier for the physical device among devices available from the vendor.

  • deviceType is a VkPhysicalDeviceType specifying the type of device.

  • deviceName is an array of VK_MAX_PHYSICAL_DEVICE_NAME_SIZE char containing a null-terminated UTF-8 string which is the name of the device.

  • pipelineCacheUUID is an array of VK_UUID_SIZE uint8_t values representing a universally unique identifier for the device.

  • limits is the VkPhysicalDeviceLimits structure specifying device-specific limits of the physical device. See Limits for details.

  • sparseProperties is the VkPhysicalDeviceSparseProperties structure specifying various sparse related properties of the physical device. See Sparse Properties for details.

Note

The value of apiVersion may be different than the version returned by vkEnumerateInstanceVersion; either higher or lower. In such cases, the application must not use functionality that exceeds the version of Vulkan associated with a given object. The pApiVersion parameter returned by vkEnumerateInstanceVersion is the version associated with a VkInstance and its children, except for a VkPhysicalDevice and its children. VkPhysicalDeviceProperties::apiVersion is the version associated with a VkPhysicalDevice and its children.
Note

The encoding of driverVersion is implementation-defined. It may not use the same encoding as apiVersion. Applications should follow information from the vendor on how to extract the version information from driverVersion.

On implementations that claim support for the Roadmap 2022 profile, the major and minor version expressed by apiVersion must be at least Vulkan 1.3.

The vendorID and deviceID fields are provided to allow applications to adapt to device characteristics that are not adequately exposed by other Vulkan queries.

Note

These may include performance profiles, hardware errata, or other characteristics.

The vendor identified by vendorID is the entity responsible for the most salient characteristics of the underlying implementation of the VkPhysicalDevice being queried.

Note

For example, in the case of a discrete GPU implementation, this should be the GPU chipset vendor. In the case of a hardware accelerator integrated into a system-on-chip (SoC), this should be the supplier of the silicon IP used to create the accelerator.

If the vendor has a PCI vendor ID, the low 16 bits of vendorID must contain that PCI vendor ID, and the remaining bits must be set to zero. Otherwise, the value returned must be a valid Khronos vendor ID, obtained as described in the Vulkan Documentation and Extensions: Procedures and Conventions document in the section “Registering a Vendor ID with Khronos”. Khronos vendor IDs are allocated starting at 0x10000, to distinguish them from the PCI vendor ID namespace. Khronos vendor IDs are symbolically defined in the VkVendorId type.

The vendor is also responsible for the value returned in deviceID. If the implementation is driven primarily by a PCI device with a PCI device ID, the low 16 bits of deviceID must contain that PCI device ID, and the remaining bits must be set to zero. Otherwise, the choice of what values to return may be dictated by operating system or platform policies - but should uniquely identify both the device version and any major configuration options (for example, core count in the case of multicore devices).

Note

The same device ID should be used for all physical implementations of that device version and configuration. For example, all uses of a specific silicon IP GPU version and configuration should use the same device ID, even if those uses occur in different SoCs.

Khronos vendor IDs which may be returned in VkPhysicalDeviceProperties::vendorID are:

// Provided by VK_VERSION_1_0
typedef enum VkVendorId {
    VK_VENDOR_ID_KHRONOS = 0x10000,
    VK_VENDOR_ID_VIV = 0x10001,
    VK_VENDOR_ID_VSI = 0x10002,
    VK_VENDOR_ID_KAZAN = 0x10003,
    VK_VENDOR_ID_CODEPLAY = 0x10004,
    VK_VENDOR_ID_MESA = 0x10005,
    VK_VENDOR_ID_POCL = 0x10006,
    VK_VENDOR_ID_MOBILEYE = 0x10007,
} VkVendorId;
Note

Khronos vendor IDs may be allocated by vendors at any time. Only the latest canonical versions of this Specification, of the corresponding vk.xml API Registry, and of the corresponding vulkan_core.h header file must contain all reserved Khronos vendor IDs.

Only Khronos vendor IDs are given symbolic names at present. PCI vendor IDs returned by the implementation can be looked up in the PCI-SIG database.

VK_MAX_PHYSICAL_DEVICE_NAME_SIZE is the length in char values of an array containing a physical device name string, as returned in VkPhysicalDeviceProperties::deviceName.

#define VK_MAX_PHYSICAL_DEVICE_NAME_SIZE  256U

The physical device types which may be returned in VkPhysicalDeviceProperties::deviceType are:

// Provided by VK_VERSION_1_0
typedef enum VkPhysicalDeviceType {
    VK_PHYSICAL_DEVICE_TYPE_OTHER = 0,
    VK_PHYSICAL_DEVICE_TYPE_INTEGRATED_GPU = 1,
    VK_PHYSICAL_DEVICE_TYPE_DISCRETE_GPU = 2,
    VK_PHYSICAL_DEVICE_TYPE_VIRTUAL_GPU = 3,
    VK_PHYSICAL_DEVICE_TYPE_CPU = 4,
} VkPhysicalDeviceType;

  • VK_PHYSICAL_DEVICE_TYPE_OTHER - the device does not match any other available types.

  • VK_PHYSICAL_DEVICE_TYPE_INTEGRATED_GPU - the device is typically one embedded in or tightly coupled with the host.

  • VK_PHYSICAL_DEVICE_TYPE_DISCRETE_GPU - the device is typically a separate processor connected to the host via an interlink.

  • VK_PHYSICAL_DEVICE_TYPE_VIRTUAL_GPU - the device is typically a virtual node in a virtualization environment.

  • VK_PHYSICAL_DEVICE_TYPE_CPU - the device is typically running on the same processors as the host.

The physical device type is advertised for informational purposes only, and does not directly affect the operation of the system. However, the device type may correlate with other advertised properties or capabilities of the system, such as how many memory heaps there are.

To query general properties of physical devices once enumerated, call:

// Provided by VK_VERSION_1_1
void vkGetPhysicalDeviceProperties2(
    VkPhysicalDevice                            physicalDevice,
    VkPhysicalDeviceProperties2*                pProperties);

or the equivalent command

// Provided by VK_KHR_get_physical_device_properties2
void vkGetPhysicalDeviceProperties2KHR(
    VkPhysicalDevice                            physicalDevice,
    VkPhysicalDeviceProperties2*                pProperties);

  • physicalDevice is the handle to the physical device whose properties will be queried.

  • pProperties is a pointer to a VkPhysicalDeviceProperties2 structure in which properties are returned.

Each structure in pProperties and its pNext chain contains members corresponding to implementation-dependent properties, behaviors, or limits. vkGetPhysicalDeviceProperties2 fills in each member to specify the corresponding value for the implementation.

Valid Usage (Implicit)

  • VUID-vkGetPhysicalDeviceProperties2-physicalDevice-parameter
    physicalDevice must be a valid VkPhysicalDevice handle

  • VUID-vkGetPhysicalDeviceProperties2-pProperties-parameter
    pProperties must be a valid pointer to a VkPhysicalDeviceProperties2 structure

The VkPhysicalDeviceProperties2 structure is defined as:

// Provided by VK_VERSION_1_1
typedef struct VkPhysicalDeviceProperties2 {
    VkStructureType               sType;
    void*                         pNext;
    VkPhysicalDeviceProperties    properties;
} VkPhysicalDeviceProperties2;

or the equivalent

// Provided by VK_KHR_get_physical_device_properties2
typedef VkPhysicalDeviceProperties2 VkPhysicalDeviceProperties2KHR;

The pNext chain of this structure is used to extend the structure with properties defined by extensions.

Valid Usage (Implicit)

The VkPhysicalDeviceVulkan11Properties structure is defined as:

// Provided by VK_VERSION_1_2
typedef struct VkPhysicalDeviceVulkan11Properties {
    VkStructureType            sType;
    void*                      pNext;
    uint8_t                    deviceUUID[VK_UUID_SIZE];
    uint8_t                    driverUUID[VK_UUID_SIZE];
    uint8_t                    deviceLUID[VK_LUID_SIZE];
    uint32_t                   deviceNodeMask;
    VkBool32                   deviceLUIDValid;
    uint32_t                   subgroupSize;
    VkShaderStageFlags         subgroupSupportedStages;
    VkSubgroupFeatureFlags     subgroupSupportedOperations;
    VkBool32                   subgroupQuadOperationsInAllStages;
    VkPointClippingBehavior    pointClippingBehavior;
    uint32_t                   maxMultiviewViewCount;
    uint32_t                   maxMultiviewInstanceIndex;
    VkBool32                   protectedNoFault;
    uint32_t                   maxPerSetDescriptors;
    VkDeviceSize               maxMemoryAllocationSize;
} VkPhysicalDeviceVulkan11Properties;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • deviceUUID is an array of VK_UUID_SIZE uint8_t values representing a universally unique identifier for the device.

  • driverUUID is an array of VK_UUID_SIZE uint8_t values representing a universally unique identifier for the driver build in use by the device.

  • deviceLUID is an array of VK_LUID_SIZE uint8_t values representing a locally unique identifier for the device.

  • deviceNodeMask is a uint32_t bitfield identifying the node within a linked device adapter corresponding to the device.

  • deviceLUIDValid is a boolean value that will be VK_TRUE if deviceLUID contains a valid LUID and deviceNodeMask contains a valid node mask, and VK_FALSE if they do not.

  • subgroupSize is the default number of invocations in each subgroup. subgroupSize is at least 1 if any of the physical device’s queues support VK_QUEUE_GRAPHICS_BIT or VK_QUEUE_COMPUTE_BIT. subgroupSize is a power-of-two.

  • subgroupSupportedStages is a bitfield of VkShaderStageFlagBits describing the shader stages that group operations with subgroup scope are supported in. subgroupSupportedStages will have the VK_SHADER_STAGE_COMPUTE_BIT bit set if any of the physical device’s queues support VK_QUEUE_COMPUTE_BIT.

  • subgroupSupportedOperations is a bitmask of VkSubgroupFeatureFlagBits specifying the sets of group operations with subgroup scope supported on this device. subgroupSupportedOperations will have the VK_SUBGROUP_FEATURE_BASIC_BIT bit set if any of the physical device’s queues support VK_QUEUE_GRAPHICS_BIT or VK_QUEUE_COMPUTE_BIT.

  • subgroupQuadOperationsInAllStages is a boolean specifying whether quad group operations are available in all stages, or are restricted to fragment and compute stages.

  • pointClippingBehavior is a VkPointClippingBehavior value specifying the point clipping behavior supported by the implementation.

  • maxMultiviewViewCount is one greater than the maximum view index that can be used in a subpass.

  • maxMultiviewInstanceIndex is the maximum valid value of instance index allowed to be generated by a drawing command recorded within a subpass of a multiview render pass instance.

  • protectedNoFault specifies how an implementation behaves when an application attempts to write to unprotected memory in a protected queue operation, read from protected memory in an unprotected queue operation, or perform a query in a protected queue operation. If this limit is VK_TRUE, such writes will be discarded or have undefined values written, reads and queries will return undefined values. If this limit is VK_FALSE, applications must not perform these operations. See Protected Memory Access Rules for more information.

  • maxPerSetDescriptors is a maximum number of descriptors (summed over all descriptor types) in a single descriptor set that is guaranteed to satisfy any implementation-dependent constraints on the size of a descriptor set itself. Applications can query whether a descriptor set that goes beyond this limit is supported using vkGetDescriptorSetLayoutSupport.

  • maxMemoryAllocationSize is the maximum size of a memory allocation that can be created, even if there is more space available in the heap.

If the VkPhysicalDeviceVulkan11Properties structure is included in the pNext chain of the VkPhysicalDeviceProperties2 structure passed to vkGetPhysicalDeviceProperties2, it is filled in with each corresponding implementation-dependent property.

These properties correspond to Vulkan 1.1 functionality.

The members of VkPhysicalDeviceVulkan11Properties have the same values as the corresponding members of VkPhysicalDeviceIDProperties, VkPhysicalDeviceSubgroupProperties, VkPhysicalDevicePointClippingProperties, VkPhysicalDeviceMultiviewProperties, VkPhysicalDeviceProtectedMemoryProperties, and VkPhysicalDeviceMaintenance3Properties.

Note

The subgroupSupportedStages, subgroupSupportedOperations, and subgroupQuadOperationsInAllStages members of this structure correspond respectively to the VkPhysicalDeviceSubgroupProperties::supportedStages, VkPhysicalDeviceSubgroupProperties::supportedOperations, and VkPhysicalDeviceSubgroupProperties::quadOperationsInAllStages members, but add the subgroup prefix to the member name.
Valid Usage (Implicit)

  • VUID-VkPhysicalDeviceVulkan11Properties-sType-sType
    sType must be VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VULKAN_1_1_PROPERTIES

The VkPhysicalDeviceVulkan12Properties structure is defined as:

// Provided by VK_VERSION_1_2
typedef struct VkPhysicalDeviceVulkan12Properties {
    VkStructureType                      sType;
    void*                                pNext;
    VkDriverId                           driverID;
    char                                 driverName[VK_MAX_DRIVER_NAME_SIZE];
    char                                 driverInfo[VK_MAX_DRIVER_INFO_SIZE];
    VkConformanceVersion                 conformanceVersion;
    VkShaderFloatControlsIndependence    denormBehaviorIndependence;
    VkShaderFloatControlsIndependence    roundingModeIndependence;
    VkBool32                             shaderSignedZeroInfNanPreserveFloat16;
    VkBool32                             shaderSignedZeroInfNanPreserveFloat32;
    VkBool32                             shaderSignedZeroInfNanPreserveFloat64;
    VkBool32                             shaderDenormPreserveFloat16;
    VkBool32                             shaderDenormPreserveFloat32;
    VkBool32                             shaderDenormPreserveFloat64;
    VkBool32                             shaderDenormFlushToZeroFloat16;
    VkBool32                             shaderDenormFlushToZeroFloat32;
    VkBool32                             shaderDenormFlushToZeroFloat64;
    VkBool32                             shaderRoundingModeRTEFloat16;
    VkBool32                             shaderRoundingModeRTEFloat32;
    VkBool32                             shaderRoundingModeRTEFloat64;
    VkBool32                             shaderRoundingModeRTZFloat16;
    VkBool32                             shaderRoundingModeRTZFloat32;
    VkBool32                             shaderRoundingModeRTZFloat64;
    uint32_t                             maxUpdateAfterBindDescriptorsInAllPools;
    VkBool32                             shaderUniformBufferArrayNonUniformIndexingNative;
    VkBool32                             shaderSampledImageArrayNonUniformIndexingNative;
    VkBool32                             shaderStorageBufferArrayNonUniformIndexingNative;
    VkBool32                             shaderStorageImageArrayNonUniformIndexingNative;
    VkBool32                             shaderInputAttachmentArrayNonUniformIndexingNative;
    VkBool32                             robustBufferAccessUpdateAfterBind;
    VkBool32                             quadDivergentImplicitLod;
    uint32_t                             maxPerStageDescriptorUpdateAfterBindSamplers;
    uint32_t                             maxPerStageDescriptorUpdateAfterBindUniformBuffers;
    uint32_t                             maxPerStageDescriptorUpdateAfterBindStorageBuffers;
    uint32_t                             maxPerStageDescriptorUpdateAfterBindSampledImages;
    uint32_t                             maxPerStageDescriptorUpdateAfterBindStorageImages;
    uint32_t                             maxPerStageDescriptorUpdateAfterBindInputAttachments;
    uint32_t                             maxPerStageUpdateAfterBindResources;
    uint32_t                             maxDescriptorSetUpdateAfterBindSamplers;
    uint32_t                             maxDescriptorSetUpdateAfterBindUniformBuffers;
    uint32_t                             maxDescriptorSetUpdateAfterBindUniformBuffersDynamic;
    uint32_t                             maxDescriptorSetUpdateAfterBindStorageBuffers;
    uint32_t                             maxDescriptorSetUpdateAfterBindStorageBuffersDynamic;
    uint32_t                             maxDescriptorSetUpdateAfterBindSampledImages;
    uint32_t                             maxDescriptorSetUpdateAfterBindStorageImages;
    uint32_t                             maxDescriptorSetUpdateAfterBindInputAttachments;
    VkResolveModeFlags                   supportedDepthResolveModes;
    VkResolveModeFlags                   supportedStencilResolveModes;
    VkBool32                             independentResolveNone;
    VkBool32                             independentResolve;
    VkBool32                             filterMinmaxSingleComponentFormats;
    VkBool32                             filterMinmaxImageComponentMapping;
    uint64_t                             maxTimelineSemaphoreValueDifference;
    VkSampleCountFlags                   framebufferIntegerColorSampleCounts;
} VkPhysicalDeviceVulkan12Properties;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • driverID is a unique identifier for the driver of the physical device.

  • driverName is an array of VK_MAX_DRIVER_NAME_SIZE char containing a null-terminated UTF-8 string which is the name of the driver.

  • driverInfo is an array of VK_MAX_DRIVER_INFO_SIZE char containing a null-terminated UTF-8 string with additional information about the driver.

  • conformanceVersion is the latest version of the Vulkan conformance test that the implementor has successfully tested this driver against prior to release (see VkConformanceVersion).

  • denormBehaviorIndependence is a VkShaderFloatControlsIndependence value indicating whether, and how, denorm behavior can be set independently for different bit widths.

  • roundingModeIndependence is a VkShaderFloatControlsIndependence value indicating whether, and how, rounding modes can be set independently for different bit widths.

  • shaderSignedZeroInfNanPreserveFloat16 is a boolean value indicating whether sign of a zero, Nans and can be preserved in 16-bit floating-point computations. It also indicates whether the SignedZeroInfNanPreserve execution mode can be used for 16-bit floating-point types.

  • shaderSignedZeroInfNanPreserveFloat32 is a boolean value indicating whether sign of a zero, Nans and can be preserved in 32-bit floating-point computations. It also indicates whether the SignedZeroInfNanPreserve execution mode can be used for 32-bit floating-point types.

  • shaderSignedZeroInfNanPreserveFloat64 is a boolean value indicating whether sign of a zero, Nans and can be preserved in 64-bit floating-point computations. It also indicates whether the SignedZeroInfNanPreserve execution mode can be used for 64-bit floating-point types.

  • shaderDenormPreserveFloat16 is a boolean value indicating whether denormals can be preserved in 16-bit floating-point computations. It also indicates whether the DenormPreserve execution mode can be used for 16-bit floating-point types.

  • shaderDenormPreserveFloat32 is a boolean value indicating whether denormals can be preserved in 32-bit floating-point computations. It also indicates whether the DenormPreserve execution mode can be used for 32-bit floating-point types.

  • shaderDenormPreserveFloat64 is a boolean value indicating whether denormals can be preserved in 64-bit floating-point computations. It also indicates whether the DenormPreserve execution mode can be used for 64-bit floating-point types.

  • shaderDenormFlushToZeroFloat16 is a boolean value indicating whether denormals can be flushed to zero in 16-bit floating-point computations. It also indicates whether the DenormFlushToZero execution mode can be used for 16-bit floating-point types.

  • shaderDenormFlushToZeroFloat32 is a boolean value indicating whether denormals can be flushed to zero in 32-bit floating-point computations. It also indicates whether the DenormFlushToZero execution mode can be used for 32-bit floating-point types.

  • shaderDenormFlushToZeroFloat64 is a boolean value indicating whether denormals can be flushed to zero in 64-bit floating-point computations. It also indicates whether the DenormFlushToZero execution mode can be used for 64-bit floating-point types.

  • shaderRoundingModeRTEFloat16 is a boolean value indicating whether an implementation supports the round-to-nearest-even rounding mode for 16-bit floating-point arithmetic and conversion instructions. It also indicates whether the RoundingModeRTE execution mode can be used for 16-bit floating-point types.

  • shaderRoundingModeRTEFloat32 is a boolean value indicating whether an implementation supports the round-to-nearest-even rounding mode for 32-bit floating-point arithmetic and conversion instructions. It also indicates whether the RoundingModeRTE execution mode can be used for 32-bit floating-point types.

  • shaderRoundingModeRTEFloat64 is a boolean value indicating whether an implementation supports the round-to-nearest-even rounding mode for 64-bit floating-point arithmetic and conversion instructions. It also indicates whether the RoundingModeRTE execution mode can be used for 64-bit floating-point types.

  • shaderRoundingModeRTZFloat16 is a boolean value indicating whether an implementation supports the round-towards-zero rounding mode for 16-bit floating-point arithmetic and conversion instructions. It also indicates whether the RoundingModeRTZ execution mode can be used for 16-bit floating-point types.

  • shaderRoundingModeRTZFloat32 is a boolean value indicating whether an implementation supports the round-towards-zero rounding mode for 32-bit floating-point arithmetic and conversion instructions. It also indicates whether the RoundingModeRTZ execution mode can be used for 32-bit floating-point types.

  • shaderRoundingModeRTZFloat64 is a boolean value indicating whether an implementation supports the round-towards-zero rounding mode for 64-bit floating-point arithmetic and conversion instructions. It also indicates whether the RoundingModeRTZ execution mode can be used for 64-bit floating-point types.

  • maxUpdateAfterBindDescriptorsInAllPools is the maximum number of descriptors (summed over all descriptor types) that can be created across all pools that are created with the VK_DESCRIPTOR_POOL_CREATE_UPDATE_AFTER_BIND_BIT bit set. Pool creation may fail when this limit is exceeded, or when the space this limit represents is unable to satisfy a pool creation due to fragmentation.

  • shaderUniformBufferArrayNonUniformIndexingNative is a boolean value indicating whether uniform buffer descriptors natively support non-uniform indexing. If this is VK_FALSE, then a single dynamic instance of an instruction that non-uniformly indexes an array of uniform buffers may execute multiple times in order to access all the descriptors.

  • shaderSampledImageArrayNonUniformIndexingNative is a boolean value indicating whether sampler and image descriptors natively support non-uniform indexing. If this is VK_FALSE, then a single dynamic instance of an instruction that non-uniformly indexes an array of samplers or images may execute multiple times in order to access all the descriptors.

  • shaderStorageBufferArrayNonUniformIndexingNative is a boolean value indicating whether storage buffer descriptors natively support non-uniform indexing. If this is VK_FALSE, then a single dynamic instance of an instruction that non-uniformly indexes an array of storage buffers may execute multiple times in order to access all the descriptors.

  • shaderStorageImageArrayNonUniformIndexingNative is a boolean value indicating whether storage image descriptors natively support non-uniform indexing. If this is VK_FALSE, then a single dynamic instance of an instruction that non-uniformly indexes an array of storage images may execute multiple times in order to access all the descriptors.

  • shaderInputAttachmentArrayNonUniformIndexingNative is a boolean value indicating whether input attachment descriptors natively support non-uniform indexing. If this is VK_FALSE, then a single dynamic instance of an instruction that non-uniformly indexes an array of input attachments may execute multiple times in order to access all the descriptors.

  • robustBufferAccessUpdateAfterBind is a boolean value indicating whether robustBufferAccess can be enabled on a device simultaneously with descriptorBindingUniformBufferUpdateAfterBind, descriptorBindingStorageBufferUpdateAfterBind, descriptorBindingUniformTexelBufferUpdateAfterBind, and/or descriptorBindingStorageTexelBufferUpdateAfterBind. If this is VK_FALSE, then either robustBufferAccess must be disabled or all of these update-after-bind features must be disabled.

  • quadDivergentImplicitLod is a boolean value indicating whether implicit LOD calculations for image operations have well-defined results when the image and/or sampler objects used for the instruction are not uniform within a quad. See Derivative Image Operations.

  • maxPerStageDescriptorUpdateAfterBindSamplers is similar to maxPerStageDescriptorSamplers but counts descriptors from descriptor sets created with or without the VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT bit set.

  • maxPerStageDescriptorUpdateAfterBindUniformBuffers is similar to maxPerStageDescriptorUniformBuffers but counts descriptors from descriptor sets created with or without the VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT bit set.

  • maxPerStageDescriptorUpdateAfterBindStorageBuffers is similar to maxPerStageDescriptorStorageBuffers but counts descriptors from descriptor sets created with or without the VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT bit set.

  • maxPerStageDescriptorUpdateAfterBindSampledImages is similar to maxPerStageDescriptorSampledImages but counts descriptors from descriptor sets created with or without the VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT bit set.

  • maxPerStageDescriptorUpdateAfterBindStorageImages is similar to maxPerStageDescriptorStorageImages but counts descriptors from descriptor sets created with or without the VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT bit set.

  • maxPerStageDescriptorUpdateAfterBindInputAttachments is similar to maxPerStageDescriptorInputAttachments but counts descriptors from descriptor sets created with or without the VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT bit set.

  • maxPerStageUpdateAfterBindResources is similar to maxPerStageResources but counts descriptors from descriptor sets created with or without the VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT bit set.

  • maxDescriptorSetUpdateAfterBindSamplers is similar to maxDescriptorSetSamplers but counts descriptors from descriptor sets created with or without the VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT bit set.

  • maxDescriptorSetUpdateAfterBindUniformBuffers is similar to maxDescriptorSetUniformBuffers but counts descriptors from descriptor sets created with or without the VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT bit set.

  • maxDescriptorSetUpdateAfterBindUniformBuffersDynamic is similar to maxDescriptorSetUniformBuffersDynamic but counts descriptors from descriptor sets created with or without the VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT bit set. While an application can allocate dynamic uniform buffer descriptors from a pool created with the VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT, bindings for these descriptors must not be present in any descriptor set layout that includes bindings created with VK_DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BIT.

  • maxDescriptorSetUpdateAfterBindStorageBuffers is similar to maxDescriptorSetStorageBuffers but counts descriptors from descriptor sets created with or without the VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT bit set.

  • maxDescriptorSetUpdateAfterBindStorageBuffersDynamic is similar to maxDescriptorSetStorageBuffersDynamic but counts descriptors from descriptor sets created with or without the VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT bit set. While an application can allocate dynamic storage buffer descriptors from a pool created with the VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT, bindings for these descriptors must not be present in any descriptor set layout that includes bindings created with VK_DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BIT.

  • maxDescriptorSetUpdateAfterBindSampledImages is similar to maxDescriptorSetSampledImages but counts descriptors from descriptor sets created with or without the VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT bit set.

  • maxDescriptorSetUpdateAfterBindStorageImages is similar to maxDescriptorSetStorageImages but counts descriptors from descriptor sets created with or without the VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT bit set.

  • maxDescriptorSetUpdateAfterBindInputAttachments is similar to maxDescriptorSetInputAttachments but counts descriptors from descriptor sets created with or without the VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT bit set.

  • supportedDepthResolveModes is a bitmask of VkResolveModeFlagBits indicating the set of supported depth resolve modes. VK_RESOLVE_MODE_SAMPLE_ZERO_BIT must be included in the set but implementations may support additional modes.

  • supportedStencilResolveModes is a bitmask of VkResolveModeFlagBits indicating the set of supported stencil resolve modes. VK_RESOLVE_MODE_SAMPLE_ZERO_BIT must be included in the set but implementations may support additional modes. VK_RESOLVE_MODE_AVERAGE_BIT must not be included in the set.

  • independentResolveNone is VK_TRUE if the implementation supports setting the depth and stencil resolve modes to different values when one of those modes is VK_RESOLVE_MODE_NONE. Otherwise the implementation only supports setting both modes to the same value.

  • independentResolve is VK_TRUE if the implementation supports all combinations of the supported depth and stencil resolve modes, including setting either depth or stencil resolve mode to VK_RESOLVE_MODE_NONE. An implementation that supports independentResolve must also support independentResolveNone.

  • filterMinmaxSingleComponentFormats is a boolean value indicating whether a minimum set of required formats support min/max filtering.

  • filterMinmaxImageComponentMapping is a boolean value indicating whether the implementation supports non-identity component mapping of the image when doing min/max filtering.

  • maxTimelineSemaphoreValueDifference indicates the maximum difference allowed by the implementation between the current value of a timeline semaphore and any pending signal or wait operations.

  • framebufferIntegerColorSampleCounts is a bitmask of VkSampleCountFlagBits indicating the color sample counts that are supported for all framebuffer color attachments with integer formats.

If the VkPhysicalDeviceVulkan12Properties structure is included in the pNext chain of the VkPhysicalDeviceProperties2 structure passed to vkGetPhysicalDeviceProperties2, it is filled in with each corresponding implementation-dependent property.

These properties correspond to Vulkan 1.2 functionality.

The members of VkPhysicalDeviceVulkan12Properties must have the same values as the corresponding members of VkPhysicalDeviceDriverProperties, VkPhysicalDeviceFloatControlsProperties, VkPhysicalDeviceDescriptorIndexingProperties, VkPhysicalDeviceDepthStencilResolveProperties, VkPhysicalDeviceSamplerFilterMinmaxProperties, and VkPhysicalDeviceTimelineSemaphoreProperties.

Valid Usage (Implicit)

  • VUID-VkPhysicalDeviceVulkan12Properties-sType-sType
    sType must be VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VULKAN_1_2_PROPERTIES

The VkPhysicalDeviceVulkan13Properties structure is defined as:

// Provided by VK_VERSION_1_3
typedef struct VkPhysicalDeviceVulkan13Properties {
    VkStructureType       sType;
    void*                 pNext;
    uint32_t              minSubgroupSize;
    uint32_t              maxSubgroupSize;
    uint32_t              maxComputeWorkgroupSubgroups;
    VkShaderStageFlags    requiredSubgroupSizeStages;
    uint32_t              maxInlineUniformBlockSize;
    uint32_t              maxPerStageDescriptorInlineUniformBlocks;
    uint32_t              maxPerStageDescriptorUpdateAfterBindInlineUniformBlocks;
    uint32_t              maxDescriptorSetInlineUniformBlocks;
    uint32_t              maxDescriptorSetUpdateAfterBindInlineUniformBlocks;
    uint32_t              maxInlineUniformTotalSize;
    VkBool32              integerDotProduct8BitUnsignedAccelerated;
    VkBool32              integerDotProduct8BitSignedAccelerated;
    VkBool32              integerDotProduct8BitMixedSignednessAccelerated;
    VkBool32              integerDotProduct4x8BitPackedUnsignedAccelerated;
    VkBool32              integerDotProduct4x8BitPackedSignedAccelerated;
    VkBool32              integerDotProduct4x8BitPackedMixedSignednessAccelerated;
    VkBool32              integerDotProduct16BitUnsignedAccelerated;
    VkBool32              integerDotProduct16BitSignedAccelerated;
    VkBool32              integerDotProduct16BitMixedSignednessAccelerated;
    VkBool32              integerDotProduct32BitUnsignedAccelerated;
    VkBool32              integerDotProduct32BitSignedAccelerated;
    VkBool32              integerDotProduct32BitMixedSignednessAccelerated;
    VkBool32              integerDotProduct64BitUnsignedAccelerated;
    VkBool32              integerDotProduct64BitSignedAccelerated;
    VkBool32              integerDotProduct64BitMixedSignednessAccelerated;
    VkBool32              integerDotProductAccumulatingSaturating8BitUnsignedAccelerated;
    VkBool32              integerDotProductAccumulatingSaturating8BitSignedAccelerated;
    VkBool32              integerDotProductAccumulatingSaturating8BitMixedSignednessAccelerated;
    VkBool32              integerDotProductAccumulatingSaturating4x8BitPackedUnsignedAccelerated;
    VkBool32              integerDotProductAccumulatingSaturating4x8BitPackedSignedAccelerated;
    VkBool32              integerDotProductAccumulatingSaturating4x8BitPackedMixedSignednessAccelerated;
    VkBool32              integerDotProductAccumulatingSaturating16BitUnsignedAccelerated;
    VkBool32              integerDotProductAccumulatingSaturating16BitSignedAccelerated;
    VkBool32              integerDotProductAccumulatingSaturating16BitMixedSignednessAccelerated;
    VkBool32              integerDotProductAccumulatingSaturating32BitUnsignedAccelerated;
    VkBool32              integerDotProductAccumulatingSaturating32BitSignedAccelerated;
    VkBool32              integerDotProductAccumulatingSaturating32BitMixedSignednessAccelerated;
    VkBool32              integerDotProductAccumulatingSaturating64BitUnsignedAccelerated;
    VkBool32              integerDotProductAccumulatingSaturating64BitSignedAccelerated;
    VkBool32              integerDotProductAccumulatingSaturating64BitMixedSignednessAccelerated;
    VkDeviceSize          storageTexelBufferOffsetAlignmentBytes;
    VkBool32              storageTexelBufferOffsetSingleTexelAlignment;
    VkDeviceSize          uniformTexelBufferOffsetAlignmentBytes;
    VkBool32              uniformTexelBufferOffsetSingleTexelAlignment;
    VkDeviceSize          maxBufferSize;
} VkPhysicalDeviceVulkan13Properties;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • minSubgroupSize is the minimum subgroup size supported by this device. minSubgroupSize is at least one if any of the physical device’s queues support VK_QUEUE_GRAPHICS_BIT or VK_QUEUE_COMPUTE_BIT. minSubgroupSize is a power-of-two. minSubgroupSize is less than or equal to maxSubgroupSize. minSubgroupSize is less than or equal to subgroupSize.

  • maxSubgroupSize is the maximum subgroup size supported by this device. maxSubgroupSize is at least one if any of the physical device’s queues support VK_QUEUE_GRAPHICS_BIT or VK_QUEUE_COMPUTE_BIT. maxSubgroupSize is a power-of-two. maxSubgroupSize is greater than or equal to minSubgroupSize. maxSubgroupSize is greater than or equal to subgroupSize.

  • maxComputeWorkgroupSubgroups is the maximum number of subgroups supported by the implementation within a workgroup.

  • requiredSubgroupSizeStages is a bitfield of what shader stages support having a required subgroup size specified.

  • maxInlineUniformBlockSize is the maximum size in bytes of an inline uniform block binding.

  • maxPerStageDescriptorInlineUniformBlocks is the maximum number of inline uniform block bindings that can be accessible to a single shader stage in a pipeline layout. Descriptor bindings with a descriptor type of VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK count against this limit. Only descriptor bindings in descriptor set layouts created without the VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT bit set count against this limit.

  • maxPerStageDescriptorUpdateAfterBindInlineUniformBlocks is similar to maxPerStageDescriptorInlineUniformBlocks but counts descriptor bindings from descriptor sets created with or without the VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT bit set.

  • maxDescriptorSetInlineUniformBlocks is the maximum number of inline uniform block bindings that can be included in descriptor bindings in a pipeline layout across all pipeline shader stages and descriptor set numbers. Descriptor bindings with a descriptor type of VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK count against this limit. Only descriptor bindings in descriptor set layouts created without the VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT bit set count against this limit.

  • maxDescriptorSetUpdateAfterBindInlineUniformBlocks is similar to maxDescriptorSetInlineUniformBlocks but counts descriptor bindings from descriptor sets created with or without the VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT bit set.

  • maxInlineUniformTotalSize is the maximum total size in bytes of all inline uniform block bindings, across all pipeline shader stages and descriptor set numbers, that can be included in a pipeline layout. Descriptor bindings with a descriptor type of VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK count against this limit.

  • integerDotProduct8BitUnsignedAccelerated is a boolean that will be VK_TRUE if the support for 8-bit unsigned dot product operations using the OpUDotKHR SPIR-V instruction is accelerated as defined below.

  • integerDotProduct8BitSignedAccelerated is a boolean that will be VK_TRUE if the support for 8-bit signed dot product operations using the OpSDotKHR SPIR-V instruction is accelerated as defined below.

  • integerDotProduct8BitMixedSignednessAccelerated is a boolean that will be VK_TRUE if the support for 8-bit mixed signedness dot product operations using the OpSUDotKHR SPIR-V instruction is accelerated as defined below.

  • integerDotProduct4x8BitPackedUnsignedAccelerated is a boolean that will be VK_TRUE if the support for 8-bit unsigned dot product operations from operands packed into 32-bit integers using the OpUDotKHR SPIR-V instruction is accelerated as defined below.

  • integerDotProduct4x8BitPackedSignedAccelerated is a boolean that will be VK_TRUE if the support for 8-bit signed dot product operations from operands packed into 32-bit integers using the OpSDotKHR SPIR-V instruction is accelerated as defined below.

  • integerDotProduct4x8BitPackedMixedSignednessAccelerated is a boolean that will be VK_TRUE if the support for 8-bit mixed signedness dot product operations from operands packed into 32-bit integers using the OpSUDotKHR SPIR-V instruction is accelerated as defined below.

  • integerDotProduct16BitUnsignedAccelerated is a boolean that will be VK_TRUE if the support for 16-bit unsigned dot product operations using the OpUDotKHR SPIR-V instruction is accelerated as defined below.

  • integerDotProduct16BitSignedAccelerated is a boolean that will be VK_TRUE if the support for 16-bit signed dot product operations using the OpSDotKHR SPIR-V instruction is accelerated as defined below.

  • integerDotProduct16BitMixedSignednessAccelerated is a boolean that will be VK_TRUE if the support for 16-bit mixed signedness dot product operations using the OpSUDotKHR SPIR-V instruction is accelerated as defined below.

  • integerDotProduct32BitUnsignedAccelerated is a boolean that will be VK_TRUE if the support for 32-bit unsigned dot product operations using the OpUDotKHR SPIR-V instruction is accelerated as defined below.

  • integerDotProduct32BitSignedAccelerated is a boolean that will be VK_TRUE if the support for 32-bit signed dot product operations using the OpSDotKHR SPIR-V instruction is accelerated as defined below.

  • integerDotProduct32BitMixedSignednessAccelerated is a boolean that will be VK_TRUE if the support for 32-bit mixed signedness dot product operations using the OpSUDotKHR SPIR-V instruction is accelerated as defined below.

  • integerDotProduct64BitUnsignedAccelerated is a boolean that will be VK_TRUE if the support for 64-bit unsigned dot product operations using the OpUDotKHR SPIR-V instruction is accelerated as defined below.

  • integerDotProduct64BitSignedAccelerated is a boolean that will be VK_TRUE if the support for 64-bit signed dot product operations using the OpSDotKHR SPIR-V instruction is accelerated as defined below.

  • integerDotProduct64BitMixedSignednessAccelerated is a boolean that will be VK_TRUE if the support for 64-bit mixed signedness dot product operations using the OpSUDotKHR SPIR-V instruction is accelerated as defined below.

  • integerDotProductAccumulatingSaturating8BitUnsignedAccelerated is a boolean that will be VK_TRUE if the support for 8-bit unsigned accumulating saturating dot product operations using the OpUDotAccSatKHR SPIR-V instruction is accelerated as defined below.

  • integerDotProductAccumulatingSaturating8BitSignedAccelerated is a boolean that will be VK_TRUE if the support for 8-bit signed accumulating saturating dot product operations using the OpSDotAccSatKHR SPIR-V instruction is accelerated as defined below.

  • integerDotProductAccumulatingSaturating8BitMixedSignednessAccelerated is a boolean that will be VK_TRUE if the support for 8-bit mixed signedness accumulating saturating dot product operations using the OpSUDotAccSatKHR SPIR-V instruction is accelerated as defined below.

  • integerDotProductAccumulatingSaturating4x8BitPackedUnsignedAccelerated is a boolean that will be VK_TRUE if the support for 8-bit unsigned accumulating saturating dot product operations from operands packed into 32-bit integers using the OpUDotAccSatKHR SPIR-V instruction is accelerated as defined below.

  • integerDotProductAccumulatingSaturating4x8BitPackedSignedAccelerated is a boolean that will be VK_TRUE if the support for 8-bit signed accumulating saturating dot product operations from operands packed into 32-bit integers using the OpSDotAccSatKHR SPIR-V instruction is accelerated as defined below.

  • integerDotProductAccumulatingSaturating4x8BitPackedMixedSignednessAccelerated is a boolean that will be VK_TRUE if the support for 8-bit mixed signedness accumulating saturating dot product operations from operands packed into 32-bit integers using the OpSUDotAccSatKHR SPIR-V instruction is accelerated as defined below.

  • integerDotProductAccumulatingSaturating16BitUnsignedAccelerated is a boolean that will be VK_TRUE if the support for 16-bit unsigned accumulating saturating dot product operations using the OpUDotAccSatKHR SPIR-V instruction is accelerated as defined below.

  • integerDotProductAccumulatingSaturating16BitSignedAccelerated is a boolean that will be VK_TRUE if the support for 16-bit signed accumulating saturating dot product operations using the OpSDotAccSatKHR SPIR-V instruction is accelerated as defined below.

  • integerDotProductAccumulatingSaturating16BitMixedSignednessAccelerated is a boolean that will be VK_TRUE if the support for 16-bit mixed signedness accumulating saturating dot product operations using the OpSUDotAccSatKHR SPIR-V instruction is accelerated as defined below.

  • integerDotProductAccumulatingSaturating32BitUnsignedAccelerated is a boolean that will be VK_TRUE if the support for 32-bit unsigned accumulating saturating dot product operations using the OpUDotAccSatKHR SPIR-V instruction is accelerated as defined below.

  • integerDotProductAccumulatingSaturating32BitSignedAccelerated is a boolean that will be VK_TRUE if the support for 32-bit signed accumulating saturating dot product operations using the OpSDotAccSatKHR SPIR-V instruction is accelerated as defined below.

  • integerDotProductAccumulatingSaturating32BitMixedSignednessAccelerated is a boolean that will be VK_TRUE if the support for 32-bit mixed signedness accumulating saturating dot product operations using the OpSUDotAccSatKHR SPIR-V instruction is accelerated as defined below.

  • integerDotProductAccumulatingSaturating64BitUnsignedAccelerated is a boolean that will be VK_TRUE if the support for 64-bit unsigned accumulating saturating dot product operations using the OpUDotAccSatKHR SPIR-V instruction is accelerated as defined below.

  • integerDotProductAccumulatingSaturating64BitSignedAccelerated is a boolean that will be VK_TRUE if the support for 64-bit signed accumulating saturating dot product operations using the OpSDotAccSatKHR SPIR-V instruction is accelerated as defined below.

  • integerDotProductAccumulatingSaturating64BitMixedSignednessAccelerated is a boolean that will be VK_TRUE if the support for 64-bit mixed signedness accumulating saturating dot product operations using the OpSUDotAccSatKHR SPIR-V instruction is accelerated as defined below.

  • storageTexelBufferOffsetAlignmentBytes is a byte alignment that is sufficient for a storage texel buffer of any format. The value must be a power of two.

  • storageTexelBufferOffsetSingleTexelAlignment indicates whether single texel alignment is sufficient for a storage texel buffer of any format.

  • uniformTexelBufferOffsetAlignmentBytes is a byte alignment that is sufficient for a uniform texel buffer of any format. The value must be a power of two.

  • uniformTexelBufferOffsetSingleTexelAlignment indicates whether single texel alignment is sufficient for a uniform texel buffer of any format.

  • maxBufferSize is the maximum size VkBuffer that can be created.

If the VkPhysicalDeviceVulkan13Properties structure is included in the pNext chain of the VkPhysicalDeviceProperties2 structure passed to vkGetPhysicalDeviceProperties2, it is filled in with each corresponding implementation-dependent property.

These properties correspond to Vulkan 1.3 functionality.

The members of VkPhysicalDeviceVulkan13Properties must have the same values as the corresponding members of VkPhysicalDeviceInlineUniformBlockProperties and VkPhysicalDeviceSubgroupSizeControlProperties.

Valid Usage (Implicit)

  • VUID-VkPhysicalDeviceVulkan13Properties-sType-sType
    sType must be VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VULKAN_1_3_PROPERTIES

The VkPhysicalDeviceIDProperties structure is defined as:

// Provided by VK_VERSION_1_1
typedef struct VkPhysicalDeviceIDProperties {
    VkStructureType    sType;
    void*              pNext;
    uint8_t            deviceUUID[VK_UUID_SIZE];
    uint8_t            driverUUID[VK_UUID_SIZE];
    uint8_t            deviceLUID[VK_LUID_SIZE];
    uint32_t           deviceNodeMask;
    VkBool32           deviceLUIDValid;
} VkPhysicalDeviceIDProperties;

or the equivalent

// Provided by VK_KHR_external_fence_capabilities, VK_KHR_external_memory_capabilities, VK_KHR_external_semaphore_capabilities
typedef VkPhysicalDeviceIDProperties VkPhysicalDeviceIDPropertiesKHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • deviceUUID is an array of VK_UUID_SIZE uint8_t values representing a universally unique identifier for the device.

  • driverUUID is an array of VK_UUID_SIZE uint8_t values representing a universally unique identifier for the driver build in use by the device.

  • deviceLUID is an array of VK_LUID_SIZE uint8_t values representing a locally unique identifier for the device.

  • deviceNodeMask is a uint32_t bitfield identifying the node within a linked device adapter corresponding to the device.

  • deviceLUIDValid is a boolean value that will be VK_TRUE if deviceLUID contains a valid LUID and deviceNodeMask contains a valid node mask, and VK_FALSE if they do not.

If the VkPhysicalDeviceIDProperties structure is included in the pNext chain of the VkPhysicalDeviceProperties2 structure passed to vkGetPhysicalDeviceProperties2, it is filled in with each corresponding implementation-dependent property.

deviceUUID must be immutable for a given device across instances, processes, driver APIs, driver versions, and system reboots.

Applications can compare the driverUUID value across instance and process boundaries, and can make similar queries in external APIs to determine whether they are capable of sharing memory objects and resources using them with the device.

deviceUUID and/or driverUUID must be used to determine whether a particular external object can be shared between driver components, where such a restriction exists as defined in the compatibility table for the particular object type:

If deviceLUIDValid is VK_FALSE, the values of deviceLUID and deviceNodeMask are undefined. If deviceLUIDValid is VK_TRUE and Vulkan is running on the Windows operating system, the contents of deviceLUID can be cast to an LUID object and must be equal to the locally unique identifier of a IDXGIAdapter1 object that corresponds to physicalDevice. If deviceLUIDValid is VK_TRUE, deviceNodeMask must contain exactly one bit. If Vulkan is running on an operating system that supports the Direct3D 12 API and physicalDevice corresponds to an individual device in a linked device adapter, deviceNodeMask identifies the Direct3D 12 node corresponding to physicalDevice. Otherwise, deviceNodeMask must be 1.

Note

Although they have identical descriptions, VkPhysicalDeviceIDProperties::deviceUUID may differ from VkPhysicalDeviceProperties2::pipelineCacheUUID. The former is intended to identify and correlate devices across API and driver boundaries, while the latter is used to identify a compatible device and driver combination to use when serializing and de-serializing pipeline state.

Implementations should return deviceUUID values which are likely to be unique even in the presence of multiple Vulkan implementations (such as a GPU driver and a software renderer; two drivers for different GPUs; or the same Vulkan driver running on two logically different devices).

Khronos' conformance testing is unable to guarantee that deviceUUID values are actually unique, so implementors should make their own best efforts to ensure this. In particular, hard-coded deviceUUID values, especially all-0 bits, should never be used.

A combination of values unique to the vendor, the driver, and the hardware environment can be used to provide a deviceUUID which is unique to a high degree of certainty. Some possible inputs to such a computation are:

  • Information reported by vkGetPhysicalDeviceProperties

  • PCI device ID (if defined)

  • PCI bus ID, or similar system configuration information.

  • Driver binary checksums.
Note

While VkPhysicalDeviceIDProperties::deviceUUID is specified to remain consistent across driver versions and system reboots, it is not intended to be usable as a serializable persistent identifier for a device. It may change when a device is physically added to, removed from, or moved to a different connector in a system while that system is powered down. Further, there is no reasonable way to verify with conformance testing that a given device retains the same UUID in a given system across all driver versions supported in that system. While implementations should make every effort to report consistent device UUIDs across driver versions, applications should avoid relying on the persistence of this value for uses other than identifying compatible devices for external object sharing purposes.
Valid Usage (Implicit)

  • VUID-VkPhysicalDeviceIDProperties-sType-sType
    sType must be VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_ID_PROPERTIES

VK_UUID_SIZE is the length in uint8_t values of an array containing a universally unique device or driver build identifier, as returned in VkPhysicalDeviceIDProperties::deviceUUID and VkPhysicalDeviceIDProperties::driverUUID.

#define VK_UUID_SIZE                      16U

VK_LUID_SIZE is the length in uint8_t values of an array containing a locally unique device identifier, as returned in VkPhysicalDeviceIDProperties::deviceLUID.

#define VK_LUID_SIZE                      8U

or the equivalent

#define VK_LUID_SIZE_KHR                  VK_LUID_SIZE

The VkPhysicalDeviceDriverProperties structure is defined as:

// Provided by VK_VERSION_1_2
typedef struct VkPhysicalDeviceDriverProperties {
    VkStructureType         sType;
    void*                   pNext;
    VkDriverId              driverID;
    char                    driverName[VK_MAX_DRIVER_NAME_SIZE];
    char                    driverInfo[VK_MAX_DRIVER_INFO_SIZE];
    VkConformanceVersion    conformanceVersion;
} VkPhysicalDeviceDriverProperties;

or the equivalent

// Provided by VK_KHR_driver_properties
typedef VkPhysicalDeviceDriverProperties VkPhysicalDeviceDriverPropertiesKHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • driverID is a unique identifier for the driver of the physical device.

  • driverName is an array of VK_MAX_DRIVER_NAME_SIZE char containing a null-terminated UTF-8 string which is the name of the driver.

  • driverInfo is an array of VK_MAX_DRIVER_INFO_SIZE char containing a null-terminated UTF-8 string with additional information about the driver.

  • conformanceVersion is the latest version of the Vulkan conformance test that the implementor has successfully tested this driver against prior to release (see VkConformanceVersion).

If the VkPhysicalDeviceDriverProperties structure is included in the pNext chain of the VkPhysicalDeviceProperties2 structure passed to vkGetPhysicalDeviceProperties2, it is filled in with each corresponding implementation-dependent property.

These are properties of the driver corresponding to a physical device.

driverID must be immutable for a given driver across instances, processes, driver versions, and system reboots.

Valid Usage (Implicit)

  • VUID-VkPhysicalDeviceDriverProperties-sType-sType
    sType must be VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DRIVER_PROPERTIES

Khronos driver IDs which may be returned in VkPhysicalDeviceDriverProperties::driverID are:

// Provided by VK_VERSION_1_2
typedef enum VkDriverId {
    VK_DRIVER_ID_AMD_PROPRIETARY = 1,
    VK_DRIVER_ID_AMD_OPEN_SOURCE = 2,
    VK_DRIVER_ID_MESA_RADV = 3,
    VK_DRIVER_ID_NVIDIA_PROPRIETARY = 4,
    VK_DRIVER_ID_INTEL_PROPRIETARY_WINDOWS = 5,
    VK_DRIVER_ID_INTEL_OPEN_SOURCE_MESA = 6,
    VK_DRIVER_ID_IMAGINATION_PROPRIETARY = 7,
    VK_DRIVER_ID_QUALCOMM_PROPRIETARY = 8,
    VK_DRIVER_ID_ARM_PROPRIETARY = 9,
    VK_DRIVER_ID_GOOGLE_SWIFTSHADER = 10,
    VK_DRIVER_ID_GGP_PROPRIETARY = 11,
    VK_DRIVER_ID_BROADCOM_PROPRIETARY = 12,
    VK_DRIVER_ID_MESA_LLVMPIPE = 13,
    VK_DRIVER_ID_MOLTENVK = 14,
    VK_DRIVER_ID_COREAVI_PROPRIETARY = 15,
    VK_DRIVER_ID_JUICE_PROPRIETARY = 16,
    VK_DRIVER_ID_VERISILICON_PROPRIETARY = 17,
    VK_DRIVER_ID_MESA_TURNIP = 18,
    VK_DRIVER_ID_MESA_V3DV = 19,
    VK_DRIVER_ID_MESA_PANVK = 20,
    VK_DRIVER_ID_SAMSUNG_PROPRIETARY = 21,
    VK_DRIVER_ID_MESA_VENUS = 22,
    VK_DRIVER_ID_MESA_DOZEN = 23,
    VK_DRIVER_ID_MESA_NVK = 24,
    VK_DRIVER_ID_IMAGINATION_OPEN_SOURCE_MESA = 25,
    VK_DRIVER_ID_MESA_HONEYKRISP = 26,
    VK_DRIVER_ID_RESERVED_27 = 27,
  // Provided by VK_KHR_driver_properties
    VK_DRIVER_ID_AMD_PROPRIETARY_KHR = VK_DRIVER_ID_AMD_PROPRIETARY,
  // Provided by VK_KHR_driver_properties
    VK_DRIVER_ID_AMD_OPEN_SOURCE_KHR = VK_DRIVER_ID_AMD_OPEN_SOURCE,
  // Provided by VK_KHR_driver_properties
    VK_DRIVER_ID_MESA_RADV_KHR = VK_DRIVER_ID_MESA_RADV,
  // Provided by VK_KHR_driver_properties
    VK_DRIVER_ID_NVIDIA_PROPRIETARY_KHR = VK_DRIVER_ID_NVIDIA_PROPRIETARY,
  // Provided by VK_KHR_driver_properties
    VK_DRIVER_ID_INTEL_PROPRIETARY_WINDOWS_KHR = VK_DRIVER_ID_INTEL_PROPRIETARY_WINDOWS,
  // Provided by VK_KHR_driver_properties
    VK_DRIVER_ID_INTEL_OPEN_SOURCE_MESA_KHR = VK_DRIVER_ID_INTEL_OPEN_SOURCE_MESA,
  // Provided by VK_KHR_driver_properties
    VK_DRIVER_ID_IMAGINATION_PROPRIETARY_KHR = VK_DRIVER_ID_IMAGINATION_PROPRIETARY,
  // Provided by VK_KHR_driver_properties
    VK_DRIVER_ID_QUALCOMM_PROPRIETARY_KHR = VK_DRIVER_ID_QUALCOMM_PROPRIETARY,
  // Provided by VK_KHR_driver_properties
    VK_DRIVER_ID_ARM_PROPRIETARY_KHR = VK_DRIVER_ID_ARM_PROPRIETARY,
  // Provided by VK_KHR_driver_properties
    VK_DRIVER_ID_GOOGLE_SWIFTSHADER_KHR = VK_DRIVER_ID_GOOGLE_SWIFTSHADER,
  // Provided by VK_KHR_driver_properties
    VK_DRIVER_ID_GGP_PROPRIETARY_KHR = VK_DRIVER_ID_GGP_PROPRIETARY,
  // Provided by VK_KHR_driver_properties
    VK_DRIVER_ID_BROADCOM_PROPRIETARY_KHR = VK_DRIVER_ID_BROADCOM_PROPRIETARY,
} VkDriverId;

or the equivalent

// Provided by VK_KHR_driver_properties
typedef VkDriverId VkDriverIdKHR;
Note

Khronos driver IDs may be allocated by vendors at any time. There may be multiple driver IDs for the same vendor, representing different drivers (for e.g. different platforms, proprietary or open source, etc.). Only the latest canonical versions of this Specification, of the corresponding vk.xml API Registry, and of the corresponding vulkan_core.h header file must contain all reserved Khronos driver IDs.

Only driver IDs registered with Khronos are given symbolic names. There may be unregistered driver IDs returned.

VK_MAX_DRIVER_NAME_SIZE is the length in char values of an array containing a driver name string, as returned in VkPhysicalDeviceDriverProperties::driverName.

#define VK_MAX_DRIVER_NAME_SIZE           256U

or the equivalent

#define VK_MAX_DRIVER_NAME_SIZE_KHR       VK_MAX_DRIVER_NAME_SIZE

VK_MAX_DRIVER_INFO_SIZE is the length in char values of an array containing a driver information string, as returned in VkPhysicalDeviceDriverProperties::driverInfo.

#define VK_MAX_DRIVER_INFO_SIZE           256U

or the equivalent

#define VK_MAX_DRIVER_INFO_SIZE_KHR       VK_MAX_DRIVER_INFO_SIZE

The conformance test suite version an implementation is compliant with is described with the VkConformanceVersion structure:

// Provided by VK_VERSION_1_2
typedef struct VkConformanceVersion {
    uint8_t    major;
    uint8_t    minor;
    uint8_t    subminor;
    uint8_t    patch;
} VkConformanceVersion;

or the equivalent

// Provided by VK_KHR_driver_properties
typedef VkConformanceVersion VkConformanceVersionKHR;

  • major is the major version number of the conformance test suite.

  • minor is the minor version number of the conformance test suite.

  • subminor is the subminor version number of the conformance test suite.

  • patch is the patch version number of the conformance test suite.

The VkPhysicalDevicePCIBusInfoPropertiesEXT structure is defined as:

// Provided by VK_EXT_pci_bus_info
typedef struct VkPhysicalDevicePCIBusInfoPropertiesEXT {
    VkStructureType    sType;
    void*              pNext;
    uint32_t           pciDomain;
    uint32_t           pciBus;
    uint32_t           pciDevice;
    uint32_t           pciFunction;
} VkPhysicalDevicePCIBusInfoPropertiesEXT;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • pciDomain is the PCI bus domain.

  • pciBus is the PCI bus identifier.

  • pciDevice is the PCI device identifier.

  • pciFunction is the PCI device function identifier.

If the VkPhysicalDevicePCIBusInfoPropertiesEXT structure is included in the pNext chain of the VkPhysicalDeviceProperties2 structure passed to vkGetPhysicalDeviceProperties2, it is filled in with each corresponding implementation-dependent property.

These are properties of the PCI bus information of a physical device.

Valid Usage (Implicit)

  • VUID-VkPhysicalDevicePCIBusInfoPropertiesEXT-sType-sType
    sType must be VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PCI_BUS_INFO_PROPERTIES_EXT

The VkPhysicalDeviceDrmPropertiesEXT structure is defined as:

// Provided by VK_EXT_physical_device_drm
typedef struct VkPhysicalDeviceDrmPropertiesEXT {
    VkStructureType    sType;
    void*              pNext;
    VkBool32           hasPrimary;
    VkBool32           hasRender;
    int64_t            primaryMajor;
    int64_t            primaryMinor;
    int64_t            renderMajor;
    int64_t            renderMinor;
} VkPhysicalDeviceDrmPropertiesEXT;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • hasPrimary is a boolean indicating whether the physical device has a DRM primary node.

  • hasRender is a boolean indicating whether the physical device has a DRM render node.

  • primaryMajor is the DRM primary node major number, if any.

  • primaryMinor is the DRM primary node minor number, if any.

  • renderMajor is the DRM render node major number, if any.

  • renderMinor is the DRM render node minor number, if any.

If the VkPhysicalDeviceDrmPropertiesEXT structure is included in the pNext chain of the VkPhysicalDeviceProperties2 structure passed to vkGetPhysicalDeviceProperties2, it is filled in with each corresponding implementation-dependent property.

These are properties of the DRM information of a physical device.

Valid Usage (Implicit)

  • VUID-VkPhysicalDeviceDrmPropertiesEXT-sType-sType
    sType must be VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DRM_PROPERTIES_EXT

The VkPhysicalDeviceShaderIntegerDotProductProperties structure is defined as:

// Provided by VK_VERSION_1_3
typedef struct VkPhysicalDeviceShaderIntegerDotProductProperties {
    VkStructureType    sType;
    void*              pNext;
    VkBool32           integerDotProduct8BitUnsignedAccelerated;
    VkBool32           integerDotProduct8BitSignedAccelerated;
    VkBool32           integerDotProduct8BitMixedSignednessAccelerated;
    VkBool32           integerDotProduct4x8BitPackedUnsignedAccelerated;
    VkBool32           integerDotProduct4x8BitPackedSignedAccelerated;
    VkBool32           integerDotProduct4x8BitPackedMixedSignednessAccelerated;
    VkBool32           integerDotProduct16BitUnsignedAccelerated;
    VkBool32           integerDotProduct16BitSignedAccelerated;
    VkBool32           integerDotProduct16BitMixedSignednessAccelerated;
    VkBool32           integerDotProduct32BitUnsignedAccelerated;
    VkBool32           integerDotProduct32BitSignedAccelerated;
    VkBool32           integerDotProduct32BitMixedSignednessAccelerated;
    VkBool32           integerDotProduct64BitUnsignedAccelerated;
    VkBool32           integerDotProduct64BitSignedAccelerated;
    VkBool32           integerDotProduct64BitMixedSignednessAccelerated;
    VkBool32           integerDotProductAccumulatingSaturating8BitUnsignedAccelerated;
    VkBool32           integerDotProductAccumulatingSaturating8BitSignedAccelerated;
    VkBool32           integerDotProductAccumulatingSaturating8BitMixedSignednessAccelerated;
    VkBool32           integerDotProductAccumulatingSaturating4x8BitPackedUnsignedAccelerated;
    VkBool32           integerDotProductAccumulatingSaturating4x8BitPackedSignedAccelerated;
    VkBool32           integerDotProductAccumulatingSaturating4x8BitPackedMixedSignednessAccelerated;
    VkBool32           integerDotProductAccumulatingSaturating16BitUnsignedAccelerated;
    VkBool32           integerDotProductAccumulatingSaturating16BitSignedAccelerated;
    VkBool32           integerDotProductAccumulatingSaturating16BitMixedSignednessAccelerated;
    VkBool32           integerDotProductAccumulatingSaturating32BitUnsignedAccelerated;
    VkBool32           integerDotProductAccumulatingSaturating32BitSignedAccelerated;
    VkBool32           integerDotProductAccumulatingSaturating32BitMixedSignednessAccelerated;
    VkBool32           integerDotProductAccumulatingSaturating64BitUnsignedAccelerated;
    VkBool32           integerDotProductAccumulatingSaturating64BitSignedAccelerated;
    VkBool32           integerDotProductAccumulatingSaturating64BitMixedSignednessAccelerated;
} VkPhysicalDeviceShaderIntegerDotProductProperties;

or the equivalent

// Provided by VK_KHR_shader_integer_dot_product
typedef VkPhysicalDeviceShaderIntegerDotProductProperties VkPhysicalDeviceShaderIntegerDotProductPropertiesKHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • integerDotProduct8BitUnsignedAccelerated is a boolean that will be VK_TRUE if the support for 8-bit unsigned dot product operations using the OpUDotKHR SPIR-V instruction is accelerated as defined below.

  • integerDotProduct8BitSignedAccelerated is a boolean that will be VK_TRUE if the support for 8-bit signed dot product operations using the OpSDotKHR SPIR-V instruction is accelerated as defined below.

  • integerDotProduct8BitMixedSignednessAccelerated is a boolean that will be VK_TRUE if the support for 8-bit mixed signedness dot product operations using the OpSUDotKHR SPIR-V instruction is accelerated as defined below.

  • integerDotProduct4x8BitPackedUnsignedAccelerated is a boolean that will be VK_TRUE if the support for 8-bit unsigned dot product operations from operands packed into 32-bit integers using the OpUDotKHR SPIR-V instruction is accelerated as defined below.

  • integerDotProduct4x8BitPackedSignedAccelerated is a boolean that will be VK_TRUE if the support for 8-bit signed dot product operations from operands packed into 32-bit integers using the OpSDotKHR SPIR-V instruction is accelerated as defined below.

  • integerDotProduct4x8BitPackedMixedSignednessAccelerated is a boolean that will be VK_TRUE if the support for 8-bit mixed signedness dot product operations from operands packed into 32-bit integers using the OpSUDotKHR SPIR-V instruction is accelerated as defined below.

  • integerDotProduct16BitUnsignedAccelerated is a boolean that will be VK_TRUE if the support for 16-bit unsigned dot product operations using the OpUDotKHR SPIR-V instruction is accelerated as defined below.

  • integerDotProduct16BitSignedAccelerated is a boolean that will be VK_TRUE if the support for 16-bit signed dot product operations using the OpSDotKHR SPIR-V instruction is accelerated as defined below.

  • integerDotProduct16BitMixedSignednessAccelerated is a boolean that will be VK_TRUE if the support for 16-bit mixed signedness dot product operations using the OpSUDotKHR SPIR-V instruction is accelerated as defined below.

  • integerDotProduct32BitUnsignedAccelerated is a boolean that will be VK_TRUE if the support for 32-bit unsigned dot product operations using the OpUDotKHR SPIR-V instruction is accelerated as defined below.

  • integerDotProduct32BitSignedAccelerated is a boolean that will be VK_TRUE if the support for 32-bit signed dot product operations using the OpSDotKHR SPIR-V instruction is accelerated as defined below.

  • integerDotProduct32BitMixedSignednessAccelerated is a boolean that will be VK_TRUE if the support for 32-bit mixed signedness dot product operations using the OpSUDotKHR SPIR-V instruction is accelerated as defined below.

  • integerDotProduct64BitUnsignedAccelerated is a boolean that will be VK_TRUE if the support for 64-bit unsigned dot product operations using the OpUDotKHR SPIR-V instruction is accelerated as defined below.

  • integerDotProduct64BitSignedAccelerated is a boolean that will be VK_TRUE if the support for 64-bit signed dot product operations using the OpSDotKHR SPIR-V instruction is accelerated as defined below.

  • integerDotProduct64BitMixedSignednessAccelerated is a boolean that will be VK_TRUE if the support for 64-bit mixed signedness dot product operations using the OpSUDotKHR SPIR-V instruction is accelerated as defined below.

  • integerDotProductAccumulatingSaturating8BitUnsignedAccelerated is a boolean that will be VK_TRUE if the support for 8-bit unsigned accumulating saturating dot product operations using the OpUDotAccSatKHR SPIR-V instruction is accelerated as defined below.

  • integerDotProductAccumulatingSaturating8BitSignedAccelerated is a boolean that will be VK_TRUE if the support for 8-bit signed accumulating saturating dot product operations using the OpSDotAccSatKHR SPIR-V instruction is accelerated as defined below.

  • integerDotProductAccumulatingSaturating8BitMixedSignednessAccelerated is a boolean that will be VK_TRUE if the support for 8-bit mixed signedness accumulating saturating dot product operations using the OpSUDotAccSatKHR SPIR-V instruction is accelerated as defined below.

  • integerDotProductAccumulatingSaturating4x8BitPackedUnsignedAccelerated is a boolean that will be VK_TRUE if the support for 8-bit unsigned accumulating saturating dot product operations from operands packed into 32-bit integers using the OpUDotAccSatKHR SPIR-V instruction is accelerated as defined below.

  • integerDotProductAccumulatingSaturating4x8BitPackedSignedAccelerated is a boolean that will be VK_TRUE if the support for 8-bit signed accumulating saturating dot product operations from operands packed into 32-bit integers using the OpSDotAccSatKHR SPIR-V instruction is accelerated as defined below.

  • integerDotProductAccumulatingSaturating4x8BitPackedMixedSignednessAccelerated is a boolean that will be VK_TRUE if the support for 8-bit mixed signedness accumulating saturating dot product operations from operands packed into 32-bit integers using the OpSUDotAccSatKHR SPIR-V instruction is accelerated as defined below.

  • integerDotProductAccumulatingSaturating16BitUnsignedAccelerated is a boolean that will be VK_TRUE if the support for 16-bit unsigned accumulating saturating dot product operations using the OpUDotAccSatKHR SPIR-V instruction is accelerated as defined below.

  • integerDotProductAccumulatingSaturating16BitSignedAccelerated is a boolean that will be VK_TRUE if the support for 16-bit signed accumulating saturating dot product operations using the OpSDotAccSatKHR SPIR-V instruction is accelerated as defined below.

  • integerDotProductAccumulatingSaturating16BitMixedSignednessAccelerated is a boolean that will be VK_TRUE if the support for 16-bit mixed signedness accumulating saturating dot product operations using the OpSUDotAccSatKHR SPIR-V instruction is accelerated as defined below.

  • integerDotProductAccumulatingSaturating32BitUnsignedAccelerated is a boolean that will be VK_TRUE if the support for 32-bit unsigned accumulating saturating dot product operations using the OpUDotAccSatKHR SPIR-V instruction is accelerated as defined below.

  • integerDotProductAccumulatingSaturating32BitSignedAccelerated is a boolean that will be VK_TRUE if the support for 32-bit signed accumulating saturating dot product operations using the OpSDotAccSatKHR SPIR-V instruction is accelerated as defined below.

  • integerDotProductAccumulatingSaturating32BitMixedSignednessAccelerated is a boolean that will be VK_TRUE if the support for 32-bit mixed signedness accumulating saturating dot product operations using the OpSUDotAccSatKHR SPIR-V instruction is accelerated as defined below.

  • integerDotProductAccumulatingSaturating64BitUnsignedAccelerated is a boolean that will be VK_TRUE if the support for 64-bit unsigned accumulating saturating dot product operations using the OpUDotAccSatKHR SPIR-V instruction is accelerated as defined below.

  • integerDotProductAccumulatingSaturating64BitSignedAccelerated is a boolean that will be VK_TRUE if the support for 64-bit signed accumulating saturating dot product operations using the OpSDotAccSatKHR SPIR-V instruction is accelerated as defined below.

  • integerDotProductAccumulatingSaturating64BitMixedSignednessAccelerated is a boolean that will be VK_TRUE if the support for 64-bit mixed signedness accumulating saturating dot product operations using the OpSUDotAccSatKHR SPIR-V instruction is accelerated as defined below.

If the VkPhysicalDeviceShaderIntegerDotProductProperties structure is included in the pNext chain of the VkPhysicalDeviceProperties2 structure passed to vkGetPhysicalDeviceProperties2, it is filled in with each corresponding implementation-dependent property.

These are properties of the integer dot product acceleration information of a physical device.

Note

A dot product operation is deemed accelerated if its implementation provides a performance advantage over application-provided code composed from elementary instructions and/or other dot product instructions, either because the implementation uses optimized machine code sequences whose generation from application-provided code cannot be guaranteed or because it uses hardware features that cannot otherwise be targeted from application-provided code.
Valid Usage (Implicit)

  • VUID-VkPhysicalDeviceShaderIntegerDotProductProperties-sType-sType
    sType must be VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_INTEGER_DOT_PRODUCT_PROPERTIES

The VkPhysicalDeviceImageProcessingPropertiesQCOM structure is defined as:

// Provided by VK_QCOM_image_processing
typedef struct VkPhysicalDeviceImageProcessingPropertiesQCOM {
    VkStructureType    sType;
    void*              pNext;
    uint32_t           maxWeightFilterPhases;
    VkExtent2D         maxWeightFilterDimension;
    VkExtent2D         maxBlockMatchRegion;
    VkExtent2D         maxBoxFilterBlockSize;
} VkPhysicalDeviceImageProcessingPropertiesQCOM;

If the VkPhysicalDeviceImageProcessingPropertiesQCOM structure is included in the pNext chain of the VkPhysicalDeviceProperties2 structure passed to vkGetPhysicalDeviceProperties2, it is filled in with each corresponding implementation-dependent property.

These are properties of the image processing information of a physical device.

Valid Usage (Implicit)

  • VUID-VkPhysicalDeviceImageProcessingPropertiesQCOM-sType-sType
    sType must be VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGE_PROCESSING_PROPERTIES_QCOM

The VkPhysicalDeviceShaderTileImagePropertiesEXT structure is defined as:

// Provided by VK_EXT_shader_tile_image
typedef struct VkPhysicalDeviceShaderTileImagePropertiesEXT {
    VkStructureType    sType;
    void*              pNext;
    VkBool32           shaderTileImageCoherentReadAccelerated;
    VkBool32           shaderTileImageReadSampleFromPixelRateInvocation;
    VkBool32           shaderTileImageReadFromHelperInvocation;
} VkPhysicalDeviceShaderTileImagePropertiesEXT;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • shaderTileImageCoherentReadAccelerated is a boolean that will be VK_TRUE if coherent reads of tile image data is accelerated.

  • shaderTileImageReadSampleFromPixelRateInvocation is a boolean that will be VK_TRUE if reading from samples from a pixel rate fragment invocation is supported when VkPipelineMultisampleStateCreateInfo::rasterizationSamples > 1.

  • shaderTileImageReadFromHelperInvocation is a boolean that will be VK_TRUE if reads of tile image data from helper fragment invocations result in valid values.

If the VkPhysicalDeviceShaderTileImagePropertiesEXT structure is included in the pNext chain of the VkPhysicalDeviceProperties2 structure passed to vkGetPhysicalDeviceProperties2, it is filled in with each corresponding implementation-dependent property.

These are properties of the tile image information of a physical device.

Valid Usage (Implicit)

  • VUID-VkPhysicalDeviceShaderTileImagePropertiesEXT-sType-sType
    sType must be VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_TILE_IMAGE_PROPERTIES_EXT

The VkPhysicalDeviceImageProcessing2PropertiesQCOM structure is defined as:

// Provided by VK_QCOM_image_processing2
typedef struct VkPhysicalDeviceImageProcessing2PropertiesQCOM {
    VkStructureType    sType;
    void*              pNext;
    VkExtent2D         maxBlockMatchWindow;
} VkPhysicalDeviceImageProcessing2PropertiesQCOM;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • maxBlockMatchWindow is a VkExtent2D describing the largest dimensions (width and height) that can be specified for the block match window.

If the VkPhysicalDeviceImageProcessing2PropertiesQCOM structure is included in the pNext chain of the VkPhysicalDeviceProperties2 structure passed to vkGetPhysicalDeviceProperties2, it is filled in with each corresponding implementation-dependent property.

These are properties of the image processing2 information of a physical device.

Valid Usage (Implicit)

  • VUID-VkPhysicalDeviceImageProcessing2PropertiesQCOM-sType-sType
    sType must be VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGE_PROCESSING_2_PROPERTIES_QCOM

The VkPhysicalDeviceLayeredDriverPropertiesMSFT structure is defined as:

// Provided by VK_MSFT_layered_driver
typedef struct VkPhysicalDeviceLayeredDriverPropertiesMSFT {
    VkStructureType                     sType;
    void*                               pNext;
    VkLayeredDriverUnderlyingApiMSFT    underlyingAPI;
} VkPhysicalDeviceLayeredDriverPropertiesMSFT;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • underlyingAPI is a VkLayeredDriverUnderlyingApiMSFT value indicating which underlying API is used to implement the layered driver, or VK_LAYERED_DRIVER_UNDERLYING_API_NONE_MSFT if the driver is not layered.

These are properties of the driver layering information of a physical device.

Valid Usage (Implicit)

  • VUID-VkPhysicalDeviceLayeredDriverPropertiesMSFT-sType-sType
    sType must be VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_LAYERED_DRIVER_PROPERTIES_MSFT

Underlying APIs which may be returned in VkPhysicalDeviceLayeredDriverPropertiesMSFT::underlyingAPI are:

// Provided by VK_MSFT_layered_driver
typedef enum VkLayeredDriverUnderlyingApiMSFT {
    VK_LAYERED_DRIVER_UNDERLYING_API_NONE_MSFT = 0,
    VK_LAYERED_DRIVER_UNDERLYING_API_D3D12_MSFT = 1,
} VkLayeredDriverUnderlyingApiMSFT;

The VkPhysicalDeviceSchedulingControlsPropertiesARM structure is defined as:

// Provided by VK_ARM_scheduling_controls
typedef struct VkPhysicalDeviceSchedulingControlsPropertiesARM {
    VkStructureType                               sType;
    void*                                         pNext;
    VkPhysicalDeviceSchedulingControlsFlagsARM    schedulingControlsFlags;
} VkPhysicalDeviceSchedulingControlsPropertiesARM;

  • schedulingControlsFlags specifies the specific scheduling controls that a physical device supports.

If the VkPhysicalDeviceSchedulingControlsPropertiesARM structure is included in the pNext chain of the VkPhysicalDeviceProperties2 structure passed to vkGetPhysicalDeviceProperties2, it is filled in with each corresponding implementation-dependent property.

Valid Usage (Implicit)

  • VUID-VkPhysicalDeviceSchedulingControlsPropertiesARM-sType-sType
    sType must be VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SCHEDULING_CONTROLS_PROPERTIES_ARM

  • VUID-VkPhysicalDeviceSchedulingControlsPropertiesARM-schedulingControlsFlags-parameter
    schedulingControlsFlags must be a valid combination of VkPhysicalDeviceSchedulingControlsFlagBitsARM values

  • VUID-VkPhysicalDeviceSchedulingControlsPropertiesARM-schedulingControlsFlags-requiredbitmask
    schedulingControlsFlags must not be 0

Bits which can be set in VkPhysicalDeviceSchedulingControlsPropertiesARM::schedulingControlsFlags, specifying supported scheduling controls, are:

// Provided by VK_ARM_scheduling_controls
// Flag bits for VkPhysicalDeviceSchedulingControlsFlagBitsARM
typedef VkFlags64 VkPhysicalDeviceSchedulingControlsFlagBitsARM;
static const VkPhysicalDeviceSchedulingControlsFlagBitsARM VK_PHYSICAL_DEVICE_SCHEDULING_CONTROLS_SHADER_CORE_COUNT_ARM = 0x00000001ULL;
// Provided by VK_ARM_scheduling_controls
typedef VkFlags64 VkPhysicalDeviceSchedulingControlsFlagsARM;

VkPhysicalDeviceSchedulingControlsFlagsARM is a bitmask type for setting a mask of zero or more VkPhysicalDeviceSchedulingControlsFlagBitsARM.

To query properties of queues available on a physical device, call:

// Provided by VK_VERSION_1_0
void vkGetPhysicalDeviceQueueFamilyProperties(
    VkPhysicalDevice                            physicalDevice,
    uint32_t*                                   pQueueFamilyPropertyCount,
    VkQueueFamilyProperties*                    pQueueFamilyProperties);

  • physicalDevice is the handle to the physical device whose properties will be queried.

  • pQueueFamilyPropertyCount is a pointer to an integer related to the number of queue families available or queried, as described below.

  • pQueueFamilyProperties is either NULL or a pointer to an array of VkQueueFamilyProperties structures.

If pQueueFamilyProperties is NULL, then the number of queue families available is returned in pQueueFamilyPropertyCount. Implementations must support at least one queue family. Otherwise, pQueueFamilyPropertyCount must point to a variable set by the application to the number of elements in the pQueueFamilyProperties array, and on return the variable is overwritten with the number of structures actually written to pQueueFamilyProperties. If pQueueFamilyPropertyCount is less than the number of queue families available, at most pQueueFamilyPropertyCount structures will be written.

Valid Usage (Implicit)

  • VUID-vkGetPhysicalDeviceQueueFamilyProperties-physicalDevice-parameter
    physicalDevice must be a valid VkPhysicalDevice handle

  • VUID-vkGetPhysicalDeviceQueueFamilyProperties-pQueueFamilyPropertyCount-parameter
    pQueueFamilyPropertyCount must be a valid pointer to a uint32_t value

  • VUID-vkGetPhysicalDeviceQueueFamilyProperties-pQueueFamilyProperties-parameter
    If the value referenced by pQueueFamilyPropertyCount is not 0, and pQueueFamilyProperties is not NULL, pQueueFamilyProperties must be a valid pointer to an array of pQueueFamilyPropertyCount VkQueueFamilyProperties structures

The VkQueueFamilyProperties structure is defined as:

// Provided by VK_VERSION_1_0
typedef struct VkQueueFamilyProperties {
    VkQueueFlags    queueFlags;
    uint32_t        queueCount;
    uint32_t        timestampValidBits;
    VkExtent3D      minImageTransferGranularity;
} VkQueueFamilyProperties;

  • queueFlags is a bitmask of VkQueueFlagBits indicating capabilities of the queues in this queue family.

  • queueCount is the unsigned integer count of queues in this queue family. Each queue family must support at least one queue.

  • timestampValidBits is the unsigned integer count of meaningful bits in the timestamps written via vkCmdWriteTimestamp2 or vkCmdWriteTimestamp. The valid range for the count is 36 to 64 bits, or a value of 0, indicating no support for timestamps. Bits outside the valid range are guaranteed to be zeros.

  • minImageTransferGranularity is the minimum granularity supported for image transfer operations on the queues in this queue family.

The value returned in minImageTransferGranularity has a unit of compressed texel blocks for images having a block-compressed format, and a unit of texels otherwise.

Possible values of minImageTransferGranularity are:

  • (0,0,0) specifies that only whole mip levels must be transferred using the image transfer operations on the corresponding queues. In this case, the following restrictions apply to all offset and extent parameters of image transfer operations:

    • The x, y, and z members of a VkOffset3D parameter must always be zero.

    • The width, height, and depth members of a VkExtent3D parameter must always match the width, height, and depth of the image subresource corresponding to the parameter, respectively.

  • (Ax, Ay, Az) where Ax, Ay, and Az are all integer powers of two. In this case the following restrictions apply to all image transfer operations:

    • x, y, and z of a VkOffset3D parameter must be integer multiples of Ax, Ay, and Az, respectively.

    • width of a VkExtent3D parameter must be an integer multiple of Ax, or else x + width must equal the width of the image subresource corresponding to the parameter.

    • height of a VkExtent3D parameter must be an integer multiple of Ay, or else y + height must equal the height of the image subresource corresponding to the parameter.

    • depth of a VkExtent3D parameter must be an integer multiple of Az, or else z + depth must equal the depth of the image subresource corresponding to the parameter.

    • If the format of the image corresponding to the parameters is one of the block-compressed formats then for the purposes of the above calculations the granularity must be scaled up by the compressed texel block dimensions.

Queues supporting graphics and/or compute operations must report (1,1,1) in minImageTransferGranularity, meaning that there are no additional restrictions on the granularity of image transfer operations for these queues. Other queues supporting image transfer operations are only required to support whole mip level transfers, thus minImageTransferGranularity for queues belonging to such queue families may be (0,0,0).

The Device Memory section describes memory properties queried from the physical device.

For physical device feature queries see the Features chapter.

Bits which may be set in VkQueueFamilyProperties::queueFlags, indicating capabilities of queues in a queue family are:

// Provided by VK_VERSION_1_0
typedef enum VkQueueFlagBits {
    VK_QUEUE_GRAPHICS_BIT = 0x00000001,
    VK_QUEUE_COMPUTE_BIT = 0x00000002,
    VK_QUEUE_TRANSFER_BIT = 0x00000004,
    VK_QUEUE_SPARSE_BINDING_BIT = 0x00000008,
  // Provided by VK_VERSION_1_1
    VK_QUEUE_PROTECTED_BIT = 0x00000010,
  // Provided by VK_KHR_video_decode_queue
    VK_QUEUE_VIDEO_DECODE_BIT_KHR = 0x00000020,
  // Provided by VK_KHR_video_encode_queue
    VK_QUEUE_VIDEO_ENCODE_BIT_KHR = 0x00000040,
  // Provided by VK_NV_optical_flow
    VK_QUEUE_OPTICAL_FLOW_BIT_NV = 0x00000100,
} VkQueueFlagBits;

  • VK_QUEUE_GRAPHICS_BIT specifies that queues in this queue family support graphics operations.

  • VK_QUEUE_COMPUTE_BIT specifies that queues in this queue family support compute operations.

  • VK_QUEUE_TRANSFER_BIT specifies that queues in this queue family support transfer operations.

  • VK_QUEUE_SPARSE_BINDING_BIT specifies that queues in this queue family support sparse memory management operations (see Sparse Resources). If any of the sparse resource features are enabled, then at least one queue family must support this bit.

  • VK_QUEUE_VIDEO_DECODE_BIT_KHR specifies that queues in this queue family support video decode operations.

  • VK_QUEUE_VIDEO_ENCODE_BIT_KHR specifies that queues in this queue family support video encode operations.

  • VK_QUEUE_OPTICAL_FLOW_BIT_NV specifies that queues in this queue family support optical flow operations.

  • VK_QUEUE_PROTECTED_BIT specifies that queues in this queue family support the VK_DEVICE_QUEUE_CREATE_PROTECTED_BIT bit. (see Protected Memory). If the physical device supports the protectedMemory feature, at least one of its queue families must support this bit.

If an implementation exposes any queue family that supports graphics operations, at least one queue family of at least one physical device exposed by the implementation must support both graphics and compute operations.

Furthermore, if the protectedMemory physical device feature is supported, then at least one queue family of at least one physical device exposed by the implementation must support graphics operations, compute operations, and protected memory operations.

Note

All commands that are allowed on a queue that supports transfer operations are also allowed on a queue that supports either graphics or compute operations. Thus, if the capabilities of a queue family include VK_QUEUE_GRAPHICS_BIT or VK_QUEUE_COMPUTE_BIT, then reporting the VK_QUEUE_TRANSFER_BIT capability separately for that queue family is optional.

For further details see Queues.

// Provided by VK_VERSION_1_0
typedef VkFlags VkQueueFlags;

VkQueueFlags is a bitmask type for setting a mask of zero or more VkQueueFlagBits.

To query properties of queues available on a physical device, call:

// Provided by VK_VERSION_1_1
void vkGetPhysicalDeviceQueueFamilyProperties2(
    VkPhysicalDevice                            physicalDevice,
    uint32_t*                                   pQueueFamilyPropertyCount,
    VkQueueFamilyProperties2*                   pQueueFamilyProperties);

or the equivalent command

// Provided by VK_KHR_get_physical_device_properties2
void vkGetPhysicalDeviceQueueFamilyProperties2KHR(
    VkPhysicalDevice                            physicalDevice,
    uint32_t*                                   pQueueFamilyPropertyCount,
    VkQueueFamilyProperties2*                   pQueueFamilyProperties);

  • physicalDevice is the handle to the physical device whose properties will be queried.

  • pQueueFamilyPropertyCount is a pointer to an integer related to the number of queue families available or queried, as described in vkGetPhysicalDeviceQueueFamilyProperties.

  • pQueueFamilyProperties is either NULL or a pointer to an array of VkQueueFamilyProperties2 structures.

vkGetPhysicalDeviceQueueFamilyProperties2 behaves similarly to vkGetPhysicalDeviceQueueFamilyProperties, with the ability to return extended information in a pNext chain of output structures.

Valid Usage (Implicit)

  • VUID-vkGetPhysicalDeviceQueueFamilyProperties2-physicalDevice-parameter
    physicalDevice must be a valid VkPhysicalDevice handle

  • VUID-vkGetPhysicalDeviceQueueFamilyProperties2-pQueueFamilyPropertyCount-parameter
    pQueueFamilyPropertyCount must be a valid pointer to a uint32_t value

  • VUID-vkGetPhysicalDeviceQueueFamilyProperties2-pQueueFamilyProperties-parameter
    If the value referenced by pQueueFamilyPropertyCount is not 0, and pQueueFamilyProperties is not NULL, pQueueFamilyProperties must be a valid pointer to an array of pQueueFamilyPropertyCount VkQueueFamilyProperties2 structures

The VkQueueFamilyProperties2 structure is defined as:

// Provided by VK_VERSION_1_1
typedef struct VkQueueFamilyProperties2 {
    VkStructureType            sType;
    void*                      pNext;
    VkQueueFamilyProperties    queueFamilyProperties;
} VkQueueFamilyProperties2;

or the equivalent

// Provided by VK_KHR_get_physical_device_properties2
typedef VkQueueFamilyProperties2 VkQueueFamilyProperties2KHR;
Valid Usage (Implicit)

The VkQueueFamilyGlobalPriorityPropertiesKHR structure is defined as:

// Provided by VK_KHR_global_priority
typedef struct VkQueueFamilyGlobalPriorityPropertiesKHR {
    VkStructureType             sType;
    void*                       pNext;
    uint32_t                    priorityCount;
    VkQueueGlobalPriorityKHR    priorities[VK_MAX_GLOBAL_PRIORITY_SIZE_KHR];
} VkQueueFamilyGlobalPriorityPropertiesKHR;

or the equivalent

// Provided by VK_EXT_global_priority_query
typedef VkQueueFamilyGlobalPriorityPropertiesKHR VkQueueFamilyGlobalPriorityPropertiesEXT;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • priorityCount is the number of supported global queue priorities in this queue family, and it must be greater than 0.

  • priorities is an array of VK_MAX_GLOBAL_PRIORITY_SIZE_KHR VkQueueGlobalPriorityKHR enums representing all supported global queue priorities in this queue family. The first priorityCount elements of the array will be valid.

If the VkQueueFamilyGlobalPriorityPropertiesKHR structure is included in the pNext chain of the VkQueueFamilyProperties2 structure passed to vkGetPhysicalDeviceQueueFamilyProperties2, it is filled in with the list of supported global queue priorities for the indicated family.

The valid elements of priorities must not contain any duplicate values.

The valid elements of priorities must be a continuous sequence of VkQueueGlobalPriorityKHR enums in the ascending order.

Note

For example, returning priorityCount as 3 with supported priorities as VK_QUEUE_GLOBAL_PRIORITY_LOW_KHR, VK_QUEUE_GLOBAL_PRIORITY_MEDIUM_KHR and VK_QUEUE_GLOBAL_PRIORITY_REALTIME_KHR is not allowed.
Valid Usage (Implicit)

  • VUID-VkQueueFamilyGlobalPriorityPropertiesKHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_QUEUE_FAMILY_GLOBAL_PRIORITY_PROPERTIES_KHR

VK_MAX_GLOBAL_PRIORITY_SIZE_KHR is the length of an array of VkQueueGlobalPriorityKHR enumerants representing supported queue priorities, as returned in VkQueueFamilyGlobalPriorityPropertiesKHR::priorities.

#define VK_MAX_GLOBAL_PRIORITY_SIZE_KHR   16U

or the equivalent

#define VK_MAX_GLOBAL_PRIORITY_SIZE_EXT   VK_MAX_GLOBAL_PRIORITY_SIZE_KHR

The VkQueueFamilyCheckpointProperties2NV structure is defined as:

// Provided by VK_KHR_synchronization2 with VK_NV_device_diagnostic_checkpoints
typedef struct VkQueueFamilyCheckpointProperties2NV {
    VkStructureType          sType;
    void*                    pNext;
    VkPipelineStageFlags2    checkpointExecutionStageMask;
} VkQueueFamilyCheckpointProperties2NV;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • checkpointExecutionStageMask is a mask indicating which pipeline stages the implementation can execute checkpoint markers in.

Additional queue family information can be queried by setting VkQueueFamilyProperties2::pNext to point to a VkQueueFamilyCheckpointProperties2NV structure.

Valid Usage (Implicit)

  • VUID-VkQueueFamilyCheckpointProperties2NV-sType-sType
    sType must be VK_STRUCTURE_TYPE_QUEUE_FAMILY_CHECKPOINT_PROPERTIES_2_NV

The VkQueueFamilyCheckpointPropertiesNV structure is defined as:

// Provided by VK_NV_device_diagnostic_checkpoints
typedef struct VkQueueFamilyCheckpointPropertiesNV {
    VkStructureType         sType;
    void*                   pNext;
    VkPipelineStageFlags    checkpointExecutionStageMask;
} VkQueueFamilyCheckpointPropertiesNV;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • checkpointExecutionStageMask is a mask indicating which pipeline stages the implementation can execute checkpoint markers in.

Additional queue family information can be queried by setting VkQueueFamilyProperties2::pNext to point to a VkQueueFamilyCheckpointPropertiesNV structure.

Valid Usage (Implicit)

  • VUID-VkQueueFamilyCheckpointPropertiesNV-sType-sType
    sType must be VK_STRUCTURE_TYPE_QUEUE_FAMILY_CHECKPOINT_PROPERTIES_NV

The VkQueueFamilyVideoPropertiesKHR structure is defined as:

// Provided by VK_KHR_video_queue
typedef struct VkQueueFamilyVideoPropertiesKHR {
    VkStructureType                  sType;
    void*                            pNext;
    VkVideoCodecOperationFlagsKHR    videoCodecOperations;
} VkQueueFamilyVideoPropertiesKHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • videoCodecOperations is a bitmask of VkVideoCodecOperationFlagBitsKHR that indicates the set of video codec operations supported by the queue family.

If this structure is included in the pNext chain of the VkQueueFamilyProperties2 structure passed to vkGetPhysicalDeviceQueueFamilyProperties2, then it is filled with the set of video codec operations supported by the specified queue family.

Valid Usage (Implicit)

  • VUID-VkQueueFamilyVideoPropertiesKHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_QUEUE_FAMILY_VIDEO_PROPERTIES_KHR

The VkQueueFamilyQueryResultStatusPropertiesKHR structure is defined as:

// Provided by VK_KHR_video_queue
typedef struct VkQueueFamilyQueryResultStatusPropertiesKHR {
    VkStructureType    sType;
    void*              pNext;
    VkBool32           queryResultStatusSupport;
} VkQueueFamilyQueryResultStatusPropertiesKHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • queryResultStatusSupport reports VK_TRUE if query type VK_QUERY_TYPE_RESULT_STATUS_ONLY_KHR and use of VK_QUERY_RESULT_WITH_STATUS_BIT_KHR are supported.

If this structure is included in the pNext chain of the VkQueueFamilyProperties2 structure passed to vkGetPhysicalDeviceQueueFamilyProperties2, then it is filled with information about whether result status queries are supported by the specified queue family.

Valid Usage (Implicit)

  • VUID-VkQueueFamilyQueryResultStatusPropertiesKHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_QUEUE_FAMILY_QUERY_RESULT_STATUS_PROPERTIES_KHR

To enumerate the performance query counters available on a queue family of a physical device, call:

// Provided by VK_KHR_performance_query
VkResult vkEnumeratePhysicalDeviceQueueFamilyPerformanceQueryCountersKHR(
    VkPhysicalDevice                            physicalDevice,
    uint32_t                                    queueFamilyIndex,
    uint32_t*                                   pCounterCount,
    VkPerformanceCounterKHR*                    pCounters,
    VkPerformanceCounterDescriptionKHR*         pCounterDescriptions);

  • physicalDevice is the handle to the physical device whose queue family performance query counter properties will be queried.

  • queueFamilyIndex is the index into the queue family of the physical device we want to get properties for.

  • pCounterCount is a pointer to an integer related to the number of counters available or queried, as described below.

  • pCounters is either NULL or a pointer to an array of VkPerformanceCounterKHR structures.

  • pCounterDescriptions is either NULL or a pointer to an array of VkPerformanceCounterDescriptionKHR structures.

If pCounters is NULL and pCounterDescriptions is NULL, then the number of counters available is returned in pCounterCount. Otherwise, pCounterCount must point to a variable set by the application to the number of elements in the pCounters, pCounterDescriptions, or both arrays and on return the variable is overwritten with the number of structures actually written out. If pCounterCount is less than the number of counters available, at most pCounterCount structures will be written, and VK_INCOMPLETE will be returned instead of VK_SUCCESS, to indicate that not all the available counters were returned.

Valid Usage (Implicit)

  • VUID-vkEnumeratePhysicalDeviceQueueFamilyPerformanceQueryCountersKHR-physicalDevice-parameter
    physicalDevice must be a valid VkPhysicalDevice handle

  • VUID-vkEnumeratePhysicalDeviceQueueFamilyPerformanceQueryCountersKHR-pCounterCount-parameter
    pCounterCount must be a valid pointer to a uint32_t value

  • VUID-vkEnumeratePhysicalDeviceQueueFamilyPerformanceQueryCountersKHR-pCounters-parameter
    If the value referenced by pCounterCount is not 0, and pCounters is not NULL, pCounters must be a valid pointer to an array of pCounterCount VkPerformanceCounterKHR structures

  • VUID-vkEnumeratePhysicalDeviceQueueFamilyPerformanceQueryCountersKHR-pCounterDescriptions-parameter
    If the value referenced by pCounterCount is not 0, and pCounterDescriptions is not NULL, pCounterDescriptions must be a valid pointer to an array of pCounterCount VkPerformanceCounterDescriptionKHR structures

Return Codes
Success

  • VK_SUCCESS

  • VK_INCOMPLETE

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

  • VK_ERROR_INITIALIZATION_FAILED

The VkPerformanceCounterKHR structure is defined as:

// Provided by VK_KHR_performance_query
typedef struct VkPerformanceCounterKHR {
    VkStructureType                   sType;
    void*                             pNext;
    VkPerformanceCounterUnitKHR       unit;
    VkPerformanceCounterScopeKHR      scope;
    VkPerformanceCounterStorageKHR    storage;
    uint8_t                           uuid[VK_UUID_SIZE];
} VkPerformanceCounterKHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • unit is a VkPerformanceCounterUnitKHR specifying the unit that the counter data will record.

  • scope is a VkPerformanceCounterScopeKHR specifying the scope that the counter belongs to.

  • storage is a VkPerformanceCounterStorageKHR specifying the storage type that the counter’s data uses.

  • uuid is an array of size VK_UUID_SIZE, containing 8-bit values that represent a universally unique identifier for the counter of the physical device.

Valid Usage (Implicit)

  • VUID-VkPerformanceCounterKHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_PERFORMANCE_COUNTER_KHR

  • VUID-VkPerformanceCounterKHR-pNext-pNext
    pNext must be NULL

Performance counters have an associated unit. This unit describes how to interpret the performance counter result.

The performance counter unit types which may be returned in VkPerformanceCounterKHR::unit are:

// Provided by VK_KHR_performance_query
typedef enum VkPerformanceCounterUnitKHR {
    VK_PERFORMANCE_COUNTER_UNIT_GENERIC_KHR = 0,
    VK_PERFORMANCE_COUNTER_UNIT_PERCENTAGE_KHR = 1,
    VK_PERFORMANCE_COUNTER_UNIT_NANOSECONDS_KHR = 2,
    VK_PERFORMANCE_COUNTER_UNIT_BYTES_KHR = 3,
    VK_PERFORMANCE_COUNTER_UNIT_BYTES_PER_SECOND_KHR = 4,
    VK_PERFORMANCE_COUNTER_UNIT_KELVIN_KHR = 5,
    VK_PERFORMANCE_COUNTER_UNIT_WATTS_KHR = 6,
    VK_PERFORMANCE_COUNTER_UNIT_VOLTS_KHR = 7,
    VK_PERFORMANCE_COUNTER_UNIT_AMPS_KHR = 8,
    VK_PERFORMANCE_COUNTER_UNIT_HERTZ_KHR = 9,
    VK_PERFORMANCE_COUNTER_UNIT_CYCLES_KHR = 10,
} VkPerformanceCounterUnitKHR;

  • VK_PERFORMANCE_COUNTER_UNIT_GENERIC_KHR - the performance counter unit is a generic data point.

  • VK_PERFORMANCE_COUNTER_UNIT_PERCENTAGE_KHR - the performance counter unit is a percentage (%).

  • VK_PERFORMANCE_COUNTER_UNIT_NANOSECONDS_KHR - the performance counter unit is a value of nanoseconds (ns).

  • VK_PERFORMANCE_COUNTER_UNIT_BYTES_KHR - the performance counter unit is a value of bytes.

  • VK_PERFORMANCE_COUNTER_UNIT_BYTES_PER_SECOND_KHR - the performance counter unit is a value of bytes/s.

  • VK_PERFORMANCE_COUNTER_UNIT_KELVIN_KHR - the performance counter unit is a temperature reported in Kelvin.

  • VK_PERFORMANCE_COUNTER_UNIT_WATTS_KHR - the performance counter unit is a value of watts (W).

  • VK_PERFORMANCE_COUNTER_UNIT_VOLTS_KHR - the performance counter unit is a value of volts (V).

  • VK_PERFORMANCE_COUNTER_UNIT_AMPS_KHR - the performance counter unit is a value of amps (A).

  • VK_PERFORMANCE_COUNTER_UNIT_HERTZ_KHR - the performance counter unit is a value of hertz (Hz).

  • VK_PERFORMANCE_COUNTER_UNIT_CYCLES_KHR - the performance counter unit is a value of cycles.

Performance counters have an associated scope. This scope describes the granularity of a performance counter.

The performance counter scope types which may be returned in VkPerformanceCounterKHR::scope are:

// Provided by VK_KHR_performance_query
typedef enum VkPerformanceCounterScopeKHR {
    VK_PERFORMANCE_COUNTER_SCOPE_COMMAND_BUFFER_KHR = 0,
    VK_PERFORMANCE_COUNTER_SCOPE_RENDER_PASS_KHR = 1,
    VK_PERFORMANCE_COUNTER_SCOPE_COMMAND_KHR = 2,
  // VK_QUERY_SCOPE_COMMAND_BUFFER_KHR is a deprecated alias
    VK_QUERY_SCOPE_COMMAND_BUFFER_KHR = VK_PERFORMANCE_COUNTER_SCOPE_COMMAND_BUFFER_KHR,
  // VK_QUERY_SCOPE_RENDER_PASS_KHR is a deprecated alias
    VK_QUERY_SCOPE_RENDER_PASS_KHR = VK_PERFORMANCE_COUNTER_SCOPE_RENDER_PASS_KHR,
  // VK_QUERY_SCOPE_COMMAND_KHR is a deprecated alias
    VK_QUERY_SCOPE_COMMAND_KHR = VK_PERFORMANCE_COUNTER_SCOPE_COMMAND_KHR,
} VkPerformanceCounterScopeKHR;

  • VK_PERFORMANCE_COUNTER_SCOPE_COMMAND_BUFFER_KHR - the performance counter scope is a single complete command buffer.

  • VK_PERFORMANCE_COUNTER_SCOPE_RENDER_PASS_KHR - the performance counter scope is zero or more complete render passes. The performance query containing the performance counter must begin and end outside a render pass instance.

  • VK_PERFORMANCE_COUNTER_SCOPE_COMMAND_KHR - the performance counter scope is zero or more commands.

Performance counters have an associated storage. This storage describes the payload of a counter result.

The performance counter storage types which may be returned in VkPerformanceCounterKHR::storage are:

// Provided by VK_KHR_performance_query
typedef enum VkPerformanceCounterStorageKHR {
    VK_PERFORMANCE_COUNTER_STORAGE_INT32_KHR = 0,
    VK_PERFORMANCE_COUNTER_STORAGE_INT64_KHR = 1,
    VK_PERFORMANCE_COUNTER_STORAGE_UINT32_KHR = 2,
    VK_PERFORMANCE_COUNTER_STORAGE_UINT64_KHR = 3,
    VK_PERFORMANCE_COUNTER_STORAGE_FLOAT32_KHR = 4,
    VK_PERFORMANCE_COUNTER_STORAGE_FLOAT64_KHR = 5,
} VkPerformanceCounterStorageKHR;

  • VK_PERFORMANCE_COUNTER_STORAGE_INT32_KHR - the performance counter storage is a 32-bit signed integer.

  • VK_PERFORMANCE_COUNTER_STORAGE_INT64_KHR - the performance counter storage is a 64-bit signed integer.

  • VK_PERFORMANCE_COUNTER_STORAGE_UINT32_KHR - the performance counter storage is a 32-bit unsigned integer.

  • VK_PERFORMANCE_COUNTER_STORAGE_UINT64_KHR - the performance counter storage is a 64-bit unsigned integer.

  • VK_PERFORMANCE_COUNTER_STORAGE_FLOAT32_KHR - the performance counter storage is a 32-bit floating-point.

  • VK_PERFORMANCE_COUNTER_STORAGE_FLOAT64_KHR - the performance counter storage is a 64-bit floating-point.

The VkPerformanceCounterDescriptionKHR structure is defined as:

// Provided by VK_KHR_performance_query
typedef struct VkPerformanceCounterDescriptionKHR {
    VkStructureType                            sType;
    void*                                      pNext;
    VkPerformanceCounterDescriptionFlagsKHR    flags;
    char                                       name[VK_MAX_DESCRIPTION_SIZE];
    char                                       category[VK_MAX_DESCRIPTION_SIZE];
    char                                       description[VK_MAX_DESCRIPTION_SIZE];
} VkPerformanceCounterDescriptionKHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • flags is a bitmask of VkPerformanceCounterDescriptionFlagBitsKHR indicating the usage behavior for the counter.

  • name is an array of size VK_MAX_DESCRIPTION_SIZE, containing a null-terminated UTF-8 string specifying the name of the counter.

  • category is an array of size VK_MAX_DESCRIPTION_SIZE, containing a null-terminated UTF-8 string specifying the category of the counter.

  • description is an array of size VK_MAX_DESCRIPTION_SIZE, containing a null-terminated UTF-8 string specifying the description of the counter.

Valid Usage (Implicit)

  • VUID-VkPerformanceCounterDescriptionKHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_PERFORMANCE_COUNTER_DESCRIPTION_KHR

  • VUID-VkPerformanceCounterDescriptionKHR-pNext-pNext
    pNext must be NULL

Bits which can be set in VkPerformanceCounterDescriptionKHR::flags, specifying usage behavior of a performance counter, are:

// Provided by VK_KHR_performance_query
typedef enum VkPerformanceCounterDescriptionFlagBitsKHR {
    VK_PERFORMANCE_COUNTER_DESCRIPTION_PERFORMANCE_IMPACTING_BIT_KHR = 0x00000001,
    VK_PERFORMANCE_COUNTER_DESCRIPTION_CONCURRENTLY_IMPACTED_BIT_KHR = 0x00000002,
  // VK_PERFORMANCE_COUNTER_DESCRIPTION_PERFORMANCE_IMPACTING_KHR is a deprecated alias
    VK_PERFORMANCE_COUNTER_DESCRIPTION_PERFORMANCE_IMPACTING_KHR = VK_PERFORMANCE_COUNTER_DESCRIPTION_PERFORMANCE_IMPACTING_BIT_KHR,
  // VK_PERFORMANCE_COUNTER_DESCRIPTION_CONCURRENTLY_IMPACTED_KHR is a deprecated alias
    VK_PERFORMANCE_COUNTER_DESCRIPTION_CONCURRENTLY_IMPACTED_KHR = VK_PERFORMANCE_COUNTER_DESCRIPTION_CONCURRENTLY_IMPACTED_BIT_KHR,
} VkPerformanceCounterDescriptionFlagBitsKHR;

  • VK_PERFORMANCE_COUNTER_DESCRIPTION_PERFORMANCE_IMPACTING_BIT_KHR specifies that recording the counter may have a noticeable performance impact.

  • VK_PERFORMANCE_COUNTER_DESCRIPTION_CONCURRENTLY_IMPACTED_BIT_KHR specifies that concurrently recording the counter while other submitted command buffers are running may impact the accuracy of the recording.

// Provided by VK_KHR_performance_query
typedef VkFlags VkPerformanceCounterDescriptionFlagsKHR;

VkPerformanceCounterDescriptionFlagsKHR is a bitmask type for setting a mask of zero or more VkPerformanceCounterDescriptionFlagBitsKHR.

5.2. Devices

Device objects represent logical connections to physical devices. Each device exposes a number of queue families each having one or more queues. All queues in a queue family support the same operations.

As described in Physical Devices, a Vulkan application will first query for all physical devices in a system. Each physical device can then be queried for its capabilities, including its queue and queue family properties. Once an acceptable physical device is identified, an application will create a corresponding logical device. The created logical device is then the primary interface to the physical device.

How to enumerate the physical devices in a system and query those physical devices for their queue family properties is described in the Physical Device Enumeration section above.

A single logical device can be created from multiple physical devices, if those physical devices belong to the same device group. A device group is a set of physical devices that support accessing each other’s memory and recording a single command buffer that can be executed on all the physical devices. Device groups are enumerated by calling vkEnumeratePhysicalDeviceGroups, and a logical device is created from a subset of the physical devices in a device group by passing the physical devices through VkDeviceGroupDeviceCreateInfo. For two physical devices to be in the same device group, they must support identical extensions, features, and properties.

Note

Physical devices in the same device group must be so similar because there are no rules for how different features/properties would interact. They must return the same values for nearly every invariant vkGetPhysicalDevice* feature, property, capability, etc., but could potentially differ for certain queries based on things like having a different display connected, or a different compositor. The specification does not attempt to enumerate which state is in each category, because such a list would quickly become out of date.

To retrieve a list of the device groups present in the system, call:

// Provided by VK_VERSION_1_1
VkResult vkEnumeratePhysicalDeviceGroups(
    VkInstance                                  instance,
    uint32_t*                                   pPhysicalDeviceGroupCount,
    VkPhysicalDeviceGroupProperties*            pPhysicalDeviceGroupProperties);

or the equivalent command

// Provided by VK_KHR_device_group_creation
VkResult vkEnumeratePhysicalDeviceGroupsKHR(
    VkInstance                                  instance,
    uint32_t*                                   pPhysicalDeviceGroupCount,
    VkPhysicalDeviceGroupProperties*            pPhysicalDeviceGroupProperties);

  • instance is a handle to a Vulkan instance previously created with vkCreateInstance.

  • pPhysicalDeviceGroupCount is a pointer to an integer related to the number of device groups available or queried, as described below.

  • pPhysicalDeviceGroupProperties is either NULL or a pointer to an array of VkPhysicalDeviceGroupProperties structures.

If pPhysicalDeviceGroupProperties is NULL, then the number of device groups available is returned in pPhysicalDeviceGroupCount. Otherwise, pPhysicalDeviceGroupCount must point to a variable set by the application to the number of elements in the pPhysicalDeviceGroupProperties array, and on return the variable is overwritten with the number of structures actually written to pPhysicalDeviceGroupProperties. If pPhysicalDeviceGroupCount is less than the number of device groups available, at most pPhysicalDeviceGroupCount structures will be written, and VK_INCOMPLETE will be returned instead of VK_SUCCESS, to indicate that not all the available device groups were returned.

Every physical device must be in exactly one device group.

Valid Usage (Implicit)

  • VUID-vkEnumeratePhysicalDeviceGroups-instance-parameter
    instance must be a valid VkInstance handle

  • VUID-vkEnumeratePhysicalDeviceGroups-pPhysicalDeviceGroupCount-parameter
    pPhysicalDeviceGroupCount must be a valid pointer to a uint32_t value

  • VUID-vkEnumeratePhysicalDeviceGroups-pPhysicalDeviceGroupProperties-parameter
    If the value referenced by pPhysicalDeviceGroupCount is not 0, and pPhysicalDeviceGroupProperties is not NULL, pPhysicalDeviceGroupProperties must be a valid pointer to an array of pPhysicalDeviceGroupCount VkPhysicalDeviceGroupProperties structures

Return Codes
Success

  • VK_SUCCESS

  • VK_INCOMPLETE

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

  • VK_ERROR_INITIALIZATION_FAILED

The VkPhysicalDeviceGroupProperties structure is defined as:

// Provided by VK_VERSION_1_1
typedef struct VkPhysicalDeviceGroupProperties {
    VkStructureType     sType;
    void*               pNext;
    uint32_t            physicalDeviceCount;
    VkPhysicalDevice    physicalDevices[VK_MAX_DEVICE_GROUP_SIZE];
    VkBool32            subsetAllocation;
} VkPhysicalDeviceGroupProperties;

or the equivalent

// Provided by VK_KHR_device_group_creation
typedef VkPhysicalDeviceGroupProperties VkPhysicalDeviceGroupPropertiesKHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • physicalDeviceCount is the number of physical devices in the group.

  • physicalDevices is an array of VK_MAX_DEVICE_GROUP_SIZE VkPhysicalDevice handles representing all physical devices in the group. The first physicalDeviceCount elements of the array will be valid.

  • subsetAllocation specifies whether logical devices created from the group support allocating device memory on a subset of devices, via the deviceMask member of the VkMemoryAllocateFlagsInfo. If this is VK_FALSE, then all device memory allocations are made across all physical devices in the group. If physicalDeviceCount is 1, then subsetAllocation must be VK_FALSE.

Valid Usage (Implicit)

  • VUID-VkPhysicalDeviceGroupProperties-sType-sType
    sType must be VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_GROUP_PROPERTIES

  • VUID-VkPhysicalDeviceGroupProperties-pNext-pNext
    pNext must be NULL

VK_MAX_DEVICE_GROUP_SIZE is the length of an array containing VkPhysicalDevice handle values representing all physical devices in a group, as returned in VkPhysicalDeviceGroupProperties::physicalDevices.

#define VK_MAX_DEVICE_GROUP_SIZE          32U

or the equivalent

#define VK_MAX_DEVICE_GROUP_SIZE_KHR      VK_MAX_DEVICE_GROUP_SIZE

5.2.1. Device Creation

Logical devices are represented by VkDevice handles:

// Provided by VK_VERSION_1_0
VK_DEFINE_HANDLE(VkDevice)

A logical device is created as a connection to a physical device. To create a logical device, call:

// Provided by VK_VERSION_1_0
VkResult vkCreateDevice(
    VkPhysicalDevice                            physicalDevice,
    const VkDeviceCreateInfo*                   pCreateInfo,
    const VkAllocationCallbacks*                pAllocator,
    VkDevice*                                   pDevice);

  • physicalDevice must be one of the device handles returned from a call to vkEnumeratePhysicalDevices (see Physical Device Enumeration).

  • pCreateInfo is a pointer to a VkDeviceCreateInfo structure containing information about how to create the device.

  • pAllocator controls host memory allocation as described in the Memory Allocation chapter.

  • pDevice is a pointer to a handle in which the created VkDevice is returned.

vkCreateDevice verifies that extensions and features requested in the ppEnabledExtensionNames and pEnabledFeatures members of pCreateInfo, respectively, are supported by the implementation. If any requested extension is not supported, vkCreateDevice must return VK_ERROR_EXTENSION_NOT_PRESENT. If any requested feature is not supported, vkCreateDevice must return VK_ERROR_FEATURE_NOT_PRESENT. Support for extensions can be checked before creating a device by querying vkEnumerateDeviceExtensionProperties. Support for features can similarly be checked by querying vkGetPhysicalDeviceFeatures.

After verifying and enabling the extensions the VkDevice object is created and returned to the application.

Multiple logical devices can be created from the same physical device. Logical device creation may fail due to lack of device-specific resources (in addition to other errors). If that occurs, vkCreateDevice will return VK_ERROR_TOO_MANY_OBJECTS.

Valid Usage
Valid Usage (Implicit)

  • VUID-vkCreateDevice-physicalDevice-parameter
    physicalDevice must be a valid VkPhysicalDevice handle

  • VUID-vkCreateDevice-pCreateInfo-parameter
    pCreateInfo must be a valid pointer to a valid VkDeviceCreateInfo structure

  • VUID-vkCreateDevice-pAllocator-parameter
    If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure

  • VUID-vkCreateDevice-pDevice-parameter
    pDevice must be a valid pointer to a VkDevice handle

Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

  • VK_ERROR_INITIALIZATION_FAILED

  • VK_ERROR_EXTENSION_NOT_PRESENT

  • VK_ERROR_FEATURE_NOT_PRESENT

  • VK_ERROR_TOO_MANY_OBJECTS

  • VK_ERROR_DEVICE_LOST

The VkDeviceCreateInfo structure is defined as:

// Provided by VK_VERSION_1_0
typedef struct VkDeviceCreateInfo {
    VkStructureType                    sType;
    const void*                        pNext;
    VkDeviceCreateFlags                flags;
    uint32_t                           queueCreateInfoCount;
    const VkDeviceQueueCreateInfo*     pQueueCreateInfos;
    // enabledLayerCount is deprecated and should not be used
    uint32_t                           enabledLayerCount;
    // ppEnabledLayerNames is deprecated and should not be used
    const char* const*                 ppEnabledLayerNames;
    uint32_t                           enabledExtensionCount;
    const char* const*                 ppEnabledExtensionNames;
    const VkPhysicalDeviceFeatures*    pEnabledFeatures;
} VkDeviceCreateInfo;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • flags is reserved for future use.

  • queueCreateInfoCount is the unsigned integer size of the pQueueCreateInfos array. Refer to the Queue Creation section below for further details.

  • pQueueCreateInfos is a pointer to an array of VkDeviceQueueCreateInfo structures describing the queues that are requested to be created along with the logical device. Refer to the Queue Creation section below for further details.

  • enabledLayerCount is deprecated and ignored.

  • ppEnabledLayerNames is deprecated and ignored. See Device Layer Deprecation.

  • enabledExtensionCount is the number of device extensions to enable.

  • ppEnabledExtensionNames is a pointer to an array of enabledExtensionCount null-terminated UTF-8 strings containing the names of extensions to enable for the created device. See the Extensions section for further details.

  • pEnabledFeatures is NULL or a pointer to a VkPhysicalDeviceFeatures structure containing boolean indicators of all the features to be enabled. Refer to the Features section for further details.

Valid Usage
Valid Usage (Implicit)
// Provided by VK_VERSION_1_0
typedef VkFlags VkDeviceCreateFlags;

VkDeviceCreateFlags is a bitmask type for setting a mask, but is currently reserved for future use.

A logical device can be created that connects to one or more physical devices by adding a VkDeviceGroupDeviceCreateInfo structure to the pNext chain of VkDeviceCreateInfo. The VkDeviceGroupDeviceCreateInfo structure is defined as:

// Provided by VK_VERSION_1_1
typedef struct VkDeviceGroupDeviceCreateInfo {
    VkStructureType            sType;
    const void*                pNext;
    uint32_t                   physicalDeviceCount;
    const VkPhysicalDevice*    pPhysicalDevices;
} VkDeviceGroupDeviceCreateInfo;

or the equivalent

// Provided by VK_KHR_device_group_creation
typedef VkDeviceGroupDeviceCreateInfo VkDeviceGroupDeviceCreateInfoKHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • physicalDeviceCount is the number of elements in the pPhysicalDevices array.

  • pPhysicalDevices is a pointer to an array of physical device handles belonging to the same device group.

The elements of the pPhysicalDevices array are an ordered list of the physical devices that the logical device represents. These must be a subset of a single device group, and need not be in the same order as they were enumerated. The order of the physical devices in the pPhysicalDevices array determines the device index of each physical device, with element i being assigned a device index of i. Certain commands and structures refer to one or more physical devices by using device indices or device masks formed using device indices.

A logical device created without using VkDeviceGroupDeviceCreateInfo, or with physicalDeviceCount equal to zero, is equivalent to a physicalDeviceCount of one and pPhysicalDevices pointing to the physicalDevice parameter to vkCreateDevice. In particular, the device index of that physical device is zero.

Valid Usage

  • VUID-VkDeviceGroupDeviceCreateInfo-pPhysicalDevices-00375
    Each element of pPhysicalDevices must be unique

  • VUID-VkDeviceGroupDeviceCreateInfo-pPhysicalDevices-00376
    All elements of pPhysicalDevices must be in the same device group as enumerated by vkEnumeratePhysicalDeviceGroups

  • VUID-VkDeviceGroupDeviceCreateInfo-physicalDeviceCount-00377
    If physicalDeviceCount is not 0, the physicalDevice parameter of vkCreateDevice must be an element of pPhysicalDevices

Valid Usage (Implicit)

  • VUID-VkDeviceGroupDeviceCreateInfo-sType-sType
    sType must be VK_STRUCTURE_TYPE_DEVICE_GROUP_DEVICE_CREATE_INFO

  • VUID-VkDeviceGroupDeviceCreateInfo-pPhysicalDevices-parameter
    If physicalDeviceCount is not 0, pPhysicalDevices must be a valid pointer to an array of physicalDeviceCount valid VkPhysicalDevice handles

To specify whether device memory allocation is allowed beyond the size reported by VkPhysicalDeviceMemoryProperties, add a VkDeviceMemoryOverallocationCreateInfoAMD structure to the pNext chain of the VkDeviceCreateInfo structure. If this structure is not specified, it is as if the VK_MEMORY_OVERALLOCATION_BEHAVIOR_DEFAULT_AMD value is used.

// Provided by VK_AMD_memory_overallocation_behavior
typedef struct VkDeviceMemoryOverallocationCreateInfoAMD {
    VkStructureType                      sType;
    const void*                          pNext;
    VkMemoryOverallocationBehaviorAMD    overallocationBehavior;
} VkDeviceMemoryOverallocationCreateInfoAMD;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • overallocationBehavior is the desired overallocation behavior.

Valid Usage (Implicit)

  • VUID-VkDeviceMemoryOverallocationCreateInfoAMD-sType-sType
    sType must be VK_STRUCTURE_TYPE_DEVICE_MEMORY_OVERALLOCATION_CREATE_INFO_AMD

  • VUID-VkDeviceMemoryOverallocationCreateInfoAMD-overallocationBehavior-parameter
    overallocationBehavior must be a valid VkMemoryOverallocationBehaviorAMD value

Possible values for VkDeviceMemoryOverallocationCreateInfoAMD::overallocationBehavior include:

// Provided by VK_AMD_memory_overallocation_behavior
typedef enum VkMemoryOverallocationBehaviorAMD {
    VK_MEMORY_OVERALLOCATION_BEHAVIOR_DEFAULT_AMD = 0,
    VK_MEMORY_OVERALLOCATION_BEHAVIOR_ALLOWED_AMD = 1,
    VK_MEMORY_OVERALLOCATION_BEHAVIOR_DISALLOWED_AMD = 2,
} VkMemoryOverallocationBehaviorAMD;

  • VK_MEMORY_OVERALLOCATION_BEHAVIOR_DEFAULT_AMD lets the implementation decide if overallocation is allowed.

  • VK_MEMORY_OVERALLOCATION_BEHAVIOR_ALLOWED_AMD specifies overallocation is allowed if platform permits.

  • VK_MEMORY_OVERALLOCATION_BEHAVIOR_DISALLOWED_AMD specifies the application is not allowed to allocate device memory beyond the heap sizes reported by VkPhysicalDeviceMemoryProperties. Allocations that are not explicitly made by the application within the scope of the Vulkan instance are not accounted for.

When using the Nsight™ Aftermath SDK, to configure how device crash dumps are created, add a VkDeviceDiagnosticsConfigCreateInfoNV structure to the pNext chain of the VkDeviceCreateInfo structure.

// Provided by VK_NV_device_diagnostics_config
typedef struct VkDeviceDiagnosticsConfigCreateInfoNV {
    VkStructureType                     sType;
    const void*                         pNext;
    VkDeviceDiagnosticsConfigFlagsNV    flags;
} VkDeviceDiagnosticsConfigCreateInfoNV;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • flags is a bitmask of VkDeviceDiagnosticsConfigFlagBitsNV specifying additional parameters for configuring diagnostic tools.

Valid Usage (Implicit)

  • VUID-VkDeviceDiagnosticsConfigCreateInfoNV-sType-sType
    sType must be VK_STRUCTURE_TYPE_DEVICE_DIAGNOSTICS_CONFIG_CREATE_INFO_NV

  • VUID-VkDeviceDiagnosticsConfigCreateInfoNV-flags-parameter
    flags must be a valid combination of VkDeviceDiagnosticsConfigFlagBitsNV values

Bits which can be set in VkDeviceDiagnosticsConfigCreateInfoNV::flags include:

// Provided by VK_NV_device_diagnostics_config
typedef enum VkDeviceDiagnosticsConfigFlagBitsNV {
    VK_DEVICE_DIAGNOSTICS_CONFIG_ENABLE_SHADER_DEBUG_INFO_BIT_NV = 0x00000001,
    VK_DEVICE_DIAGNOSTICS_CONFIG_ENABLE_RESOURCE_TRACKING_BIT_NV = 0x00000002,
    VK_DEVICE_DIAGNOSTICS_CONFIG_ENABLE_AUTOMATIC_CHECKPOINTS_BIT_NV = 0x00000004,
    VK_DEVICE_DIAGNOSTICS_CONFIG_ENABLE_SHADER_ERROR_REPORTING_BIT_NV = 0x00000008,
} VkDeviceDiagnosticsConfigFlagBitsNV;

  • VK_DEVICE_DIAGNOSTICS_CONFIG_ENABLE_SHADER_DEBUG_INFO_BIT_NV enables the generation of debug information for shaders.

  • VK_DEVICE_DIAGNOSTICS_CONFIG_ENABLE_RESOURCE_TRACKING_BIT_NV enables driver side tracking of resources (images, buffers, etc.) used to augment the device fault information.

  • VK_DEVICE_DIAGNOSTICS_CONFIG_ENABLE_AUTOMATIC_CHECKPOINTS_BIT_NV enables automatic insertion of diagnostic checkpoints for draw calls, dispatches, trace rays, and copies. The CPU call stack at the time of the command will be associated as the marker data for the automatically inserted checkpoints.

  • VK_DEVICE_DIAGNOSTICS_CONFIG_ENABLE_SHADER_ERROR_REPORTING_BIT_NV enables shader error reporting.

// Provided by VK_NV_device_diagnostics_config
typedef VkFlags VkDeviceDiagnosticsConfigFlagsNV;

VkDeviceDiagnosticsConfigFlagsNV is a bitmask type for setting a mask of zero or more VkDeviceDiagnosticsConfigFlagBitsNV.

To register callbacks for underlying device memory events of type VkDeviceMemoryReportEventTypeEXT, add one or multiple VkDeviceDeviceMemoryReportCreateInfoEXT structures to the pNext chain of the VkDeviceCreateInfo structure.

// Provided by VK_EXT_device_memory_report
typedef struct VkDeviceDeviceMemoryReportCreateInfoEXT {
    VkStructureType                        sType;
    const void*                            pNext;
    VkDeviceMemoryReportFlagsEXT           flags;
    PFN_vkDeviceMemoryReportCallbackEXT    pfnUserCallback;
    void*                                  pUserData;
} VkDeviceDeviceMemoryReportCreateInfoEXT;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • flags is 0 and reserved for future use.

  • pfnUserCallback is the application callback function to call.

  • pUserData is user data to be passed to the callback.

The callback may be called from multiple threads simultaneously.

The callback must be called only once by the implementation when a VkDeviceMemoryReportEventTypeEXT event occurs.

Note

The callback could be called from a background thread other than the thread calling the Vulkan commands.
Valid Usage (Implicit)

  • VUID-VkDeviceDeviceMemoryReportCreateInfoEXT-sType-sType
    sType must be VK_STRUCTURE_TYPE_DEVICE_DEVICE_MEMORY_REPORT_CREATE_INFO_EXT

  • VUID-VkDeviceDeviceMemoryReportCreateInfoEXT-flags-zerobitmask
    flags must be 0

  • VUID-VkDeviceDeviceMemoryReportCreateInfoEXT-pfnUserCallback-parameter
    pfnUserCallback must be a valid PFN_vkDeviceMemoryReportCallbackEXT value

  • VUID-VkDeviceDeviceMemoryReportCreateInfoEXT-pUserData-parameter
    pUserData must be a pointer value

The prototype for the VkDeviceDeviceMemoryReportCreateInfoEXT::pfnUserCallback function implemented by the application is:

// Provided by VK_EXT_device_memory_report
typedef void (VKAPI_PTR *PFN_vkDeviceMemoryReportCallbackEXT)(
    const VkDeviceMemoryReportCallbackDataEXT*  pCallbackData,
    void*                                       pUserData);

The callback must not make calls to any Vulkan commands.

The definition of VkDeviceMemoryReportCallbackDataEXT is:

// Provided by VK_EXT_device_memory_report
typedef struct VkDeviceMemoryReportCallbackDataEXT {
    VkStructureType                     sType;
    void*                               pNext;
    VkDeviceMemoryReportFlagsEXT        flags;
    VkDeviceMemoryReportEventTypeEXT    type;
    uint64_t                            memoryObjectId;
    VkDeviceSize                        size;
    VkObjectType                        objectType;
    uint64_t                            objectHandle;
    uint32_t                            heapIndex;
} VkDeviceMemoryReportCallbackDataEXT;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • flags is 0 and reserved for future use.

  • type is a VkDeviceMemoryReportEventTypeEXT type specifying the type of event reported in this VkDeviceMemoryReportCallbackDataEXT structure.

  • memoryObjectId is the unique id for the underlying memory object as described below.

  • size is the size of the memory object in bytes. If type is VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_ALLOCATE_EXT, VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_IMPORT_EXT or VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_ALLOCATION_FAILED_EXT, size is a valid VkDeviceSize value. Otherwise, size is undefined.

  • objectType is a VkObjectType value specifying the type of the object associated with this device memory report event. If type is VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_ALLOCATE_EXT, VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_FREE_EXT, VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_IMPORT_EXT, VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_UNIMPORT_EXT or VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_ALLOCATION_FAILED_EXT, objectType is a valid VkObjectType enum. Otherwise, objectType is undefined.

  • objectHandle is the object this device memory report event is attributed to. If type is VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_ALLOCATE_EXT, VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_FREE_EXT, VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_IMPORT_EXT or VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_UNIMPORT_EXT, objectHandle is a valid Vulkan handle of the type associated with objectType as defined in the VkObjectType and Vulkan Handle Relationship table. Otherwise, objectHandle is undefined.

  • heapIndex describes which memory heap this device memory allocation is made from. If type is VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_ALLOCATE_EXT or VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_ALLOCATION_FAILED_EXT, heapIndex corresponds to one of the valid heaps from the VkPhysicalDeviceMemoryProperties structure. Otherwise, heapIndex is undefined.

memoryObjectId is used to avoid double-counting on the same memory object.

If an internally-allocated device memory object or a VkDeviceMemory cannot be exported, memoryObjectId must be unique in the VkDevice.

If an internally-allocated device memory object or a VkDeviceMemory supports being exported, memoryObjectId must be unique system wide.

If an internal device memory object or a VkDeviceMemory is backed by an imported external memory object, memoryObjectId must be unique system wide.

Implementor’s Note

If the heap backing an internally-allocated device memory cannot be used to back VkDeviceMemory, implementations can advertise that heap with no types.

Note

This structure should only be considered valid during the lifetime of the triggered callback.

For VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_ALLOCATE_EXT and VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_IMPORT_EXT events, objectHandle usually will not yet exist when the application or tool receives the callback. objectHandle will only exist when the create or allocate call that triggered the event returns, and if the allocation or import ends up failing objectHandle will not ever exist.
Valid Usage (Implicit)

  • VUID-VkDeviceMemoryReportCallbackDataEXT-sType-sType
    sType must be VK_STRUCTURE_TYPE_DEVICE_MEMORY_REPORT_CALLBACK_DATA_EXT

  • VUID-VkDeviceMemoryReportCallbackDataEXT-pNext-pNext
    pNext must be NULL

// Provided by VK_EXT_device_memory_report
typedef VkFlags VkDeviceMemoryReportFlagsEXT;

VkDeviceMemoryReportFlagsEXT is a bitmask type for setting a mask, but is currently reserved for future use.

Possible values of VkDeviceMemoryReportCallbackDataEXT::type, specifying event types which cause the device driver to call the callback, are:

// Provided by VK_EXT_device_memory_report
typedef enum VkDeviceMemoryReportEventTypeEXT {
    VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_ALLOCATE_EXT = 0,
    VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_FREE_EXT = 1,
    VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_IMPORT_EXT = 2,
    VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_UNIMPORT_EXT = 3,
    VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_ALLOCATION_FAILED_EXT = 4,
} VkDeviceMemoryReportEventTypeEXT;

  • VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_ALLOCATE_EXT specifies this event corresponds to the allocation of an internal device memory object or a VkDeviceMemory.

  • VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_FREE_EXT specifies this event corresponds to the deallocation of an internally-allocated device memory object or a VkDeviceMemory.

  • VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_IMPORT_EXT specifies this event corresponds to the import of an external memory object.

  • VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_UNIMPORT_EXT specifies this event is the release of an imported external memory object.

  • VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_ALLOCATION_FAILED_EXT specifies this event corresponds to the failed allocation of an internal device memory object or a VkDeviceMemory.

To reserve private data storage slots, add a VkDevicePrivateDataCreateInfo structure to the pNext chain of the VkDeviceCreateInfo structure. Reserving slots in this manner is not strictly necessary, but doing so may improve performance.

// Provided by VK_VERSION_1_3
typedef struct VkDevicePrivateDataCreateInfo {
    VkStructureType    sType;
    const void*        pNext;
    uint32_t           privateDataSlotRequestCount;
} VkDevicePrivateDataCreateInfo;

or the equivalent

// Provided by VK_EXT_private_data
typedef VkDevicePrivateDataCreateInfo VkDevicePrivateDataCreateInfoEXT;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • privateDataSlotRequestCount is the amount of slots to reserve.

Valid Usage (Implicit)

  • VUID-VkDevicePrivateDataCreateInfo-sType-sType
    sType must be VK_STRUCTURE_TYPE_DEVICE_PRIVATE_DATA_CREATE_INFO

To disable the implementation’s internal pipeline cache, add a VkDevicePipelineBinaryInternalCacheControlKHR structure to the pNext chain of the VkDeviceCreateInfo structure.

// Provided by VK_KHR_pipeline_binary
typedef struct VkDevicePipelineBinaryInternalCacheControlKHR {
    VkStructureType    sType;
    const void*        pNext;
    VkBool32           disableInternalCache;
} VkDevicePipelineBinaryInternalCacheControlKHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • disableInternalCache specifies whether or not to disable the implementation’s internal pipeline cache.

If the VkDeviceCreateInfo::pNext chain does not include this structure, then disableInternalCache defaults to VK_FALSE.

Valid Usage
Valid Usage (Implicit)

  • VUID-VkDevicePipelineBinaryInternalCacheControlKHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_DEVICE_PIPELINE_BINARY_INTERNAL_CACHE_CONTROL_KHR

The number of shader cores used by all the queues of a device can be controlled by adding a VkDeviceQueueShaderCoreControlCreateInfoARM structure to the pNext chain of the VkDeviceCreateInfo structure.

5.2.2. Device Use

The following is a high-level list of VkDevice uses along with references on where to find more information:

5.2.3. Lost Device

A logical device may become lost for a number of implementation-specific reasons, indicating that pending and future command execution may fail and cause resources and backing memory to become undefined.

Note

Typical reasons for device loss will include things like execution timing out (to prevent denial of service), power management events, platform resource management, implementation errors.

Applications not adhering to valid usage may also result in device loss being reported, however this is not guaranteed. Even if device loss is reported, the system may be in an unrecoverable state, and further usage of the API is still considered invalid.

When this happens, certain commands will return VK_ERROR_DEVICE_LOST. After any such event, the logical device is considered lost. It is not possible to reset the logical device to a non-lost state, however the lost state is specific to a logical device (VkDevice), and the corresponding physical device (VkPhysicalDevice) may be otherwise unaffected.

In some cases, the physical device may also be lost, and attempting to create a new logical device will fail, returning VK_ERROR_DEVICE_LOST. This is usually indicative of a problem with the underlying implementation, or its connection to the host. If the physical device has not been lost, and a new logical device is successfully created from that physical device, it must be in the non-lost state.

Note

Whilst logical device loss may be recoverable, in the case of physical device loss, it is unlikely that an application will be able to recover unless additional, unaffected physical devices exist on the system. The error is largely informational and intended only to inform the application that a platform issue has occurred, and should be investigated further. For example, underlying hardware may have developed a fault or become physically disconnected from the rest of the system. In many cases, physical device loss may cause other more serious issues such as the operating system crashing; in which case it may not be reported via the Vulkan API.

When a device is lost, its child objects are not implicitly destroyed and their handles are still valid. Those objects must still be destroyed before their parents or the device can be destroyed (see the Object Lifetime section). The host address space corresponding to device memory mapped using vkMapMemory is still valid, and host memory accesses to these mapped regions are still valid, but the contents are undefined. It is still legal to call any API command on the device and child objects.

Once a device is lost, command execution may fail, and certain commands that return a VkResult may return VK_ERROR_DEVICE_LOST. These commands can be identified by the inclusion of VK_ERROR_DEVICE_LOST in the Return Codes section for each command. Commands that do not allow runtime errors must still operate correctly for valid usage and, if applicable, return valid data.

Commands that wait indefinitely for device execution (namely vkDeviceWaitIdle, vkQueueWaitIdle, vkWaitForFences or vkAcquireNextImageKHR with a maximum timeout, and vkGetQueryPoolResults with the VK_QUERY_RESULT_WAIT_BIT bit set in flags) must return in finite time even in the case of a lost device, and return either VK_SUCCESS or VK_ERROR_DEVICE_LOST. For any command that may return VK_ERROR_DEVICE_LOST, for the purpose of determining whether a command buffer is in the pending state, or whether resources are considered in-use by the device, a return value of VK_ERROR_DEVICE_LOST is equivalent to VK_SUCCESS.

If a device was created with the maintenance5 feature enabled, and any device command returns VK_ERROR_DEVICE_LOST, then all device commands for which VK_ERROR_DEVICE_LOST is a valid return value and which happen-after it on the same host thread must return VK_ERROR_DEVICE_LOST.

Device commands executing on other threads must begin returning VK_ERROR_DEVICE_LOST within finite time.

The content of any external memory objects that have been exported from or imported to a lost device become undefined. Objects on other logical devices or in other APIs which are associated with the same underlying memory resource as the external memory objects on the lost device are unaffected other than their content becoming undefined. The layout of subresources of images on other logical devices that are bound to VkDeviceMemory objects associated with the same underlying memory resources as external memory objects on the lost device becomes VK_IMAGE_LAYOUT_UNDEFINED.

The state of VkSemaphore objects on other logical devices created by importing a semaphore payload with temporary permanence which was exported from the lost device is undefined. The state of VkSemaphore objects on other logical devices that permanently share a semaphore payload with a VkSemaphore object on the lost device is undefined, and remains undefined following any subsequent signal operations. Implementations must ensure pending and subsequently submitted wait operations on such semaphores behave as defined in Semaphore State Requirements For Wait Operations for external semaphores not in a valid state for a wait operation.

5.2.4. Device Destruction

To destroy a device, call:

// Provided by VK_VERSION_1_0
void vkDestroyDevice(
    VkDevice                                    device,
    const VkAllocationCallbacks*                pAllocator);

  • device is the logical device to destroy.

  • pAllocator controls host memory allocation as described in the Memory Allocation chapter.

To ensure that no work is active on the device, vkDeviceWaitIdle can be used to gate the destruction of the device. Prior to destroying a device, an application is responsible for destroying/freeing any Vulkan objects that were created using that device as the first parameter of the corresponding vkCreate* or vkAllocate* command.

Note

The lifetime of each of these objects is bound by the lifetime of the VkDevice object. Therefore, to avoid resource leaks, it is critical that an application explicitly free all of these resources prior to calling vkDestroyDevice.
Valid Usage

  • VUID-vkDestroyDevice-device-05137
    All child objects created on device must have been destroyed prior to destroying device

  • VUID-vkDestroyDevice-device-00379
    If VkAllocationCallbacks were provided when device was created, a compatible set of callbacks must be provided here

  • VUID-vkDestroyDevice-device-00380
    If no VkAllocationCallbacks were provided when device was created, pAllocator must be NULL

Valid Usage (Implicit)

  • VUID-vkDestroyDevice-device-parameter
    If device is not NULL, device must be a valid VkDevice handle

  • VUID-vkDestroyDevice-pAllocator-parameter
    If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure

Host Synchronization

  • Host access to device must be externally synchronized

  • Host access to all VkQueue objects created from device must be externally synchronized

5.3. Queues

5.3.1. Queue Family Properties

As discussed in the Physical Device Enumeration section above, the vkGetPhysicalDeviceQueueFamilyProperties command is used to retrieve details about the queue families and queues supported by a device.

Each index in the pQueueFamilyProperties array returned by vkGetPhysicalDeviceQueueFamilyProperties describes a unique queue family on that physical device. These indices are used when creating queues, and they correspond directly with the queueFamilyIndex that is passed to the vkCreateDevice command via the VkDeviceQueueCreateInfo structure as described in the Queue Creation section below.

Grouping of queue families within a physical device is implementation-dependent.

Note

The general expectation is that a physical device groups all queues of matching capabilities into a single family. However, while implementations should do this, it is possible that a physical device may return two separate queue families with the same capabilities.

Once an application has identified a physical device with the queue(s) that it desires to use, it will create those queues in conjunction with a logical device. This is described in the following section.

5.3.2. Queue Creation

Creating a logical device also creates the queues associated with that device. The queues to create are described by a set of VkDeviceQueueCreateInfo structures that are passed to vkCreateDevice in pQueueCreateInfos.

Queues are represented by VkQueue handles:

// Provided by VK_VERSION_1_0
VK_DEFINE_HANDLE(VkQueue)

The VkDeviceQueueCreateInfo structure is defined as:

// Provided by VK_VERSION_1_0
typedef struct VkDeviceQueueCreateInfo {
    VkStructureType             sType;
    const void*                 pNext;
    VkDeviceQueueCreateFlags    flags;
    uint32_t                    queueFamilyIndex;
    uint32_t                    queueCount;
    const float*                pQueuePriorities;
} VkDeviceQueueCreateInfo;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • flags is a bitmask indicating behavior of the queues.

  • queueFamilyIndex is an unsigned integer indicating the index of the queue family in which to create the queues on this device. This index corresponds to the index of an element of the pQueueFamilyProperties array that was returned by vkGetPhysicalDeviceQueueFamilyProperties.

  • queueCount is an unsigned integer specifying the number of queues to create in the queue family indicated by queueFamilyIndex, and with the behavior specified by flags.

  • pQueuePriorities is a pointer to an array of queueCount normalized floating-point values, specifying priorities of work that will be submitted to each created queue. See Queue Priority for more information.

Valid Usage

  • VUID-VkDeviceQueueCreateInfo-queueFamilyIndex-00381
    queueFamilyIndex must be less than pQueueFamilyPropertyCount returned by vkGetPhysicalDeviceQueueFamilyProperties

  • VUID-VkDeviceQueueCreateInfo-queueCount-00382
    queueCount must be less than or equal to the queueCount member of the VkQueueFamilyProperties structure, as returned by vkGetPhysicalDeviceQueueFamilyProperties in the pQueueFamilyProperties[queueFamilyIndex]

  • VUID-VkDeviceQueueCreateInfo-pQueuePriorities-00383
    Each element of pQueuePriorities must be between 0.0 and 1.0 inclusive

  • VUID-VkDeviceQueueCreateInfo-flags-02861
    If the protectedMemory feature is not enabled, the VK_DEVICE_QUEUE_CREATE_PROTECTED_BIT bit of flags must not be set

  • VUID-VkDeviceQueueCreateInfo-flags-06449
    If flags includes VK_DEVICE_QUEUE_CREATE_PROTECTED_BIT, queueFamilyIndex must be the index of a queue family that includes the VK_QUEUE_PROTECTED_BIT capability

  • VUID-VkDeviceQueueCreateInfo-pNext-09398
    If the pNext chain includes a VkDeviceQueueShaderCoreControlCreateInfoARM structure then VkPhysicalDeviceSchedulingControlsPropertiesARM::schedulingControlsFlags must contain VK_PHYSICAL_DEVICE_SCHEDULING_CONTROLS_SHADER_CORE_COUNT_ARM

Valid Usage (Implicit)

  • VUID-VkDeviceQueueCreateInfo-sType-sType
    sType must be VK_STRUCTURE_TYPE_DEVICE_QUEUE_CREATE_INFO

  • VUID-VkDeviceQueueCreateInfo-pNext-pNext
    Each pNext member of any structure (including this one) in the pNext chain must be either NULL or a pointer to a valid instance of VkDeviceQueueGlobalPriorityCreateInfoKHR or VkDeviceQueueShaderCoreControlCreateInfoARM

  • VUID-VkDeviceQueueCreateInfo-sType-unique
    The sType value of each struct in the pNext chain must be unique

  • VUID-VkDeviceQueueCreateInfo-flags-parameter
    flags must be a valid combination of VkDeviceQueueCreateFlagBits values

  • VUID-VkDeviceQueueCreateInfo-pQueuePriorities-parameter
    pQueuePriorities must be a valid pointer to an array of queueCount float values

  • VUID-VkDeviceQueueCreateInfo-queueCount-arraylength
    queueCount must be greater than 0

Bits which can be set in VkDeviceQueueCreateInfo::flags, specifying usage behavior of a queue, are:

// Provided by VK_VERSION_1_1
typedef enum VkDeviceQueueCreateFlagBits {
  // Provided by VK_VERSION_1_1
    VK_DEVICE_QUEUE_CREATE_PROTECTED_BIT = 0x00000001,
} VkDeviceQueueCreateFlagBits;

  • VK_DEVICE_QUEUE_CREATE_PROTECTED_BIT specifies that the device queue is a protected-capable queue.

// Provided by VK_VERSION_1_0
typedef VkFlags VkDeviceQueueCreateFlags;

VkDeviceQueueCreateFlags is a bitmask type for setting a mask of zero or more VkDeviceQueueCreateFlagBits.

Queues can be created with a system-wide priority by adding a VkDeviceQueueGlobalPriorityCreateInfoKHR structure to the pNext chain of VkDeviceQueueCreateInfo.

The VkDeviceQueueGlobalPriorityCreateInfoKHR structure is defined as:

// Provided by VK_KHR_global_priority
typedef struct VkDeviceQueueGlobalPriorityCreateInfoKHR {
    VkStructureType             sType;
    const void*                 pNext;
    VkQueueGlobalPriorityKHR    globalPriority;
} VkDeviceQueueGlobalPriorityCreateInfoKHR;

or the equivalent

// Provided by VK_EXT_global_priority
typedef VkDeviceQueueGlobalPriorityCreateInfoKHR VkDeviceQueueGlobalPriorityCreateInfoEXT;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • globalPriority is the system-wide priority associated to these queues as specified by VkQueueGlobalPriorityKHR

Queues created without specifying VkDeviceQueueGlobalPriorityCreateInfoKHR will default to VK_QUEUE_GLOBAL_PRIORITY_MEDIUM_KHR.

Valid Usage (Implicit)

  • VUID-VkDeviceQueueGlobalPriorityCreateInfoKHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_DEVICE_QUEUE_GLOBAL_PRIORITY_CREATE_INFO_KHR

  • VUID-VkDeviceQueueGlobalPriorityCreateInfoKHR-globalPriority-parameter
    globalPriority must be a valid VkQueueGlobalPriorityKHR value

Possible values of VkDeviceQueueGlobalPriorityCreateInfoKHR::globalPriority, specifying a system-wide priority level are:

// Provided by VK_KHR_global_priority
typedef enum VkQueueGlobalPriorityKHR {
    VK_QUEUE_GLOBAL_PRIORITY_LOW_KHR = 128,
    VK_QUEUE_GLOBAL_PRIORITY_MEDIUM_KHR = 256,
    VK_QUEUE_GLOBAL_PRIORITY_HIGH_KHR = 512,
    VK_QUEUE_GLOBAL_PRIORITY_REALTIME_KHR = 1024,
    VK_QUEUE_GLOBAL_PRIORITY_LOW_EXT = VK_QUEUE_GLOBAL_PRIORITY_LOW_KHR,
    VK_QUEUE_GLOBAL_PRIORITY_MEDIUM_EXT = VK_QUEUE_GLOBAL_PRIORITY_MEDIUM_KHR,
    VK_QUEUE_GLOBAL_PRIORITY_HIGH_EXT = VK_QUEUE_GLOBAL_PRIORITY_HIGH_KHR,
    VK_QUEUE_GLOBAL_PRIORITY_REALTIME_EXT = VK_QUEUE_GLOBAL_PRIORITY_REALTIME_KHR,
} VkQueueGlobalPriorityKHR;

or the equivalent

// Provided by VK_EXT_global_priority
typedef VkQueueGlobalPriorityKHR VkQueueGlobalPriorityEXT;

Priority values are sorted in ascending order. A comparison operation on the enum values can be used to determine the priority order.

  • VK_QUEUE_GLOBAL_PRIORITY_LOW_KHR is below the system default. Useful for non-interactive tasks.

  • VK_QUEUE_GLOBAL_PRIORITY_MEDIUM_KHR is the system default priority.

  • VK_QUEUE_GLOBAL_PRIORITY_HIGH_KHR is above the system default.

  • VK_QUEUE_GLOBAL_PRIORITY_REALTIME_KHR is the highest priority. Useful for critical tasks.

Queues with higher system priority may be allotted more processing time than queues with lower priority. An implementation may allow a higher-priority queue to starve a lower-priority queue until the higher-priority queue has no further commands to execute.

Priorities imply no ordering or scheduling constraints.

No specific guarantees are made about higher priority queues receiving more processing time or better quality of service than lower priority queues.

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

Abuse of this feature may result in starving the rest of the system of implementation resources. Therefore, the driver implementation may deny requests to acquire a priority above the default priority (VK_QUEUE_GLOBAL_PRIORITY_MEDIUM_KHR) if the caller does not have sufficient privileges. In this scenario VK_ERROR_NOT_PERMITTED_KHR 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.

If the globalPriorityQuery feature is enabled and the requested global priority is not reported via VkQueueFamilyGlobalPriorityPropertiesKHR, the driver implementation must fail the queue creation. In this scenario, VK_ERROR_INITIALIZATION_FAILED is returned.

The number of shader cores used by a queue can be controlled by adding a VkDeviceQueueShaderCoreControlCreateInfoARM structure to the pNext chain of VkDeviceQueueCreateInfo structures.

The VkDeviceQueueShaderCoreControlCreateInfoARM structure is defined as:

// Provided by VK_ARM_scheduling_controls
typedef struct VkDeviceQueueShaderCoreControlCreateInfoARM {
    VkStructureType    sType;
    void*              pNext;
    uint32_t           shaderCoreCount;
} VkDeviceQueueShaderCoreControlCreateInfoARM;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • shaderCoreCount is the number of shader cores this queue uses.

Queues created without specifying VkDeviceQueueShaderCoreControlCreateInfoARM will default to using all the shader cores available.

Valid Usage

  • VUID-VkDeviceQueueShaderCoreControlCreateInfoARM-shaderCoreCount-09399
    shaderCoreCount must be greater than 0 and less than or equal to the total number of shader cores as reported via VkPhysicalDeviceShaderCoreBuiltinsPropertiesARM::shaderCoreCount

Valid Usage (Implicit)

  • VUID-VkDeviceQueueShaderCoreControlCreateInfoARM-sType-sType
    sType must be VK_STRUCTURE_TYPE_DEVICE_QUEUE_SHADER_CORE_CONTROL_CREATE_INFO_ARM

To retrieve a handle to a VkQueue object, call:

// Provided by VK_VERSION_1_0
void vkGetDeviceQueue(
    VkDevice                                    device,
    uint32_t                                    queueFamilyIndex,
    uint32_t                                    queueIndex,
    VkQueue*                                    pQueue);

  • device is the logical device that owns the queue.

  • queueFamilyIndex is the index of the queue family to which the queue belongs.

  • queueIndex is the index within this queue family of the queue to retrieve.

  • pQueue is a pointer to a VkQueue object that will be filled with the handle for the requested queue.

vkGetDeviceQueue must only be used to get queues that were created with the flags parameter of VkDeviceQueueCreateInfo set to zero. To get queues that were created with a non-zero flags parameter use vkGetDeviceQueue2.

Valid Usage

  • VUID-vkGetDeviceQueue-queueFamilyIndex-00384
    queueFamilyIndex must be one of the queue family indices specified when device was created, via the VkDeviceQueueCreateInfo structure

  • VUID-vkGetDeviceQueue-queueIndex-00385
    queueIndex must be less than the value of VkDeviceQueueCreateInfo::queueCount for the queue family indicated by queueFamilyIndex when device was created

  • VUID-vkGetDeviceQueue-flags-01841
    VkDeviceQueueCreateInfo::flags must have been set to zero when device was created

Valid Usage (Implicit)

  • VUID-vkGetDeviceQueue-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkGetDeviceQueue-pQueue-parameter
    pQueue must be a valid pointer to a VkQueue handle

To retrieve a handle to a VkQueue object with specific VkDeviceQueueCreateFlags creation flags, call:

// Provided by VK_VERSION_1_1
void vkGetDeviceQueue2(
    VkDevice                                    device,
    const VkDeviceQueueInfo2*                   pQueueInfo,
    VkQueue*                                    pQueue);

  • device is the logical device that owns the queue.

  • pQueueInfo is a pointer to a VkDeviceQueueInfo2 structure, describing parameters of the device queue to be retrieved.

  • pQueue is a pointer to a VkQueue object that will be filled with the handle for the requested queue.

Valid Usage (Implicit)

  • VUID-vkGetDeviceQueue2-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkGetDeviceQueue2-pQueueInfo-parameter
    pQueueInfo must be a valid pointer to a valid VkDeviceQueueInfo2 structure

  • VUID-vkGetDeviceQueue2-pQueue-parameter
    pQueue must be a valid pointer to a VkQueue handle

The VkDeviceQueueInfo2 structure is defined as:

// Provided by VK_VERSION_1_1
typedef struct VkDeviceQueueInfo2 {
    VkStructureType             sType;
    const void*                 pNext;
    VkDeviceQueueCreateFlags    flags;
    uint32_t                    queueFamilyIndex;
    uint32_t                    queueIndex;
} VkDeviceQueueInfo2;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure. The pNext chain of VkDeviceQueueInfo2 can be used to provide additional device queue parameters to vkGetDeviceQueue2.

  • flags is a VkDeviceQueueCreateFlags value indicating the flags used to create the device queue.

  • queueFamilyIndex is the index of the queue family to which the queue belongs.

  • queueIndex is the index of the queue to retrieve from within the set of queues that share both the queue family and flags specified.

The queue returned by vkGetDeviceQueue2 must have the same flags value from this structure as that used at device creation time in a VkDeviceQueueCreateInfo structure.

Note

Normally, if you create both protected-capable and non-protected-capable queues with the same family, they are treated as separate lists of queues and queueIndex is relative to the start of the list of queues specified by both queueFamilyIndex and flags. However, for historical reasons, some implementations may exhibit different behavior. These divergent implementations instead concatenate the lists of queues and treat queueIndex as relative to the start of the first list of queues with the given queueFamilyIndex. This only matters in cases where an application has created both protected-capable and non-protected-capable queues from the same queue family.

For such divergent implementations, the maximum value of queueIndex is equal to the sum of VkDeviceQueueCreateInfo::queueCount minus one, for all VkDeviceQueueCreateInfo structures that share a common queueFamilyIndex.

Such implementations will return NULL for either the protected or unprotected queues when calling vkGetDeviceQueue2 with queueIndex in the range zero to VkDeviceQueueCreateInfo::queueCount minus one. In cases where these implementations returned NULL, the corresponding queues are instead located in the extended range described in the preceding two paragraphs.

This behavior will not be observed on any driver that has passed Vulkan conformance test suite version 1.3.3.0, or any subsequent version. This information can be found by querying VkPhysicalDeviceDriverProperties::conformanceVersion.
Valid Usage

  • VUID-VkDeviceQueueInfo2-queueFamilyIndex-01842
    queueFamilyIndex must be one of the queue family indices specified when device was created, via the VkDeviceQueueCreateInfo structure

  • VUID-VkDeviceQueueInfo2-flags-06225
    flags must be equal to VkDeviceQueueCreateInfo::flags for a VkDeviceQueueCreateInfo structure for the queue family indicated by queueFamilyIndex when device was created

  • VUID-VkDeviceQueueInfo2-queueIndex-01843
    queueIndex must be less than VkDeviceQueueCreateInfo::queueCount for the corresponding queue family and flags indicated by queueFamilyIndex and flags when device was created

Valid Usage (Implicit)

  • VUID-VkDeviceQueueInfo2-sType-sType
    sType must be VK_STRUCTURE_TYPE_DEVICE_QUEUE_INFO_2

  • VUID-VkDeviceQueueInfo2-pNext-pNext
    pNext must be NULL

  • VUID-VkDeviceQueueInfo2-flags-parameter
    flags must be a valid combination of VkDeviceQueueCreateFlagBits values

5.3.3. Queue Family Index

The queue family index is used in multiple places in Vulkan in order to tie operations to a specific family of queues.

When retrieving a handle to the queue via vkGetDeviceQueue, the queue family index is used to select which queue family to retrieve the VkQueue handle from as described in the previous section.

When creating a VkCommandPool object (see Command Pools), a queue family index is specified in the VkCommandPoolCreateInfo structure. Command buffers from this pool can only be submitted on queues corresponding to this queue family.

When creating VkImage (see Images) and VkBuffer (see Buffers) resources, a set of queue families is included in the VkImageCreateInfo and VkBufferCreateInfo structures to specify the queue families that can access the resource.

When inserting a VkBufferMemoryBarrier or VkImageMemoryBarrier (see Pipeline Barriers), a source and destination queue family index is specified to allow the ownership of a buffer or image to be transferred from one queue family to another. See the Resource Sharing section for details.

5.3.4. Queue Priority

Each queue is assigned a priority, as set in the VkDeviceQueueCreateInfo structures when creating the device. The priority of each queue is a normalized floating-point value between 0.0 and 1.0, which is then translated to a discrete priority level by the implementation. Higher values indicate a higher priority, with 0.0 being the lowest priority and 1.0 being the highest.

Within the same device, queues with higher priority may be allotted more processing time than queues with lower priority. The implementation makes no guarantees with regards to ordering or scheduling among queues with the same priority, other than the constraints defined by any explicit synchronization primitives. The implementation makes no guarantees with regards to queues across different devices.

An implementation may allow a higher-priority queue to starve a lower-priority queue on the same VkDevice until the higher-priority queue has no further commands to execute. The relationship of queue priorities must not cause queues on one VkDevice to starve queues on another VkDevice.

No specific guarantees are made about higher priority queues receiving more processing time or better quality of service than lower priority queues.

5.3.5. Queue Submission

Work is submitted to a queue via queue submission commands such as vkQueueSubmit2 or vkQueueSubmit. Queue submission commands define a set of queue operations to be executed by the underlying physical device, including synchronization with semaphores and fences.

Submission commands take as parameters a target queue, zero or more batches of work, and an optional fence to signal upon completion. Each batch consists of three distinct parts:

  1. Zero or more semaphores to wait on before execution of the rest of the batch.

  2. Zero or more work items to execute.

    • If present, these describe a queue operation matching the work described.

  3. Zero or more semaphores to signal upon completion of the work items.

If a fence is present in a queue submission, it describes a fence signal operation.

All work described by a queue submission command must be submitted to the queue before the command returns.

Sparse Memory Binding

In Vulkan it is possible to sparsely bind memory to buffers and images as described in the Sparse Resource chapter. Sparse memory binding is a queue operation. A queue whose flags include the VK_QUEUE_SPARSE_BINDING_BIT must be able to support the mapping of a virtual address to a physical address on the device. This causes an update to the page table mappings on the device. This update must be synchronized on a queue to avoid corrupting page table mappings during execution of graphics commands. By binding the sparse memory resources on queues, all commands that are dependent on the updated bindings are synchronized to only execute after the binding is updated. See the Synchronization and Cache Control chapter for how this synchronization is accomplished.

5.3.6. Queue Destruction

Queues are created along with a logical device during vkCreateDevice. All queues associated with a logical device are destroyed when vkDestroyDevice is called on that device.

6. Command Buffers

Command buffers are objects used to record commands which can be subsequently submitted to a device queue for execution. There are two levels of command buffers - primary command buffers, which can execute secondary command buffers, and which are submitted to queues, and secondary command buffers, which can be executed by primary command buffers, and which are not directly submitted to queues.

Command buffers are represented by VkCommandBuffer handles:

// Provided by VK_VERSION_1_0
VK_DEFINE_HANDLE(VkCommandBuffer)

Recorded commands include commands to bind pipelines and descriptor sets to the command buffer, commands to modify dynamic state, commands to draw (for graphics rendering), commands to dispatch (for compute), commands to execute secondary command buffers (for primary command buffers only), commands to copy buffers and images, and other commands.

Each command buffer manages state independently of other command buffers. There is no inheritance of state across primary and secondary command buffers, or between secondary command buffers. When a command buffer begins recording, all state in that command buffer is undefined. When secondary command buffer(s) are recorded to execute on a primary command buffer, the secondary command buffer inherits no state from the primary command buffer, and all state of the primary command buffer is undefined after an execute secondary command buffer command is recorded. There is one exception to this rule - if the primary command buffer is inside a render pass instance, then the render pass and subpass state is not disturbed by executing secondary command buffers. For state dependent commands (such as draws and dispatches), any state consumed by those commands must not be undefined.

VkCommandBufferInheritanceViewportScissorInfoNV defines an exception allowing limited inheritance of dynamic viewport and scissor state.

Unless otherwise specified, and without explicit synchronization, the various commands submitted to a queue via command buffers may execute in arbitrary order relative to each other, and/or concurrently. Also, the memory side effects of those commands may not be directly visible to other commands without explicit memory dependencies. This is true within a command buffer, and across command buffers submitted to a given queue. See the synchronization chapter for information on implicit and explicit synchronization between commands.

6.1. Command Buffer Lifecycle

Each command buffer is always in one of the following states:

Initial

When a command buffer is allocated, it is in the initial state. Some commands are able to reset a command buffer (or a set of command buffers) back to this state from any of the executable, recording or invalid state. Command buffers in the initial state can only be moved to the recording state, or freed.

Recording

vkBeginCommandBuffer changes the state of a command buffer from the initial state to the recording state. Once a command buffer is in the recording state, vkCmd* commands can be used to record to the command buffer.

Executable

vkEndCommandBuffer ends the recording of a command buffer, and moves it from the recording state to the executable state. Executable command buffers can be submitted, reset, or recorded to another command buffer.

Pending

Queue submission of a command buffer changes the state of a command buffer from the executable state to the pending state. Whilst in the pending state, applications must not attempt to modify the command buffer in any way - as the device may be processing the commands recorded to it. Once execution of a command buffer completes, the command buffer either reverts back to the executable state, or if it was recorded with VK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT, it moves to the invalid state. A synchronization command should be used to detect when this occurs.

Invalid

Some operations, such as modifying or deleting a resource that was used in a command recorded to a command buffer, will transition the state of that command buffer into the invalid state. Command buffers in the invalid state can only be reset or freed.

image/svg+xml Initial Recording Pending Executable Invalid Allocate Begin End Submission Completion Completion withOne Time Submit Reset Reset Invalidate
Figure 1. Lifecycle of a command buffer

Any given command that operates on a command buffer has its own requirements on what state a command buffer must be in, which are detailed in the valid usage constraints for that command.

Resetting a command buffer is an operation that discards any previously recorded commands and puts a command buffer in the initial state. Resetting occurs as a result of vkResetCommandBuffer or vkResetCommandPool, or as part of vkBeginCommandBuffer (which additionally puts the command buffer in the recording state).

Secondary command buffers can be recorded to a primary command buffer via vkCmdExecuteCommands. This partially ties the lifecycle of the two command buffers together - if the primary is submitted to a queue, both the primary and any secondaries recorded to it move to the pending state. Once execution of the primary completes, so it does for any secondary recorded within it. After all executions of each command buffer complete, they each move to their appropriate completion state (either to the executable state or the invalid state, as specified above).

If a secondary moves to the invalid state or the initial state, then all primary buffers it is recorded in move to the invalid state. A primary moving to any other state does not affect the state of a secondary recorded in it.

Note

Resetting or freeing a primary command buffer removes the lifecycle linkage to all secondary command buffers that were recorded into it.

6.2. Command Pools

Command pools are opaque objects that command buffer memory is allocated from, and which allow the implementation to amortize the cost of resource creation across multiple command buffers. Command pools are externally synchronized, meaning that a command pool must not be used concurrently in multiple threads. That includes use via recording commands on any command buffers allocated from the pool, as well as operations that allocate, free, and reset command buffers or the pool itself.

Command pools are represented by VkCommandPool handles:

// Provided by VK_VERSION_1_0
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkCommandPool)

To create a command pool, call:

// Provided by VK_VERSION_1_0
VkResult vkCreateCommandPool(
    VkDevice                                    device,
    const VkCommandPoolCreateInfo*              pCreateInfo,
    const VkAllocationCallbacks*                pAllocator,
    VkCommandPool*                              pCommandPool);

  • device is the logical device that creates the command pool.

  • pCreateInfo is a pointer to a VkCommandPoolCreateInfo structure specifying the state of the command pool object.

  • pAllocator controls host memory allocation as described in the Memory Allocation chapter.

  • pCommandPool is a pointer to a VkCommandPool handle in which the created pool is returned.

Valid Usage

  • VUID-vkCreateCommandPool-queueFamilyIndex-01937
    pCreateInfo->queueFamilyIndex must be the index of a queue family available in the logical device device

Valid Usage (Implicit)

  • VUID-vkCreateCommandPool-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkCreateCommandPool-pCreateInfo-parameter
    pCreateInfo must be a valid pointer to a valid VkCommandPoolCreateInfo structure

  • VUID-vkCreateCommandPool-pAllocator-parameter
    If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure

  • VUID-vkCreateCommandPool-pCommandPool-parameter
    pCommandPool must be a valid pointer to a VkCommandPool handle

Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

The VkCommandPoolCreateInfo structure is defined as:

// Provided by VK_VERSION_1_0
typedef struct VkCommandPoolCreateInfo {
    VkStructureType             sType;
    const void*                 pNext;
    VkCommandPoolCreateFlags    flags;
    uint32_t                    queueFamilyIndex;
} VkCommandPoolCreateInfo;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • flags is a bitmask of VkCommandPoolCreateFlagBits indicating usage behavior for the pool and command buffers allocated from it.

  • queueFamilyIndex designates a queue family as described in section Queue Family Properties. All command buffers allocated from this command pool must be submitted on queues from the same queue family.

Valid Usage

  • VUID-VkCommandPoolCreateInfo-flags-02860
    If the protectedMemory feature is not enabled, the VK_COMMAND_POOL_CREATE_PROTECTED_BIT bit of flags must not be set

Valid Usage (Implicit)

  • VUID-VkCommandPoolCreateInfo-sType-sType
    sType must be VK_STRUCTURE_TYPE_COMMAND_POOL_CREATE_INFO

  • VUID-VkCommandPoolCreateInfo-pNext-pNext
    pNext must be NULL

  • VUID-VkCommandPoolCreateInfo-flags-parameter
    flags must be a valid combination of VkCommandPoolCreateFlagBits values

Bits which can be set in VkCommandPoolCreateInfo::flags, specifying usage behavior for a command pool, are:

// Provided by VK_VERSION_1_0
typedef enum VkCommandPoolCreateFlagBits {
    VK_COMMAND_POOL_CREATE_TRANSIENT_BIT = 0x00000001,
    VK_COMMAND_POOL_CREATE_RESET_COMMAND_BUFFER_BIT = 0x00000002,
  // Provided by VK_VERSION_1_1
    VK_COMMAND_POOL_CREATE_PROTECTED_BIT = 0x00000004,
} VkCommandPoolCreateFlagBits;

  • VK_COMMAND_POOL_CREATE_TRANSIENT_BIT specifies that command buffers allocated from the pool will be short-lived, meaning that they will be reset or freed in a relatively short timeframe. This flag may be used by the implementation to control memory allocation behavior within the pool.

  • VK_COMMAND_POOL_CREATE_RESET_COMMAND_BUFFER_BIT allows any command buffer allocated from a pool to be individually reset to the initial state; either by calling vkResetCommandBuffer, or via the implicit reset when calling vkBeginCommandBuffer. If this flag is not set on a pool, then vkResetCommandBuffer must not be called for any command buffer allocated from that pool.

  • VK_COMMAND_POOL_CREATE_PROTECTED_BIT specifies that command buffers allocated from the pool are protected command buffers.

// Provided by VK_VERSION_1_0
typedef VkFlags VkCommandPoolCreateFlags;

VkCommandPoolCreateFlags is a bitmask type for setting a mask of zero or more VkCommandPoolCreateFlagBits.

To trim a command pool, call:

// Provided by VK_VERSION_1_1
void vkTrimCommandPool(
    VkDevice                                    device,
    VkCommandPool                               commandPool,
    VkCommandPoolTrimFlags                      flags);

or the equivalent command

// Provided by VK_KHR_maintenance1
void vkTrimCommandPoolKHR(
    VkDevice                                    device,
    VkCommandPool                               commandPool,
    VkCommandPoolTrimFlags                      flags);

  • device is the logical device that owns the command pool.

  • commandPool is the command pool to trim.

  • flags is reserved for future use.

Trimming a command pool recycles unused memory from the command pool back to the system. Command buffers allocated from the pool are not affected by the command.

Note

This command provides applications with some control over the internal memory allocations used by command pools.

Unused memory normally arises from command buffers that have been recorded and later reset, such that they are no longer using the memory. On reset, a command buffer can return memory to its command pool, but the only way to release memory from a command pool to the system requires calling vkResetCommandPool, which cannot be executed while any command buffers from that pool are still in use. Subsequent recording operations into command buffers will reuse this memory but since total memory requirements fluctuate over time, unused memory can accumulate.

In this situation, trimming a command pool may be useful to return unused memory back to the system, returning the total outstanding memory allocated by the pool back to a more “average” value.

Implementations utilize many internal allocation strategies that make it impossible to guarantee that all unused memory is released back to the system. For instance, an implementation of a command pool may involve allocating memory in bulk from the system and sub-allocating from that memory. In such an implementation any live command buffer that holds a reference to a bulk allocation would prevent that allocation from being freed, even if only a small proportion of the bulk allocation is in use.

In most cases trimming will result in a reduction in allocated but unused memory, but it does not guarantee the “ideal” behavior.

Trimming may be an expensive operation, and should not be called frequently. Trimming should be treated as a way to relieve memory pressure after application-known points when there exists enough unused memory that the cost of trimming is “worth” it.
Valid Usage (Implicit)

  • VUID-vkTrimCommandPool-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkTrimCommandPool-commandPool-parameter
    commandPool must be a valid VkCommandPool handle

  • VUID-vkTrimCommandPool-flags-zerobitmask
    flags must be 0

  • VUID-vkTrimCommandPool-commandPool-parent
    commandPool must have been created, allocated, or retrieved from device

Host Synchronization

  • Host access to commandPool must be externally synchronized

// Provided by VK_VERSION_1_1
typedef VkFlags VkCommandPoolTrimFlags;

or the equivalent

// Provided by VK_KHR_maintenance1
typedef VkCommandPoolTrimFlags VkCommandPoolTrimFlagsKHR;

VkCommandPoolTrimFlags is a bitmask type for setting a mask, but is currently reserved for future use.

To reset a command pool, call:

// Provided by VK_VERSION_1_0
VkResult vkResetCommandPool(
    VkDevice                                    device,
    VkCommandPool                               commandPool,
    VkCommandPoolResetFlags                     flags);

  • device is the logical device that owns the command pool.

  • commandPool is the command pool to reset.

  • flags is a bitmask of VkCommandPoolResetFlagBits controlling the reset operation.

Resetting a command pool recycles all of the resources from all of the command buffers allocated from the command pool back to the command pool. All command buffers that have been allocated from the command pool are put in the initial state.

Any primary command buffer allocated from another VkCommandPool that is in the recording or executable state and has a secondary command buffer allocated from commandPool recorded into it, becomes invalid.

Valid Usage

  • VUID-vkResetCommandPool-commandPool-00040
    All VkCommandBuffer objects allocated from commandPool must not be in the pending state

Valid Usage (Implicit)

  • VUID-vkResetCommandPool-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkResetCommandPool-commandPool-parameter
    commandPool must be a valid VkCommandPool handle

  • VUID-vkResetCommandPool-flags-parameter
    flags must be a valid combination of VkCommandPoolResetFlagBits values

  • VUID-vkResetCommandPool-commandPool-parent
    commandPool must have been created, allocated, or retrieved from device

Host Synchronization

  • Host access to commandPool must be externally synchronized

Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

Bits which can be set in vkResetCommandPool::flags, controlling the reset operation, are:

// Provided by VK_VERSION_1_0
typedef enum VkCommandPoolResetFlagBits {
    VK_COMMAND_POOL_RESET_RELEASE_RESOURCES_BIT = 0x00000001,
} VkCommandPoolResetFlagBits;

  • VK_COMMAND_POOL_RESET_RELEASE_RESOURCES_BIT specifies that resetting a command pool recycles all of the resources from the command pool back to the system.

// Provided by VK_VERSION_1_0
typedef VkFlags VkCommandPoolResetFlags;

VkCommandPoolResetFlags is a bitmask type for setting a mask of zero or more VkCommandPoolResetFlagBits.

To destroy a command pool, call:

// Provided by VK_VERSION_1_0
void vkDestroyCommandPool(
    VkDevice                                    device,
    VkCommandPool                               commandPool,
    const VkAllocationCallbacks*                pAllocator);

  • device is the logical device that destroys the command pool.

  • commandPool is the handle of the command pool to destroy.

  • pAllocator controls host memory allocation as described in the Memory Allocation chapter.

When a pool is destroyed, all command buffers allocated from the pool are freed.

Any primary command buffer allocated from another VkCommandPool that is in the recording or executable state and has a secondary command buffer allocated from commandPool recorded into it, becomes invalid.

Valid Usage

  • VUID-vkDestroyCommandPool-commandPool-00041
    All VkCommandBuffer objects allocated from commandPool must not be in the pending state

  • VUID-vkDestroyCommandPool-commandPool-00042
    If VkAllocationCallbacks were provided when commandPool was created, a compatible set of callbacks must be provided here

  • VUID-vkDestroyCommandPool-commandPool-00043
    If no VkAllocationCallbacks were provided when commandPool was created, pAllocator must be NULL

Valid Usage (Implicit)

  • VUID-vkDestroyCommandPool-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkDestroyCommandPool-commandPool-parameter
    If commandPool is not VK_NULL_HANDLE, commandPool must be a valid VkCommandPool handle

  • VUID-vkDestroyCommandPool-pAllocator-parameter
    If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure

  • VUID-vkDestroyCommandPool-commandPool-parent
    If commandPool is a valid handle, it must have been created, allocated, or retrieved from device

Host Synchronization

  • Host access to commandPool must be externally synchronized

6.3. Command Buffer Allocation and Management

To allocate command buffers, call:

// Provided by VK_VERSION_1_0
VkResult vkAllocateCommandBuffers(
    VkDevice                                    device,
    const VkCommandBufferAllocateInfo*          pAllocateInfo,
    VkCommandBuffer*                            pCommandBuffers);

  • device is the logical device that owns the command pool.

  • pAllocateInfo is a pointer to a VkCommandBufferAllocateInfo structure describing parameters of the allocation.

  • pCommandBuffers is a pointer to an array of VkCommandBuffer handles in which the resulting command buffer objects are returned. The array must be at least the length specified by the commandBufferCount member of pAllocateInfo. Each allocated command buffer begins in the initial state.

vkAllocateCommandBuffers can be used to allocate multiple command buffers. If the allocation of any of those command buffers fails, the implementation must free all successfully allocated command buffer objects from this command, set all entries of the pCommandBuffers array to NULL and return the error.

Note

Filling pCommandBuffers with NULL values on failure is an exception to the default error behavior that output parameters will have undefined contents.

When command buffers are first allocated, they are in the initial state.

Valid Usage (Implicit)

  • VUID-vkAllocateCommandBuffers-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkAllocateCommandBuffers-pAllocateInfo-parameter
    pAllocateInfo must be a valid pointer to a valid VkCommandBufferAllocateInfo structure

  • VUID-vkAllocateCommandBuffers-pCommandBuffers-parameter
    pCommandBuffers must be a valid pointer to an array of pAllocateInfo->commandBufferCount VkCommandBuffer handles

  • VUID-vkAllocateCommandBuffers-pAllocateInfo::commandBufferCount-arraylength
    pAllocateInfo->commandBufferCount must be greater than 0

Host Synchronization

  • Host access to pAllocateInfo->commandPool must be externally synchronized

Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

The VkCommandBufferAllocateInfo structure is defined as:

// Provided by VK_VERSION_1_0
typedef struct VkCommandBufferAllocateInfo {
    VkStructureType         sType;
    const void*             pNext;
    VkCommandPool           commandPool;
    VkCommandBufferLevel    level;
    uint32_t                commandBufferCount;
} VkCommandBufferAllocateInfo;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • commandPool is the command pool from which the command buffers are allocated.

  • level is a VkCommandBufferLevel value specifying the command buffer level.

  • commandBufferCount is the number of command buffers to allocate from the pool.

Valid Usage (Implicit)

  • VUID-VkCommandBufferAllocateInfo-sType-sType
    sType must be VK_STRUCTURE_TYPE_COMMAND_BUFFER_ALLOCATE_INFO

  • VUID-VkCommandBufferAllocateInfo-pNext-pNext
    pNext must be NULL

  • VUID-VkCommandBufferAllocateInfo-commandPool-parameter
    commandPool must be a valid VkCommandPool handle

  • VUID-VkCommandBufferAllocateInfo-level-parameter
    level must be a valid VkCommandBufferLevel value

Possible values of VkCommandBufferAllocateInfo::level, specifying the command buffer level, are:

// Provided by VK_VERSION_1_0
typedef enum VkCommandBufferLevel {
    VK_COMMAND_BUFFER_LEVEL_PRIMARY = 0,
    VK_COMMAND_BUFFER_LEVEL_SECONDARY = 1,
} VkCommandBufferLevel;

  • VK_COMMAND_BUFFER_LEVEL_PRIMARY specifies a primary command buffer.

  • VK_COMMAND_BUFFER_LEVEL_SECONDARY specifies a secondary command buffer.

To reset a command buffer, call:

// Provided by VK_VERSION_1_0
VkResult vkResetCommandBuffer(
    VkCommandBuffer                             commandBuffer,
    VkCommandBufferResetFlags                   flags);

Any primary command buffer that is in the recording or executable state and has commandBuffer recorded into it, becomes invalid.

Valid Usage

  • VUID-vkResetCommandBuffer-commandBuffer-00045
    commandBuffer must not be in the pending state

  • VUID-vkResetCommandBuffer-commandBuffer-00046
    commandBuffer must have been allocated from a pool that was created with the VK_COMMAND_POOL_CREATE_RESET_COMMAND_BUFFER_BIT

Valid Usage (Implicit)

  • VUID-vkResetCommandBuffer-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkResetCommandBuffer-flags-parameter
    flags must be a valid combination of VkCommandBufferResetFlagBits values

Host Synchronization

  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

Bits which can be set in vkResetCommandBuffer::flags, controlling the reset operation, are:

// Provided by VK_VERSION_1_0
typedef enum VkCommandBufferResetFlagBits {
    VK_COMMAND_BUFFER_RESET_RELEASE_RESOURCES_BIT = 0x00000001,
} VkCommandBufferResetFlagBits;

  • VK_COMMAND_BUFFER_RESET_RELEASE_RESOURCES_BIT specifies that most or all memory resources currently owned by the command buffer should be returned to the parent command pool. If this flag is not set, then the command buffer may hold onto memory resources and reuse them when recording commands. commandBuffer is moved to the initial state.

// Provided by VK_VERSION_1_0
typedef VkFlags VkCommandBufferResetFlags;

VkCommandBufferResetFlags is a bitmask type for setting a mask of zero or more VkCommandBufferResetFlagBits.

To free command buffers, call:

// Provided by VK_VERSION_1_0
void vkFreeCommandBuffers(
    VkDevice                                    device,
    VkCommandPool                               commandPool,
    uint32_t                                    commandBufferCount,
    const VkCommandBuffer*                      pCommandBuffers);

  • device is the logical device that owns the command pool.

  • commandPool is the command pool from which the command buffers were allocated.

  • commandBufferCount is the length of the pCommandBuffers array.

  • pCommandBuffers is a pointer to an array of handles of command buffers to free.

Any primary command buffer that is in the recording or executable state and has any element of pCommandBuffers recorded into it, becomes invalid.

Valid Usage

  • VUID-vkFreeCommandBuffers-pCommandBuffers-00047
    All elements of pCommandBuffers must not be in the pending state

  • VUID-vkFreeCommandBuffers-pCommandBuffers-00048
    pCommandBuffers must be a valid pointer to an array of commandBufferCount VkCommandBuffer handles, each element of which must either be a valid handle or NULL

Valid Usage (Implicit)

  • VUID-vkFreeCommandBuffers-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkFreeCommandBuffers-commandPool-parameter
    commandPool must be a valid VkCommandPool handle

  • VUID-vkFreeCommandBuffers-commandBufferCount-arraylength
    commandBufferCount must be greater than 0

  • VUID-vkFreeCommandBuffers-commandPool-parent
    commandPool must have been created, allocated, or retrieved from device

  • VUID-vkFreeCommandBuffers-pCommandBuffers-parent
    Each element of pCommandBuffers that is a valid handle must have been created, allocated, or retrieved from commandPool

Host Synchronization

  • Host access to commandPool must be externally synchronized

  • Host access to each member of pCommandBuffers must be externally synchronized

6.4. Command Buffer Recording

To begin recording a command buffer, call:

// Provided by VK_VERSION_1_0
VkResult vkBeginCommandBuffer(
    VkCommandBuffer                             commandBuffer,
    const VkCommandBufferBeginInfo*             pBeginInfo);

  • commandBuffer is the handle of the command buffer which is to be put in the recording state.

  • pBeginInfo is a pointer to a VkCommandBufferBeginInfo structure defining additional information about how the command buffer begins recording.

Valid Usage

  • VUID-vkBeginCommandBuffer-commandBuffer-00049
    commandBuffer must not be in the recording or pending state

  • VUID-vkBeginCommandBuffer-commandBuffer-00050
    If commandBuffer was allocated from a VkCommandPool which did not have the VK_COMMAND_POOL_CREATE_RESET_COMMAND_BUFFER_BIT flag set, commandBuffer must be in the initial state

  • VUID-vkBeginCommandBuffer-commandBuffer-00051
    If commandBuffer is a secondary command buffer, the pInheritanceInfo member of pBeginInfo must be a valid VkCommandBufferInheritanceInfo structure

  • VUID-vkBeginCommandBuffer-commandBuffer-00052
    If commandBuffer is a secondary command buffer and either the occlusionQueryEnable member of the pInheritanceInfo member of pBeginInfo is VK_FALSE, or the occlusionQueryPrecise feature is not enabled, then pBeginInfo->pInheritanceInfo->queryFlags must not contain VK_QUERY_CONTROL_PRECISE_BIT

  • VUID-vkBeginCommandBuffer-commandBuffer-02840
    If commandBuffer is a primary command buffer, then pBeginInfo->flags must not set both the VK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT and the VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT flags

Valid Usage (Implicit)

  • VUID-vkBeginCommandBuffer-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkBeginCommandBuffer-pBeginInfo-parameter
    pBeginInfo must be a valid pointer to a valid VkCommandBufferBeginInfo structure

Host Synchronization

  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

The VkCommandBufferBeginInfo structure is defined as:

// Provided by VK_VERSION_1_0
typedef struct VkCommandBufferBeginInfo {
    VkStructureType                          sType;
    const void*                              pNext;
    VkCommandBufferUsageFlags                flags;
    const VkCommandBufferInheritanceInfo*    pInheritanceInfo;
} VkCommandBufferBeginInfo;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • flags is a bitmask of VkCommandBufferUsageFlagBits specifying usage behavior for the command buffer.

  • pInheritanceInfo is a pointer to a VkCommandBufferInheritanceInfo structure, used if commandBuffer is a secondary command buffer. If this is a primary command buffer, then this value is ignored.

Valid Usage

  • VUID-VkCommandBufferBeginInfo-flags-09123
    If flags contains VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT, the VkCommandPool that commandBuffer was allocated from must support graphics operations

  • VUID-VkCommandBufferBeginInfo-flags-00055
    If flags contains VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT, the framebuffer member of pInheritanceInfo must be either VK_NULL_HANDLE, or a valid VkFramebuffer that is compatible with the renderPass member of pInheritanceInfo

  • VUID-VkCommandBufferBeginInfo-flags-09240
    If flags contains VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT and the dynamicRendering feature is not enabled, the renderPass member of pInheritanceInfo must not be VK_NULL_HANDLE

  • VUID-VkCommandBufferBeginInfo-flags-06002
    If flags contains VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT and the renderPass member of pInheritanceInfo is VK_NULL_HANDLE, the pNext chain of pInheritanceInfo must include a VkCommandBufferInheritanceRenderingInfo structure

  • VUID-VkCommandBufferBeginInfo-flags-06003
    If flags contains VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT, the renderPass member of pInheritanceInfo is VK_NULL_HANDLE, and the pNext chain of pInheritanceInfo includes a VkAttachmentSampleCountInfoAMD or VkAttachmentSampleCountInfoNV structure, the colorAttachmentCount member of that structure must be equal to the value of VkCommandBufferInheritanceRenderingInfo::colorAttachmentCount

  • VUID-VkCommandBufferBeginInfo-flags-06000
    If flags contains VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT and the renderPass member of pInheritanceInfo is not VK_NULL_HANDLE, the renderPass member of pInheritanceInfo must be a valid VkRenderPass

  • VUID-VkCommandBufferBeginInfo-flags-06001
    If flags contains VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT and the renderPass member of pInheritanceInfo is not VK_NULL_HANDLE, the subpass member of pInheritanceInfo must be a valid subpass index within the renderPass member of pInheritanceInfo

Valid Usage (Implicit)

  • VUID-VkCommandBufferBeginInfo-sType-sType
    sType must be VK_STRUCTURE_TYPE_COMMAND_BUFFER_BEGIN_INFO

  • VUID-VkCommandBufferBeginInfo-pNext-pNext
    pNext must be NULL or a pointer to a valid instance of VkDeviceGroupCommandBufferBeginInfo

  • VUID-VkCommandBufferBeginInfo-sType-unique
    The sType value of each struct in the pNext chain must be unique

  • VUID-VkCommandBufferBeginInfo-flags-parameter
    flags must be a valid combination of VkCommandBufferUsageFlagBits values

Bits which can be set in VkCommandBufferBeginInfo::flags, specifying usage behavior for a command buffer, are:

// Provided by VK_VERSION_1_0
typedef enum VkCommandBufferUsageFlagBits {
    VK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT = 0x00000001,
    VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT = 0x00000002,
    VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT = 0x00000004,
} VkCommandBufferUsageFlagBits;

  • VK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT specifies that each recording of the command buffer will only be submitted once, and the command buffer will be reset and recorded again between each submission.

  • VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT specifies that a secondary command buffer is considered to be entirely inside a render pass. If this is a primary command buffer, then this bit is ignored.

  • VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT specifies that a command buffer can be resubmitted to any queue of the same queue family while it is in the pending state, and recorded into multiple primary command buffers.

// Provided by VK_VERSION_1_0
typedef VkFlags VkCommandBufferUsageFlags;

VkCommandBufferUsageFlags is a bitmask type for setting a mask of zero or more VkCommandBufferUsageFlagBits.

If the command buffer is a secondary command buffer, then the VkCommandBufferInheritanceInfo structure defines any state that will be inherited from the primary command buffer:

// Provided by VK_VERSION_1_0
typedef struct VkCommandBufferInheritanceInfo {
    VkStructureType                  sType;
    const void*                      pNext;
    VkRenderPass                     renderPass;
    uint32_t                         subpass;
    VkFramebuffer                    framebuffer;
    VkBool32                         occlusionQueryEnable;
    VkQueryControlFlags              queryFlags;
    VkQueryPipelineStatisticFlags    pipelineStatistics;
} VkCommandBufferInheritanceInfo;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • renderPass is a VkRenderPass object defining which render passes the VkCommandBuffer will be compatible with and can be executed within.

  • subpass is the index of the subpass within the render pass instance that the VkCommandBuffer will be executed within.

  • framebuffer can refer to the VkFramebuffer object that the VkCommandBuffer will be rendering to if it is executed within a render pass instance. It can be VK_NULL_HANDLE if the framebuffer is not known.

    Note

    Specifying the exact framebuffer that the secondary command buffer will be executed with may result in better performance at command buffer execution time.

  • occlusionQueryEnable specifies whether the command buffer can be executed while an occlusion query is active in the primary command buffer. If this is VK_TRUE, then this command buffer can be executed whether the primary command buffer has an occlusion query active or not. If this is VK_FALSE, then the primary command buffer must not have an occlusion query active.

  • queryFlags specifies the query flags that can be used by an active occlusion query in the primary command buffer when this secondary command buffer is executed. If this value includes the VK_QUERY_CONTROL_PRECISE_BIT bit, then the active query can return boolean results or actual sample counts. If this bit is not set, then the active query must not use the VK_QUERY_CONTROL_PRECISE_BIT bit.

  • pipelineStatistics is a bitmask of VkQueryPipelineStatisticFlagBits specifying the set of pipeline statistics that can be counted by an active query in the primary command buffer when this secondary command buffer is executed. If this value includes a given bit, then this command buffer can be executed whether the primary command buffer has a pipeline statistics query active that includes this bit or not. If this value excludes a given bit, then the active pipeline statistics query must not be from a query pool that counts that statistic.

If the VkCommandBuffer will not be executed within a render pass instance, or if the render pass instance was begun with vkCmdBeginRendering, renderPass, subpass, and framebuffer are ignored.

Valid Usage

  • VUID-VkCommandBufferInheritanceInfo-occlusionQueryEnable-00056
    If the inheritedQueries feature is not enabled, occlusionQueryEnable must be VK_FALSE

  • VUID-VkCommandBufferInheritanceInfo-queryFlags-00057
    If the inheritedQueries feature is enabled, queryFlags must be a valid combination of VkQueryControlFlagBits values

  • VUID-VkCommandBufferInheritanceInfo-queryFlags-02788
    If the inheritedQueries feature is not enabled, queryFlags must be 0

  • VUID-VkCommandBufferInheritanceInfo-pipelineStatistics-02789
    If the pipelineStatisticsQuery feature is enabled, pipelineStatistics must be a valid combination of VkQueryPipelineStatisticFlagBits values

  • VUID-VkCommandBufferInheritanceInfo-pipelineStatistics-00058
    If the pipelineStatisticsQuery feature is not enabled, pipelineStatistics must be 0

Valid Usage (Implicit)
Note

On some implementations, not using the VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT bit enables command buffers to be patched in-place if needed, rather than creating a copy of the command buffer.

If a command buffer is in the invalid, or executable state, and the command buffer was allocated from a command pool with the VK_COMMAND_POOL_CREATE_RESET_COMMAND_BUFFER_BIT flag set, then vkBeginCommandBuffer implicitly resets the command buffer, behaving as if vkResetCommandBuffer had been called with VK_COMMAND_BUFFER_RESET_RELEASE_RESOURCES_BIT not set. After the implicit reset, commandBuffer is moved to the recording state.

If the commandBufferInheritance feature is enabled, all graphics and compute state including bound pipeline state, bound shader objects, bound vertex and index buffers, bound descriptor sets and push constants, and all previously set dynamic state is inherited by the secondary command buffer from the primary or secondary command buffer that executes it. Furthermore, all of the state set by this secondary command buffer is inherited back to the primary or secondard command buffer that executes it. If the commandBufferInheritance feature is not enabled there is a limited amount of inheritance of state into the secondary command buffer as specified below.

If the pNext chain of VkCommandBufferInheritanceInfo includes a VkCommandBufferInheritanceConditionalRenderingInfoEXT structure, then that structure controls whether a command buffer can be executed while conditional rendering is active in the primary command buffer.

The VkCommandBufferInheritanceConditionalRenderingInfoEXT structure is defined as:

// Provided by VK_EXT_conditional_rendering
typedef struct VkCommandBufferInheritanceConditionalRenderingInfoEXT {
    VkStructureType    sType;
    const void*        pNext;
    VkBool32           conditionalRenderingEnable;
} VkCommandBufferInheritanceConditionalRenderingInfoEXT;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • conditionalRenderingEnable specifies whether the command buffer can be executed while conditional rendering is active in the primary command buffer. If this is VK_TRUE, then this command buffer can be executed whether the primary command buffer has active conditional rendering or not. If this is VK_FALSE, then the primary command buffer must not have conditional rendering active.

If this structure is not present, the behavior is as if conditionalRenderingEnable is VK_FALSE.

Valid Usage

  • VUID-VkCommandBufferInheritanceConditionalRenderingInfoEXT-conditionalRenderingEnable-01977
    If the inheritedConditionalRendering feature is not enabled, conditionalRenderingEnable must be VK_FALSE

Valid Usage (Implicit)

  • VUID-VkCommandBufferInheritanceConditionalRenderingInfoEXT-sType-sType
    sType must be VK_STRUCTURE_TYPE_COMMAND_BUFFER_INHERITANCE_CONDITIONAL_RENDERING_INFO_EXT

To begin recording a secondary command buffer compatible with execution inside a render pass using render pass transform, add the VkCommandBufferInheritanceRenderPassTransformInfoQCOM to the pNext chain of VkCommandBufferInheritanceInfo structure passed to the vkBeginCommandBuffer command specifying the parameters for transformed rasterization.

The VkCommandBufferInheritanceRenderPassTransformInfoQCOM structure is defined as:

// Provided by VK_QCOM_render_pass_transform
typedef struct VkCommandBufferInheritanceRenderPassTransformInfoQCOM {
    VkStructureType                  sType;
    void*                            pNext;
    VkSurfaceTransformFlagBitsKHR    transform;
    VkRect2D                         renderArea;
} VkCommandBufferInheritanceRenderPassTransformInfoQCOM;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • transform is a VkSurfaceTransformFlagBitsKHR value describing the transform to be applied to the render pass.

  • renderArea is the render area that is affected by the command buffer.

When the secondary is recorded to execute within a render pass instance using vkCmdExecuteCommands, the render pass transform parameters of the secondary command buffer must be consistent with the render pass transform parameters specified for the render pass instance. In particular, the transform and renderArea for command buffer must be identical to the transform and renderArea of the render pass instance.

Valid Usage

  • VUID-VkCommandBufferInheritanceRenderPassTransformInfoQCOM-transform-02864
    transform must be VK_SURFACE_TRANSFORM_IDENTITY_BIT_KHR, VK_SURFACE_TRANSFORM_ROTATE_90_BIT_KHR, VK_SURFACE_TRANSFORM_ROTATE_180_BIT_KHR, or VK_SURFACE_TRANSFORM_ROTATE_270_BIT_KHR

Valid Usage (Implicit)

  • VUID-VkCommandBufferInheritanceRenderPassTransformInfoQCOM-sType-sType
    sType must be VK_STRUCTURE_TYPE_COMMAND_BUFFER_INHERITANCE_RENDER_PASS_TRANSFORM_INFO_QCOM

The VkCommandBufferInheritanceViewportScissorInfoNV structure is defined as:

// Provided by VK_NV_inherited_viewport_scissor
typedef struct VkCommandBufferInheritanceViewportScissorInfoNV {
    VkStructureType      sType;
    const void*          pNext;
    VkBool32             viewportScissor2D;
    uint32_t             viewportDepthCount;
    const VkViewport*    pViewportDepths;
} VkCommandBufferInheritanceViewportScissorInfoNV;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • viewportScissor2D specifies whether the listed dynamic state is inherited.

  • viewportDepthCount specifies the maximum number of viewports to inherit. When viewportScissor2D is VK_FALSE, the behavior is as if this value is zero.

  • pViewportDepths is a pointer to a VkViewport structure specifying the expected depth range for each inherited viewport.

If the pNext chain of VkCommandBufferInheritanceInfo includes a VkCommandBufferInheritanceViewportScissorInfoNV structure, then that structure controls whether a command buffer can inherit the following state from other command buffers:

  • VK_DYNAMIC_STATE_SCISSOR

  • VK_DYNAMIC_STATE_SCISSOR_WITH_COUNT

  • VK_DYNAMIC_STATE_DISCARD_RECTANGLE_EXT

  • VK_DYNAMIC_STATE_DISCARD_RECTANGLE_ENABLE_EXT

  • VK_DYNAMIC_STATE_DISCARD_RECTANGLE_MODE_EXT

as well as the following state, with restrictions on inherited depth values and viewport count:

  • VK_DYNAMIC_STATE_VIEWPORT

  • VK_DYNAMIC_STATE_VIEWPORT_WITH_COUNT

If viewportScissor2D is VK_FALSE, then the command buffer does not inherit the listed dynamic state, and should set this state itself. If this structure is not present, the behavior is as if viewportScissor2D is VK_FALSE.

If viewportScissor2D is VK_TRUE, then the listed dynamic state is inherited, and the command buffer must not set this state, except that the viewport and scissor count may be set by binding a graphics pipeline that does not specify this state as dynamic.

Note

Due to this restriction, applications should ensure either all or none of the graphics pipelines bound in this secondary command buffer use dynamic viewport/scissor counts.

When the command buffer is executed as part of a the execution of a vkCmdExecuteCommands command, the inherited state (if enabled) is determined by the following procedure, performed separately for each dynamic state, and separately for each value for dynamic state that consists of multiple values (e.g. multiple viewports).

  • With i being the index of the executed command buffer in the pCommandBuffers array of vkCmdExecuteCommands, if i > 0 and any secondary command buffer from index 0 to i-1 modifies the state, the inherited state is provisionally set to the final value set by the last such secondary command buffer. Binding a graphics pipeline defining the state statically is equivalent to setting the state to an undefined value.

  • Otherwise, the tentatative inherited state is that of the primary command buffer at the point the vkCmdExecuteCommands command was recorded; if the state is undefined, then so is the provisional inherited state.

  • If the provisional inherited state is an undefined value, then the state is not inherited.

  • If the provisional inherited state is a viewport, with n being its viewport index, then if n ≥ viewportDepthCount, or if either VkViewport::minDepth or VkViewport::maxDepth are not equal to the respective values of the nth element of pViewportDepths, then the state is not inherited.

  • If the provisional inherited state passes both checks, then it becomes the actual inherited state.

Note

There is no support for inheriting dynamic state from a secondary command buffer executed as part of a different vkCmdExecuteCommands command.
Valid Usage

  • VUID-VkCommandBufferInheritanceViewportScissorInfoNV-viewportScissor2D-04782
    If the inheritedViewportScissor2D feature is not enabled, viewportScissor2D must be VK_FALSE

  • VUID-VkCommandBufferInheritanceViewportScissorInfoNV-viewportScissor2D-04783
    If the multiViewport feature is not enabled and viewportScissor2D is VK_TRUE, then viewportDepthCount must be 1

  • VUID-VkCommandBufferInheritanceViewportScissorInfoNV-viewportScissor2D-04784
    If viewportScissor2D is VK_TRUE, then viewportDepthCount must be greater than 0

  • VUID-VkCommandBufferInheritanceViewportScissorInfoNV-viewportScissor2D-04785
    If viewportScissor2D is VK_TRUE, then pViewportDepths must be a valid pointer to an array of viewportDepthCount valid VkViewport structures, except any requirements on x, y, width, and height do not apply

  • VUID-VkCommandBufferInheritanceViewportScissorInfoNV-viewportScissor2D-04786
    If viewportScissor2D is VK_TRUE, then the command buffer must be recorded with the VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT

Valid Usage (Implicit)

  • VUID-VkCommandBufferInheritanceViewportScissorInfoNV-sType-sType
    sType must be VK_STRUCTURE_TYPE_COMMAND_BUFFER_INHERITANCE_VIEWPORT_SCISSOR_INFO_NV

The VkCommandBufferInheritanceRenderingInfo structure is defined as:

// Provided by VK_VERSION_1_3
typedef struct VkCommandBufferInheritanceRenderingInfo {
    VkStructureType          sType;
    const void*              pNext;
    VkRenderingFlags         flags;
    uint32_t                 viewMask;
    uint32_t                 colorAttachmentCount;
    const VkFormat*          pColorAttachmentFormats;
    VkFormat                 depthAttachmentFormat;
    VkFormat                 stencilAttachmentFormat;
    VkSampleCountFlagBits    rasterizationSamples;
} VkCommandBufferInheritanceRenderingInfo;

or the equivalent

// Provided by VK_KHR_dynamic_rendering
typedef VkCommandBufferInheritanceRenderingInfo VkCommandBufferInheritanceRenderingInfoKHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure

  • flags is a bitmask of VkRenderingFlagBits used by the render pass instance.

  • viewMask is the view mask used for rendering.

  • colorAttachmentCount is the number of color attachments specified in the render pass instance.

  • pColorAttachmentFormats is a pointer to an array of VkFormat values defining the format of color attachments.

  • depthAttachmentFormat is a VkFormat value defining the format of the depth attachment.

  • stencilAttachmentFormat is a VkFormat value defining the format of the stencil attachment.

  • rasterizationSamples is a VkSampleCountFlagBits specifying the number of samples used in rasterization.

If the pNext chain of VkCommandBufferInheritanceInfo includes a VkCommandBufferInheritanceRenderingInfo structure, then that structure controls parameters of dynamic render pass instances that the VkCommandBuffer can be executed within. If VkCommandBufferInheritanceInfo::renderPass is not VK_NULL_HANDLE, or VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT is not specified in VkCommandBufferBeginInfo::flags, parameters of this structure are ignored.

If colorAttachmentCount is 0 and the variableMultisampleRate feature is enabled, rasterizationSamples is ignored.

If depthAttachmentFormat, stencilAttachmentFormat, or any element of pColorAttachmentFormats is VK_FORMAT_UNDEFINED, it indicates that the corresponding attachment is unused within the render pass and writes to those attachments are discarded.

Valid Usage

  • VUID-VkCommandBufferInheritanceRenderingInfo-colorAttachmentCount-06004
    If colorAttachmentCount is not 0, rasterizationSamples must be a valid VkSampleCountFlagBits value

  • VUID-VkCommandBufferInheritanceRenderingInfo-variableMultisampleRate-06005
    If the variableMultisampleRate feature is not enabled, rasterizationSamples must be a valid VkSampleCountFlagBits value

  • VUID-VkCommandBufferInheritanceRenderingInfo-depthAttachmentFormat-06540
    If depthAttachmentFormat is not VK_FORMAT_UNDEFINED, it must be a format that includes a depth component

  • VUID-VkCommandBufferInheritanceRenderingInfo-depthAttachmentFormat-06007
    If depthAttachmentFormat is not VK_FORMAT_UNDEFINED, it must be a format with potential format features that include VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT

  • VUID-VkCommandBufferInheritanceRenderingInfo-pColorAttachmentFormats-06492
    If any element of pColorAttachmentFormats is not VK_FORMAT_UNDEFINED, it must be a format with potential format features that include VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT , or VK_FORMAT_FEATURE_2_LINEAR_COLOR_ATTACHMENT_BIT_NV if the linearColorAttachment feature is enabled

  • VUID-VkCommandBufferInheritanceRenderingInfo-stencilAttachmentFormat-06541
    If stencilAttachmentFormat is not VK_FORMAT_UNDEFINED, it must be a format that includes a stencil aspect

  • VUID-VkCommandBufferInheritanceRenderingInfo-stencilAttachmentFormat-06199
    If stencilAttachmentFormat is not VK_FORMAT_UNDEFINED, it must be a format with potential format features that include VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT

  • VUID-VkCommandBufferInheritanceRenderingInfo-depthAttachmentFormat-06200
    If depthAttachmentFormat is not VK_FORMAT_UNDEFINED and stencilAttachmentFormat is not VK_FORMAT_UNDEFINED, depthAttachmentFormat must equal stencilAttachmentFormat

  • VUID-VkCommandBufferInheritanceRenderingInfo-multiview-06008
    If the multiview feature is not enabled, viewMask must be 0

  • VUID-VkCommandBufferInheritanceRenderingInfo-viewMask-06009
    The index of the most significant bit in viewMask must be less than maxMultiviewViewCount

Valid Usage (Implicit)

  • VUID-VkCommandBufferInheritanceRenderingInfo-sType-sType
    sType must be VK_STRUCTURE_TYPE_COMMAND_BUFFER_INHERITANCE_RENDERING_INFO

  • VUID-VkCommandBufferInheritanceRenderingInfo-flags-parameter
    flags must be a valid combination of VkRenderingFlagBits values

  • VUID-VkCommandBufferInheritanceRenderingInfo-pColorAttachmentFormats-parameter
    If colorAttachmentCount is not 0, pColorAttachmentFormats must be a valid pointer to an array of colorAttachmentCount valid VkFormat values

  • VUID-VkCommandBufferInheritanceRenderingInfo-depthAttachmentFormat-parameter
    depthAttachmentFormat must be a valid VkFormat value

  • VUID-VkCommandBufferInheritanceRenderingInfo-stencilAttachmentFormat-parameter
    stencilAttachmentFormat must be a valid VkFormat value

  • VUID-VkCommandBufferInheritanceRenderingInfo-rasterizationSamples-parameter
    If rasterizationSamples is not 0, rasterizationSamples must be a valid VkSampleCountFlagBits value

The VkAttachmentSampleCountInfoAMD or VkAttachmentSampleCountInfoNV structure is defined as:

// Provided by VK_KHR_dynamic_rendering with VK_AMD_mixed_attachment_samples
typedef struct VkAttachmentSampleCountInfoAMD {
    VkStructureType                 sType;
    const void*                     pNext;
    uint32_t                        colorAttachmentCount;
    const VkSampleCountFlagBits*    pColorAttachmentSamples;
    VkSampleCountFlagBits           depthStencilAttachmentSamples;
} VkAttachmentSampleCountInfoAMD;

or the equivalent

// Provided by VK_KHR_dynamic_rendering with VK_NV_framebuffer_mixed_samples
typedef VkAttachmentSampleCountInfoAMD VkAttachmentSampleCountInfoNV;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure

  • colorAttachmentCount is the number of color attachments specified in a render pass instance.

  • pColorAttachmentSamples is a pointer to an array of VkSampleCountFlagBits values defining the sample count of color attachments.

  • depthStencilAttachmentSamples is a VkSampleCountFlagBits value defining the sample count of a depth/stencil attachment.

If VkCommandBufferInheritanceInfo::renderPass is VK_NULL_HANDLE, VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT is specified in VkCommandBufferBeginInfo::flags, and the pNext chain of VkCommandBufferInheritanceInfo includes VkAttachmentSampleCountInfoAMD, then this structure defines the sample counts of each attachment within the render pass instance. If VkAttachmentSampleCountInfoAMD is not included, the value of VkCommandBufferInheritanceRenderingInfo::rasterizationSamples is used as the sample count for each attachment. If VkCommandBufferInheritanceInfo::renderPass is not VK_NULL_HANDLE, or VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT is not specified in VkCommandBufferBeginInfo::flags, parameters of this structure are ignored.

VkAttachmentSampleCountInfoAMD can also be included in the pNext chain of VkGraphicsPipelineCreateInfo. When a graphics pipeline is created without a VkRenderPass, if this structure is included in the pNext chain of VkGraphicsPipelineCreateInfo, it specifies the sample count of attachments used for rendering. If this structure is not specified, and the pipeline does not include a VkRenderPass, the value of VkPipelineMultisampleStateCreateInfo::rasterizationSamples is used as the sample count for each attachment. If a graphics pipeline is created with a valid VkRenderPass, parameters of this structure are ignored.

Valid Usage (Implicit)

  • VUID-VkAttachmentSampleCountInfoAMD-sType-sType
    sType must be VK_STRUCTURE_TYPE_ATTACHMENT_SAMPLE_COUNT_INFO_AMD

Once recording starts, an application records a sequence of commands (vkCmd*) to set state in the command buffer, draw, dispatch, and other commands.

Several commands can also be recorded indirectly from VkBuffer content, see Device-Generated Commands.

To complete recording of a command buffer, call:

// Provided by VK_VERSION_1_0
VkResult vkEndCommandBuffer(
    VkCommandBuffer                             commandBuffer);

  • commandBuffer is the command buffer to complete recording.

The command buffer must have been in the recording state, and, if successful, is moved to the executable state.

If there was an error during recording, the application will be notified by an unsuccessful return code returned by vkEndCommandBuffer, and the command buffer will be moved to the invalid state.

In case the application recorded one or more video encode operations into the command buffer, implementations may return the VK_ERROR_INVALID_VIDEO_STD_PARAMETERS_KHR error if any of the specified Video Std parameters do not adhere to the syntactic or semantic requirements of the used video compression standard, or if values derived from parameters according to the rules defined by the used video compression standard do not adhere to the capabilities of the video compression standard or the implementation.

Note

Applications should not rely on the VK_ERROR_INVALID_VIDEO_STD_PARAMETERS_KHR error being returned by any command as a means to verify Video Std parameters, as implementations are not required to report the error in any specific set of cases.
Valid Usage

  • VUID-vkEndCommandBuffer-commandBuffer-00059
    commandBuffer must be in the recording state

  • VUID-vkEndCommandBuffer-commandBuffer-00060
    If commandBuffer is a primary command buffer, there must not be an active render pass instance

  • VUID-vkEndCommandBuffer-commandBuffer-00061
    All queries made active during the recording of commandBuffer must have been made inactive

  • VUID-vkEndCommandBuffer-None-01978
    Conditional rendering must not be active

  • VUID-vkEndCommandBuffer-None-06991
    There must be no video session object bound

  • VUID-vkEndCommandBuffer-commandBuffer-01815
    If commandBuffer is a secondary command buffer, there must not be an outstanding vkCmdBeginDebugUtilsLabelEXT command recorded to commandBuffer that has not previously been ended by a call to vkCmdEndDebugUtilsLabelEXT

  • VUID-vkEndCommandBuffer-commandBuffer-00062
    If commandBuffer is a secondary command buffer, there must not be an outstanding vkCmdDebugMarkerBeginEXT command recorded to commandBuffer that has not previously been ended by a call to vkCmdDebugMarkerEndEXT

Valid Usage (Implicit)

  • VUID-vkEndCommandBuffer-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

Host Synchronization

  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

  • VK_ERROR_INVALID_VIDEO_STD_PARAMETERS_KHR

When a command buffer is in the executable state, it can be submitted to a queue for execution.

6.5. Command Buffer Submission

Note

Submission can be a high overhead operation, and applications should attempt to batch work together into as few calls to vkQueueSubmit or vkQueueSubmit2 as possible.

To submit command buffers to a queue, call:

// Provided by VK_VERSION_1_3
VkResult vkQueueSubmit2(
    VkQueue                                     queue,
    uint32_t                                    submitCount,
    const VkSubmitInfo2*                        pSubmits,
    VkFence                                     fence);

or the equivalent command

// Provided by VK_KHR_synchronization2
VkResult vkQueueSubmit2KHR(
    VkQueue                                     queue,
    uint32_t                                    submitCount,
    const VkSubmitInfo2*                        pSubmits,
    VkFence                                     fence);

  • queue is the queue that the command buffers will be submitted to.

  • submitCount is the number of elements in the pSubmits array.

  • pSubmits is a pointer to an array of VkSubmitInfo2 structures, each specifying a command buffer submission batch.

  • fence is an optional handle to a fence to be signaled once all submitted command buffers have completed execution. If fence is not VK_NULL_HANDLE, it defines a fence signal operation.

vkQueueSubmit2 is a queue submission command, with each batch defined by an element of pSubmits.

Semaphore operations submitted with vkQueueSubmit2 have additional ordering constraints compared to other submission commands, with dependencies involving previous and subsequent queue operations. Information about these additional constraints can be found in the semaphore section of the synchronization chapter.

If any command buffer submitted to this queue is in the executable state, it is moved to the pending state. Once execution of all submissions of a command buffer complete, it moves from the pending state, back to the executable state. If a command buffer was recorded with the VK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT flag, it instead moves back to the invalid state.

If vkQueueSubmit2 fails, it may return VK_ERROR_OUT_OF_HOST_MEMORY or VK_ERROR_OUT_OF_DEVICE_MEMORY. If it does, the implementation must ensure that the state and contents of any resources or synchronization primitives referenced by the submitted command buffers and any semaphores referenced by pSubmits is unaffected by the call or its failure. If vkQueueSubmit2 fails in such a way that the implementation is unable to make that guarantee, the implementation must return VK_ERROR_DEVICE_LOST. See Lost Device.

Valid Usage

  • VUID-vkQueueSubmit2-fence-04894
    If fence is not VK_NULL_HANDLE, fence must be unsignaled

  • VUID-vkQueueSubmit2-fence-04895
    If fence is not VK_NULL_HANDLE, fence must not be associated with any other queue command that has not yet completed execution on that queue

  • VUID-vkQueueSubmit2-synchronization2-03866
    The synchronization2 feature must be enabled

  • VUID-vkQueueSubmit2-commandBuffer-03867
    If a command recorded into the commandBuffer member of any element of the pCommandBufferInfos member of any element of pSubmits referenced a VkEvent, that event must not be referenced by a command that has been submitted to another queue and is still in the pending state

  • VUID-vkQueueSubmit2-semaphore-03868
    The semaphore member of any binary semaphore element of the pSignalSemaphoreInfos member of any element of pSubmits must be unsignaled when the semaphore signal operation it defines is executed on the device

  • VUID-vkQueueSubmit2-stageMask-03869
    The stageMask member of any element of the pSignalSemaphoreInfos member of any element of pSubmits must only include pipeline stages that are supported by the queue family which queue belongs to

  • VUID-vkQueueSubmit2-stageMask-03870
    The stageMask member of any element of the pWaitSemaphoreInfos member of any element of pSubmits must only include pipeline stages that are supported by the queue family which queue belongs to

  • VUID-vkQueueSubmit2-semaphore-03871
    When a semaphore wait operation for a binary semaphore is executed, as defined by the semaphore member of any element of the pWaitSemaphoreInfos member of any element of pSubmits, there must be no other queues waiting on the same semaphore

  • VUID-vkQueueSubmit2-semaphore-03873
    The semaphore member of any element of the pWaitSemaphoreInfos member of any element of pSubmits that was created with a VkSemaphoreTypeKHR of VK_SEMAPHORE_TYPE_BINARY_KHR must reference a semaphore signal operation that has been submitted for execution and any semaphore signal operations on which it depends must have also been submitted for execution

  • VUID-vkQueueSubmit2-commandBuffer-03874
    The commandBuffer member of any element of the pCommandBufferInfos member of any element of pSubmits must be in the pending or executable state

  • VUID-vkQueueSubmit2-commandBuffer-03875
    If a command recorded into the commandBuffer member of any element of the pCommandBufferInfos member of any element of pSubmits was not recorded with the VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT, it must not be in the pending state

  • VUID-vkQueueSubmit2-commandBuffer-03876
    Any secondary command buffers recorded into the commandBuffer member of any element of the pCommandBufferInfos member of any element of pSubmits must be in the pending or executable state

  • VUID-vkQueueSubmit2-commandBuffer-03877
    If any secondary command buffers recorded into the commandBuffer member of any element of the pCommandBufferInfos member of any element of pSubmits was not recorded with the VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT, it must not be in the pending state

  • VUID-vkQueueSubmit2-commandBuffer-03878
    The commandBuffer member of any element of the pCommandBufferInfos member of any element of pSubmits must have been allocated from a VkCommandPool that was created for the same queue family queue belongs to

  • VUID-vkQueueSubmit2-commandBuffer-03879
    If a command recorded into the commandBuffer member of any element of the pCommandBufferInfos member of any element of pSubmits includes a Queue Family Ownership Transfer Acquire Operation, there must exist a previously submitted Queue Family Ownership Transfer Release Operation on a queue in the queue family identified by the acquire operation, with parameters matching the acquire operation as defined in the definition of such acquire operations, and which happens before the acquire operation

  • VUID-vkQueueSubmit2-commandBuffer-03880
    If a command recorded into the commandBuffer member of any element of the pCommandBufferInfos member of any element of pSubmits was a vkCmdBeginQuery whose queryPool was created with a queryType of VK_QUERY_TYPE_PERFORMANCE_QUERY_KHR, the profiling lock must have been held continuously on the VkDevice that queue was retrieved from, throughout recording of those command buffers

  • VUID-vkQueueSubmit2-queue-06447
    If queue was not created with VK_DEVICE_QUEUE_CREATE_PROTECTED_BIT, the flags member of any element of pSubmits must not include VK_SUBMIT_PROTECTED_BIT_KHR

Valid Usage (Implicit)

  • VUID-vkQueueSubmit2-queue-parameter
    queue must be a valid VkQueue handle

  • VUID-vkQueueSubmit2-pSubmits-parameter
    If submitCount is not 0, pSubmits must be a valid pointer to an array of submitCount valid VkSubmitInfo2 structures

  • VUID-vkQueueSubmit2-fence-parameter
    If fence is not VK_NULL_HANDLE, fence must be a valid VkFence handle

  • VUID-vkQueueSubmit2-commonparent
    Both of fence, and queue that are valid handles of non-ignored parameters must have been created, allocated, or retrieved from the same VkDevice

Host Synchronization

  • Host access to queue must be externally synchronized

  • Host access to fence must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Video Coding Scope Supported Queue Types Command Type

-

-

-

Any

-
Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

  • VK_ERROR_DEVICE_LOST

The VkSubmitInfo2 structure is defined as:

// Provided by VK_VERSION_1_3
typedef struct VkSubmitInfo2 {
    VkStructureType                     sType;
    const void*                         pNext;
    VkSubmitFlags                       flags;
    uint32_t                            waitSemaphoreInfoCount;
    const VkSemaphoreSubmitInfo*        pWaitSemaphoreInfos;
    uint32_t                            commandBufferInfoCount;
    const VkCommandBufferSubmitInfo*    pCommandBufferInfos;
    uint32_t                            signalSemaphoreInfoCount;
    const VkSemaphoreSubmitInfo*        pSignalSemaphoreInfos;
} VkSubmitInfo2;

or the equivalent

// Provided by VK_KHR_synchronization2
typedef VkSubmitInfo2 VkSubmitInfo2KHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • flags is a bitmask of VkSubmitFlagBits.

  • waitSemaphoreInfoCount is the number of elements in pWaitSemaphoreInfos.

  • pWaitSemaphoreInfos is a pointer to an array of VkSemaphoreSubmitInfo structures defining semaphore wait operations.

  • commandBufferInfoCount is the number of elements in pCommandBufferInfos and the number of command buffers to execute in the batch.

  • pCommandBufferInfos is a pointer to an array of VkCommandBufferSubmitInfo structures describing command buffers to execute in the batch.

  • signalSemaphoreInfoCount is the number of elements in pSignalSemaphoreInfos.

  • pSignalSemaphoreInfos is a pointer to an array of VkSemaphoreSubmitInfo describing semaphore signal operations.

Valid Usage

  • VUID-VkSubmitInfo2-semaphore-03881
    If the same semaphore is used as the semaphore member of both an element of pSignalSemaphoreInfos and pWaitSemaphoreInfos, and that semaphore is a timeline semaphore, the value member of the pSignalSemaphoreInfos element must be greater than the value member of the pWaitSemaphoreInfos element

  • VUID-VkSubmitInfo2-semaphore-03882
    If the semaphore member of any element of pSignalSemaphoreInfos is a timeline semaphore, the value member of that element must have a value greater than the current value of the semaphore when the semaphore signal operation is executed

  • VUID-VkSubmitInfo2-semaphore-03883
    If the semaphore member of any element of pSignalSemaphoreInfos is a timeline semaphore, the value member of that element must have a value which does not differ from the current value of the semaphore or the value of any outstanding semaphore wait or signal operation on that semaphore by more than maxTimelineSemaphoreValueDifference

  • VUID-VkSubmitInfo2-semaphore-03884
    If the semaphore member of any element of pWaitSemaphoreInfos is a timeline semaphore, the value member of that element must have a value which does not differ from the current value of the semaphore or the value of any outstanding semaphore wait or signal operation on that semaphore by more than maxTimelineSemaphoreValueDifference

  • VUID-VkSubmitInfo2-flags-03886
    If flags includes VK_SUBMIT_PROTECTED_BIT, all elements of pCommandBuffers must be protected command buffers

  • VUID-VkSubmitInfo2-flags-03887
    If flags does not include VK_SUBMIT_PROTECTED_BIT, each element of pCommandBuffers must not be a protected command buffer

  • VUID-VkSubmitInfo2KHR-commandBuffer-06192
    If any commandBuffer member of an element of pCommandBufferInfos contains any resumed render pass instances, they must be suspended by a render pass instance earlier in submission order within pCommandBufferInfos

  • VUID-VkSubmitInfo2KHR-commandBuffer-06010
    If any commandBuffer member of an element of pCommandBufferInfos contains any suspended render pass instances, they must be resumed by a render pass instance later in submission order within pCommandBufferInfos

  • VUID-VkSubmitInfo2KHR-commandBuffer-06011
    If any commandBuffer member of an element of pCommandBufferInfos contains any suspended render pass instances, there must be no action or synchronization commands between that render pass instance and the render pass instance that resumes it

  • VUID-VkSubmitInfo2KHR-commandBuffer-06012
    If any commandBuffer member of an element of pCommandBufferInfos contains any suspended render pass instances, there must be no render pass instances between that render pass instance and the render pass instance that resumes it

  • VUID-VkSubmitInfo2KHR-variableSampleLocations-06013
    If the variableSampleLocations limit is not supported, and any commandBuffer member of an element of pCommandBufferInfos contains any suspended render pass instances, where a graphics pipeline has been bound, any pipelines bound in the render pass instance that resumes it, or any subsequent render pass instances that resume from that one and so on, must use the same sample locations

Valid Usage (Implicit)

  • VUID-VkSubmitInfo2-sType-sType
    sType must be VK_STRUCTURE_TYPE_SUBMIT_INFO_2

  • VUID-VkSubmitInfo2-pNext-pNext
    Each pNext member of any structure (including this one) in the pNext chain must be either NULL or a pointer to a valid instance of VkFrameBoundaryEXT, VkLatencySubmissionPresentIdNV, VkPerformanceQuerySubmitInfoKHR, VkWin32KeyedMutexAcquireReleaseInfoKHR, or VkWin32KeyedMutexAcquireReleaseInfoNV

  • VUID-VkSubmitInfo2-sType-unique
    The sType value of each struct in the pNext chain must be unique

  • VUID-VkSubmitInfo2-flags-parameter
    flags must be a valid combination of VkSubmitFlagBits values

  • VUID-VkSubmitInfo2-pWaitSemaphoreInfos-parameter
    If waitSemaphoreInfoCount is not 0, pWaitSemaphoreInfos must be a valid pointer to an array of waitSemaphoreInfoCount valid VkSemaphoreSubmitInfo structures

  • VUID-VkSubmitInfo2-pCommandBufferInfos-parameter
    If commandBufferInfoCount is not 0, pCommandBufferInfos must be a valid pointer to an array of commandBufferInfoCount valid VkCommandBufferSubmitInfo structures

  • VUID-VkSubmitInfo2-pSignalSemaphoreInfos-parameter
    If signalSemaphoreInfoCount is not 0, pSignalSemaphoreInfos must be a valid pointer to an array of signalSemaphoreInfoCount valid VkSemaphoreSubmitInfo structures

Bits which can be set in VkSubmitInfo2::flags, specifying submission behavior, are:

// Provided by VK_VERSION_1_3
typedef enum VkSubmitFlagBits {
    VK_SUBMIT_PROTECTED_BIT = 0x00000001,
    VK_SUBMIT_PROTECTED_BIT_KHR = VK_SUBMIT_PROTECTED_BIT,
} VkSubmitFlagBits;

or the equivalent

// Provided by VK_KHR_synchronization2
typedef VkSubmitFlagBits VkSubmitFlagBitsKHR;

  • VK_SUBMIT_PROTECTED_BIT specifies that this batch is a protected submission.

// Provided by VK_VERSION_1_3
typedef VkFlags VkSubmitFlags;

or the equivalent

// Provided by VK_KHR_synchronization2
typedef VkSubmitFlags VkSubmitFlagsKHR;

VkSubmitFlags is a bitmask type for setting a mask of zero or more VkSubmitFlagBits.

The VkSemaphoreSubmitInfo structure is defined as:

// Provided by VK_VERSION_1_3
typedef struct VkSemaphoreSubmitInfo {
    VkStructureType          sType;
    const void*              pNext;
    VkSemaphore              semaphore;
    uint64_t                 value;
    VkPipelineStageFlags2    stageMask;
    uint32_t                 deviceIndex;
} VkSemaphoreSubmitInfo;

or the equivalent

// Provided by VK_KHR_synchronization2
typedef VkSemaphoreSubmitInfo VkSemaphoreSubmitInfoKHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • semaphore is a VkSemaphore affected by this operation.

  • value is either the value used to signal semaphore or the value waited on by semaphore, if semaphore is a timeline semaphore. Otherwise it is ignored.

  • stageMask is a VkPipelineStageFlags2 mask of pipeline stages which limit the first synchronization scope of a semaphore signal operation, or second synchronization scope of a semaphore wait operation as described in the semaphore wait operation and semaphore signal operation sections of the synchronization chapter.

  • deviceIndex is the index of the device within a device group that executes the semaphore wait or signal operation.

Whether this structure defines a semaphore wait or signal operation is defined by how it is used.

Valid Usage

  • VUID-VkSemaphoreSubmitInfo-stageMask-03929
    If the geometryShader feature is not enabled, stageMask must not contain VK_PIPELINE_STAGE_2_GEOMETRY_SHADER_BIT

  • VUID-VkSemaphoreSubmitInfo-stageMask-03930
    If the tessellationShader feature is not enabled, stageMask must not contain VK_PIPELINE_STAGE_2_TESSELLATION_CONTROL_SHADER_BIT or VK_PIPELINE_STAGE_2_TESSELLATION_EVALUATION_SHADER_BIT

  • VUID-VkSemaphoreSubmitInfo-stageMask-03931
    If the conditionalRendering feature is not enabled, stageMask must not contain VK_PIPELINE_STAGE_2_CONDITIONAL_RENDERING_BIT_EXT

  • VUID-VkSemaphoreSubmitInfo-stageMask-03932
    If the fragmentDensityMap feature is not enabled, stageMask must not contain VK_PIPELINE_STAGE_2_FRAGMENT_DENSITY_PROCESS_BIT_EXT

  • VUID-VkSemaphoreSubmitInfo-stageMask-03933
    If the transformFeedback feature is not enabled, stageMask must not contain VK_PIPELINE_STAGE_2_TRANSFORM_FEEDBACK_BIT_EXT

  • VUID-VkSemaphoreSubmitInfo-stageMask-03934
    If the meshShader feature is not enabled, stageMask must not contain VK_PIPELINE_STAGE_2_MESH_SHADER_BIT_EXT

  • VUID-VkSemaphoreSubmitInfo-stageMask-03935
    If the taskShader feature is not enabled, stageMask must not contain VK_PIPELINE_STAGE_2_TASK_SHADER_BIT_EXT

  • VUID-VkSemaphoreSubmitInfo-stageMask-07316
    If neither the shadingRateImage or attachmentFragmentShadingRate are enabled, stageMask must not contain VK_PIPELINE_STAGE_2_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR

  • VUID-VkSemaphoreSubmitInfo-stageMask-04957
    If the subpassShading feature is not enabled, stageMask must not contain VK_PIPELINE_STAGE_2_SUBPASS_SHADER_BIT_HUAWEI

  • VUID-VkSemaphoreSubmitInfo-stageMask-04995
    If the invocationMask feature is not enabled, stageMask must not contain VK_PIPELINE_STAGE_2_INVOCATION_MASK_BIT_HUAWEI

  • VUID-VkSemaphoreSubmitInfo-stageMask-07946
    If neither the VK_NV_ray_tracing extension or rayTracingPipeline feature are enabled, stageMask must not contain VK_PIPELINE_STAGE_2_RAY_TRACING_SHADER_BIT_KHR

  • VUID-VkSemaphoreSubmitInfo-device-03888
    If the device that semaphore was created on is not a device group, deviceIndex must be 0

  • VUID-VkSemaphoreSubmitInfo-device-03889
    If the device that semaphore was created on is a device group, deviceIndex must be a valid device index

Valid Usage (Implicit)

  • VUID-VkSemaphoreSubmitInfo-sType-sType
    sType must be VK_STRUCTURE_TYPE_SEMAPHORE_SUBMIT_INFO

  • VUID-VkSemaphoreSubmitInfo-pNext-pNext
    pNext must be NULL

  • VUID-VkSemaphoreSubmitInfo-semaphore-parameter
    semaphore must be a valid VkSemaphore handle

  • VUID-VkSemaphoreSubmitInfo-stageMask-parameter
    stageMask must be a valid combination of VkPipelineStageFlagBits2 values

The VkCommandBufferSubmitInfo structure is defined as:

// Provided by VK_VERSION_1_3
typedef struct VkCommandBufferSubmitInfo {
    VkStructureType    sType;
    const void*        pNext;
    VkCommandBuffer    commandBuffer;
    uint32_t           deviceMask;
} VkCommandBufferSubmitInfo;

or the equivalent

// Provided by VK_KHR_synchronization2
typedef VkCommandBufferSubmitInfo VkCommandBufferSubmitInfoKHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • commandBuffer is a VkCommandBuffer to be submitted for execution.

  • deviceMask is a bitmask indicating which devices in a device group execute the command buffer. A deviceMask of 0 is equivalent to setting all bits corresponding to valid devices in the group to 1.

Valid Usage

  • VUID-VkCommandBufferSubmitInfo-commandBuffer-03890
    commandBuffer must not have been allocated with VK_COMMAND_BUFFER_LEVEL_SECONDARY

  • VUID-VkCommandBufferSubmitInfo-deviceMask-03891
    If deviceMask is not 0, it must be a valid device mask

  • VUID-VkCommandBufferSubmitInfo-commandBuffer-09445
    If any render pass instance in commandBuffer was recorded with a VkRenderPassStripeBeginInfoARM structure in its pNext chain and did not specify the VK_RENDERING_RESUMING_BIT flag, a VkRenderPassStripeSubmitInfoARM must be included in the pNext chain

  • VUID-VkCommandBufferSubmitInfo-pNext-09446
    If a VkRenderPassStripeSubmitInfoARM is included in the pNext chain, the value of VkRenderPassStripeSubmitInfoARM::stripeSemaphoreInfoCount must be equal to the sum of the VkRenderPassStripeBeginInfoARM::stripeInfoCount parameters provided to render pass instances recorded in commandBuffer that did not specify the VK_RENDERING_RESUMING_BIT flag

Valid Usage (Implicit)

  • VUID-VkCommandBufferSubmitInfo-sType-sType
    sType must be VK_STRUCTURE_TYPE_COMMAND_BUFFER_SUBMIT_INFO

  • VUID-VkCommandBufferSubmitInfo-pNext-pNext
    pNext must be NULL or a pointer to a valid instance of VkRenderPassStripeSubmitInfoARM

  • VUID-VkCommandBufferSubmitInfo-sType-unique
    The sType value of each struct in the pNext chain must be unique

  • VUID-VkCommandBufferSubmitInfo-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

The VkRenderPassStripeSubmitInfoARM structure is defined as:

// Provided by VK_ARM_render_pass_striped
typedef struct VkRenderPassStripeSubmitInfoARM {
    VkStructureType                 sType;
    const void*                     pNext;
    uint32_t                        stripeSemaphoreInfoCount;
    const VkSemaphoreSubmitInfo*    pStripeSemaphoreInfos;
} VkRenderPassStripeSubmitInfoARM;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • stripeSemaphoreInfoCount is the number of semaphores used to signal stripe completion in the render pass instances in the submitted command buffer.

  • pStripeSemaphoreInfos is a pointer to an array of stripeSemaphoreInfoCount VkSemaphoreSubmitInfo structures describing the semaphores used to signal stripe completion.

This structure can be included in the pNext chain of VkCommandBufferSubmitInfo to provide a set of semaphores to be signaled for each striped render pass instance.

The elements of pStripeSemaphoreInfos are mapped to render pass instances in VkCommandBufferSubmitInfo::commandBuffer in submission order and in stripe order within each render pass instance. Each semaphore in pStripeSemaphoreInfos is signaled when the implementation has completed execution of the associated stripe. In a render pass instance that has multiview enabled, the stripe includes all views in the view mask. In a render pass instance with layerCount greater than 1, the stripe includes all layers.

Render pass instances that specify the VK_RENDERING_RESUMING_BIT will not have any elements of pStripeSemaphoreInfos mapped to them. Instead, for suspending and resuming render pass instances, this mapping is done for the first suspending render pass instance, and the per-stripe semaphores are only signaled for the last resuming render pass instance.

Valid Usage

  • VUID-VkRenderPassStripeSubmitInfoARM-semaphore-09447
    The semaphore member of each element of pStripeSemaphoreInfos must have been created with a VkSemaphoreType of VK_SEMAPHORE_TYPE_BINARY

Valid Usage (Implicit)

  • VUID-VkRenderPassStripeSubmitInfoARM-sType-sType
    sType must be VK_STRUCTURE_TYPE_RENDER_PASS_STRIPE_SUBMIT_INFO_ARM

  • VUID-VkRenderPassStripeSubmitInfoARM-pStripeSemaphoreInfos-parameter
    pStripeSemaphoreInfos must be a valid pointer to an array of stripeSemaphoreInfoCount valid VkSemaphoreSubmitInfo structures

  • VUID-VkRenderPassStripeSubmitInfoARM-stripeSemaphoreInfoCount-arraylength
    stripeSemaphoreInfoCount must be greater than 0

To submit command buffers to a queue, call:

// Provided by VK_VERSION_1_0
VkResult vkQueueSubmit(
    VkQueue                                     queue,
    uint32_t                                    submitCount,
    const VkSubmitInfo*                         pSubmits,
    VkFence                                     fence);

  • queue is the queue that the command buffers will be submitted to.

  • submitCount is the number of elements in the pSubmits array.

  • pSubmits is a pointer to an array of VkSubmitInfo structures, each specifying a command buffer submission batch.

  • fence is an optional handle to a fence to be signaled once all submitted command buffers have completed execution. If fence is not VK_NULL_HANDLE, it defines a fence signal operation.

vkQueueSubmit is a queue submission command, with each batch defined by an element of pSubmits. Batches begin execution in the order they appear in pSubmits, but may complete out of order.

Fence and semaphore operations submitted with vkQueueSubmit have additional ordering constraints compared to other submission commands, with dependencies involving previous and subsequent queue operations. Information about these additional constraints can be found in the semaphore and fence sections of the synchronization chapter.

Details on the interaction of pWaitDstStageMask with synchronization are described in the semaphore wait operation section of the synchronization chapter.

The order that batches appear in pSubmits is used to determine submission order, and thus all the implicit ordering guarantees that respect it. Other than these implicit ordering guarantees and any explicit synchronization primitives, these batches may overlap or otherwise execute out of order.

If any command buffer submitted to this queue is in the executable state, it is moved to the pending state. Once execution of all submissions of a command buffer complete, it moves from the pending state, back to the executable state. If a command buffer was recorded with the VK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT flag, it instead moves to the invalid state.

If vkQueueSubmit fails, it may return VK_ERROR_OUT_OF_HOST_MEMORY or VK_ERROR_OUT_OF_DEVICE_MEMORY. If it does, the implementation must ensure that the state and contents of any resources or synchronization primitives referenced by the submitted command buffers and any semaphores referenced by pSubmits is unaffected by the call or its failure. If vkQueueSubmit fails in such a way that the implementation is unable to make that guarantee, the implementation must return VK_ERROR_DEVICE_LOST. See Lost Device.

Valid Usage

  • VUID-vkQueueSubmit-fence-00063
    If fence is not VK_NULL_HANDLE, fence must be unsignaled

  • VUID-vkQueueSubmit-fence-00064
    If fence is not VK_NULL_HANDLE, fence must not be associated with any other queue command that has not yet completed execution on that queue

  • VUID-vkQueueSubmit-pCommandBuffers-00065
    Any calls to vkCmdSetEvent, vkCmdResetEvent or vkCmdWaitEvents that have been recorded into any of the command buffer elements of the pCommandBuffers member of any element of pSubmits, must not reference any VkEvent that is referenced by any of those commands in a command buffer that has been submitted to another queue and is still in the pending state

  • VUID-vkQueueSubmit-pWaitDstStageMask-00066
    Any stage flag included in any element of the pWaitDstStageMask member of any element of pSubmits must be a pipeline stage supported by one of the capabilities of queue, as specified in the table of supported pipeline stages

  • VUID-vkQueueSubmit-pSignalSemaphores-00067
    Each binary semaphore element of the pSignalSemaphores member of any element of pSubmits must be unsignaled when the semaphore signal operation it defines is executed on the device

  • VUID-vkQueueSubmit-pWaitSemaphores-00068
    When a semaphore wait operation referring to a binary semaphore defined by any element of the pWaitSemaphores member of any element of pSubmits executes on queue, there must be no other queues waiting on the same semaphore

  • VUID-vkQueueSubmit-pWaitSemaphores-03238
    All elements of the pWaitSemaphores member of all elements of pSubmits created with a VkSemaphoreType of VK_SEMAPHORE_TYPE_BINARY must reference a semaphore signal operation that has been submitted for execution and any semaphore signal operations on which it depends must have also been submitted for execution

  • VUID-vkQueueSubmit-pCommandBuffers-00070
    Each element of the pCommandBuffers member of each element of pSubmits must be in the pending or executable state

  • VUID-vkQueueSubmit-pCommandBuffers-00071
    If any element of the pCommandBuffers member of any element of pSubmits was not recorded with the VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT, it must not be in the pending state

  • VUID-vkQueueSubmit-pCommandBuffers-00072
    Any secondary command buffers recorded into any element of the pCommandBuffers member of any element of pSubmits must be in the pending or executable state

  • VUID-vkQueueSubmit-pCommandBuffers-00073
    If any secondary command buffers recorded into any element of the pCommandBuffers member of any element of pSubmits was not recorded with the VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT, it must not be in the pending state

  • VUID-vkQueueSubmit-pCommandBuffers-00074
    Each element of the pCommandBuffers member of each element of pSubmits must have been allocated from a VkCommandPool that was created for the same queue family queue belongs to

  • VUID-vkQueueSubmit-pSubmits-02207
    If any element of pSubmits->pCommandBuffers includes a Queue Family Ownership Transfer Acquire Operation, there must exist a previously submitted Queue Family Ownership Transfer Release Operation on a queue in the queue family identified by the acquire operation, with parameters matching the acquire operation as defined in the definition of such acquire operations, and which happens-before the acquire operation

  • VUID-vkQueueSubmit-pCommandBuffers-03220
    If a command recorded into any element of pCommandBuffers was a vkCmdBeginQuery whose queryPool was created with a queryType of VK_QUERY_TYPE_PERFORMANCE_QUERY_KHR, the profiling lock must have been held continuously on the VkDevice that queue was retrieved from, throughout recording of those command buffers

  • VUID-vkQueueSubmit-pSubmits-02808
    Any resource created with VK_SHARING_MODE_EXCLUSIVE that is read by an operation specified by pSubmits must not be owned by any queue family other than the one which queue belongs to, at the time it is executed

  • VUID-vkQueueSubmit-pSubmits-04626
    Any resource created with VK_SHARING_MODE_CONCURRENT that is accessed by an operation specified by pSubmits must have included the queue family of queue at resource creation time

  • VUID-vkQueueSubmit-queue-06448
    If queue was not created with VK_DEVICE_QUEUE_CREATE_PROTECTED_BIT, there must be no element of pSubmits that includes a VkProtectedSubmitInfo structure in its pNext chain with protectedSubmit equal to VK_TRUE

Valid Usage (Implicit)

  • VUID-vkQueueSubmit-queue-parameter
    queue must be a valid VkQueue handle

  • VUID-vkQueueSubmit-pSubmits-parameter
    If submitCount is not 0, pSubmits must be a valid pointer to an array of submitCount valid VkSubmitInfo structures

  • VUID-vkQueueSubmit-fence-parameter
    If fence is not VK_NULL_HANDLE, fence must be a valid VkFence handle

  • VUID-vkQueueSubmit-commonparent
    Both of fence, and queue that are valid handles of non-ignored parameters must have been created, allocated, or retrieved from the same VkDevice

Host Synchronization

  • Host access to queue must be externally synchronized

  • Host access to fence must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Video Coding Scope Supported Queue Types Command Type

-

-

-

Any

-
Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

  • VK_ERROR_DEVICE_LOST

The VkSubmitInfo structure is defined as:

// Provided by VK_VERSION_1_0
typedef struct VkSubmitInfo {
    VkStructureType                sType;
    const void*                    pNext;
    uint32_t                       waitSemaphoreCount;
    const VkSemaphore*             pWaitSemaphores;
    const VkPipelineStageFlags*    pWaitDstStageMask;
    uint32_t                       commandBufferCount;
    const VkCommandBuffer*         pCommandBuffers;
    uint32_t                       signalSemaphoreCount;
    const VkSemaphore*             pSignalSemaphores;
} VkSubmitInfo;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • waitSemaphoreCount is the number of semaphores upon which to wait before executing the command buffers for the batch.

  • pWaitSemaphores is a pointer to an array of VkSemaphore handles upon which to wait before the command buffers for this batch begin execution. If semaphores to wait on are provided, they define a semaphore wait operation.

  • pWaitDstStageMask is a pointer to an array of pipeline stages at which each corresponding semaphore wait will occur.

  • commandBufferCount is the number of command buffers to execute in the batch.

  • pCommandBuffers is a pointer to an array of VkCommandBuffer handles to execute in the batch.

  • signalSemaphoreCount is the number of semaphores to be signaled once the commands specified in pCommandBuffers have completed execution.

  • pSignalSemaphores is a pointer to an array of VkSemaphore handles which will be signaled when the command buffers for this batch have completed execution. If semaphores to be signaled are provided, they define a semaphore signal operation.

The order that command buffers appear in pCommandBuffers is used to determine submission order, and thus all the implicit ordering guarantees that respect it. Other than these implicit ordering guarantees and any explicit synchronization primitives, these command buffers may overlap or otherwise execute out of order.

Valid Usage

  • VUID-VkSubmitInfo-pWaitDstStageMask-04090
    If the geometryShader feature is not enabled, pWaitDstStageMask must not contain VK_PIPELINE_STAGE_GEOMETRY_SHADER_BIT

  • VUID-VkSubmitInfo-pWaitDstStageMask-04091
    If the tessellationShader feature is not enabled, pWaitDstStageMask must not contain VK_PIPELINE_STAGE_TESSELLATION_CONTROL_SHADER_BIT or VK_PIPELINE_STAGE_TESSELLATION_EVALUATION_SHADER_BIT

  • VUID-VkSubmitInfo-pWaitDstStageMask-04092
    If the conditionalRendering feature is not enabled, pWaitDstStageMask must not contain VK_PIPELINE_STAGE_CONDITIONAL_RENDERING_BIT_EXT

  • VUID-VkSubmitInfo-pWaitDstStageMask-04093
    If the fragmentDensityMap feature is not enabled, pWaitDstStageMask must not contain VK_PIPELINE_STAGE_FRAGMENT_DENSITY_PROCESS_BIT_EXT

  • VUID-VkSubmitInfo-pWaitDstStageMask-04094
    If the transformFeedback feature is not enabled, pWaitDstStageMask must not contain VK_PIPELINE_STAGE_TRANSFORM_FEEDBACK_BIT_EXT

  • VUID-VkSubmitInfo-pWaitDstStageMask-04095
    If the meshShader feature is not enabled, pWaitDstStageMask must not contain VK_PIPELINE_STAGE_MESH_SHADER_BIT_EXT

  • VUID-VkSubmitInfo-pWaitDstStageMask-04096
    If the taskShader feature is not enabled, pWaitDstStageMask must not contain VK_PIPELINE_STAGE_TASK_SHADER_BIT_EXT

  • VUID-VkSubmitInfo-pWaitDstStageMask-07318
    If neither the shadingRateImage or attachmentFragmentShadingRate are enabled, pWaitDstStageMask must not contain VK_PIPELINE_STAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR

  • VUID-VkSubmitInfo-pWaitDstStageMask-03937
    If the synchronization2 feature is not enabled, pWaitDstStageMask must not be 0

  • VUID-VkSubmitInfo-pWaitDstStageMask-07949
    If neither the VK_NV_ray_tracing extension or rayTracingPipeline feature are enabled, pWaitDstStageMask must not contain VK_PIPELINE_STAGE_RAY_TRACING_SHADER_BIT_KHR

  • VUID-VkSubmitInfo-pCommandBuffers-00075
    Each element of pCommandBuffers must not have been allocated with VK_COMMAND_BUFFER_LEVEL_SECONDARY

  • VUID-VkSubmitInfo-pWaitDstStageMask-00078
    Each element of pWaitDstStageMask must not include VK_PIPELINE_STAGE_HOST_BIT

  • VUID-VkSubmitInfo-pWaitSemaphores-03239
    If any element of pWaitSemaphores or pSignalSemaphores was created with a VkSemaphoreType of VK_SEMAPHORE_TYPE_TIMELINE, then the pNext chain must include a VkTimelineSemaphoreSubmitInfo structure

  • VUID-VkSubmitInfo-pNext-03240
    If the pNext chain of this structure includes a VkTimelineSemaphoreSubmitInfo structure and any element of pWaitSemaphores was created with a VkSemaphoreType of VK_SEMAPHORE_TYPE_TIMELINE, then its waitSemaphoreValueCount member must equal waitSemaphoreCount

  • VUID-VkSubmitInfo-pNext-03241
    If the pNext chain of this structure includes a VkTimelineSemaphoreSubmitInfo structure and any element of pSignalSemaphores was created with a VkSemaphoreType of VK_SEMAPHORE_TYPE_TIMELINE, then its signalSemaphoreValueCount member must equal signalSemaphoreCount

  • VUID-VkSubmitInfo-pSignalSemaphores-03242
    For each element of pSignalSemaphores created with a VkSemaphoreType of VK_SEMAPHORE_TYPE_TIMELINE the corresponding element of VkTimelineSemaphoreSubmitInfo::pSignalSemaphoreValues must have a value greater than the current value of the semaphore when the semaphore signal operation is executed

  • VUID-VkSubmitInfo-pWaitSemaphores-03243
    For each element of pWaitSemaphores created with a VkSemaphoreType of VK_SEMAPHORE_TYPE_TIMELINE the corresponding element of VkTimelineSemaphoreSubmitInfo::pWaitSemaphoreValues must have a value which does not differ from the current value of the semaphore or the value of any outstanding semaphore wait or signal operation on that semaphore by more than maxTimelineSemaphoreValueDifference

  • VUID-VkSubmitInfo-pSignalSemaphores-03244
    For each element of pSignalSemaphores created with a VkSemaphoreType of VK_SEMAPHORE_TYPE_TIMELINE the corresponding element of VkTimelineSemaphoreSubmitInfo::pSignalSemaphoreValues must have a value which does not differ from the current value of the semaphore or the value of any outstanding semaphore wait or signal operation on that semaphore by more than maxTimelineSemaphoreValueDifference

  • VUID-VkSubmitInfo-pNext-04120
    If the pNext chain of this structure does not include a VkProtectedSubmitInfo structure with protectedSubmit set to VK_TRUE, then each element of the pCommandBuffers array must be an unprotected command buffer

  • VUID-VkSubmitInfo-pNext-04148
    If the pNext chain of this structure includes a VkProtectedSubmitInfo structure with protectedSubmit set to VK_TRUE, then each element of the pCommandBuffers array must be a protected command buffer

  • VUID-VkSubmitInfo-pCommandBuffers-06193
    If pCommandBuffers contains any resumed render pass instances, they must be suspended by a render pass instance earlier in submission order within pCommandBuffers

  • VUID-VkSubmitInfo-pCommandBuffers-06014
    If pCommandBuffers contains any suspended render pass instances, they must be resumed by a render pass instance later in submission order within pCommandBuffers

  • VUID-VkSubmitInfo-pCommandBuffers-06015
    If pCommandBuffers contains any suspended render pass instances, there must be no action or synchronization commands executed in a primary or secondary command buffer between that render pass instance and the render pass instance that resumes it

  • VUID-VkSubmitInfo-pCommandBuffers-06016
    If pCommandBuffers contains any suspended render pass instances, there must be no render pass instances between that render pass instance and the render pass instance that resumes it

  • VUID-VkSubmitInfo-variableSampleLocations-06017
    If the variableSampleLocations limit is not supported, and any element of pCommandBuffers contains any suspended render pass instances, where a graphics pipeline has been bound, any pipelines bound in the render pass instance that resumes it, or any subsequent render pass instances that resume from that one and so on, must use the same sample locations

Valid Usage (Implicit)

To specify the values to use when waiting for and signaling semaphores created with a VkSemaphoreType of VK_SEMAPHORE_TYPE_TIMELINE, add a VkTimelineSemaphoreSubmitInfo structure to the pNext chain of the VkSubmitInfo structure when using vkQueueSubmit or the VkBindSparseInfo structure when using vkQueueBindSparse . The VkTimelineSemaphoreSubmitInfo structure is defined as:

// Provided by VK_VERSION_1_2
typedef struct VkTimelineSemaphoreSubmitInfo {
    VkStructureType    sType;
    const void*        pNext;
    uint32_t           waitSemaphoreValueCount;
    const uint64_t*    pWaitSemaphoreValues;
    uint32_t           signalSemaphoreValueCount;
    const uint64_t*    pSignalSemaphoreValues;
} VkTimelineSemaphoreSubmitInfo;

or the equivalent

// Provided by VK_KHR_timeline_semaphore
typedef VkTimelineSemaphoreSubmitInfo VkTimelineSemaphoreSubmitInfoKHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • waitSemaphoreValueCount is the number of semaphore wait values specified in pWaitSemaphoreValues.

  • pWaitSemaphoreValues is a pointer to an array of waitSemaphoreValueCount values for the corresponding semaphores in VkSubmitInfo::pWaitSemaphores to wait for.

  • signalSemaphoreValueCount is the number of semaphore signal values specified in pSignalSemaphoreValues.

  • pSignalSemaphoreValues is a pointer to an array signalSemaphoreValueCount values for the corresponding semaphores in VkSubmitInfo::pSignalSemaphores to set when signaled.

If the semaphore in VkSubmitInfo::pWaitSemaphores or VkSubmitInfo::pSignalSemaphores corresponding to an entry in pWaitSemaphoreValues or pSignalSemaphoreValues respectively was not created with a VkSemaphoreType of VK_SEMAPHORE_TYPE_TIMELINE, the implementation must ignore the value in the pWaitSemaphoreValues or pSignalSemaphoreValues entry.

Valid Usage (Implicit)

  • VUID-VkTimelineSemaphoreSubmitInfo-sType-sType
    sType must be VK_STRUCTURE_TYPE_TIMELINE_SEMAPHORE_SUBMIT_INFO

  • VUID-VkTimelineSemaphoreSubmitInfo-pWaitSemaphoreValues-parameter
    If waitSemaphoreValueCount is not 0, and pWaitSemaphoreValues is not NULL, pWaitSemaphoreValues must be a valid pointer to an array of waitSemaphoreValueCount uint64_t values

  • VUID-VkTimelineSemaphoreSubmitInfo-pSignalSemaphoreValues-parameter
    If signalSemaphoreValueCount is not 0, and pSignalSemaphoreValues is not NULL, pSignalSemaphoreValues must be a valid pointer to an array of signalSemaphoreValueCount uint64_t values

To specify the values to use when waiting for and signaling semaphores whose current payload refers to a Direct3D 12 fence, add a VkD3D12FenceSubmitInfoKHR structure to the pNext chain of the VkSubmitInfo structure. The VkD3D12FenceSubmitInfoKHR structure is defined as:

// Provided by VK_KHR_external_semaphore_win32
typedef struct VkD3D12FenceSubmitInfoKHR {
    VkStructureType    sType;
    const void*        pNext;
    uint32_t           waitSemaphoreValuesCount;
    const uint64_t*    pWaitSemaphoreValues;
    uint32_t           signalSemaphoreValuesCount;
    const uint64_t*    pSignalSemaphoreValues;
} VkD3D12FenceSubmitInfoKHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • waitSemaphoreValuesCount is the number of semaphore wait values specified in pWaitSemaphoreValues.

  • pWaitSemaphoreValues is a pointer to an array of waitSemaphoreValuesCount values for the corresponding semaphores in VkSubmitInfo::pWaitSemaphores to wait for.

  • signalSemaphoreValuesCount is the number of semaphore signal values specified in pSignalSemaphoreValues.

  • pSignalSemaphoreValues is a pointer to an array of signalSemaphoreValuesCount values for the corresponding semaphores in VkSubmitInfo::pSignalSemaphores to set when signaled.

If the semaphore in VkSubmitInfo::pWaitSemaphores or VkSubmitInfo::pSignalSemaphores corresponding to an entry in pWaitSemaphoreValues or pSignalSemaphoreValues respectively does not currently have a payload referring to a Direct3D 12 fence, the implementation must ignore the value in the pWaitSemaphoreValues or pSignalSemaphoreValues entry.

Note

As the introduction of the external semaphore handle type VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_D3D12_FENCE_BIT predates that of timeline semaphores, support for importing semaphore payloads from external handles of that type into semaphores created (implicitly or explicitly) with a VkSemaphoreType of VK_SEMAPHORE_TYPE_BINARY is preserved for backwards compatibility. However, applications should prefer importing such handle types into semaphores created with a VkSemaphoreType of VK_SEMAPHORE_TYPE_TIMELINE, and use the VkTimelineSemaphoreSubmitInfo structure instead of the VkD3D12FenceSubmitInfoKHR structure to specify the values to use when waiting for and signaling such semaphores.
Valid Usage

  • VUID-VkD3D12FenceSubmitInfoKHR-waitSemaphoreValuesCount-00079
    waitSemaphoreValuesCount must be the same value as VkSubmitInfo::waitSemaphoreCount, where this structure is in the pNext chain of a VkSubmitInfo structure

  • VUID-VkD3D12FenceSubmitInfoKHR-signalSemaphoreValuesCount-00080
    signalSemaphoreValuesCount must be the same value as VkSubmitInfo::signalSemaphoreCount, where this structure is in the pNext chain of a VkSubmitInfo structure

Valid Usage (Implicit)

  • VUID-VkD3D12FenceSubmitInfoKHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_D3D12_FENCE_SUBMIT_INFO_KHR

  • VUID-VkD3D12FenceSubmitInfoKHR-pWaitSemaphoreValues-parameter
    If waitSemaphoreValuesCount is not 0, and pWaitSemaphoreValues is not NULL, pWaitSemaphoreValues must be a valid pointer to an array of waitSemaphoreValuesCount uint64_t values

  • VUID-VkD3D12FenceSubmitInfoKHR-pSignalSemaphoreValues-parameter
    If signalSemaphoreValuesCount is not 0, and pSignalSemaphoreValues is not NULL, pSignalSemaphoreValues must be a valid pointer to an array of signalSemaphoreValuesCount uint64_t values

When submitting work that operates on memory imported from a Direct3D 11 resource to a queue, the keyed mutex mechanism may be used in addition to Vulkan semaphores to synchronize the work. Keyed mutexes are a property of a properly created shareable Direct3D 11 resource. They can only be used if the imported resource was created with the D3D11_RESOURCE_MISC_SHARED_KEYEDMUTEX flag.

To acquire keyed mutexes before submitted work and/or release them after, add a VkWin32KeyedMutexAcquireReleaseInfoKHR structure to the pNext chain of the VkSubmitInfo structure.

The VkWin32KeyedMutexAcquireReleaseInfoKHR structure is defined as:

// Provided by VK_KHR_win32_keyed_mutex
typedef struct VkWin32KeyedMutexAcquireReleaseInfoKHR {
    VkStructureType          sType;
    const void*              pNext;
    uint32_t                 acquireCount;
    const VkDeviceMemory*    pAcquireSyncs;
    const uint64_t*          pAcquireKeys;
    const uint32_t*          pAcquireTimeouts;
    uint32_t                 releaseCount;
    const VkDeviceMemory*    pReleaseSyncs;
    const uint64_t*          pReleaseKeys;
} VkWin32KeyedMutexAcquireReleaseInfoKHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • acquireCount is the number of entries in the pAcquireSyncs, pAcquireKeys, and pAcquireTimeouts arrays.

  • pAcquireSyncs is a pointer to an array of VkDeviceMemory objects which were imported from Direct3D 11 resources.

  • pAcquireKeys is a pointer to an array of mutex key values to wait for prior to beginning the submitted work. Entries refer to the keyed mutex associated with the corresponding entries in pAcquireSyncs.

  • pAcquireTimeouts is a pointer to an array of timeout values, in millisecond units, for each acquire specified in pAcquireKeys.

  • releaseCount is the number of entries in the pReleaseSyncs and pReleaseKeys arrays.

  • pReleaseSyncs is a pointer to an array of VkDeviceMemory objects which were imported from Direct3D 11 resources.

  • pReleaseKeys is a pointer to an array of mutex key values to set when the submitted work has completed. Entries refer to the keyed mutex associated with the corresponding entries in pReleaseSyncs.

Valid Usage

  • VUID-VkWin32KeyedMutexAcquireReleaseInfoKHR-pAcquireSyncs-00081
    Each member of pAcquireSyncs and pReleaseSyncs must be a device memory object imported by setting VkImportMemoryWin32HandleInfoKHR::handleType to VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_BIT or VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_KMT_BIT

Valid Usage (Implicit)

  • VUID-VkWin32KeyedMutexAcquireReleaseInfoKHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_WIN32_KEYED_MUTEX_ACQUIRE_RELEASE_INFO_KHR

  • VUID-VkWin32KeyedMutexAcquireReleaseInfoKHR-pAcquireSyncs-parameter
    If acquireCount is not 0, pAcquireSyncs must be a valid pointer to an array of acquireCount valid VkDeviceMemory handles

  • VUID-VkWin32KeyedMutexAcquireReleaseInfoKHR-pAcquireKeys-parameter
    If acquireCount is not 0, pAcquireKeys must be a valid pointer to an array of acquireCount uint64_t values

  • VUID-VkWin32KeyedMutexAcquireReleaseInfoKHR-pAcquireTimeouts-parameter
    If acquireCount is not 0, pAcquireTimeouts must be a valid pointer to an array of acquireCount uint32_t values

  • VUID-VkWin32KeyedMutexAcquireReleaseInfoKHR-pReleaseSyncs-parameter
    If releaseCount is not 0, pReleaseSyncs must be a valid pointer to an array of releaseCount valid VkDeviceMemory handles

  • VUID-VkWin32KeyedMutexAcquireReleaseInfoKHR-pReleaseKeys-parameter
    If releaseCount is not 0, pReleaseKeys must be a valid pointer to an array of releaseCount uint64_t values

  • VUID-VkWin32KeyedMutexAcquireReleaseInfoKHR-commonparent
    Both of the elements of pAcquireSyncs, and the elements of pReleaseSyncs that are valid handles of non-ignored parameters must have been created, allocated, or retrieved from the same VkDevice

When submitting work that operates on memory imported from a Direct3D 11 resource to a queue, the keyed mutex mechanism may be used in addition to Vulkan semaphores to synchronize the work. Keyed mutexes are a property of a properly created shareable Direct3D 11 resource. They can only be used if the imported resource was created with the D3D11_RESOURCE_MISC_SHARED_KEYEDMUTEX flag.

To acquire keyed mutexes before submitted work and/or release them after, add a VkWin32KeyedMutexAcquireReleaseInfoNV structure to the pNext chain of the VkSubmitInfo structure.

The VkWin32KeyedMutexAcquireReleaseInfoNV structure is defined as:

// Provided by VK_NV_win32_keyed_mutex
typedef struct VkWin32KeyedMutexAcquireReleaseInfoNV {
    VkStructureType          sType;
    const void*              pNext;
    uint32_t                 acquireCount;
    const VkDeviceMemory*    pAcquireSyncs;
    const uint64_t*          pAcquireKeys;
    const uint32_t*          pAcquireTimeoutMilliseconds;
    uint32_t                 releaseCount;
    const VkDeviceMemory*    pReleaseSyncs;
    const uint64_t*          pReleaseKeys;
} VkWin32KeyedMutexAcquireReleaseInfoNV;

  • acquireCount is the number of entries in the pAcquireSyncs, pAcquireKeys, and pAcquireTimeoutMilliseconds arrays.

  • pAcquireSyncs is a pointer to an array of VkDeviceMemory objects which were imported from Direct3D 11 resources.

  • pAcquireKeys is a pointer to an array of mutex key values to wait for prior to beginning the submitted work. Entries refer to the keyed mutex associated with the corresponding entries in pAcquireSyncs.

  • pAcquireTimeoutMilliseconds is a pointer to an array of timeout values, in millisecond units, for each acquire specified in pAcquireKeys.

  • releaseCount is the number of entries in the pReleaseSyncs and pReleaseKeys arrays.

  • pReleaseSyncs is a pointer to an array of VkDeviceMemory objects which were imported from Direct3D 11 resources.

  • pReleaseKeys is a pointer to an array of mutex key values to set when the submitted work has completed. Entries refer to the keyed mutex associated with the corresponding entries in pReleaseSyncs.

Valid Usage (Implicit)

  • VUID-VkWin32KeyedMutexAcquireReleaseInfoNV-sType-sType
    sType must be VK_STRUCTURE_TYPE_WIN32_KEYED_MUTEX_ACQUIRE_RELEASE_INFO_NV

  • VUID-VkWin32KeyedMutexAcquireReleaseInfoNV-pAcquireSyncs-parameter
    If acquireCount is not 0, pAcquireSyncs must be a valid pointer to an array of acquireCount valid VkDeviceMemory handles

  • VUID-VkWin32KeyedMutexAcquireReleaseInfoNV-pAcquireKeys-parameter
    If acquireCount is not 0, pAcquireKeys must be a valid pointer to an array of acquireCount uint64_t values

  • VUID-VkWin32KeyedMutexAcquireReleaseInfoNV-pAcquireTimeoutMilliseconds-parameter
    If acquireCount is not 0, pAcquireTimeoutMilliseconds must be a valid pointer to an array of acquireCount uint32_t values

  • VUID-VkWin32KeyedMutexAcquireReleaseInfoNV-pReleaseSyncs-parameter
    If releaseCount is not 0, pReleaseSyncs must be a valid pointer to an array of releaseCount valid VkDeviceMemory handles

  • VUID-VkWin32KeyedMutexAcquireReleaseInfoNV-pReleaseKeys-parameter
    If releaseCount is not 0, pReleaseKeys must be a valid pointer to an array of releaseCount uint64_t values

  • VUID-VkWin32KeyedMutexAcquireReleaseInfoNV-commonparent
    Both of the elements of pAcquireSyncs, and the elements of pReleaseSyncs that are valid handles of non-ignored parameters must have been created, allocated, or retrieved from the same VkDevice

If the pNext chain of VkSubmitInfo includes a VkProtectedSubmitInfo structure, then the structure indicates whether the batch is protected. The VkProtectedSubmitInfo structure is defined as:

// Provided by VK_VERSION_1_1
typedef struct VkProtectedSubmitInfo {
    VkStructureType    sType;
    const void*        pNext;
    VkBool32           protectedSubmit;
} VkProtectedSubmitInfo;

  • protectedSubmit specifies whether the batch is protected. If protectedSubmit is VK_TRUE, the batch is protected. If protectedSubmit is VK_FALSE, the batch is unprotected. If the VkSubmitInfo::pNext chain does not include this structure, the batch is unprotected.

Valid Usage (Implicit)

  • VUID-VkProtectedSubmitInfo-sType-sType
    sType must be VK_STRUCTURE_TYPE_PROTECTED_SUBMIT_INFO

If the pNext chain of VkSubmitInfo includes a VkDeviceGroupSubmitInfo structure, then that structure includes device indices and masks specifying which physical devices execute semaphore operations and command buffers.

The VkDeviceGroupSubmitInfo structure is defined as:

// Provided by VK_VERSION_1_1
typedef struct VkDeviceGroupSubmitInfo {
    VkStructureType    sType;
    const void*        pNext;
    uint32_t           waitSemaphoreCount;
    const uint32_t*    pWaitSemaphoreDeviceIndices;
    uint32_t           commandBufferCount;
    const uint32_t*    pCommandBufferDeviceMasks;
    uint32_t           signalSemaphoreCount;
    const uint32_t*    pSignalSemaphoreDeviceIndices;
} VkDeviceGroupSubmitInfo;

or the equivalent

// Provided by VK_KHR_device_group
typedef VkDeviceGroupSubmitInfo VkDeviceGroupSubmitInfoKHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • waitSemaphoreCount is the number of elements in the pWaitSemaphoreDeviceIndices array.

  • pWaitSemaphoreDeviceIndices is a pointer to an array of waitSemaphoreCount device indices indicating which physical device executes the semaphore wait operation in the corresponding element of VkSubmitInfo::pWaitSemaphores.

  • commandBufferCount is the number of elements in the pCommandBufferDeviceMasks array.

  • pCommandBufferDeviceMasks is a pointer to an array of commandBufferCount device masks indicating which physical devices execute the command buffer in the corresponding element of VkSubmitInfo::pCommandBuffers. A physical device executes the command buffer if the corresponding bit is set in the mask.

  • signalSemaphoreCount is the number of elements in the pSignalSemaphoreDeviceIndices array.

  • pSignalSemaphoreDeviceIndices is a pointer to an array of signalSemaphoreCount device indices indicating which physical device executes the semaphore signal operation in the corresponding element of VkSubmitInfo::pSignalSemaphores.

If this structure is not present, semaphore operations and command buffers execute on device index zero.

Valid Usage

  • VUID-VkDeviceGroupSubmitInfo-waitSemaphoreCount-00082
    waitSemaphoreCount must equal VkSubmitInfo::waitSemaphoreCount

  • VUID-VkDeviceGroupSubmitInfo-commandBufferCount-00083
    commandBufferCount must equal VkSubmitInfo::commandBufferCount

  • VUID-VkDeviceGroupSubmitInfo-signalSemaphoreCount-00084
    signalSemaphoreCount must equal VkSubmitInfo::signalSemaphoreCount

  • VUID-VkDeviceGroupSubmitInfo-pWaitSemaphoreDeviceIndices-00085
    All elements of pWaitSemaphoreDeviceIndices and pSignalSemaphoreDeviceIndices must be valid device indices

  • VUID-VkDeviceGroupSubmitInfo-pCommandBufferDeviceMasks-00086
    All elements of pCommandBufferDeviceMasks must be valid device masks

Valid Usage (Implicit)

  • VUID-VkDeviceGroupSubmitInfo-sType-sType
    sType must be VK_STRUCTURE_TYPE_DEVICE_GROUP_SUBMIT_INFO

  • VUID-VkDeviceGroupSubmitInfo-pWaitSemaphoreDeviceIndices-parameter
    If waitSemaphoreCount is not 0, pWaitSemaphoreDeviceIndices must be a valid pointer to an array of waitSemaphoreCount uint32_t values

  • VUID-VkDeviceGroupSubmitInfo-pCommandBufferDeviceMasks-parameter
    If commandBufferCount is not 0, pCommandBufferDeviceMasks must be a valid pointer to an array of commandBufferCount uint32_t values

  • VUID-VkDeviceGroupSubmitInfo-pSignalSemaphoreDeviceIndices-parameter
    If signalSemaphoreCount is not 0, pSignalSemaphoreDeviceIndices must be a valid pointer to an array of signalSemaphoreCount uint32_t values

If the pNext chain of VkSubmitInfo includes a VkPerformanceQuerySubmitInfoKHR structure, then the structure indicates which counter pass is active for the batch in that submit.

The VkPerformanceQuerySubmitInfoKHR structure is defined as:

// Provided by VK_KHR_performance_query
typedef struct VkPerformanceQuerySubmitInfoKHR {
    VkStructureType    sType;
    const void*        pNext;
    uint32_t           counterPassIndex;
} VkPerformanceQuerySubmitInfoKHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • counterPassIndex specifies which counter pass index is active.

If the VkSubmitInfo::pNext chain does not include this structure, the batch defaults to use counter pass index 0.

Valid Usage

  • VUID-VkPerformanceQuerySubmitInfoKHR-counterPassIndex-03221
    counterPassIndex must be less than the number of counter passes required by any queries within the batch. The required number of counter passes for a performance query is obtained by calling vkGetPhysicalDeviceQueueFamilyPerformanceQueryPassesKHR

Valid Usage (Implicit)

  • VUID-VkPerformanceQuerySubmitInfoKHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_PERFORMANCE_QUERY_SUBMIT_INFO_KHR

6.6. Queue Forward Progress

When using binary semaphores, the application must ensure that command buffer submissions will be able to complete without any subsequent operations by the application on any queue. After any call to vkQueueSubmit (or other queue operation), for every queued wait on a semaphore created with a VkSemaphoreType of VK_SEMAPHORE_TYPE_BINARY there must be a prior signal of that semaphore that will not be consumed by a different wait on the semaphore.

When using timeline semaphores, wait-before-signal behavior is well-defined and applications can submit work via vkQueueSubmit defining a timeline semaphore wait operation before submitting a corresponding semaphore signal operation. For each timeline semaphore wait operation defined by a call to vkQueueSubmit, the application must ensure that a corresponding semaphore signal operation is executed before forward progress can be made.

If a command buffer submission waits for any events to be signaled, the application must ensure that command buffer submissions will be able to complete without any subsequent operations by the application. Events signaled by the host must be signaled before the command buffer waits on those events.

Note

The ability for commands to wait on the host to set an events was originally added to allow low-latency updates to resources between host and device. However, to ensure quality of service, implementations would necessarily detect extended stalls in execution and timeout after a short period. As this period is not defined in the Vulkan specification, it is impossible to correctly validate any application with any wait period. Since the original users of this functionality were highly limited and platform-specific, this functionality is now considered defunct and should not be used.

6.7. Secondary Command Buffer Execution

Secondary command buffers must not be directly submitted to a queue. To record a secondary command buffer to execute as part of a primary command buffer, call:

// Provided by VK_VERSION_1_0
void vkCmdExecuteCommands(
    VkCommandBuffer                             commandBuffer,
    uint32_t                                    commandBufferCount,
    const VkCommandBuffer*                      pCommandBuffers);

  • commandBuffer is a handle to a primary command buffer that the secondary command buffers are executed in.

  • commandBufferCount is the length of the pCommandBuffers array.

  • pCommandBuffers is a pointer to an array of commandBufferCount secondary command buffer handles, which are recorded to execute in the primary command buffer in the order they are listed in the array.

If any element of pCommandBuffers was not recorded with the VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT flag, and it was recorded into any other primary command buffer which is currently in the executable or recording state, that primary command buffer becomes invalid.

If the nestedCommandBuffer feature is enabled it is valid usage for vkCmdExecuteCommands to also be recorded to a secondary command buffer.

Valid Usage

  • VUID-vkCmdExecuteCommands-pCommandBuffers-00088
    Each element of pCommandBuffers must have been allocated with a level of VK_COMMAND_BUFFER_LEVEL_SECONDARY

  • VUID-vkCmdExecuteCommands-pCommandBuffers-00089
    Each element of pCommandBuffers must be in the pending or executable state

  • VUID-vkCmdExecuteCommands-pCommandBuffers-00091
    If any element of pCommandBuffers was not recorded with the VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT flag, it must not be in the pending state

  • VUID-vkCmdExecuteCommands-pCommandBuffers-00092
    If any element of pCommandBuffers was not recorded with the VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT flag, it must not have already been recorded to commandBuffer

  • VUID-vkCmdExecuteCommands-pCommandBuffers-00093
    If any element of pCommandBuffers was not recorded with the VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT flag, it must not appear more than once in pCommandBuffers

  • VUID-vkCmdExecuteCommands-pCommandBuffers-00094
    Each element of pCommandBuffers must have been allocated from a VkCommandPool that was created for the same queue family as the VkCommandPool from which commandBuffer was allocated

  • VUID-vkCmdExecuteCommands-pCommandBuffers-00096
    If vkCmdExecuteCommands is being called within a render pass instance, each element of pCommandBuffers must have been recorded with the VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT

  • VUID-vkCmdExecuteCommands-pCommandBuffers-00099
    If vkCmdExecuteCommands is being called within a render pass instance, and any element of pCommandBuffers was recorded with VkCommandBufferInheritanceInfo::framebuffer not equal to VK_NULL_HANDLE, that VkFramebuffer must match the VkFramebuffer used in the current render pass instance

  • VUID-vkCmdExecuteCommands-contents-09680
    If vkCmdExecuteCommands is being called within a render pass instance begun with vkCmdBeginRenderPass, and vkCmdNextSubpass has not been called in the current render pass instance, the contents parameter of vkCmdBeginRenderPass must have been set to VK_SUBPASS_CONTENTS_SECONDARY_COMMAND_BUFFERS , or VK_SUBPASS_CONTENTS_INLINE_AND_SECONDARY_COMMAND_BUFFERS_EXT

  • VUID-vkCmdExecuteCommands-None-09681
    If vkCmdExecuteCommands is being called within a render pass instance begun with vkCmdBeginRenderPass, and vkCmdNextSubpass has been called in the current render pass instance, the contents parameter of the last call to vkCmdNextSubpass must have been set to VK_SUBPASS_CONTENTS_SECONDARY_COMMAND_BUFFERS , or VK_SUBPASS_CONTENTS_INLINE_AND_SECONDARY_COMMAND_BUFFERS_KHR

  • VUID-vkCmdExecuteCommands-pCommandBuffers-06019
    If vkCmdExecuteCommands is being called within a render pass instance begun with vkCmdBeginRenderPass, each element of pCommandBuffers must have been recorded with VkCommandBufferInheritanceInfo::subpass set to the index of the subpass which the given command buffer will be executed in

  • VUID-vkCmdExecuteCommands-pBeginInfo-06020
    If vkCmdExecuteCommands is being called within a render pass instance begun with vkCmdBeginRenderPass, the render passes specified in the pBeginInfo->pInheritanceInfo->renderPass members of the vkBeginCommandBuffer commands used to begin recording each element of pCommandBuffers must be compatible with the current render pass

  • VUID-vkCmdExecuteCommands-pNext-02865
    If vkCmdExecuteCommands is being called within a render pass instance that included VkRenderPassTransformBeginInfoQCOM in the pNext chain of VkRenderPassBeginInfo, then each element of pCommandBuffers must have been recorded with VkCommandBufferInheritanceRenderPassTransformInfoQCOM in the pNext chain of VkCommandBufferBeginInfo

  • VUID-vkCmdExecuteCommands-pNext-02866
    If vkCmdExecuteCommands is being called within a render pass instance that included VkRenderPassTransformBeginInfoQCOM in the pNext chain of VkRenderPassBeginInfo, then each element of pCommandBuffers must have been recorded with VkCommandBufferInheritanceRenderPassTransformInfoQCOM::transform identical to VkRenderPassTransformBeginInfoQCOM::transform

  • VUID-vkCmdExecuteCommands-pNext-02867
    If vkCmdExecuteCommands is being called within a render pass instance that included VkRenderPassTransformBeginInfoQCOM in the pNext chain of VkRenderPassBeginInfo, then each element of pCommandBuffers must have been recorded with VkCommandBufferInheritanceRenderPassTransformInfoQCOM::renderArea identical to VkRenderPassBeginInfo::renderArea

  • VUID-vkCmdExecuteCommands-pCommandBuffers-00100
    If vkCmdExecuteCommands is not being called within a render pass instance, each element of pCommandBuffers must not have been recorded with the VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT

  • VUID-vkCmdExecuteCommands-commandBuffer-00101
    If the inheritedQueries feature is not enabled, commandBuffer must not have any queries active

  • VUID-vkCmdExecuteCommands-commandBuffer-00102
    If commandBuffer has a VK_QUERY_TYPE_OCCLUSION query active, then each element of pCommandBuffers must have been recorded with VkCommandBufferInheritanceInfo::occlusionQueryEnable set to VK_TRUE

  • VUID-vkCmdExecuteCommands-commandBuffer-00103
    If commandBuffer has a VK_QUERY_TYPE_OCCLUSION query active, then each element of pCommandBuffers must have been recorded with VkCommandBufferInheritanceInfo::queryFlags having all bits set that are set for the query

  • VUID-vkCmdExecuteCommands-commandBuffer-00104
    If commandBuffer has a VK_QUERY_TYPE_PIPELINE_STATISTICS query active, then each element of pCommandBuffers must have been recorded with VkCommandBufferInheritanceInfo::pipelineStatistics having all bits set that are set in the VkQueryPool the query uses

  • VUID-vkCmdExecuteCommands-pCommandBuffers-00105
    Each element of pCommandBuffers must not begin any query types that are active in commandBuffer

  • VUID-vkCmdExecuteCommands-commandBuffer-07594
    commandBuffer must not have any queries other than VK_QUERY_TYPE_OCCLUSION and VK_QUERY_TYPE_PIPELINE_STATISTICS active

  • VUID-vkCmdExecuteCommands-commandBuffer-01820
    If commandBuffer is a protected command buffer and protectedNoFault is not supported, each element of pCommandBuffers must be a protected command buffer

  • VUID-vkCmdExecuteCommands-commandBuffer-01821
    If commandBuffer is an unprotected command buffer and protectedNoFault is not supported, each element of pCommandBuffers must be an unprotected command buffer

  • VUID-vkCmdExecuteCommands-None-02286
    This command must not be recorded when transform feedback is active

  • VUID-vkCmdExecuteCommands-commandBuffer-06533
    If vkCmdExecuteCommands is being called within a render pass instance and any recorded command in commandBuffer in the current subpass will write to an image subresource as an attachment, commands recorded in elements of pCommandBuffers must not read from the memory backing that image subresource in any other way

  • VUID-vkCmdExecuteCommands-commandBuffer-06534
    If vkCmdExecuteCommands is being called within a render pass instance and any recorded command in commandBuffer in the current subpass will read from an image subresource used as an attachment in any way other than as an attachment, commands recorded in elements of pCommandBuffers must not write to that image subresource as an attachment

  • VUID-vkCmdExecuteCommands-pCommandBuffers-06535
    If vkCmdExecuteCommands is being called within a render pass instance and any recorded command in a given element of pCommandBuffers will write to an image subresource as an attachment, commands recorded in elements of pCommandBuffers at a higher index must not read from the memory backing that image subresource in any other way

  • VUID-vkCmdExecuteCommands-pCommandBuffers-06536
    If vkCmdExecuteCommands is being called within a render pass instance and any recorded command in a given element of pCommandBuffers will read from an image subresource used as an attachment in any way other than as an attachment, commands recorded in elements of pCommandBuffers at a higher index must not write to that image subresource as an attachment

  • VUID-vkCmdExecuteCommands-pCommandBuffers-06021
    If pCommandBuffers contains any suspended render pass instances, there must be no action or synchronization commands between that render pass instance and any render pass instance that resumes it

  • VUID-vkCmdExecuteCommands-pCommandBuffers-06022
    If pCommandBuffers contains any suspended render pass instances, there must be no render pass instances between that render pass instance and any render pass instance that resumes it

  • VUID-vkCmdExecuteCommands-variableSampleLocations-06023
    If the variableSampleLocations limit is not supported, and any element of pCommandBuffers contains any suspended render pass instances, where a graphics pipeline has been bound, any pipelines bound in the render pass instance that resumes it, or any subsequent render pass instances that resume from that one and so on, must use the same sample locations

  • VUID-vkCmdExecuteCommands-flags-06024
    If vkCmdExecuteCommands is being called within a render pass instance begun with vkCmdBeginRendering, its VkRenderingInfo::flags parameter must have included VK_RENDERING_CONTENTS_SECONDARY_COMMAND_BUFFERS_BIT

  • VUID-vkCmdExecuteCommands-pBeginInfo-06025
    If vkCmdExecuteCommands is being called within a render pass instance begun with vkCmdBeginRendering, the render passes specified in the pBeginInfo->pInheritanceInfo->renderPass members of the vkBeginCommandBuffer commands used to begin recording each element of pCommandBuffers must be VK_NULL_HANDLE

  • VUID-vkCmdExecuteCommands-flags-06026
    If vkCmdExecuteCommands is being called within a render pass instance begun with vkCmdBeginRendering, the flags member of the VkCommandBufferInheritanceRenderingInfo structure included in the pNext chain of VkCommandBufferBeginInfo::pInheritanceInfo used to begin recording each element of pCommandBuffers must be equal to the VkRenderingInfo::flags parameter to vkCmdBeginRendering, excluding VK_RENDERING_CONTENTS_SECONDARY_COMMAND_BUFFERS_BIT

  • VUID-vkCmdExecuteCommands-colorAttachmentCount-06027
    If vkCmdExecuteCommands is being called within a render pass instance begun with vkCmdBeginRendering, the colorAttachmentCount member of the VkCommandBufferInheritanceRenderingInfo structure included in the pNext chain of VkCommandBufferBeginInfo::pInheritanceInfo used to begin recording each element of pCommandBuffers must be equal to the VkRenderingInfo::colorAttachmentCount parameter to vkCmdBeginRendering

  • VUID-vkCmdExecuteCommands-imageView-06028
    If vkCmdExecuteCommands is being called within a render pass instance begun with vkCmdBeginRendering, if the imageView member of an element of the VkRenderingInfo::pColorAttachments parameter to vkCmdBeginRendering is not VK_NULL_HANDLE, the corresponding element of the pColorAttachmentFormats member of the VkCommandBufferInheritanceRenderingInfo structure included in the pNext chain of VkCommandBufferBeginInfo::pInheritanceInfo used to begin recording each element of pCommandBuffers must be equal to the format used to create that image view

  • VUID-vkCmdExecuteCommands-imageView-07606
    If vkCmdExecuteCommands is being called within a render pass instance begun with vkCmdBeginRendering, if the imageView member of an element of the VkRenderingInfo::pColorAttachments parameter to vkCmdBeginRendering is VK_NULL_HANDLE, the corresponding element of the pColorAttachmentFormats member of the VkCommandBufferInheritanceRenderingInfo structure included in the pNext chain of VkCommandBufferBeginInfo::pInheritanceInfo used to begin recording each element of pCommandBuffers must be VK_FORMAT_UNDEFINED

  • VUID-vkCmdExecuteCommands-pDepthAttachment-06029
    If vkCmdExecuteCommands is being called within a render pass instance begun with vkCmdBeginRendering, if the VkRenderingInfo::pDepthAttachment->imageView parameter to vkCmdBeginRendering is not VK_NULL_HANDLE, the value of the depthAttachmentFormat member of the VkCommandBufferInheritanceRenderingInfo structure included in the pNext chain of VkCommandBufferBeginInfo::pInheritanceInfo used to begin recording each element of pCommandBuffers must be equal to the format used to create that image view

  • VUID-vkCmdExecuteCommands-pStencilAttachment-06030
    If vkCmdExecuteCommands is being called within a render pass instance begun with vkCmdBeginRendering, if the VkRenderingInfo::pStencilAttachment->imageView parameter to vkCmdBeginRendering is not VK_NULL_HANDLE, the value of the stencilAttachmentFormat member of the VkCommandBufferInheritanceRenderingInfo structure included in the pNext chain of VkCommandBufferBeginInfo::pInheritanceInfo used to begin recording each element of pCommandBuffers must be equal to the format used to create that image view

  • VUID-vkCmdExecuteCommands-pDepthAttachment-06774
    If vkCmdExecuteCommands is being called within a render pass instance begun with vkCmdBeginRendering and the VkRenderingInfo::pDepthAttachment->imageView parameter to vkCmdBeginRendering was VK_NULL_HANDLE, the value of the depthAttachmentFormat member of the VkCommandBufferInheritanceRenderingInfo structure included in the pNext chain of VkCommandBufferBeginInfo::pInheritanceInfo used to begin recording each element of pCommandBuffers must be VK_FORMAT_UNDEFINED

  • VUID-vkCmdExecuteCommands-pStencilAttachment-06775
    If vkCmdExecuteCommands is being called within a render pass instance begun with vkCmdBeginRendering and the VkRenderingInfo::pStencilAttachment->imageView parameter to vkCmdBeginRendering was VK_NULL_HANDLE, the value of the stencilAttachmentFormat member of the VkCommandBufferInheritanceRenderingInfo structure included in the pNext chain of VkCommandBufferBeginInfo::pInheritanceInfo used to begin recording each element of pCommandBuffers must be VK_FORMAT_UNDEFINED

  • VUID-vkCmdExecuteCommands-viewMask-06031
    If vkCmdExecuteCommands is being called within a render pass instance begun with vkCmdBeginRendering, the viewMask member of the VkCommandBufferInheritanceRenderingInfo structure included in the pNext chain of VkCommandBufferBeginInfo::pInheritanceInfo used to begin recording each element of pCommandBuffers must be equal to the VkRenderingInfo::viewMask parameter to vkCmdBeginRendering

  • VUID-vkCmdExecuteCommands-pNext-06032
    If vkCmdExecuteCommands is being called within a render pass instance begun with vkCmdBeginRendering and the pNext chain of VkCommandBufferInheritanceInfo includes a VkAttachmentSampleCountInfoAMD or VkAttachmentSampleCountInfoNV structure, if the imageView member of an element of the VkRenderingInfo::pColorAttachments parameter to vkCmdBeginRendering is not VK_NULL_HANDLE, the corresponding element of the pColorAttachmentSamples member of the VkAttachmentSampleCountInfoAMD or VkAttachmentSampleCountInfoNV structure included in the pNext chain of VkCommandBufferBeginInfo::pInheritanceInfo used to begin recording each element of pCommandBuffers must be equal to the sample count used to create that image view

  • VUID-vkCmdExecuteCommands-pNext-06033
    If vkCmdExecuteCommands is being called within a render pass instance begun with vkCmdBeginRendering and the pNext chain of VkCommandBufferInheritanceInfo includes a VkAttachmentSampleCountInfoAMD or VkAttachmentSampleCountInfoNV structure, if the VkRenderingInfo::pDepthAttachment->imageView parameter to vkCmdBeginRendering is not VK_NULL_HANDLE, the value of the depthStencilAttachmentSamples member of the VkAttachmentSampleCountInfoAMD or VkAttachmentSampleCountInfoNV structure included in the pNext chain of VkCommandBufferBeginInfo::pInheritanceInfo used to begin recording each element of pCommandBuffers must be equal to the sample count used to create that image view

  • VUID-vkCmdExecuteCommands-pNext-06034
    If vkCmdExecuteCommands is being called within a render pass instance begun with vkCmdBeginRendering and the pNext chain of VkCommandBufferInheritanceInfo includes a VkAttachmentSampleCountInfoAMD or VkAttachmentSampleCountInfoNV structure, if the VkRenderingInfo::pStencilAttachment->imageView parameter to vkCmdBeginRendering is not VK_NULL_HANDLE, the value of the depthStencilAttachmentSamples member of the VkAttachmentSampleCountInfoAMD or VkAttachmentSampleCountInfoNV structure included in the pNext chain of VkCommandBufferBeginInfo::pInheritanceInfo used to begin recording each element of pCommandBuffers must be equal to the sample count used to create that image view

  • VUID-vkCmdExecuteCommands-pNext-06035
    If vkCmdExecuteCommands is being called within a render pass instance begun with vkCmdBeginRendering and the pNext chain of VkCommandBufferInheritanceInfo does not include a VkAttachmentSampleCountInfoAMD or VkAttachmentSampleCountInfoNV structure, if the imageView member of an element of the VkRenderingInfo::pColorAttachments parameter to vkCmdBeginRendering is not VK_NULL_HANDLE, the value of VkCommandBufferInheritanceRenderingInfo::rasterizationSamples must be equal to the sample count used to create that image view

  • VUID-vkCmdExecuteCommands-pNext-06036
    If vkCmdExecuteCommands is being called within a render pass instance begun with vkCmdBeginRendering and the pNext chain of VkCommandBufferInheritanceInfo does not include a VkAttachmentSampleCountInfoAMD or VkAttachmentSampleCountInfoNV structure, if the VkRenderingInfo::pDepthAttachment->imageView parameter to vkCmdBeginRendering is not VK_NULL_HANDLE, the value of VkCommandBufferInheritanceRenderingInfo::rasterizationSamples must be equal to the sample count used to create that image view

  • VUID-vkCmdExecuteCommands-pNext-06037
    If vkCmdExecuteCommands is being called within a render pass instance begun with vkCmdBeginRendering and the pNext chain of VkCommandBufferInheritanceInfo does not include a VkAttachmentSampleCountInfoAMD or VkAttachmentSampleCountInfoNV structure, if the VkRenderingInfo::pStencilAttachment->imageView parameter to vkCmdBeginRendering is not VK_NULL_HANDLE, the value of VkCommandBufferInheritanceRenderingInfo::rasterizationSamples must be equal to the sample count used to create that image view

  • VUID-vkCmdExecuteCommands-pNext-09299
    If vkCmdExecuteCommands is being called within a render pass instance begun with vkCmdBeginRendering, with any color attachment using a resolve mode of VK_RESOLVE_MODE_EXTERNAL_FORMAT_DOWNSAMPLE_ANDROID, the pNext chain of VkCommandBufferInheritanceInfo used to create each element of pCommandBuffers must include a VkExternalFormatANDROID structure with an externalFormat matching that used to create the resolve attachment in the render pass

  • VUID-vkCmdExecuteCommands-pNext-09300
    If vkCmdExecuteCommands is being called within a render pass instance begun with vkCmdBeginRendering with any color attachment using a resolve mode of VK_RESOLVE_MODE_EXTERNAL_FORMAT_DOWNSAMPLE_ANDROID, and the pNext chain of VkCommandBufferInheritanceInfo does not include a VkAttachmentSampleCountInfoAMD or VkAttachmentSampleCountInfoNV structure, the value of VkCommandBufferInheritanceRenderingInfo::rasterizationSamples must be VK_SAMPLE_COUNT_1_BIT

  • VUID-vkCmdExecuteCommands-commandBuffer-09375
    commandBuffer must not be a secondary command buffer unless the nestedCommandBuffer feature is enabled

  • VUID-vkCmdExecuteCommands-nestedCommandBuffer-09376
    If the nestedCommandBuffer feature is enabled, the command buffer nesting level of each element of pCommandBuffers must be less than maxCommandBufferNestingLevel

  • VUID-vkCmdExecuteCommands-nestedCommandBufferRendering-09377
    If the nestedCommandBufferRendering feature is not enabled, and commandBuffer is a secondary command buffer, commandBuffer must not have been recorded with VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT

  • VUID-vkCmdExecuteCommands-nestedCommandBufferSimultaneousUse-09378
    If the nestedCommandBufferSimultaneousUse feature is not enabled, and commandBuffer is a secondary command buffer, each element of pCommandBuffers must not have been recorded with VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT

  • VUID-vkCmdExecuteCommands-pCommandBuffers-09504
    If vkCmdExecuteCommands is being called within a render pass instance begun with vkCmdBeginRendering, the color attachment mapping state specified by VkRenderingAttachmentLocationInfoKHR in the inheritance info of each element of pCommandBuffers and in the current state of commandBuffer must match

  • VUID-vkCmdExecuteCommands-pCommandBuffers-09505
    If vkCmdExecuteCommands is being called within a render pass instance begun with vkCmdBeginRendering, the input attachment mapping state specified by VkRenderingInputAttachmentIndexInfoKHR in the inheritance info of each element of pCommandBuffers and in the current state of commandBuffer must match

Valid Usage (Implicit)

  • VUID-vkCmdExecuteCommands-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdExecuteCommands-pCommandBuffers-parameter
    pCommandBuffers must be a valid pointer to an array of commandBufferCount valid VkCommandBuffer handles

  • VUID-vkCmdExecuteCommands-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdExecuteCommands-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support transfer, graphics, or compute operations

  • VUID-vkCmdExecuteCommands-videocoding
    This command must only be called outside of a video coding scope

  • VUID-vkCmdExecuteCommands-commandBufferCount-arraylength
    commandBufferCount must be greater than 0

  • VUID-vkCmdExecuteCommands-commonparent
    Both of commandBuffer, and the elements of pCommandBuffers must have been created, allocated, or retrieved from the same VkDevice

Host Synchronization

  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Video Coding Scope Supported Queue Types Command Type

Primary
Secondary

Both

Outside

Transfer
Graphics
Compute

Indirection

6.8. Nested Command Buffers

In addition to secondary command buffer execution from primary command buffers, an implementation may support nested command buffers, which enable secondary command buffers to be executed from other secondary command buffers. If the nestedCommandBuffer feature is enabled, the implementation supports nested command buffers.

Nested command buffer execution works the same as primary-to-secondary execution, except that it is subject to some additional implementation-defined limits.

Each secondary command buffer has a command buffer nesting level, which is determined at vkEndCommandBuffer time and evaluated at vkCmdExecuteCommands time. A secondary command buffer that executes no other secondary command buffers has a command buffer nesting level of zero. Otherwise, the command buffer nesting level of a secondary command buffer is equal to the maximum nesting level of all secondary command buffers executed by that command buffer plus one. Some implementations may have a limit on the maximum nesting level of secondary command buffers that can be recorded. This limit is advertised in maxCommandBufferNestingLevel.

If the nestedCommandBufferRendering feature is enabled, the implementation supports calling vkCmdExecuteCommands inside secondary command buffers recorded with VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT. If the nestedCommandBufferSimultaneousUse feature is enabled, the implementation supports calling vkCmdExecuteCommands with secondary command buffers recorded with VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT.

Whenever vkCmdExecuteCommands is recorded inside a secondary command buffer recorded with VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT, each member of pCommandBuffers must have been recorded with a VkCommandBufferBeginInfo with VkCommandBufferInheritanceInfo compatible with the VkCommandBufferInheritanceInfo of the command buffer into which the vkCmdExecuteCommands call is being recorded. The VkCommandBufferInheritanceRenderingInfo structures are compatible when the VkCommandBufferInheritanceRenderingInfo::renderpass are compatible, or if they are VK_NULL_HANDLE then the VkCommandBufferInheritanceRenderingInfo members match, and all other members of VkCommandBufferInheritanceRenderingInfo match. This requirement applies recursively, down to the most nested command buffer and up to the command buffer where the render pass was originally begun.

6.9. Command Buffer Device Mask

Each command buffer has a piece of state storing the current device mask of the command buffer. This mask controls which physical devices within the logical device all subsequent commands will execute on, including state-setting commands, action commands, and synchronization commands.

Scissor, exclusive scissor, and viewport state (excluding the count of each) can be set to different values on each physical device (only when set as dynamic state), and each physical device will render using its local copy of the state. Other state is shared between physical devices, such that all physical devices use the most recently set values for the state. However, when recording an action command that uses a piece of state, the most recent command that set that state must have included all physical devices that execute the action command in its current device mask.

The command buffer’s device mask is orthogonal to the pCommandBufferDeviceMasks member of VkDeviceGroupSubmitInfo. Commands only execute on a physical device if the device index is set in both device masks.

If the pNext chain of VkCommandBufferBeginInfo includes a VkDeviceGroupCommandBufferBeginInfo structure, then that structure includes an initial device mask for the command buffer.

The VkDeviceGroupCommandBufferBeginInfo structure is defined as:

// Provided by VK_VERSION_1_1
typedef struct VkDeviceGroupCommandBufferBeginInfo {
    VkStructureType    sType;
    const void*        pNext;
    uint32_t           deviceMask;
} VkDeviceGroupCommandBufferBeginInfo;

or the equivalent

// Provided by VK_KHR_device_group
typedef VkDeviceGroupCommandBufferBeginInfo VkDeviceGroupCommandBufferBeginInfoKHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • deviceMask is the initial value of the command buffer’s device mask.

The initial device mask also acts as an upper bound on the set of devices that can ever be in the device mask in the command buffer.

If this structure is not present, the initial value of a command buffer’s device mask is set to include all physical devices in the logical device when the command buffer begins recording.

Valid Usage

  • VUID-VkDeviceGroupCommandBufferBeginInfo-deviceMask-00106
    deviceMask must be a valid device mask value

  • VUID-VkDeviceGroupCommandBufferBeginInfo-deviceMask-00107
    deviceMask must not be zero

Valid Usage (Implicit)

  • VUID-VkDeviceGroupCommandBufferBeginInfo-sType-sType
    sType must be VK_STRUCTURE_TYPE_DEVICE_GROUP_COMMAND_BUFFER_BEGIN_INFO

To update the current device mask of a command buffer, call:

// Provided by VK_VERSION_1_1
void vkCmdSetDeviceMask(
    VkCommandBuffer                             commandBuffer,
    uint32_t                                    deviceMask);

or the equivalent command

// Provided by VK_KHR_device_group
void vkCmdSetDeviceMaskKHR(
    VkCommandBuffer                             commandBuffer,
    uint32_t                                    deviceMask);

  • commandBuffer is command buffer whose current device mask is modified.

  • deviceMask is the new value of the current device mask.

deviceMask is used to filter out subsequent commands from executing on all physical devices whose bit indices are not set in the mask, except commands beginning a render pass instance, commands transitioning to the next subpass in the render pass instance, and commands ending a render pass instance, which always execute on the set of physical devices whose bit indices are included in the deviceMask member of the VkDeviceGroupRenderPassBeginInfo structure passed to the command beginning the corresponding render pass instance.

Valid Usage

  • VUID-vkCmdSetDeviceMask-deviceMask-00108
    deviceMask must be a valid device mask value

  • VUID-vkCmdSetDeviceMask-deviceMask-00109
    deviceMask must not be zero

  • VUID-vkCmdSetDeviceMask-deviceMask-00110
    deviceMask must not include any set bits that were not in the VkDeviceGroupCommandBufferBeginInfo::deviceMask value when the command buffer began recording

  • VUID-vkCmdSetDeviceMask-deviceMask-00111
    If vkCmdSetDeviceMask is called inside a render pass instance, deviceMask must not include any set bits that were not in the VkDeviceGroupRenderPassBeginInfo::deviceMask value when the render pass instance began recording

Valid Usage (Implicit)

  • VUID-vkCmdSetDeviceMask-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdSetDeviceMask-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdSetDeviceMask-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support graphics, compute, or transfer operations

Host Synchronization

  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Video Coding Scope Supported Queue Types Command Type

Primary
Secondary

Both

Both

Graphics
Compute
Transfer

State

7. Synchronization and Cache Control

Synchronization of access to resources is primarily the responsibility of the application in Vulkan. The order of execution of commands with respect to the host and other commands on the device has few implicit guarantees, and needs to be explicitly specified. Memory caches and other optimizations are also explicitly managed, requiring that the flow of data through the system is largely under application control.

Whilst some implicit guarantees exist between commands, five explicit synchronization mechanisms are exposed by Vulkan:

Fences

Fences can be used to communicate to the host that execution of some task on the device has completed, controlling resource access between host and device.

Semaphores

Semaphores can be used to control resource access across multiple queues.

Events

Events provide a fine-grained synchronization primitive which can be signaled either within a command buffer or by the host, and can be waited upon within a command buffer or queried on the host. Events can be used to control resource access within a single queue.

Pipeline Barriers

Pipeline barriers also provide synchronization control within a command buffer, but at a single point, rather than with separate signal and wait operations. Pipeline barriers can be used to control resource access within a single queue.

Render Pass Objects

Render pass objects provide a synchronization framework for rendering tasks, built upon the concepts in this chapter. Many cases that would otherwise need an application to use other synchronization primitives can be expressed more efficiently as part of a render pass. Render pass objects can be used to control resource access within a single queue.

7.1. Execution and Memory Dependencies

An operation is an arbitrary amount of work to be executed on the host, a device, or an external entity such as a presentation engine. Synchronization commands introduce explicit execution dependencies, and memory dependencies between two sets of operations defined by the command’s two synchronization scopes.

The synchronization scopes define which other operations a synchronization command is able to create execution dependencies with. Any type of operation that is not in a synchronization command’s synchronization scopes will not be included in the resulting dependency. For example, for many synchronization commands, the synchronization scopes can be limited to just operations executing in specific pipeline stages, which allows other pipeline stages to be excluded from a dependency. Other scoping options are possible, depending on the particular command.

An execution dependency is a guarantee that for two sets of operations, the first set must happen-before the second set. If an operation happens-before another operation, then the first operation must complete before the second operation is initiated. More precisely:

  • Let Ops1 and Ops2 be separate sets of operations.

  • Let Sync be a synchronization command.

  • Let Scope1st and Scope2nd be the synchronization scopes of Sync.

  • Let ScopedOps1 be the intersection of sets Ops1 and Scope1st.

  • Let ScopedOps2 be the intersection of sets Ops2 and Scope2nd.

  • Submitting Ops1, Sync and Ops2 for execution, in that order, will result in execution dependency ExeDep between ScopedOps1 and ScopedOps2.

  • Execution dependency ExeDep guarantees that ScopedOps1 happen-before ScopedOps2.

An execution dependency chain is a sequence of execution dependencies that form a happens-before relation between the first dependency’s ScopedOps1 and the final dependency’s ScopedOps2. For each consecutive pair of execution dependencies, a chain exists if the intersection of Scope2nd in the first dependency and Scope1st in the second dependency is not an empty set. The formation of a single execution dependency from an execution dependency chain can be described by substituting the following in the description of execution dependencies:

  • Let Sync be a set of synchronization commands that generate an execution dependency chain.

  • Let Scope1st be the first synchronization scope of the first command in Sync.

  • Let Scope2nd be the second synchronization scope of the last command in Sync.

Execution dependencies alone are not sufficient to guarantee that values resulting from writes in one set of operations can be read from another set of operations.

Three additional types of operations are used to control memory access. Availability operations cause the values generated by specified memory write accesses to become available to a memory domain for future access. Any available value remains available until a subsequent write to the same memory location occurs (whether it is made available or not) or the memory is freed. Memory domain operations cause writes that are available to a source memory domain to become available to a destination memory domain (an example of this is making writes available to the host domain available to the device domain). Visibility operations cause values available to a memory domain to become visible to specified memory accesses.

Availability, visibility, memory domains, and memory domain operations are formally defined in the Availability and Visibility section of the Memory Model chapter. Which API operations perform each of these operations is defined in Availability, Visibility, and Domain Operations.

A memory dependency is an execution dependency which includes availability and visibility operations such that:

  • The first set of operations happens-before the availability operation.

  • The availability operation happens-before the visibility operation.

  • The visibility operation happens-before the second set of operations.

Once written values are made visible to a particular type of memory access, they can be read or written by that type of memory access. Most synchronization commands in Vulkan define a memory dependency.

The specific memory accesses that are made available and visible are defined by the access scopes of a memory dependency. Any type of access that is in a memory dependency’s first access scope and occurs in ScopedOps1 is made available. Any type of access that is in a memory dependency’s second access scope and occurs in ScopedOps2 has any available writes made visible to it. Any type of operation that is not in a synchronization command’s access scopes will not be included in the resulting dependency.

A memory dependency enforces availability and visibility of memory accesses and execution order between two sets of operations. Adding to the description of execution dependency chains:

  • Let MemOps1 be the set of memory accesses performed by ScopedOps1.

  • Let MemOps2 be the set of memory accesses performed by ScopedOps2.

  • Let AccessScope1st be the first access scope of the first command in the Sync chain.

  • Let AccessScope2nd be the second access scope of the last command in the Sync chain.

  • Let ScopedMemOps1 be the intersection of sets MemOps1 and AccessScope1st.

  • Let ScopedMemOps2 be the intersection of sets MemOps2 and AccessScope2nd.

  • Submitting Ops1, Sync, and Ops2 for execution, in that order, will result in a memory dependency MemDep between ScopedOps1 and ScopedOps2.

  • Memory dependency MemDep guarantees that:

    • Memory writes in ScopedMemOps1 are made available.

    • Available memory writes, including those from ScopedMemOps1, are made visible to ScopedMemOps2.

Note

Execution and memory dependencies are used to solve data hazards, i.e. to ensure that read and write operations occur in a well-defined order. Write-after-read hazards can be solved with just an execution dependency, but read-after-write and write-after-write hazards need appropriate memory dependencies to be included between them. If an application does not include dependencies to solve these hazards, the results and execution orders of memory accesses are undefined.

7.1.1. Image Layout Transitions

Image subresources can be transitioned from one layout to another as part of a memory dependency (e.g. by using an image memory barrier). When a layout transition is specified in a memory dependency, it happens-after the availability operations in the memory dependency, and happens-before the visibility operations. Image layout transitions may perform read and write accesses on all memory bound to the image subresource range, so applications must ensure that all memory writes have been made available before a layout transition is executed. Available memory is automatically made visible to a layout transition, and writes performed by a layout transition are automatically made available.

Layout transitions always apply to a particular image subresource range, and specify both an old layout and new layout. The old layout must either be VK_IMAGE_LAYOUT_UNDEFINED, or match the current layout of the image subresource range. If the old layout matches the current layout of the image subresource range, the transition preserves the contents of that range. If the old layout is VK_IMAGE_LAYOUT_UNDEFINED, the contents of that range may be discarded.

Note

Image layout transitions with VK_IMAGE_LAYOUT_UNDEFINED allow the implementation to discard the image subresource range, which can provide performance or power benefits. Tile-based architectures may be able to avoid flushing tile data to memory, and immediate style renderers may be able to achieve fast metadata clears to reinitialize frame buffer compression state, or similar.

If the contents of an attachment are not needed after a render pass completes, then applications should use VK_ATTACHMENT_STORE_OP_DONT_CARE.

As image layout transitions may perform read and write accesses on the memory bound to the image, if the image subresource affected by the layout transition is bound to peer memory for any device in the current device mask then the memory heap the bound memory comes from must support the VK_PEER_MEMORY_FEATURE_GENERIC_SRC_BIT and VK_PEER_MEMORY_FEATURE_GENERIC_DST_BIT capabilities as returned by vkGetDeviceGroupPeerMemoryFeatures.

Note

Applications must ensure that layout transitions happen-after all operations accessing the image with the old layout, and happen-before any operations that will access the image with the new layout. Layout transitions are potentially read/write operations, so not defining appropriate memory dependencies to guarantee this will result in a data race.

Image layout transitions interact with memory aliasing.

Layout transitions that are performed via image memory barriers execute in their entirety in submission order, relative to other image layout transitions submitted to the same queue, including those performed by render passes. In effect there is an implicit execution dependency from each such layout transition to all layout transitions previously submitted to the same queue.

The image layout of each image subresource of a depth/stencil image created with VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT is dependent on the last sample locations used to render to the image subresource as a depth/stencil attachment, thus when the image member of an image memory barrier is an image created with this flag the application can chain a VkSampleLocationsInfoEXT structure to the pNext chain of VkImageMemoryBarrier2 or VkImageMemoryBarrier to specify the sample locations to use during any image layout transition.

If the VkSampleLocationsInfoEXT structure does not match the sample location state last used to render to the image subresource range specified by subresourceRange, or if no VkSampleLocationsInfoEXT structure is present, then the contents of the given image subresource range becomes undefined as if oldLayout would equal VK_IMAGE_LAYOUT_UNDEFINED.

7.1.2. Pipeline Stages

The work performed by an action command consists of multiple operations, which are performed as a sequence of logically independent steps known as pipeline stages. The exact pipeline stages executed depend on the particular command that is used, and current command buffer state when the command was recorded.

Note

Operations performed by synchronization commands (e.g. availability and visibility operations) are not executed by a defined pipeline stage. However other commands can still synchronize with them by using the synchronization scopes to create a dependency chain.

Execution of operations across pipeline stages must adhere to implicit ordering guarantees, particularly including pipeline stage order. Otherwise, execution across pipeline stages may overlap or execute out of order with regards to other stages, unless otherwise enforced by an execution dependency.

Several of the synchronization commands include pipeline stage parameters, restricting the synchronization scopes for that command to just those stages. This allows fine grained control over the exact execution dependencies and accesses performed by action commands. Implementations should use these pipeline stages to avoid unnecessary stalls or cache flushing.

Bits which can be set in a VkPipelineStageFlags2 mask, specifying stages of execution, are:

// Provided by VK_VERSION_1_3
// Flag bits for VkPipelineStageFlagBits2
typedef VkFlags64 VkPipelineStageFlagBits2;
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_NONE = 0ULL;
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_NONE_KHR = 0ULL;
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_TOP_OF_PIPE_BIT = 0x00000001ULL;
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_TOP_OF_PIPE_BIT_KHR = 0x00000001ULL;
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_DRAW_INDIRECT_BIT = 0x00000002ULL;
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_DRAW_INDIRECT_BIT_KHR = 0x00000002ULL;
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_VERTEX_INPUT_BIT = 0x00000004ULL;
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_VERTEX_INPUT_BIT_KHR = 0x00000004ULL;
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_VERTEX_SHADER_BIT = 0x00000008ULL;
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_VERTEX_SHADER_BIT_KHR = 0x00000008ULL;
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_TESSELLATION_CONTROL_SHADER_BIT = 0x00000010ULL;
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_TESSELLATION_CONTROL_SHADER_BIT_KHR = 0x00000010ULL;
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_TESSELLATION_EVALUATION_SHADER_BIT = 0x00000020ULL;
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_TESSELLATION_EVALUATION_SHADER_BIT_KHR = 0x00000020ULL;
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_GEOMETRY_SHADER_BIT = 0x00000040ULL;
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_GEOMETRY_SHADER_BIT_KHR = 0x00000040ULL;
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_FRAGMENT_SHADER_BIT = 0x00000080ULL;
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_FRAGMENT_SHADER_BIT_KHR = 0x00000080ULL;
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_EARLY_FRAGMENT_TESTS_BIT = 0x00000100ULL;
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_EARLY_FRAGMENT_TESTS_BIT_KHR = 0x00000100ULL;
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_LATE_FRAGMENT_TESTS_BIT = 0x00000200ULL;
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_LATE_FRAGMENT_TESTS_BIT_KHR = 0x00000200ULL;
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_COLOR_ATTACHMENT_OUTPUT_BIT = 0x00000400ULL;
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_COLOR_ATTACHMENT_OUTPUT_BIT_KHR = 0x00000400ULL;
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_COMPUTE_SHADER_BIT = 0x00000800ULL;
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_COMPUTE_SHADER_BIT_KHR = 0x00000800ULL;
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_ALL_TRANSFER_BIT = 0x00001000ULL;
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_ALL_TRANSFER_BIT_KHR = 0x00001000ULL;
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_TRANSFER_BIT = 0x00001000ULL;
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_TRANSFER_BIT_KHR = 0x00001000ULL;
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_BOTTOM_OF_PIPE_BIT = 0x00002000ULL;
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_BOTTOM_OF_PIPE_BIT_KHR = 0x00002000ULL;
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_HOST_BIT = 0x00004000ULL;
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_HOST_BIT_KHR = 0x00004000ULL;
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT = 0x00008000ULL;
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT_KHR = 0x00008000ULL;
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT = 0x00010000ULL;
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT_KHR = 0x00010000ULL;
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_COPY_BIT = 0x100000000ULL;
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_COPY_BIT_KHR = 0x100000000ULL;
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_RESOLVE_BIT = 0x200000000ULL;
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_RESOLVE_BIT_KHR = 0x200000000ULL;
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_BLIT_BIT = 0x400000000ULL;
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_BLIT_BIT_KHR = 0x400000000ULL;
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_CLEAR_BIT = 0x800000000ULL;
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_CLEAR_BIT_KHR = 0x800000000ULL;
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_INDEX_INPUT_BIT = 0x1000000000ULL;
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_INDEX_INPUT_BIT_KHR = 0x1000000000ULL;
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_VERTEX_ATTRIBUTE_INPUT_BIT = 0x2000000000ULL;
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_VERTEX_ATTRIBUTE_INPUT_BIT_KHR = 0x2000000000ULL;
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_PRE_RASTERIZATION_SHADERS_BIT = 0x4000000000ULL;
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_PRE_RASTERIZATION_SHADERS_BIT_KHR = 0x4000000000ULL;
// Provided by VK_KHR_video_decode_queue
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_VIDEO_DECODE_BIT_KHR = 0x04000000ULL;
// Provided by VK_KHR_video_encode_queue
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_VIDEO_ENCODE_BIT_KHR = 0x08000000ULL;
// Provided by VK_KHR_synchronization2 with VK_EXT_transform_feedback
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_TRANSFORM_FEEDBACK_BIT_EXT = 0x01000000ULL;
// Provided by VK_KHR_synchronization2 with VK_EXT_conditional_rendering
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_CONDITIONAL_RENDERING_BIT_EXT = 0x00040000ULL;
// Provided by VK_KHR_synchronization2 with VK_NV_device_generated_commands
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_COMMAND_PREPROCESS_BIT_NV = 0x00020000ULL;
// Provided by VK_KHR_synchronization2 with VK_EXT_device_generated_commands
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_COMMAND_PREPROCESS_BIT_EXT = 0x00020000ULL;
// Provided by VK_KHR_fragment_shading_rate with VK_KHR_synchronization2
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR = 0x00400000ULL;
// Provided by VK_KHR_synchronization2 with VK_NV_shading_rate_image
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_SHADING_RATE_IMAGE_BIT_NV = 0x00400000ULL;
// Provided by VK_KHR_acceleration_structure with VK_KHR_synchronization2
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_BUILD_BIT_KHR = 0x02000000ULL;
// Provided by VK_KHR_ray_tracing_pipeline with VK_KHR_synchronization2
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_RAY_TRACING_SHADER_BIT_KHR = 0x00200000ULL;
// Provided by VK_KHR_synchronization2 with VK_NV_ray_tracing
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_RAY_TRACING_SHADER_BIT_NV = 0x00200000ULL;
// Provided by VK_KHR_synchronization2 with VK_NV_ray_tracing
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_BUILD_BIT_NV = 0x02000000ULL;
// Provided by VK_KHR_synchronization2 with VK_EXT_fragment_density_map
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_FRAGMENT_DENSITY_PROCESS_BIT_EXT = 0x00800000ULL;
// Provided by VK_KHR_synchronization2 with VK_NV_mesh_shader
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_TASK_SHADER_BIT_NV = 0x00080000ULL;
// Provided by VK_KHR_synchronization2 with VK_NV_mesh_shader
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_MESH_SHADER_BIT_NV = 0x00100000ULL;
// Provided by VK_KHR_synchronization2 with VK_EXT_mesh_shader
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_TASK_SHADER_BIT_EXT = 0x00080000ULL;
// Provided by VK_KHR_synchronization2 with VK_EXT_mesh_shader
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_MESH_SHADER_BIT_EXT = 0x00100000ULL;
// Provided by VK_HUAWEI_subpass_shading
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_SUBPASS_SHADER_BIT_HUAWEI = 0x8000000000ULL;
// VK_PIPELINE_STAGE_2_SUBPASS_SHADING_BIT_HUAWEI is a deprecated alias
// Provided by VK_HUAWEI_subpass_shading
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_SUBPASS_SHADING_BIT_HUAWEI = 0x8000000000ULL;
// Provided by VK_HUAWEI_invocation_mask
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_INVOCATION_MASK_BIT_HUAWEI = 0x10000000000ULL;
// Provided by VK_KHR_ray_tracing_maintenance1 with VK_KHR_synchronization2 or VK_VERSION_1_3
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_COPY_BIT_KHR = 0x10000000ULL;
// Provided by VK_EXT_opacity_micromap
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_MICROMAP_BUILD_BIT_EXT = 0x40000000ULL;
// Provided by VK_HUAWEI_cluster_culling_shader
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_CLUSTER_CULLING_SHADER_BIT_HUAWEI = 0x20000000000ULL;
// Provided by VK_NV_optical_flow
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_OPTICAL_FLOW_BIT_NV = 0x20000000ULL;

or the equivalent

// Provided by VK_KHR_synchronization2
typedef VkPipelineStageFlagBits2 VkPipelineStageFlagBits2KHR;

  • VK_PIPELINE_STAGE_2_NONE specifies no stages of execution.

  • VK_PIPELINE_STAGE_2_DRAW_INDIRECT_BIT specifies the stage of the pipeline where indirect command parameters are consumed. This stage also includes reading commands written by vkCmdPreprocessGeneratedCommandsNV. This stage also includes reading commands written by vkCmdPreprocessGeneratedCommandsEXT.

  • VK_PIPELINE_STAGE_2_TASK_SHADER_BIT_EXT specifies the task shader stage.

  • VK_PIPELINE_STAGE_2_MESH_SHADER_BIT_EXT specifies the mesh shader stage.

  • VK_PIPELINE_STAGE_2_INDEX_INPUT_BIT specifies the stage of the pipeline where index buffers are consumed.

  • VK_PIPELINE_STAGE_2_VERTEX_ATTRIBUTE_INPUT_BIT specifies the stage of the pipeline where vertex buffers are consumed.

  • VK_PIPELINE_STAGE_2_VERTEX_INPUT_BIT is equivalent to the logical OR of:

    • VK_PIPELINE_STAGE_2_INDEX_INPUT_BIT

    • VK_PIPELINE_STAGE_2_VERTEX_ATTRIBUTE_INPUT_BIT

  • VK_PIPELINE_STAGE_2_VERTEX_SHADER_BIT specifies the vertex shader stage.

  • VK_PIPELINE_STAGE_2_TESSELLATION_CONTROL_SHADER_BIT specifies the tessellation control shader stage.

  • VK_PIPELINE_STAGE_2_TESSELLATION_EVALUATION_SHADER_BIT specifies the tessellation evaluation shader stage.

  • VK_PIPELINE_STAGE_2_GEOMETRY_SHADER_BIT specifies the geometry shader stage.

  • VK_PIPELINE_STAGE_2_PRE_RASTERIZATION_SHADERS_BIT is equivalent to specifying all supported pre-rasterization shader stages:

    • VK_PIPELINE_STAGE_2_VERTEX_SHADER_BIT

    • VK_PIPELINE_STAGE_2_TESSELLATION_CONTROL_SHADER_BIT

    • VK_PIPELINE_STAGE_2_TESSELLATION_EVALUATION_SHADER_BIT

    • VK_PIPELINE_STAGE_2_GEOMETRY_SHADER_BIT

    • VK_PIPELINE_STAGE_2_TASK_SHADER_BIT_EXT

    • VK_PIPELINE_STAGE_2_MESH_SHADER_BIT_EXT

    • VK_PIPELINE_STAGE_2_CLUSTER_CULLING_SHADER_BIT_HUAWEI

  • VK_PIPELINE_STAGE_2_FRAGMENT_SHADER_BIT specifies the fragment shader stage.

  • VK_PIPELINE_STAGE_2_EARLY_FRAGMENT_TESTS_BIT specifies the stage of the pipeline where early fragment tests (depth and stencil tests before fragment shading) are performed. This stage also includes render pass load operations for framebuffer attachments with a depth/stencil format.

  • VK_PIPELINE_STAGE_2_LATE_FRAGMENT_TESTS_BIT specifies the stage of the pipeline where late fragment tests (depth and stencil tests after fragment shading) are performed. This stage also includes render pass store operations for framebuffer attachments with a depth/stencil format.

  • VK_PIPELINE_STAGE_2_COLOR_ATTACHMENT_OUTPUT_BIT specifies the stage of the pipeline where final color values are output from the pipeline. This stage includes blending, logic operations, render pass load and store operations for color attachments, render pass multisample resolve operations, and vkCmdClearAttachments.

  • VK_PIPELINE_STAGE_2_COMPUTE_SHADER_BIT specifies the compute shader stage.

  • VK_PIPELINE_STAGE_2_HOST_BIT specifies a pseudo-stage indicating execution on the host of reads/writes of device memory. This stage is not invoked by any commands recorded in a command buffer.

  • VK_PIPELINE_STAGE_2_COPY_BIT specifies the execution of all copy commands, including vkCmdCopyQueryPoolResults.

  • VK_PIPELINE_STAGE_2_BLIT_BIT specifies the execution of vkCmdBlitImage.

  • VK_PIPELINE_STAGE_2_RESOLVE_BIT specifies the execution of vkCmdResolveImage.

  • VK_PIPELINE_STAGE_2_CLEAR_BIT specifies the execution of clear commands, with the exception of vkCmdClearAttachments.

  • VK_PIPELINE_STAGE_2_ALL_TRANSFER_BIT is equivalent to specifying all of:

    • VK_PIPELINE_STAGE_2_COPY_BIT

    • VK_PIPELINE_STAGE_2_BLIT_BIT

    • VK_PIPELINE_STAGE_2_RESOLVE_BIT

    • VK_PIPELINE_STAGE_2_CLEAR_BIT

    • VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_COPY_BIT_KHR

  • VK_PIPELINE_STAGE_2_RAY_TRACING_SHADER_BIT_KHR specifies the execution of the ray tracing shader stages.

  • VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_BUILD_BIT_KHR specifies the execution of acceleration structure commands or acceleration structure copy commands.

  • VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_COPY_BIT_KHR specifies the execution of acceleration structure copy commands.

  • VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT specifies the execution of all graphics pipeline stages, and is equivalent to the logical OR of:

    • VK_PIPELINE_STAGE_2_DRAW_INDIRECT_BIT

    • VK_PIPELINE_STAGE_2_TASK_SHADER_BIT_EXT

    • VK_PIPELINE_STAGE_2_MESH_SHADER_BIT_EXT

    • VK_PIPELINE_STAGE_2_VERTEX_INPUT_BIT

    • VK_PIPELINE_STAGE_2_VERTEX_SHADER_BIT

    • VK_PIPELINE_STAGE_2_TESSELLATION_CONTROL_SHADER_BIT

    • VK_PIPELINE_STAGE_2_TESSELLATION_EVALUATION_SHADER_BIT

    • VK_PIPELINE_STAGE_2_GEOMETRY_SHADER_BIT

    • VK_PIPELINE_STAGE_2_FRAGMENT_SHADER_BIT

    • VK_PIPELINE_STAGE_2_EARLY_FRAGMENT_TESTS_BIT

    • VK_PIPELINE_STAGE_2_LATE_FRAGMENT_TESTS_BIT

    • VK_PIPELINE_STAGE_2_COLOR_ATTACHMENT_OUTPUT_BIT

    • VK_PIPELINE_STAGE_2_CONDITIONAL_RENDERING_BIT_EXT

    • VK_PIPELINE_STAGE_2_TRANSFORM_FEEDBACK_BIT_EXT

    • VK_PIPELINE_STAGE_2_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR

    • VK_PIPELINE_STAGE_2_FRAGMENT_DENSITY_PROCESS_BIT_EXT

    • VK_PIPELINE_STAGE_2_SUBPASS_SHADER_BIT_HUAWEI

    • VK_PIPELINE_STAGE_2_INVOCATION_MASK_BIT_HUAWEI

    • VK_PIPELINE_STAGE_2_CLUSTER_CULLING_SHADER_BIT_HUAWEI

  • VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT specifies all operations performed by all commands supported on the queue it is used with.

  • VK_PIPELINE_STAGE_2_CONDITIONAL_RENDERING_BIT_EXT specifies the stage of the pipeline where the predicate of conditional rendering is consumed.

  • VK_PIPELINE_STAGE_2_TRANSFORM_FEEDBACK_BIT_EXT specifies the stage of the pipeline where vertex attribute output values are written to the transform feedback buffers.

  • VK_PIPELINE_STAGE_2_COMMAND_PREPROCESS_BIT_NV specifies the stage of the pipeline where device-side generation of commands via vkCmdPreprocessGeneratedCommandsNV is handled.

  • VK_PIPELINE_STAGE_2_COMMAND_PREPROCESS_BIT_EXT specifies the stage of the pipeline where device-side generation of commands via vkCmdPreprocessGeneratedCommandsEXT is handled.

  • VK_PIPELINE_STAGE_2_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR specifies the stage of the pipeline where the fragment shading rate attachment or shading rate image is read to determine the fragment shading rate for portions of a rasterized primitive.

  • VK_PIPELINE_STAGE_2_FRAGMENT_DENSITY_PROCESS_BIT_EXT specifies the stage of the pipeline where the fragment density map is read to generate the fragment areas.

  • VK_PIPELINE_STAGE_2_INVOCATION_MASK_BIT_HUAWEI specifies the stage of the pipeline where the invocation mask image is read by the implementation to optimize the ray dispatch.

  • VK_PIPELINE_STAGE_2_VIDEO_DECODE_BIT_KHR specifies the execution of video decode operations.

  • VK_PIPELINE_STAGE_2_VIDEO_ENCODE_BIT_KHR specifies the execution of video encode operations.

  • VK_PIPELINE_STAGE_2_OPTICAL_FLOW_BIT_NV specifies the stage of the pipeline where optical flow operation are performed.

  • VK_PIPELINE_STAGE_2_SUBPASS_SHADER_BIT_HUAWEI specifies the subpass shading shader stage.

  • VK_PIPELINE_STAGE_2_MICROMAP_BUILD_BIT_EXT specifies the execution of micromap commands.

  • VK_PIPELINE_STAGE_2_CLUSTER_CULLING_SHADER_BIT_HUAWEI specifies the cluster culling shader stage.

  • VK_PIPELINE_STAGE_2_TOP_OF_PIPE_BIT is equivalent to VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT with VkAccessFlags2 set to 0 when specified in the second synchronization scope, but equivalent to VK_PIPELINE_STAGE_2_NONE in the first scope.

  • VK_PIPELINE_STAGE_2_BOTTOM_OF_PIPE_BIT is equivalent to VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT with VkAccessFlags2 set to 0 when specified in the first synchronization scope, but equivalent to VK_PIPELINE_STAGE_2_NONE in the second scope.

Note

The TOP and BOTTOM pipeline stages are deprecated, and applications should prefer VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT and VK_PIPELINE_STAGE_2_NONE.
Note

The VkPipelineStageFlags2 bitmask goes beyond the 31 individual bit flags allowable within a C99 enum, which is how VkPipelineStageFlagBits is defined. The first 31 values are common to both, and are interchangeable.

VkPipelineStageFlags2 is a bitmask type for setting a mask of zero or more VkPipelineStageFlagBits2 flags:

// Provided by VK_VERSION_1_3
typedef VkFlags64 VkPipelineStageFlags2;

or the equivalent

// Provided by VK_KHR_synchronization2
typedef VkPipelineStageFlags2 VkPipelineStageFlags2KHR;

Bits which can be set in a VkPipelineStageFlags mask, specifying stages of execution, are:

// Provided by VK_VERSION_1_0
typedef enum VkPipelineStageFlagBits {
    VK_PIPELINE_STAGE_TOP_OF_PIPE_BIT = 0x00000001,
    VK_PIPELINE_STAGE_DRAW_INDIRECT_BIT = 0x00000002,
    VK_PIPELINE_STAGE_VERTEX_INPUT_BIT = 0x00000004,
    VK_PIPELINE_STAGE_VERTEX_SHADER_BIT = 0x00000008,
    VK_PIPELINE_STAGE_TESSELLATION_CONTROL_SHADER_BIT = 0x00000010,
    VK_PIPELINE_STAGE_TESSELLATION_EVALUATION_SHADER_BIT = 0x00000020,
    VK_PIPELINE_STAGE_GEOMETRY_SHADER_BIT = 0x00000040,
    VK_PIPELINE_STAGE_FRAGMENT_SHADER_BIT = 0x00000080,
    VK_PIPELINE_STAGE_EARLY_FRAGMENT_TESTS_BIT = 0x00000100,
    VK_PIPELINE_STAGE_LATE_FRAGMENT_TESTS_BIT = 0x00000200,
    VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT = 0x00000400,
    VK_PIPELINE_STAGE_COMPUTE_SHADER_BIT = 0x00000800,
    VK_PIPELINE_STAGE_TRANSFER_BIT = 0x00001000,
    VK_PIPELINE_STAGE_BOTTOM_OF_PIPE_BIT = 0x00002000,
    VK_PIPELINE_STAGE_HOST_BIT = 0x00004000,
    VK_PIPELINE_STAGE_ALL_GRAPHICS_BIT = 0x00008000,
    VK_PIPELINE_STAGE_ALL_COMMANDS_BIT = 0x00010000,
  // Provided by VK_VERSION_1_3
    VK_PIPELINE_STAGE_NONE = 0,
  // Provided by VK_EXT_transform_feedback
    VK_PIPELINE_STAGE_TRANSFORM_FEEDBACK_BIT_EXT = 0x01000000,
  // Provided by VK_EXT_conditional_rendering
    VK_PIPELINE_STAGE_CONDITIONAL_RENDERING_BIT_EXT = 0x00040000,
  // Provided by VK_KHR_acceleration_structure
    VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR = 0x02000000,
  // Provided by VK_KHR_ray_tracing_pipeline
    VK_PIPELINE_STAGE_RAY_TRACING_SHADER_BIT_KHR = 0x00200000,
  // Provided by VK_EXT_fragment_density_map
    VK_PIPELINE_STAGE_FRAGMENT_DENSITY_PROCESS_BIT_EXT = 0x00800000,
  // Provided by VK_KHR_fragment_shading_rate
    VK_PIPELINE_STAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR = 0x00400000,
  // Provided by VK_NV_device_generated_commands
    VK_PIPELINE_STAGE_COMMAND_PREPROCESS_BIT_NV = 0x00020000,
  // Provided by VK_EXT_mesh_shader
    VK_PIPELINE_STAGE_TASK_SHADER_BIT_EXT = 0x00080000,
  // Provided by VK_EXT_mesh_shader
    VK_PIPELINE_STAGE_MESH_SHADER_BIT_EXT = 0x00100000,
  // Provided by VK_NV_shading_rate_image
    VK_PIPELINE_STAGE_SHADING_RATE_IMAGE_BIT_NV = VK_PIPELINE_STAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR,
  // Provided by VK_NV_ray_tracing
    VK_PIPELINE_STAGE_RAY_TRACING_SHADER_BIT_NV = VK_PIPELINE_STAGE_RAY_TRACING_SHADER_BIT_KHR,
  // Provided by VK_NV_ray_tracing
    VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_NV = VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR,
  // Provided by VK_NV_mesh_shader
    VK_PIPELINE_STAGE_TASK_SHADER_BIT_NV = VK_PIPELINE_STAGE_TASK_SHADER_BIT_EXT,
  // Provided by VK_NV_mesh_shader
    VK_PIPELINE_STAGE_MESH_SHADER_BIT_NV = VK_PIPELINE_STAGE_MESH_SHADER_BIT_EXT,
  // Provided by VK_KHR_synchronization2
    VK_PIPELINE_STAGE_NONE_KHR = VK_PIPELINE_STAGE_NONE,
  // Provided by VK_EXT_device_generated_commands
    VK_PIPELINE_STAGE_COMMAND_PREPROCESS_BIT_EXT = VK_PIPELINE_STAGE_COMMAND_PREPROCESS_BIT_NV,
} VkPipelineStageFlagBits;

These values all have the same meaning as the equivalently named values for VkPipelineStageFlags2.

  • VK_PIPELINE_STAGE_NONE specifies no stages of execution.

  • VK_PIPELINE_STAGE_DRAW_INDIRECT_BIT specifies the stage of the pipeline where VkDrawIndirect* / VkDispatchIndirect* / VkTraceRaysIndirect* data structures are consumed. This stage also includes reading commands written by vkCmdExecuteGeneratedCommandsNV. This stage also includes reading commands written by vkCmdExecuteGeneratedCommandsEXT.

  • VK_PIPELINE_STAGE_TASK_SHADER_BIT_EXT specifies the task shader stage.

  • VK_PIPELINE_STAGE_MESH_SHADER_BIT_EXT specifies the mesh shader stage.

  • VK_PIPELINE_STAGE_VERTEX_INPUT_BIT specifies the stage of the pipeline where vertex and index buffers are consumed.

  • VK_PIPELINE_STAGE_VERTEX_SHADER_BIT specifies the vertex shader stage.

  • VK_PIPELINE_STAGE_TESSELLATION_CONTROL_SHADER_BIT specifies the tessellation control shader stage.

  • VK_PIPELINE_STAGE_TESSELLATION_EVALUATION_SHADER_BIT specifies the tessellation evaluation shader stage.

  • VK_PIPELINE_STAGE_GEOMETRY_SHADER_BIT specifies the geometry shader stage.

  • VK_PIPELINE_STAGE_FRAGMENT_SHADER_BIT specifies the fragment shader stage.

  • VK_PIPELINE_STAGE_EARLY_FRAGMENT_TESTS_BIT specifies the stage of the pipeline where early fragment tests (depth and stencil tests before fragment shading) are performed. This stage also includes render pass load operations for framebuffer attachments with a depth/stencil format.

  • VK_PIPELINE_STAGE_LATE_FRAGMENT_TESTS_BIT specifies the stage of the pipeline where late fragment tests (depth and stencil tests after fragment shading) are performed. This stage also includes render pass store operations for framebuffer attachments with a depth/stencil format.

  • VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT specifies the stage of the pipeline after blending where the final color values are output from the pipeline. This stage includes blending, logic operations, render pass load and store operations for color attachments, render pass multisample resolve operations, and vkCmdClearAttachments.

  • VK_PIPELINE_STAGE_COMPUTE_SHADER_BIT specifies the execution of a compute shader.

  • VK_PIPELINE_STAGE_TRANSFER_BIT specifies the following commands:

  • VK_PIPELINE_STAGE_HOST_BIT specifies a pseudo-stage indicating execution on the host of reads/writes of device memory. This stage is not invoked by any commands recorded in a command buffer.

  • VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR specifies the execution of vkCmdBuildAccelerationStructureNV, vkCmdCopyAccelerationStructureNV, vkCmdWriteAccelerationStructuresPropertiesNV , vkCmdBuildAccelerationStructuresKHR, vkCmdBuildAccelerationStructuresIndirectKHR, vkCmdCopyAccelerationStructureKHR, vkCmdCopyAccelerationStructureToMemoryKHR, vkCmdCopyMemoryToAccelerationStructureKHR, and vkCmdWriteAccelerationStructuresPropertiesKHR.

  • VK_PIPELINE_STAGE_RAY_TRACING_SHADER_BIT_KHR specifies the execution of the ray tracing shader stages, via vkCmdTraceRaysNV , vkCmdTraceRaysKHR, or vkCmdTraceRaysIndirectKHR

  • VK_PIPELINE_STAGE_ALL_GRAPHICS_BIT specifies the execution of all graphics pipeline stages, and is equivalent to the logical OR of:

    • VK_PIPELINE_STAGE_DRAW_INDIRECT_BIT

    • VK_PIPELINE_STAGE_TASK_SHADER_BIT_EXT

    • VK_PIPELINE_STAGE_MESH_SHADER_BIT_EXT

    • VK_PIPELINE_STAGE_VERTEX_INPUT_BIT

    • VK_PIPELINE_STAGE_VERTEX_SHADER_BIT

    • VK_PIPELINE_STAGE_TESSELLATION_CONTROL_SHADER_BIT

    • VK_PIPELINE_STAGE_TESSELLATION_EVALUATION_SHADER_BIT

    • VK_PIPELINE_STAGE_GEOMETRY_SHADER_BIT

    • VK_PIPELINE_STAGE_FRAGMENT_SHADER_BIT

    • VK_PIPELINE_STAGE_EARLY_FRAGMENT_TESTS_BIT

    • VK_PIPELINE_STAGE_LATE_FRAGMENT_TESTS_BIT

    • VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT

    • VK_PIPELINE_STAGE_CONDITIONAL_RENDERING_BIT_EXT

    • VK_PIPELINE_STAGE_TRANSFORM_FEEDBACK_BIT_EXT

    • VK_PIPELINE_STAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR

    • VK_PIPELINE_STAGE_FRAGMENT_DENSITY_PROCESS_BIT_EXT

  • VK_PIPELINE_STAGE_ALL_COMMANDS_BIT specifies all operations performed by all commands supported on the queue it is used with.

  • VK_PIPELINE_STAGE_CONDITIONAL_RENDERING_BIT_EXT specifies the stage of the pipeline where the predicate of conditional rendering is consumed.

  • VK_PIPELINE_STAGE_TRANSFORM_FEEDBACK_BIT_EXT specifies the stage of the pipeline where vertex attribute output values are written to the transform feedback buffers.

  • VK_PIPELINE_STAGE_COMMAND_PREPROCESS_BIT_NV specifies the stage of the pipeline where device-side preprocessing for generated commands via vkCmdPreprocessGeneratedCommandsNV is handled.

  • VK_PIPELINE_STAGE_COMMAND_PREPROCESS_BIT_EXT specifies the stage of the pipeline where device-side preprocessing for generated commands via vkCmdPreprocessGeneratedCommandsEXT is handled.

  • VK_PIPELINE_STAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR specifies the stage of the pipeline where the fragment shading rate attachment or shading rate image is read to determine the fragment shading rate for portions of a rasterized primitive.

  • VK_PIPELINE_STAGE_FRAGMENT_DENSITY_PROCESS_BIT_EXT specifies the stage of the pipeline where the fragment density map is read to generate the fragment areas.

  • VK_PIPELINE_STAGE_TOP_OF_PIPE_BIT is equivalent to VK_PIPELINE_STAGE_ALL_COMMANDS_BIT with VkAccessFlags set to 0 when specified in the second synchronization scope, but specifies no stage of execution when specified in the first scope.

  • VK_PIPELINE_STAGE_BOTTOM_OF_PIPE_BIT is equivalent to VK_PIPELINE_STAGE_ALL_COMMANDS_BIT with VkAccessFlags set to 0 when specified in the first synchronization scope, but specifies no stage of execution when specified in the second scope.

// Provided by VK_VERSION_1_0
typedef VkFlags VkPipelineStageFlags;

VkPipelineStageFlags is a bitmask type for setting a mask of zero or more VkPipelineStageFlagBits.

If a synchronization command includes a source stage mask, its first synchronization scope only includes execution of the pipeline stages specified in that mask and any logically earlier stages. Its first access scope only includes memory accesses performed by pipeline stages explicitly specified in the source stage mask.

If a synchronization command includes a destination stage mask, its second synchronization scope only includes execution of the pipeline stages specified in that mask and any logically later stages. Its second access scope only includes memory accesses performed by pipeline stages explicitly specified in the destination stage mask.

Note

Note that access scopes do not interact with the logically earlier or later stages for either scope - only the stages the application specifies are considered part of each access scope.

Certain pipeline stages are only available on queues that support a particular set of operations. The following table lists, for each pipeline stage flag, which queue capability flag must be supported by the queue. When multiple flags are enumerated in the second column of the table, it means that the pipeline stage is supported on the queue if it supports any of the listed capability flags. For further details on queue capabilities see Physical Device Enumeration and Queues.

Table 3. Supported Pipeline Stage Flags
Pipeline stage flag Required queue capability flag

VK_PIPELINE_STAGE_2_NONE

None required

VK_PIPELINE_STAGE_2_TOP_OF_PIPE_BIT

None required

VK_PIPELINE_STAGE_2_DRAW_INDIRECT_BIT

VK_QUEUE_GRAPHICS_BIT or VK_QUEUE_COMPUTE_BIT

VK_PIPELINE_STAGE_2_VERTEX_INPUT_BIT

VK_QUEUE_GRAPHICS_BIT

VK_PIPELINE_STAGE_2_VERTEX_SHADER_BIT

VK_QUEUE_GRAPHICS_BIT

VK_PIPELINE_STAGE_2_TESSELLATION_CONTROL_SHADER_BIT

VK_QUEUE_GRAPHICS_BIT

VK_PIPELINE_STAGE_2_TESSELLATION_EVALUATION_SHADER_BIT

VK_QUEUE_GRAPHICS_BIT

VK_PIPELINE_STAGE_2_GEOMETRY_SHADER_BIT

VK_QUEUE_GRAPHICS_BIT

VK_PIPELINE_STAGE_2_FRAGMENT_SHADER_BIT

VK_QUEUE_GRAPHICS_BIT

VK_PIPELINE_STAGE_2_EARLY_FRAGMENT_TESTS_BIT

VK_QUEUE_GRAPHICS_BIT

VK_PIPELINE_STAGE_2_LATE_FRAGMENT_TESTS_BIT

VK_QUEUE_GRAPHICS_BIT

VK_PIPELINE_STAGE_2_COLOR_ATTACHMENT_OUTPUT_BIT

VK_QUEUE_GRAPHICS_BIT

VK_PIPELINE_STAGE_2_COMPUTE_SHADER_BIT

VK_QUEUE_COMPUTE_BIT

VK_PIPELINE_STAGE_2_ALL_TRANSFER_BIT

VK_QUEUE_GRAPHICS_BIT or VK_QUEUE_COMPUTE_BIT or VK_QUEUE_TRANSFER_BIT

VK_PIPELINE_STAGE_2_BOTTOM_OF_PIPE_BIT

None required

VK_PIPELINE_STAGE_2_HOST_BIT

None required

VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT

VK_QUEUE_GRAPHICS_BIT

VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

None required

VK_PIPELINE_STAGE_2_COPY_BIT

VK_QUEUE_GRAPHICS_BIT or VK_QUEUE_COMPUTE_BIT or VK_QUEUE_TRANSFER_BIT

VK_PIPELINE_STAGE_2_RESOLVE_BIT

VK_QUEUE_GRAPHICS_BIT or VK_QUEUE_COMPUTE_BIT or VK_QUEUE_TRANSFER_BIT

VK_PIPELINE_STAGE_2_BLIT_BIT

VK_QUEUE_GRAPHICS_BIT or VK_QUEUE_COMPUTE_BIT or VK_QUEUE_TRANSFER_BIT

VK_PIPELINE_STAGE_2_CLEAR_BIT

VK_QUEUE_GRAPHICS_BIT or VK_QUEUE_COMPUTE_BIT or VK_QUEUE_TRANSFER_BIT

VK_PIPELINE_STAGE_2_INDEX_INPUT_BIT

VK_QUEUE_GRAPHICS_BIT

VK_PIPELINE_STAGE_2_VERTEX_ATTRIBUTE_INPUT_BIT

VK_QUEUE_GRAPHICS_BIT

VK_PIPELINE_STAGE_2_PRE_RASTERIZATION_SHADERS_BIT

VK_QUEUE_GRAPHICS_BIT

VK_PIPELINE_STAGE_2_VIDEO_DECODE_BIT_KHR

VK_QUEUE_VIDEO_DECODE_BIT_KHR

VK_PIPELINE_STAGE_2_VIDEO_ENCODE_BIT_KHR

VK_QUEUE_VIDEO_ENCODE_BIT_KHR

VK_PIPELINE_STAGE_2_TRANSFORM_FEEDBACK_BIT_EXT

VK_QUEUE_GRAPHICS_BIT

VK_PIPELINE_STAGE_2_CONDITIONAL_RENDERING_BIT_EXT

VK_QUEUE_GRAPHICS_BIT or VK_QUEUE_COMPUTE_BIT

VK_PIPELINE_STAGE_2_COMMAND_PREPROCESS_BIT_NV

VK_QUEUE_GRAPHICS_BIT or VK_QUEUE_COMPUTE_BIT

VK_PIPELINE_STAGE_2_COMMAND_PREPROCESS_BIT_EXT

VK_QUEUE_GRAPHICS_BIT or VK_QUEUE_COMPUTE_BIT

VK_PIPELINE_STAGE_2_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR

VK_QUEUE_GRAPHICS_BIT

VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_BUILD_BIT_KHR

VK_QUEUE_COMPUTE_BIT

VK_PIPELINE_STAGE_2_RAY_TRACING_SHADER_BIT_KHR

VK_QUEUE_COMPUTE_BIT

VK_PIPELINE_STAGE_2_FRAGMENT_DENSITY_PROCESS_BIT_EXT

VK_QUEUE_GRAPHICS_BIT

VK_PIPELINE_STAGE_2_TASK_SHADER_BIT_EXT

VK_QUEUE_GRAPHICS_BIT

VK_PIPELINE_STAGE_2_MESH_SHADER_BIT_EXT

VK_QUEUE_GRAPHICS_BIT

VK_PIPELINE_STAGE_2_SUBPASS_SHADER_BIT_HUAWEI

VK_QUEUE_GRAPHICS_BIT

VK_PIPELINE_STAGE_2_INVOCATION_MASK_BIT_HUAWEI

VK_QUEUE_GRAPHICS_BIT

VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_COPY_BIT_KHR

VK_QUEUE_GRAPHICS_BIT or VK_QUEUE_COMPUTE_BIT or VK_QUEUE_TRANSFER_BIT

VK_PIPELINE_STAGE_2_MICROMAP_BUILD_BIT_EXT

VK_QUEUE_COMPUTE_BIT

VK_PIPELINE_STAGE_2_CLUSTER_CULLING_SHADER_BIT_HUAWEI

VK_QUEUE_GRAPHICS_BIT

VK_PIPELINE_STAGE_2_OPTICAL_FLOW_BIT_NV

VK_QUEUE_OPTICAL_FLOW_BIT_NV

Pipeline stages that execute as a result of a command logically complete execution in a specific order, such that completion of a logically later pipeline stage must not happen-before completion of a logically earlier stage. This means that including any stage in the source stage mask for a particular synchronization command also implies that any logically earlier stages are included in Scope1st for that command.

Similarly, initiation of a logically earlier pipeline stage must not happen-after initiation of a logically later pipeline stage. Including any given stage in the destination stage mask for a particular synchronization command also implies that any logically later stages are included in Scope2nd for that command.

Note

Implementations may not support synchronization at every pipeline stage for every synchronization operation. If a pipeline stage that an implementation does not support synchronization for appears in a source stage mask, it may substitute any logically later stage in its place for the first synchronization scope. If a pipeline stage that an implementation does not support synchronization for appears in a destination stage mask, it may substitute any logically earlier stage in its place for the second synchronization scope.

For example, if an implementation is unable to signal an event immediately after vertex shader execution is complete, it may instead signal the event after color attachment output has completed.

If an implementation makes such a substitution, it must not affect the semantics of execution or memory dependencies or image and buffer memory barriers.

Graphics pipelines are executable on queues supporting VK_QUEUE_GRAPHICS_BIT. Stages executed by graphics pipelines can only be specified in commands recorded for queues supporting VK_QUEUE_GRAPHICS_BIT.

The graphics primitive pipeline executes the following stages, with the logical ordering of the stages matching the order specified here:

  • VK_PIPELINE_STAGE_2_DRAW_INDIRECT_BIT

  • VK_PIPELINE_STAGE_2_INDEX_INPUT_BIT

  • VK_PIPELINE_STAGE_2_VERTEX_ATTRIBUTE_INPUT_BIT

  • VK_PIPELINE_STAGE_2_VERTEX_SHADER_BIT

  • VK_PIPELINE_STAGE_2_TESSELLATION_CONTROL_SHADER_BIT

  • VK_PIPELINE_STAGE_2_TESSELLATION_EVALUATION_SHADER_BIT

  • VK_PIPELINE_STAGE_2_GEOMETRY_SHADER_BIT

  • VK_PIPELINE_STAGE_2_TRANSFORM_FEEDBACK_BIT_EXT

  • VK_PIPELINE_STAGE_2_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR

  • VK_PIPELINE_STAGE_2_EARLY_FRAGMENT_TESTS_BIT

  • VK_PIPELINE_STAGE_2_FRAGMENT_SHADER_BIT

  • VK_PIPELINE_STAGE_2_LATE_FRAGMENT_TESTS_BIT

  • VK_PIPELINE_STAGE_2_COLOR_ATTACHMENT_OUTPUT_BIT

The graphics mesh pipeline executes the following stages, with the logical ordering of the stages matching the order specified here:

  • VK_PIPELINE_STAGE_2_DRAW_INDIRECT_BIT

  • VK_PIPELINE_STAGE_2_TASK_SHADER_BIT_EXT

  • VK_PIPELINE_STAGE_2_MESH_SHADER_BIT_EXT

  • VK_PIPELINE_STAGE_2_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR

  • VK_PIPELINE_STAGE_2_EARLY_FRAGMENT_TESTS_BIT

  • VK_PIPELINE_STAGE_2_FRAGMENT_SHADER_BIT

  • VK_PIPELINE_STAGE_2_LATE_FRAGMENT_TESTS_BIT

  • VK_PIPELINE_STAGE_2_COLOR_ATTACHMENT_OUTPUT_BIT

For the compute pipeline, the following stages occur in this order:

  • VK_PIPELINE_STAGE_2_DRAW_INDIRECT_BIT

  • VK_PIPELINE_STAGE_2_COMPUTE_SHADER_BIT

For the subpass shading pipeline, the following stages occur in this order:

  • VK_PIPELINE_STAGE_2_SUBPASS_SHADER_BIT_HUAWEI

For graphics pipeline commands executing in a render pass with a fragment density map attachment, the following pipeline stage where the fragment density map read happens has no particular order relative to the other stages, except that it is logically earlier than VK_PIPELINE_STAGE_EARLY_FRAGMENT_TESTS_BIT:

  • VK_PIPELINE_STAGE_FRAGMENT_DENSITY_PROCESS_BIT_EXT

  • VK_PIPELINE_STAGE_EARLY_FRAGMENT_TESTS_BIT

The conditional rendering stage is formally part of both the graphics, and the compute pipeline. The pipeline stage where the predicate read happens has unspecified order relative to other stages of these pipelines:

  • VK_PIPELINE_STAGE_CONDITIONAL_RENDERING_BIT_EXT

For the transfer pipeline, the following stages occur in this order:

  • VK_PIPELINE_STAGE_2_TRANSFER_BIT

For host operations, only one pipeline stage occurs, so no order is guaranteed:

  • VK_PIPELINE_STAGE_2_HOST_BIT

For the command preprocessing pipeline, the following stages occur in this order:

  • VK_PIPELINE_STAGE_2_COMMAND_PREPROCESS_BIT_EXT

For acceleration structure build operations, only one pipeline stage occurs, so no order is guaranteed:

  • VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_BUILD_BIT_KHR

For acceleration structure copy operations, only one pipeline stage occurs, so no order is guaranteed:

  • VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_COPY_BIT_KHR

For opacity micromap build operations, only one pipeline stage occurs, so no order is guaranteed:

  • VK_PIPELINE_STAGE_2_MICROMAP_BUILD_BIT_EXT

For the ray tracing pipeline, the following stages occur in this order:

  • VK_PIPELINE_STAGE_2_DRAW_INDIRECT_BIT

  • VK_PIPELINE_STAGE_2_RAY_TRACING_SHADER_BIT_KHR

For the video decode pipeline, the following stages occur in this order:

  • VK_PIPELINE_STAGE_2_VIDEO_DECODE_BIT_KHR

For the video encode pipeline, the following stages occur in this order:

  • VK_PIPELINE_STAGE_2_VIDEO_ENCODE_BIT_KHR

7.1.3. Access Types

Memory in Vulkan can be accessed from within shader invocations and via some fixed-function stages of the pipeline. The access type is a function of the descriptor type used, or how a fixed-function stage accesses memory.

Some synchronization commands take sets of access types as parameters to define the access scopes of a memory dependency. If a synchronization command includes a source access mask, its first access scope only includes accesses via the access types specified in that mask. Similarly, if a synchronization command includes a destination access mask, its second access scope only includes accesses via the access types specified in that mask.

Bits which can be set in the srcAccessMask and dstAccessMask members of VkMemoryBarrier2KHR, VkImageMemoryBarrier2KHR, and VkBufferMemoryBarrier2KHR, specifying access behavior, are:

// Provided by VK_VERSION_1_3
// Flag bits for VkAccessFlagBits2
typedef VkFlags64 VkAccessFlagBits2;
static const VkAccessFlagBits2 VK_ACCESS_2_NONE = 0ULL;
static const VkAccessFlagBits2 VK_ACCESS_2_NONE_KHR = 0ULL;
static const VkAccessFlagBits2 VK_ACCESS_2_INDIRECT_COMMAND_READ_BIT = 0x00000001ULL;
static const VkAccessFlagBits2 VK_ACCESS_2_INDIRECT_COMMAND_READ_BIT_KHR = 0x00000001ULL;
static const VkAccessFlagBits2 VK_ACCESS_2_INDEX_READ_BIT = 0x00000002ULL;
static const VkAccessFlagBits2 VK_ACCESS_2_INDEX_READ_BIT_KHR = 0x00000002ULL;
static const VkAccessFlagBits2 VK_ACCESS_2_VERTEX_ATTRIBUTE_READ_BIT = 0x00000004ULL;
static const VkAccessFlagBits2 VK_ACCESS_2_VERTEX_ATTRIBUTE_READ_BIT_KHR = 0x00000004ULL;
static const VkAccessFlagBits2 VK_ACCESS_2_UNIFORM_READ_BIT = 0x00000008ULL;
static const VkAccessFlagBits2 VK_ACCESS_2_UNIFORM_READ_BIT_KHR = 0x00000008ULL;
static const VkAccessFlagBits2 VK_ACCESS_2_INPUT_ATTACHMENT_READ_BIT = 0x00000010ULL;
static const VkAccessFlagBits2 VK_ACCESS_2_INPUT_ATTACHMENT_READ_BIT_KHR = 0x00000010ULL;
static const VkAccessFlagBits2 VK_ACCESS_2_SHADER_READ_BIT = 0x00000020ULL;
static const VkAccessFlagBits2 VK_ACCESS_2_SHADER_READ_BIT_KHR = 0x00000020ULL;
static const VkAccessFlagBits2 VK_ACCESS_2_SHADER_WRITE_BIT = 0x00000040ULL;
static const VkAccessFlagBits2 VK_ACCESS_2_SHADER_WRITE_BIT_KHR = 0x00000040ULL;
static const VkAccessFlagBits2 VK_ACCESS_2_COLOR_ATTACHMENT_READ_BIT = 0x00000080ULL;
static const VkAccessFlagBits2 VK_ACCESS_2_COLOR_ATTACHMENT_READ_BIT_KHR = 0x00000080ULL;
static const VkAccessFlagBits2 VK_ACCESS_2_COLOR_ATTACHMENT_WRITE_BIT = 0x00000100ULL;
static const VkAccessFlagBits2 VK_ACCESS_2_COLOR_ATTACHMENT_WRITE_BIT_KHR = 0x00000100ULL;
static const VkAccessFlagBits2 VK_ACCESS_2_DEPTH_STENCIL_ATTACHMENT_READ_BIT = 0x00000200ULL;
static const VkAccessFlagBits2 VK_ACCESS_2_DEPTH_STENCIL_ATTACHMENT_READ_BIT_KHR = 0x00000200ULL;
static const VkAccessFlagBits2 VK_ACCESS_2_DEPTH_STENCIL_ATTACHMENT_WRITE_BIT = 0x00000400ULL;
static const VkAccessFlagBits2 VK_ACCESS_2_DEPTH_STENCIL_ATTACHMENT_WRITE_BIT_KHR = 0x00000400ULL;
static const VkAccessFlagBits2 VK_ACCESS_2_TRANSFER_READ_BIT = 0x00000800ULL;
static const VkAccessFlagBits2 VK_ACCESS_2_TRANSFER_READ_BIT_KHR = 0x00000800ULL;
static const VkAccessFlagBits2 VK_ACCESS_2_TRANSFER_WRITE_BIT = 0x00001000ULL;
static const VkAccessFlagBits2 VK_ACCESS_2_TRANSFER_WRITE_BIT_KHR = 0x00001000ULL;
static const VkAccessFlagBits2 VK_ACCESS_2_HOST_READ_BIT = 0x00002000ULL;
static const VkAccessFlagBits2 VK_ACCESS_2_HOST_READ_BIT_KHR = 0x00002000ULL;
static const VkAccessFlagBits2 VK_ACCESS_2_HOST_WRITE_BIT = 0x00004000ULL;
static const VkAccessFlagBits2 VK_ACCESS_2_HOST_WRITE_BIT_KHR = 0x00004000ULL;
static const VkAccessFlagBits2 VK_ACCESS_2_MEMORY_READ_BIT = 0x00008000ULL;
static const VkAccessFlagBits2 VK_ACCESS_2_MEMORY_READ_BIT_KHR = 0x00008000ULL;
static const VkAccessFlagBits2 VK_ACCESS_2_MEMORY_WRITE_BIT = 0x00010000ULL;
static const VkAccessFlagBits2 VK_ACCESS_2_MEMORY_WRITE_BIT_KHR = 0x00010000ULL;
static const VkAccessFlagBits2 VK_ACCESS_2_SHADER_SAMPLED_READ_BIT = 0x100000000ULL;
static const VkAccessFlagBits2 VK_ACCESS_2_SHADER_SAMPLED_READ_BIT_KHR = 0x100000000ULL;
static const VkAccessFlagBits2 VK_ACCESS_2_SHADER_STORAGE_READ_BIT = 0x200000000ULL;
static const VkAccessFlagBits2 VK_ACCESS_2_SHADER_STORAGE_READ_BIT_KHR = 0x200000000ULL;
static const VkAccessFlagBits2 VK_ACCESS_2_SHADER_STORAGE_WRITE_BIT = 0x400000000ULL;
static const VkAccessFlagBits2 VK_ACCESS_2_SHADER_STORAGE_WRITE_BIT_KHR = 0x400000000ULL;
// Provided by VK_KHR_video_decode_queue
static const VkAccessFlagBits2 VK_ACCESS_2_VIDEO_DECODE_READ_BIT_KHR = 0x800000000ULL;
// Provided by VK_KHR_video_decode_queue
static const VkAccessFlagBits2 VK_ACCESS_2_VIDEO_DECODE_WRITE_BIT_KHR = 0x1000000000ULL;
// Provided by VK_KHR_video_encode_queue
static const VkAccessFlagBits2 VK_ACCESS_2_VIDEO_ENCODE_READ_BIT_KHR = 0x2000000000ULL;
// Provided by VK_KHR_video_encode_queue
static const VkAccessFlagBits2 VK_ACCESS_2_VIDEO_ENCODE_WRITE_BIT_KHR = 0x4000000000ULL;
// Provided by VK_KHR_synchronization2 with VK_EXT_transform_feedback
static const VkAccessFlagBits2 VK_ACCESS_2_TRANSFORM_FEEDBACK_WRITE_BIT_EXT = 0x02000000ULL;
// Provided by VK_KHR_synchronization2 with VK_EXT_transform_feedback
static const VkAccessFlagBits2 VK_ACCESS_2_TRANSFORM_FEEDBACK_COUNTER_READ_BIT_EXT = 0x04000000ULL;
// Provided by VK_KHR_synchronization2 with VK_EXT_transform_feedback
static const VkAccessFlagBits2 VK_ACCESS_2_TRANSFORM_FEEDBACK_COUNTER_WRITE_BIT_EXT = 0x08000000ULL;
// Provided by VK_KHR_synchronization2 with VK_EXT_conditional_rendering
static const VkAccessFlagBits2 VK_ACCESS_2_CONDITIONAL_RENDERING_READ_BIT_EXT = 0x00100000ULL;
// Provided by VK_KHR_synchronization2 with VK_NV_device_generated_commands
static const VkAccessFlagBits2 VK_ACCESS_2_COMMAND_PREPROCESS_READ_BIT_NV = 0x00020000ULL;
// Provided by VK_KHR_synchronization2 with VK_NV_device_generated_commands
static const VkAccessFlagBits2 VK_ACCESS_2_COMMAND_PREPROCESS_WRITE_BIT_NV = 0x00040000ULL;
// Provided by VK_KHR_synchronization2 with VK_EXT_device_generated_commands
static const VkAccessFlagBits2 VK_ACCESS_2_COMMAND_PREPROCESS_READ_BIT_EXT = 0x00020000ULL;
// Provided by VK_KHR_synchronization2 with VK_EXT_device_generated_commands
static const VkAccessFlagBits2 VK_ACCESS_2_COMMAND_PREPROCESS_WRITE_BIT_EXT = 0x00040000ULL;
// Provided by VK_KHR_fragment_shading_rate with VK_KHR_synchronization2
static const VkAccessFlagBits2 VK_ACCESS_2_FRAGMENT_SHADING_RATE_ATTACHMENT_READ_BIT_KHR = 0x00800000ULL;
// Provided by VK_KHR_synchronization2 with VK_NV_shading_rate_image
static const VkAccessFlagBits2 VK_ACCESS_2_SHADING_RATE_IMAGE_READ_BIT_NV = 0x00800000ULL;
// Provided by VK_KHR_acceleration_structure with VK_KHR_synchronization2
static const VkAccessFlagBits2 VK_ACCESS_2_ACCELERATION_STRUCTURE_READ_BIT_KHR = 0x00200000ULL;
// Provided by VK_KHR_acceleration_structure with VK_KHR_synchronization2
static const VkAccessFlagBits2 VK_ACCESS_2_ACCELERATION_STRUCTURE_WRITE_BIT_KHR = 0x00400000ULL;
// Provided by VK_KHR_synchronization2 with VK_NV_ray_tracing
static const VkAccessFlagBits2 VK_ACCESS_2_ACCELERATION_STRUCTURE_READ_BIT_NV = 0x00200000ULL;
// Provided by VK_KHR_synchronization2 with VK_NV_ray_tracing
static const VkAccessFlagBits2 VK_ACCESS_2_ACCELERATION_STRUCTURE_WRITE_BIT_NV = 0x00400000ULL;
// Provided by VK_KHR_synchronization2 with VK_EXT_fragment_density_map
static const VkAccessFlagBits2 VK_ACCESS_2_FRAGMENT_DENSITY_MAP_READ_BIT_EXT = 0x01000000ULL;
// Provided by VK_KHR_synchronization2 with VK_EXT_blend_operation_advanced
static const VkAccessFlagBits2 VK_ACCESS_2_COLOR_ATTACHMENT_READ_NONCOHERENT_BIT_EXT = 0x00080000ULL;
// Provided by VK_EXT_descriptor_buffer
static const VkAccessFlagBits2 VK_ACCESS_2_DESCRIPTOR_BUFFER_READ_BIT_EXT = 0x20000000000ULL;
// Provided by VK_HUAWEI_invocation_mask
static const VkAccessFlagBits2 VK_ACCESS_2_INVOCATION_MASK_READ_BIT_HUAWEI = 0x8000000000ULL;
// Provided by VK_KHR_ray_tracing_maintenance1 with (VK_KHR_synchronization2 or VK_VERSION_1_3) and VK_KHR_ray_tracing_pipeline
static const VkAccessFlagBits2 VK_ACCESS_2_SHADER_BINDING_TABLE_READ_BIT_KHR = 0x10000000000ULL;
// Provided by VK_EXT_opacity_micromap
static const VkAccessFlagBits2 VK_ACCESS_2_MICROMAP_READ_BIT_EXT = 0x100000000000ULL;
// Provided by VK_EXT_opacity_micromap
static const VkAccessFlagBits2 VK_ACCESS_2_MICROMAP_WRITE_BIT_EXT = 0x200000000000ULL;
// Provided by VK_NV_optical_flow
static const VkAccessFlagBits2 VK_ACCESS_2_OPTICAL_FLOW_READ_BIT_NV = 0x40000000000ULL;
// Provided by VK_NV_optical_flow
static const VkAccessFlagBits2 VK_ACCESS_2_OPTICAL_FLOW_WRITE_BIT_NV = 0x80000000000ULL;

or the equivalent

// Provided by VK_KHR_synchronization2
typedef VkAccessFlagBits2 VkAccessFlagBits2KHR;

  • VK_ACCESS_2_NONE specifies no accesses.

  • VK_ACCESS_2_MEMORY_READ_BIT specifies all read accesses. It is always valid in any access mask, and is treated as equivalent to setting all READ access flags that are valid where it is used.

  • VK_ACCESS_2_MEMORY_WRITE_BIT specifies all write accesses. It is always valid in any access mask, and is treated as equivalent to setting all WRITE access flags that are valid where it is used.

  • VK_ACCESS_2_INDIRECT_COMMAND_READ_BIT specifies read access to command data read from indirect buffers as part of an indirect build, trace, drawing or dispatch command. Such access occurs in the VK_PIPELINE_STAGE_2_DRAW_INDIRECT_BIT pipeline stage.

  • VK_ACCESS_2_INDEX_READ_BIT specifies read access to an index buffer as part of an indexed drawing command, bound by vkCmdBindIndexBuffer2KHR and vkCmdBindIndexBuffer. Such access occurs in the VK_PIPELINE_STAGE_2_INDEX_INPUT_BIT pipeline stage.

  • VK_ACCESS_2_VERTEX_ATTRIBUTE_READ_BIT specifies read access to a vertex buffer as part of a drawing command, bound by vkCmdBindVertexBuffers. Such access occurs in the VK_PIPELINE_STAGE_2_VERTEX_ATTRIBUTE_INPUT_BIT pipeline stage.

  • VK_ACCESS_2_UNIFORM_READ_BIT specifies read access to a uniform buffer in any shader pipeline stage.

  • VK_ACCESS_2_INPUT_ATTACHMENT_READ_BIT specifies read access to an input attachment within a render pass during subpass shading or fragment shading. Such access occurs in the VK_PIPELINE_STAGE_2_SUBPASS_SHADER_BIT_HUAWEI or VK_PIPELINE_STAGE_2_FRAGMENT_SHADER_BIT pipeline stage.

  • VK_ACCESS_2_SHADER_SAMPLED_READ_BIT specifies read access to a uniform texel buffer or sampled image in any shader pipeline stage.

  • VK_ACCESS_2_SHADER_STORAGE_READ_BIT specifies read access to a storage buffer, physical storage buffer, storage texel buffer, or storage image in any shader pipeline stage.

  • VK_ACCESS_2_SHADER_BINDING_TABLE_READ_BIT_KHR specifies read access to a shader binding table in any shader pipeline stage.

  • VK_ACCESS_2_SHADER_READ_BIT is equivalent to the logical OR of:

    • VK_ACCESS_2_SHADER_SAMPLED_READ_BIT

    • VK_ACCESS_2_SHADER_STORAGE_READ_BIT

  • VK_ACCESS_2_SHADER_STORAGE_WRITE_BIT specifies write access to a storage buffer, physical storage buffer, storage texel buffer, or storage image in any shader pipeline stage.

  • VK_ACCESS_2_SHADER_WRITE_BIT is equivalent to VK_ACCESS_2_SHADER_STORAGE_WRITE_BIT.

  • VK_ACCESS_2_COLOR_ATTACHMENT_READ_BIT specifies read access to a color attachment, such as via blending (other than advanced blend operations), logic operations or certain render pass load operations in the VK_PIPELINE_STAGE_2_COLOR_ATTACHMENT_OUTPUT_BIT pipeline stage or via fragment shader tile image reads in the VK_PIPELINE_STAGE_2_FRAGMENT_SHADER_BIT pipeline stage.

  • VK_ACCESS_2_COLOR_ATTACHMENT_WRITE_BIT specifies write access to a color attachment during a render pass or via certain render pass load, store, and multisample resolve operations. Such access occurs in the VK_PIPELINE_STAGE_2_COLOR_ATTACHMENT_OUTPUT_BIT pipeline stage.

  • VK_ACCESS_2_DEPTH_STENCIL_ATTACHMENT_READ_BIT specifies read access to a depth/stencil attachment, via depth or stencil operations or certain render pass load operations in the VK_PIPELINE_STAGE_2_EARLY_FRAGMENT_TESTS_BIT or VK_PIPELINE_STAGE_2_LATE_FRAGMENT_TESTS_BIT pipeline stages or via fragment shader tile image reads in the VK_PIPELINE_STAGE_2_FRAGMENT_SHADER_BIT pipeline stage.

  • VK_ACCESS_2_DEPTH_STENCIL_ATTACHMENT_WRITE_BIT specifies write access to a depth/stencil attachment, via depth or stencil operations or certain render pass load and store operations. Such access occurs in the VK_PIPELINE_STAGE_2_EARLY_FRAGMENT_TESTS_BIT or VK_PIPELINE_STAGE_2_LATE_FRAGMENT_TESTS_BIT pipeline stages.

  • VK_ACCESS_2_TRANSFER_READ_BIT specifies read access to an image or buffer in a copy operation. Such access occurs in the VK_PIPELINE_STAGE_2_COPY_BIT, VK_PIPELINE_STAGE_2_BLIT_BIT, or VK_PIPELINE_STAGE_2_RESOLVE_BIT pipeline stages.

  • VK_ACCESS_2_TRANSFER_WRITE_BIT specifies write access to an image or buffer in a clear or copy operation. Such access occurs in the VK_PIPELINE_STAGE_2_COPY_BIT, VK_PIPELINE_STAGE_2_BLIT_BIT, VK_PIPELINE_STAGE_2_CLEAR_BIT, or VK_PIPELINE_STAGE_2_RESOLVE_BIT pipeline stages.

  • VK_ACCESS_2_HOST_READ_BIT specifies read access by a host operation. Accesses of this type are not performed through a resource, but directly on memory. Such access occurs in the VK_PIPELINE_STAGE_2_HOST_BIT pipeline stage.

  • VK_ACCESS_2_HOST_WRITE_BIT specifies write access by a host operation. Accesses of this type are not performed through a resource, but directly on memory. Such access occurs in the VK_PIPELINE_STAGE_2_HOST_BIT pipeline stage.

  • VK_ACCESS_2_CONDITIONAL_RENDERING_READ_BIT_EXT specifies read access to a predicate as part of conditional rendering. Such access occurs in the VK_PIPELINE_STAGE_2_CONDITIONAL_RENDERING_BIT_EXT pipeline stage.

  • VK_ACCESS_2_TRANSFORM_FEEDBACK_WRITE_BIT_EXT specifies write access to a transform feedback buffer made when transform feedback is active. Such access occurs in the VK_PIPELINE_STAGE_2_TRANSFORM_FEEDBACK_BIT_EXT pipeline stage.

  • VK_ACCESS_2_TRANSFORM_FEEDBACK_COUNTER_READ_BIT_EXT specifies read access to a transform feedback counter buffer which is read when vkCmdBeginTransformFeedbackEXT executes. Such access occurs in the VK_PIPELINE_STAGE_2_TRANSFORM_FEEDBACK_BIT_EXT pipeline stage.

  • VK_ACCESS_2_TRANSFORM_FEEDBACK_COUNTER_WRITE_BIT_EXT specifies write access to a transform feedback counter buffer which is written when vkCmdEndTransformFeedbackEXT executes. Such access occurs in the VK_PIPELINE_STAGE_2_TRANSFORM_FEEDBACK_BIT_EXT pipeline stage.

  • VK_ACCESS_2_COMMAND_PREPROCESS_READ_BIT_NV specifies reads from buffer inputs to vkCmdPreprocessGeneratedCommandsNV. Such access occurs in the VK_PIPELINE_STAGE_2_COMMAND_PREPROCESS_BIT_NV pipeline stage.

  • VK_ACCESS_2_COMMAND_PREPROCESS_WRITE_BIT_NV specifies writes to the target command buffer preprocess outputs. Such access occurs in the VK_PIPELINE_STAGE_2_COMMAND_PREPROCESS_BIT_NV pipeline stage.

  • VK_ACCESS_2_COMMAND_PREPROCESS_READ_BIT_EXT specifies reads from buffer inputs to vkCmdPreprocessGeneratedCommandsEXT. Such access occurs in the VK_PIPELINE_STAGE_2_COMMAND_PREPROCESS_BIT_EXT pipeline stage.

  • VK_ACCESS_2_COMMAND_PREPROCESS_WRITE_BIT_EXT specifies writes to the target command buffer preprocess outputs. Such access occurs in the VK_PIPELINE_STAGE_2_COMMAND_PREPROCESS_BIT_EXT pipeline stage.

  • VK_ACCESS_2_COLOR_ATTACHMENT_READ_NONCOHERENT_BIT_EXT specifies read access to color attachments, including advanced blend operations. Such access occurs in the VK_PIPELINE_STAGE_2_COLOR_ATTACHMENT_OUTPUT_BIT pipeline stage.

  • VK_ACCESS_2_INVOCATION_MASK_READ_BIT_HUAWEI specifies read access to an invocation mask image in the VK_PIPELINE_STAGE_2_INVOCATION_MASK_BIT_HUAWEI pipeline stage.

  • VK_ACCESS_2_ACCELERATION_STRUCTURE_READ_BIT_KHR specifies read access to an acceleration structure as part of a trace, build, or copy command, or to an acceleration structure scratch buffer as part of a build command. Such access occurs in the VK_PIPELINE_STAGE_2_RAY_TRACING_SHADER_BIT_KHR pipeline stage or VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_BUILD_BIT_KHR pipeline stage.

  • VK_ACCESS_2_ACCELERATION_STRUCTURE_WRITE_BIT_KHR specifies write access to an acceleration structure or acceleration structure scratch buffer as part of a build or copy command. Such access occurs in the VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_BUILD_BIT_KHR pipeline stage.

  • VK_ACCESS_2_FRAGMENT_DENSITY_MAP_READ_BIT_EXT specifies read access to a fragment density map attachment during dynamic fragment density map operations. Such access occurs in the VK_PIPELINE_STAGE_2_FRAGMENT_DENSITY_PROCESS_BIT_EXT pipeline stage.

  • VK_ACCESS_2_FRAGMENT_SHADING_RATE_ATTACHMENT_READ_BIT_KHR specifies read access to a fragment shading rate attachment during rasterization. Such access occurs in the VK_PIPELINE_STAGE_2_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR pipeline stage.

  • VK_ACCESS_2_SHADING_RATE_IMAGE_READ_BIT_NV specifies read access to a shading rate image during rasterization. Such access occurs in the VK_PIPELINE_STAGE_2_SHADING_RATE_IMAGE_BIT_NV pipeline stage. It is equivalent to VK_ACCESS_2_FRAGMENT_SHADING_RATE_ATTACHMENT_READ_BIT_KHR.

  • VK_ACCESS_2_VIDEO_DECODE_READ_BIT_KHR specifies read access to an image or buffer resource in a video decode operation. Such access occurs in the VK_PIPELINE_STAGE_2_VIDEO_DECODE_BIT_KHR pipeline stage.

  • VK_ACCESS_2_VIDEO_DECODE_WRITE_BIT_KHR specifies write access to an image or buffer resource in a video decode operation. Such access occurs in the VK_PIPELINE_STAGE_2_VIDEO_DECODE_BIT_KHR pipeline stage.

  • VK_ACCESS_2_VIDEO_ENCODE_READ_BIT_KHR specifies read access to an image or buffer resource in a video encode operation. Such access occurs in the VK_PIPELINE_STAGE_2_VIDEO_ENCODE_BIT_KHR pipeline stage.

  • VK_ACCESS_2_VIDEO_ENCODE_WRITE_BIT_KHR specifies write access to an image or buffer resource in a video encode operation. Such access occurs in the VK_PIPELINE_STAGE_2_VIDEO_ENCODE_BIT_KHR pipeline stage.

  • VK_ACCESS_2_DESCRIPTOR_BUFFER_READ_BIT_EXT specifies read access to a descriptor buffer in any shader pipeline stage.

  • VK_ACCESS_2_OPTICAL_FLOW_READ_BIT_NV specifies read access to an image or buffer resource as part of a optical flow operation. Such access occurs in the VK_PIPELINE_STAGE_2_OPTICAL_FLOW_BIT_NV pipeline stage.

  • VK_ACCESS_2_OPTICAL_FLOW_WRITE_BIT_NV specifies write access to an image or buffer resource as part of a optical flow operation. Such access occurs in the VK_PIPELINE_STAGE_2_OPTICAL_FLOW_BIT_NV pipeline stage.

  • VK_ACCESS_2_MICROMAP_WRITE_BIT_EXT specifies write access to a micromap object. Such access occurs in the VK_PIPELINE_STAGE_2_MICROMAP_BUILD_BIT_EXT pipeline stage.

  • VK_ACCESS_2_MICROMAP_READ_BIT_EXT specifies read access to a micromap object. Such access occurs in the VK_PIPELINE_STAGE_2_MICROMAP_BUILD_BIT_EXT and VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_BUILD_BIT_KHR pipeline stages.

Note

In situations where an application wishes to select all access types for a given set of pipeline stages, VK_ACCESS_2_MEMORY_READ_BIT or VK_ACCESS_2_MEMORY_WRITE_BIT can be used. This is particularly useful when specifying stages that only have a single access type.
Note

The VkAccessFlags2 bitmask goes beyond the 31 individual bit flags allowable within a C99 enum, which is how VkAccessFlagBits is defined. The first 31 values are common to both, and are interchangeable.

VkAccessFlags2 is a bitmask type for setting a mask of zero or more VkAccessFlagBits2:

// Provided by VK_VERSION_1_3
typedef VkFlags64 VkAccessFlags2;

or the equivalent

// Provided by VK_KHR_synchronization2
typedef VkAccessFlags2 VkAccessFlags2KHR;

Bits which can be set in the srcAccessMask and dstAccessMask members of VkSubpassDependency, VkSubpassDependency2, VkMemoryBarrier, VkBufferMemoryBarrier, and VkImageMemoryBarrier, specifying access behavior, are:

// Provided by VK_VERSION_1_0
typedef enum VkAccessFlagBits {
    VK_ACCESS_INDIRECT_COMMAND_READ_BIT = 0x00000001,
    VK_ACCESS_INDEX_READ_BIT = 0x00000002,
    VK_ACCESS_VERTEX_ATTRIBUTE_READ_BIT = 0x00000004,
    VK_ACCESS_UNIFORM_READ_BIT = 0x00000008,
    VK_ACCESS_INPUT_ATTACHMENT_READ_BIT = 0x00000010,
    VK_ACCESS_SHADER_READ_BIT = 0x00000020,
    VK_ACCESS_SHADER_WRITE_BIT = 0x00000040,
    VK_ACCESS_COLOR_ATTACHMENT_READ_BIT = 0x00000080,
    VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT = 0x00000100,
    VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_READ_BIT = 0x00000200,
    VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_WRITE_BIT = 0x00000400,
    VK_ACCESS_TRANSFER_READ_BIT = 0x00000800,
    VK_ACCESS_TRANSFER_WRITE_BIT = 0x00001000,
    VK_ACCESS_HOST_READ_BIT = 0x00002000,
    VK_ACCESS_HOST_WRITE_BIT = 0x00004000,
    VK_ACCESS_MEMORY_READ_BIT = 0x00008000,
    VK_ACCESS_MEMORY_WRITE_BIT = 0x00010000,
  // Provided by VK_VERSION_1_3
    VK_ACCESS_NONE = 0,
  // Provided by VK_EXT_transform_feedback
    VK_ACCESS_TRANSFORM_FEEDBACK_WRITE_BIT_EXT = 0x02000000,
  // Provided by VK_EXT_transform_feedback
    VK_ACCESS_TRANSFORM_FEEDBACK_COUNTER_READ_BIT_EXT = 0x04000000,
  // Provided by VK_EXT_transform_feedback
    VK_ACCESS_TRANSFORM_FEEDBACK_COUNTER_WRITE_BIT_EXT = 0x08000000,
  // Provided by VK_EXT_conditional_rendering
    VK_ACCESS_CONDITIONAL_RENDERING_READ_BIT_EXT = 0x00100000,
  // Provided by VK_EXT_blend_operation_advanced
    VK_ACCESS_COLOR_ATTACHMENT_READ_NONCOHERENT_BIT_EXT = 0x00080000,
  // Provided by VK_KHR_acceleration_structure
    VK_ACCESS_ACCELERATION_STRUCTURE_READ_BIT_KHR = 0x00200000,
  // Provided by VK_KHR_acceleration_structure
    VK_ACCESS_ACCELERATION_STRUCTURE_WRITE_BIT_KHR = 0x00400000,
  // Provided by VK_EXT_fragment_density_map
    VK_ACCESS_FRAGMENT_DENSITY_MAP_READ_BIT_EXT = 0x01000000,
  // Provided by VK_KHR_fragment_shading_rate
    VK_ACCESS_FRAGMENT_SHADING_RATE_ATTACHMENT_READ_BIT_KHR = 0x00800000,
  // Provided by VK_NV_device_generated_commands
    VK_ACCESS_COMMAND_PREPROCESS_READ_BIT_NV = 0x00020000,
  // Provided by VK_NV_device_generated_commands
    VK_ACCESS_COMMAND_PREPROCESS_WRITE_BIT_NV = 0x00040000,
  // Provided by VK_NV_shading_rate_image
    VK_ACCESS_SHADING_RATE_IMAGE_READ_BIT_NV = VK_ACCESS_FRAGMENT_SHADING_RATE_ATTACHMENT_READ_BIT_KHR,
  // Provided by VK_NV_ray_tracing
    VK_ACCESS_ACCELERATION_STRUCTURE_READ_BIT_NV = VK_ACCESS_ACCELERATION_STRUCTURE_READ_BIT_KHR,
  // Provided by VK_NV_ray_tracing
    VK_ACCESS_ACCELERATION_STRUCTURE_WRITE_BIT_NV = VK_ACCESS_ACCELERATION_STRUCTURE_WRITE_BIT_KHR,
  // Provided by VK_KHR_synchronization2
    VK_ACCESS_NONE_KHR = VK_ACCESS_NONE,
  // Provided by VK_EXT_device_generated_commands
    VK_ACCESS_COMMAND_PREPROCESS_READ_BIT_EXT = VK_ACCESS_COMMAND_PREPROCESS_READ_BIT_NV,
  // Provided by VK_EXT_device_generated_commands
    VK_ACCESS_COMMAND_PREPROCESS_WRITE_BIT_EXT = VK_ACCESS_COMMAND_PREPROCESS_WRITE_BIT_NV,
} VkAccessFlagBits;

These values all have the same meaning as the equivalently named values for VkAccessFlags2.

  • VK_ACCESS_NONE specifies no accesses.

  • VK_ACCESS_MEMORY_READ_BIT specifies all read accesses. It is always valid in any access mask, and is treated as equivalent to setting all READ access flags that are valid where it is used.

  • VK_ACCESS_MEMORY_WRITE_BIT specifies all write accesses. It is always valid in any access mask, and is treated as equivalent to setting all WRITE access flags that are valid where it is used.

  • VK_ACCESS_INDIRECT_COMMAND_READ_BIT specifies read access to indirect command data read as part of an indirect build, trace, drawing or dispatching command. Such access occurs in the VK_PIPELINE_STAGE_DRAW_INDIRECT_BIT pipeline stage.

  • VK_ACCESS_INDEX_READ_BIT specifies read access to an index buffer as part of an indexed drawing command, bound by vkCmdBindIndexBuffer2KHR and vkCmdBindIndexBuffer. Such access occurs in the VK_PIPELINE_STAGE_VERTEX_INPUT_BIT pipeline stage.

  • VK_ACCESS_VERTEX_ATTRIBUTE_READ_BIT specifies read access to a vertex buffer as part of a drawing command, bound by vkCmdBindVertexBuffers. Such access occurs in the VK_PIPELINE_STAGE_VERTEX_INPUT_BIT pipeline stage.

  • VK_ACCESS_UNIFORM_READ_BIT specifies read access to a uniform buffer in any shader pipeline stage.

  • VK_ACCESS_INPUT_ATTACHMENT_READ_BIT specifies read access to an input attachment within a render pass during subpass shading or fragment shading. Such access occurs in the VK_PIPELINE_STAGE_2_SUBPASS_SHADER_BIT_HUAWEI or VK_PIPELINE_STAGE_FRAGMENT_SHADER_BIT pipeline stage.

  • VK_ACCESS_SHADER_READ_BIT specifies read access to a uniform texel buffer, sampled image, storage buffer, physical storage buffer, shader binding table, storage texel buffer, or storage image in any shader pipeline stage.

  • VK_ACCESS_SHADER_WRITE_BIT specifies write access to a storage buffer, physical storage buffer, storage texel buffer, or storage image in any shader pipeline stage.

  • VK_ACCESS_COLOR_ATTACHMENT_READ_BIT specifies read access to a color attachment, such as via blending (other than advanced blend operations), logic operations or certain render pass load operations in the VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT pipeline stage or via fragment shader tile image reads in the VK_PIPELINE_STAGE_FRAGMENT_SHADER_BIT pipeline stage.

  • VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT specifies write access to a color, resolve, or depth/stencil resolve attachment during a render pass or via certain render pass load and store operations. Such access occurs in the VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT pipeline stage.

  • VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_READ_BIT specifies read access to a depth/stencil attachment, via depth or stencil operations or certain render pass load operations in the VK_PIPELINE_STAGE_EARLY_FRAGMENT_TESTS_BIT or VK_PIPELINE_STAGE_LATE_FRAGMENT_TESTS_BIT pipeline stages or via fragment shader tile image reads in the VK_PIPELINE_STAGE_FRAGMENT_SHADER_BIT pipeline stage.

  • VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_WRITE_BIT specifies write access to a depth/stencil attachment, via depth or stencil operations or certain render pass load and store operations. Such access occurs in the VK_PIPELINE_STAGE_EARLY_FRAGMENT_TESTS_BIT or VK_PIPELINE_STAGE_LATE_FRAGMENT_TESTS_BIT pipeline stages.

  • VK_ACCESS_TRANSFER_READ_BIT specifies read access to an image or buffer in a copy operation. Such access occurs in the VK_PIPELINE_STAGE_2_ALL_TRANSFER_BIT pipeline stage.

  • VK_ACCESS_TRANSFER_WRITE_BIT specifies write access to an image or buffer in a clear or copy operation. Such access occurs in the VK_PIPELINE_STAGE_2_ALL_TRANSFER_BIT pipeline stage.

  • VK_ACCESS_HOST_READ_BIT specifies read access by a host operation. Accesses of this type are not performed through a resource, but directly on memory. Such access occurs in the VK_PIPELINE_STAGE_HOST_BIT pipeline stage.

  • VK_ACCESS_HOST_WRITE_BIT specifies write access by a host operation. Accesses of this type are not performed through a resource, but directly on memory. Such access occurs in the VK_PIPELINE_STAGE_HOST_BIT pipeline stage.

  • VK_ACCESS_CONDITIONAL_RENDERING_READ_BIT_EXT specifies read access to a predicate as part of conditional rendering. Such access occurs in the VK_PIPELINE_STAGE_CONDITIONAL_RENDERING_BIT_EXT pipeline stage.

  • VK_ACCESS_TRANSFORM_FEEDBACK_WRITE_BIT_EXT specifies write access to a transform feedback buffer made when transform feedback is active. Such access occurs in the VK_PIPELINE_STAGE_TRANSFORM_FEEDBACK_BIT_EXT pipeline stage.

  • VK_ACCESS_TRANSFORM_FEEDBACK_COUNTER_READ_BIT_EXT specifies read access to a transform feedback counter buffer which is read when vkCmdBeginTransformFeedbackEXT executes. Such access occurs in the VK_PIPELINE_STAGE_TRANSFORM_FEEDBACK_BIT_EXT pipeline stage.

  • VK_ACCESS_TRANSFORM_FEEDBACK_COUNTER_WRITE_BIT_EXT specifies write access to a transform feedback counter buffer which is written when vkCmdEndTransformFeedbackEXT executes. Such access occurs in the VK_PIPELINE_STAGE_TRANSFORM_FEEDBACK_BIT_EXT pipeline stage.

  • VK_ACCESS_COMMAND_PREPROCESS_READ_BIT_NV specifies reads from buffer inputs to vkCmdPreprocessGeneratedCommandsNV. Such access occurs in the VK_PIPELINE_STAGE_COMMAND_PREPROCESS_BIT_NV pipeline stage.

  • VK_ACCESS_COMMAND_PREPROCESS_WRITE_BIT_NV specifies writes to the target command buffer preprocess outputs in vkCmdPreprocessGeneratedCommandsNV. Such access occurs in the VK_PIPELINE_STAGE_COMMAND_PREPROCESS_BIT_NV pipeline stage.

  • VK_ACCESS_COMMAND_PREPROCESS_READ_BIT_EXT specifies reads from buffer inputs to vkCmdPreprocessGeneratedCommandsEXT. Such access occurs in the VK_PIPELINE_STAGE_COMMAND_PREPROCESS_BIT_EXT pipeline stage.

  • VK_ACCESS_COMMAND_PREPROCESS_WRITE_BIT_EXT specifies writes to the target command buffer preprocess outputs in vkCmdPreprocessGeneratedCommandsEXT. Such access occurs in the VK_PIPELINE_STAGE_COMMAND_PREPROCESS_BIT_EXT pipeline stage.

  • VK_ACCESS_COLOR_ATTACHMENT_READ_NONCOHERENT_BIT_EXT specifies read access to color attachments, including advanced blend operations. Such access occurs in the VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT pipeline stage.

  • VK_ACCESS_2_INVOCATION_MASK_READ_BIT_HUAWEI specifies read access to an invocation mask image in the VK_PIPELINE_STAGE_2_INVOCATION_MASK_BIT_HUAWEI pipeline stage.

  • VK_ACCESS_ACCELERATION_STRUCTURE_READ_BIT_KHR specifies read access to an acceleration structure as part of a trace, build, or copy command, or to an acceleration structure scratch buffer as part of a build command. Such access occurs in the VK_PIPELINE_STAGE_RAY_TRACING_SHADER_BIT_KHR pipeline stage or VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR pipeline stage.

  • VK_ACCESS_ACCELERATION_STRUCTURE_WRITE_BIT_KHR specifies write access to an acceleration structure or acceleration structure scratch buffer as part of a build or copy command. Such access occurs in the VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR pipeline stage.

  • VK_ACCESS_FRAGMENT_DENSITY_MAP_READ_BIT_EXT specifies read access to a fragment density map attachment during dynamic fragment density map operations Such access occurs in the VK_PIPELINE_STAGE_FRAGMENT_DENSITY_PROCESS_BIT_EXT pipeline stage.

  • VK_ACCESS_FRAGMENT_SHADING_RATE_ATTACHMENT_READ_BIT_KHR specifies read access to a fragment shading rate attachment during rasterization. Such access occurs in the VK_PIPELINE_STAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR pipeline stage.

  • VK_ACCESS_SHADING_RATE_IMAGE_READ_BIT_NV specifies read access to a shading rate image during rasterization. Such access occurs in the VK_PIPELINE_STAGE_SHADING_RATE_IMAGE_BIT_NV pipeline stage. It is equivalent to VK_PIPELINE_STAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR.

Certain access types are only performed by a subset of pipeline stages. Any synchronization command that takes both stage masks and access masks uses both to define the access scopes - only the specified access types performed by the specified stages are included in the access scope. An application must not specify an access flag in a synchronization command if it does not include a pipeline stage in the corresponding stage mask that is able to perform accesses of that type. The following table lists, for each access flag, which pipeline stages can perform that type of access.

Table 4. Supported Access Types
Access flag Supported pipeline stages

VK_ACCESS_2_NONE

Any

VK_ACCESS_2_INDIRECT_COMMAND_READ_BIT

VK_PIPELINE_STAGE_2_DRAW_INDIRECT_BIT, VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_BUILD_BIT_KHR

VK_ACCESS_2_INDEX_READ_BIT

VK_PIPELINE_STAGE_2_VERTEX_INPUT_BIT, VK_PIPELINE_STAGE_2_INDEX_INPUT_BIT

VK_ACCESS_2_VERTEX_ATTRIBUTE_READ_BIT

VK_PIPELINE_STAGE_2_VERTEX_INPUT_BIT, VK_PIPELINE_STAGE_2_VERTEX_ATTRIBUTE_INPUT_BIT

VK_ACCESS_2_UNIFORM_READ_BIT

VK_PIPELINE_STAGE_2_VERTEX_SHADER_BIT, VK_PIPELINE_STAGE_2_TESSELLATION_CONTROL_SHADER_BIT, VK_PIPELINE_STAGE_2_TESSELLATION_EVALUATION_SHADER_BIT, VK_PIPELINE_STAGE_2_GEOMETRY_SHADER_BIT, VK_PIPELINE_STAGE_2_FRAGMENT_SHADER_BIT, VK_PIPELINE_STAGE_2_COMPUTE_SHADER_BIT, VK_PIPELINE_STAGE_2_RAY_TRACING_SHADER_BIT_KHR, VK_PIPELINE_STAGE_2_TASK_SHADER_BIT_EXT, VK_PIPELINE_STAGE_2_MESH_SHADER_BIT_EXT, VK_PIPELINE_STAGE_2_SUBPASS_SHADER_BIT_HUAWEI, VK_PIPELINE_STAGE_2_CLUSTER_CULLING_SHADER_BIT_HUAWEI

VK_ACCESS_2_INPUT_ATTACHMENT_READ_BIT

VK_PIPELINE_STAGE_2_FRAGMENT_SHADER_BIT, VK_PIPELINE_STAGE_2_SUBPASS_SHADER_BIT_HUAWEI

VK_ACCESS_2_SHADER_READ_BIT

VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_BUILD_BIT_KHR, VK_PIPELINE_STAGE_2_MICROMAP_BUILD_BIT_EXT, VK_PIPELINE_STAGE_2_VERTEX_SHADER_BIT, VK_PIPELINE_STAGE_2_TESSELLATION_CONTROL_SHADER_BIT, VK_PIPELINE_STAGE_2_TESSELLATION_EVALUATION_SHADER_BIT, VK_PIPELINE_STAGE_2_GEOMETRY_SHADER_BIT, VK_PIPELINE_STAGE_2_FRAGMENT_SHADER_BIT, VK_PIPELINE_STAGE_2_COMPUTE_SHADER_BIT, VK_PIPELINE_STAGE_2_RAY_TRACING_SHADER_BIT_KHR, VK_PIPELINE_STAGE_2_TASK_SHADER_BIT_EXT, VK_PIPELINE_STAGE_2_MESH_SHADER_BIT_EXT, VK_PIPELINE_STAGE_2_SUBPASS_SHADER_BIT_HUAWEI, VK_PIPELINE_STAGE_2_CLUSTER_CULLING_SHADER_BIT_HUAWEI

VK_ACCESS_2_SHADER_WRITE_BIT

VK_PIPELINE_STAGE_2_VERTEX_SHADER_BIT, VK_PIPELINE_STAGE_2_TESSELLATION_CONTROL_SHADER_BIT, VK_PIPELINE_STAGE_2_TESSELLATION_EVALUATION_SHADER_BIT, VK_PIPELINE_STAGE_2_GEOMETRY_SHADER_BIT, VK_PIPELINE_STAGE_2_FRAGMENT_SHADER_BIT, VK_PIPELINE_STAGE_2_COMPUTE_SHADER_BIT, VK_PIPELINE_STAGE_2_RAY_TRACING_SHADER_BIT_KHR, VK_PIPELINE_STAGE_2_TASK_SHADER_BIT_EXT, VK_PIPELINE_STAGE_2_MESH_SHADER_BIT_EXT, VK_PIPELINE_STAGE_2_SUBPASS_SHADER_BIT_HUAWEI, VK_PIPELINE_STAGE_2_CLUSTER_CULLING_SHADER_BIT_HUAWEI

VK_ACCESS_2_COLOR_ATTACHMENT_READ_BIT

VK_PIPELINE_STAGE_2_FRAGMENT_SHADER_BIT, VK_PIPELINE_STAGE_2_COLOR_ATTACHMENT_OUTPUT_BIT

VK_ACCESS_2_COLOR_ATTACHMENT_WRITE_BIT

VK_PIPELINE_STAGE_2_COLOR_ATTACHMENT_OUTPUT_BIT

VK_ACCESS_2_DEPTH_STENCIL_ATTACHMENT_READ_BIT

VK_PIPELINE_STAGE_2_FRAGMENT_SHADER_BIT, VK_PIPELINE_STAGE_2_EARLY_FRAGMENT_TESTS_BIT, VK_PIPELINE_STAGE_2_LATE_FRAGMENT_TESTS_BIT

VK_ACCESS_2_DEPTH_STENCIL_ATTACHMENT_WRITE_BIT

VK_PIPELINE_STAGE_2_EARLY_FRAGMENT_TESTS_BIT, VK_PIPELINE_STAGE_2_LATE_FRAGMENT_TESTS_BIT

VK_ACCESS_2_TRANSFER_READ_BIT

VK_PIPELINE_STAGE_2_ALL_TRANSFER_BIT, VK_PIPELINE_STAGE_2_COPY_BIT, VK_PIPELINE_STAGE_2_RESOLVE_BIT, VK_PIPELINE_STAGE_2_BLIT_BIT, VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_BUILD_BIT_KHR, VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_COPY_BIT_KHR, VK_PIPELINE_STAGE_2_MICROMAP_BUILD_BIT_EXT

VK_ACCESS_2_TRANSFER_WRITE_BIT

VK_PIPELINE_STAGE_2_ALL_TRANSFER_BIT, VK_PIPELINE_STAGE_2_COPY_BIT, VK_PIPELINE_STAGE_2_RESOLVE_BIT, VK_PIPELINE_STAGE_2_BLIT_BIT, VK_PIPELINE_STAGE_2_CLEAR_BIT, VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_BUILD_BIT_KHR, VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_COPY_BIT_KHR, VK_PIPELINE_STAGE_2_MICROMAP_BUILD_BIT_EXT

VK_ACCESS_2_HOST_READ_BIT

VK_PIPELINE_STAGE_2_HOST_BIT

VK_ACCESS_2_HOST_WRITE_BIT

VK_PIPELINE_STAGE_2_HOST_BIT

VK_ACCESS_2_MEMORY_READ_BIT

Any

VK_ACCESS_2_MEMORY_WRITE_BIT

Any

VK_ACCESS_2_SHADER_SAMPLED_READ_BIT

VK_PIPELINE_STAGE_2_VERTEX_SHADER_BIT, VK_PIPELINE_STAGE_2_TESSELLATION_CONTROL_SHADER_BIT, VK_PIPELINE_STAGE_2_TESSELLATION_EVALUATION_SHADER_BIT, VK_PIPELINE_STAGE_2_GEOMETRY_SHADER_BIT, VK_PIPELINE_STAGE_2_FRAGMENT_SHADER_BIT, VK_PIPELINE_STAGE_2_COMPUTE_SHADER_BIT, VK_PIPELINE_STAGE_2_RAY_TRACING_SHADER_BIT_KHR, VK_PIPELINE_STAGE_2_TASK_SHADER_BIT_EXT, VK_PIPELINE_STAGE_2_MESH_SHADER_BIT_EXT, VK_PIPELINE_STAGE_2_SUBPASS_SHADER_BIT_HUAWEI, VK_PIPELINE_STAGE_2_CLUSTER_CULLING_SHADER_BIT_HUAWEI

VK_ACCESS_2_SHADER_STORAGE_READ_BIT

VK_PIPELINE_STAGE_2_VERTEX_SHADER_BIT, VK_PIPELINE_STAGE_2_TESSELLATION_CONTROL_SHADER_BIT, VK_PIPELINE_STAGE_2_TESSELLATION_EVALUATION_SHADER_BIT, VK_PIPELINE_STAGE_2_GEOMETRY_SHADER_BIT, VK_PIPELINE_STAGE_2_FRAGMENT_SHADER_BIT, VK_PIPELINE_STAGE_2_COMPUTE_SHADER_BIT, VK_PIPELINE_STAGE_2_RAY_TRACING_SHADER_BIT_KHR, VK_PIPELINE_STAGE_2_TASK_SHADER_BIT_EXT, VK_PIPELINE_STAGE_2_MESH_SHADER_BIT_EXT, VK_PIPELINE_STAGE_2_SUBPASS_SHADER_BIT_HUAWEI, VK_PIPELINE_STAGE_2_CLUSTER_CULLING_SHADER_BIT_HUAWEI

VK_ACCESS_2_SHADER_STORAGE_WRITE_BIT

VK_PIPELINE_STAGE_2_VERTEX_SHADER_BIT, VK_PIPELINE_STAGE_2_TESSELLATION_CONTROL_SHADER_BIT, VK_PIPELINE_STAGE_2_TESSELLATION_EVALUATION_SHADER_BIT, VK_PIPELINE_STAGE_2_GEOMETRY_SHADER_BIT, VK_PIPELINE_STAGE_2_FRAGMENT_SHADER_BIT, VK_PIPELINE_STAGE_2_COMPUTE_SHADER_BIT, VK_PIPELINE_STAGE_2_RAY_TRACING_SHADER_BIT_KHR, VK_PIPELINE_STAGE_2_TASK_SHADER_BIT_EXT, VK_PIPELINE_STAGE_2_MESH_SHADER_BIT_EXT, VK_PIPELINE_STAGE_2_SUBPASS_SHADER_BIT_HUAWEI, VK_PIPELINE_STAGE_2_CLUSTER_CULLING_SHADER_BIT_HUAWEI

VK_ACCESS_2_VIDEO_DECODE_READ_BIT_KHR

VK_PIPELINE_STAGE_2_VIDEO_DECODE_BIT_KHR

VK_ACCESS_2_VIDEO_DECODE_WRITE_BIT_KHR

VK_PIPELINE_STAGE_2_VIDEO_DECODE_BIT_KHR

VK_ACCESS_2_VIDEO_ENCODE_READ_BIT_KHR

VK_PIPELINE_STAGE_2_VIDEO_ENCODE_BIT_KHR

VK_ACCESS_2_VIDEO_ENCODE_WRITE_BIT_KHR

VK_PIPELINE_STAGE_2_VIDEO_ENCODE_BIT_KHR

VK_ACCESS_2_TRANSFORM_FEEDBACK_WRITE_BIT_EXT

VK_PIPELINE_STAGE_2_TRANSFORM_FEEDBACK_BIT_EXT

VK_ACCESS_2_TRANSFORM_FEEDBACK_COUNTER_READ_BIT_EXT

VK_PIPELINE_STAGE_2_DRAW_INDIRECT_BIT, VK_PIPELINE_STAGE_2_TRANSFORM_FEEDBACK_BIT_EXT

VK_ACCESS_2_TRANSFORM_FEEDBACK_COUNTER_WRITE_BIT_EXT

VK_PIPELINE_STAGE_2_TRANSFORM_FEEDBACK_BIT_EXT

VK_ACCESS_2_CONDITIONAL_RENDERING_READ_BIT_EXT

VK_PIPELINE_STAGE_2_CONDITIONAL_RENDERING_BIT_EXT

VK_ACCESS_2_COMMAND_PREPROCESS_READ_BIT_NV

VK_PIPELINE_STAGE_2_COMMAND_PREPROCESS_BIT_NV

VK_ACCESS_2_COMMAND_PREPROCESS_WRITE_BIT_NV

VK_PIPELINE_STAGE_2_COMMAND_PREPROCESS_BIT_NV

VK_ACCESS_2_COMMAND_PREPROCESS_READ_BIT_EXT

VK_PIPELINE_STAGE_2_COMMAND_PREPROCESS_BIT_EXT

VK_ACCESS_2_COMMAND_PREPROCESS_WRITE_BIT_EXT

VK_PIPELINE_STAGE_2_COMMAND_PREPROCESS_BIT_EXT

VK_ACCESS_2_FRAGMENT_SHADING_RATE_ATTACHMENT_READ_BIT_KHR

VK_PIPELINE_STAGE_2_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR

VK_ACCESS_2_ACCELERATION_STRUCTURE_READ_BIT_KHR

VK_PIPELINE_STAGE_2_VERTEX_SHADER_BIT, VK_PIPELINE_STAGE_2_TESSELLATION_CONTROL_SHADER_BIT, VK_PIPELINE_STAGE_2_TESSELLATION_EVALUATION_SHADER_BIT, VK_PIPELINE_STAGE_2_GEOMETRY_SHADER_BIT, VK_PIPELINE_STAGE_2_FRAGMENT_SHADER_BIT, VK_PIPELINE_STAGE_2_COMPUTE_SHADER_BIT, VK_PIPELINE_STAGE_2_RAY_TRACING_SHADER_BIT_KHR, VK_PIPELINE_STAGE_2_TASK_SHADER_BIT_EXT, VK_PIPELINE_STAGE_2_MESH_SHADER_BIT_EXT, VK_PIPELINE_STAGE_2_CLUSTER_CULLING_SHADER_BIT_HUAWEI, VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_BUILD_BIT_KHR, VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_COPY_BIT_KHR, VK_PIPELINE_STAGE_2_SUBPASS_SHADER_BIT_HUAWEI

VK_ACCESS_2_ACCELERATION_STRUCTURE_WRITE_BIT_KHR

VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_BUILD_BIT_KHR, VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_COPY_BIT_KHR

VK_ACCESS_2_FRAGMENT_DENSITY_MAP_READ_BIT_EXT

VK_PIPELINE_STAGE_2_FRAGMENT_DENSITY_PROCESS_BIT_EXT

VK_ACCESS_2_COLOR_ATTACHMENT_READ_NONCOHERENT_BIT_EXT

VK_PIPELINE_STAGE_2_COLOR_ATTACHMENT_OUTPUT_BIT

VK_ACCESS_2_DESCRIPTOR_BUFFER_READ_BIT_EXT

VK_PIPELINE_STAGE_2_VERTEX_SHADER_BIT, VK_PIPELINE_STAGE_2_TESSELLATION_CONTROL_SHADER_BIT, VK_PIPELINE_STAGE_2_TESSELLATION_EVALUATION_SHADER_BIT, VK_PIPELINE_STAGE_2_GEOMETRY_SHADER_BIT, VK_PIPELINE_STAGE_2_FRAGMENT_SHADER_BIT, VK_PIPELINE_STAGE_2_COMPUTE_SHADER_BIT, VK_PIPELINE_STAGE_2_RAY_TRACING_SHADER_BIT_KHR, VK_PIPELINE_STAGE_2_TASK_SHADER_BIT_EXT, VK_PIPELINE_STAGE_2_MESH_SHADER_BIT_EXT, VK_PIPELINE_STAGE_2_SUBPASS_SHADER_BIT_HUAWEI, VK_PIPELINE_STAGE_2_CLUSTER_CULLING_SHADER_BIT_HUAWEI

VK_ACCESS_2_INVOCATION_MASK_READ_BIT_HUAWEI

VK_PIPELINE_STAGE_2_INVOCATION_MASK_BIT_HUAWEI

VK_ACCESS_2_MICROMAP_READ_BIT_EXT

VK_PIPELINE_STAGE_2_MICROMAP_BUILD_BIT_EXT, VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_BUILD_BIT_KHR

VK_ACCESS_2_MICROMAP_WRITE_BIT_EXT

VK_PIPELINE_STAGE_2_MICROMAP_BUILD_BIT_EXT

VK_ACCESS_2_OPTICAL_FLOW_READ_BIT_NV

VK_PIPELINE_STAGE_2_OPTICAL_FLOW_BIT_NV

VK_ACCESS_2_OPTICAL_FLOW_WRITE_BIT_NV

VK_PIPELINE_STAGE_2_OPTICAL_FLOW_BIT_NV

 
// Provided by VK_VERSION_1_0
typedef VkFlags VkAccessFlags;

VkAccessFlags is a bitmask type for setting a mask of zero or more VkAccessFlagBits.

If a memory object does not have the VK_MEMORY_PROPERTY_HOST_COHERENT_BIT property, then vkFlushMappedMemoryRanges must be called in order to guarantee that writes to the memory object from the host are made available to the host domain, where they can be further made available to the device domain via a domain operation. Similarly, vkInvalidateMappedMemoryRanges must be called to guarantee that writes which are available to the host domain are made visible to host operations.

If the memory object does have the VK_MEMORY_PROPERTY_HOST_COHERENT_BIT property flag, writes to the memory object from the host are automatically made available to the host domain. Similarly, writes made available to the host domain are automatically made visible to the host.

Note

Queue submission commands automatically perform a domain operation from host to device for all writes performed before the command executes, so in most cases an explicit memory barrier is not needed for this case. In the few circumstances where a submit does not occur between the host write and the device read access, writes can be made available by using an explicit memory barrier.

7.1.4. Framebuffer Region Dependencies

Pipeline stages that operate on, or with respect to, the framebuffer are collectively the framebuffer-space pipeline stages. These stages are:

  • VK_PIPELINE_STAGE_FRAGMENT_SHADER_BIT

  • VK_PIPELINE_STAGE_EARLY_FRAGMENT_TESTS_BIT

  • VK_PIPELINE_STAGE_LATE_FRAGMENT_TESTS_BIT

  • VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT

For these pipeline stages, an execution or memory dependency from the first set of operations to the second set can either be a single framebuffer-global dependency, or split into multiple framebuffer-local dependencies. A dependency with non-framebuffer-space pipeline stages is neither framebuffer-global nor framebuffer-local.

A framebuffer region is a subset of the entire framebuffer, and can either be:

  • A sample region, which is set of sample (x, y, layer, sample) coordinates that is a subset of the entire framebuffer, or

  • A fragment region, which is a set of fragment (x, y, layer) coordinates that is a subset of the entire framebuffer.

Both synchronization scopes of a framebuffer-local dependency include only the operations performed within corresponding framebuffer regions (as defined below). No ordering guarantees are made between different framebuffer regions for a framebuffer-local dependency.

Both synchronization scopes of a framebuffer-global dependency include operations on all framebuffer-regions.

If the first synchronization scope includes operations on pixels/fragments with N samples and the second synchronization scope includes operations on pixels/fragments with M samples, where N does not equal M, then a framebuffer region containing all samples at a given (x, y, layer) coordinate in the first synchronization scope corresponds to a region containing all samples at the same coordinate in the second synchronization scope. In other words, the framebuffer region is a fragment region and it is a pixel granularity dependency. If N equals M, and if the VkSubpassDescription::flags does not specify the VK_SUBPASS_DESCRIPTION_FRAGMENT_REGION_BIT_QCOM flag, then a framebuffer region containing a single (x, y, layer, sample) coordinate in the first synchronization scope corresponds to a region containing the same sample at the same coordinate in the second synchronization scope. In other words, the framebuffer region is a sample region and it is a sample granularity dependency.

If the pipeline performing the operation was created with VK_PIPELINE_COLOR_BLEND_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_ACCESS_BIT_EXT, VK_PIPELINE_DEPTH_STENCIL_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_DEPTH_ACCESS_BIT_EXT, or VK_PIPELINE_DEPTH_STENCIL_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_STENCIL_ACCESS_BIT_EXT, the framebuffer region is a fragment region and it is a pixel granularity dependency.

Note

Since fragment shader invocations are not specified to run in any particular groupings, the size of a framebuffer region is implementation-dependent, not known to the application, and must be assumed to be no larger than specified above.
Note

Practically, the pixel vs. sample granularity dependency means that if an input attachment has a different number of samples than the pipeline’s rasterizationSamples, then a fragment can access any sample in the input attachment’s pixel even if it only uses framebuffer-local dependencies. If the input attachment has the same number of samples, then the fragment can only access the covered samples in its input SampleMask (i.e. the fragment operations happen-after a framebuffer-local dependency for each sample the fragment covers). To access samples that are not covered, either the VkSubpassDescription::flags VK_SUBPASS_DESCRIPTION_FRAGMENT_REGION_BIT_QCOM flag is required, or a framebuffer-global dependency is required.

If a synchronization command includes a dependencyFlags parameter, and specifies the VK_DEPENDENCY_BY_REGION_BIT flag, then it defines framebuffer-local dependencies for the framebuffer-space pipeline stages in that synchronization command, for all framebuffer regions. If no dependencyFlags parameter is included, or the VK_DEPENDENCY_BY_REGION_BIT flag is not specified, then a framebuffer-global dependency is specified for those stages. The VK_DEPENDENCY_BY_REGION_BIT flag does not affect the dependencies between non-framebuffer-space pipeline stages, nor does it affect the dependencies between framebuffer-space and non-framebuffer-space pipeline stages.

Note

Framebuffer-local dependencies are more efficient for most architectures; particularly tile-based architectures - which can keep framebuffer-regions entirely in on-chip registers and thus avoid external bandwidth across such a dependency. Including a framebuffer-global dependency in your rendering will usually force all implementations to flush data to memory, or to a higher level cache, breaking any potential locality optimizations.

7.1.5. View-Local Dependencies

In a render pass instance that has multiview enabled, dependencies can be either view-local or view-global.

A view-local dependency only includes operations from a single source view from the source subpass in the first synchronization scope, and only includes operations from a single destination view from the destination subpass in the second synchronization scope. A view-global dependency includes all views in the view mask of the source and destination subpasses in the corresponding synchronization scopes.

If a synchronization command includes a dependencyFlags parameter and specifies the VK_DEPENDENCY_VIEW_LOCAL_BIT flag, then it defines view-local dependencies for that synchronization command, for all views. If no dependencyFlags parameter is included or the VK_DEPENDENCY_VIEW_LOCAL_BIT flag is not specified, then a view-global dependency is specified.

7.1.6. Device-Local Dependencies

Dependencies can be either device-local or non-device-local. A device-local dependency acts as multiple separate dependencies, one for each physical device that executes the synchronization command, where each dependency only includes operations from that physical device in both synchronization scopes. A non-device-local dependency is a single dependency where both synchronization scopes include operations from all physical devices that participate in the synchronization command. For subpass dependencies, all physical devices in the VkDeviceGroupRenderPassBeginInfo::deviceMask participate in the dependency, and for pipeline barriers all physical devices that are set in the command buffer’s current device mask participate in the dependency.

If a synchronization command includes a dependencyFlags parameter and specifies the VK_DEPENDENCY_DEVICE_GROUP_BIT flag, then it defines a non-device-local dependency for that synchronization command. If no dependencyFlags parameter is included or the VK_DEPENDENCY_DEVICE_GROUP_BIT flag is not specified, then it defines device-local dependencies for that synchronization command, for all participating physical devices.

Semaphore and event dependencies are device-local and only execute on the one physical device that performs the dependency.

7.2. Implicit Synchronization Guarantees

A small number of implicit ordering guarantees are provided by Vulkan, ensuring that the order in which commands are submitted is meaningful, and avoiding unnecessary complexity in common operations.

Submission order is a fundamental ordering in Vulkan, giving meaning to the order in which action and synchronization commands are recorded and submitted to a single queue. Explicit and implicit ordering guarantees between commands in Vulkan all work on the premise that this ordering is meaningful. This order does not itself define any execution or memory dependencies; synchronization commands and other orderings within the API use this ordering to define their scopes.

Submission order for any given set of commands is based on the order in which they were recorded to command buffers and then submitted. This order is determined as follows:

  1. The initial order is determined by the order in which vkQueueSubmit and vkQueueSubmit2 commands are executed on the host, for a single queue, from first to last.

  2. The order in which VkSubmitInfo structures are specified in the pSubmits parameter of vkQueueSubmit, or in which VkSubmitInfo2 structures are specified in the pSubmits parameter of vkQueueSubmit2, from lowest index to highest.

  3. The order in which command buffers are specified in the pCommandBuffers member of VkSubmitInfo or VkSubmitInfo2 from lowest index to highest.

  4. The order in which commands outside of a render pass were recorded to a command buffer on the host, from first to last.

  5. The order in which commands inside a single subpass were recorded to a command buffer on the host, from first to last.

Note

When using a render pass object with multiple subpasses, commands in different subpasses have no defined submission order relative to each other, regardless of the order in which the subpasses were recorded. Commands within a subpass are still ordered relative to other commands in the same subpass, and those outside of the render pass.

State commands do not execute any operations on the device, instead they set the state of the command buffer when they execute on the host, in the order that they are recorded. Action commands consume the current state of the command buffer when they are recorded, and will execute state changes on the device as required to match the recorded state.

The order of primitives passing through the graphics pipeline and image layout transitions as part of an image memory barrier provide additional guarantees based on submission order.

Execution of pipeline stages within a given command also has a loose ordering, dependent only on a single command.

Signal operation order is a fundamental ordering in Vulkan, giving meaning to the order in which semaphore and fence signal operations occur when submitted to a single queue. The signal operation order for queue operations is determined as follows:

  1. The initial order is determined by the order in which vkQueueSubmit and vkQueueSubmit2 commands are executed on the host, for a single queue, from first to last.

  2. The order in which VkSubmitInfo structures are specified in the pSubmits parameter of vkQueueSubmit, or in which VkSubmitInfo2 structures are specified in the pSubmits parameter of vkQueueSubmit2, from lowest index to highest.

  3. The fence signal operation defined by the fence parameter of a vkQueueSubmit or vkQueueSubmit2 or vkQueueBindSparse command is ordered after all semaphore signal operations defined by that command.

Semaphore signal operations defined by a single VkSubmitInfo or VkSubmitInfo2 or VkBindSparseInfo structure are unordered with respect to other semaphore signal operations defined within the same structure.

The vkSignalSemaphore command does not execute on a queue but instead performs the signal operation from the host. The semaphore signal operation defined by executing a vkSignalSemaphore command happens-after the vkSignalSemaphore command is invoked and happens-before the command returns.

Note

When signaling timeline semaphores, it is the responsibility of the application to ensure that they are ordered such that the semaphore value is strictly increasing. Because the first synchronization scope for a semaphore signal operation contains all semaphore signal operations which occur earlier in submission order, all semaphore signal operations contained in any given batch are guaranteed to happen-after all semaphore signal operations contained in any previous batches. However, no ordering guarantee is provided between the semaphore signal operations defined within a single batch. This, combined with the requirement that timeline semaphore values strictly increase, means that it is invalid to signal the same timeline semaphore twice within a single batch.

If an application wishes to ensure that some semaphore signal operation happens-after some other semaphore signal operation, it can submit a separate batch containing only semaphore signal operations, which will happen-after the semaphore signal operations in any earlier batches.

When signaling a semaphore from the host, the only ordering guarantee is that the signal operation happens-after when vkSignalSemaphore is called and happens-before it returns. Therefore, it is invalid to call vkSignalSemaphore while there are any outstanding signal operations on that semaphore from any queue submissions unless those queue submissions have some dependency which ensures that they happen-after the host signal operation. One example of this would be if the pending signal operation is, itself, waiting on the same semaphore at a lower value and the call to vkSignalSemaphore signals that lower value. Furthermore, if there are two or more processes or threads signaling the same timeline semaphore from the host, the application must ensure that the vkSignalSemaphore with the lower semaphore value returns before vkSignalSemaphore is called with the higher value.

7.3. Fences

Fences are a synchronization primitive that can be used to insert a dependency from a queue to the host. Fences have two states - signaled and unsignaled. A fence can be signaled as part of the execution of a queue submission command. Fences can be unsignaled on the host with vkResetFences. Fences can be waited on by the host with the vkWaitForFences command, and the current state can be queried with vkGetFenceStatus.

The internal data of a fence may include a reference to any resources and pending work associated with signal or unsignal operations performed on that fence object, collectively referred to as the fence’s payload. Mechanisms to import and export that internal data to and from fences are provided below. These mechanisms indirectly enable applications to share fence state between two or more fences and other synchronization primitives across process and API boundaries.

Fences are represented by VkFence handles:

// Provided by VK_VERSION_1_0
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkFence)

To create a fence, call:

// Provided by VK_VERSION_1_0
VkResult vkCreateFence(
    VkDevice                                    device,
    const VkFenceCreateInfo*                    pCreateInfo,
    const VkAllocationCallbacks*                pAllocator,
    VkFence*                                    pFence);

  • device is the logical device that creates the fence.

  • pCreateInfo is a pointer to a VkFenceCreateInfo structure containing information about how the fence is to be created.

  • pAllocator controls host memory allocation as described in the Memory Allocation chapter.

  • pFence is a pointer to a handle in which the resulting fence object is returned.

Valid Usage (Implicit)

  • VUID-vkCreateFence-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkCreateFence-pCreateInfo-parameter
    pCreateInfo must be a valid pointer to a valid VkFenceCreateInfo structure

  • VUID-vkCreateFence-pAllocator-parameter
    If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure

  • VUID-vkCreateFence-pFence-parameter
    pFence must be a valid pointer to a VkFence handle

Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

The VkFenceCreateInfo structure is defined as:

// Provided by VK_VERSION_1_0
typedef struct VkFenceCreateInfo {
    VkStructureType       sType;
    const void*           pNext;
    VkFenceCreateFlags    flags;
} VkFenceCreateInfo;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • flags is a bitmask of VkFenceCreateFlagBits specifying the initial state and behavior of the fence.

Valid Usage (Implicit)

  • VUID-VkFenceCreateInfo-sType-sType
    sType must be VK_STRUCTURE_TYPE_FENCE_CREATE_INFO

  • VUID-VkFenceCreateInfo-pNext-pNext
    Each pNext member of any structure (including this one) in the pNext chain must be either NULL or a pointer to a valid instance of VkExportFenceCreateInfo or VkExportFenceWin32HandleInfoKHR

  • VUID-VkFenceCreateInfo-sType-unique
    The sType value of each struct in the pNext chain must be unique

  • VUID-VkFenceCreateInfo-flags-parameter
    flags must be a valid combination of VkFenceCreateFlagBits values

// Provided by VK_VERSION_1_0
typedef enum VkFenceCreateFlagBits {
    VK_FENCE_CREATE_SIGNALED_BIT = 0x00000001,
} VkFenceCreateFlagBits;

  • VK_FENCE_CREATE_SIGNALED_BIT specifies that the fence object is created in the signaled state. Otherwise, it is created in the unsignaled state.

// Provided by VK_VERSION_1_0
typedef VkFlags VkFenceCreateFlags;

VkFenceCreateFlags is a bitmask type for setting a mask of zero or more VkFenceCreateFlagBits.

To create a fence whose payload can be exported to external handles, add a VkExportFenceCreateInfo structure to the pNext chain of the VkFenceCreateInfo structure. The VkExportFenceCreateInfo structure is defined as:

// Provided by VK_VERSION_1_1
typedef struct VkExportFenceCreateInfo {
    VkStructureType                   sType;
    const void*                       pNext;
    VkExternalFenceHandleTypeFlags    handleTypes;
} VkExportFenceCreateInfo;

or the equivalent

// Provided by VK_KHR_external_fence
typedef VkExportFenceCreateInfo VkExportFenceCreateInfoKHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • handleTypes is a bitmask of VkExternalFenceHandleTypeFlagBits specifying one or more fence handle types the application can export from the resulting fence. The application can request multiple handle types for the same fence.

Valid Usage

  • VUID-VkExportFenceCreateInfo-handleTypes-01446
    The bits in handleTypes must be supported and compatible, as reported by VkExternalFenceProperties

Valid Usage (Implicit)

  • VUID-VkExportFenceCreateInfo-sType-sType
    sType must be VK_STRUCTURE_TYPE_EXPORT_FENCE_CREATE_INFO

  • VUID-VkExportFenceCreateInfo-handleTypes-parameter
    handleTypes must be a valid combination of VkExternalFenceHandleTypeFlagBits values

To specify additional attributes of NT handles exported from a fence, add a VkExportFenceWin32HandleInfoKHR structure to the pNext chain of the VkFenceCreateInfo structure. The VkExportFenceWin32HandleInfoKHR structure is defined as:

// Provided by VK_KHR_external_fence_win32
typedef struct VkExportFenceWin32HandleInfoKHR {
    VkStructureType               sType;
    const void*                   pNext;
    const SECURITY_ATTRIBUTES*    pAttributes;
    DWORD                         dwAccess;
    LPCWSTR                       name;
} VkExportFenceWin32HandleInfoKHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • pAttributes is a pointer to a Windows SECURITY_ATTRIBUTES structure specifying security attributes of the handle.

  • dwAccess is a DWORD specifying access rights of the handle.

  • name is a null-terminated UTF-16 string to associate with the underlying synchronization primitive referenced by NT handles exported from the created fence.

If VkExportFenceCreateInfo is not included in the same pNext chain, this structure is ignored.

If VkExportFenceCreateInfo is included in the pNext chain of VkFenceCreateInfo with a Windows handleType, but either VkExportFenceWin32HandleInfoKHR is not included in the pNext chain, or it is included but pAttributes is set to NULL, default security descriptor values will be used, and child processes created by the application will not inherit the handle, as described in the MSDN documentation for “Synchronization Object Security and Access Rights”1. Further, if the structure is not present, the access rights will be

DXGI_SHARED_RESOURCE_READ | DXGI_SHARED_RESOURCE_WRITE

for handles of the following types:

VK_EXTERNAL_FENCE_HANDLE_TYPE_OPAQUE_WIN32_BIT

1

https://docs.microsoft.com/en-us/windows/win32/sync/synchronization-object-security-and-access-rights

Valid Usage

  • VUID-VkExportFenceWin32HandleInfoKHR-handleTypes-01447
    If VkExportFenceCreateInfo::handleTypes does not include VK_EXTERNAL_FENCE_HANDLE_TYPE_OPAQUE_WIN32_BIT, a VkExportFenceWin32HandleInfoKHR structure must not be included in the pNext chain of VkFenceCreateInfo

Valid Usage (Implicit)

  • VUID-VkExportFenceWin32HandleInfoKHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_EXPORT_FENCE_WIN32_HANDLE_INFO_KHR

  • VUID-VkExportFenceWin32HandleInfoKHR-pAttributes-parameter
    If pAttributes is not NULL, pAttributes must be a valid pointer to a valid SECURITY_ATTRIBUTES value

To export a Windows handle representing the state of a fence, call:

// Provided by VK_KHR_external_fence_win32
VkResult vkGetFenceWin32HandleKHR(
    VkDevice                                    device,
    const VkFenceGetWin32HandleInfoKHR*         pGetWin32HandleInfo,
    HANDLE*                                     pHandle);

  • device is the logical device that created the fence being exported.

  • pGetWin32HandleInfo is a pointer to a VkFenceGetWin32HandleInfoKHR structure containing parameters of the export operation.

  • pHandle will return the Windows handle representing the fence state.

For handle types defined as NT handles, the handles returned by vkGetFenceWin32HandleKHR are owned by the application. To avoid leaking resources, the application must release ownership of them using the CloseHandle system call when they are no longer needed.

Exporting a Windows handle from a fence may have side effects depending on the transference of the specified handle type, as described in Importing Fence Payloads.

Valid Usage (Implicit)

  • VUID-vkGetFenceWin32HandleKHR-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkGetFenceWin32HandleKHR-pGetWin32HandleInfo-parameter
    pGetWin32HandleInfo must be a valid pointer to a valid VkFenceGetWin32HandleInfoKHR structure

  • VUID-vkGetFenceWin32HandleKHR-pHandle-parameter
    pHandle must be a valid pointer to a HANDLE value

Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_TOO_MANY_OBJECTS

  • VK_ERROR_OUT_OF_HOST_MEMORY

The VkFenceGetWin32HandleInfoKHR structure is defined as:

// Provided by VK_KHR_external_fence_win32
typedef struct VkFenceGetWin32HandleInfoKHR {
    VkStructureType                      sType;
    const void*                          pNext;
    VkFence                              fence;
    VkExternalFenceHandleTypeFlagBits    handleType;
} VkFenceGetWin32HandleInfoKHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • fence is the fence from which state will be exported.

  • handleType is a VkExternalFenceHandleTypeFlagBits value specifying the type of handle requested.

The properties of the handle returned depend on the value of handleType. See VkExternalFenceHandleTypeFlagBits for a description of the properties of the defined external fence handle types.

Valid Usage

  • VUID-VkFenceGetWin32HandleInfoKHR-handleType-01448
    handleType must have been included in VkExportFenceCreateInfo::handleTypes when the fence’s current payload was created

  • VUID-VkFenceGetWin32HandleInfoKHR-handleType-01449
    If handleType is defined as an NT handle, vkGetFenceWin32HandleKHR must be called no more than once for each valid unique combination of fence and handleType

  • VUID-VkFenceGetWin32HandleInfoKHR-fence-01450
    fence must not currently have its payload replaced by an imported payload as described below in Importing Fence Payloads unless that imported payload’s handle type was included in VkExternalFenceProperties::exportFromImportedHandleTypes for handleType

  • VUID-VkFenceGetWin32HandleInfoKHR-handleType-01451
    If handleType refers to a handle type with copy payload transference semantics, fence must be signaled, or have an associated fence signal operation pending execution

  • VUID-VkFenceGetWin32HandleInfoKHR-handleType-01452
    handleType must be defined as an NT handle or a global share handle

Valid Usage (Implicit)

  • VUID-VkFenceGetWin32HandleInfoKHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_FENCE_GET_WIN32_HANDLE_INFO_KHR

  • VUID-VkFenceGetWin32HandleInfoKHR-pNext-pNext
    pNext must be NULL

  • VUID-VkFenceGetWin32HandleInfoKHR-fence-parameter
    fence must be a valid VkFence handle

  • VUID-VkFenceGetWin32HandleInfoKHR-handleType-parameter
    handleType must be a valid VkExternalFenceHandleTypeFlagBits value

To export a POSIX file descriptor representing the payload of a fence, call:

// Provided by VK_KHR_external_fence_fd
VkResult vkGetFenceFdKHR(
    VkDevice                                    device,
    const VkFenceGetFdInfoKHR*                  pGetFdInfo,
    int*                                        pFd);

  • device is the logical device that created the fence being exported.

  • pGetFdInfo is a pointer to a VkFenceGetFdInfoKHR structure containing parameters of the export operation.

  • pFd will return the file descriptor representing the fence payload.

Each call to vkGetFenceFdKHR must create a new file descriptor and transfer ownership of it to the application. To avoid leaking resources, the application must release ownership of the file descriptor when it is no longer needed.

Note

Ownership can be released in many ways. For example, the application can call close() on the file descriptor, or transfer ownership back to Vulkan by using the file descriptor to import a fence payload.

If pGetFdInfo->handleType is VK_EXTERNAL_FENCE_HANDLE_TYPE_SYNC_FD_BIT and the fence is signaled at the time vkGetFenceFdKHR is called, pFd may return the value -1 instead of a valid file descriptor.

Where supported by the operating system, the implementation must set the file descriptor to be closed automatically when an execve system call is made.

Exporting a file descriptor from a fence may have side effects depending on the transference of the specified handle type, as described in Importing Fence State.

Valid Usage (Implicit)

  • VUID-vkGetFenceFdKHR-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkGetFenceFdKHR-pGetFdInfo-parameter
    pGetFdInfo must be a valid pointer to a valid VkFenceGetFdInfoKHR structure

  • VUID-vkGetFenceFdKHR-pFd-parameter
    pFd must be a valid pointer to an int value

Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_TOO_MANY_OBJECTS

  • VK_ERROR_OUT_OF_HOST_MEMORY

The VkFenceGetFdInfoKHR structure is defined as:

// Provided by VK_KHR_external_fence_fd
typedef struct VkFenceGetFdInfoKHR {
    VkStructureType                      sType;
    const void*                          pNext;
    VkFence                              fence;
    VkExternalFenceHandleTypeFlagBits    handleType;
} VkFenceGetFdInfoKHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • fence is the fence from which state will be exported.

  • handleType is a VkExternalFenceHandleTypeFlagBits value specifying the type of handle requested.

The properties of the file descriptor returned depend on the value of handleType. See VkExternalFenceHandleTypeFlagBits for a description of the properties of the defined external fence handle types.

Valid Usage

  • VUID-VkFenceGetFdInfoKHR-handleType-01453
    handleType must have been included in VkExportFenceCreateInfo::handleTypes when fence’s current payload was created

  • VUID-VkFenceGetFdInfoKHR-handleType-01454
    If handleType refers to a handle type with copy payload transference semantics, fence must be signaled, or have an associated fence signal operation pending execution

  • VUID-VkFenceGetFdInfoKHR-fence-01455
    fence must not currently have its payload replaced by an imported payload as described below in Importing Fence Payloads unless that imported payload’s handle type was included in VkExternalFenceProperties::exportFromImportedHandleTypes for handleType

  • VUID-VkFenceGetFdInfoKHR-handleType-01456
    handleType must be defined as a POSIX file descriptor handle

Valid Usage (Implicit)

  • VUID-VkFenceGetFdInfoKHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_FENCE_GET_FD_INFO_KHR

  • VUID-VkFenceGetFdInfoKHR-pNext-pNext
    pNext must be NULL

  • VUID-VkFenceGetFdInfoKHR-fence-parameter
    fence must be a valid VkFence handle

  • VUID-VkFenceGetFdInfoKHR-handleType-parameter
    handleType must be a valid VkExternalFenceHandleTypeFlagBits value

To destroy a fence, call:

// Provided by VK_VERSION_1_0
void vkDestroyFence(
    VkDevice                                    device,
    VkFence                                     fence,
    const VkAllocationCallbacks*                pAllocator);

  • device is the logical device that destroys the fence.

  • fence is the handle of the fence to destroy.

  • pAllocator controls host memory allocation as described in the Memory Allocation chapter.

Valid Usage

  • VUID-vkDestroyFence-fence-01120
    All queue submission commands that refer to fence must have completed execution

  • VUID-vkDestroyFence-fence-01121
    If VkAllocationCallbacks were provided when fence was created, a compatible set of callbacks must be provided here

  • VUID-vkDestroyFence-fence-01122
    If no VkAllocationCallbacks were provided when fence was created, pAllocator must be NULL

Valid Usage (Implicit)

  • VUID-vkDestroyFence-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkDestroyFence-fence-parameter
    If fence is not VK_NULL_HANDLE, fence must be a valid VkFence handle

  • VUID-vkDestroyFence-pAllocator-parameter
    If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure

  • VUID-vkDestroyFence-fence-parent
    If fence is a valid handle, it must have been created, allocated, or retrieved from device

Host Synchronization

  • Host access to fence must be externally synchronized

To query the status of a fence from the host, call:

// Provided by VK_VERSION_1_0
VkResult vkGetFenceStatus(
    VkDevice                                    device,
    VkFence                                     fence);

  • device is the logical device that owns the fence.

  • fence is the handle of the fence to query.

Upon success, vkGetFenceStatus returns the status of the fence object, with the following return codes:

Table 5. Fence Object Status Codes
Status Meaning

VK_SUCCESS

The fence specified by fence is signaled.

VK_NOT_READY

The fence specified by fence is unsignaled.

VK_ERROR_DEVICE_LOST

The device has been lost. See Lost Device.

If a queue submission command is pending execution, then the value returned by this command may immediately be out of date.

If the device has been lost (see Lost Device), vkGetFenceStatus may return any of the above status codes. If the device has been lost and vkGetFenceStatus is called repeatedly, it will eventually return either VK_SUCCESS or VK_ERROR_DEVICE_LOST.

Valid Usage (Implicit)

  • VUID-vkGetFenceStatus-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkGetFenceStatus-fence-parameter
    fence must be a valid VkFence handle

  • VUID-vkGetFenceStatus-fence-parent
    fence must have been created, allocated, or retrieved from device

Return Codes
Success

  • VK_SUCCESS

  • VK_NOT_READY

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

  • VK_ERROR_DEVICE_LOST

To set the state of fences to unsignaled from the host, call:

// Provided by VK_VERSION_1_0
VkResult vkResetFences(
    VkDevice                                    device,
    uint32_t                                    fenceCount,
    const VkFence*                              pFences);

  • device is the logical device that owns the fences.

  • fenceCount is the number of fences to reset.

  • pFences is a pointer to an array of fence handles to reset.

If any member of pFences currently has its payload imported with temporary permanence, that fence’s prior permanent payload is first restored. The remaining operations described therefore operate on the restored payload.

When vkResetFences is executed on the host, it defines a fence unsignal operation for each fence, which resets the fence to the unsignaled state.

If any member of pFences is already in the unsignaled state when vkResetFences is executed, then vkResetFences has no effect on that fence.

Valid Usage

  • VUID-vkResetFences-pFences-01123
    Each element of pFences must not be currently associated with any queue command that has not yet completed execution on that queue

Valid Usage (Implicit)

  • VUID-vkResetFences-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkResetFences-pFences-parameter
    pFences must be a valid pointer to an array of fenceCount valid VkFence handles

  • VUID-vkResetFences-fenceCount-arraylength
    fenceCount must be greater than 0

  • VUID-vkResetFences-pFences-parent
    Each element of pFences must have been created, allocated, or retrieved from device

Host Synchronization

  • Host access to each member of pFences must be externally synchronized

Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

When a fence is submitted to a queue as part of a queue submission command, it defines a memory dependency on the batches that were submitted as part of that command, and defines a fence signal operation which sets the fence to the signaled state.

The first synchronization scope includes every batch submitted in the same queue submission command. Fence signal operations that are defined by vkQueueSubmit or vkQueueSubmit2 additionally include in the first synchronization scope all commands that occur earlier in submission order. Fence signal operations that are defined by vkQueueSubmit or vkQueueSubmit2 or vkQueueBindSparse additionally include in the first synchronization scope any semaphore and fence signal operations that occur earlier in signal operation order.

The second synchronization scope only includes the fence signal operation.

The first access scope includes all memory access performed by the device.

The second access scope is empty.

To wait for one or more fences to enter the signaled state on the host, call:

// Provided by VK_VERSION_1_0
VkResult vkWaitForFences(
    VkDevice                                    device,
    uint32_t                                    fenceCount,
    const VkFence*                              pFences,
    VkBool32                                    waitAll,
    uint64_t                                    timeout);

  • device is the logical device that owns the fences.

  • fenceCount is the number of fences to wait on.

  • pFences is a pointer to an array of fenceCount fence handles.

  • waitAll is the condition that must be satisfied to successfully unblock the wait. If waitAll is VK_TRUE, then the condition is that all fences in pFences are signaled. Otherwise, the condition is that at least one fence in pFences is signaled.

  • timeout is the timeout period in units of nanoseconds. timeout is adjusted to the closest value allowed by the implementation-dependent timeout accuracy, which may be substantially longer than one nanosecond, and may be longer than the requested period.

If the condition is satisfied when vkWaitForFences is called, then vkWaitForFences returns immediately. If the condition is not satisfied at the time vkWaitForFences is called, then vkWaitForFences will block and wait until the condition is satisfied or the timeout has expired, whichever is sooner.

If timeout is zero, then vkWaitForFences does not wait, but simply returns the current state of the fences. VK_TIMEOUT will be returned in this case if the condition is not satisfied, even though no actual wait was performed.

If the condition is satisfied before the timeout has expired, vkWaitForFences returns VK_SUCCESS. Otherwise, vkWaitForFences returns VK_TIMEOUT after the timeout has expired.

If device loss occurs (see Lost Device) before the timeout has expired, vkWaitForFences must return in finite time with either VK_SUCCESS or VK_ERROR_DEVICE_LOST.

Note

While we guarantee that vkWaitForFences must return in finite time, no guarantees are made that it returns immediately upon device loss. However, the application can reasonably expect that the delay will be on the order of seconds and that calling vkWaitForFences will not result in a permanently (or seemingly permanently) dead process.
Valid Usage (Implicit)

  • VUID-vkWaitForFences-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkWaitForFences-pFences-parameter
    pFences must be a valid pointer to an array of fenceCount valid VkFence handles

  • VUID-vkWaitForFences-fenceCount-arraylength
    fenceCount must be greater than 0

  • VUID-vkWaitForFences-pFences-parent
    Each element of pFences must have been created, allocated, or retrieved from device

Return Codes
Success

  • VK_SUCCESS

  • VK_TIMEOUT

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

  • VK_ERROR_DEVICE_LOST

An execution dependency is defined by waiting for a fence to become signaled, either via vkWaitForFences or by polling on vkGetFenceStatus.

The first synchronization scope includes only the fence signal operation.

The second synchronization scope includes the host operations of vkWaitForFences or vkGetFenceStatus indicating that the fence has become signaled.

Note

Signaling a fence and waiting on the host does not guarantee that the results of memory accesses will be visible to the host, as the access scope of a memory dependency defined by a fence only includes device access. A memory barrier or other memory dependency must be used to guarantee this. See the description of host access types for more information.

7.3.1. Alternate Methods to Signal Fences

Besides submitting a fence to a queue as part of a queue submission command, a fence may also be signaled when a particular event occurs on a device or display.

To create a fence that will be signaled when an event occurs on a device, call:

// Provided by VK_EXT_display_control
VkResult vkRegisterDeviceEventEXT(
    VkDevice                                    device,
    const VkDeviceEventInfoEXT*                 pDeviceEventInfo,
    const VkAllocationCallbacks*                pAllocator,
    VkFence*                                    pFence);

  • device is a logical device on which the event may occur.

  • pDeviceEventInfo is a pointer to a VkDeviceEventInfoEXT structure describing the event of interest to the application.

  • pAllocator controls host memory allocation as described in the Memory Allocation chapter.

  • pFence is a pointer to a handle in which the resulting fence object is returned.

Valid Usage (Implicit)

  • VUID-vkRegisterDeviceEventEXT-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkRegisterDeviceEventEXT-pDeviceEventInfo-parameter
    pDeviceEventInfo must be a valid pointer to a valid VkDeviceEventInfoEXT structure

  • VUID-vkRegisterDeviceEventEXT-pAllocator-parameter
    If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure

  • VUID-vkRegisterDeviceEventEXT-pFence-parameter
    pFence must be a valid pointer to a VkFence handle

Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

The VkDeviceEventInfoEXT structure is defined as:

// Provided by VK_EXT_display_control
typedef struct VkDeviceEventInfoEXT {
    VkStructureType         sType;
    const void*             pNext;
    VkDeviceEventTypeEXT    deviceEvent;
} VkDeviceEventInfoEXT;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • device is a VkDeviceEventTypeEXT value specifying when the fence will be signaled.

Valid Usage (Implicit)

  • VUID-VkDeviceEventInfoEXT-sType-sType
    sType must be VK_STRUCTURE_TYPE_DEVICE_EVENT_INFO_EXT

  • VUID-VkDeviceEventInfoEXT-pNext-pNext
    pNext must be NULL

  • VUID-VkDeviceEventInfoEXT-deviceEvent-parameter
    deviceEvent must be a valid VkDeviceEventTypeEXT value

Possible values of VkDeviceEventInfoEXT::device, specifying when a fence will be signaled, are:

// Provided by VK_EXT_display_control
typedef enum VkDeviceEventTypeEXT {
    VK_DEVICE_EVENT_TYPE_DISPLAY_HOTPLUG_EXT = 0,
} VkDeviceEventTypeEXT;

  • VK_DEVICE_EVENT_TYPE_DISPLAY_HOTPLUG_EXT specifies that the fence is signaled when a display is plugged into or unplugged from the specified device. Applications can use this notification to determine when they need to re-enumerate the available displays on a device.

To create a fence that will be signaled when an event occurs on a VkDisplayKHR object, call:

// Provided by VK_EXT_display_control
VkResult vkRegisterDisplayEventEXT(
    VkDevice                                    device,
    VkDisplayKHR                                display,
    const VkDisplayEventInfoEXT*                pDisplayEventInfo,
    const VkAllocationCallbacks*                pAllocator,
    VkFence*                                    pFence);

  • device is a logical device associated with display

  • display is the display on which the event may occur.

  • pDisplayEventInfo is a pointer to a VkDisplayEventInfoEXT structure describing the event of interest to the application.

  • pAllocator controls host memory allocation as described in the Memory Allocation chapter.

  • pFence is a pointer to a handle in which the resulting fence object is returned.

Valid Usage (Implicit)

  • VUID-vkRegisterDisplayEventEXT-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkRegisterDisplayEventEXT-display-parameter
    display must be a valid VkDisplayKHR handle

  • VUID-vkRegisterDisplayEventEXT-pDisplayEventInfo-parameter
    pDisplayEventInfo must be a valid pointer to a valid VkDisplayEventInfoEXT structure

  • VUID-vkRegisterDisplayEventEXT-pAllocator-parameter
    If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure

  • VUID-vkRegisterDisplayEventEXT-pFence-parameter
    pFence must be a valid pointer to a VkFence handle

  • VUID-vkRegisterDisplayEventEXT-commonparent
    Both of device, and display must have been created, allocated, or retrieved from the same VkPhysicalDevice

Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

The VkDisplayEventInfoEXT structure is defined as:

// Provided by VK_EXT_display_control
typedef struct VkDisplayEventInfoEXT {
    VkStructureType          sType;
    const void*              pNext;
    VkDisplayEventTypeEXT    displayEvent;
} VkDisplayEventInfoEXT;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • displayEvent is a VkDisplayEventTypeEXT specifying when the fence will be signaled.

Valid Usage (Implicit)

  • VUID-VkDisplayEventInfoEXT-sType-sType
    sType must be VK_STRUCTURE_TYPE_DISPLAY_EVENT_INFO_EXT

  • VUID-VkDisplayEventInfoEXT-pNext-pNext
    pNext must be NULL

  • VUID-VkDisplayEventInfoEXT-displayEvent-parameter
    displayEvent must be a valid VkDisplayEventTypeEXT value

Possible values of VkDisplayEventInfoEXT::displayEvent, specifying when a fence will be signaled, are:

// Provided by VK_EXT_display_control
typedef enum VkDisplayEventTypeEXT {
    VK_DISPLAY_EVENT_TYPE_FIRST_PIXEL_OUT_EXT = 0,
} VkDisplayEventTypeEXT;

  • VK_DISPLAY_EVENT_TYPE_FIRST_PIXEL_OUT_EXT specifies that the fence is signaled when the first pixel of the next display refresh cycle leaves the display engine for the display.

7.3.2. Importing Fence Payloads

Applications can import a fence payload into an existing fence using an external fence handle. The effects of the import operation will be either temporary or permanent, as specified by the application. If the import is temporary, the fence will be restored to its permanent state the next time that fence is passed to vkResetFences.

Note

Restoring a fence to its prior permanent payload is a distinct operation from resetting a fence payload. See vkResetFences for more detail.

Performing a subsequent temporary import on a fence before resetting it has no effect on this requirement; the next unsignal of the fence must still restore its last permanent state. A permanent payload import behaves as if the target fence was destroyed, and a new fence was created with the same handle but the imported payload. Because importing a fence payload temporarily or permanently detaches the existing payload from a fence, similar usage restrictions to those applied to vkDestroyFence are applied to any command that imports a fence payload. Which of these import types is used is referred to as the import operation’s permanence. Each handle type supports either one or both types of permanence.

The implementation must perform the import operation by either referencing or copying the payload referred to by the specified external fence handle, depending on the handle’s type. The import method used is referred to as the handle type’s transference. When using handle types with reference transference, importing a payload to a fence adds the fence to the set of all fences sharing that payload. This set includes the fence from which the payload was exported. Fence signaling, waiting, and resetting operations performed on any fence in the set must behave as if the set were a single fence. Importing a payload using handle types with copy transference creates a duplicate copy of the payload at the time of import, but makes no further reference to it. Fence signaling, waiting, and resetting operations performed on the target of copy imports must not affect any other fence or payload.

Export operations have the same transference as the specified handle type’s import operations. Additionally, exporting a fence payload to a handle with copy transference has the same side effects on the source fence’s payload as executing a fence reset operation. If the fence was using a temporarily imported payload, the fence’s prior permanent payload will be restored.

Note

The tables Handle Types Supported by VkImportFenceWin32HandleInfoKHR and Handle Types Supported by VkImportFenceFdInfoKHR define the permanence and transference of each handle type.

External synchronization allows implementations to modify an object’s internal state, i.e. payload, without internal synchronization. However, for fences sharing a payload across processes, satisfying the external synchronization requirements of VkFence parameters as if all fences in the set were the same object is sometimes infeasible. Satisfying valid usage constraints on the state of a fence would similarly require impractical coordination or levels of trust between processes. Therefore, these constraints only apply to a specific fence handle, not to its payload. For distinct fence objects which share a payload:

  • If multiple commands which queue a signal operation, or which unsignal a fence, are called concurrently, behavior will be as if the commands were called in an arbitrary sequential order.

  • If a queue submission command is called with a fence that is sharing a payload, and the payload is already associated with another queue command that has not yet completed execution, either one or both of the commands will cause the fence to become signaled when they complete execution.

  • If a fence payload is reset while it is associated with a queue command that has not yet completed execution, the payload will become unsignaled, but may become signaled again when the command completes execution.

  • In the preceding cases, any of the devices associated with the fences sharing the payload may be lost, or any of the queue submission or fence reset commands may return VK_ERROR_INITIALIZATION_FAILED.

Other than these non-deterministic results, behavior is well defined. In particular:

  • The implementation must not crash or enter an internally inconsistent state where future valid Vulkan commands might cause undefined results,

  • Timeouts on future wait commands on fences sharing the payload must be effective.

Note

These rules allow processes to synchronize access to shared memory without trusting each other. However, such processes must still be cautious not to use the shared fence for more than synchronizing access to the shared memory. For example, a process should not use a fence with shared payload to tell when commands it submitted to a queue have completed and objects used by those commands may be destroyed, since the other process can accidentally or maliciously cause the fence to signal before the commands actually complete.

When a fence is using an imported payload, its VkExportFenceCreateInfo::handleTypes value is specified when creating the fence from which the payload was exported, rather than specified when creating the fence. Additionally, VkExternalFenceProperties::exportFromImportedHandleTypes restricts which handle types can be exported from such a fence based on the specific handle type used to import the current payload. Passing a fence to vkAcquireNextImageKHR is equivalent to temporarily importing a fence payload to that fence.

Note

Because the exportable handle types of an imported fence correspond to its current imported payload, and vkAcquireNextImageKHR behaves the same as a temporary import operation for which the source fence is opaque to the application, applications have no way of determining whether any external handle types can be exported from a fence in this state. Therefore, applications must not attempt to export handles from fences using a temporarily imported payload from vkAcquireNextImageKHR.

When importing a fence payload, it is the responsibility of the application to ensure the external handles meet all valid usage requirements. However, implementations must perform sufficient validation of external handles to ensure that the operation results in a valid fence which will not cause program termination, device loss, queue stalls, host thread stalls, or corruption of other resources when used as allowed according to its import parameters. If the external handle provided does not meet these requirements, the implementation must fail the fence payload import operation with the error code VK_ERROR_INVALID_EXTERNAL_HANDLE.

To import a fence payload from a Windows handle, call:

// Provided by VK_KHR_external_fence_win32
VkResult vkImportFenceWin32HandleKHR(
    VkDevice                                    device,
    const VkImportFenceWin32HandleInfoKHR*      pImportFenceWin32HandleInfo);

  • device is the logical device that created the fence.

  • pImportFenceWin32HandleInfo is a pointer to a VkImportFenceWin32HandleInfoKHR structure specifying the fence and import parameters.

Importing a fence payload from Windows handles does not transfer ownership of the handle to the Vulkan implementation. For handle types defined as NT handles, the application must release ownership using the CloseHandle system call when the handle is no longer needed.

Applications can import the same fence payload into multiple instances of Vulkan, into the same instance from which it was exported, and multiple times into a given Vulkan instance.

Valid Usage

  • VUID-vkImportFenceWin32HandleKHR-fence-04448
    fence must not be associated with any queue command that has not yet completed execution on that queue

Valid Usage (Implicit)

  • VUID-vkImportFenceWin32HandleKHR-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkImportFenceWin32HandleKHR-pImportFenceWin32HandleInfo-parameter
    pImportFenceWin32HandleInfo must be a valid pointer to a valid VkImportFenceWin32HandleInfoKHR structure

Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_INVALID_EXTERNAL_HANDLE

The VkImportFenceWin32HandleInfoKHR structure is defined as:

// Provided by VK_KHR_external_fence_win32
typedef struct VkImportFenceWin32HandleInfoKHR {
    VkStructureType                      sType;
    const void*                          pNext;
    VkFence                              fence;
    VkFenceImportFlags                   flags;
    VkExternalFenceHandleTypeFlagBits    handleType;
    HANDLE                               handle;
    LPCWSTR                              name;
} VkImportFenceWin32HandleInfoKHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • fence is the fence into which the state will be imported.

  • flags is a bitmask of VkFenceImportFlagBits specifying additional parameters for the fence payload import operation.

  • handleType is a VkExternalFenceHandleTypeFlagBits value specifying the type of handle.

  • handle is NULL or the external handle to import.

  • name is NULL or a null-terminated UTF-16 string naming the underlying synchronization primitive to import.

The handle types supported by handleType are:

Table 6. Handle Types Supported by VkImportFenceWin32HandleInfoKHR
Handle Type Transference Permanence Supported

VK_EXTERNAL_FENCE_HANDLE_TYPE_OPAQUE_WIN32_BIT

Reference

Temporary,Permanent

VK_EXTERNAL_FENCE_HANDLE_TYPE_OPAQUE_WIN32_KMT_BIT

Reference

Temporary,Permanent
Valid Usage

  • VUID-VkImportFenceWin32HandleInfoKHR-handleType-01457
    handleType must be a value included in the Handle Types Supported by VkImportFenceWin32HandleInfoKHR table

  • VUID-VkImportFenceWin32HandleInfoKHR-handleType-01459
    If handleType is not VK_EXTERNAL_FENCE_HANDLE_TYPE_OPAQUE_WIN32_BIT, name must be NULL

  • VUID-VkImportFenceWin32HandleInfoKHR-handleType-01460
    If handle is NULL, name must name a valid synchronization primitive of the type specified by handleType

  • VUID-VkImportFenceWin32HandleInfoKHR-handleType-01461
    If name is NULL, handle must be a valid handle of the type specified by handleType

  • VUID-VkImportFenceWin32HandleInfoKHR-handle-01462
    If handle is not NULL, name must be NULL

  • VUID-VkImportFenceWin32HandleInfoKHR-handle-01539
    If handle is not NULL, it must obey any requirements listed for handleType in external fence handle types compatibility

  • VUID-VkImportFenceWin32HandleInfoKHR-name-01540
    If name is not NULL, it must obey any requirements listed for handleType in external fence handle types compatibility

Valid Usage (Implicit)

  • VUID-VkImportFenceWin32HandleInfoKHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_IMPORT_FENCE_WIN32_HANDLE_INFO_KHR

  • VUID-VkImportFenceWin32HandleInfoKHR-pNext-pNext
    pNext must be NULL

  • VUID-VkImportFenceWin32HandleInfoKHR-fence-parameter
    fence must be a valid VkFence handle

  • VUID-VkImportFenceWin32HandleInfoKHR-flags-parameter
    flags must be a valid combination of VkFenceImportFlagBits values

Host Synchronization

  • Host access to fence must be externally synchronized

To import a fence payload from a POSIX file descriptor, call:

// Provided by VK_KHR_external_fence_fd
VkResult vkImportFenceFdKHR(
    VkDevice                                    device,
    const VkImportFenceFdInfoKHR*               pImportFenceFdInfo);

  • device is the logical device that created the fence.

  • pImportFenceFdInfo is a pointer to a VkImportFenceFdInfoKHR structure specifying the fence and import parameters.

Importing a fence payload from a file descriptor transfers ownership of the file descriptor from the application to the Vulkan implementation. The application must not perform any operations on the file descriptor after a successful import.

Applications can import the same fence payload into multiple instances of Vulkan, into the same instance from which it was exported, and multiple times into a given Vulkan instance.

Valid Usage

  • VUID-vkImportFenceFdKHR-fence-01463
    fence must not be associated with any queue command that has not yet completed execution on that queue

Valid Usage (Implicit)

  • VUID-vkImportFenceFdKHR-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkImportFenceFdKHR-pImportFenceFdInfo-parameter
    pImportFenceFdInfo must be a valid pointer to a valid VkImportFenceFdInfoKHR structure

Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_INVALID_EXTERNAL_HANDLE

The VkImportFenceFdInfoKHR structure is defined as:

// Provided by VK_KHR_external_fence_fd
typedef struct VkImportFenceFdInfoKHR {
    VkStructureType                      sType;
    const void*                          pNext;
    VkFence                              fence;
    VkFenceImportFlags                   flags;
    VkExternalFenceHandleTypeFlagBits    handleType;
    int                                  fd;
} VkImportFenceFdInfoKHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • fence is the fence into which the payload will be imported.

  • flags is a bitmask of VkFenceImportFlagBits specifying additional parameters for the fence payload import operation.

  • handleType is a VkExternalFenceHandleTypeFlagBits value specifying the type of fd.

  • fd is the external handle to import.

The handle types supported by handleType are:

Table 7. Handle Types Supported by VkImportFenceFdInfoKHR
Handle Type Transference Permanence Supported

VK_EXTERNAL_FENCE_HANDLE_TYPE_OPAQUE_FD_BIT

Reference

Temporary,Permanent

VK_EXTERNAL_FENCE_HANDLE_TYPE_SYNC_FD_BIT

Copy

Temporary
Valid Usage

  • VUID-VkImportFenceFdInfoKHR-handleType-01464
    handleType must be a value included in the Handle Types Supported by VkImportFenceFdInfoKHR table

  • VUID-VkImportFenceFdInfoKHR-fd-01541
    fd must obey any requirements listed for handleType in external fence handle types compatibility

  • VUID-VkImportFenceFdInfoKHR-handleType-07306
    If handleType refers to a handle type with copy payload transference semantics, flags must contain VK_FENCE_IMPORT_TEMPORARY_BIT

If handleType is VK_EXTERNAL_FENCE_HANDLE_TYPE_SYNC_FD_BIT, the special value -1 for fd is treated like a valid sync file descriptor referring to an object that has already signaled. The import operation will succeed and the VkFence will have a temporarily imported payload as if a valid file descriptor had been provided.

Note

This special behavior for importing an invalid sync file descriptor allows easier interoperability with other system APIs which use the convention that an invalid sync file descriptor represents work that has already completed and does not need to be waited for. It is consistent with the option for implementations to return a -1 file descriptor when exporting a VK_EXTERNAL_FENCE_HANDLE_TYPE_SYNC_FD_BIT from a VkFence which is signaled.
Valid Usage (Implicit)

  • VUID-VkImportFenceFdInfoKHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_IMPORT_FENCE_FD_INFO_KHR

  • VUID-VkImportFenceFdInfoKHR-pNext-pNext
    pNext must be NULL

  • VUID-VkImportFenceFdInfoKHR-fence-parameter
    fence must be a valid VkFence handle

  • VUID-VkImportFenceFdInfoKHR-flags-parameter
    flags must be a valid combination of VkFenceImportFlagBits values

  • VUID-VkImportFenceFdInfoKHR-handleType-parameter
    handleType must be a valid VkExternalFenceHandleTypeFlagBits value

Host Synchronization

  • Host access to fence must be externally synchronized

Bits which can be set in

specifying additional parameters of a fence import operation are:

// Provided by VK_VERSION_1_1
typedef enum VkFenceImportFlagBits {
    VK_FENCE_IMPORT_TEMPORARY_BIT = 0x00000001,
  // Provided by VK_KHR_external_fence
    VK_FENCE_IMPORT_TEMPORARY_BIT_KHR = VK_FENCE_IMPORT_TEMPORARY_BIT,
} VkFenceImportFlagBits;

or the equivalent

// Provided by VK_KHR_external_fence
typedef VkFenceImportFlagBits VkFenceImportFlagBitsKHR;

  • VK_FENCE_IMPORT_TEMPORARY_BIT specifies that the fence payload will be imported only temporarily, as described in Importing Fence Payloads, regardless of the permanence of handleType.

// Provided by VK_VERSION_1_1
typedef VkFlags VkFenceImportFlags;

or the equivalent

// Provided by VK_KHR_external_fence
typedef VkFenceImportFlags VkFenceImportFlagsKHR;

VkFenceImportFlags is a bitmask type for setting a mask of zero or more VkFenceImportFlagBits.

7.4. Semaphores

Semaphores are a synchronization primitive that can be used to insert a dependency between queue operations or between a queue operation and the host. Binary semaphores have two states - signaled and unsignaled. Timeline semaphores have a strictly increasing 64-bit unsigned integer payload and are signaled with respect to a particular reference value. A semaphore can be signaled after execution of a queue operation is completed, and a queue operation can wait for a semaphore to become signaled before it begins execution. A timeline semaphore can additionally be signaled from the host with the vkSignalSemaphore command and waited on from the host with the vkWaitSemaphores command.

The internal data of a semaphore may include a reference to any resources and pending work associated with signal or unsignal operations performed on that semaphore object, collectively referred to as the semaphore’s payload. Mechanisms to import and export that internal data to and from semaphores are provided below. These mechanisms indirectly enable applications to share semaphore state between two or more semaphores and other synchronization primitives across process and API boundaries.

Semaphores are represented by VkSemaphore handles:

// Provided by VK_VERSION_1_0
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkSemaphore)

To create a semaphore, call:

// Provided by VK_VERSION_1_0
VkResult vkCreateSemaphore(
    VkDevice                                    device,
    const VkSemaphoreCreateInfo*                pCreateInfo,
    const VkAllocationCallbacks*                pAllocator,
    VkSemaphore*                                pSemaphore);

  • device is the logical device that creates the semaphore.

  • pCreateInfo is a pointer to a VkSemaphoreCreateInfo structure containing information about how the semaphore is to be created.

  • pAllocator controls host memory allocation as described in the Memory Allocation chapter.

  • pSemaphore is a pointer to a handle in which the resulting semaphore object is returned.

Valid Usage (Implicit)

  • VUID-vkCreateSemaphore-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkCreateSemaphore-pCreateInfo-parameter
    pCreateInfo must be a valid pointer to a valid VkSemaphoreCreateInfo structure

  • VUID-vkCreateSemaphore-pAllocator-parameter
    If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure

  • VUID-vkCreateSemaphore-pSemaphore-parameter
    pSemaphore must be a valid pointer to a VkSemaphore handle

Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

The VkSemaphoreCreateInfo structure is defined as:

// Provided by VK_VERSION_1_0
typedef struct VkSemaphoreCreateInfo {
    VkStructureType           sType;
    const void*               pNext;
    VkSemaphoreCreateFlags    flags;
} VkSemaphoreCreateInfo;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • flags is reserved for future use.

Valid Usage

  • VUID-VkSemaphoreCreateInfo-pNext-06789
    If the pNext chain includes a VkExportMetalObjectCreateInfoEXT structure, its exportObjectType member must be VK_EXPORT_METAL_OBJECT_TYPE_METAL_SHARED_EVENT_BIT_EXT

Valid Usage (Implicit)
// Provided by VK_VERSION_1_0
typedef VkFlags VkSemaphoreCreateFlags;

VkSemaphoreCreateFlags is a bitmask type for setting a mask, but is currently reserved for future use.

The VkSemaphoreTypeCreateInfo structure is defined as:

// Provided by VK_VERSION_1_2
typedef struct VkSemaphoreTypeCreateInfo {
    VkStructureType    sType;
    const void*        pNext;
    VkSemaphoreType    semaphoreType;
    uint64_t           initialValue;
} VkSemaphoreTypeCreateInfo;

or the equivalent

// Provided by VK_KHR_timeline_semaphore
typedef VkSemaphoreTypeCreateInfo VkSemaphoreTypeCreateInfoKHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • semaphoreType is a VkSemaphoreType value specifying the type of the semaphore.

  • initialValue is the initial payload value if semaphoreType is VK_SEMAPHORE_TYPE_TIMELINE.

To create a semaphore of a specific type, add a VkSemaphoreTypeCreateInfo structure to the VkSemaphoreCreateInfo::pNext chain.

If no VkSemaphoreTypeCreateInfo structure is included in the pNext chain of VkSemaphoreCreateInfo, then the created semaphore will have a default VkSemaphoreType of VK_SEMAPHORE_TYPE_BINARY.

Valid Usage

  • VUID-VkSemaphoreTypeCreateInfo-timelineSemaphore-03252
    If the timelineSemaphore feature is not enabled, semaphoreType must not equal VK_SEMAPHORE_TYPE_TIMELINE

  • VUID-VkSemaphoreTypeCreateInfo-semaphoreType-03279
    If semaphoreType is VK_SEMAPHORE_TYPE_BINARY, initialValue must be zero

Valid Usage (Implicit)

  • VUID-VkSemaphoreTypeCreateInfo-sType-sType
    sType must be VK_STRUCTURE_TYPE_SEMAPHORE_TYPE_CREATE_INFO

  • VUID-VkSemaphoreTypeCreateInfo-semaphoreType-parameter
    semaphoreType must be a valid VkSemaphoreType value

Possible values of VkSemaphoreTypeCreateInfo::semaphoreType, specifying the type of a semaphore, are:

// Provided by VK_VERSION_1_2
typedef enum VkSemaphoreType {
    VK_SEMAPHORE_TYPE_BINARY = 0,
    VK_SEMAPHORE_TYPE_TIMELINE = 1,
  // Provided by VK_KHR_timeline_semaphore
    VK_SEMAPHORE_TYPE_BINARY_KHR = VK_SEMAPHORE_TYPE_BINARY,
  // Provided by VK_KHR_timeline_semaphore
    VK_SEMAPHORE_TYPE_TIMELINE_KHR = VK_SEMAPHORE_TYPE_TIMELINE,
} VkSemaphoreType;

or the equivalent

// Provided by VK_KHR_timeline_semaphore
typedef VkSemaphoreType VkSemaphoreTypeKHR;

  • VK_SEMAPHORE_TYPE_BINARY specifies a binary semaphore type that has a boolean payload indicating whether the semaphore is currently signaled or unsignaled. When created, the semaphore is in the unsignaled state.

  • VK_SEMAPHORE_TYPE_TIMELINE specifies a timeline semaphore type that has a strictly increasing 64-bit unsigned integer payload indicating whether the semaphore is signaled with respect to a particular reference value. When created, the semaphore payload has the value given by the initialValue field of VkSemaphoreTypeCreateInfo.

To create a semaphore whose payload can be exported to external handles, add a VkExportSemaphoreCreateInfo structure to the pNext chain of the VkSemaphoreCreateInfo structure. The VkExportSemaphoreCreateInfo structure is defined as:

// Provided by VK_VERSION_1_1
typedef struct VkExportSemaphoreCreateInfo {
    VkStructureType                       sType;
    const void*                           pNext;
    VkExternalSemaphoreHandleTypeFlags    handleTypes;
} VkExportSemaphoreCreateInfo;

or the equivalent

// Provided by VK_KHR_external_semaphore
typedef VkExportSemaphoreCreateInfo VkExportSemaphoreCreateInfoKHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • handleTypes is a bitmask of VkExternalSemaphoreHandleTypeFlagBits specifying one or more semaphore handle types the application can export from the resulting semaphore. The application can request multiple handle types for the same semaphore.

Valid Usage

  • VUID-VkExportSemaphoreCreateInfo-handleTypes-01124
    The bits in handleTypes must be supported and compatible, as reported by VkExternalSemaphoreProperties

Valid Usage (Implicit)

  • VUID-VkExportSemaphoreCreateInfo-sType-sType
    sType must be VK_STRUCTURE_TYPE_EXPORT_SEMAPHORE_CREATE_INFO

  • VUID-VkExportSemaphoreCreateInfo-handleTypes-parameter
    handleTypes must be a valid combination of VkExternalSemaphoreHandleTypeFlagBits values

To specify additional attributes of NT handles exported from a semaphore, add a VkExportSemaphoreWin32HandleInfoKHR structure to the pNext chain of the VkSemaphoreCreateInfo structure. The VkExportSemaphoreWin32HandleInfoKHR structure is defined as:

// Provided by VK_KHR_external_semaphore_win32
typedef struct VkExportSemaphoreWin32HandleInfoKHR {
    VkStructureType               sType;
    const void*                   pNext;
    const SECURITY_ATTRIBUTES*    pAttributes;
    DWORD                         dwAccess;
    LPCWSTR                       name;
} VkExportSemaphoreWin32HandleInfoKHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • pAttributes is a pointer to a Windows SECURITY_ATTRIBUTES structure specifying security attributes of the handle.

  • dwAccess is a DWORD specifying access rights of the handle.

  • name is a null-terminated UTF-16 string to associate with the underlying synchronization primitive referenced by NT handles exported from the created semaphore.

If VkExportSemaphoreCreateInfo is not included in the same pNext chain, this structure is ignored.

If VkExportSemaphoreCreateInfo is included in the pNext chain of VkSemaphoreCreateInfo with a Windows handleType, but either VkExportSemaphoreWin32HandleInfoKHR is not included in the pNext chain, or it is included but pAttributes is set to NULL, default security descriptor values will be used, and child processes created by the application will not inherit the handle, as described in the MSDN documentation for “Synchronization Object Security and Access Rights”1. Further, if the structure is not present, the access rights used depend on the handle type.

For handles of the following types:

VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32_BIT

The implementation must ensure the access rights allow both signal and wait operations on the semaphore.

For handles of the following types:

VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_D3D12_FENCE_BIT

The access rights must be:

GENERIC_ALL

1

https://docs.microsoft.com/en-us/windows/win32/sync/synchronization-object-security-and-access-rights

Valid Usage

  • VUID-VkExportSemaphoreWin32HandleInfoKHR-handleTypes-01125
    If VkExportSemaphoreCreateInfo::handleTypes does not include VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32_BIT or VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_D3D12_FENCE_BIT, VkExportSemaphoreWin32HandleInfoKHR must not be included in the pNext chain of VkSemaphoreCreateInfo

Valid Usage (Implicit)

  • VUID-VkExportSemaphoreWin32HandleInfoKHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_EXPORT_SEMAPHORE_WIN32_HANDLE_INFO_KHR

  • VUID-VkExportSemaphoreWin32HandleInfoKHR-pAttributes-parameter
    If pAttributes is not NULL, pAttributes must be a valid pointer to a valid SECURITY_ATTRIBUTES value

To export a Windows handle representing the payload of a semaphore, call:

// Provided by VK_KHR_external_semaphore_win32
VkResult vkGetSemaphoreWin32HandleKHR(
    VkDevice                                    device,
    const VkSemaphoreGetWin32HandleInfoKHR*     pGetWin32HandleInfo,
    HANDLE*                                     pHandle);

  • device is the logical device that created the semaphore being exported.

  • pGetWin32HandleInfo is a pointer to a VkSemaphoreGetWin32HandleInfoKHR structure containing parameters of the export operation.

  • pHandle will return the Windows handle representing the semaphore state.

For handle types defined as NT handles, the handles returned by vkGetSemaphoreWin32HandleKHR are owned by the application. To avoid leaking resources, the application must release ownership of them using the CloseHandle system call when they are no longer needed.

Exporting a Windows handle from a semaphore may have side effects depending on the transference of the specified handle type, as described in Importing Semaphore Payloads.

Valid Usage (Implicit)

  • VUID-vkGetSemaphoreWin32HandleKHR-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkGetSemaphoreWin32HandleKHR-pGetWin32HandleInfo-parameter
    pGetWin32HandleInfo must be a valid pointer to a valid VkSemaphoreGetWin32HandleInfoKHR structure

  • VUID-vkGetSemaphoreWin32HandleKHR-pHandle-parameter
    pHandle must be a valid pointer to a HANDLE value

Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_TOO_MANY_OBJECTS

  • VK_ERROR_OUT_OF_HOST_MEMORY

The VkSemaphoreGetWin32HandleInfoKHR structure is defined as:

// Provided by VK_KHR_external_semaphore_win32
typedef struct VkSemaphoreGetWin32HandleInfoKHR {
    VkStructureType                          sType;
    const void*                              pNext;
    VkSemaphore                              semaphore;
    VkExternalSemaphoreHandleTypeFlagBits    handleType;
} VkSemaphoreGetWin32HandleInfoKHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • semaphore is the semaphore from which state will be exported.

  • handleType is a VkExternalSemaphoreHandleTypeFlagBits value specifying the type of handle requested.

The properties of the handle returned depend on the value of handleType. See VkExternalSemaphoreHandleTypeFlagBits for a description of the properties of the defined external semaphore handle types.

Valid Usage

  • VUID-VkSemaphoreGetWin32HandleInfoKHR-handleType-01126
    handleType must have been included in VkExportSemaphoreCreateInfo::handleTypes when the semaphore’s current payload was created

  • VUID-VkSemaphoreGetWin32HandleInfoKHR-handleType-01127
    If handleType is defined as an NT handle, vkGetSemaphoreWin32HandleKHR must be called no more than once for each valid unique combination of semaphore and handleType

  • VUID-VkSemaphoreGetWin32HandleInfoKHR-semaphore-01128
    semaphore must not currently have its payload replaced by an imported payload as described below in Importing Semaphore Payloads unless that imported payload’s handle type was included in VkExternalSemaphoreProperties::exportFromImportedHandleTypes for handleType

  • VUID-VkSemaphoreGetWin32HandleInfoKHR-handleType-01129
    If handleType refers to a handle type with copy payload transference semantics, as defined below in Importing Semaphore Payloads, there must be no queue waiting on semaphore

  • VUID-VkSemaphoreGetWin32HandleInfoKHR-handleType-01130
    If handleType refers to a handle type with copy payload transference semantics, semaphore must be signaled, or have an associated semaphore signal operation pending execution

  • VUID-VkSemaphoreGetWin32HandleInfoKHR-handleType-01131
    handleType must be defined as an NT handle or a global share handle

Valid Usage (Implicit)

  • VUID-VkSemaphoreGetWin32HandleInfoKHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_SEMAPHORE_GET_WIN32_HANDLE_INFO_KHR

  • VUID-VkSemaphoreGetWin32HandleInfoKHR-pNext-pNext
    pNext must be NULL

  • VUID-VkSemaphoreGetWin32HandleInfoKHR-semaphore-parameter
    semaphore must be a valid VkSemaphore handle

  • VUID-VkSemaphoreGetWin32HandleInfoKHR-handleType-parameter
    handleType must be a valid VkExternalSemaphoreHandleTypeFlagBits value

The VkQueryLowLatencySupportNV structure is defined as:

// Provided by VK_NV_low_latency
typedef struct VkQueryLowLatencySupportNV {
    VkStructureType    sType;
    const void*        pNext;
    void*              pQueriedLowLatencyData;
} VkQueryLowLatencySupportNV;

This structure describes the following feature:

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • pQueriedLowLatencyData is used for NVIDIA Reflex Support.

Valid Usage (Implicit)

  • VUID-VkQueryLowLatencySupportNV-sType-sType
    sType must be VK_STRUCTURE_TYPE_QUERY_LOW_LATENCY_SUPPORT_NV

  • VUID-VkQueryLowLatencySupportNV-pQueriedLowLatencyData-parameter
    pQueriedLowLatencyData must be a pointer value

To export a POSIX file descriptor representing the payload of a semaphore, call:

// Provided by VK_KHR_external_semaphore_fd
VkResult vkGetSemaphoreFdKHR(
    VkDevice                                    device,
    const VkSemaphoreGetFdInfoKHR*              pGetFdInfo,
    int*                                        pFd);

  • device is the logical device that created the semaphore being exported.

  • pGetFdInfo is a pointer to a VkSemaphoreGetFdInfoKHR structure containing parameters of the export operation.

  • pFd will return the file descriptor representing the semaphore payload.

Each call to vkGetSemaphoreFdKHR must create a new file descriptor and transfer ownership of it to the application. To avoid leaking resources, the application must release ownership of the file descriptor when it is no longer needed.

Note

Ownership can be released in many ways. For example, the application can call close() on the file descriptor, or transfer ownership back to Vulkan by using the file descriptor to import a semaphore payload.

Where supported by the operating system, the implementation must set the file descriptor to be closed automatically when an execve system call is made.

Exporting a file descriptor from a semaphore may have side effects depending on the transference of the specified handle type, as described in Importing Semaphore State.

Valid Usage (Implicit)

  • VUID-vkGetSemaphoreFdKHR-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkGetSemaphoreFdKHR-pGetFdInfo-parameter
    pGetFdInfo must be a valid pointer to a valid VkSemaphoreGetFdInfoKHR structure

  • VUID-vkGetSemaphoreFdKHR-pFd-parameter
    pFd must be a valid pointer to an int value

Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_TOO_MANY_OBJECTS

  • VK_ERROR_OUT_OF_HOST_MEMORY

The VkSemaphoreGetFdInfoKHR structure is defined as:

// Provided by VK_KHR_external_semaphore_fd
typedef struct VkSemaphoreGetFdInfoKHR {
    VkStructureType                          sType;
    const void*                              pNext;
    VkSemaphore                              semaphore;
    VkExternalSemaphoreHandleTypeFlagBits    handleType;
} VkSemaphoreGetFdInfoKHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • semaphore is the semaphore from which state will be exported.

  • handleType is a VkExternalSemaphoreHandleTypeFlagBits value specifying the type of handle requested.

The properties of the file descriptor returned depend on the value of handleType. See VkExternalSemaphoreHandleTypeFlagBits for a description of the properties of the defined external semaphore handle types.

Valid Usage

  • VUID-VkSemaphoreGetFdInfoKHR-handleType-01132
    handleType must have been included in VkExportSemaphoreCreateInfo::handleTypes when semaphore’s current payload was created

  • VUID-VkSemaphoreGetFdInfoKHR-semaphore-01133
    semaphore must not currently have its payload replaced by an imported payload as described below in Importing Semaphore Payloads unless that imported payload’s handle type was included in VkExternalSemaphoreProperties::exportFromImportedHandleTypes for handleType

  • VUID-VkSemaphoreGetFdInfoKHR-handleType-01134
    If handleType refers to a handle type with copy payload transference semantics, as defined below in Importing Semaphore Payloads, there must be no queue waiting on semaphore

  • VUID-VkSemaphoreGetFdInfoKHR-handleType-01135
    If handleType refers to a handle type with copy payload transference semantics, semaphore must be signaled, or have an associated semaphore signal operation pending execution

  • VUID-VkSemaphoreGetFdInfoKHR-handleType-01136
    handleType must be defined as a POSIX file descriptor handle

  • VUID-VkSemaphoreGetFdInfoKHR-handleType-03253
    If handleType refers to a handle type with copy payload transference semantics, semaphore must have been created with a VkSemaphoreType of VK_SEMAPHORE_TYPE_BINARY

  • VUID-VkSemaphoreGetFdInfoKHR-handleType-03254
    If handleType refers to a handle type with copy payload transference semantics, semaphore must have an associated semaphore signal operation that has been submitted for execution and any semaphore signal operations on which it depends must have also been submitted for execution

Valid Usage (Implicit)

  • VUID-VkSemaphoreGetFdInfoKHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_SEMAPHORE_GET_FD_INFO_KHR

  • VUID-VkSemaphoreGetFdInfoKHR-pNext-pNext
    pNext must be NULL

  • VUID-VkSemaphoreGetFdInfoKHR-semaphore-parameter
    semaphore must be a valid VkSemaphore handle

  • VUID-VkSemaphoreGetFdInfoKHR-handleType-parameter
    handleType must be a valid VkExternalSemaphoreHandleTypeFlagBits value

To export a Zircon event handle representing the payload of a semaphore, call:

// Provided by VK_FUCHSIA_external_semaphore
VkResult vkGetSemaphoreZirconHandleFUCHSIA(
    VkDevice                                    device,
    const VkSemaphoreGetZirconHandleInfoFUCHSIA* pGetZirconHandleInfo,
    zx_handle_t*                                pZirconHandle);

  • device is the logical device that created the semaphore being exported.

  • pGetZirconHandleInfo is a pointer to a VkSemaphoreGetZirconHandleInfoFUCHSIA structure containing parameters of the export operation.

  • pZirconHandle will return the Zircon event handle representing the semaphore payload.

Each call to vkGetSemaphoreZirconHandleFUCHSIA must create a Zircon event handle and transfer ownership of it to the application. To avoid leaking resources, the application must release ownership of the Zircon event handle when it is no longer needed.

Note

Ownership can be released in many ways. For example, the application can call zx_handle_close() on the file descriptor, or transfer ownership back to Vulkan by using the file descriptor to import a semaphore payload.

Exporting a Zircon event handle from a semaphore may have side effects depending on the transference of the specified handle type, as described in Importing Semaphore State.

Valid Usage (Implicit)

  • VUID-vkGetSemaphoreZirconHandleFUCHSIA-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkGetSemaphoreZirconHandleFUCHSIA-pGetZirconHandleInfo-parameter
    pGetZirconHandleInfo must be a valid pointer to a valid VkSemaphoreGetZirconHandleInfoFUCHSIA structure

  • VUID-vkGetSemaphoreZirconHandleFUCHSIA-pZirconHandle-parameter
    pZirconHandle must be a valid pointer to a zx_handle_t value

Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_TOO_MANY_OBJECTS

  • VK_ERROR_OUT_OF_HOST_MEMORY

The VkSemaphoreGetZirconHandleInfoFUCHSIA structure is defined as:

// Provided by VK_FUCHSIA_external_semaphore
typedef struct VkSemaphoreGetZirconHandleInfoFUCHSIA {
    VkStructureType                          sType;
    const void*                              pNext;
    VkSemaphore                              semaphore;
    VkExternalSemaphoreHandleTypeFlagBits    handleType;
} VkSemaphoreGetZirconHandleInfoFUCHSIA;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • semaphore is the semaphore from which state will be exported.

  • handleType is a VkExternalSemaphoreHandleTypeFlagBits value specifying the type of handle requested.

The properties of the Zircon event handle returned depend on the value of handleType. See VkExternalSemaphoreHandleTypeFlagBits for a description of the properties of the defined external semaphore handle types.

Valid Usage

  • VUID-VkSemaphoreGetZirconHandleInfoFUCHSIA-handleType-04758
    handleType must have been included in VkExportSemaphoreCreateInfo::handleTypes when semaphore’s current payload was created

  • VUID-VkSemaphoreGetZirconHandleInfoFUCHSIA-semaphore-04759
    semaphore must not currently have its payload replaced by an imported payload as described below in Importing Semaphore Payloads unless that imported payload’s handle type was included in VkExternalSemaphoreProperties::exportFromImportedHandleTypes for handleType

  • VUID-VkSemaphoreGetZirconHandleInfoFUCHSIA-handleType-04760
    If handleType refers to a handle type with copy payload transference semantics, as defined below in Importing Semaphore Payloads, there must be no queue waiting on semaphore

  • VUID-VkSemaphoreGetZirconHandleInfoFUCHSIA-handleType-04761
    If handleType refers to a handle type with copy payload transference semantics, semaphore must be signaled, or have an associated semaphore signal operation pending execution

  • VUID-VkSemaphoreGetZirconHandleInfoFUCHSIA-handleType-04762
    handleType must be defined as a Zircon event handle

  • VUID-VkSemaphoreGetZirconHandleInfoFUCHSIA-semaphore-04763
    semaphore must have been created with a VkSemaphoreType of VK_SEMAPHORE_TYPE_BINARY

Valid Usage (Implicit)

  • VUID-VkSemaphoreGetZirconHandleInfoFUCHSIA-sType-sType
    sType must be VK_STRUCTURE_TYPE_SEMAPHORE_GET_ZIRCON_HANDLE_INFO_FUCHSIA

  • VUID-VkSemaphoreGetZirconHandleInfoFUCHSIA-pNext-pNext
    pNext must be NULL

  • VUID-VkSemaphoreGetZirconHandleInfoFUCHSIA-semaphore-parameter
    semaphore must be a valid VkSemaphore handle

  • VUID-VkSemaphoreGetZirconHandleInfoFUCHSIA-handleType-parameter
    handleType must be a valid VkExternalSemaphoreHandleTypeFlagBits value

To destroy a semaphore, call:

// Provided by VK_VERSION_1_0
void vkDestroySemaphore(
    VkDevice                                    device,
    VkSemaphore                                 semaphore,
    const VkAllocationCallbacks*                pAllocator);

  • device is the logical device that destroys the semaphore.

  • semaphore is the handle of the semaphore to destroy.

  • pAllocator controls host memory allocation as described in the Memory Allocation chapter.

Valid Usage

  • VUID-vkDestroySemaphore-semaphore-05149
    All submitted batches that refer to semaphore must have completed execution

  • VUID-vkDestroySemaphore-semaphore-01138
    If VkAllocationCallbacks were provided when semaphore was created, a compatible set of callbacks must be provided here

  • VUID-vkDestroySemaphore-semaphore-01139
    If no VkAllocationCallbacks were provided when semaphore was created, pAllocator must be NULL

Valid Usage (Implicit)

  • VUID-vkDestroySemaphore-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkDestroySemaphore-semaphore-parameter
    If semaphore is not VK_NULL_HANDLE, semaphore must be a valid VkSemaphore handle

  • VUID-vkDestroySemaphore-pAllocator-parameter
    If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure

  • VUID-vkDestroySemaphore-semaphore-parent
    If semaphore is a valid handle, it must have been created, allocated, or retrieved from device

Host Synchronization

  • Host access to semaphore must be externally synchronized

7.4.1. Semaphore Signaling

When a batch is submitted to a queue via a queue submission, and it includes semaphores to be signaled, it defines a memory dependency on the batch, and defines semaphore signal operations which set the semaphores to the signaled state.

In case of semaphores created with a VkSemaphoreType of VK_SEMAPHORE_TYPE_TIMELINE the semaphore is considered signaled with respect to the counter value set to be signaled as specified in VkTimelineSemaphoreSubmitInfo or VkSemaphoreSignalInfo.

The first synchronization scope includes every command submitted in the same batch. In the case of vkQueueSubmit2, the first synchronization scope is limited to the pipeline stage specified by VkSemaphoreSubmitInfo::stageMask. Semaphore signal operations that are defined by vkQueueSubmit or vkQueueSubmit2 additionally include all commands that occur earlier in submission order. Semaphore signal operations that are defined by vkQueueSubmit or vkQueueSubmit2 or vkQueueBindSparse additionally include in the first synchronization scope any semaphore and fence signal operations that occur earlier in signal operation order.

The second synchronization scope includes only the semaphore signal operation.

The first access scope includes all memory access performed by the device.

The second access scope is empty.

7.4.2. Semaphore Waiting

When a batch is submitted to a queue via a queue submission, and it includes semaphores to be waited on, it defines a memory dependency between prior semaphore signal operations and the batch, and defines semaphore wait operations.

Such semaphore wait operations set the semaphores created with a VkSemaphoreType of VK_SEMAPHORE_TYPE_BINARY to the unsignaled state. In case of semaphores created with a VkSemaphoreType of VK_SEMAPHORE_TYPE_TIMELINE a prior semaphore signal operation defines a memory dependency with a semaphore wait operation if the value the semaphore is signaled with is greater than or equal to the value the semaphore is waited with, thus the semaphore will continue to be considered signaled with respect to the counter value waited on as specified in VkTimelineSemaphoreSubmitInfo.

The first synchronization scope includes one semaphore signal operation for each semaphore waited on by this batch. The specific signal operation waited on for each semaphore must meet the following criteria:

  • for binary semaphores, the signal operation is either earlier in submission order on the same queue, or is submitted by a command whose host operation happens-before this batch is submitted on the host

  • for binary semaphores, no wait operation exists that happens-after the signal operation and happens-before this wait operation

  • the signal operation is not guaranteed to happen-after the semaphore wait operation in this batch

  • for timeline semaphores, the signal value is greater than or equal to the wait value

If multiple semaphore signal operations meet these criteria, any of those operations may be included in the first synchronization scope. When waiting on a binary semaphore, applications must ensure that exactly one semaphore signal operation meets these criteria.

The second synchronization scope includes every command submitted in the same batch. In the case of vkQueueSubmit, the second synchronization scope is limited to operations on the pipeline stages determined by the destination stage mask specified by the corresponding element of pWaitDstStageMask. In the case of vkQueueSubmit2, the second synchronization scope is limited to the pipeline stage specified by VkSemaphoreSubmitInfo::stageMask. Also, in the case of either vkQueueSubmit2 or vkQueueSubmit, the second synchronization scope additionally includes all commands that occur later in submission order.

The first access scope is empty.

The second access scope includes all memory access performed by the device.

The semaphore wait operation happens-after the first set of operations in the execution dependency, and happens-before the second set of operations in the execution dependency.

Note

Unlike timeline semaphores, fences or events, waiting for a binary semaphore also unsignals that semaphore when the wait completes. Applications must ensure that between two such wait operations, the semaphore is signaled again, with execution dependencies used to ensure these occur in order. Binary semaphore waits and signals should thus occur in discrete 1:1 pairs.
Note

A common scenario for using pWaitDstStageMask with values other than VK_PIPELINE_STAGE_ALL_COMMANDS_BIT is when synchronizing a window system presentation operation against subsequent command buffers which render the next frame. In this case, a presentation image must not be overwritten until the presentation operation completes, but other pipeline stages can execute without waiting. A mask of VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT prevents subsequent color attachment writes from executing until the semaphore signals. Some implementations may be able to execute transfer operations and/or pre-rasterization work before the semaphore is signaled.

If an image layout transition needs to be performed on a presentable image before it is used in a framebuffer, that can be performed as the first operation submitted to the queue after acquiring the image, and should not prevent other work from overlapping with the presentation operation. For example, a VkImageMemoryBarrier could use:

  • srcStageMask = VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT

  • srcAccessMask = 0

  • dstStageMask = VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT

  • dstAccessMask = VK_ACCESS_COLOR_ATTACHMENT_READ_BIT | VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT.

  • oldLayout = VK_IMAGE_LAYOUT_PRESENT_SRC_KHR

  • newLayout = VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL

Alternatively, oldLayout can be VK_IMAGE_LAYOUT_UNDEFINED, if the image’s contents need not be preserved.

This barrier accomplishes a dependency chain between previous presentation operations and subsequent color attachment output operations, with the layout transition performed in between, and does not introduce a dependency between previous work and any pre-rasterization shader stages. More precisely, the semaphore signals after the presentation operation completes, the semaphore wait stalls the VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT stage, and there is a dependency from that same stage to itself with the layout transition performed in between.

7.4.3. Semaphore State Requirements for Wait Operations

Before waiting on a semaphore, the application must ensure the semaphore is in a valid state for a wait operation. Specifically, when a semaphore wait operation is submitted to a queue:

  • A binary semaphore must be signaled, or have an associated semaphore signal operation that is pending execution.

  • Any semaphore signal operations on which the pending binary semaphore signal operation depends must also be completed or pending execution.

  • There must be no other queue waiting on the same binary semaphore when the operation executes.

7.4.4. Host Operations on Semaphores

In addition to semaphore signal operations and semaphore wait operations submitted to device queues, timeline semaphores support the following host operations:

  • Query the current counter value of the semaphore using the vkGetSemaphoreCounterValue command.

  • Wait for a set of semaphores to reach particular counter values using the vkWaitSemaphores command.

  • Signal the semaphore with a particular counter value from the host using the vkSignalSemaphore command.

To query the current counter value of a semaphore created with a VkSemaphoreType of VK_SEMAPHORE_TYPE_TIMELINE from the host, call:

// Provided by VK_VERSION_1_2
VkResult vkGetSemaphoreCounterValue(
    VkDevice                                    device,
    VkSemaphore                                 semaphore,
    uint64_t*                                   pValue);

or the equivalent command

// Provided by VK_KHR_timeline_semaphore
VkResult vkGetSemaphoreCounterValueKHR(
    VkDevice                                    device,
    VkSemaphore                                 semaphore,
    uint64_t*                                   pValue);

  • device is the logical device that owns the semaphore.

  • semaphore is the handle of the semaphore to query.

  • pValue is a pointer to a 64-bit integer value in which the current counter value of the semaphore is returned.

Note

If a queue submission command is pending execution, then the value returned by this command may immediately be out of date.
Valid Usage

  • VUID-vkGetSemaphoreCounterValue-semaphore-03255
    semaphore must have been created with a VkSemaphoreType of VK_SEMAPHORE_TYPE_TIMELINE

Valid Usage (Implicit)

  • VUID-vkGetSemaphoreCounterValue-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkGetSemaphoreCounterValue-semaphore-parameter
    semaphore must be a valid VkSemaphore handle

  • VUID-vkGetSemaphoreCounterValue-pValue-parameter
    pValue must be a valid pointer to a uint64_t value

  • VUID-vkGetSemaphoreCounterValue-semaphore-parent
    semaphore must have been created, allocated, or retrieved from device

Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

  • VK_ERROR_DEVICE_LOST

To wait for a set of semaphores created with a VkSemaphoreType of VK_SEMAPHORE_TYPE_TIMELINE to reach particular counter values on the host, call:

// Provided by VK_VERSION_1_2
VkResult vkWaitSemaphores(
    VkDevice                                    device,
    const VkSemaphoreWaitInfo*                  pWaitInfo,
    uint64_t                                    timeout);

or the equivalent command

// Provided by VK_KHR_timeline_semaphore
VkResult vkWaitSemaphoresKHR(
    VkDevice                                    device,
    const VkSemaphoreWaitInfo*                  pWaitInfo,
    uint64_t                                    timeout);

  • device is the logical device that owns the semaphores.

  • pWaitInfo is a pointer to a VkSemaphoreWaitInfo structure containing information about the wait condition.

  • timeout is the timeout period in units of nanoseconds. timeout is adjusted to the closest value allowed by the implementation-dependent timeout accuracy, which may be substantially longer than one nanosecond, and may be longer than the requested period.

If the condition is satisfied when vkWaitSemaphores is called, then vkWaitSemaphores returns immediately. If the condition is not satisfied at the time vkWaitSemaphores is called, then vkWaitSemaphores will block and wait until the condition is satisfied or the timeout has expired, whichever is sooner.

If timeout is zero, then vkWaitSemaphores does not wait, but simply returns information about the current state of the semaphores. VK_TIMEOUT will be returned in this case if the condition is not satisfied, even though no actual wait was performed.

If the condition is satisfied before the timeout has expired, vkWaitSemaphores returns VK_SUCCESS. Otherwise, vkWaitSemaphores returns VK_TIMEOUT after the timeout has expired.

If device loss occurs (see Lost Device) before the timeout has expired, vkWaitSemaphores must return in finite time with either VK_SUCCESS or VK_ERROR_DEVICE_LOST.

Valid Usage (Implicit)

  • VUID-vkWaitSemaphores-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkWaitSemaphores-pWaitInfo-parameter
    pWaitInfo must be a valid pointer to a valid VkSemaphoreWaitInfo structure

Return Codes
Success

  • VK_SUCCESS

  • VK_TIMEOUT

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

  • VK_ERROR_DEVICE_LOST

The VkSemaphoreWaitInfo structure is defined as:

// Provided by VK_VERSION_1_2
typedef struct VkSemaphoreWaitInfo {
    VkStructureType         sType;
    const void*             pNext;
    VkSemaphoreWaitFlags    flags;
    uint32_t                semaphoreCount;
    const VkSemaphore*      pSemaphores;
    const uint64_t*         pValues;
} VkSemaphoreWaitInfo;

or the equivalent

// Provided by VK_KHR_timeline_semaphore
typedef VkSemaphoreWaitInfo VkSemaphoreWaitInfoKHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • flags is a bitmask of VkSemaphoreWaitFlagBits specifying additional parameters for the semaphore wait operation.

  • semaphoreCount is the number of semaphores to wait on.

  • pSemaphores is a pointer to an array of semaphoreCount semaphore handles to wait on.

  • pValues is a pointer to an array of semaphoreCount timeline semaphore values.

Valid Usage

  • VUID-VkSemaphoreWaitInfo-pSemaphores-03256
    All of the elements of pSemaphores must reference a semaphore that was created with a VkSemaphoreType of VK_SEMAPHORE_TYPE_TIMELINE

Valid Usage (Implicit)

  • VUID-VkSemaphoreWaitInfo-sType-sType
    sType must be VK_STRUCTURE_TYPE_SEMAPHORE_WAIT_INFO

  • VUID-VkSemaphoreWaitInfo-pNext-pNext
    pNext must be NULL

  • VUID-VkSemaphoreWaitInfo-flags-parameter
    flags must be a valid combination of VkSemaphoreWaitFlagBits values

  • VUID-VkSemaphoreWaitInfo-pSemaphores-parameter
    pSemaphores must be a valid pointer to an array of semaphoreCount valid VkSemaphore handles

  • VUID-VkSemaphoreWaitInfo-pValues-parameter
    pValues must be a valid pointer to an array of semaphoreCount uint64_t values

  • VUID-VkSemaphoreWaitInfo-semaphoreCount-arraylength
    semaphoreCount must be greater than 0

Bits which can be set in VkSemaphoreWaitInfo::flags, specifying additional parameters of a semaphore wait operation, are:

// Provided by VK_VERSION_1_2
typedef enum VkSemaphoreWaitFlagBits {
    VK_SEMAPHORE_WAIT_ANY_BIT = 0x00000001,
  // Provided by VK_KHR_timeline_semaphore
    VK_SEMAPHORE_WAIT_ANY_BIT_KHR = VK_SEMAPHORE_WAIT_ANY_BIT,
} VkSemaphoreWaitFlagBits;

or the equivalent

// Provided by VK_KHR_timeline_semaphore
typedef VkSemaphoreWaitFlagBits VkSemaphoreWaitFlagBitsKHR;

  • VK_SEMAPHORE_WAIT_ANY_BIT specifies that the semaphore wait condition is that at least one of the semaphores in VkSemaphoreWaitInfo::pSemaphores has reached the value specified by the corresponding element of VkSemaphoreWaitInfo::pValues. If VK_SEMAPHORE_WAIT_ANY_BIT is not set, the semaphore wait condition is that all of the semaphores in VkSemaphoreWaitInfo::pSemaphores have reached the value specified by the corresponding element of VkSemaphoreWaitInfo::pValues.

// Provided by VK_VERSION_1_2
typedef VkFlags VkSemaphoreWaitFlags;

or the equivalent

// Provided by VK_KHR_timeline_semaphore
typedef VkSemaphoreWaitFlags VkSemaphoreWaitFlagsKHR;

VkSemaphoreWaitFlags is a bitmask type for setting a mask of zero or more VkSemaphoreWaitFlagBits.

To signal a semaphore created with a VkSemaphoreType of VK_SEMAPHORE_TYPE_TIMELINE with a particular counter value, on the host, call:

// Provided by VK_VERSION_1_2
VkResult vkSignalSemaphore(
    VkDevice                                    device,
    const VkSemaphoreSignalInfo*                pSignalInfo);

or the equivalent command

// Provided by VK_KHR_timeline_semaphore
VkResult vkSignalSemaphoreKHR(
    VkDevice                                    device,
    const VkSemaphoreSignalInfo*                pSignalInfo);

  • device is the logical device that owns the semaphore.

  • pSignalInfo is a pointer to a VkSemaphoreSignalInfo structure containing information about the signal operation.

When vkSignalSemaphore is executed on the host, it defines and immediately executes a semaphore signal operation which sets the timeline semaphore to the given value.

The first synchronization scope is defined by the host execution model, but includes execution of vkSignalSemaphore on the host and anything that happened-before it.

The second synchronization scope is empty.

Valid Usage (Implicit)

  • VUID-vkSignalSemaphore-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkSignalSemaphore-pSignalInfo-parameter
    pSignalInfo must be a valid pointer to a valid VkSemaphoreSignalInfo structure

Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

The VkSemaphoreSignalInfo structure is defined as:

// Provided by VK_VERSION_1_2
typedef struct VkSemaphoreSignalInfo {
    VkStructureType    sType;
    const void*        pNext;
    VkSemaphore        semaphore;
    uint64_t           value;
} VkSemaphoreSignalInfo;

or the equivalent

// Provided by VK_KHR_timeline_semaphore
typedef VkSemaphoreSignalInfo VkSemaphoreSignalInfoKHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • semaphore is the handle of the semaphore to signal.

  • value is the value to signal.

Valid Usage

  • VUID-VkSemaphoreSignalInfo-semaphore-03257
    semaphore must have been created with a VkSemaphoreType of VK_SEMAPHORE_TYPE_TIMELINE

  • VUID-VkSemaphoreSignalInfo-value-03258
    value must have a value greater than the current value of the semaphore

  • VUID-VkSemaphoreSignalInfo-value-03259
    value must be less than the value of any pending semaphore signal operations

  • VUID-VkSemaphoreSignalInfo-value-03260
    value must have a value which does not differ from the current value of the semaphore or the value of any outstanding semaphore wait or signal operation on semaphore by more than maxTimelineSemaphoreValueDifference

Valid Usage (Implicit)

  • VUID-VkSemaphoreSignalInfo-sType-sType
    sType must be VK_STRUCTURE_TYPE_SEMAPHORE_SIGNAL_INFO

  • VUID-VkSemaphoreSignalInfo-pNext-pNext
    pNext must be NULL

  • VUID-VkSemaphoreSignalInfo-semaphore-parameter
    semaphore must be a valid VkSemaphore handle

7.4.5. Importing Semaphore Payloads

Applications can import a semaphore payload into an existing semaphore using an external semaphore handle. The effects of the import operation will be either temporary or permanent, as specified by the application. If the import is temporary, the implementation must restore the semaphore to its prior permanent state after submitting the next semaphore wait operation. Performing a subsequent temporary import on a semaphore before performing a semaphore wait has no effect on this requirement; the next wait submitted on the semaphore must still restore its last permanent state. A permanent payload import behaves as if the target semaphore was destroyed, and a new semaphore was created with the same handle but the imported payload. Because importing a semaphore payload temporarily or permanently detaches the existing payload from a semaphore, similar usage restrictions to those applied to vkDestroySemaphore are applied to any command that imports a semaphore payload. Which of these import types is used is referred to as the import operation’s permanence. Each handle type supports either one or both types of permanence.

The implementation must perform the import operation by either referencing or copying the payload referred to by the specified external semaphore handle, depending on the handle’s type. The import method used is referred to as the handle type’s transference. When using handle types with reference transference, importing a payload to a semaphore adds the semaphore to the set of all semaphores sharing that payload. This set includes the semaphore from which the payload was exported. Semaphore signaling and waiting operations performed on any semaphore in the set must behave as if the set were a single semaphore. Importing a payload using handle types with copy transference creates a duplicate copy of the payload at the time of import, but makes no further reference to it. Semaphore signaling and waiting operations performed on the target of copy imports must not affect any other semaphore or payload.

Export operations have the same transference as the specified handle type’s import operations. Additionally, exporting a semaphore payload to a handle with copy transference has the same side effects on the source semaphore’s payload as executing a semaphore wait operation. If the semaphore was using a temporarily imported payload, the semaphore’s prior permanent payload will be restored.

Note

The permanence and transference of handle types can be found in:

External synchronization allows implementations to modify an object’s internal state, i.e. payload, without internal synchronization. However, for semaphores sharing a payload across processes, satisfying the external synchronization requirements of VkSemaphore parameters as if all semaphores in the set were the same object is sometimes infeasible. Satisfying the wait operation state requirements would similarly require impractical coordination or levels of trust between processes. Therefore, these constraints only apply to a specific semaphore handle, not to its payload. For distinct semaphore objects which share a payload, if the semaphores are passed to separate queue submission commands concurrently, behavior will be as if the commands were called in an arbitrary sequential order. If the wait operation state requirements are violated for the shared payload by a queue submission command, or if a signal operation is queued for a shared payload that is already signaled or has a pending signal operation, effects must be limited to one or more of the following:

  • Returning VK_ERROR_INITIALIZATION_FAILED from the command which resulted in the violation.

  • Losing the logical device on which the violation occurred immediately or at a future time, resulting in a VK_ERROR_DEVICE_LOST error from subsequent commands, including the one causing the violation.

  • Continuing execution of the violating command or operation as if the semaphore wait completed successfully after an implementation-dependent timeout. In this case, the state of the payload becomes undefined, and future operations on semaphores sharing the payload will be subject to these same rules. The semaphore must be destroyed or have its payload replaced by an import operation to again have a well-defined state.

Note

These rules allow processes to synchronize access to shared memory without trusting each other. However, such processes must still be cautious not to use the shared semaphore for more than synchronizing access to the shared memory. For example, a process should not use a shared semaphore as part of an execution dependency chain that, when complete, leads to objects being destroyed, if it does not trust other processes sharing the semaphore payload.

When a semaphore is using an imported payload, its VkExportSemaphoreCreateInfo::handleTypes value is specified when creating the semaphore from which the payload was exported, rather than specified when creating the semaphore. Additionally, VkExternalSemaphoreProperties::exportFromImportedHandleTypes restricts which handle types can be exported from such a semaphore based on the specific handle type used to import the current payload. Passing a semaphore to vkAcquireNextImageKHR is equivalent to temporarily importing a semaphore payload to that semaphore.

Note

Because the exportable handle types of an imported semaphore correspond to its current imported payload, and vkAcquireNextImageKHR behaves the same as a temporary import operation for which the source semaphore is opaque to the application, applications have no way of determining whether any external handle types can be exported from a semaphore in this state. Therefore, applications must not attempt to export external handles from semaphores using a temporarily imported payload from vkAcquireNextImageKHR.

When importing a semaphore payload, it is the responsibility of the application to ensure the external handles meet all valid usage requirements. However, implementations must perform sufficient validation of external handles to ensure that the operation results in a valid semaphore which will not cause program termination, device loss, queue stalls, or corruption of other resources when used as allowed according to its import parameters, and excepting those side effects allowed for violations of the valid semaphore state for wait operations rules. If the external handle provided does not meet these requirements, the implementation must fail the semaphore payload import operation with the error code VK_ERROR_INVALID_EXTERNAL_HANDLE.

In addition, when importing a semaphore payload that is not compatible with the payload type corresponding to the VkSemaphoreType the semaphore was created with, the implementation may fail the semaphore payload import operation with the error code VK_ERROR_INVALID_EXTERNAL_HANDLE.

Note

As the introduction of the external semaphore handle type VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_D3D12_FENCE_BIT predates that of timeline semaphores, support for importing semaphore payloads from external handles of that type into semaphores created (implicitly or explicitly) with a VkSemaphoreType of VK_SEMAPHORE_TYPE_BINARY is preserved for backwards compatibility. However, applications should prefer importing such handle types into semaphores created with a VkSemaphoreType of VK_SEMAPHORE_TYPE_TIMELINE.

To import a semaphore payload from a Windows handle, call:

// Provided by VK_KHR_external_semaphore_win32
VkResult vkImportSemaphoreWin32HandleKHR(
    VkDevice                                    device,
    const VkImportSemaphoreWin32HandleInfoKHR*  pImportSemaphoreWin32HandleInfo);

  • device is the logical device that created the semaphore.

  • pImportSemaphoreWin32HandleInfo is a pointer to a VkImportSemaphoreWin32HandleInfoKHR structure specifying the semaphore and import parameters.

Importing a semaphore payload from Windows handles does not transfer ownership of the handle to the Vulkan implementation. For handle types defined as NT handles, the application must release ownership using the CloseHandle system call when the handle is no longer needed.

Applications can import the same semaphore payload into multiple instances of Vulkan, into the same instance from which it was exported, and multiple times into a given Vulkan instance.

Valid Usage (Implicit)

  • VUID-vkImportSemaphoreWin32HandleKHR-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkImportSemaphoreWin32HandleKHR-pImportSemaphoreWin32HandleInfo-parameter
    pImportSemaphoreWin32HandleInfo must be a valid pointer to a valid VkImportSemaphoreWin32HandleInfoKHR structure

Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_INVALID_EXTERNAL_HANDLE

The VkImportSemaphoreWin32HandleInfoKHR structure is defined as:

// Provided by VK_KHR_external_semaphore_win32
typedef struct VkImportSemaphoreWin32HandleInfoKHR {
    VkStructureType                          sType;
    const void*                              pNext;
    VkSemaphore                              semaphore;
    VkSemaphoreImportFlags                   flags;
    VkExternalSemaphoreHandleTypeFlagBits    handleType;
    HANDLE                                   handle;
    LPCWSTR                                  name;
} VkImportSemaphoreWin32HandleInfoKHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • semaphore is the semaphore into which the payload will be imported.

  • flags is a bitmask of VkSemaphoreImportFlagBits specifying additional parameters for the semaphore payload import operation.

  • handleType is a VkExternalSemaphoreHandleTypeFlagBits value specifying the type of handle.

  • handle is NULL or the external handle to import.

  • name is NULL or a null-terminated UTF-16 string naming the underlying synchronization primitive to import.

The handle types supported by handleType are:

Table 8. Handle Types Supported by VkImportSemaphoreWin32HandleInfoKHR
Handle Type Transference Permanence Supported

VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32_BIT

Reference

Temporary,Permanent

VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32_KMT_BIT

Reference

Temporary,Permanent

VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_D3D12_FENCE_BIT

Reference

Temporary,Permanent
Valid Usage

  • VUID-VkImportSemaphoreWin32HandleInfoKHR-handleType-01140
    handleType must be a value included in the Handle Types Supported by VkImportSemaphoreWin32HandleInfoKHR table

  • VUID-VkImportSemaphoreWin32HandleInfoKHR-handleType-01466
    If handleType is not VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32_BIT or VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_D3D12_FENCE_BIT, name must be NULL

  • VUID-VkImportSemaphoreWin32HandleInfoKHR-handleType-01467
    If handle is NULL, name must name a valid synchronization primitive of the type specified by handleType

  • VUID-VkImportSemaphoreWin32HandleInfoKHR-handleType-01468
    If name is NULL, handle must be a valid handle of the type specified by handleType

  • VUID-VkImportSemaphoreWin32HandleInfoKHR-handle-01469
    If handle is not NULL, name must be NULL

  • VUID-VkImportSemaphoreWin32HandleInfoKHR-handle-01542
    If handle is not NULL, it must obey any requirements listed for handleType in external semaphore handle types compatibility

  • VUID-VkImportSemaphoreWin32HandleInfoKHR-name-01543
    If name is not NULL, it must obey any requirements listed for handleType in external semaphore handle types compatibility

  • VUID-VkImportSemaphoreWin32HandleInfoKHR-handleType-03261
    If handleType is VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32_BIT or VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32_KMT_BIT, the VkSemaphoreCreateInfo::flags field must match that of the semaphore from which handle or name was exported

  • VUID-VkImportSemaphoreWin32HandleInfoKHR-handleType-03262
    If handleType is VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32_BIT or VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32_KMT_BIT, the VkSemaphoreTypeCreateInfo::semaphoreType field must match that of the semaphore from which handle or name was exported

  • VUID-VkImportSemaphoreWin32HandleInfoKHR-flags-03322
    If flags contains VK_SEMAPHORE_IMPORT_TEMPORARY_BIT, the VkSemaphoreTypeCreateInfo::semaphoreType field of the semaphore from which handle or name was exported must not be VK_SEMAPHORE_TYPE_TIMELINE

Valid Usage (Implicit)

  • VUID-VkImportSemaphoreWin32HandleInfoKHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_IMPORT_SEMAPHORE_WIN32_HANDLE_INFO_KHR

  • VUID-VkImportSemaphoreWin32HandleInfoKHR-pNext-pNext
    pNext must be NULL

  • VUID-VkImportSemaphoreWin32HandleInfoKHR-semaphore-parameter
    semaphore must be a valid VkSemaphore handle

  • VUID-VkImportSemaphoreWin32HandleInfoKHR-flags-parameter
    flags must be a valid combination of VkSemaphoreImportFlagBits values

Host Synchronization

  • Host access to semaphore must be externally synchronized

To import a semaphore payload from a POSIX file descriptor, call:

// Provided by VK_KHR_external_semaphore_fd
VkResult vkImportSemaphoreFdKHR(
    VkDevice                                    device,
    const VkImportSemaphoreFdInfoKHR*           pImportSemaphoreFdInfo);

  • device is the logical device that created the semaphore.

  • pImportSemaphoreFdInfo is a pointer to a VkImportSemaphoreFdInfoKHR structure specifying the semaphore and import parameters.

Importing a semaphore payload from a file descriptor transfers ownership of the file descriptor from the application to the Vulkan implementation. The application must not perform any operations on the file descriptor after a successful import.

Applications can import the same semaphore payload into multiple instances of Vulkan, into the same instance from which it was exported, and multiple times into a given Vulkan instance.

Valid Usage

  • VUID-vkImportSemaphoreFdKHR-semaphore-01142
    semaphore must not be associated with any queue command that has not yet completed execution on that queue

Valid Usage (Implicit)

  • VUID-vkImportSemaphoreFdKHR-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkImportSemaphoreFdKHR-pImportSemaphoreFdInfo-parameter
    pImportSemaphoreFdInfo must be a valid pointer to a valid VkImportSemaphoreFdInfoKHR structure

Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_INVALID_EXTERNAL_HANDLE

The VkImportSemaphoreFdInfoKHR structure is defined as:

// Provided by VK_KHR_external_semaphore_fd
typedef struct VkImportSemaphoreFdInfoKHR {
    VkStructureType                          sType;
    const void*                              pNext;
    VkSemaphore                              semaphore;
    VkSemaphoreImportFlags                   flags;
    VkExternalSemaphoreHandleTypeFlagBits    handleType;
    int                                      fd;
} VkImportSemaphoreFdInfoKHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • semaphore is the semaphore into which the payload will be imported.

  • flags is a bitmask of VkSemaphoreImportFlagBits specifying additional parameters for the semaphore payload import operation.

  • handleType is a VkExternalSemaphoreHandleTypeFlagBits value specifying the type of fd.

  • fd is the external handle to import.

The handle types supported by handleType are:

Table 9. Handle Types Supported by VkImportSemaphoreFdInfoKHR
Handle Type Transference Permanence Supported

VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_FD_BIT

Reference

Temporary,Permanent

VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_SYNC_FD_BIT

Copy

Temporary
Valid Usage

  • VUID-VkImportSemaphoreFdInfoKHR-handleType-01143
    handleType must be a value included in the Handle Types Supported by VkImportSemaphoreFdInfoKHR table

  • VUID-VkImportSemaphoreFdInfoKHR-fd-01544
    fd must obey any requirements listed for handleType in external semaphore handle types compatibility

  • VUID-VkImportSemaphoreFdInfoKHR-handleType-03263
    If handleType is VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_FD_BIT, the VkSemaphoreCreateInfo::flags field must match that of the semaphore from which fd was exported

  • VUID-VkImportSemaphoreFdInfoKHR-handleType-07307
    If handleType refers to a handle type with copy payload transference semantics, flags must contain VK_SEMAPHORE_IMPORT_TEMPORARY_BIT

  • VUID-VkImportSemaphoreFdInfoKHR-handleType-03264
    If handleType is VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_FD_BIT, the VkSemaphoreTypeCreateInfo::semaphoreType field must match that of the semaphore from which fd was exported

  • VUID-VkImportSemaphoreFdInfoKHR-flags-03323
    If flags contains VK_SEMAPHORE_IMPORT_TEMPORARY_BIT, the VkSemaphoreTypeCreateInfo::semaphoreType field of the semaphore from which fd was exported must not be VK_SEMAPHORE_TYPE_TIMELINE

If handleType is VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_SYNC_FD_BIT, the special value -1 for fd is treated like a valid sync file descriptor referring to an object that has already signaled. The import operation will succeed and the VkSemaphore will have a temporarily imported payload as if a valid file descriptor had been provided.

Note

This special behavior for importing an invalid sync file descriptor allows easier interoperability with other system APIs which use the convention that an invalid sync file descriptor represents work that has already completed and does not need to be waited for. It is consistent with the option for implementations to return a -1 file descriptor when exporting a VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_SYNC_FD_BIT from a VkSemaphore which is signaled.
Valid Usage (Implicit)

  • VUID-VkImportSemaphoreFdInfoKHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_IMPORT_SEMAPHORE_FD_INFO_KHR

  • VUID-VkImportSemaphoreFdInfoKHR-pNext-pNext
    pNext must be NULL

  • VUID-VkImportSemaphoreFdInfoKHR-semaphore-parameter
    semaphore must be a valid VkSemaphore handle

  • VUID-VkImportSemaphoreFdInfoKHR-flags-parameter
    flags must be a valid combination of VkSemaphoreImportFlagBits values

  • VUID-VkImportSemaphoreFdInfoKHR-handleType-parameter
    handleType must be a valid VkExternalSemaphoreHandleTypeFlagBits value

Host Synchronization

  • Host access to semaphore must be externally synchronized

To import a semaphore payload from a Zircon event handle, call:

// Provided by VK_FUCHSIA_external_semaphore
VkResult vkImportSemaphoreZirconHandleFUCHSIA(
    VkDevice                                    device,
    const VkImportSemaphoreZirconHandleInfoFUCHSIA* pImportSemaphoreZirconHandleInfo);

  • device is the logical device that created the semaphore.

  • pImportSemaphoreZirconHandleInfo is a pointer to a VkImportSemaphoreZirconHandleInfoFUCHSIA structure specifying the semaphore and import parameters.

Importing a semaphore payload from a Zircon event handle transfers ownership of the handle from the application to the Vulkan implementation. The application must not perform any operations on the handle after a successful import.

Applications can import the same semaphore payload into multiple instances of Vulkan, into the same instance from which it was exported, and multiple times into a given Vulkan instance.

Valid Usage

  • VUID-vkImportSemaphoreZirconHandleFUCHSIA-semaphore-04764
    semaphore must not be associated with any queue command that has not yet completed execution on that queue

Valid Usage (Implicit)

  • VUID-vkImportSemaphoreZirconHandleFUCHSIA-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkImportSemaphoreZirconHandleFUCHSIA-pImportSemaphoreZirconHandleInfo-parameter
    pImportSemaphoreZirconHandleInfo must be a valid pointer to a valid VkImportSemaphoreZirconHandleInfoFUCHSIA structure

Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_INVALID_EXTERNAL_HANDLE

The VkImportSemaphoreZirconHandleInfoFUCHSIA structure is defined as:

// Provided by VK_FUCHSIA_external_semaphore
typedef struct VkImportSemaphoreZirconHandleInfoFUCHSIA {
    VkStructureType                          sType;
    const void*                              pNext;
    VkSemaphore                              semaphore;
    VkSemaphoreImportFlags                   flags;
    VkExternalSemaphoreHandleTypeFlagBits    handleType;
    zx_handle_t                              zirconHandle;
} VkImportSemaphoreZirconHandleInfoFUCHSIA;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • semaphore is the semaphore into which the payload will be imported.

  • flags is a bitmask of VkSemaphoreImportFlagBits specifying additional parameters for the semaphore payload import operation.

  • handleType is a VkExternalSemaphoreHandleTypeFlagBits value specifying the type of zirconHandle.

  • zirconHandle is the external handle to import.

The handle types supported by handleType are:

Table 10. Handle Types Supported by VkImportSemaphoreZirconHandleInfoFUCHSIA
Handle Type Transference Permanence Supported

VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_ZIRCON_EVENT_BIT_FUCHSIA

Reference

Temporary,Permanent
Valid Usage
Valid Usage (Implicit)

  • VUID-VkImportSemaphoreZirconHandleInfoFUCHSIA-sType-sType
    sType must be VK_STRUCTURE_TYPE_IMPORT_SEMAPHORE_ZIRCON_HANDLE_INFO_FUCHSIA

  • VUID-VkImportSemaphoreZirconHandleInfoFUCHSIA-pNext-pNext
    pNext must be NULL

  • VUID-VkImportSemaphoreZirconHandleInfoFUCHSIA-semaphore-parameter
    semaphore must be a valid VkSemaphore handle

  • VUID-VkImportSemaphoreZirconHandleInfoFUCHSIA-flags-parameter
    flags must be a valid combination of VkSemaphoreImportFlagBits values

  • VUID-VkImportSemaphoreZirconHandleInfoFUCHSIA-handleType-parameter
    handleType must be a valid VkExternalSemaphoreHandleTypeFlagBits value

Host Synchronization

  • Host access to semaphore must be externally synchronized

Bits which can be set in

specifying additional parameters of a semaphore import operation are:

// Provided by VK_VERSION_1_1
typedef enum VkSemaphoreImportFlagBits {
    VK_SEMAPHORE_IMPORT_TEMPORARY_BIT = 0x00000001,
  // Provided by VK_KHR_external_semaphore
    VK_SEMAPHORE_IMPORT_TEMPORARY_BIT_KHR = VK_SEMAPHORE_IMPORT_TEMPORARY_BIT,
} VkSemaphoreImportFlagBits;

or the equivalent

// Provided by VK_KHR_external_semaphore
typedef VkSemaphoreImportFlagBits VkSemaphoreImportFlagBitsKHR;

These bits have the following meanings:

  • VK_SEMAPHORE_IMPORT_TEMPORARY_BIT specifies that the semaphore payload will be imported only temporarily, as described in Importing Semaphore Payloads, regardless of the permanence of handleType.

// Provided by VK_VERSION_1_1
typedef VkFlags VkSemaphoreImportFlags;

or the equivalent

// Provided by VK_KHR_external_semaphore
typedef VkSemaphoreImportFlags VkSemaphoreImportFlagsKHR;

VkSemaphoreImportFlags is a bitmask type for setting a mask of zero or more VkSemaphoreImportFlagBits.

7.5. Events

Events are a synchronization primitive that can be used to insert a fine-grained dependency between commands submitted to the same queue, or between the host and a queue. Events must not be used to insert a dependency between commands submitted to different queues. Events have two states - signaled and unsignaled. An application can signal or unsignal an event either on the host or on the device. A device can be made to wait for an event to become signaled before executing further operations. No command exists to wait for an event to become signaled on the host, but the current state of an event can be queried.

Events are represented by VkEvent handles:

// Provided by VK_VERSION_1_0
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkEvent)

To create an event, call:

// Provided by VK_VERSION_1_0
VkResult vkCreateEvent(
    VkDevice                                    device,
    const VkEventCreateInfo*                    pCreateInfo,
    const VkAllocationCallbacks*                pAllocator,
    VkEvent*                                    pEvent);

  • device is the logical device that creates the event.

  • pCreateInfo is a pointer to a VkEventCreateInfo structure containing information about how the event is to be created.

  • pAllocator controls host memory allocation as described in the Memory Allocation chapter.

  • pEvent is a pointer to a handle in which the resulting event object is returned.

When created, the event object is in the unsignaled state.

Valid Usage

  • VUID-vkCreateEvent-device-09672
    device must support at least one queue family with one of the VK_QUEUE_VIDEO_ENCODE_BIT_KHR, VK_QUEUE_VIDEO_DECODE_BIT_KHR, VK_QUEUE_COMPUTE_BIT, or VK_QUEUE_GRAPHICS_BIT capabilities

  • VUID-vkCreateEvent-events-04468
    If the VK_KHR_portability_subset extension is enabled, and VkPhysicalDevicePortabilitySubsetFeaturesKHR::events is VK_FALSE, then the implementation does not support events, and vkCreateEvent must not be used

Valid Usage (Implicit)

  • VUID-vkCreateEvent-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkCreateEvent-pCreateInfo-parameter
    pCreateInfo must be a valid pointer to a valid VkEventCreateInfo structure

  • VUID-vkCreateEvent-pAllocator-parameter
    If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure

  • VUID-vkCreateEvent-pEvent-parameter
    pEvent must be a valid pointer to a VkEvent handle

Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

The VkEventCreateInfo structure is defined as:

// Provided by VK_VERSION_1_0
typedef struct VkEventCreateInfo {
    VkStructureType       sType;
    const void*           pNext;
    VkEventCreateFlags    flags;
} VkEventCreateInfo;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • flags is a bitmask of VkEventCreateFlagBits defining additional creation parameters.

Valid Usage

  • VUID-VkEventCreateInfo-pNext-06790
    If the pNext chain includes a VkExportMetalObjectCreateInfoEXT structure, its exportObjectType member must be VK_EXPORT_METAL_OBJECT_TYPE_METAL_SHARED_EVENT_BIT_EXT

Valid Usage (Implicit)

  • VUID-VkEventCreateInfo-sType-sType
    sType must be VK_STRUCTURE_TYPE_EVENT_CREATE_INFO

  • VUID-VkEventCreateInfo-pNext-pNext
    Each pNext member of any structure (including this one) in the pNext chain must be either NULL or a pointer to a valid instance of VkExportMetalObjectCreateInfoEXT or VkImportMetalSharedEventInfoEXT

  • VUID-VkEventCreateInfo-sType-unique
    The sType value of each struct in the pNext chain must be unique, with the exception of structures of type VkExportMetalObjectCreateInfoEXT

  • VUID-VkEventCreateInfo-flags-parameter
    flags must be a valid combination of VkEventCreateFlagBits values

// Provided by VK_VERSION_1_0
typedef enum VkEventCreateFlagBits {
  // Provided by VK_VERSION_1_3
    VK_EVENT_CREATE_DEVICE_ONLY_BIT = 0x00000001,
  // Provided by VK_KHR_synchronization2
    VK_EVENT_CREATE_DEVICE_ONLY_BIT_KHR = VK_EVENT_CREATE_DEVICE_ONLY_BIT,
} VkEventCreateFlagBits;

  • VK_EVENT_CREATE_DEVICE_ONLY_BIT specifies that host event commands will not be used with this event.

// Provided by VK_VERSION_1_0
typedef VkFlags VkEventCreateFlags;

VkEventCreateFlags is a bitmask type for setting a mask of VkEventCreateFlagBits.

To destroy an event, call:

// Provided by VK_VERSION_1_0
void vkDestroyEvent(
    VkDevice                                    device,
    VkEvent                                     event,
    const VkAllocationCallbacks*                pAllocator);

  • device is the logical device that destroys the event.

  • event is the handle of the event to destroy.

  • pAllocator controls host memory allocation as described in the Memory Allocation chapter.

Valid Usage

  • VUID-vkDestroyEvent-event-01145
    All submitted commands that refer to event must have completed execution

  • VUID-vkDestroyEvent-event-01146
    If VkAllocationCallbacks were provided when event was created, a compatible set of callbacks must be provided here

  • VUID-vkDestroyEvent-event-01147
    If no VkAllocationCallbacks were provided when event was created, pAllocator must be NULL

Valid Usage (Implicit)

  • VUID-vkDestroyEvent-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkDestroyEvent-event-parameter
    If event is not VK_NULL_HANDLE, event must be a valid VkEvent handle

  • VUID-vkDestroyEvent-pAllocator-parameter
    If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure

  • VUID-vkDestroyEvent-event-parent
    If event is a valid handle, it must have been created, allocated, or retrieved from device

Host Synchronization

  • Host access to event must be externally synchronized

To query the state of an event from the host, call:

// Provided by VK_VERSION_1_0
VkResult vkGetEventStatus(
    VkDevice                                    device,
    VkEvent                                     event);

  • device is the logical device that owns the event.

  • event is the handle of the event to query.

Upon success, vkGetEventStatus returns the state of the event object with the following return codes:

Table 11. Event Object Status Codes
Status Meaning

VK_EVENT_SET

The event specified by event is signaled.

VK_EVENT_RESET

The event specified by event is unsignaled.

If a vkCmdSetEvent or vkCmdResetEvent command is in a command buffer that is in the pending state, then the value returned by this command may immediately be out of date.

The state of an event can be updated by the host. The state of the event is immediately changed, and subsequent calls to vkGetEventStatus will return the new state. If an event is already in the requested state, then updating it to the same state has no effect.

Valid Usage

  • VUID-vkGetEventStatus-event-03940
    event must not have been created with VK_EVENT_CREATE_DEVICE_ONLY_BIT

Valid Usage (Implicit)

  • VUID-vkGetEventStatus-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkGetEventStatus-event-parameter
    event must be a valid VkEvent handle

  • VUID-vkGetEventStatus-event-parent
    event must have been created, allocated, or retrieved from device

Return Codes
Success

  • VK_EVENT_SET

  • VK_EVENT_RESET

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

  • VK_ERROR_DEVICE_LOST

To set the state of an event to signaled from the host, call:

// Provided by VK_VERSION_1_0
VkResult vkSetEvent(
    VkDevice                                    device,
    VkEvent                                     event);

  • device is the logical device that owns the event.

  • event is the event to set.

When vkSetEvent is executed on the host, it defines an event signal operation which sets the event to the signaled state.

If event is already in the signaled state when vkSetEvent is executed, then vkSetEvent has no effect, and no event signal operation occurs.

Note

If a command buffer is waiting for an event to be signaled from the host, the application must signal the event before submitting the command buffer, as described in the queue forward progress section.
Valid Usage

  • VUID-vkSetEvent-event-03941
    event must not have been created with VK_EVENT_CREATE_DEVICE_ONLY_BIT

  • VUID-vkSetEvent-event-09543
    event must not be waited on by a command buffer in the pending state

Valid Usage (Implicit)

  • VUID-vkSetEvent-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkSetEvent-event-parameter
    event must be a valid VkEvent handle

  • VUID-vkSetEvent-event-parent
    event must have been created, allocated, or retrieved from device

Host Synchronization

  • Host access to event must be externally synchronized

Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

To set the state of an event to unsignaled from the host, call:

// Provided by VK_VERSION_1_0
VkResult vkResetEvent(
    VkDevice                                    device,
    VkEvent                                     event);

  • device is the logical device that owns the event.

  • event is the event to reset.

When vkResetEvent is executed on the host, it defines an event unsignal operation which resets the event to the unsignaled state.

If event is already in the unsignaled state when vkResetEvent is executed, then vkResetEvent has no effect, and no event unsignal operation occurs.

Valid Usage

  • VUID-vkResetEvent-event-03821
    There must be an execution dependency between vkResetEvent and the execution of any vkCmdWaitEvents that includes event in its pEvents parameter

  • VUID-vkResetEvent-event-03822
    There must be an execution dependency between vkResetEvent and the execution of any vkCmdWaitEvents2 that includes event in its pEvents parameter

  • VUID-vkResetEvent-event-03823
    event must not have been created with VK_EVENT_CREATE_DEVICE_ONLY_BIT

Valid Usage (Implicit)

  • VUID-vkResetEvent-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkResetEvent-event-parameter
    event must be a valid VkEvent handle

  • VUID-vkResetEvent-event-parent
    event must have been created, allocated, or retrieved from device

Host Synchronization

  • Host access to event must be externally synchronized

Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

The state of an event can also be updated on the device by commands inserted in command buffers.

To signal an event from a device, call:

// Provided by VK_VERSION_1_3
void vkCmdSetEvent2(
    VkCommandBuffer                             commandBuffer,
    VkEvent                                     event,
    const VkDependencyInfo*                     pDependencyInfo);

or the equivalent command

// Provided by VK_KHR_synchronization2
void vkCmdSetEvent2KHR(
    VkCommandBuffer                             commandBuffer,
    VkEvent                                     event,
    const VkDependencyInfo*                     pDependencyInfo);

  • commandBuffer is the command buffer into which the command is recorded.

  • event is the event that will be signaled.

  • pDependencyInfo is a pointer to a VkDependencyInfo structure defining the first scopes of this operation.

When vkCmdSetEvent2 is submitted to a queue, it defines the first half of memory dependencies defined by pDependencyInfo, as well as an event signal operation which sets the event to the signaled state. A memory dependency is defined between the event signal operation and commands that occur earlier in submission order.

The first synchronization scope and access scope are defined by the union of all the memory dependencies defined by pDependencyInfo, and are applied to all operations that occur earlier in submission order. Queue family ownership transfers and image layout transitions defined by pDependencyInfo are also included in the first scopes.

The second synchronization scope includes only the event signal operation, and any queue family ownership transfers and image layout transitions defined by pDependencyInfo.

The second access scope includes only queue family ownership transfers and image layout transitions.

Future vkCmdWaitEvents2 commands rely on all values of each element in pDependencyInfo matching exactly with those used to signal the corresponding event. vkCmdWaitEvents must not be used to wait on the result of a signal operation defined by vkCmdSetEvent2.

Note

The extra information provided by vkCmdSetEvent2 compared to vkCmdSetEvent allows implementations to more efficiently schedule the operations required to satisfy the requested dependencies. With vkCmdSetEvent, the full dependency information is not known until vkCmdWaitEvents is recorded, forcing implementations to insert the required operations at that point and not before.

If event is already in the signaled state when vkCmdSetEvent2 is executed on the device, then vkCmdSetEvent2 has no effect, no event signal operation occurs, and no dependency is generated.

Valid Usage

  • VUID-vkCmdSetEvent2-synchronization2-03824
    The synchronization2 feature must be enabled

  • VUID-vkCmdSetEvent2-dependencyFlags-03825
    The dependencyFlags member of pDependencyInfo must be 0

  • VUID-vkCmdSetEvent2-srcStageMask-09391
    The srcStageMask member of any element of the pMemoryBarriers, pBufferMemoryBarriers, or pImageMemoryBarriers members of pDependencyInfo must not include VK_PIPELINE_STAGE_2_HOST_BIT

  • VUID-vkCmdSetEvent2-dstStageMask-09392
    The dstStageMask member of any element of the pMemoryBarriers, pBufferMemoryBarriers, or pImageMemoryBarriers members of pDependencyInfo must not include VK_PIPELINE_STAGE_2_HOST_BIT

  • VUID-vkCmdSetEvent2-commandBuffer-03826
    The current device mask of commandBuffer must include exactly one physical device

  • VUID-vkCmdSetEvent2-srcStageMask-03827
    The srcStageMask member of any element of the pMemoryBarriers, pBufferMemoryBarriers, or pImageMemoryBarriers members of pDependencyInfo must only include pipeline stages valid for the queue family that was used to create the command pool that commandBuffer was allocated from

  • VUID-vkCmdSetEvent2-dstStageMask-03828
    The dstStageMask member of any element of the pMemoryBarriers, pBufferMemoryBarriers, or pImageMemoryBarriers members of pDependencyInfo must only include pipeline stages valid for the queue family that was used to create the command pool that commandBuffer was allocated from

Valid Usage (Implicit)

  • VUID-vkCmdSetEvent2-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdSetEvent2-event-parameter
    event must be a valid VkEvent handle

  • VUID-vkCmdSetEvent2-pDependencyInfo-parameter
    pDependencyInfo must be a valid pointer to a valid VkDependencyInfo structure

  • VUID-vkCmdSetEvent2-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdSetEvent2-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support graphics, compute, decode, or encode operations

  • VUID-vkCmdSetEvent2-renderpass
    This command must only be called outside of a render pass instance

  • VUID-vkCmdSetEvent2-commonparent
    Both of commandBuffer, and event must have been created, allocated, or retrieved from the same VkDevice

Host Synchronization

  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Video Coding Scope Supported Queue Types Command Type

Primary
Secondary

Outside

Both

Graphics
Compute
Decode
Encode

Synchronization

The VkDependencyInfo structure is defined as:

// Provided by VK_VERSION_1_3
typedef struct VkDependencyInfo {
    VkStructureType                  sType;
    const void*                      pNext;
    VkDependencyFlags                dependencyFlags;
    uint32_t                         memoryBarrierCount;
    const VkMemoryBarrier2*          pMemoryBarriers;
    uint32_t                         bufferMemoryBarrierCount;
    const VkBufferMemoryBarrier2*    pBufferMemoryBarriers;
    uint32_t                         imageMemoryBarrierCount;
    const VkImageMemoryBarrier2*     pImageMemoryBarriers;
} VkDependencyInfo;

or the equivalent

// Provided by VK_KHR_synchronization2
typedef VkDependencyInfo VkDependencyInfoKHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • dependencyFlags is a bitmask of VkDependencyFlagBits specifying how execution and memory dependencies are formed.

  • memoryBarrierCount is the length of the pMemoryBarriers array.

  • pMemoryBarriers is a pointer to an array of VkMemoryBarrier2 structures defining memory dependencies between any memory accesses.

  • bufferMemoryBarrierCount is the length of the pBufferMemoryBarriers array.

  • pBufferMemoryBarriers is a pointer to an array of VkBufferMemoryBarrier2 structures defining memory dependencies between buffer ranges.

  • imageMemoryBarrierCount is the length of the pImageMemoryBarriers array.

  • pImageMemoryBarriers is a pointer to an array of VkImageMemoryBarrier2 structures defining memory dependencies between image subresources.

This structure defines a set of memory dependencies, as well as queue family ownership transfer operations and image layout transitions.

Each member of pMemoryBarriers, pBufferMemoryBarriers, and pImageMemoryBarriers defines a separate memory dependency.

Valid Usage (Implicit)

  • VUID-VkDependencyInfo-sType-sType
    sType must be VK_STRUCTURE_TYPE_DEPENDENCY_INFO

  • VUID-VkDependencyInfo-pNext-pNext
    pNext must be NULL

  • VUID-VkDependencyInfo-dependencyFlags-parameter
    dependencyFlags must be a valid combination of VkDependencyFlagBits values

  • VUID-VkDependencyInfo-pMemoryBarriers-parameter
    If memoryBarrierCount is not 0, pMemoryBarriers must be a valid pointer to an array of memoryBarrierCount valid VkMemoryBarrier2 structures

  • VUID-VkDependencyInfo-pBufferMemoryBarriers-parameter
    If bufferMemoryBarrierCount is not 0, pBufferMemoryBarriers must be a valid pointer to an array of bufferMemoryBarrierCount valid VkBufferMemoryBarrier2 structures

  • VUID-VkDependencyInfo-pImageMemoryBarriers-parameter
    If imageMemoryBarrierCount is not 0, pImageMemoryBarriers must be a valid pointer to an array of imageMemoryBarrierCount valid VkImageMemoryBarrier2 structures

To set the state of an event to signaled from a device, call:

// Provided by VK_VERSION_1_0
void vkCmdSetEvent(
    VkCommandBuffer                             commandBuffer,
    VkEvent                                     event,
    VkPipelineStageFlags                        stageMask);

  • commandBuffer is the command buffer into which the command is recorded.

  • event is the event that will be signaled.

  • stageMask specifies the source stage mask used to determine the first synchronization scope.

vkCmdSetEvent behaves identically to vkCmdSetEvent2, except that it does not define an access scope, and must only be used with vkCmdWaitEvents, not vkCmdWaitEvents2.

Valid Usage

  • VUID-vkCmdSetEvent-stageMask-04090
    If the geometryShader feature is not enabled, stageMask must not contain VK_PIPELINE_STAGE_GEOMETRY_SHADER_BIT

  • VUID-vkCmdSetEvent-stageMask-04091
    If the tessellationShader feature is not enabled, stageMask must not contain VK_PIPELINE_STAGE_TESSELLATION_CONTROL_SHADER_BIT or VK_PIPELINE_STAGE_TESSELLATION_EVALUATION_SHADER_BIT

  • VUID-vkCmdSetEvent-stageMask-04092
    If the conditionalRendering feature is not enabled, stageMask must not contain VK_PIPELINE_STAGE_CONDITIONAL_RENDERING_BIT_EXT

  • VUID-vkCmdSetEvent-stageMask-04093
    If the fragmentDensityMap feature is not enabled, stageMask must not contain VK_PIPELINE_STAGE_FRAGMENT_DENSITY_PROCESS_BIT_EXT

  • VUID-vkCmdSetEvent-stageMask-04094
    If the transformFeedback feature is not enabled, stageMask must not contain VK_PIPELINE_STAGE_TRANSFORM_FEEDBACK_BIT_EXT

  • VUID-vkCmdSetEvent-stageMask-04095
    If the meshShader feature is not enabled, stageMask must not contain VK_PIPELINE_STAGE_MESH_SHADER_BIT_EXT

  • VUID-vkCmdSetEvent-stageMask-04096
    If the taskShader feature is not enabled, stageMask must not contain VK_PIPELINE_STAGE_TASK_SHADER_BIT_EXT

  • VUID-vkCmdSetEvent-stageMask-07318
    If neither the shadingRateImage or attachmentFragmentShadingRate are enabled, stageMask must not contain VK_PIPELINE_STAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR

  • VUID-vkCmdSetEvent-stageMask-03937
    If the synchronization2 feature is not enabled, stageMask must not be 0

  • VUID-vkCmdSetEvent-stageMask-07949
    If neither the VK_NV_ray_tracing extension or rayTracingPipeline feature are enabled, stageMask must not contain VK_PIPELINE_STAGE_RAY_TRACING_SHADER_BIT_KHR

  • VUID-vkCmdSetEvent-stageMask-06457
    Any pipeline stage included in stageMask must be supported by the capabilities of the queue family specified by the queueFamilyIndex member of the VkCommandPoolCreateInfo structure that was used to create the VkCommandPool that commandBuffer was allocated from, as specified in the table of supported pipeline stages

  • VUID-vkCmdSetEvent-stageMask-01149
    stageMask must not include VK_PIPELINE_STAGE_HOST_BIT

  • VUID-vkCmdSetEvent-commandBuffer-01152
    The current device mask of commandBuffer must include exactly one physical device

Valid Usage (Implicit)

  • VUID-vkCmdSetEvent-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdSetEvent-event-parameter
    event must be a valid VkEvent handle

  • VUID-vkCmdSetEvent-stageMask-parameter
    stageMask must be a valid combination of VkPipelineStageFlagBits values

  • VUID-vkCmdSetEvent-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdSetEvent-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support graphics, compute, decode, or encode operations

  • VUID-vkCmdSetEvent-renderpass
    This command must only be called outside of a render pass instance

  • VUID-vkCmdSetEvent-commonparent
    Both of commandBuffer, and event must have been created, allocated, or retrieved from the same VkDevice

Host Synchronization

  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Video Coding Scope Supported Queue Types Command Type

Primary
Secondary

Outside

Both

Graphics
Compute
Decode
Encode

Synchronization

To unsignal the event from a device, call:

// Provided by VK_VERSION_1_3
void vkCmdResetEvent2(
    VkCommandBuffer                             commandBuffer,
    VkEvent                                     event,
    VkPipelineStageFlags2                       stageMask);

or the equivalent command

// Provided by VK_KHR_synchronization2
void vkCmdResetEvent2KHR(
    VkCommandBuffer                             commandBuffer,
    VkEvent                                     event,
    VkPipelineStageFlags2                       stageMask);

  • commandBuffer is the command buffer into which the command is recorded.

  • event is the event that will be unsignaled.

  • stageMask is a VkPipelineStageFlags2 mask of pipeline stages used to determine the first synchronization scope.

When vkCmdResetEvent2 is submitted to a queue, it defines an execution dependency on commands that were submitted before it, and defines an event unsignal operation which resets the event to the unsignaled state.

The first synchronization scope includes all commands that occur earlier in submission order. The synchronization scope is limited to operations by stageMask or stages that are logically earlier than stageMask.

The second synchronization scope includes only the event unsignal operation.

If event is already in the unsignaled state when vkCmdResetEvent2 is executed on the device, then this command has no effect, no event unsignal operation occurs, and no execution dependency is generated.

Valid Usage

  • VUID-vkCmdResetEvent2-stageMask-03929
    If the geometryShader feature is not enabled, stageMask must not contain VK_PIPELINE_STAGE_2_GEOMETRY_SHADER_BIT

  • VUID-vkCmdResetEvent2-stageMask-03930
    If the tessellationShader feature is not enabled, stageMask must not contain VK_PIPELINE_STAGE_2_TESSELLATION_CONTROL_SHADER_BIT or VK_PIPELINE_STAGE_2_TESSELLATION_EVALUATION_SHADER_BIT

  • VUID-vkCmdResetEvent2-stageMask-03931
    If the conditionalRendering feature is not enabled, stageMask must not contain VK_PIPELINE_STAGE_2_CONDITIONAL_RENDERING_BIT_EXT

  • VUID-vkCmdResetEvent2-stageMask-03932
    If the fragmentDensityMap feature is not enabled, stageMask must not contain VK_PIPELINE_STAGE_2_FRAGMENT_DENSITY_PROCESS_BIT_EXT

  • VUID-vkCmdResetEvent2-stageMask-03933
    If the transformFeedback feature is not enabled, stageMask must not contain VK_PIPELINE_STAGE_2_TRANSFORM_FEEDBACK_BIT_EXT

  • VUID-vkCmdResetEvent2-stageMask-03934
    If the meshShader feature is not enabled, stageMask must not contain VK_PIPELINE_STAGE_2_MESH_SHADER_BIT_EXT

  • VUID-vkCmdResetEvent2-stageMask-03935
    If the taskShader feature is not enabled, stageMask must not contain VK_PIPELINE_STAGE_2_TASK_SHADER_BIT_EXT

  • VUID-vkCmdResetEvent2-stageMask-07316
    If neither the shadingRateImage or attachmentFragmentShadingRate are enabled, stageMask must not contain VK_PIPELINE_STAGE_2_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR

  • VUID-vkCmdResetEvent2-stageMask-04957
    If the subpassShading feature is not enabled, stageMask must not contain VK_PIPELINE_STAGE_2_SUBPASS_SHADER_BIT_HUAWEI

  • VUID-vkCmdResetEvent2-stageMask-04995
    If the invocationMask feature is not enabled, stageMask must not contain VK_PIPELINE_STAGE_2_INVOCATION_MASK_BIT_HUAWEI

  • VUID-vkCmdResetEvent2-stageMask-07946
    If neither the VK_NV_ray_tracing extension or rayTracingPipeline feature are enabled, stageMask must not contain VK_PIPELINE_STAGE_2_RAY_TRACING_SHADER_BIT_KHR

  • VUID-vkCmdResetEvent2-synchronization2-03829
    The synchronization2 feature must be enabled

  • VUID-vkCmdResetEvent2-stageMask-03830
    stageMask must not include VK_PIPELINE_STAGE_2_HOST_BIT

  • VUID-vkCmdResetEvent2-event-03831
    There must be an execution dependency between vkCmdResetEvent2 and the execution of any vkCmdWaitEvents that includes event in its pEvents parameter

  • VUID-vkCmdResetEvent2-event-03832
    There must be an execution dependency between vkCmdResetEvent2 and the execution of any vkCmdWaitEvents2 that includes event in its pEvents parameter

  • VUID-vkCmdResetEvent2-commandBuffer-03833
    commandBuffer’s current device mask must include exactly one physical device

Valid Usage (Implicit)

  • VUID-vkCmdResetEvent2-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdResetEvent2-event-parameter
    event must be a valid VkEvent handle

  • VUID-vkCmdResetEvent2-stageMask-parameter
    stageMask must be a valid combination of VkPipelineStageFlagBits2 values

  • VUID-vkCmdResetEvent2-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdResetEvent2-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support graphics, compute, decode, or encode operations

  • VUID-vkCmdResetEvent2-renderpass
    This command must only be called outside of a render pass instance

  • VUID-vkCmdResetEvent2-commonparent
    Both of commandBuffer, and event must have been created, allocated, or retrieved from the same VkDevice

Host Synchronization

  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Video Coding Scope Supported Queue Types Command Type

Primary
Secondary

Outside

Both

Graphics
Compute
Decode
Encode

Synchronization

To set the state of an event to unsignaled from a device, call:

// Provided by VK_VERSION_1_0
void vkCmdResetEvent(
    VkCommandBuffer                             commandBuffer,
    VkEvent                                     event,
    VkPipelineStageFlags                        stageMask);

  • commandBuffer is the command buffer into which the command is recorded.

  • event is the event that will be unsignaled.

  • stageMask is a bitmask of VkPipelineStageFlagBits specifying the source stage mask used to determine when the event is unsignaled.

vkCmdResetEvent behaves identically to vkCmdResetEvent2.

Valid Usage

  • VUID-vkCmdResetEvent-stageMask-04090
    If the geometryShader feature is not enabled, stageMask must not contain VK_PIPELINE_STAGE_GEOMETRY_SHADER_BIT

  • VUID-vkCmdResetEvent-stageMask-04091
    If the tessellationShader feature is not enabled, stageMask must not contain VK_PIPELINE_STAGE_TESSELLATION_CONTROL_SHADER_BIT or VK_PIPELINE_STAGE_TESSELLATION_EVALUATION_SHADER_BIT

  • VUID-vkCmdResetEvent-stageMask-04092
    If the conditionalRendering feature is not enabled, stageMask must not contain VK_PIPELINE_STAGE_CONDITIONAL_RENDERING_BIT_EXT

  • VUID-vkCmdResetEvent-stageMask-04093
    If the fragmentDensityMap feature is not enabled, stageMask must not contain VK_PIPELINE_STAGE_FRAGMENT_DENSITY_PROCESS_BIT_EXT

  • VUID-vkCmdResetEvent-stageMask-04094
    If the transformFeedback feature is not enabled, stageMask must not contain VK_PIPELINE_STAGE_TRANSFORM_FEEDBACK_BIT_EXT

  • VUID-vkCmdResetEvent-stageMask-04095
    If the meshShader feature is not enabled, stageMask must not contain VK_PIPELINE_STAGE_MESH_SHADER_BIT_EXT

  • VUID-vkCmdResetEvent-stageMask-04096
    If the taskShader feature is not enabled, stageMask must not contain VK_PIPELINE_STAGE_TASK_SHADER_BIT_EXT

  • VUID-vkCmdResetEvent-stageMask-07318
    If neither the shadingRateImage or attachmentFragmentShadingRate are enabled, stageMask must not contain VK_PIPELINE_STAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR

  • VUID-vkCmdResetEvent-stageMask-03937
    If the synchronization2 feature is not enabled, stageMask must not be 0

  • VUID-vkCmdResetEvent-stageMask-07949
    If neither the VK_NV_ray_tracing extension or rayTracingPipeline feature are enabled, stageMask must not contain VK_PIPELINE_STAGE_RAY_TRACING_SHADER_BIT_KHR

  • VUID-vkCmdResetEvent-stageMask-06458
    Any pipeline stage included in stageMask must be supported by the capabilities of the queue family specified by the queueFamilyIndex member of the VkCommandPoolCreateInfo structure that was used to create the VkCommandPool that commandBuffer was allocated from, as specified in the table of supported pipeline stages

  • VUID-vkCmdResetEvent-stageMask-01153
    stageMask must not include VK_PIPELINE_STAGE_HOST_BIT

  • VUID-vkCmdResetEvent-event-03834
    There must be an execution dependency between vkCmdResetEvent and the execution of any vkCmdWaitEvents that includes event in its pEvents parameter

  • VUID-vkCmdResetEvent-event-03835
    There must be an execution dependency between vkCmdResetEvent and the execution of any vkCmdWaitEvents2 that includes event in its pEvents parameter

  • VUID-vkCmdResetEvent-commandBuffer-01157
    commandBuffer’s current device mask must include exactly one physical device

Valid Usage (Implicit)

  • VUID-vkCmdResetEvent-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdResetEvent-event-parameter
    event must be a valid VkEvent handle

  • VUID-vkCmdResetEvent-stageMask-parameter
    stageMask must be a valid combination of VkPipelineStageFlagBits values

  • VUID-vkCmdResetEvent-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdResetEvent-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support graphics, compute, decode, or encode operations

  • VUID-vkCmdResetEvent-renderpass
    This command must only be called outside of a render pass instance

  • VUID-vkCmdResetEvent-commonparent
    Both of commandBuffer, and event must have been created, allocated, or retrieved from the same VkDevice

Host Synchronization

  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Video Coding Scope Supported Queue Types Command Type

Primary
Secondary

Outside

Both

Graphics
Compute
Decode
Encode

Synchronization

To wait for one or more events to enter the signaled state on a device, call:

// Provided by VK_VERSION_1_3
void vkCmdWaitEvents2(
    VkCommandBuffer                             commandBuffer,
    uint32_t                                    eventCount,
    const VkEvent*                              pEvents,
    const VkDependencyInfo*                     pDependencyInfos);

or the equivalent command

// Provided by VK_KHR_synchronization2
void vkCmdWaitEvents2KHR(
    VkCommandBuffer                             commandBuffer,
    uint32_t                                    eventCount,
    const VkEvent*                              pEvents,
    const VkDependencyInfo*                     pDependencyInfos);

  • commandBuffer is the command buffer into which the command is recorded.

  • eventCount is the length of the pEvents array.

  • pEvents is a pointer to an array of eventCount events to wait on.

  • pDependencyInfos is a pointer to an array of eventCount VkDependencyInfo structures, defining the second synchronization scope.

When vkCmdWaitEvents2 is submitted to a queue, it inserts memory dependencies according to the elements of pDependencyInfos and each corresponding element of pEvents. vkCmdWaitEvents2 must not be used to wait on event signal operations occurring on other queues, or signal operations executed by vkCmdSetEvent.

The first synchronization scope and access scope of each memory dependency defined by any element i of pDependencyInfos are applied to operations that occurred earlier in submission order than the last event signal operation on element i of pEvents.

Signal operations for an event at index i are only included if:

  • The event was signaled by a vkCmdSetEvent2 command that occurred earlier in submission order with a dependencyInfo parameter exactly equal to the element of pDependencyInfos at index i ; or

  • The event was created without VK_EVENT_CREATE_DEVICE_ONLY_BIT, and the first synchronization scope defined by the element of pDependencyInfos at index i only includes host operations (VK_PIPELINE_STAGE_2_HOST_BIT).

The second synchronization scope and access scope of each memory dependency defined by any element i of pDependencyInfos are applied to operations that occurred later in submission order than vkCmdWaitEvents2.

Note

vkCmdWaitEvents2 is used with vkCmdSetEvent2 to define a memory dependency between two sets of action commands, roughly in the same way as pipeline barriers, but split into two commands such that work between the two may execute unhindered.
Note

Applications should be careful to avoid race conditions when using events. There is no direct ordering guarantee between vkCmdSetEvent2 and vkCmdResetEvent2, vkCmdResetEvent, or vkCmdSetEvent. Another execution dependency (e.g. a pipeline barrier or semaphore with VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT) is needed to prevent such a race condition.
Valid Usage

  • VUID-vkCmdWaitEvents2-synchronization2-03836
    The synchronization2 feature must be enabled

  • VUID-vkCmdWaitEvents2-pEvents-03837
    Members of pEvents must not have been signaled by vkCmdSetEvent

  • VUID-vkCmdWaitEvents2-pEvents-03838
    For any element i of pEvents, if that event is signaled by vkCmdSetEvent2, that command’s dependencyInfo parameter must be exactly equal to the ith element of pDependencyInfos

  • VUID-vkCmdWaitEvents2-pEvents-03839
    For any element i of pEvents, if that event is signaled by vkSetEvent, barriers in the ith element of pDependencyInfos must include only host operations in their first synchronization scope

  • VUID-vkCmdWaitEvents2-pEvents-03840
    For any element i of pEvents, if barriers in the ith element of pDependencyInfos include only host operations, the ith element of pEvents must be signaled before vkCmdWaitEvents2 is executed

  • VUID-vkCmdWaitEvents2-pEvents-03841
    For any element i of pEvents, if barriers in the ith element of pDependencyInfos do not include host operations, the ith element of pEvents must be signaled by a corresponding vkCmdSetEvent2 that occurred earlier in submission order

  • VUID-vkCmdWaitEvents2-srcStageMask-03842
    The srcStageMask member of any element of the pMemoryBarriers, pBufferMemoryBarriers, or pImageMemoryBarriers members of pDependencyInfos must only include pipeline stages valid for the queue family that was used to create the command pool that commandBuffer was allocated from

  • VUID-vkCmdWaitEvents2-dstStageMask-03843
    The dstStageMask member of any element of the pMemoryBarriers, pBufferMemoryBarriers, or pImageMemoryBarriers members of pDependencyInfos must only include pipeline stages valid for the queue family that was used to create the command pool that commandBuffer was allocated from

  • VUID-vkCmdWaitEvents2-dependencyFlags-03844
    If vkCmdWaitEvents2 is being called inside a render pass instance, the srcStageMask member of any element of the pMemoryBarriers, pBufferMemoryBarriers, or pImageMemoryBarriers members of pDependencyInfos must not include VK_PIPELINE_STAGE_2_HOST_BIT

  • VUID-vkCmdWaitEvents2-commandBuffer-03846
    commandBuffer’s current device mask must include exactly one physical device

Valid Usage (Implicit)

  • VUID-vkCmdWaitEvents2-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdWaitEvents2-pEvents-parameter
    pEvents must be a valid pointer to an array of eventCount valid VkEvent handles

  • VUID-vkCmdWaitEvents2-pDependencyInfos-parameter
    pDependencyInfos must be a valid pointer to an array of eventCount valid VkDependencyInfo structures

  • VUID-vkCmdWaitEvents2-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdWaitEvents2-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support graphics, compute, decode, or encode operations

  • VUID-vkCmdWaitEvents2-eventCount-arraylength
    eventCount must be greater than 0

  • VUID-vkCmdWaitEvents2-commonparent
    Both of commandBuffer, and the elements of pEvents must have been created, allocated, or retrieved from the same VkDevice

Host Synchronization

  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Video Coding Scope Supported Queue Types Command Type

Primary
Secondary

Both

Both

Graphics
Compute
Decode
Encode

Synchronization

To wait for one or more events to enter the signaled state on a device, call:

// Provided by VK_VERSION_1_0
void vkCmdWaitEvents(
    VkCommandBuffer                             commandBuffer,
    uint32_t                                    eventCount,
    const VkEvent*                              pEvents,
    VkPipelineStageFlags                        srcStageMask,
    VkPipelineStageFlags                        dstStageMask,
    uint32_t                                    memoryBarrierCount,
    const VkMemoryBarrier*                      pMemoryBarriers,
    uint32_t                                    bufferMemoryBarrierCount,
    const VkBufferMemoryBarrier*                pBufferMemoryBarriers,
    uint32_t                                    imageMemoryBarrierCount,
    const VkImageMemoryBarrier*                 pImageMemoryBarriers);

  • commandBuffer is the command buffer into which the command is recorded.

  • eventCount is the length of the pEvents array.

  • pEvents is a pointer to an array of event object handles to wait on.

  • srcStageMask is a bitmask of VkPipelineStageFlagBits specifying the source stage mask.

  • dstStageMask is a bitmask of VkPipelineStageFlagBits specifying the destination stage mask.

  • memoryBarrierCount is the length of the pMemoryBarriers array.

  • pMemoryBarriers is a pointer to an array of VkMemoryBarrier structures.

  • bufferMemoryBarrierCount is the length of the pBufferMemoryBarriers array.

  • pBufferMemoryBarriers is a pointer to an array of VkBufferMemoryBarrier structures.

  • imageMemoryBarrierCount is the length of the pImageMemoryBarriers array.

  • pImageMemoryBarriers is a pointer to an array of VkImageMemoryBarrier structures.

vkCmdWaitEvents is largely similar to vkCmdWaitEvents2, but can only wait on signal operations defined by vkCmdSetEvent. As vkCmdSetEvent does not define any access scopes, vkCmdWaitEvents defines the first access scope for each event signal operation in addition to its own access scopes.

Note

Since vkCmdSetEvent does not have any dependency information beyond a stage mask, implementations do not have the same opportunity to perform availability and visibility operations or image layout transitions in advance as they do with vkCmdSetEvent2 and vkCmdWaitEvents2.

When vkCmdWaitEvents is submitted to a queue, it defines a memory dependency between prior event signal operations on the same queue or the host, and subsequent commands. vkCmdWaitEvents must not be used to wait on event signal operations occurring on other queues.

The first synchronization scope only includes event signal operations that operate on members of pEvents, and the operations that happened-before the event signal operations. Event signal operations performed by vkCmdSetEvent that occur earlier in submission order are included in the first synchronization scope, if the logically latest pipeline stage in their stageMask parameter is logically earlier than or equal to the logically latest pipeline stage in srcStageMask. Event signal operations performed by vkSetEvent are only included in the first synchronization scope if VK_PIPELINE_STAGE_HOST_BIT is included in srcStageMask.

The second synchronization scope includes all commands that occur later in submission order. The second synchronization scope is limited to operations on the pipeline stages determined by the destination stage mask specified by dstStageMask.

The first access scope is limited to accesses in the pipeline stages determined by the source stage mask specified by srcStageMask. Within that, the first access scope only includes the first access scopes defined by elements of the pMemoryBarriers, pBufferMemoryBarriers and pImageMemoryBarriers arrays, which each define a set of memory barriers. If no memory barriers are specified, then the first access scope includes no accesses.

The second access scope is limited to accesses in the pipeline stages determined by the destination stage mask specified by dstStageMask. Within that, the second access scope only includes the second access scopes defined by elements of the pMemoryBarriers, pBufferMemoryBarriers and pImageMemoryBarriers arrays, which each define a set of memory barriers. If no memory barriers are specified, then the second access scope includes no accesses.

Valid Usage

  • VUID-vkCmdWaitEvents-srcStageMask-04090
    If the geometryShader feature is not enabled, srcStageMask must not contain VK_PIPELINE_STAGE_GEOMETRY_SHADER_BIT

  • VUID-vkCmdWaitEvents-srcStageMask-04091
    If the tessellationShader feature is not enabled, srcStageMask must not contain VK_PIPELINE_STAGE_TESSELLATION_CONTROL_SHADER_BIT or VK_PIPELINE_STAGE_TESSELLATION_EVALUATION_SHADER_BIT

  • VUID-vkCmdWaitEvents-srcStageMask-04092
    If the conditionalRendering feature is not enabled, srcStageMask must not contain VK_PIPELINE_STAGE_CONDITIONAL_RENDERING_BIT_EXT

  • VUID-vkCmdWaitEvents-srcStageMask-04093
    If the fragmentDensityMap feature is not enabled, srcStageMask must not contain VK_PIPELINE_STAGE_FRAGMENT_DENSITY_PROCESS_BIT_EXT

  • VUID-vkCmdWaitEvents-srcStageMask-04094
    If the transformFeedback feature is not enabled, srcStageMask must not contain VK_PIPELINE_STAGE_TRANSFORM_FEEDBACK_BIT_EXT

  • VUID-vkCmdWaitEvents-srcStageMask-04095
    If the meshShader feature is not enabled, srcStageMask must not contain VK_PIPELINE_STAGE_MESH_SHADER_BIT_EXT

  • VUID-vkCmdWaitEvents-srcStageMask-04096
    If the taskShader feature is not enabled, srcStageMask must not contain VK_PIPELINE_STAGE_TASK_SHADER_BIT_EXT

  • VUID-vkCmdWaitEvents-srcStageMask-07318
    If neither the shadingRateImage or attachmentFragmentShadingRate are enabled, srcStageMask must not contain VK_PIPELINE_STAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR

  • VUID-vkCmdWaitEvents-srcStageMask-03937
    If the synchronization2 feature is not enabled, srcStageMask must not be 0

  • VUID-vkCmdWaitEvents-srcStageMask-07949
    If neither the VK_NV_ray_tracing extension or rayTracingPipeline feature are enabled, srcStageMask must not contain VK_PIPELINE_STAGE_RAY_TRACING_SHADER_BIT_KHR

  • VUID-vkCmdWaitEvents-srcAccessMask-06257
    If the rayQuery feature is not enabled and a memory barrier srcAccessMask includes VK_ACCESS_ACCELERATION_STRUCTURE_READ_BIT_KHR, srcStageMask must not include any of the VK_PIPELINE_STAGE_*_SHADER_BIT stages except VK_PIPELINE_STAGE_RAY_TRACING_SHADER_BIT_KHR

  • VUID-vkCmdWaitEvents-dstStageMask-04090
    If the geometryShader feature is not enabled, dstStageMask must not contain VK_PIPELINE_STAGE_GEOMETRY_SHADER_BIT

  • VUID-vkCmdWaitEvents-dstStageMask-04091
    If the tessellationShader feature is not enabled, dstStageMask must not contain VK_PIPELINE_STAGE_TESSELLATION_CONTROL_SHADER_BIT or VK_PIPELINE_STAGE_TESSELLATION_EVALUATION_SHADER_BIT

  • VUID-vkCmdWaitEvents-dstStageMask-04092
    If the conditionalRendering feature is not enabled, dstStageMask must not contain VK_PIPELINE_STAGE_CONDITIONAL_RENDERING_BIT_EXT

  • VUID-vkCmdWaitEvents-dstStageMask-04093
    If the fragmentDensityMap feature is not enabled, dstStageMask must not contain VK_PIPELINE_STAGE_FRAGMENT_DENSITY_PROCESS_BIT_EXT

  • VUID-vkCmdWaitEvents-dstStageMask-04094
    If the transformFeedback feature is not enabled, dstStageMask must not contain VK_PIPELINE_STAGE_TRANSFORM_FEEDBACK_BIT_EXT

  • VUID-vkCmdWaitEvents-dstStageMask-04095
    If the meshShader feature is not enabled, dstStageMask must not contain VK_PIPELINE_STAGE_MESH_SHADER_BIT_EXT

  • VUID-vkCmdWaitEvents-dstStageMask-04096
    If the taskShader feature is not enabled, dstStageMask must not contain VK_PIPELINE_STAGE_TASK_SHADER_BIT_EXT

  • VUID-vkCmdWaitEvents-dstStageMask-07318
    If neither the shadingRateImage or attachmentFragmentShadingRate are enabled, dstStageMask must not contain VK_PIPELINE_STAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR

  • VUID-vkCmdWaitEvents-dstStageMask-03937
    If the synchronization2 feature is not enabled, dstStageMask must not be 0

  • VUID-vkCmdWaitEvents-dstStageMask-07949
    If neither the VK_NV_ray_tracing extension or rayTracingPipeline feature are enabled, dstStageMask must not contain VK_PIPELINE_STAGE_RAY_TRACING_SHADER_BIT_KHR

  • VUID-vkCmdWaitEvents-dstAccessMask-06257
    If the rayQuery feature is not enabled and a memory barrier dstAccessMask includes VK_ACCESS_ACCELERATION_STRUCTURE_READ_BIT_KHR, dstStageMask must not include any of the VK_PIPELINE_STAGE_*_SHADER_BIT stages except VK_PIPELINE_STAGE_RAY_TRACING_SHADER_BIT_KHR

  • VUID-vkCmdWaitEvents-srcAccessMask-02815
    The srcAccessMask member of each element of pMemoryBarriers must only include access flags that are supported by one or more of the pipeline stages in srcStageMask, as specified in the table of supported access types

  • VUID-vkCmdWaitEvents-dstAccessMask-02816
    The dstAccessMask member of each element of pMemoryBarriers must only include access flags that are supported by one or more of the pipeline stages in dstStageMask, as specified in the table of supported access types

  • VUID-vkCmdWaitEvents-pBufferMemoryBarriers-02817
    For any element of pBufferMemoryBarriers, if its srcQueueFamilyIndex and dstQueueFamilyIndex members are equal, or if its srcQueueFamilyIndex is the queue family index that was used to create the command pool that commandBuffer was allocated from, then its srcAccessMask member must only contain access flags that are supported by one or more of the pipeline stages in srcStageMask, as specified in the table of supported access types

  • VUID-vkCmdWaitEvents-pBufferMemoryBarriers-02818
    For any element of pBufferMemoryBarriers, if its srcQueueFamilyIndex and dstQueueFamilyIndex members are equal, or if its dstQueueFamilyIndex is the queue family index that was used to create the command pool that commandBuffer was allocated from, then its dstAccessMask member must only contain access flags that are supported by one or more of the pipeline stages in dstStageMask, as specified in the table of supported access types

  • VUID-vkCmdWaitEvents-pImageMemoryBarriers-02819
    For any element of pImageMemoryBarriers, if its srcQueueFamilyIndex and dstQueueFamilyIndex members are equal, or if its srcQueueFamilyIndex is the queue family index that was used to create the command pool that commandBuffer was allocated from, then its srcAccessMask member must only contain access flags that are supported by one or more of the pipeline stages in srcStageMask, as specified in the table of supported access types

  • VUID-vkCmdWaitEvents-pImageMemoryBarriers-02820
    For any element of pImageMemoryBarriers, if its srcQueueFamilyIndex and dstQueueFamilyIndex members are equal, or if its dstQueueFamilyIndex is the queue family index that was used to create the command pool that commandBuffer was allocated from, then its dstAccessMask member must only contain access flags that are supported by one or more of the pipeline stages in dstStageMask, as specified in the table of supported access types

  • VUID-vkCmdWaitEvents-srcStageMask-06459
    Any pipeline stage included in srcStageMask must be supported by the capabilities of the queue family specified by the queueFamilyIndex member of the VkCommandPoolCreateInfo structure that was used to create the VkCommandPool that commandBuffer was allocated from, as specified in the table of supported pipeline stages

  • VUID-vkCmdWaitEvents-dstStageMask-06460
    Any pipeline stage included in dstStageMask must be supported by the capabilities of the queue family specified by the queueFamilyIndex member of the VkCommandPoolCreateInfo structure that was used to create the VkCommandPool that commandBuffer was allocated from, as specified in the table of supported pipeline stages

  • VUID-vkCmdWaitEvents-srcStageMask-01158
    srcStageMask must be the bitwise OR of the stageMask parameter used in previous calls to vkCmdSetEvent with any of the elements of pEvents and VK_PIPELINE_STAGE_HOST_BIT if any of the elements of pEvents was set using vkSetEvent

  • VUID-vkCmdWaitEvents-srcStageMask-07308
    If vkCmdWaitEvents is being called inside a render pass instance, srcStageMask must not include VK_PIPELINE_STAGE_HOST_BIT

  • VUID-vkCmdWaitEvents-srcQueueFamilyIndex-02803
    The srcQueueFamilyIndex and dstQueueFamilyIndex members of any element of pBufferMemoryBarriers or pImageMemoryBarriers must be equal

  • VUID-vkCmdWaitEvents-commandBuffer-01167
    commandBuffer’s current device mask must include exactly one physical device

  • VUID-vkCmdWaitEvents-pEvents-03847
    Elements of pEvents must not have been signaled by vkCmdSetEvent2

Valid Usage (Implicit)

  • VUID-vkCmdWaitEvents-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdWaitEvents-pEvents-parameter
    pEvents must be a valid pointer to an array of eventCount valid VkEvent handles

  • VUID-vkCmdWaitEvents-srcStageMask-parameter
    srcStageMask must be a valid combination of VkPipelineStageFlagBits values

  • VUID-vkCmdWaitEvents-dstStageMask-parameter
    dstStageMask must be a valid combination of VkPipelineStageFlagBits values

  • VUID-vkCmdWaitEvents-pMemoryBarriers-parameter
    If memoryBarrierCount is not 0, pMemoryBarriers must be a valid pointer to an array of memoryBarrierCount valid VkMemoryBarrier structures

  • VUID-vkCmdWaitEvents-pBufferMemoryBarriers-parameter
    If bufferMemoryBarrierCount is not 0, pBufferMemoryBarriers must be a valid pointer to an array of bufferMemoryBarrierCount valid VkBufferMemoryBarrier structures

  • VUID-vkCmdWaitEvents-pImageMemoryBarriers-parameter
    If imageMemoryBarrierCount is not 0, pImageMemoryBarriers must be a valid pointer to an array of imageMemoryBarrierCount valid VkImageMemoryBarrier structures

  • VUID-vkCmdWaitEvents-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdWaitEvents-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support graphics, compute, decode, or encode operations

  • VUID-vkCmdWaitEvents-eventCount-arraylength
    eventCount must be greater than 0

  • VUID-vkCmdWaitEvents-commonparent
    Both of commandBuffer, and the elements of pEvents must have been created, allocated, or retrieved from the same VkDevice

Host Synchronization

  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Video Coding Scope Supported Queue Types Command Type

Primary
Secondary

Both

Both

Graphics
Compute
Decode
Encode

Synchronization

7.6. Pipeline Barriers

To record a pipeline barrier, call:

// Provided by VK_VERSION_1_3
void vkCmdPipelineBarrier2(
    VkCommandBuffer                             commandBuffer,
    const VkDependencyInfo*                     pDependencyInfo);

or the equivalent command

// Provided by VK_KHR_synchronization2
void vkCmdPipelineBarrier2KHR(
    VkCommandBuffer                             commandBuffer,
    const VkDependencyInfo*                     pDependencyInfo);

  • commandBuffer is the command buffer into which the command is recorded.

  • pDependencyInfo is a pointer to a VkDependencyInfo structure defining the scopes of this operation.

When vkCmdPipelineBarrier2 is submitted to a queue, it defines memory dependencies between commands that were submitted to the same queue before it, and those submitted to the same queue after it.

The first synchronization scope and access scope of each memory dependency defined by pDependencyInfo are applied to operations that occurred earlier in submission order.

The second synchronization scope and access scope of each memory dependency defined by pDependencyInfo are applied to operations that occurred later in submission order.

If vkCmdPipelineBarrier2 is recorded within a render pass instance, the synchronization scopes are limited to a subset of operations within the same subpass or render pass instance.

Valid Usage

  • VUID-vkCmdPipelineBarrier2-None-07889
    If vkCmdPipelineBarrier2 is called within a render pass instance using a VkRenderPass object, the render pass must have been created with at least one subpass dependency that expresses a dependency from the current subpass to itself, does not include VK_DEPENDENCY_BY_REGION_BIT if this command does not, does not include VK_DEPENDENCY_VIEW_LOCAL_BIT if this command does not, and has synchronization scopes and access scopes that are all supersets of the scopes defined in this command

  • VUID-vkCmdPipelineBarrier2-bufferMemoryBarrierCount-01178
    If vkCmdPipelineBarrier2 is called within a render pass instance using a VkRenderPass object, it must not include any buffer memory barriers

  • VUID-vkCmdPipelineBarrier2-image-04073
    If vkCmdPipelineBarrier2 is called within a render pass instance using a VkRenderPass object, the image member of any image memory barrier included in this command must be an attachment used in the current subpass both as an input attachment, and as either a color, color resolve, or depth/stencil attachment

  • VUID-vkCmdPipelineBarrier2-image-09373
    If vkCmdPipelineBarrier2 is called within a render pass instance using a VkRenderPass object, and the image member of any image memory barrier is a color resolve attachment, the corresponding color attachment must be VK_ATTACHMENT_UNUSED

  • VUID-vkCmdPipelineBarrier2-image-09374
    If vkCmdPipelineBarrier2 is called within a render pass instance using a VkRenderPass object, and the image member of any image memory barrier is a color resolve attachment, it must have been created with a non-zero VkExternalFormatANDROID::externalFormat value

  • VUID-vkCmdPipelineBarrier2-oldLayout-01181
    If vkCmdPipelineBarrier2 is called within a render pass instance, the oldLayout and newLayout members of any image memory barrier included in this command must be equal

  • VUID-vkCmdPipelineBarrier2-srcQueueFamilyIndex-01182
    If vkCmdPipelineBarrier2 is called within a render pass instance, the srcQueueFamilyIndex and dstQueueFamilyIndex members of any memory barrier included in this command must be equal

  • VUID-vkCmdPipelineBarrier2-None-07890
    If vkCmdPipelineBarrier2 is called within a render pass instance, and the source stage masks of any memory barriers include framebuffer-space stages, destination stage masks of all memory barriers must only include framebuffer-space stages

  • VUID-vkCmdPipelineBarrier2-dependencyFlags-07891
    If vkCmdPipelineBarrier2 is called within a render pass instance, and the source stage masks of any memory barriers include framebuffer-space stages, then dependencyFlags must include VK_DEPENDENCY_BY_REGION_BIT

  • VUID-vkCmdPipelineBarrier2-None-07892
    If vkCmdPipelineBarrier2 is called within a render pass instance, the source and destination stage masks of any memory barriers must only include graphics pipeline stages

  • VUID-vkCmdPipelineBarrier2-dependencyFlags-01186
    If vkCmdPipelineBarrier2 is called outside of a render pass instance, the dependency flags must not include VK_DEPENDENCY_VIEW_LOCAL_BIT

  • VUID-vkCmdPipelineBarrier2-None-07893
    If vkCmdPipelineBarrier2 is called inside a render pass instance, and there is more than one view in the current subpass, dependency flags must include VK_DEPENDENCY_VIEW_LOCAL_BIT

  • VUID-vkCmdPipelineBarrier2-None-09553
    If none of the shaderTileImageColorReadAccess, shaderTileImageStencilReadAccess, or shaderTileImageDepthReadAccess features are enabled, and the dynamicRenderingLocalRead feature is not enabled, vkCmdPipelineBarrier2 must not be called within a render pass instance started with vkCmdBeginRendering

  • VUID-vkCmdPipelineBarrier2-None-09554
    If the dynamicRenderingLocalRead feature is not enabled, and vkCmdPipelineBarrier2 is called within a render pass instance started with vkCmdBeginRendering, there must be no buffer or image memory barriers specified by this command

  • VUID-vkCmdPipelineBarrier2-None-09586
    If the dynamicRenderingLocalRead feature is not enabled, and vkCmdPipelineBarrier2 is called within a render pass instance started with vkCmdBeginRendering, memory barriers specified by this command must only include VK_ACCESS_2_COLOR_ATTACHMENT_READ_BIT, VK_ACCESS_2_COLOR_ATTACHMENT_WRITE_BIT, VK_ACCESS_2_DEPTH_STENCIL_ATTACHMENT_READ_BIT, or VK_ACCESS_2_DEPTH_STENCIL_ATTACHMENT_WRITE_BIT in their access masks

  • VUID-vkCmdPipelineBarrier2-image-09555
    If vkCmdPipelineBarrier2 is called within a render pass instance started with vkCmdBeginRendering, and the image member of any image memory barrier is used as an attachment in the current render pass instance, it must be in the VK_IMAGE_LAYOUT_RENDERING_LOCAL_READ_KHR or VK_IMAGE_LAYOUT_GENERAL layout

  • VUID-vkCmdPipelineBarrier2-srcStageMask-09556
    If vkCmdPipelineBarrier2 is called within a render pass instance started with vkCmdBeginRendering, this command must only specify framebuffer-space stages in srcStageMask and dstStageMask

  • VUID-vkCmdPipelineBarrier2-synchronization2-03848
    The synchronization2 feature must be enabled

  • VUID-vkCmdPipelineBarrier2-srcStageMask-09673
    The srcStageMask member of any element of the pMemoryBarriers member of pDependencyInfo must only include pipeline stages valid for the queue family that was used to create the command pool that commandBuffer was allocated from

  • VUID-vkCmdPipelineBarrier2-dstStageMask-09674
    The dstStageMask member of any element of the pMemoryBarriers member of pDependencyInfo must only include pipeline stages valid for the queue family that was used to create the command pool that commandBuffer was allocated from

  • VUID-vkCmdPipelineBarrier2-srcStageMask-09675
    If a buffer or image memory barrier does not specify an acquire operation, the respective srcStageMask member of the element of the pBufferMemoryBarriers or pImageMemoryBarriers members of pDependencyInfo must only include pipeline stages valid for the queue family that was used to create the command pool that commandBuffer was allocated from

  • VUID-vkCmdPipelineBarrier2-dstStageMask-09676
    If a buffer or image memory barrier does not specify an release operation, the respective dstStageMask member of the element of the pBufferMemoryBarriers or pImageMemoryBarriers members of pDependencyInfo must only include pipeline stages valid for the queue family that was used to create the command pool that commandBuffer was allocated from

Valid Usage (Implicit)

  • VUID-vkCmdPipelineBarrier2-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdPipelineBarrier2-pDependencyInfo-parameter
    pDependencyInfo must be a valid pointer to a valid VkDependencyInfo structure

  • VUID-vkCmdPipelineBarrier2-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdPipelineBarrier2-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support transfer, graphics, compute, decode, or encode operations

Host Synchronization

  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Video Coding Scope Supported Queue Types Command Type

Primary
Secondary

Both

Both

Transfer
Graphics
Compute
Decode
Encode

Synchronization

To record a pipeline barrier, call:

// Provided by VK_VERSION_1_0
void vkCmdPipelineBarrier(
    VkCommandBuffer                             commandBuffer,
    VkPipelineStageFlags                        srcStageMask,
    VkPipelineStageFlags                        dstStageMask,
    VkDependencyFlags                           dependencyFlags,
    uint32_t                                    memoryBarrierCount,
    const VkMemoryBarrier*                      pMemoryBarriers,
    uint32_t                                    bufferMemoryBarrierCount,
    const VkBufferMemoryBarrier*                pBufferMemoryBarriers,
    uint32_t                                    imageMemoryBarrierCount,
    const VkImageMemoryBarrier*                 pImageMemoryBarriers);

  • commandBuffer is the command buffer into which the command is recorded.

  • srcStageMask is a bitmask of VkPipelineStageFlagBits specifying the source stages.

  • dstStageMask is a bitmask of VkPipelineStageFlagBits specifying the destination stages.

  • dependencyFlags is a bitmask of VkDependencyFlagBits specifying how execution and memory dependencies are formed.

  • memoryBarrierCount is the length of the pMemoryBarriers array.

  • pMemoryBarriers is a pointer to an array of VkMemoryBarrier structures.

  • bufferMemoryBarrierCount is the length of the pBufferMemoryBarriers array.

  • pBufferMemoryBarriers is a pointer to an array of VkBufferMemoryBarrier structures.

  • imageMemoryBarrierCount is the length of the pImageMemoryBarriers array.

  • pImageMemoryBarriers is a pointer to an array of VkImageMemoryBarrier structures.

vkCmdPipelineBarrier operates almost identically to vkCmdPipelineBarrier2, except that the scopes and barriers are defined as direct parameters rather than being defined by a VkDependencyInfo.

When vkCmdPipelineBarrier is submitted to a queue, it defines a memory dependency between commands that were submitted to the same queue before it, and those submitted to the same queue after it.

If vkCmdPipelineBarrier was recorded outside a render pass instance, the first synchronization scope includes all commands that occur earlier in submission order. If vkCmdPipelineBarrier was recorded inside a render pass instance, the first synchronization scope includes only commands that occur earlier in submission order within the same subpass. In either case, the first synchronization scope is limited to operations on the pipeline stages determined by the source stage mask specified by srcStageMask.

If vkCmdPipelineBarrier was recorded outside a render pass instance, the second synchronization scope includes all commands that occur later in submission order. If vkCmdPipelineBarrier was recorded inside a render pass instance, the second synchronization scope includes only commands that occur later in submission order within the same subpass. In either case, the second synchronization scope is limited to operations on the pipeline stages determined by the destination stage mask specified by dstStageMask.

The first access scope is limited to accesses in the pipeline stages determined by the source stage mask specified by srcStageMask. Within that, the first access scope only includes the first access scopes defined by elements of the pMemoryBarriers, pBufferMemoryBarriers and pImageMemoryBarriers arrays, which each define a set of memory barriers. If no memory barriers are specified, then the first access scope includes no accesses.

The second access scope is limited to accesses in the pipeline stages determined by the destination stage mask specified by dstStageMask. Within that, the second access scope only includes the second access scopes defined by elements of the pMemoryBarriers, pBufferMemoryBarriers and pImageMemoryBarriers arrays, which each define a set of memory barriers. If no memory barriers are specified, then the second access scope includes no accesses.

If dependencyFlags includes VK_DEPENDENCY_BY_REGION_BIT, then any dependency between framebuffer-space pipeline stages is framebuffer-local - otherwise it is framebuffer-global.

Valid Usage

  • VUID-vkCmdPipelineBarrier-srcStageMask-04090
    If the geometryShader feature is not enabled, srcStageMask must not contain VK_PIPELINE_STAGE_GEOMETRY_SHADER_BIT

  • VUID-vkCmdPipelineBarrier-srcStageMask-04091
    If the tessellationShader feature is not enabled, srcStageMask must not contain VK_PIPELINE_STAGE_TESSELLATION_CONTROL_SHADER_BIT or VK_PIPELINE_STAGE_TESSELLATION_EVALUATION_SHADER_BIT

  • VUID-vkCmdPipelineBarrier-srcStageMask-04092
    If the conditionalRendering feature is not enabled, srcStageMask must not contain VK_PIPELINE_STAGE_CONDITIONAL_RENDERING_BIT_EXT

  • VUID-vkCmdPipelineBarrier-srcStageMask-04093
    If the fragmentDensityMap feature is not enabled, srcStageMask must not contain VK_PIPELINE_STAGE_FRAGMENT_DENSITY_PROCESS_BIT_EXT

  • VUID-vkCmdPipelineBarrier-srcStageMask-04094
    If the transformFeedback feature is not enabled, srcStageMask must not contain VK_PIPELINE_STAGE_TRANSFORM_FEEDBACK_BIT_EXT

  • VUID-vkCmdPipelineBarrier-srcStageMask-04095
    If the meshShader feature is not enabled, srcStageMask must not contain VK_PIPELINE_STAGE_MESH_SHADER_BIT_EXT

  • VUID-vkCmdPipelineBarrier-srcStageMask-04096
    If the taskShader feature is not enabled, srcStageMask must not contain VK_PIPELINE_STAGE_TASK_SHADER_BIT_EXT

  • VUID-vkCmdPipelineBarrier-srcStageMask-07318
    If neither the shadingRateImage or attachmentFragmentShadingRate are enabled, srcStageMask must not contain VK_PIPELINE_STAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR

  • VUID-vkCmdPipelineBarrier-srcStageMask-03937
    If the synchronization2 feature is not enabled, srcStageMask must not be 0

  • VUID-vkCmdPipelineBarrier-srcStageMask-07949
    If neither the VK_NV_ray_tracing extension or rayTracingPipeline feature are enabled, srcStageMask must not contain VK_PIPELINE_STAGE_RAY_TRACING_SHADER_BIT_KHR

  • VUID-vkCmdPipelineBarrier-srcAccessMask-06257
    If the rayQuery feature is not enabled and a memory barrier srcAccessMask includes VK_ACCESS_ACCELERATION_STRUCTURE_READ_BIT_KHR, srcStageMask must not include any of the VK_PIPELINE_STAGE_*_SHADER_BIT stages except VK_PIPELINE_STAGE_RAY_TRACING_SHADER_BIT_KHR

  • VUID-vkCmdPipelineBarrier-dstStageMask-04090
    If the geometryShader feature is not enabled, dstStageMask must not contain VK_PIPELINE_STAGE_GEOMETRY_SHADER_BIT

  • VUID-vkCmdPipelineBarrier-dstStageMask-04091
    If the tessellationShader feature is not enabled, dstStageMask must not contain VK_PIPELINE_STAGE_TESSELLATION_CONTROL_SHADER_BIT or VK_PIPELINE_STAGE_TESSELLATION_EVALUATION_SHADER_BIT

  • VUID-vkCmdPipelineBarrier-dstStageMask-04092
    If the conditionalRendering feature is not enabled, dstStageMask must not contain VK_PIPELINE_STAGE_CONDITIONAL_RENDERING_BIT_EXT

  • VUID-vkCmdPipelineBarrier-dstStageMask-04093
    If the fragmentDensityMap feature is not enabled, dstStageMask must not contain VK_PIPELINE_STAGE_FRAGMENT_DENSITY_PROCESS_BIT_EXT

  • VUID-vkCmdPipelineBarrier-dstStageMask-04094
    If the transformFeedback feature is not enabled, dstStageMask must not contain VK_PIPELINE_STAGE_TRANSFORM_FEEDBACK_BIT_EXT

  • VUID-vkCmdPipelineBarrier-dstStageMask-04095
    If the meshShader feature is not enabled, dstStageMask must not contain VK_PIPELINE_STAGE_MESH_SHADER_BIT_EXT

  • VUID-vkCmdPipelineBarrier-dstStageMask-04096
    If the taskShader feature is not enabled, dstStageMask must not contain VK_PIPELINE_STAGE_TASK_SHADER_BIT_EXT

  • VUID-vkCmdPipelineBarrier-dstStageMask-07318
    If neither the shadingRateImage or attachmentFragmentShadingRate are enabled, dstStageMask must not contain VK_PIPELINE_STAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR

  • VUID-vkCmdPipelineBarrier-dstStageMask-03937
    If the synchronization2 feature is not enabled, dstStageMask must not be 0

  • VUID-vkCmdPipelineBarrier-dstStageMask-07949
    If neither the VK_NV_ray_tracing extension or rayTracingPipeline feature are enabled, dstStageMask must not contain VK_PIPELINE_STAGE_RAY_TRACING_SHADER_BIT_KHR

  • VUID-vkCmdPipelineBarrier-dstAccessMask-06257
    If the rayQuery feature is not enabled and a memory barrier dstAccessMask includes VK_ACCESS_ACCELERATION_STRUCTURE_READ_BIT_KHR, dstStageMask must not include any of the VK_PIPELINE_STAGE_*_SHADER_BIT stages except VK_PIPELINE_STAGE_RAY_TRACING_SHADER_BIT_KHR

  • VUID-vkCmdPipelineBarrier-srcAccessMask-02815
    The srcAccessMask member of each element of pMemoryBarriers must only include access flags that are supported by one or more of the pipeline stages in srcStageMask, as specified in the table of supported access types

  • VUID-vkCmdPipelineBarrier-dstAccessMask-02816
    The dstAccessMask member of each element of pMemoryBarriers must only include access flags that are supported by one or more of the pipeline stages in dstStageMask, as specified in the table of supported access types

  • VUID-vkCmdPipelineBarrier-pBufferMemoryBarriers-02817
    For any element of pBufferMemoryBarriers, if its srcQueueFamilyIndex and dstQueueFamilyIndex members are equal, or if its srcQueueFamilyIndex is the queue family index that was used to create the command pool that commandBuffer was allocated from, then its srcAccessMask member must only contain access flags that are supported by one or more of the pipeline stages in srcStageMask, as specified in the table of supported access types

  • VUID-vkCmdPipelineBarrier-pBufferMemoryBarriers-02818
    For any element of pBufferMemoryBarriers, if its srcQueueFamilyIndex and dstQueueFamilyIndex members are equal, or if its dstQueueFamilyIndex is the queue family index that was used to create the command pool that commandBuffer was allocated from, then its dstAccessMask member must only contain access flags that are supported by one or more of the pipeline stages in dstStageMask, as specified in the table of supported access types

  • VUID-vkCmdPipelineBarrier-pImageMemoryBarriers-02819
    For any element of pImageMemoryBarriers, if its srcQueueFamilyIndex and dstQueueFamilyIndex members are equal, or if its srcQueueFamilyIndex is the queue family index that was used to create the command pool that commandBuffer was allocated from, then its srcAccessMask member must only contain access flags that are supported by one or more of the pipeline stages in srcStageMask, as specified in the table of supported access types

  • VUID-vkCmdPipelineBarrier-pImageMemoryBarriers-02820
    For any element of pImageMemoryBarriers, if its srcQueueFamilyIndex and dstQueueFamilyIndex members are equal, or if its dstQueueFamilyIndex is the queue family index that was used to create the command pool that commandBuffer was allocated from, then its dstAccessMask member must only contain access flags that are supported by one or more of the pipeline stages in dstStageMask, as specified in the table of supported access types

  • VUID-vkCmdPipelineBarrier-None-07889
    If vkCmdPipelineBarrier is called within a render pass instance using a VkRenderPass object, the render pass must have been created with at least one subpass dependency that expresses a dependency from the current subpass to itself, does not include VK_DEPENDENCY_BY_REGION_BIT if this command does not, does not include VK_DEPENDENCY_VIEW_LOCAL_BIT if this command does not, and has synchronization scopes and access scopes that are all supersets of the scopes defined in this command

  • VUID-vkCmdPipelineBarrier-bufferMemoryBarrierCount-01178
    If vkCmdPipelineBarrier is called within a render pass instance using a VkRenderPass object, it must not include any buffer memory barriers

  • VUID-vkCmdPipelineBarrier-image-04073
    If vkCmdPipelineBarrier is called within a render pass instance using a VkRenderPass object, the image member of any image memory barrier included in this command must be an attachment used in the current subpass both as an input attachment, and as either a color, color resolve, or depth/stencil attachment

  • VUID-vkCmdPipelineBarrier-image-09373
    If vkCmdPipelineBarrier is called within a render pass instance using a VkRenderPass object, and the image member of any image memory barrier is a color resolve attachment, the corresponding color attachment must be VK_ATTACHMENT_UNUSED

  • VUID-vkCmdPipelineBarrier-image-09374
    If vkCmdPipelineBarrier is called within a render pass instance using a VkRenderPass object, and the image member of any image memory barrier is a color resolve attachment, it must have been created with a non-zero VkExternalFormatANDROID::externalFormat value

  • VUID-vkCmdPipelineBarrier-oldLayout-01181
    If vkCmdPipelineBarrier is called within a render pass instance, the oldLayout and newLayout members of any image memory barrier included in this command must be equal

  • VUID-vkCmdPipelineBarrier-srcQueueFamilyIndex-01182
    If vkCmdPipelineBarrier is called within a render pass instance, the srcQueueFamilyIndex and dstQueueFamilyIndex members of any memory barrier included in this command must be equal

  • VUID-vkCmdPipelineBarrier-None-07890
    If vkCmdPipelineBarrier is called within a render pass instance, and the source stage masks of any memory barriers include framebuffer-space stages, destination stage masks of all memory barriers must only include framebuffer-space stages

  • VUID-vkCmdPipelineBarrier-dependencyFlags-07891
    If vkCmdPipelineBarrier is called within a render pass instance, and the source stage masks of any memory barriers include framebuffer-space stages, then dependencyFlags must include VK_DEPENDENCY_BY_REGION_BIT

  • VUID-vkCmdPipelineBarrier-None-07892
    If vkCmdPipelineBarrier is called within a render pass instance, the source and destination stage masks of any memory barriers must only include graphics pipeline stages

  • VUID-vkCmdPipelineBarrier-dependencyFlags-01186
    If vkCmdPipelineBarrier is called outside of a render pass instance, the dependency flags must not include VK_DEPENDENCY_VIEW_LOCAL_BIT

  • VUID-vkCmdPipelineBarrier-None-07893
    If vkCmdPipelineBarrier is called inside a render pass instance, and there is more than one view in the current subpass, dependency flags must include VK_DEPENDENCY_VIEW_LOCAL_BIT

  • VUID-vkCmdPipelineBarrier-None-09553
    If none of the shaderTileImageColorReadAccess, shaderTileImageStencilReadAccess, or shaderTileImageDepthReadAccess features are enabled, and the dynamicRenderingLocalRead feature is not enabled, vkCmdPipelineBarrier must not be called within a render pass instance started with vkCmdBeginRendering

  • VUID-vkCmdPipelineBarrier-None-09554
    If the dynamicRenderingLocalRead feature is not enabled, and vkCmdPipelineBarrier is called within a render pass instance started with vkCmdBeginRendering, there must be no buffer or image memory barriers specified by this command

  • VUID-vkCmdPipelineBarrier-None-09586
    If the dynamicRenderingLocalRead feature is not enabled, and vkCmdPipelineBarrier is called within a render pass instance started with vkCmdBeginRendering, memory barriers specified by this command must only include VK_ACCESS_2_COLOR_ATTACHMENT_READ_BIT, VK_ACCESS_2_COLOR_ATTACHMENT_WRITE_BIT, VK_ACCESS_2_DEPTH_STENCIL_ATTACHMENT_READ_BIT, or VK_ACCESS_2_DEPTH_STENCIL_ATTACHMENT_WRITE_BIT in their access masks

  • VUID-vkCmdPipelineBarrier-image-09555
    If vkCmdPipelineBarrier is called within a render pass instance started with vkCmdBeginRendering, and the image member of any image memory barrier is used as an attachment in the current render pass instance, it must be in the VK_IMAGE_LAYOUT_RENDERING_LOCAL_READ_KHR or VK_IMAGE_LAYOUT_GENERAL layout

  • VUID-vkCmdPipelineBarrier-srcStageMask-09556
    If vkCmdPipelineBarrier is called within a render pass instance started with vkCmdBeginRendering, this command must only specify framebuffer-space stages in srcStageMask and dstStageMask

  • VUID-vkCmdPipelineBarrier-srcStageMask-06461
    Any pipeline stage included in srcStageMask must be supported by the capabilities of the queue family specified by the queueFamilyIndex member of the VkCommandPoolCreateInfo structure that was used to create the VkCommandPool that commandBuffer was allocated from, as specified in the table of supported pipeline stages

  • VUID-vkCmdPipelineBarrier-dstStageMask-06462
    Any pipeline stage included in dstStageMask must be supported by the capabilities of the queue family specified by the queueFamilyIndex member of the VkCommandPoolCreateInfo structure that was used to create the VkCommandPool that commandBuffer was allocated from, as specified in the table of supported pipeline stages

  • VUID-vkCmdPipelineBarrier-srcStageMask-09633
    If either srcStageMask or dstStageMask includes VK_PIPELINE_STAGE_HOST_BIT, for any element of pImageMemoryBarriers, srcQueueFamilyIndex and dstQueueFamilyIndex must be equal

  • VUID-vkCmdPipelineBarrier-srcStageMask-09634
    If either srcStageMask or dstStageMask includes VK_PIPELINE_STAGE_HOST_BIT, for any element of pBufferMemoryBarriers, srcQueueFamilyIndex and dstQueueFamilyIndex must be equal

Valid Usage (Implicit)

  • VUID-vkCmdPipelineBarrier-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdPipelineBarrier-srcStageMask-parameter
    srcStageMask must be a valid combination of VkPipelineStageFlagBits values

  • VUID-vkCmdPipelineBarrier-dstStageMask-parameter
    dstStageMask must be a valid combination of VkPipelineStageFlagBits values

  • VUID-vkCmdPipelineBarrier-dependencyFlags-parameter
    dependencyFlags must be a valid combination of VkDependencyFlagBits values

  • VUID-vkCmdPipelineBarrier-pMemoryBarriers-parameter
    If memoryBarrierCount is not 0, pMemoryBarriers must be a valid pointer to an array of memoryBarrierCount valid VkMemoryBarrier structures

  • VUID-vkCmdPipelineBarrier-pBufferMemoryBarriers-parameter
    If bufferMemoryBarrierCount is not 0, pBufferMemoryBarriers must be a valid pointer to an array of bufferMemoryBarrierCount valid VkBufferMemoryBarrier structures

  • VUID-vkCmdPipelineBarrier-pImageMemoryBarriers-parameter
    If imageMemoryBarrierCount is not 0, pImageMemoryBarriers must be a valid pointer to an array of imageMemoryBarrierCount valid VkImageMemoryBarrier structures

  • VUID-vkCmdPipelineBarrier-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdPipelineBarrier-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support transfer, graphics, compute, decode, or encode operations

Host Synchronization

  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Video Coding Scope Supported Queue Types Command Type

Primary
Secondary

Both

Both

Transfer
Graphics
Compute
Decode
Encode

Synchronization

Bits which can be set in vkCmdPipelineBarrier::dependencyFlags, specifying how execution and memory dependencies are formed, are:

// Provided by VK_VERSION_1_0
typedef enum VkDependencyFlagBits {
    VK_DEPENDENCY_BY_REGION_BIT = 0x00000001,
  // Provided by VK_VERSION_1_1
    VK_DEPENDENCY_DEVICE_GROUP_BIT = 0x00000004,
  // Provided by VK_VERSION_1_1
    VK_DEPENDENCY_VIEW_LOCAL_BIT = 0x00000002,
  // Provided by VK_EXT_attachment_feedback_loop_layout
    VK_DEPENDENCY_FEEDBACK_LOOP_BIT_EXT = 0x00000008,
  // Provided by VK_KHR_multiview
    VK_DEPENDENCY_VIEW_LOCAL_BIT_KHR = VK_DEPENDENCY_VIEW_LOCAL_BIT,
  // Provided by VK_KHR_device_group
    VK_DEPENDENCY_DEVICE_GROUP_BIT_KHR = VK_DEPENDENCY_DEVICE_GROUP_BIT,
} VkDependencyFlagBits;

  • VK_DEPENDENCY_BY_REGION_BIT specifies that dependencies will be framebuffer-local.

  • VK_DEPENDENCY_VIEW_LOCAL_BIT specifies that dependencies will be view-local.

  • VK_DEPENDENCY_DEVICE_GROUP_BIT specifies that dependencies are non-device-local.

  • VK_DEPENDENCY_FEEDBACK_LOOP_BIT_EXT specifies that the render pass will write to and read from the same image using the VK_IMAGE_LAYOUT_ATTACHMENT_FEEDBACK_LOOP_OPTIMAL_EXT layout.

// Provided by VK_VERSION_1_0
typedef VkFlags VkDependencyFlags;

VkDependencyFlags is a bitmask type for setting a mask of zero or more VkDependencyFlagBits.

7.7. Memory Barriers

Memory barriers are used to explicitly control access to buffer and image subresource ranges. Memory barriers are used to transfer ownership between queue families, change image layouts, and define availability and visibility operations. They explicitly define the access types and buffer and image subresource ranges that are included in the access scopes of a memory dependency that is created by a synchronization command that includes them.

7.7.1. Global Memory Barriers

Global memory barriers apply to memory accesses involving all memory objects that exist at the time of its execution.

The VkMemoryBarrier2 structure is defined as:

// Provided by VK_VERSION_1_3
typedef struct VkMemoryBarrier2 {
    VkStructureType          sType;
    const void*              pNext;
    VkPipelineStageFlags2    srcStageMask;
    VkAccessFlags2           srcAccessMask;
    VkPipelineStageFlags2    dstStageMask;
    VkAccessFlags2           dstAccessMask;
} VkMemoryBarrier2;

or the equivalent

// Provided by VK_KHR_synchronization2
typedef VkMemoryBarrier2 VkMemoryBarrier2KHR;

This structure defines a memory dependency affecting all device memory.

The first synchronization scope and access scope described by this structure include only operations and memory accesses specified by srcStageMask and srcAccessMask.

The second synchronization scope and access scope described by this structure include only operations and memory accesses specified by dstStageMask and dstAccessMask.

Valid Usage

  • VUID-VkMemoryBarrier2-srcStageMask-03929
    If the geometryShader feature is not enabled, srcStageMask must not contain VK_PIPELINE_STAGE_2_GEOMETRY_SHADER_BIT

  • VUID-VkMemoryBarrier2-srcStageMask-03930
    If the tessellationShader feature is not enabled, srcStageMask must not contain VK_PIPELINE_STAGE_2_TESSELLATION_CONTROL_SHADER_BIT or VK_PIPELINE_STAGE_2_TESSELLATION_EVALUATION_SHADER_BIT

  • VUID-VkMemoryBarrier2-srcStageMask-03931
    If the conditionalRendering feature is not enabled, srcStageMask must not contain VK_PIPELINE_STAGE_2_CONDITIONAL_RENDERING_BIT_EXT

  • VUID-VkMemoryBarrier2-srcStageMask-03932
    If the fragmentDensityMap feature is not enabled, srcStageMask must not contain VK_PIPELINE_STAGE_2_FRAGMENT_DENSITY_PROCESS_BIT_EXT

  • VUID-VkMemoryBarrier2-srcStageMask-03933
    If the transformFeedback feature is not enabled, srcStageMask must not contain VK_PIPELINE_STAGE_2_TRANSFORM_FEEDBACK_BIT_EXT

  • VUID-VkMemoryBarrier2-srcStageMask-03934
    If the meshShader feature is not enabled, srcStageMask must not contain VK_PIPELINE_STAGE_2_MESH_SHADER_BIT_EXT

  • VUID-VkMemoryBarrier2-srcStageMask-03935
    If the taskShader feature is not enabled, srcStageMask must not contain VK_PIPELINE_STAGE_2_TASK_SHADER_BIT_EXT

  • VUID-VkMemoryBarrier2-srcStageMask-07316
    If neither the shadingRateImage or attachmentFragmentShadingRate are enabled, srcStageMask must not contain VK_PIPELINE_STAGE_2_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR

  • VUID-VkMemoryBarrier2-srcStageMask-04957
    If the subpassShading feature is not enabled, srcStageMask must not contain VK_PIPELINE_STAGE_2_SUBPASS_SHADER_BIT_HUAWEI

  • VUID-VkMemoryBarrier2-srcStageMask-04995
    If the invocationMask feature is not enabled, srcStageMask must not contain VK_PIPELINE_STAGE_2_INVOCATION_MASK_BIT_HUAWEI

  • VUID-VkMemoryBarrier2-srcStageMask-07946
    If neither the VK_NV_ray_tracing extension or rayTracingPipeline feature are enabled, srcStageMask must not contain VK_PIPELINE_STAGE_2_RAY_TRACING_SHADER_BIT_KHR

  • VUID-VkMemoryBarrier2-srcAccessMask-03900
    If srcAccessMask includes VK_ACCESS_2_INDIRECT_COMMAND_READ_BIT, srcStageMask must include VK_PIPELINE_STAGE_2_DRAW_INDIRECT_BIT, VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_BUILD_BIT_KHR, VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkMemoryBarrier2-srcAccessMask-03901
    If srcAccessMask includes VK_ACCESS_2_INDEX_READ_BIT, srcStageMask must include VK_PIPELINE_STAGE_2_INDEX_INPUT_BIT, VK_PIPELINE_STAGE_2_VERTEX_INPUT_BIT, VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkMemoryBarrier2-srcAccessMask-03902
    If srcAccessMask includes VK_ACCESS_2_VERTEX_ATTRIBUTE_READ_BIT, srcStageMask must include VK_PIPELINE_STAGE_2_VERTEX_ATTRIBUTE_INPUT_BIT, VK_PIPELINE_STAGE_2_VERTEX_INPUT_BIT, VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkMemoryBarrier2-srcAccessMask-03903
    If srcAccessMask includes VK_ACCESS_2_INPUT_ATTACHMENT_READ_BIT, srcStageMask must include VK_PIPELINE_STAGE_2_FRAGMENT_SHADER_BIT, VK_PIPELINE_STAGE_2_SUBPASS_SHADER_BIT_HUAWEI, VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkMemoryBarrier2-srcAccessMask-03904
    If srcAccessMask includes VK_ACCESS_2_UNIFORM_READ_BIT, srcStageMask must include VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT, or one of the VK_PIPELINE_STAGE_*_SHADER_BIT stages

  • VUID-VkMemoryBarrier2-srcAccessMask-03905
    If srcAccessMask includes VK_ACCESS_2_SHADER_SAMPLED_READ_BIT, srcStageMask must include VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT, or one of the VK_PIPELINE_STAGE_*_SHADER_BIT stages

  • VUID-VkMemoryBarrier2-srcAccessMask-03906
    If srcAccessMask includes VK_ACCESS_2_SHADER_STORAGE_READ_BIT, srcStageMask must include VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT, or one of the VK_PIPELINE_STAGE_*_SHADER_BIT stages

  • VUID-VkMemoryBarrier2-srcAccessMask-03907
    If srcAccessMask includes VK_ACCESS_2_SHADER_STORAGE_WRITE_BIT, srcStageMask must include VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT, or one of the VK_PIPELINE_STAGE_*_SHADER_BIT stages

  • VUID-VkMemoryBarrier2-srcAccessMask-07454
    If srcAccessMask includes VK_ACCESS_2_SHADER_READ_BIT, srcStageMask must include VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT, VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_BUILD_BIT_KHR, VK_PIPELINE_STAGE_2_MICROMAP_BUILD_BIT_EXT, or one of the VK_PIPELINE_STAGE_*_SHADER_BIT stages

  • VUID-VkMemoryBarrier2-srcAccessMask-03909
    If srcAccessMask includes VK_ACCESS_2_SHADER_WRITE_BIT, srcStageMask must include VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT, or one of the VK_PIPELINE_STAGE_*_SHADER_BIT stages

  • VUID-VkMemoryBarrier2-srcAccessMask-03910
    If srcAccessMask includes VK_ACCESS_2_COLOR_ATTACHMENT_READ_BIT, srcStageMask must include VK_PIPELINE_STAGE_2_COLOR_ATTACHMENT_OUTPUT_BIT VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkMemoryBarrier2-srcAccessMask-03911
    If srcAccessMask includes VK_ACCESS_2_COLOR_ATTACHMENT_WRITE_BIT, srcStageMask must include VK_PIPELINE_STAGE_2_COLOR_ATTACHMENT_OUTPUT_BIT VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkMemoryBarrier2-srcAccessMask-03912
    If srcAccessMask includes VK_ACCESS_2_DEPTH_STENCIL_ATTACHMENT_READ_BIT, srcStageMask must include VK_PIPELINE_STAGE_2_EARLY_FRAGMENT_TESTS_BIT, VK_PIPELINE_STAGE_2_LATE_FRAGMENT_TESTS_BIT, VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkMemoryBarrier2-srcAccessMask-03913
    If srcAccessMask includes VK_ACCESS_2_DEPTH_STENCIL_ATTACHMENT_WRITE_BIT, srcStageMask must include VK_PIPELINE_STAGE_2_EARLY_FRAGMENT_TESTS_BIT, VK_PIPELINE_STAGE_2_LATE_FRAGMENT_TESTS_BIT, VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkMemoryBarrier2-srcAccessMask-03914
    If srcAccessMask includes VK_ACCESS_2_TRANSFER_READ_BIT, srcStageMask must include VK_PIPELINE_STAGE_2_COPY_BIT, VK_PIPELINE_STAGE_2_BLIT_BIT, VK_PIPELINE_STAGE_2_RESOLVE_BIT, VK_PIPELINE_STAGE_2_ALL_TRANSFER_BIT, VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_BUILD_BIT_KHR, VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_COPY_BIT_KHR, or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkMemoryBarrier2-srcAccessMask-03915
    If srcAccessMask includes VK_ACCESS_2_TRANSFER_WRITE_BIT, srcStageMask must include VK_PIPELINE_STAGE_2_COPY_BIT, VK_PIPELINE_STAGE_2_BLIT_BIT, VK_PIPELINE_STAGE_2_RESOLVE_BIT, VK_PIPELINE_STAGE_2_CLEAR_BIT, VK_PIPELINE_STAGE_2_ALL_TRANSFER_BIT, VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_BUILD_BIT_KHR, or VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_COPY_BIT_KHR, VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkMemoryBarrier2-srcAccessMask-03916
    If srcAccessMask includes VK_ACCESS_2_HOST_READ_BIT, srcStageMask must include VK_PIPELINE_STAGE_2_HOST_BIT

  • VUID-VkMemoryBarrier2-srcAccessMask-03917
    If srcAccessMask includes VK_ACCESS_2_HOST_WRITE_BIT, srcStageMask must include VK_PIPELINE_STAGE_2_HOST_BIT

  • VUID-VkMemoryBarrier2-srcAccessMask-03918
    If srcAccessMask includes VK_ACCESS_2_CONDITIONAL_RENDERING_READ_BIT_EXT, srcStageMask must include VK_PIPELINE_STAGE_2_CONDITIONAL_RENDERING_BIT_EXT, VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkMemoryBarrier2-srcAccessMask-03919
    If srcAccessMask includes VK_ACCESS_2_FRAGMENT_DENSITY_MAP_READ_BIT_EXT, srcStageMask must include VK_PIPELINE_STAGE_2_FRAGMENT_DENSITY_PROCESS_BIT_EXT, VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkMemoryBarrier2-srcAccessMask-03920
    If srcAccessMask includes VK_ACCESS_2_TRANSFORM_FEEDBACK_WRITE_BIT_EXT, srcStageMask must include VK_PIPELINE_STAGE_2_TRANSFORM_FEEDBACK_BIT_EXT, VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkMemoryBarrier2-srcAccessMask-04747
    If srcAccessMask includes VK_ACCESS_2_TRANSFORM_FEEDBACK_COUNTER_READ_BIT_EXT, srcStageMask must include VK_PIPELINE_STAGE_2_DRAW_INDIRECT_BIT, VK_PIPELINE_STAGE_2_TRANSFORM_FEEDBACK_BIT_EXT, VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkMemoryBarrier2-srcAccessMask-03922
    If srcAccessMask includes VK_ACCESS_2_TRANSFORM_FEEDBACK_COUNTER_WRITE_BIT_EXT, srcStageMask must include VK_PIPELINE_STAGE_2_TRANSFORM_FEEDBACK_BIT_EXT, VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkMemoryBarrier2-srcAccessMask-03923
    If srcAccessMask includes VK_ACCESS_2_SHADING_RATE_IMAGE_READ_BIT_NV, srcStageMask must include VK_PIPELINE_STAGE_2_SHADING_RATE_IMAGE_BIT_NV, VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkMemoryBarrier2-srcAccessMask-04994
    If srcAccessMask includes VK_ACCESS_2_INVOCATION_MASK_READ_BIT_HUAWEI, srcStageMask must include VK_PIPELINE_STAGE_2_INVOCATION_MASK_BIT_HUAWEI

  • VUID-VkMemoryBarrier2-srcAccessMask-03924
    If srcAccessMask includes VK_ACCESS_2_COMMAND_PREPROCESS_READ_BIT_NV, srcStageMask must include VK_PIPELINE_STAGE_2_COMMAND_PREPROCESS_BIT_NV or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkMemoryBarrier2-srcAccessMask-03925
    If srcAccessMask includes VK_ACCESS_2_COMMAND_PREPROCESS_WRITE_BIT_NV, srcStageMask must include VK_PIPELINE_STAGE_2_COMMAND_PREPROCESS_BIT_NV or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkMemoryBarrier2-srcAccessMask-03926
    If srcAccessMask includes VK_ACCESS_2_COLOR_ATTACHMENT_READ_NONCOHERENT_BIT_EXT, srcStageMask must include VK_PIPELINE_STAGE_2_COLOR_ATTACHMENT_OUTPUT_BIT VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkMemoryBarrier2-srcAccessMask-03927
    If srcAccessMask includes VK_ACCESS_2_ACCELERATION_STRUCTURE_READ_BIT_KHR, srcStageMask must include VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_BUILD_BIT_KHR, VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_COPY_BIT_KHR, VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT, or one of the VK_PIPELINE_STAGE_*_SHADER_BIT stages

  • VUID-VkMemoryBarrier2-srcAccessMask-03928
    If srcAccessMask includes VK_ACCESS_2_ACCELERATION_STRUCTURE_WRITE_BIT_KHR, srcStageMask must include VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_COPY_BIT_KHR, VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_BUILD_BIT_KHR or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkMemoryBarrier2-srcAccessMask-06256
    If the rayQuery feature is not enabled and srcAccessMask includes VK_ACCESS_2_ACCELERATION_STRUCTURE_READ_BIT_KHR, srcStageMask must not include any of the VK_PIPELINE_STAGE_*_SHADER_BIT stages except VK_PIPELINE_STAGE_2_RAY_TRACING_SHADER_BIT_KHR

  • VUID-VkMemoryBarrier2-srcAccessMask-07272
    If srcAccessMask includes VK_ACCESS_2_SHADER_BINDING_TABLE_READ_BIT_KHR, srcStageMask must include VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT or VK_PIPELINE_STAGE_2_RAY_TRACING_SHADER_BIT_KHR

  • VUID-VkMemoryBarrier2-srcAccessMask-04858
    If srcAccessMask includes VK_ACCESS_2_VIDEO_DECODE_READ_BIT_KHR, srcStageMask must include VK_PIPELINE_STAGE_2_VIDEO_DECODE_BIT_KHR

  • VUID-VkMemoryBarrier2-srcAccessMask-04859
    If srcAccessMask includes VK_ACCESS_2_VIDEO_DECODE_WRITE_BIT_KHR, srcStageMask must include VK_PIPELINE_STAGE_2_VIDEO_DECODE_BIT_KHR

  • VUID-VkMemoryBarrier2-srcAccessMask-04860
    If srcAccessMask includes VK_ACCESS_2_VIDEO_ENCODE_READ_BIT_KHR, srcStageMask must include VK_PIPELINE_STAGE_2_VIDEO_ENCODE_BIT_KHR

  • VUID-VkMemoryBarrier2-srcAccessMask-04861
    If srcAccessMask includes VK_ACCESS_2_VIDEO_ENCODE_WRITE_BIT_KHR, srcStageMask must include VK_PIPELINE_STAGE_2_VIDEO_ENCODE_BIT_KHR

  • VUID-VkMemoryBarrier2-srcAccessMask-07455
    If srcAccessMask includes VK_ACCESS_2_OPTICAL_FLOW_READ_BIT_NV, srcStageMask must include VK_PIPELINE_STAGE_2_OPTICAL_FLOW_BIT_NV

  • VUID-VkMemoryBarrier2-srcAccessMask-07456
    If srcAccessMask includes VK_ACCESS_2_OPTICAL_FLOW_WRITE_BIT_NV, srcStageMask must include VK_PIPELINE_STAGE_2_OPTICAL_FLOW_BIT_NV

  • VUID-VkMemoryBarrier2-srcAccessMask-07457
    If srcAccessMask includes VK_ACCESS_2_MICROMAP_WRITE_BIT_EXT, srcStageMask must include VK_PIPELINE_STAGE_2_MICROMAP_BUILD_BIT_EXT

  • VUID-VkMemoryBarrier2-srcAccessMask-07458
    If srcAccessMask includes VK_ACCESS_2_MICROMAP_READ_BIT_EXT, srcStageMask must include VK_PIPELINE_STAGE_2_MICROMAP_BUILD_BIT_EXT or VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_BUILD_BIT_KHR

  • VUID-VkMemoryBarrier2-srcAccessMask-08118
    If srcAccessMask includes VK_ACCESS_2_DESCRIPTOR_BUFFER_READ_BIT_EXT, srcStageMask must include VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT, or one of VK_PIPELINE_STAGE_*_SHADER_BIT stages

  • VUID-VkMemoryBarrier2-dstStageMask-03929
    If the geometryShader feature is not enabled, dstStageMask must not contain VK_PIPELINE_STAGE_2_GEOMETRY_SHADER_BIT

  • VUID-VkMemoryBarrier2-dstStageMask-03930
    If the tessellationShader feature is not enabled, dstStageMask must not contain VK_PIPELINE_STAGE_2_TESSELLATION_CONTROL_SHADER_BIT or VK_PIPELINE_STAGE_2_TESSELLATION_EVALUATION_SHADER_BIT

  • VUID-VkMemoryBarrier2-dstStageMask-03931
    If the conditionalRendering feature is not enabled, dstStageMask must not contain VK_PIPELINE_STAGE_2_CONDITIONAL_RENDERING_BIT_EXT

  • VUID-VkMemoryBarrier2-dstStageMask-03932
    If the fragmentDensityMap feature is not enabled, dstStageMask must not contain VK_PIPELINE_STAGE_2_FRAGMENT_DENSITY_PROCESS_BIT_EXT

  • VUID-VkMemoryBarrier2-dstStageMask-03933
    If the transformFeedback feature is not enabled, dstStageMask must not contain VK_PIPELINE_STAGE_2_TRANSFORM_FEEDBACK_BIT_EXT

  • VUID-VkMemoryBarrier2-dstStageMask-03934
    If the meshShader feature is not enabled, dstStageMask must not contain VK_PIPELINE_STAGE_2_MESH_SHADER_BIT_EXT

  • VUID-VkMemoryBarrier2-dstStageMask-03935
    If the taskShader feature is not enabled, dstStageMask must not contain VK_PIPELINE_STAGE_2_TASK_SHADER_BIT_EXT

  • VUID-VkMemoryBarrier2-dstStageMask-07316
    If neither the shadingRateImage or attachmentFragmentShadingRate are enabled, dstStageMask must not contain VK_PIPELINE_STAGE_2_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR

  • VUID-VkMemoryBarrier2-dstStageMask-04957
    If the subpassShading feature is not enabled, dstStageMask must not contain VK_PIPELINE_STAGE_2_SUBPASS_SHADER_BIT_HUAWEI

  • VUID-VkMemoryBarrier2-dstStageMask-04995
    If the invocationMask feature is not enabled, dstStageMask must not contain VK_PIPELINE_STAGE_2_INVOCATION_MASK_BIT_HUAWEI

  • VUID-VkMemoryBarrier2-dstStageMask-07946
    If neither the VK_NV_ray_tracing extension or rayTracingPipeline feature are enabled, dstStageMask must not contain VK_PIPELINE_STAGE_2_RAY_TRACING_SHADER_BIT_KHR

  • VUID-VkMemoryBarrier2-dstAccessMask-03900
    If dstAccessMask includes VK_ACCESS_2_INDIRECT_COMMAND_READ_BIT, dstStageMask must include VK_PIPELINE_STAGE_2_DRAW_INDIRECT_BIT, VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_BUILD_BIT_KHR, VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkMemoryBarrier2-dstAccessMask-03901
    If dstAccessMask includes VK_ACCESS_2_INDEX_READ_BIT, dstStageMask must include VK_PIPELINE_STAGE_2_INDEX_INPUT_BIT, VK_PIPELINE_STAGE_2_VERTEX_INPUT_BIT, VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkMemoryBarrier2-dstAccessMask-03902
    If dstAccessMask includes VK_ACCESS_2_VERTEX_ATTRIBUTE_READ_BIT, dstStageMask must include VK_PIPELINE_STAGE_2_VERTEX_ATTRIBUTE_INPUT_BIT, VK_PIPELINE_STAGE_2_VERTEX_INPUT_BIT, VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkMemoryBarrier2-dstAccessMask-03903
    If dstAccessMask includes VK_ACCESS_2_INPUT_ATTACHMENT_READ_BIT, dstStageMask must include VK_PIPELINE_STAGE_2_FRAGMENT_SHADER_BIT, VK_PIPELINE_STAGE_2_SUBPASS_SHADER_BIT_HUAWEI, VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkMemoryBarrier2-dstAccessMask-03904
    If dstAccessMask includes VK_ACCESS_2_UNIFORM_READ_BIT, dstStageMask must include VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT, or one of the VK_PIPELINE_STAGE_*_SHADER_BIT stages

  • VUID-VkMemoryBarrier2-dstAccessMask-03905
    If dstAccessMask includes VK_ACCESS_2_SHADER_SAMPLED_READ_BIT, dstStageMask must include VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT, or one of the VK_PIPELINE_STAGE_*_SHADER_BIT stages

  • VUID-VkMemoryBarrier2-dstAccessMask-03906
    If dstAccessMask includes VK_ACCESS_2_SHADER_STORAGE_READ_BIT, dstStageMask must include VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT, or one of the VK_PIPELINE_STAGE_*_SHADER_BIT stages

  • VUID-VkMemoryBarrier2-dstAccessMask-03907
    If dstAccessMask includes VK_ACCESS_2_SHADER_STORAGE_WRITE_BIT, dstStageMask must include VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT, or one of the VK_PIPELINE_STAGE_*_SHADER_BIT stages

  • VUID-VkMemoryBarrier2-dstAccessMask-07454
    If dstAccessMask includes VK_ACCESS_2_SHADER_READ_BIT, dstStageMask must include VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT, VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_BUILD_BIT_KHR, VK_PIPELINE_STAGE_2_MICROMAP_BUILD_BIT_EXT, or one of the VK_PIPELINE_STAGE_*_SHADER_BIT stages

  • VUID-VkMemoryBarrier2-dstAccessMask-03909
    If dstAccessMask includes VK_ACCESS_2_SHADER_WRITE_BIT, dstStageMask must include VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT, or one of the VK_PIPELINE_STAGE_*_SHADER_BIT stages

  • VUID-VkMemoryBarrier2-dstAccessMask-03910
    If dstAccessMask includes VK_ACCESS_2_COLOR_ATTACHMENT_READ_BIT, dstStageMask must include VK_PIPELINE_STAGE_2_COLOR_ATTACHMENT_OUTPUT_BIT VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkMemoryBarrier2-dstAccessMask-03911
    If dstAccessMask includes VK_ACCESS_2_COLOR_ATTACHMENT_WRITE_BIT, dstStageMask must include VK_PIPELINE_STAGE_2_COLOR_ATTACHMENT_OUTPUT_BIT VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkMemoryBarrier2-dstAccessMask-03912
    If dstAccessMask includes VK_ACCESS_2_DEPTH_STENCIL_ATTACHMENT_READ_BIT, dstStageMask must include VK_PIPELINE_STAGE_2_EARLY_FRAGMENT_TESTS_BIT, VK_PIPELINE_STAGE_2_LATE_FRAGMENT_TESTS_BIT, VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkMemoryBarrier2-dstAccessMask-03913
    If dstAccessMask includes VK_ACCESS_2_DEPTH_STENCIL_ATTACHMENT_WRITE_BIT, dstStageMask must include VK_PIPELINE_STAGE_2_EARLY_FRAGMENT_TESTS_BIT, VK_PIPELINE_STAGE_2_LATE_FRAGMENT_TESTS_BIT, VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkMemoryBarrier2-dstAccessMask-03914
    If dstAccessMask includes VK_ACCESS_2_TRANSFER_READ_BIT, dstStageMask must include VK_PIPELINE_STAGE_2_COPY_BIT, VK_PIPELINE_STAGE_2_BLIT_BIT, VK_PIPELINE_STAGE_2_RESOLVE_BIT, VK_PIPELINE_STAGE_2_ALL_TRANSFER_BIT, VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_BUILD_BIT_KHR, VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_COPY_BIT_KHR, or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkMemoryBarrier2-dstAccessMask-03915
    If dstAccessMask includes VK_ACCESS_2_TRANSFER_WRITE_BIT, dstStageMask must include VK_PIPELINE_STAGE_2_COPY_BIT, VK_PIPELINE_STAGE_2_BLIT_BIT, VK_PIPELINE_STAGE_2_RESOLVE_BIT, VK_PIPELINE_STAGE_2_CLEAR_BIT, VK_PIPELINE_STAGE_2_ALL_TRANSFER_BIT, VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_BUILD_BIT_KHR, or VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_COPY_BIT_KHR, VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkMemoryBarrier2-dstAccessMask-03916
    If dstAccessMask includes VK_ACCESS_2_HOST_READ_BIT, dstStageMask must include VK_PIPELINE_STAGE_2_HOST_BIT

  • VUID-VkMemoryBarrier2-dstAccessMask-03917
    If dstAccessMask includes VK_ACCESS_2_HOST_WRITE_BIT, dstStageMask must include VK_PIPELINE_STAGE_2_HOST_BIT

  • VUID-VkMemoryBarrier2-dstAccessMask-03918
    If dstAccessMask includes VK_ACCESS_2_CONDITIONAL_RENDERING_READ_BIT_EXT, dstStageMask must include VK_PIPELINE_STAGE_2_CONDITIONAL_RENDERING_BIT_EXT, VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkMemoryBarrier2-dstAccessMask-03919
    If dstAccessMask includes VK_ACCESS_2_FRAGMENT_DENSITY_MAP_READ_BIT_EXT, dstStageMask must include VK_PIPELINE_STAGE_2_FRAGMENT_DENSITY_PROCESS_BIT_EXT, VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkMemoryBarrier2-dstAccessMask-03920
    If dstAccessMask includes VK_ACCESS_2_TRANSFORM_FEEDBACK_WRITE_BIT_EXT, dstStageMask must include VK_PIPELINE_STAGE_2_TRANSFORM_FEEDBACK_BIT_EXT, VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkMemoryBarrier2-dstAccessMask-04747
    If dstAccessMask includes VK_ACCESS_2_TRANSFORM_FEEDBACK_COUNTER_READ_BIT_EXT, dstStageMask must include VK_PIPELINE_STAGE_2_DRAW_INDIRECT_BIT, VK_PIPELINE_STAGE_2_TRANSFORM_FEEDBACK_BIT_EXT, VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkMemoryBarrier2-dstAccessMask-03922
    If dstAccessMask includes VK_ACCESS_2_TRANSFORM_FEEDBACK_COUNTER_WRITE_BIT_EXT, dstStageMask must include VK_PIPELINE_STAGE_2_TRANSFORM_FEEDBACK_BIT_EXT, VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkMemoryBarrier2-dstAccessMask-03923
    If dstAccessMask includes VK_ACCESS_2_SHADING_RATE_IMAGE_READ_BIT_NV, dstStageMask must include VK_PIPELINE_STAGE_2_SHADING_RATE_IMAGE_BIT_NV, VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkMemoryBarrier2-dstAccessMask-04994
    If dstAccessMask includes VK_ACCESS_2_INVOCATION_MASK_READ_BIT_HUAWEI, dstStageMask must include VK_PIPELINE_STAGE_2_INVOCATION_MASK_BIT_HUAWEI

  • VUID-VkMemoryBarrier2-dstAccessMask-03924
    If dstAccessMask includes VK_ACCESS_2_COMMAND_PREPROCESS_READ_BIT_NV, dstStageMask must include VK_PIPELINE_STAGE_2_COMMAND_PREPROCESS_BIT_NV or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkMemoryBarrier2-dstAccessMask-03925
    If dstAccessMask includes VK_ACCESS_2_COMMAND_PREPROCESS_WRITE_BIT_NV, dstStageMask must include VK_PIPELINE_STAGE_2_COMMAND_PREPROCESS_BIT_NV or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkMemoryBarrier2-dstAccessMask-03926
    If dstAccessMask includes VK_ACCESS_2_COLOR_ATTACHMENT_READ_NONCOHERENT_BIT_EXT, dstStageMask must include VK_PIPELINE_STAGE_2_COLOR_ATTACHMENT_OUTPUT_BIT VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkMemoryBarrier2-dstAccessMask-03927
    If dstAccessMask includes VK_ACCESS_2_ACCELERATION_STRUCTURE_READ_BIT_KHR, dstStageMask must include VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_BUILD_BIT_KHR, VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_COPY_BIT_KHR, VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT, or one of the VK_PIPELINE_STAGE_*_SHADER_BIT stages

  • VUID-VkMemoryBarrier2-dstAccessMask-03928
    If dstAccessMask includes VK_ACCESS_2_ACCELERATION_STRUCTURE_WRITE_BIT_KHR, dstStageMask must include VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_COPY_BIT_KHR, VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_BUILD_BIT_KHR or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkMemoryBarrier2-dstAccessMask-06256
    If the rayQuery feature is not enabled and dstAccessMask includes VK_ACCESS_2_ACCELERATION_STRUCTURE_READ_BIT_KHR, dstStageMask must not include any of the VK_PIPELINE_STAGE_*_SHADER_BIT stages except VK_PIPELINE_STAGE_2_RAY_TRACING_SHADER_BIT_KHR

  • VUID-VkMemoryBarrier2-dstAccessMask-07272
    If dstAccessMask includes VK_ACCESS_2_SHADER_BINDING_TABLE_READ_BIT_KHR, dstStageMask must include VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT or VK_PIPELINE_STAGE_2_RAY_TRACING_SHADER_BIT_KHR

  • VUID-VkMemoryBarrier2-dstAccessMask-04858
    If dstAccessMask includes VK_ACCESS_2_VIDEO_DECODE_READ_BIT_KHR, dstStageMask must include VK_PIPELINE_STAGE_2_VIDEO_DECODE_BIT_KHR

  • VUID-VkMemoryBarrier2-dstAccessMask-04859
    If dstAccessMask includes VK_ACCESS_2_VIDEO_DECODE_WRITE_BIT_KHR, dstStageMask must include VK_PIPELINE_STAGE_2_VIDEO_DECODE_BIT_KHR

  • VUID-VkMemoryBarrier2-dstAccessMask-04860
    If dstAccessMask includes VK_ACCESS_2_VIDEO_ENCODE_READ_BIT_KHR, dstStageMask must include VK_PIPELINE_STAGE_2_VIDEO_ENCODE_BIT_KHR

  • VUID-VkMemoryBarrier2-dstAccessMask-04861
    If dstAccessMask includes VK_ACCESS_2_VIDEO_ENCODE_WRITE_BIT_KHR, dstStageMask must include VK_PIPELINE_STAGE_2_VIDEO_ENCODE_BIT_KHR

  • VUID-VkMemoryBarrier2-dstAccessMask-07455
    If dstAccessMask includes VK_ACCESS_2_OPTICAL_FLOW_READ_BIT_NV, dstStageMask must include VK_PIPELINE_STAGE_2_OPTICAL_FLOW_BIT_NV

  • VUID-VkMemoryBarrier2-dstAccessMask-07456
    If dstAccessMask includes VK_ACCESS_2_OPTICAL_FLOW_WRITE_BIT_NV, dstStageMask must include VK_PIPELINE_STAGE_2_OPTICAL_FLOW_BIT_NV

  • VUID-VkMemoryBarrier2-dstAccessMask-07457
    If dstAccessMask includes VK_ACCESS_2_MICROMAP_WRITE_BIT_EXT, dstStageMask must include VK_PIPELINE_STAGE_2_MICROMAP_BUILD_BIT_EXT

  • VUID-VkMemoryBarrier2-dstAccessMask-07458
    If dstAccessMask includes VK_ACCESS_2_MICROMAP_READ_BIT_EXT, dstStageMask must include VK_PIPELINE_STAGE_2_MICROMAP_BUILD_BIT_EXT or VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_BUILD_BIT_KHR

  • VUID-VkMemoryBarrier2-dstAccessMask-08118
    If dstAccessMask includes VK_ACCESS_2_DESCRIPTOR_BUFFER_READ_BIT_EXT, dstStageMask must include VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT, or one of VK_PIPELINE_STAGE_*_SHADER_BIT stages

Valid Usage (Implicit)

  • VUID-VkMemoryBarrier2-sType-sType
    sType must be VK_STRUCTURE_TYPE_MEMORY_BARRIER_2

  • VUID-VkMemoryBarrier2-srcStageMask-parameter
    srcStageMask must be a valid combination of VkPipelineStageFlagBits2 values

  • VUID-VkMemoryBarrier2-srcAccessMask-parameter
    srcAccessMask must be a valid combination of VkAccessFlagBits2 values

  • VUID-VkMemoryBarrier2-dstStageMask-parameter
    dstStageMask must be a valid combination of VkPipelineStageFlagBits2 values

  • VUID-VkMemoryBarrier2-dstAccessMask-parameter
    dstAccessMask must be a valid combination of VkAccessFlagBits2 values

The VkMemoryBarrier structure is defined as:

// Provided by VK_VERSION_1_0
typedef struct VkMemoryBarrier {
    VkStructureType    sType;
    const void*        pNext;
    VkAccessFlags      srcAccessMask;
    VkAccessFlags      dstAccessMask;
} VkMemoryBarrier;

The first access scope is limited to access types in the source access mask specified by srcAccessMask.

The second access scope is limited to access types in the destination access mask specified by dstAccessMask.

Valid Usage (Implicit)

  • VUID-VkMemoryBarrier-sType-sType
    sType must be VK_STRUCTURE_TYPE_MEMORY_BARRIER

  • VUID-VkMemoryBarrier-pNext-pNext
    pNext must be NULL

  • VUID-VkMemoryBarrier-srcAccessMask-parameter
    srcAccessMask must be a valid combination of VkAccessFlagBits values

  • VUID-VkMemoryBarrier-dstAccessMask-parameter
    dstAccessMask must be a valid combination of VkAccessFlagBits values

7.7.2. Buffer Memory Barriers

Buffer memory barriers only apply to memory accesses involving a specific buffer range. That is, a memory dependency formed from a buffer memory barrier is scoped to access via the specified buffer range. Buffer memory barriers can also be used to define a queue family ownership transfer for the specified buffer range.

The VkBufferMemoryBarrier2 structure is defined as:

// Provided by VK_VERSION_1_3
typedef struct VkBufferMemoryBarrier2 {
    VkStructureType          sType;
    const void*              pNext;
    VkPipelineStageFlags2    srcStageMask;
    VkAccessFlags2           srcAccessMask;
    VkPipelineStageFlags2    dstStageMask;
    VkAccessFlags2           dstAccessMask;
    uint32_t                 srcQueueFamilyIndex;
    uint32_t                 dstQueueFamilyIndex;
    VkBuffer                 buffer;
    VkDeviceSize             offset;
    VkDeviceSize             size;
} VkBufferMemoryBarrier2;

or the equivalent

// Provided by VK_KHR_synchronization2
typedef VkBufferMemoryBarrier2 VkBufferMemoryBarrier2KHR;

This structure defines a memory dependency limited to a range of a buffer, and can define a queue family ownership transfer operation for that range.

The first synchronization scope and access scope described by this structure include only operations and memory accesses specified by srcStageMask and srcAccessMask.

The second synchronization scope and access scope described by this structure include only operations and memory accesses specified by dstStageMask and dstAccessMask.

Both access scopes are limited to only memory accesses to buffer in the range defined by offset and size.

If buffer was created with VK_SHARING_MODE_EXCLUSIVE, and srcQueueFamilyIndex is not equal to dstQueueFamilyIndex, this memory barrier defines a queue family ownership transfer operation. When executed on a queue in the family identified by srcQueueFamilyIndex, this barrier defines a queue family release operation for the specified buffer range, and the second synchronization scope does not apply to this operation. When executed on a queue in the family identified by dstQueueFamilyIndex, this barrier defines a queue family acquire operation for the specified buffer range, and the first synchronization scope does not apply to this operation.

A queue family ownership transfer operation is also defined if the values are not equal, and either is one of the special queue family values reserved for external memory ownership transfers, as described in Queue Family Ownership Transfer. A queue family release operation is defined when dstQueueFamilyIndex is one of those values, and a queue family acquire operation is defined when srcQueueFamilyIndex is one of those values.

Valid Usage

  • VUID-VkBufferMemoryBarrier2-srcStageMask-03929
    If the geometryShader feature is not enabled, srcStageMask must not contain VK_PIPELINE_STAGE_2_GEOMETRY_SHADER_BIT

  • VUID-VkBufferMemoryBarrier2-srcStageMask-03930
    If the tessellationShader feature is not enabled, srcStageMask must not contain VK_PIPELINE_STAGE_2_TESSELLATION_CONTROL_SHADER_BIT or VK_PIPELINE_STAGE_2_TESSELLATION_EVALUATION_SHADER_BIT

  • VUID-VkBufferMemoryBarrier2-srcStageMask-03931
    If the conditionalRendering feature is not enabled, srcStageMask must not contain VK_PIPELINE_STAGE_2_CONDITIONAL_RENDERING_BIT_EXT

  • VUID-VkBufferMemoryBarrier2-srcStageMask-03932
    If the fragmentDensityMap feature is not enabled, srcStageMask must not contain VK_PIPELINE_STAGE_2_FRAGMENT_DENSITY_PROCESS_BIT_EXT

  • VUID-VkBufferMemoryBarrier2-srcStageMask-03933
    If the transformFeedback feature is not enabled, srcStageMask must not contain VK_PIPELINE_STAGE_2_TRANSFORM_FEEDBACK_BIT_EXT

  • VUID-VkBufferMemoryBarrier2-srcStageMask-03934
    If the meshShader feature is not enabled, srcStageMask must not contain VK_PIPELINE_STAGE_2_MESH_SHADER_BIT_EXT

  • VUID-VkBufferMemoryBarrier2-srcStageMask-03935
    If the taskShader feature is not enabled, srcStageMask must not contain VK_PIPELINE_STAGE_2_TASK_SHADER_BIT_EXT

  • VUID-VkBufferMemoryBarrier2-srcStageMask-07316
    If neither the shadingRateImage or attachmentFragmentShadingRate are enabled, srcStageMask must not contain VK_PIPELINE_STAGE_2_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR

  • VUID-VkBufferMemoryBarrier2-srcStageMask-04957
    If the subpassShading feature is not enabled, srcStageMask must not contain VK_PIPELINE_STAGE_2_SUBPASS_SHADER_BIT_HUAWEI

  • VUID-VkBufferMemoryBarrier2-srcStageMask-04995
    If the invocationMask feature is not enabled, srcStageMask must not contain VK_PIPELINE_STAGE_2_INVOCATION_MASK_BIT_HUAWEI

  • VUID-VkBufferMemoryBarrier2-srcStageMask-07946
    If neither the VK_NV_ray_tracing extension or rayTracingPipeline feature are enabled, srcStageMask must not contain VK_PIPELINE_STAGE_2_RAY_TRACING_SHADER_BIT_KHR

  • VUID-VkBufferMemoryBarrier2-srcAccessMask-03900
    If srcAccessMask includes VK_ACCESS_2_INDIRECT_COMMAND_READ_BIT, srcStageMask must include VK_PIPELINE_STAGE_2_DRAW_INDIRECT_BIT, VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_BUILD_BIT_KHR, VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkBufferMemoryBarrier2-srcAccessMask-03901
    If srcAccessMask includes VK_ACCESS_2_INDEX_READ_BIT, srcStageMask must include VK_PIPELINE_STAGE_2_INDEX_INPUT_BIT, VK_PIPELINE_STAGE_2_VERTEX_INPUT_BIT, VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkBufferMemoryBarrier2-srcAccessMask-03902
    If srcAccessMask includes VK_ACCESS_2_VERTEX_ATTRIBUTE_READ_BIT, srcStageMask must include VK_PIPELINE_STAGE_2_VERTEX_ATTRIBUTE_INPUT_BIT, VK_PIPELINE_STAGE_2_VERTEX_INPUT_BIT, VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkBufferMemoryBarrier2-srcAccessMask-03903
    If srcAccessMask includes VK_ACCESS_2_INPUT_ATTACHMENT_READ_BIT, srcStageMask must include VK_PIPELINE_STAGE_2_FRAGMENT_SHADER_BIT, VK_PIPELINE_STAGE_2_SUBPASS_SHADER_BIT_HUAWEI, VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkBufferMemoryBarrier2-srcAccessMask-03904
    If srcAccessMask includes VK_ACCESS_2_UNIFORM_READ_BIT, srcStageMask must include VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT, or one of the VK_PIPELINE_STAGE_*_SHADER_BIT stages

  • VUID-VkBufferMemoryBarrier2-srcAccessMask-03905
    If srcAccessMask includes VK_ACCESS_2_SHADER_SAMPLED_READ_BIT, srcStageMask must include VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT, or one of the VK_PIPELINE_STAGE_*_SHADER_BIT stages

  • VUID-VkBufferMemoryBarrier2-srcAccessMask-03906
    If srcAccessMask includes VK_ACCESS_2_SHADER_STORAGE_READ_BIT, srcStageMask must include VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT, or one of the VK_PIPELINE_STAGE_*_SHADER_BIT stages

  • VUID-VkBufferMemoryBarrier2-srcAccessMask-03907
    If srcAccessMask includes VK_ACCESS_2_SHADER_STORAGE_WRITE_BIT, srcStageMask must include VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT, or one of the VK_PIPELINE_STAGE_*_SHADER_BIT stages

  • VUID-VkBufferMemoryBarrier2-srcAccessMask-07454
    If srcAccessMask includes VK_ACCESS_2_SHADER_READ_BIT, srcStageMask must include VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT, VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_BUILD_BIT_KHR, VK_PIPELINE_STAGE_2_MICROMAP_BUILD_BIT_EXT, or one of the VK_PIPELINE_STAGE_*_SHADER_BIT stages

  • VUID-VkBufferMemoryBarrier2-srcAccessMask-03909
    If srcAccessMask includes VK_ACCESS_2_SHADER_WRITE_BIT, srcStageMask must include VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT, or one of the VK_PIPELINE_STAGE_*_SHADER_BIT stages

  • VUID-VkBufferMemoryBarrier2-srcAccessMask-03910
    If srcAccessMask includes VK_ACCESS_2_COLOR_ATTACHMENT_READ_BIT, srcStageMask must include VK_PIPELINE_STAGE_2_COLOR_ATTACHMENT_OUTPUT_BIT VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkBufferMemoryBarrier2-srcAccessMask-03911
    If srcAccessMask includes VK_ACCESS_2_COLOR_ATTACHMENT_WRITE_BIT, srcStageMask must include VK_PIPELINE_STAGE_2_COLOR_ATTACHMENT_OUTPUT_BIT VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkBufferMemoryBarrier2-srcAccessMask-03912
    If srcAccessMask includes VK_ACCESS_2_DEPTH_STENCIL_ATTACHMENT_READ_BIT, srcStageMask must include VK_PIPELINE_STAGE_2_EARLY_FRAGMENT_TESTS_BIT, VK_PIPELINE_STAGE_2_LATE_FRAGMENT_TESTS_BIT, VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkBufferMemoryBarrier2-srcAccessMask-03913
    If srcAccessMask includes VK_ACCESS_2_DEPTH_STENCIL_ATTACHMENT_WRITE_BIT, srcStageMask must include VK_PIPELINE_STAGE_2_EARLY_FRAGMENT_TESTS_BIT, VK_PIPELINE_STAGE_2_LATE_FRAGMENT_TESTS_BIT, VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkBufferMemoryBarrier2-srcAccessMask-03914
    If srcAccessMask includes VK_ACCESS_2_TRANSFER_READ_BIT, srcStageMask must include VK_PIPELINE_STAGE_2_COPY_BIT, VK_PIPELINE_STAGE_2_BLIT_BIT, VK_PIPELINE_STAGE_2_RESOLVE_BIT, VK_PIPELINE_STAGE_2_ALL_TRANSFER_BIT, VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_BUILD_BIT_KHR, VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_COPY_BIT_KHR, or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkBufferMemoryBarrier2-srcAccessMask-03915
    If srcAccessMask includes VK_ACCESS_2_TRANSFER_WRITE_BIT, srcStageMask must include VK_PIPELINE_STAGE_2_COPY_BIT, VK_PIPELINE_STAGE_2_BLIT_BIT, VK_PIPELINE_STAGE_2_RESOLVE_BIT, VK_PIPELINE_STAGE_2_CLEAR_BIT, VK_PIPELINE_STAGE_2_ALL_TRANSFER_BIT, VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_BUILD_BIT_KHR, or VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_COPY_BIT_KHR, VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkBufferMemoryBarrier2-srcAccessMask-03916
    If srcAccessMask includes VK_ACCESS_2_HOST_READ_BIT, srcStageMask must include VK_PIPELINE_STAGE_2_HOST_BIT

  • VUID-VkBufferMemoryBarrier2-srcAccessMask-03917
    If srcAccessMask includes VK_ACCESS_2_HOST_WRITE_BIT, srcStageMask must include VK_PIPELINE_STAGE_2_HOST_BIT

  • VUID-VkBufferMemoryBarrier2-srcAccessMask-03918
    If srcAccessMask includes VK_ACCESS_2_CONDITIONAL_RENDERING_READ_BIT_EXT, srcStageMask must include VK_PIPELINE_STAGE_2_CONDITIONAL_RENDERING_BIT_EXT, VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkBufferMemoryBarrier2-srcAccessMask-03919
    If srcAccessMask includes VK_ACCESS_2_FRAGMENT_DENSITY_MAP_READ_BIT_EXT, srcStageMask must include VK_PIPELINE_STAGE_2_FRAGMENT_DENSITY_PROCESS_BIT_EXT, VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkBufferMemoryBarrier2-srcAccessMask-03920
    If srcAccessMask includes VK_ACCESS_2_TRANSFORM_FEEDBACK_WRITE_BIT_EXT, srcStageMask must include VK_PIPELINE_STAGE_2_TRANSFORM_FEEDBACK_BIT_EXT, VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkBufferMemoryBarrier2-srcAccessMask-04747
    If srcAccessMask includes VK_ACCESS_2_TRANSFORM_FEEDBACK_COUNTER_READ_BIT_EXT, srcStageMask must include VK_PIPELINE_STAGE_2_DRAW_INDIRECT_BIT, VK_PIPELINE_STAGE_2_TRANSFORM_FEEDBACK_BIT_EXT, VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkBufferMemoryBarrier2-srcAccessMask-03922
    If srcAccessMask includes VK_ACCESS_2_TRANSFORM_FEEDBACK_COUNTER_WRITE_BIT_EXT, srcStageMask must include VK_PIPELINE_STAGE_2_TRANSFORM_FEEDBACK_BIT_EXT, VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkBufferMemoryBarrier2-srcAccessMask-03923
    If srcAccessMask includes VK_ACCESS_2_SHADING_RATE_IMAGE_READ_BIT_NV, srcStageMask must include VK_PIPELINE_STAGE_2_SHADING_RATE_IMAGE_BIT_NV, VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkBufferMemoryBarrier2-srcAccessMask-04994
    If srcAccessMask includes VK_ACCESS_2_INVOCATION_MASK_READ_BIT_HUAWEI, srcStageMask must include VK_PIPELINE_STAGE_2_INVOCATION_MASK_BIT_HUAWEI

  • VUID-VkBufferMemoryBarrier2-srcAccessMask-03924
    If srcAccessMask includes VK_ACCESS_2_COMMAND_PREPROCESS_READ_BIT_NV, srcStageMask must include VK_PIPELINE_STAGE_2_COMMAND_PREPROCESS_BIT_NV or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkBufferMemoryBarrier2-srcAccessMask-03925
    If srcAccessMask includes VK_ACCESS_2_COMMAND_PREPROCESS_WRITE_BIT_NV, srcStageMask must include VK_PIPELINE_STAGE_2_COMMAND_PREPROCESS_BIT_NV or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkBufferMemoryBarrier2-srcAccessMask-03926
    If srcAccessMask includes VK_ACCESS_2_COLOR_ATTACHMENT_READ_NONCOHERENT_BIT_EXT, srcStageMask must include VK_PIPELINE_STAGE_2_COLOR_ATTACHMENT_OUTPUT_BIT VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkBufferMemoryBarrier2-srcAccessMask-03927
    If srcAccessMask includes VK_ACCESS_2_ACCELERATION_STRUCTURE_READ_BIT_KHR, srcStageMask must include VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_BUILD_BIT_KHR, VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_COPY_BIT_KHR, VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT, or one of the VK_PIPELINE_STAGE_*_SHADER_BIT stages

  • VUID-VkBufferMemoryBarrier2-srcAccessMask-03928
    If srcAccessMask includes VK_ACCESS_2_ACCELERATION_STRUCTURE_WRITE_BIT_KHR, srcStageMask must include VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_COPY_BIT_KHR, VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_BUILD_BIT_KHR or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkBufferMemoryBarrier2-srcAccessMask-06256
    If the rayQuery feature is not enabled and srcAccessMask includes VK_ACCESS_2_ACCELERATION_STRUCTURE_READ_BIT_KHR, srcStageMask must not include any of the VK_PIPELINE_STAGE_*_SHADER_BIT stages except VK_PIPELINE_STAGE_2_RAY_TRACING_SHADER_BIT_KHR

  • VUID-VkBufferMemoryBarrier2-srcAccessMask-07272
    If srcAccessMask includes VK_ACCESS_2_SHADER_BINDING_TABLE_READ_BIT_KHR, srcStageMask must include VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT or VK_PIPELINE_STAGE_2_RAY_TRACING_SHADER_BIT_KHR

  • VUID-VkBufferMemoryBarrier2-srcAccessMask-04858
    If srcAccessMask includes VK_ACCESS_2_VIDEO_DECODE_READ_BIT_KHR, srcStageMask must include VK_PIPELINE_STAGE_2_VIDEO_DECODE_BIT_KHR

  • VUID-VkBufferMemoryBarrier2-srcAccessMask-04859
    If srcAccessMask includes VK_ACCESS_2_VIDEO_DECODE_WRITE_BIT_KHR, srcStageMask must include VK_PIPELINE_STAGE_2_VIDEO_DECODE_BIT_KHR

  • VUID-VkBufferMemoryBarrier2-srcAccessMask-04860
    If srcAccessMask includes VK_ACCESS_2_VIDEO_ENCODE_READ_BIT_KHR, srcStageMask must include VK_PIPELINE_STAGE_2_VIDEO_ENCODE_BIT_KHR

  • VUID-VkBufferMemoryBarrier2-srcAccessMask-04861
    If srcAccessMask includes VK_ACCESS_2_VIDEO_ENCODE_WRITE_BIT_KHR, srcStageMask must include VK_PIPELINE_STAGE_2_VIDEO_ENCODE_BIT_KHR

  • VUID-VkBufferMemoryBarrier2-srcAccessMask-07455
    If srcAccessMask includes VK_ACCESS_2_OPTICAL_FLOW_READ_BIT_NV, srcStageMask must include VK_PIPELINE_STAGE_2_OPTICAL_FLOW_BIT_NV

  • VUID-VkBufferMemoryBarrier2-srcAccessMask-07456
    If srcAccessMask includes VK_ACCESS_2_OPTICAL_FLOW_WRITE_BIT_NV, srcStageMask must include VK_PIPELINE_STAGE_2_OPTICAL_FLOW_BIT_NV

  • VUID-VkBufferMemoryBarrier2-srcAccessMask-07457
    If srcAccessMask includes VK_ACCESS_2_MICROMAP_WRITE_BIT_EXT, srcStageMask must include VK_PIPELINE_STAGE_2_MICROMAP_BUILD_BIT_EXT

  • VUID-VkBufferMemoryBarrier2-srcAccessMask-07458
    If srcAccessMask includes VK_ACCESS_2_MICROMAP_READ_BIT_EXT, srcStageMask must include VK_PIPELINE_STAGE_2_MICROMAP_BUILD_BIT_EXT or VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_BUILD_BIT_KHR

  • VUID-VkBufferMemoryBarrier2-srcAccessMask-08118
    If srcAccessMask includes VK_ACCESS_2_DESCRIPTOR_BUFFER_READ_BIT_EXT, srcStageMask must include VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT, or one of VK_PIPELINE_STAGE_*_SHADER_BIT stages

  • VUID-VkBufferMemoryBarrier2-dstStageMask-03929
    If the geometryShader feature is not enabled, dstStageMask must not contain VK_PIPELINE_STAGE_2_GEOMETRY_SHADER_BIT

  • VUID-VkBufferMemoryBarrier2-dstStageMask-03930
    If the tessellationShader feature is not enabled, dstStageMask must not contain VK_PIPELINE_STAGE_2_TESSELLATION_CONTROL_SHADER_BIT or VK_PIPELINE_STAGE_2_TESSELLATION_EVALUATION_SHADER_BIT

  • VUID-VkBufferMemoryBarrier2-dstStageMask-03931
    If the conditionalRendering feature is not enabled, dstStageMask must not contain VK_PIPELINE_STAGE_2_CONDITIONAL_RENDERING_BIT_EXT

  • VUID-VkBufferMemoryBarrier2-dstStageMask-03932
    If the fragmentDensityMap feature is not enabled, dstStageMask must not contain VK_PIPELINE_STAGE_2_FRAGMENT_DENSITY_PROCESS_BIT_EXT

  • VUID-VkBufferMemoryBarrier2-dstStageMask-03933
    If the transformFeedback feature is not enabled, dstStageMask must not contain VK_PIPELINE_STAGE_2_TRANSFORM_FEEDBACK_BIT_EXT

  • VUID-VkBufferMemoryBarrier2-dstStageMask-03934
    If the meshShader feature is not enabled, dstStageMask must not contain VK_PIPELINE_STAGE_2_MESH_SHADER_BIT_EXT

  • VUID-VkBufferMemoryBarrier2-dstStageMask-03935
    If the taskShader feature is not enabled, dstStageMask must not contain VK_PIPELINE_STAGE_2_TASK_SHADER_BIT_EXT

  • VUID-VkBufferMemoryBarrier2-dstStageMask-07316
    If neither the shadingRateImage or attachmentFragmentShadingRate are enabled, dstStageMask must not contain VK_PIPELINE_STAGE_2_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR

  • VUID-VkBufferMemoryBarrier2-dstStageMask-04957
    If the subpassShading feature is not enabled, dstStageMask must not contain VK_PIPELINE_STAGE_2_SUBPASS_SHADER_BIT_HUAWEI

  • VUID-VkBufferMemoryBarrier2-dstStageMask-04995
    If the invocationMask feature is not enabled, dstStageMask must not contain VK_PIPELINE_STAGE_2_INVOCATION_MASK_BIT_HUAWEI

  • VUID-VkBufferMemoryBarrier2-dstStageMask-07946
    If neither the VK_NV_ray_tracing extension or rayTracingPipeline feature are enabled, dstStageMask must not contain VK_PIPELINE_STAGE_2_RAY_TRACING_SHADER_BIT_KHR

  • VUID-VkBufferMemoryBarrier2-dstAccessMask-03900
    If dstAccessMask includes VK_ACCESS_2_INDIRECT_COMMAND_READ_BIT, dstStageMask must include VK_PIPELINE_STAGE_2_DRAW_INDIRECT_BIT, VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_BUILD_BIT_KHR, VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkBufferMemoryBarrier2-dstAccessMask-03901
    If dstAccessMask includes VK_ACCESS_2_INDEX_READ_BIT, dstStageMask must include VK_PIPELINE_STAGE_2_INDEX_INPUT_BIT, VK_PIPELINE_STAGE_2_VERTEX_INPUT_BIT, VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkBufferMemoryBarrier2-dstAccessMask-03902
    If dstAccessMask includes VK_ACCESS_2_VERTEX_ATTRIBUTE_READ_BIT, dstStageMask must include VK_PIPELINE_STAGE_2_VERTEX_ATTRIBUTE_INPUT_BIT, VK_PIPELINE_STAGE_2_VERTEX_INPUT_BIT, VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkBufferMemoryBarrier2-dstAccessMask-03903
    If dstAccessMask includes VK_ACCESS_2_INPUT_ATTACHMENT_READ_BIT, dstStageMask must include VK_PIPELINE_STAGE_2_FRAGMENT_SHADER_BIT, VK_PIPELINE_STAGE_2_SUBPASS_SHADER_BIT_HUAWEI, VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkBufferMemoryBarrier2-dstAccessMask-03904
    If dstAccessMask includes VK_ACCESS_2_UNIFORM_READ_BIT, dstStageMask must include VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT, or one of the VK_PIPELINE_STAGE_*_SHADER_BIT stages

  • VUID-VkBufferMemoryBarrier2-dstAccessMask-03905
    If dstAccessMask includes VK_ACCESS_2_SHADER_SAMPLED_READ_BIT, dstStageMask must include VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT, or one of the VK_PIPELINE_STAGE_*_SHADER_BIT stages

  • VUID-VkBufferMemoryBarrier2-dstAccessMask-03906
    If dstAccessMask includes VK_ACCESS_2_SHADER_STORAGE_READ_BIT, dstStageMask must include VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT, or one of the VK_PIPELINE_STAGE_*_SHADER_BIT stages

  • VUID-VkBufferMemoryBarrier2-dstAccessMask-03907
    If dstAccessMask includes VK_ACCESS_2_SHADER_STORAGE_WRITE_BIT, dstStageMask must include VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT, or one of the VK_PIPELINE_STAGE_*_SHADER_BIT stages

  • VUID-VkBufferMemoryBarrier2-dstAccessMask-07454
    If dstAccessMask includes VK_ACCESS_2_SHADER_READ_BIT, dstStageMask must include VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT, VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_BUILD_BIT_KHR, VK_PIPELINE_STAGE_2_MICROMAP_BUILD_BIT_EXT, or one of the VK_PIPELINE_STAGE_*_SHADER_BIT stages

  • VUID-VkBufferMemoryBarrier2-dstAccessMask-03909
    If dstAccessMask includes VK_ACCESS_2_SHADER_WRITE_BIT, dstStageMask must include VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT, or one of the VK_PIPELINE_STAGE_*_SHADER_BIT stages

  • VUID-VkBufferMemoryBarrier2-dstAccessMask-03910
    If dstAccessMask includes VK_ACCESS_2_COLOR_ATTACHMENT_READ_BIT, dstStageMask must include VK_PIPELINE_STAGE_2_COLOR_ATTACHMENT_OUTPUT_BIT VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkBufferMemoryBarrier2-dstAccessMask-03911
    If dstAccessMask includes VK_ACCESS_2_COLOR_ATTACHMENT_WRITE_BIT, dstStageMask must include VK_PIPELINE_STAGE_2_COLOR_ATTACHMENT_OUTPUT_BIT VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkBufferMemoryBarrier2-dstAccessMask-03912
    If dstAccessMask includes VK_ACCESS_2_DEPTH_STENCIL_ATTACHMENT_READ_BIT, dstStageMask must include VK_PIPELINE_STAGE_2_EARLY_FRAGMENT_TESTS_BIT, VK_PIPELINE_STAGE_2_LATE_FRAGMENT_TESTS_BIT, VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkBufferMemoryBarrier2-dstAccessMask-03913
    If dstAccessMask includes VK_ACCESS_2_DEPTH_STENCIL_ATTACHMENT_WRITE_BIT, dstStageMask must include VK_PIPELINE_STAGE_2_EARLY_FRAGMENT_TESTS_BIT, VK_PIPELINE_STAGE_2_LATE_FRAGMENT_TESTS_BIT, VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkBufferMemoryBarrier2-dstAccessMask-03914
    If dstAccessMask includes VK_ACCESS_2_TRANSFER_READ_BIT, dstStageMask must include VK_PIPELINE_STAGE_2_COPY_BIT, VK_PIPELINE_STAGE_2_BLIT_BIT, VK_PIPELINE_STAGE_2_RESOLVE_BIT, VK_PIPELINE_STAGE_2_ALL_TRANSFER_BIT, VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_BUILD_BIT_KHR, VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_COPY_BIT_KHR, or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkBufferMemoryBarrier2-dstAccessMask-03915
    If dstAccessMask includes VK_ACCESS_2_TRANSFER_WRITE_BIT, dstStageMask must include VK_PIPELINE_STAGE_2_COPY_BIT, VK_PIPELINE_STAGE_2_BLIT_BIT, VK_PIPELINE_STAGE_2_RESOLVE_BIT, VK_PIPELINE_STAGE_2_CLEAR_BIT, VK_PIPELINE_STAGE_2_ALL_TRANSFER_BIT, VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_BUILD_BIT_KHR, or VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_COPY_BIT_KHR, VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkBufferMemoryBarrier2-dstAccessMask-03916
    If dstAccessMask includes VK_ACCESS_2_HOST_READ_BIT, dstStageMask must include VK_PIPELINE_STAGE_2_HOST_BIT

  • VUID-VkBufferMemoryBarrier2-dstAccessMask-03917
    If dstAccessMask includes VK_ACCESS_2_HOST_WRITE_BIT, dstStageMask must include VK_PIPELINE_STAGE_2_HOST_BIT

  • VUID-VkBufferMemoryBarrier2-dstAccessMask-03918
    If dstAccessMask includes VK_ACCESS_2_CONDITIONAL_RENDERING_READ_BIT_EXT, dstStageMask must include VK_PIPELINE_STAGE_2_CONDITIONAL_RENDERING_BIT_EXT, VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkBufferMemoryBarrier2-dstAccessMask-03919
    If dstAccessMask includes VK_ACCESS_2_FRAGMENT_DENSITY_MAP_READ_BIT_EXT, dstStageMask must include VK_PIPELINE_STAGE_2_FRAGMENT_DENSITY_PROCESS_BIT_EXT, VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkBufferMemoryBarrier2-dstAccessMask-03920
    If dstAccessMask includes VK_ACCESS_2_TRANSFORM_FEEDBACK_WRITE_BIT_EXT, dstStageMask must include VK_PIPELINE_STAGE_2_TRANSFORM_FEEDBACK_BIT_EXT, VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkBufferMemoryBarrier2-dstAccessMask-04747
    If dstAccessMask includes VK_ACCESS_2_TRANSFORM_FEEDBACK_COUNTER_READ_BIT_EXT, dstStageMask must include VK_PIPELINE_STAGE_2_DRAW_INDIRECT_BIT, VK_PIPELINE_STAGE_2_TRANSFORM_FEEDBACK_BIT_EXT, VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkBufferMemoryBarrier2-dstAccessMask-03922
    If dstAccessMask includes VK_ACCESS_2_TRANSFORM_FEEDBACK_COUNTER_WRITE_BIT_EXT, dstStageMask must include VK_PIPELINE_STAGE_2_TRANSFORM_FEEDBACK_BIT_EXT, VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkBufferMemoryBarrier2-dstAccessMask-03923
    If dstAccessMask includes VK_ACCESS_2_SHADING_RATE_IMAGE_READ_BIT_NV, dstStageMask must include VK_PIPELINE_STAGE_2_SHADING_RATE_IMAGE_BIT_NV, VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkBufferMemoryBarrier2-dstAccessMask-04994
    If dstAccessMask includes VK_ACCESS_2_INVOCATION_MASK_READ_BIT_HUAWEI, dstStageMask must include VK_PIPELINE_STAGE_2_INVOCATION_MASK_BIT_HUAWEI

  • VUID-VkBufferMemoryBarrier2-dstAccessMask-03924
    If dstAccessMask includes VK_ACCESS_2_COMMAND_PREPROCESS_READ_BIT_NV, dstStageMask must include VK_PIPELINE_STAGE_2_COMMAND_PREPROCESS_BIT_NV or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkBufferMemoryBarrier2-dstAccessMask-03925
    If dstAccessMask includes VK_ACCESS_2_COMMAND_PREPROCESS_WRITE_BIT_NV, dstStageMask must include VK_PIPELINE_STAGE_2_COMMAND_PREPROCESS_BIT_NV or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkBufferMemoryBarrier2-dstAccessMask-03926
    If dstAccessMask includes VK_ACCESS_2_COLOR_ATTACHMENT_READ_NONCOHERENT_BIT_EXT, dstStageMask must include VK_PIPELINE_STAGE_2_COLOR_ATTACHMENT_OUTPUT_BIT VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkBufferMemoryBarrier2-dstAccessMask-03927
    If dstAccessMask includes VK_ACCESS_2_ACCELERATION_STRUCTURE_READ_BIT_KHR, dstStageMask must include VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_BUILD_BIT_KHR, VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_COPY_BIT_KHR, VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT, or one of the VK_PIPELINE_STAGE_*_SHADER_BIT stages

  • VUID-VkBufferMemoryBarrier2-dstAccessMask-03928
    If dstAccessMask includes VK_ACCESS_2_ACCELERATION_STRUCTURE_WRITE_BIT_KHR, dstStageMask must include VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_COPY_BIT_KHR, VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_BUILD_BIT_KHR or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkBufferMemoryBarrier2-dstAccessMask-06256
    If the rayQuery feature is not enabled and dstAccessMask includes VK_ACCESS_2_ACCELERATION_STRUCTURE_READ_BIT_KHR, dstStageMask must not include any of the VK_PIPELINE_STAGE_*_SHADER_BIT stages except VK_PIPELINE_STAGE_2_RAY_TRACING_SHADER_BIT_KHR

  • VUID-VkBufferMemoryBarrier2-dstAccessMask-07272
    If dstAccessMask includes VK_ACCESS_2_SHADER_BINDING_TABLE_READ_BIT_KHR, dstStageMask must include VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT or VK_PIPELINE_STAGE_2_RAY_TRACING_SHADER_BIT_KHR

  • VUID-VkBufferMemoryBarrier2-dstAccessMask-04858
    If dstAccessMask includes VK_ACCESS_2_VIDEO_DECODE_READ_BIT_KHR, dstStageMask must include VK_PIPELINE_STAGE_2_VIDEO_DECODE_BIT_KHR

  • VUID-VkBufferMemoryBarrier2-dstAccessMask-04859
    If dstAccessMask includes VK_ACCESS_2_VIDEO_DECODE_WRITE_BIT_KHR, dstStageMask must include VK_PIPELINE_STAGE_2_VIDEO_DECODE_BIT_KHR

  • VUID-VkBufferMemoryBarrier2-dstAccessMask-04860
    If dstAccessMask includes VK_ACCESS_2_VIDEO_ENCODE_READ_BIT_KHR, dstStageMask must include VK_PIPELINE_STAGE_2_VIDEO_ENCODE_BIT_KHR

  • VUID-VkBufferMemoryBarrier2-dstAccessMask-04861
    If dstAccessMask includes VK_ACCESS_2_VIDEO_ENCODE_WRITE_BIT_KHR, dstStageMask must include VK_PIPELINE_STAGE_2_VIDEO_ENCODE_BIT_KHR

  • VUID-VkBufferMemoryBarrier2-dstAccessMask-07455
    If dstAccessMask includes VK_ACCESS_2_OPTICAL_FLOW_READ_BIT_NV, dstStageMask must include VK_PIPELINE_STAGE_2_OPTICAL_FLOW_BIT_NV

  • VUID-VkBufferMemoryBarrier2-dstAccessMask-07456
    If dstAccessMask includes VK_ACCESS_2_OPTICAL_FLOW_WRITE_BIT_NV, dstStageMask must include VK_PIPELINE_STAGE_2_OPTICAL_FLOW_BIT_NV

  • VUID-VkBufferMemoryBarrier2-dstAccessMask-07457
    If dstAccessMask includes VK_ACCESS_2_MICROMAP_WRITE_BIT_EXT, dstStageMask must include VK_PIPELINE_STAGE_2_MICROMAP_BUILD_BIT_EXT

  • VUID-VkBufferMemoryBarrier2-dstAccessMask-07458
    If dstAccessMask includes VK_ACCESS_2_MICROMAP_READ_BIT_EXT, dstStageMask must include VK_PIPELINE_STAGE_2_MICROMAP_BUILD_BIT_EXT or VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_BUILD_BIT_KHR

  • VUID-VkBufferMemoryBarrier2-dstAccessMask-08118
    If dstAccessMask includes VK_ACCESS_2_DESCRIPTOR_BUFFER_READ_BIT_EXT, dstStageMask must include VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT, or one of VK_PIPELINE_STAGE_*_SHADER_BIT stages

  • VUID-VkBufferMemoryBarrier2-offset-01187
    offset must be less than the size of buffer

  • VUID-VkBufferMemoryBarrier2-size-01188
    If size is not equal to VK_WHOLE_SIZE, size must be greater than 0

  • VUID-VkBufferMemoryBarrier2-size-01189
    If size is not equal to VK_WHOLE_SIZE, size must be less than or equal to than the size of buffer minus offset

  • VUID-VkBufferMemoryBarrier2-buffer-01931
    If buffer is non-sparse then it must be bound completely and contiguously to a single VkDeviceMemory object

  • VUID-VkBufferMemoryBarrier2-buffer-09095
    If buffer was created with a sharing mode of VK_SHARING_MODE_EXCLUSIVE, and srcQueueFamilyIndex and dstQueueFamilyIndex are not equal, srcQueueFamilyIndex must be VK_QUEUE_FAMILY_EXTERNAL, VK_QUEUE_FAMILY_FOREIGN_EXT, or a valid queue family

  • VUID-VkBufferMemoryBarrier2-buffer-09096
    If buffer was created with a sharing mode of VK_SHARING_MODE_EXCLUSIVE, and srcQueueFamilyIndex and dstQueueFamilyIndex are not equal, dstQueueFamilyIndex must be VK_QUEUE_FAMILY_EXTERNAL, VK_QUEUE_FAMILY_FOREIGN_EXT, or a valid queue family

  • VUID-VkBufferMemoryBarrier2-srcQueueFamilyIndex-04087
    If srcQueueFamilyIndex is not equal to dstQueueFamilyIndex, at least one of srcQueueFamilyIndex or dstQueueFamilyIndex must not be VK_QUEUE_FAMILY_EXTERNAL or VK_QUEUE_FAMILY_FOREIGN_EXT

  • VUID-VkBufferMemoryBarrier2-None-09097
    If the VK_KHR_external_memory extension is not enabled, and the value of VkApplicationInfo::apiVersion used to create the VkInstance is not greater than or equal to Version 1.1, srcQueueFamilyIndex must not be VK_QUEUE_FAMILY_EXTERNAL

  • VUID-VkBufferMemoryBarrier2-None-09098
    If the VK_KHR_external_memory extension is not enabled, and the value of VkApplicationInfo::apiVersion used to create the VkInstance is not greater than or equal to Version 1.1, dstQueueFamilyIndex must not be VK_QUEUE_FAMILY_EXTERNAL

  • VUID-VkBufferMemoryBarrier2-srcQueueFamilyIndex-09099
    If the VK_EXT_queue_family_foreign extension is not enabled srcQueueFamilyIndex must not be VK_QUEUE_FAMILY_FOREIGN_EXT

  • VUID-VkBufferMemoryBarrier2-dstQueueFamilyIndex-09100
    If the VK_EXT_queue_family_foreign extension is not enabled dstQueueFamilyIndex must not be VK_QUEUE_FAMILY_FOREIGN_EXT

  • VUID-VkBufferMemoryBarrier2-srcStageMask-03851
    If either srcStageMask or dstStageMask includes VK_PIPELINE_STAGE_2_HOST_BIT, srcQueueFamilyIndex and dstQueueFamilyIndex must be equal

Valid Usage (Implicit)

  • VUID-VkBufferMemoryBarrier2-sType-sType
    sType must be VK_STRUCTURE_TYPE_BUFFER_MEMORY_BARRIER_2

  • VUID-VkBufferMemoryBarrier2-pNext-pNext
    pNext must be NULL or a pointer to a valid instance of VkExternalMemoryAcquireUnmodifiedEXT

  • VUID-VkBufferMemoryBarrier2-sType-unique
    The sType value of each struct in the pNext chain must be unique

  • VUID-VkBufferMemoryBarrier2-srcStageMask-parameter
    srcStageMask must be a valid combination of VkPipelineStageFlagBits2 values

  • VUID-VkBufferMemoryBarrier2-srcAccessMask-parameter
    srcAccessMask must be a valid combination of VkAccessFlagBits2 values

  • VUID-VkBufferMemoryBarrier2-dstStageMask-parameter
    dstStageMask must be a valid combination of VkPipelineStageFlagBits2 values

  • VUID-VkBufferMemoryBarrier2-dstAccessMask-parameter
    dstAccessMask must be a valid combination of VkAccessFlagBits2 values

  • VUID-VkBufferMemoryBarrier2-buffer-parameter
    buffer must be a valid VkBuffer handle

The VkBufferMemoryBarrier structure is defined as:

// Provided by VK_VERSION_1_0
typedef struct VkBufferMemoryBarrier {
    VkStructureType    sType;
    const void*        pNext;
    VkAccessFlags      srcAccessMask;
    VkAccessFlags      dstAccessMask;
    uint32_t           srcQueueFamilyIndex;
    uint32_t           dstQueueFamilyIndex;
    VkBuffer           buffer;
    VkDeviceSize       offset;
    VkDeviceSize       size;
} VkBufferMemoryBarrier;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • srcAccessMask is a bitmask of VkAccessFlagBits specifying a source access mask.

  • dstAccessMask is a bitmask of VkAccessFlagBits specifying a destination access mask.

  • srcQueueFamilyIndex is the source queue family for a queue family ownership transfer.

  • dstQueueFamilyIndex is the destination queue family for a queue family ownership transfer.

  • buffer is a handle to the buffer whose backing memory is affected by the barrier.

  • offset is an offset in bytes into the backing memory for buffer; this is relative to the base offset as bound to the buffer (see vkBindBufferMemory).

  • size is a size in bytes of the affected area of backing memory for buffer, or VK_WHOLE_SIZE to use the range from offset to the end of the buffer.

The first access scope is limited to access to memory through the specified buffer range, via access types in the source access mask specified by srcAccessMask. If srcAccessMask includes VK_ACCESS_HOST_WRITE_BIT, a memory domain operation is performed where available memory in the host domain is also made available to the device domain.

The second access scope is limited to access to memory through the specified buffer range, via access types in the destination access mask specified by dstAccessMask. If dstAccessMask includes VK_ACCESS_HOST_WRITE_BIT or VK_ACCESS_HOST_READ_BIT, a memory domain operation is performed where available memory in the device domain is also made available to the host domain.

Note

When VK_MEMORY_PROPERTY_HOST_COHERENT_BIT is used, available memory in host domain is automatically made visible to host domain, and any host write is automatically made available to host domain.

If srcQueueFamilyIndex is not equal to dstQueueFamilyIndex, and srcQueueFamilyIndex is equal to the current queue family, then the memory barrier defines a queue family release operation for the specified buffer range, and the second synchronization scope of the calling command does not apply to this operation.

If dstQueueFamilyIndex is not equal to srcQueueFamilyIndex, and dstQueueFamilyIndex is equal to the current queue family, then the memory barrier defines a queue family acquire operation for the specified buffer range, and the first synchronization scope of the calling command does not apply to this operation.

Valid Usage

  • VUID-VkBufferMemoryBarrier-offset-01187
    offset must be less than the size of buffer

  • VUID-VkBufferMemoryBarrier-size-01188
    If size is not equal to VK_WHOLE_SIZE, size must be greater than 0

  • VUID-VkBufferMemoryBarrier-size-01189
    If size is not equal to VK_WHOLE_SIZE, size must be less than or equal to than the size of buffer minus offset

  • VUID-VkBufferMemoryBarrier-buffer-01931
    If buffer is non-sparse then it must be bound completely and contiguously to a single VkDeviceMemory object

  • VUID-VkBufferMemoryBarrier-buffer-09095
    If buffer was created with a sharing mode of VK_SHARING_MODE_EXCLUSIVE, and srcQueueFamilyIndex and dstQueueFamilyIndex are not equal, srcQueueFamilyIndex must be VK_QUEUE_FAMILY_EXTERNAL, VK_QUEUE_FAMILY_FOREIGN_EXT, or a valid queue family

  • VUID-VkBufferMemoryBarrier-buffer-09096
    If buffer was created with a sharing mode of VK_SHARING_MODE_EXCLUSIVE, and srcQueueFamilyIndex and dstQueueFamilyIndex are not equal, dstQueueFamilyIndex must be VK_QUEUE_FAMILY_EXTERNAL, VK_QUEUE_FAMILY_FOREIGN_EXT, or a valid queue family

  • VUID-VkBufferMemoryBarrier-srcQueueFamilyIndex-04087
    If srcQueueFamilyIndex is not equal to dstQueueFamilyIndex, at least one of srcQueueFamilyIndex or dstQueueFamilyIndex must not be VK_QUEUE_FAMILY_EXTERNAL or VK_QUEUE_FAMILY_FOREIGN_EXT

  • VUID-VkBufferMemoryBarrier-None-09097
    If the VK_KHR_external_memory extension is not enabled, and the value of VkApplicationInfo::apiVersion used to create the VkInstance is not greater than or equal to Version 1.1, srcQueueFamilyIndex must not be VK_QUEUE_FAMILY_EXTERNAL

  • VUID-VkBufferMemoryBarrier-None-09098
    If the VK_KHR_external_memory extension is not enabled, and the value of VkApplicationInfo::apiVersion used to create the VkInstance is not greater than or equal to Version 1.1, dstQueueFamilyIndex must not be VK_QUEUE_FAMILY_EXTERNAL

  • VUID-VkBufferMemoryBarrier-srcQueueFamilyIndex-09099
    If the VK_EXT_queue_family_foreign extension is not enabled srcQueueFamilyIndex must not be VK_QUEUE_FAMILY_FOREIGN_EXT

  • VUID-VkBufferMemoryBarrier-dstQueueFamilyIndex-09100
    If the VK_EXT_queue_family_foreign extension is not enabled dstQueueFamilyIndex must not be VK_QUEUE_FAMILY_FOREIGN_EXT

  • VUID-VkBufferMemoryBarrier-None-09049
    If the synchronization2 feature is not enabled, and buffer was created with a sharing mode of VK_SHARING_MODE_CONCURRENT, at least one of srcQueueFamilyIndex and dstQueueFamilyIndex must be VK_QUEUE_FAMILY_IGNORED

  • VUID-VkBufferMemoryBarrier-None-09050
    If the synchronization2 feature is not enabled, and buffer was created with a sharing mode of VK_SHARING_MODE_CONCURRENT, srcQueueFamilyIndex must be VK_QUEUE_FAMILY_IGNORED or VK_QUEUE_FAMILY_EXTERNAL

  • VUID-VkBufferMemoryBarrier-None-09051
    If the synchronization2 feature is not enabled, and buffer was created with a sharing mode of VK_SHARING_MODE_CONCURRENT, dstQueueFamilyIndex must be VK_QUEUE_FAMILY_IGNORED or VK_QUEUE_FAMILY_EXTERNAL

Valid Usage (Implicit)

  • VUID-VkBufferMemoryBarrier-sType-sType
    sType must be VK_STRUCTURE_TYPE_BUFFER_MEMORY_BARRIER

  • VUID-VkBufferMemoryBarrier-pNext-pNext
    pNext must be NULL or a pointer to a valid instance of VkExternalMemoryAcquireUnmodifiedEXT

  • VUID-VkBufferMemoryBarrier-sType-unique
    The sType value of each struct in the pNext chain must be unique

  • VUID-VkBufferMemoryBarrier-buffer-parameter
    buffer must be a valid VkBuffer handle

VK_WHOLE_SIZE is a special value indicating that the entire remaining length of a buffer following a given offset should be used. It can be specified for VkBufferMemoryBarrier::size and other structures.

#define VK_WHOLE_SIZE                     (~0ULL)

7.7.3. Image Memory Barriers

Image memory barriers only apply to memory accesses involving a specific image subresource range. That is, a memory dependency formed from an image memory barrier is scoped to access via the specified image subresource range. Image memory barriers can also be used to define image layout transitions or a queue family ownership transfer for the specified image subresource range.

The VkImageMemoryBarrier2 structure is defined as:

// Provided by VK_VERSION_1_3
typedef struct VkImageMemoryBarrier2 {
    VkStructureType            sType;
    const void*                pNext;
    VkPipelineStageFlags2      srcStageMask;
    VkAccessFlags2             srcAccessMask;
    VkPipelineStageFlags2      dstStageMask;
    VkAccessFlags2             dstAccessMask;
    VkImageLayout              oldLayout;
    VkImageLayout              newLayout;
    uint32_t                   srcQueueFamilyIndex;
    uint32_t                   dstQueueFamilyIndex;
    VkImage                    image;
    VkImageSubresourceRange    subresourceRange;
} VkImageMemoryBarrier2;

or the equivalent

// Provided by VK_KHR_synchronization2
typedef VkImageMemoryBarrier2 VkImageMemoryBarrier2KHR;

This structure defines a memory dependency limited to an image subresource range, and can define a queue family ownership transfer operation and image layout transition for that subresource range.

The first synchronization scope and access scope described by this structure include only operations and memory accesses specified by srcStageMask and srcAccessMask.

The second synchronization scope and access scope described by this structure include only operations and memory accesses specified by dstStageMask and dstAccessMask.

Both access scopes are limited to only memory accesses to image in the subresource range defined by subresourceRange.

If image was created with VK_SHARING_MODE_EXCLUSIVE, and srcQueueFamilyIndex is not equal to dstQueueFamilyIndex, this memory barrier defines a queue family ownership transfer operation. When executed on a queue in the family identified by srcQueueFamilyIndex, this barrier defines a queue family release operation for the specified image subresource range, and the second synchronization scope does not apply to this operation. When executed on a queue in the family identified by dstQueueFamilyIndex, this barrier defines a queue family acquire operation for the specified image subresource range, and the first synchronization, the first synchronization scope does not apply to this operation.

A queue family ownership transfer operation is also defined if the values are not equal, and either is one of the special queue family values reserved for external memory ownership transfers, as described in Queue Family Ownership Transfer. A queue family release operation is defined when dstQueueFamilyIndex is one of those values, and a queue family acquire operation is defined when srcQueueFamilyIndex is one of those values.

If oldLayout is not equal to newLayout, then the memory barrier defines an image layout transition for the specified image subresource range. If this memory barrier defines a queue family ownership transfer operation, the layout transition is only executed once between the queues.

Note

When the old and new layout are equal, the layout values are ignored - data is preserved no matter what values are specified, or what layout the image is currently in.

If image has a multi-planar format and the image is disjoint, then including VK_IMAGE_ASPECT_COLOR_BIT in the aspectMask member of subresourceRange is equivalent to including VK_IMAGE_ASPECT_PLANE_0_BIT, VK_IMAGE_ASPECT_PLANE_1_BIT, and (for three-plane formats only) VK_IMAGE_ASPECT_PLANE_2_BIT.

Valid Usage

  • VUID-VkImageMemoryBarrier2-srcStageMask-03929
    If the geometryShader feature is not enabled, srcStageMask must not contain VK_PIPELINE_STAGE_2_GEOMETRY_SHADER_BIT

  • VUID-VkImageMemoryBarrier2-srcStageMask-03930
    If the tessellationShader feature is not enabled, srcStageMask must not contain VK_PIPELINE_STAGE_2_TESSELLATION_CONTROL_SHADER_BIT or VK_PIPELINE_STAGE_2_TESSELLATION_EVALUATION_SHADER_BIT

  • VUID-VkImageMemoryBarrier2-srcStageMask-03931
    If the conditionalRendering feature is not enabled, srcStageMask must not contain VK_PIPELINE_STAGE_2_CONDITIONAL_RENDERING_BIT_EXT

  • VUID-VkImageMemoryBarrier2-srcStageMask-03932
    If the fragmentDensityMap feature is not enabled, srcStageMask must not contain VK_PIPELINE_STAGE_2_FRAGMENT_DENSITY_PROCESS_BIT_EXT

  • VUID-VkImageMemoryBarrier2-srcStageMask-03933
    If the transformFeedback feature is not enabled, srcStageMask must not contain VK_PIPELINE_STAGE_2_TRANSFORM_FEEDBACK_BIT_EXT

  • VUID-VkImageMemoryBarrier2-srcStageMask-03934
    If the meshShader feature is not enabled, srcStageMask must not contain VK_PIPELINE_STAGE_2_MESH_SHADER_BIT_EXT

  • VUID-VkImageMemoryBarrier2-srcStageMask-03935
    If the taskShader feature is not enabled, srcStageMask must not contain VK_PIPELINE_STAGE_2_TASK_SHADER_BIT_EXT

  • VUID-VkImageMemoryBarrier2-srcStageMask-07316
    If neither the shadingRateImage or attachmentFragmentShadingRate are enabled, srcStageMask must not contain VK_PIPELINE_STAGE_2_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR

  • VUID-VkImageMemoryBarrier2-srcStageMask-04957
    If the subpassShading feature is not enabled, srcStageMask must not contain VK_PIPELINE_STAGE_2_SUBPASS_SHADER_BIT_HUAWEI

  • VUID-VkImageMemoryBarrier2-srcStageMask-04995
    If the invocationMask feature is not enabled, srcStageMask must not contain VK_PIPELINE_STAGE_2_INVOCATION_MASK_BIT_HUAWEI

  • VUID-VkImageMemoryBarrier2-srcStageMask-07946
    If neither the VK_NV_ray_tracing extension or rayTracingPipeline feature are enabled, srcStageMask must not contain VK_PIPELINE_STAGE_2_RAY_TRACING_SHADER_BIT_KHR

  • VUID-VkImageMemoryBarrier2-srcAccessMask-03900
    If srcAccessMask includes VK_ACCESS_2_INDIRECT_COMMAND_READ_BIT, srcStageMask must include VK_PIPELINE_STAGE_2_DRAW_INDIRECT_BIT, VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_BUILD_BIT_KHR, VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkImageMemoryBarrier2-srcAccessMask-03901
    If srcAccessMask includes VK_ACCESS_2_INDEX_READ_BIT, srcStageMask must include VK_PIPELINE_STAGE_2_INDEX_INPUT_BIT, VK_PIPELINE_STAGE_2_VERTEX_INPUT_BIT, VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkImageMemoryBarrier2-srcAccessMask-03902
    If srcAccessMask includes VK_ACCESS_2_VERTEX_ATTRIBUTE_READ_BIT, srcStageMask must include VK_PIPELINE_STAGE_2_VERTEX_ATTRIBUTE_INPUT_BIT, VK_PIPELINE_STAGE_2_VERTEX_INPUT_BIT, VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkImageMemoryBarrier2-srcAccessMask-03903
    If srcAccessMask includes VK_ACCESS_2_INPUT_ATTACHMENT_READ_BIT, srcStageMask must include VK_PIPELINE_STAGE_2_FRAGMENT_SHADER_BIT, VK_PIPELINE_STAGE_2_SUBPASS_SHADER_BIT_HUAWEI, VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkImageMemoryBarrier2-srcAccessMask-03904
    If srcAccessMask includes VK_ACCESS_2_UNIFORM_READ_BIT, srcStageMask must include VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT, or one of the VK_PIPELINE_STAGE_*_SHADER_BIT stages

  • VUID-VkImageMemoryBarrier2-srcAccessMask-03905
    If srcAccessMask includes VK_ACCESS_2_SHADER_SAMPLED_READ_BIT, srcStageMask must include VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT, or one of the VK_PIPELINE_STAGE_*_SHADER_BIT stages

  • VUID-VkImageMemoryBarrier2-srcAccessMask-03906
    If srcAccessMask includes VK_ACCESS_2_SHADER_STORAGE_READ_BIT, srcStageMask must include VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT, or one of the VK_PIPELINE_STAGE_*_SHADER_BIT stages

  • VUID-VkImageMemoryBarrier2-srcAccessMask-03907
    If srcAccessMask includes VK_ACCESS_2_SHADER_STORAGE_WRITE_BIT, srcStageMask must include VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT, or one of the VK_PIPELINE_STAGE_*_SHADER_BIT stages

  • VUID-VkImageMemoryBarrier2-srcAccessMask-07454
    If srcAccessMask includes VK_ACCESS_2_SHADER_READ_BIT, srcStageMask must include VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT, VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_BUILD_BIT_KHR, VK_PIPELINE_STAGE_2_MICROMAP_BUILD_BIT_EXT, or one of the VK_PIPELINE_STAGE_*_SHADER_BIT stages

  • VUID-VkImageMemoryBarrier2-srcAccessMask-03909
    If srcAccessMask includes VK_ACCESS_2_SHADER_WRITE_BIT, srcStageMask must include VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT, or one of the VK_PIPELINE_STAGE_*_SHADER_BIT stages

  • VUID-VkImageMemoryBarrier2-srcAccessMask-03910
    If srcAccessMask includes VK_ACCESS_2_COLOR_ATTACHMENT_READ_BIT, srcStageMask must include VK_PIPELINE_STAGE_2_COLOR_ATTACHMENT_OUTPUT_BIT VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkImageMemoryBarrier2-srcAccessMask-03911
    If srcAccessMask includes VK_ACCESS_2_COLOR_ATTACHMENT_WRITE_BIT, srcStageMask must include VK_PIPELINE_STAGE_2_COLOR_ATTACHMENT_OUTPUT_BIT VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkImageMemoryBarrier2-srcAccessMask-03912
    If srcAccessMask includes VK_ACCESS_2_DEPTH_STENCIL_ATTACHMENT_READ_BIT, srcStageMask must include VK_PIPELINE_STAGE_2_EARLY_FRAGMENT_TESTS_BIT, VK_PIPELINE_STAGE_2_LATE_FRAGMENT_TESTS_BIT, VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkImageMemoryBarrier2-srcAccessMask-03913
    If srcAccessMask includes VK_ACCESS_2_DEPTH_STENCIL_ATTACHMENT_WRITE_BIT, srcStageMask must include VK_PIPELINE_STAGE_2_EARLY_FRAGMENT_TESTS_BIT, VK_PIPELINE_STAGE_2_LATE_FRAGMENT_TESTS_BIT, VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkImageMemoryBarrier2-srcAccessMask-03914
    If srcAccessMask includes VK_ACCESS_2_TRANSFER_READ_BIT, srcStageMask must include VK_PIPELINE_STAGE_2_COPY_BIT, VK_PIPELINE_STAGE_2_BLIT_BIT, VK_PIPELINE_STAGE_2_RESOLVE_BIT, VK_PIPELINE_STAGE_2_ALL_TRANSFER_BIT, VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_BUILD_BIT_KHR, VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_COPY_BIT_KHR, or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkImageMemoryBarrier2-srcAccessMask-03915
    If srcAccessMask includes VK_ACCESS_2_TRANSFER_WRITE_BIT, srcStageMask must include VK_PIPELINE_STAGE_2_COPY_BIT, VK_PIPELINE_STAGE_2_BLIT_BIT, VK_PIPELINE_STAGE_2_RESOLVE_BIT, VK_PIPELINE_STAGE_2_CLEAR_BIT, VK_PIPELINE_STAGE_2_ALL_TRANSFER_BIT, VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_BUILD_BIT_KHR, or VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_COPY_BIT_KHR, VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkImageMemoryBarrier2-srcAccessMask-03916
    If srcAccessMask includes VK_ACCESS_2_HOST_READ_BIT, srcStageMask must include VK_PIPELINE_STAGE_2_HOST_BIT

  • VUID-VkImageMemoryBarrier2-srcAccessMask-03917
    If srcAccessMask includes VK_ACCESS_2_HOST_WRITE_BIT, srcStageMask must include VK_PIPELINE_STAGE_2_HOST_BIT

  • VUID-VkImageMemoryBarrier2-srcAccessMask-03918
    If srcAccessMask includes VK_ACCESS_2_CONDITIONAL_RENDERING_READ_BIT_EXT, srcStageMask must include VK_PIPELINE_STAGE_2_CONDITIONAL_RENDERING_BIT_EXT, VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkImageMemoryBarrier2-srcAccessMask-03919
    If srcAccessMask includes VK_ACCESS_2_FRAGMENT_DENSITY_MAP_READ_BIT_EXT, srcStageMask must include VK_PIPELINE_STAGE_2_FRAGMENT_DENSITY_PROCESS_BIT_EXT, VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkImageMemoryBarrier2-srcAccessMask-03920
    If srcAccessMask includes VK_ACCESS_2_TRANSFORM_FEEDBACK_WRITE_BIT_EXT, srcStageMask must include VK_PIPELINE_STAGE_2_TRANSFORM_FEEDBACK_BIT_EXT, VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkImageMemoryBarrier2-srcAccessMask-04747
    If srcAccessMask includes VK_ACCESS_2_TRANSFORM_FEEDBACK_COUNTER_READ_BIT_EXT, srcStageMask must include VK_PIPELINE_STAGE_2_DRAW_INDIRECT_BIT, VK_PIPELINE_STAGE_2_TRANSFORM_FEEDBACK_BIT_EXT, VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkImageMemoryBarrier2-srcAccessMask-03922
    If srcAccessMask includes VK_ACCESS_2_TRANSFORM_FEEDBACK_COUNTER_WRITE_BIT_EXT, srcStageMask must include VK_PIPELINE_STAGE_2_TRANSFORM_FEEDBACK_BIT_EXT, VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkImageMemoryBarrier2-srcAccessMask-03923
    If srcAccessMask includes VK_ACCESS_2_SHADING_RATE_IMAGE_READ_BIT_NV, srcStageMask must include VK_PIPELINE_STAGE_2_SHADING_RATE_IMAGE_BIT_NV, VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkImageMemoryBarrier2-srcAccessMask-04994
    If srcAccessMask includes VK_ACCESS_2_INVOCATION_MASK_READ_BIT_HUAWEI, srcStageMask must include VK_PIPELINE_STAGE_2_INVOCATION_MASK_BIT_HUAWEI

  • VUID-VkImageMemoryBarrier2-srcAccessMask-03924
    If srcAccessMask includes VK_ACCESS_2_COMMAND_PREPROCESS_READ_BIT_NV, srcStageMask must include VK_PIPELINE_STAGE_2_COMMAND_PREPROCESS_BIT_NV or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkImageMemoryBarrier2-srcAccessMask-03925
    If srcAccessMask includes VK_ACCESS_2_COMMAND_PREPROCESS_WRITE_BIT_NV, srcStageMask must include VK_PIPELINE_STAGE_2_COMMAND_PREPROCESS_BIT_NV or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkImageMemoryBarrier2-srcAccessMask-03926
    If srcAccessMask includes VK_ACCESS_2_COLOR_ATTACHMENT_READ_NONCOHERENT_BIT_EXT, srcStageMask must include VK_PIPELINE_STAGE_2_COLOR_ATTACHMENT_OUTPUT_BIT VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkImageMemoryBarrier2-srcAccessMask-03927
    If srcAccessMask includes VK_ACCESS_2_ACCELERATION_STRUCTURE_READ_BIT_KHR, srcStageMask must include VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_BUILD_BIT_KHR, VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_COPY_BIT_KHR, VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT, or one of the VK_PIPELINE_STAGE_*_SHADER_BIT stages

  • VUID-VkImageMemoryBarrier2-srcAccessMask-03928
    If srcAccessMask includes VK_ACCESS_2_ACCELERATION_STRUCTURE_WRITE_BIT_KHR, srcStageMask must include VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_COPY_BIT_KHR, VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_BUILD_BIT_KHR or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkImageMemoryBarrier2-srcAccessMask-06256
    If the rayQuery feature is not enabled and srcAccessMask includes VK_ACCESS_2_ACCELERATION_STRUCTURE_READ_BIT_KHR, srcStageMask must not include any of the VK_PIPELINE_STAGE_*_SHADER_BIT stages except VK_PIPELINE_STAGE_2_RAY_TRACING_SHADER_BIT_KHR

  • VUID-VkImageMemoryBarrier2-srcAccessMask-07272
    If srcAccessMask includes VK_ACCESS_2_SHADER_BINDING_TABLE_READ_BIT_KHR, srcStageMask must include VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT or VK_PIPELINE_STAGE_2_RAY_TRACING_SHADER_BIT_KHR

  • VUID-VkImageMemoryBarrier2-srcAccessMask-04858
    If srcAccessMask includes VK_ACCESS_2_VIDEO_DECODE_READ_BIT_KHR, srcStageMask must include VK_PIPELINE_STAGE_2_VIDEO_DECODE_BIT_KHR

  • VUID-VkImageMemoryBarrier2-srcAccessMask-04859
    If srcAccessMask includes VK_ACCESS_2_VIDEO_DECODE_WRITE_BIT_KHR, srcStageMask must include VK_PIPELINE_STAGE_2_VIDEO_DECODE_BIT_KHR

  • VUID-VkImageMemoryBarrier2-srcAccessMask-04860
    If srcAccessMask includes VK_ACCESS_2_VIDEO_ENCODE_READ_BIT_KHR, srcStageMask must include VK_PIPELINE_STAGE_2_VIDEO_ENCODE_BIT_KHR

  • VUID-VkImageMemoryBarrier2-srcAccessMask-04861
    If srcAccessMask includes VK_ACCESS_2_VIDEO_ENCODE_WRITE_BIT_KHR, srcStageMask must include VK_PIPELINE_STAGE_2_VIDEO_ENCODE_BIT_KHR

  • VUID-VkImageMemoryBarrier2-srcAccessMask-07455
    If srcAccessMask includes VK_ACCESS_2_OPTICAL_FLOW_READ_BIT_NV, srcStageMask must include VK_PIPELINE_STAGE_2_OPTICAL_FLOW_BIT_NV

  • VUID-VkImageMemoryBarrier2-srcAccessMask-07456
    If srcAccessMask includes VK_ACCESS_2_OPTICAL_FLOW_WRITE_BIT_NV, srcStageMask must include VK_PIPELINE_STAGE_2_OPTICAL_FLOW_BIT_NV

  • VUID-VkImageMemoryBarrier2-srcAccessMask-07457
    If srcAccessMask includes VK_ACCESS_2_MICROMAP_WRITE_BIT_EXT, srcStageMask must include VK_PIPELINE_STAGE_2_MICROMAP_BUILD_BIT_EXT

  • VUID-VkImageMemoryBarrier2-srcAccessMask-07458
    If srcAccessMask includes VK_ACCESS_2_MICROMAP_READ_BIT_EXT, srcStageMask must include VK_PIPELINE_STAGE_2_MICROMAP_BUILD_BIT_EXT or VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_BUILD_BIT_KHR

  • VUID-VkImageMemoryBarrier2-srcAccessMask-08118
    If srcAccessMask includes VK_ACCESS_2_DESCRIPTOR_BUFFER_READ_BIT_EXT, srcStageMask must include VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT, or one of VK_PIPELINE_STAGE_*_SHADER_BIT stages

  • VUID-VkImageMemoryBarrier2-dstStageMask-03929
    If the geometryShader feature is not enabled, dstStageMask must not contain VK_PIPELINE_STAGE_2_GEOMETRY_SHADER_BIT

  • VUID-VkImageMemoryBarrier2-dstStageMask-03930
    If the tessellationShader feature is not enabled, dstStageMask must not contain VK_PIPELINE_STAGE_2_TESSELLATION_CONTROL_SHADER_BIT or VK_PIPELINE_STAGE_2_TESSELLATION_EVALUATION_SHADER_BIT

  • VUID-VkImageMemoryBarrier2-dstStageMask-03931
    If the conditionalRendering feature is not enabled, dstStageMask must not contain VK_PIPELINE_STAGE_2_CONDITIONAL_RENDERING_BIT_EXT

  • VUID-VkImageMemoryBarrier2-dstStageMask-03932
    If the fragmentDensityMap feature is not enabled, dstStageMask must not contain VK_PIPELINE_STAGE_2_FRAGMENT_DENSITY_PROCESS_BIT_EXT

  • VUID-VkImageMemoryBarrier2-dstStageMask-03933
    If the transformFeedback feature is not enabled, dstStageMask must not contain VK_PIPELINE_STAGE_2_TRANSFORM_FEEDBACK_BIT_EXT

  • VUID-VkImageMemoryBarrier2-dstStageMask-03934
    If the meshShader feature is not enabled, dstStageMask must not contain VK_PIPELINE_STAGE_2_MESH_SHADER_BIT_EXT

  • VUID-VkImageMemoryBarrier2-dstStageMask-03935
    If the taskShader feature is not enabled, dstStageMask must not contain VK_PIPELINE_STAGE_2_TASK_SHADER_BIT_EXT

  • VUID-VkImageMemoryBarrier2-dstStageMask-07316
    If neither the shadingRateImage or attachmentFragmentShadingRate are enabled, dstStageMask must not contain VK_PIPELINE_STAGE_2_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR

  • VUID-VkImageMemoryBarrier2-dstStageMask-04957
    If the subpassShading feature is not enabled, dstStageMask must not contain VK_PIPELINE_STAGE_2_SUBPASS_SHADER_BIT_HUAWEI

  • VUID-VkImageMemoryBarrier2-dstStageMask-04995
    If the invocationMask feature is not enabled, dstStageMask must not contain VK_PIPELINE_STAGE_2_INVOCATION_MASK_BIT_HUAWEI

  • VUID-VkImageMemoryBarrier2-dstStageMask-07946
    If neither the VK_NV_ray_tracing extension or rayTracingPipeline feature are enabled, dstStageMask must not contain VK_PIPELINE_STAGE_2_RAY_TRACING_SHADER_BIT_KHR

  • VUID-VkImageMemoryBarrier2-dstAccessMask-03900
    If dstAccessMask includes VK_ACCESS_2_INDIRECT_COMMAND_READ_BIT, dstStageMask must include VK_PIPELINE_STAGE_2_DRAW_INDIRECT_BIT, VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_BUILD_BIT_KHR, VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkImageMemoryBarrier2-dstAccessMask-03901
    If dstAccessMask includes VK_ACCESS_2_INDEX_READ_BIT, dstStageMask must include VK_PIPELINE_STAGE_2_INDEX_INPUT_BIT, VK_PIPELINE_STAGE_2_VERTEX_INPUT_BIT, VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkImageMemoryBarrier2-dstAccessMask-03902
    If dstAccessMask includes VK_ACCESS_2_VERTEX_ATTRIBUTE_READ_BIT, dstStageMask must include VK_PIPELINE_STAGE_2_VERTEX_ATTRIBUTE_INPUT_BIT, VK_PIPELINE_STAGE_2_VERTEX_INPUT_BIT, VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkImageMemoryBarrier2-dstAccessMask-03903
    If dstAccessMask includes VK_ACCESS_2_INPUT_ATTACHMENT_READ_BIT, dstStageMask must include VK_PIPELINE_STAGE_2_FRAGMENT_SHADER_BIT, VK_PIPELINE_STAGE_2_SUBPASS_SHADER_BIT_HUAWEI, VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkImageMemoryBarrier2-dstAccessMask-03904
    If dstAccessMask includes VK_ACCESS_2_UNIFORM_READ_BIT, dstStageMask must include VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT, or one of the VK_PIPELINE_STAGE_*_SHADER_BIT stages

  • VUID-VkImageMemoryBarrier2-dstAccessMask-03905
    If dstAccessMask includes VK_ACCESS_2_SHADER_SAMPLED_READ_BIT, dstStageMask must include VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT, or one of the VK_PIPELINE_STAGE_*_SHADER_BIT stages

  • VUID-VkImageMemoryBarrier2-dstAccessMask-03906
    If dstAccessMask includes VK_ACCESS_2_SHADER_STORAGE_READ_BIT, dstStageMask must include VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT, or one of the VK_PIPELINE_STAGE_*_SHADER_BIT stages

  • VUID-VkImageMemoryBarrier2-dstAccessMask-03907
    If dstAccessMask includes VK_ACCESS_2_SHADER_STORAGE_WRITE_BIT, dstStageMask must include VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT, or one of the VK_PIPELINE_STAGE_*_SHADER_BIT stages

  • VUID-VkImageMemoryBarrier2-dstAccessMask-07454
    If dstAccessMask includes VK_ACCESS_2_SHADER_READ_BIT, dstStageMask must include VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT, VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_BUILD_BIT_KHR, VK_PIPELINE_STAGE_2_MICROMAP_BUILD_BIT_EXT, or one of the VK_PIPELINE_STAGE_*_SHADER_BIT stages

  • VUID-VkImageMemoryBarrier2-dstAccessMask-03909
    If dstAccessMask includes VK_ACCESS_2_SHADER_WRITE_BIT, dstStageMask must include VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT, or one of the VK_PIPELINE_STAGE_*_SHADER_BIT stages

  • VUID-VkImageMemoryBarrier2-dstAccessMask-03910
    If dstAccessMask includes VK_ACCESS_2_COLOR_ATTACHMENT_READ_BIT, dstStageMask must include VK_PIPELINE_STAGE_2_COLOR_ATTACHMENT_OUTPUT_BIT VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkImageMemoryBarrier2-dstAccessMask-03911
    If dstAccessMask includes VK_ACCESS_2_COLOR_ATTACHMENT_WRITE_BIT, dstStageMask must include VK_PIPELINE_STAGE_2_COLOR_ATTACHMENT_OUTPUT_BIT VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkImageMemoryBarrier2-dstAccessMask-03912
    If dstAccessMask includes VK_ACCESS_2_DEPTH_STENCIL_ATTACHMENT_READ_BIT, dstStageMask must include VK_PIPELINE_STAGE_2_EARLY_FRAGMENT_TESTS_BIT, VK_PIPELINE_STAGE_2_LATE_FRAGMENT_TESTS_BIT, VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkImageMemoryBarrier2-dstAccessMask-03913
    If dstAccessMask includes VK_ACCESS_2_DEPTH_STENCIL_ATTACHMENT_WRITE_BIT, dstStageMask must include VK_PIPELINE_STAGE_2_EARLY_FRAGMENT_TESTS_BIT, VK_PIPELINE_STAGE_2_LATE_FRAGMENT_TESTS_BIT, VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkImageMemoryBarrier2-dstAccessMask-03914
    If dstAccessMask includes VK_ACCESS_2_TRANSFER_READ_BIT, dstStageMask must include VK_PIPELINE_STAGE_2_COPY_BIT, VK_PIPELINE_STAGE_2_BLIT_BIT, VK_PIPELINE_STAGE_2_RESOLVE_BIT, VK_PIPELINE_STAGE_2_ALL_TRANSFER_BIT, VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_BUILD_BIT_KHR, VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_COPY_BIT_KHR, or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkImageMemoryBarrier2-dstAccessMask-03915
    If dstAccessMask includes VK_ACCESS_2_TRANSFER_WRITE_BIT, dstStageMask must include VK_PIPELINE_STAGE_2_COPY_BIT, VK_PIPELINE_STAGE_2_BLIT_BIT, VK_PIPELINE_STAGE_2_RESOLVE_BIT, VK_PIPELINE_STAGE_2_CLEAR_BIT, VK_PIPELINE_STAGE_2_ALL_TRANSFER_BIT, VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_BUILD_BIT_KHR, or VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_COPY_BIT_KHR, VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkImageMemoryBarrier2-dstAccessMask-03916
    If dstAccessMask includes VK_ACCESS_2_HOST_READ_BIT, dstStageMask must include VK_PIPELINE_STAGE_2_HOST_BIT

  • VUID-VkImageMemoryBarrier2-dstAccessMask-03917
    If dstAccessMask includes VK_ACCESS_2_HOST_WRITE_BIT, dstStageMask must include VK_PIPELINE_STAGE_2_HOST_BIT

  • VUID-VkImageMemoryBarrier2-dstAccessMask-03918
    If dstAccessMask includes VK_ACCESS_2_CONDITIONAL_RENDERING_READ_BIT_EXT, dstStageMask must include VK_PIPELINE_STAGE_2_CONDITIONAL_RENDERING_BIT_EXT, VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkImageMemoryBarrier2-dstAccessMask-03919
    If dstAccessMask includes VK_ACCESS_2_FRAGMENT_DENSITY_MAP_READ_BIT_EXT, dstStageMask must include VK_PIPELINE_STAGE_2_FRAGMENT_DENSITY_PROCESS_BIT_EXT, VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkImageMemoryBarrier2-dstAccessMask-03920
    If dstAccessMask includes VK_ACCESS_2_TRANSFORM_FEEDBACK_WRITE_BIT_EXT, dstStageMask must include VK_PIPELINE_STAGE_2_TRANSFORM_FEEDBACK_BIT_EXT, VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkImageMemoryBarrier2-dstAccessMask-04747
    If dstAccessMask includes VK_ACCESS_2_TRANSFORM_FEEDBACK_COUNTER_READ_BIT_EXT, dstStageMask must include VK_PIPELINE_STAGE_2_DRAW_INDIRECT_BIT, VK_PIPELINE_STAGE_2_TRANSFORM_FEEDBACK_BIT_EXT, VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkImageMemoryBarrier2-dstAccessMask-03922
    If dstAccessMask includes VK_ACCESS_2_TRANSFORM_FEEDBACK_COUNTER_WRITE_BIT_EXT, dstStageMask must include VK_PIPELINE_STAGE_2_TRANSFORM_FEEDBACK_BIT_EXT, VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkImageMemoryBarrier2-dstAccessMask-03923
    If dstAccessMask includes VK_ACCESS_2_SHADING_RATE_IMAGE_READ_BIT_NV, dstStageMask must include VK_PIPELINE_STAGE_2_SHADING_RATE_IMAGE_BIT_NV, VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkImageMemoryBarrier2-dstAccessMask-04994
    If dstAccessMask includes VK_ACCESS_2_INVOCATION_MASK_READ_BIT_HUAWEI, dstStageMask must include VK_PIPELINE_STAGE_2_INVOCATION_MASK_BIT_HUAWEI

  • VUID-VkImageMemoryBarrier2-dstAccessMask-03924
    If dstAccessMask includes VK_ACCESS_2_COMMAND_PREPROCESS_READ_BIT_NV, dstStageMask must include VK_PIPELINE_STAGE_2_COMMAND_PREPROCESS_BIT_NV or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkImageMemoryBarrier2-dstAccessMask-03925
    If dstAccessMask includes VK_ACCESS_2_COMMAND_PREPROCESS_WRITE_BIT_NV, dstStageMask must include VK_PIPELINE_STAGE_2_COMMAND_PREPROCESS_BIT_NV or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkImageMemoryBarrier2-dstAccessMask-03926
    If dstAccessMask includes VK_ACCESS_2_COLOR_ATTACHMENT_READ_NONCOHERENT_BIT_EXT, dstStageMask must include VK_PIPELINE_STAGE_2_COLOR_ATTACHMENT_OUTPUT_BIT VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkImageMemoryBarrier2-dstAccessMask-03927
    If dstAccessMask includes VK_ACCESS_2_ACCELERATION_STRUCTURE_READ_BIT_KHR, dstStageMask must include VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_BUILD_BIT_KHR, VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_COPY_BIT_KHR, VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT, or one of the VK_PIPELINE_STAGE_*_SHADER_BIT stages

  • VUID-VkImageMemoryBarrier2-dstAccessMask-03928
    If dstAccessMask includes VK_ACCESS_2_ACCELERATION_STRUCTURE_WRITE_BIT_KHR, dstStageMask must include VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_COPY_BIT_KHR, VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_BUILD_BIT_KHR or VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

  • VUID-VkImageMemoryBarrier2-dstAccessMask-06256
    If the rayQuery feature is not enabled and dstAccessMask includes VK_ACCESS_2_ACCELERATION_STRUCTURE_READ_BIT_KHR, dstStageMask must not include any of the VK_PIPELINE_STAGE_*_SHADER_BIT stages except VK_PIPELINE_STAGE_2_RAY_TRACING_SHADER_BIT_KHR

  • VUID-VkImageMemoryBarrier2-dstAccessMask-07272
    If dstAccessMask includes VK_ACCESS_2_SHADER_BINDING_TABLE_READ_BIT_KHR, dstStageMask must include VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT or VK_PIPELINE_STAGE_2_RAY_TRACING_SHADER_BIT_KHR

  • VUID-VkImageMemoryBarrier2-dstAccessMask-04858
    If dstAccessMask includes VK_ACCESS_2_VIDEO_DECODE_READ_BIT_KHR, dstStageMask must include VK_PIPELINE_STAGE_2_VIDEO_DECODE_BIT_KHR

  • VUID-VkImageMemoryBarrier2-dstAccessMask-04859
    If dstAccessMask includes VK_ACCESS_2_VIDEO_DECODE_WRITE_BIT_KHR, dstStageMask must include VK_PIPELINE_STAGE_2_VIDEO_DECODE_BIT_KHR

  • VUID-VkImageMemoryBarrier2-dstAccessMask-04860
    If dstAccessMask includes VK_ACCESS_2_VIDEO_ENCODE_READ_BIT_KHR, dstStageMask must include VK_PIPELINE_STAGE_2_VIDEO_ENCODE_BIT_KHR

  • VUID-VkImageMemoryBarrier2-dstAccessMask-04861
    If dstAccessMask includes VK_ACCESS_2_VIDEO_ENCODE_WRITE_BIT_KHR, dstStageMask must include VK_PIPELINE_STAGE_2_VIDEO_ENCODE_BIT_KHR

  • VUID-VkImageMemoryBarrier2-dstAccessMask-07455
    If dstAccessMask includes VK_ACCESS_2_OPTICAL_FLOW_READ_BIT_NV, dstStageMask must include VK_PIPELINE_STAGE_2_OPTICAL_FLOW_BIT_NV

  • VUID-VkImageMemoryBarrier2-dstAccessMask-07456
    If dstAccessMask includes VK_ACCESS_2_OPTICAL_FLOW_WRITE_BIT_NV, dstStageMask must include VK_PIPELINE_STAGE_2_OPTICAL_FLOW_BIT_NV

  • VUID-VkImageMemoryBarrier2-dstAccessMask-07457
    If dstAccessMask includes VK_ACCESS_2_MICROMAP_WRITE_BIT_EXT, dstStageMask must include VK_PIPELINE_STAGE_2_MICROMAP_BUILD_BIT_EXT

  • VUID-VkImageMemoryBarrier2-dstAccessMask-07458
    If dstAccessMask includes VK_ACCESS_2_MICROMAP_READ_BIT_EXT, dstStageMask must include VK_PIPELINE_STAGE_2_MICROMAP_BUILD_BIT_EXT or VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_BUILD_BIT_KHR

  • VUID-VkImageMemoryBarrier2-dstAccessMask-08118
    If dstAccessMask includes VK_ACCESS_2_DESCRIPTOR_BUFFER_READ_BIT_EXT, dstStageMask must include VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT, or one of VK_PIPELINE_STAGE_*_SHADER_BIT stages

  • VUID-VkImageMemoryBarrier2-oldLayout-01208
    If srcQueueFamilyIndex and dstQueueFamilyIndex define a queue family ownership transfer or oldLayout and newLayout define an image layout transition, and oldLayout or newLayout is VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL then image must have been created with VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT

  • VUID-VkImageMemoryBarrier2-oldLayout-01209
    If srcQueueFamilyIndex and dstQueueFamilyIndex define a queue family ownership transfer or oldLayout and newLayout define an image layout transition, and oldLayout or newLayout is VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL then image must have been created with VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT

  • VUID-VkImageMemoryBarrier2-oldLayout-01210
    If srcQueueFamilyIndex and dstQueueFamilyIndex define a queue family ownership transfer or oldLayout and newLayout define an image layout transition, and oldLayout or newLayout is VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL then image must have been created with VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT

  • VUID-VkImageMemoryBarrier2-oldLayout-01211
    If srcQueueFamilyIndex and dstQueueFamilyIndex define a queue family ownership transfer or oldLayout and newLayout define an image layout transition, and oldLayout or newLayout is VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL then image must have been created with VK_IMAGE_USAGE_SAMPLED_BIT or VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT

  • VUID-VkImageMemoryBarrier2-oldLayout-01212
    If srcQueueFamilyIndex and dstQueueFamilyIndex define a queue family ownership transfer or oldLayout and newLayout define an image layout transition, and oldLayout or newLayout is VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL then image must have been created with VK_IMAGE_USAGE_TRANSFER_SRC_BIT

  • VUID-VkImageMemoryBarrier2-oldLayout-01213
    If srcQueueFamilyIndex and dstQueueFamilyIndex define a queue family ownership transfer or oldLayout and newLayout define an image layout transition, and oldLayout or newLayout is VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL then image must have been created with VK_IMAGE_USAGE_TRANSFER_DST_BIT

  • VUID-VkImageMemoryBarrier2-oldLayout-01197
    If srcQueueFamilyIndex and dstQueueFamilyIndex define a queue family ownership transfer or oldLayout and newLayout define an image layout transition, oldLayout must be VK_IMAGE_LAYOUT_UNDEFINED or the current layout of the image subresources affected by the barrier

  • VUID-VkImageMemoryBarrier2-newLayout-01198
    If srcQueueFamilyIndex and dstQueueFamilyIndex define a queue family ownership transfer or oldLayout and newLayout define an image layout transition, newLayout must not be VK_IMAGE_LAYOUT_UNDEFINED or VK_IMAGE_LAYOUT_PREINITIALIZED

  • VUID-VkImageMemoryBarrier2-oldLayout-01658
    If srcQueueFamilyIndex and dstQueueFamilyIndex define a queue family ownership transfer or oldLayout and newLayout define an image layout transition, and oldLayout or newLayout is VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL then image must have been created with VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT

  • VUID-VkImageMemoryBarrier2-oldLayout-01659
    If srcQueueFamilyIndex and dstQueueFamilyIndex define a queue family ownership transfer or oldLayout and newLayout define an image layout transition, and oldLayout or newLayout is VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL then image must have been created with VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT

  • VUID-VkImageMemoryBarrier2-srcQueueFamilyIndex-04065
    If srcQueueFamilyIndex and dstQueueFamilyIndex define a queue family ownership transfer or oldLayout and newLayout define an image layout transition, and oldLayout or newLayout is VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL then image must have been created with at least one of VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT, VK_IMAGE_USAGE_SAMPLED_BIT, or VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT

  • VUID-VkImageMemoryBarrier2-srcQueueFamilyIndex-04066
    If srcQueueFamilyIndex and dstQueueFamilyIndex define a queue family ownership transfer or oldLayout and newLayout define an image layout transition, and oldLayout or newLayout is VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL then image must have been created with VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT set

  • VUID-VkImageMemoryBarrier2-srcQueueFamilyIndex-04067
    If srcQueueFamilyIndex and dstQueueFamilyIndex define a queue family ownership transfer or oldLayout and newLayout define an image layout transition, and oldLayout or newLayout is VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL then image must have been created with at least one of VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT, VK_IMAGE_USAGE_SAMPLED_BIT, or VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT

  • VUID-VkImageMemoryBarrier2-srcQueueFamilyIndex-04068
    If srcQueueFamilyIndex and dstQueueFamilyIndex define a queue family ownership transfer or oldLayout and newLayout define an image layout transition, and oldLayout or newLayout is VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL then image must have been created with VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT set

  • VUID-VkImageMemoryBarrier2-synchronization2-07793
    If the synchronization2 feature is not enabled, oldLayout must not be VK_IMAGE_LAYOUT_ATTACHMENT_OPTIMAL_KHR or VK_IMAGE_LAYOUT_READ_ONLY_OPTIMAL_KHR

  • VUID-VkImageMemoryBarrier2-synchronization2-07794
    If the synchronization2 feature is not enabled, newLayout must not be VK_IMAGE_LAYOUT_ATTACHMENT_OPTIMAL_KHR or VK_IMAGE_LAYOUT_READ_ONLY_OPTIMAL_KHR

  • VUID-VkImageMemoryBarrier2-srcQueueFamilyIndex-03938
    If srcQueueFamilyIndex and dstQueueFamilyIndex define a queue family ownership transfer or oldLayout and newLayout define an image layout transition, and oldLayout or newLayout is VK_IMAGE_LAYOUT_ATTACHMENT_OPTIMAL, image must have been created with VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT or VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT

  • VUID-VkImageMemoryBarrier2-srcQueueFamilyIndex-03939
    If srcQueueFamilyIndex and dstQueueFamilyIndex define a queue family ownership transfer or oldLayout and newLayout define an image layout transition, and oldLayout or newLayout is VK_IMAGE_LAYOUT_READ_ONLY_OPTIMAL, image must have been created with at least one of VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT, VK_IMAGE_USAGE_SAMPLED_BIT, or VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT

  • VUID-VkImageMemoryBarrier2-oldLayout-02088
    If srcQueueFamilyIndex and dstQueueFamilyIndex define a queue family ownership transfer or oldLayout and newLayout define an image layout transition, and oldLayout or newLayout is VK_IMAGE_LAYOUT_FRAGMENT_SHADING_RATE_ATTACHMENT_OPTIMAL_KHR then image must have been created with VK_IMAGE_USAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR set

  • VUID-VkImageMemoryBarrier2-image-09117
    If image was created with a sharing mode of VK_SHARING_MODE_EXCLUSIVE, and srcQueueFamilyIndex and dstQueueFamilyIndex are not equal, srcQueueFamilyIndex must be VK_QUEUE_FAMILY_EXTERNAL, VK_QUEUE_FAMILY_FOREIGN_EXT, or a valid queue family

  • VUID-VkImageMemoryBarrier2-image-09118
    If image was created with a sharing mode of VK_SHARING_MODE_EXCLUSIVE, and srcQueueFamilyIndex and dstQueueFamilyIndex are not equal, dstQueueFamilyIndex must be VK_QUEUE_FAMILY_EXTERNAL, VK_QUEUE_FAMILY_FOREIGN_EXT, or a valid queue family

  • VUID-VkImageMemoryBarrier2-srcQueueFamilyIndex-04070
    If srcQueueFamilyIndex is not equal to dstQueueFamilyIndex, at least one of srcQueueFamilyIndex or dstQueueFamilyIndex must not be VK_QUEUE_FAMILY_EXTERNAL or VK_QUEUE_FAMILY_FOREIGN_EXT

  • VUID-VkImageMemoryBarrier2-None-09119
    If the VK_KHR_external_memory extension is not enabled, and the value of VkApplicationInfo::apiVersion used to create the VkInstance is not greater than or equal to Version 1.1, srcQueueFamilyIndex must not be VK_QUEUE_FAMILY_EXTERNAL

  • VUID-VkImageMemoryBarrier2-None-09120
    If the VK_KHR_external_memory extension is not enabled, and the value of VkApplicationInfo::apiVersion used to create the VkInstance is not greater than or equal to Version 1.1, dstQueueFamilyIndex must not be VK_QUEUE_FAMILY_EXTERNAL

  • VUID-VkImageMemoryBarrier2-srcQueueFamilyIndex-09121
    If the VK_EXT_queue_family_foreign extension is not enabled srcQueueFamilyIndex must not be VK_QUEUE_FAMILY_FOREIGN_EXT

  • VUID-VkImageMemoryBarrier2-dstQueueFamilyIndex-09122
    If the VK_EXT_queue_family_foreign extension is not enabled dstQueueFamilyIndex must not be VK_QUEUE_FAMILY_FOREIGN_EXT

  • VUID-VkImageMemoryBarrier2-srcQueueFamilyIndex-07120
    If srcQueueFamilyIndex and dstQueueFamilyIndex define a queue family ownership transfer or oldLayout and newLayout define an image layout transition, and oldLayout or newLayout is VK_IMAGE_LAYOUT_VIDEO_DECODE_SRC_KHR then image must have been created with VK_IMAGE_USAGE_VIDEO_DECODE_SRC_BIT_KHR

  • VUID-VkImageMemoryBarrier2-srcQueueFamilyIndex-07121
    If srcQueueFamilyIndex and dstQueueFamilyIndex define a queue family ownership transfer or oldLayout and newLayout define an image layout transition, and oldLayout or newLayout is VK_IMAGE_LAYOUT_VIDEO_DECODE_DST_KHR then image must have been created with VK_IMAGE_USAGE_VIDEO_DECODE_DST_BIT_KHR

  • VUID-VkImageMemoryBarrier2-srcQueueFamilyIndex-07122
    If srcQueueFamilyIndex and dstQueueFamilyIndex define a queue family ownership transfer or oldLayout and newLayout define an image layout transition, and oldLayout or newLayout is VK_IMAGE_LAYOUT_VIDEO_DECODE_DPB_KHR then image must have been created with VK_IMAGE_USAGE_VIDEO_DECODE_DPB_BIT_KHR

  • VUID-VkImageMemoryBarrier2-srcQueueFamilyIndex-07123
    If srcQueueFamilyIndex and dstQueueFamilyIndex define a queue family ownership transfer or oldLayout and newLayout define an image layout transition, and oldLayout or newLayout is VK_IMAGE_LAYOUT_VIDEO_ENCODE_SRC_KHR then image must have been created with VK_IMAGE_USAGE_VIDEO_ENCODE_SRC_BIT_KHR

  • VUID-VkImageMemoryBarrier2-srcQueueFamilyIndex-07124
    If srcQueueFamilyIndex and dstQueueFamilyIndex define a queue family ownership transfer or oldLayout and newLayout define an image layout transition, and oldLayout or newLayout is VK_IMAGE_LAYOUT_VIDEO_ENCODE_DST_KHR then image must have been created with VK_IMAGE_USAGE_VIDEO_ENCODE_DST_BIT_KHR

  • VUID-VkImageMemoryBarrier2-srcQueueFamilyIndex-07125
    If srcQueueFamilyIndex and dstQueueFamilyIndex define a queue family ownership transfer or oldLayout and newLayout define an image layout transition, and oldLayout or newLayout is VK_IMAGE_LAYOUT_VIDEO_ENCODE_DPB_KHR then image must have been created with VK_IMAGE_USAGE_VIDEO_ENCODE_DPB_BIT_KHR

  • VUID-VkImageMemoryBarrier2-srcQueueFamilyIndex-07006
    If srcQueueFamilyIndex and dstQueueFamilyIndex define a queue family ownership transfer or oldLayout and newLayout define an image layout transition, and oldLayout or newLayout is VK_IMAGE_LAYOUT_ATTACHMENT_FEEDBACK_LOOP_OPTIMAL_EXT then image must have been created with either the VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT or VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT usage bits, and the VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT or VK_IMAGE_USAGE_SAMPLED_BIT usage bits, and the VK_IMAGE_USAGE_ATTACHMENT_FEEDBACK_LOOP_BIT_EXT usage bit

  • VUID-VkImageMemoryBarrier2-attachmentFeedbackLoopLayout-07313
    If the attachmentFeedbackLoopLayout feature is not enabled, newLayout must not be VK_IMAGE_LAYOUT_ATTACHMENT_FEEDBACK_LOOP_OPTIMAL_EXT

  • VUID-VkImageMemoryBarrier2-srcQueueFamilyIndex-09550
    If srcQueueFamilyIndex and dstQueueFamilyIndex define a queue family ownership transfer or oldLayout and newLayout define an image layout transition, and oldLayout or newLayout is VK_IMAGE_LAYOUT_RENDERING_LOCAL_READ_KHR then image must have been created with either VK_IMAGE_USAGE_STORAGE_BIT, or with both VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT and either of VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT or VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT

  • VUID-VkImageMemoryBarrier2-dynamicRenderingLocalRead-09551
    If the dynamicRenderingLocalRead feature is not enabled, oldLayout must not be VK_IMAGE_LAYOUT_RENDERING_LOCAL_READ_KHR

  • VUID-VkImageMemoryBarrier2-dynamicRenderingLocalRead-09552
    If the dynamicRenderingLocalRead feature is not enabled, newLayout must not be VK_IMAGE_LAYOUT_RENDERING_LOCAL_READ_KHR

  • VUID-VkImageMemoryBarrier2-subresourceRange-01486
    subresourceRange.baseMipLevel must be less than the mipLevels specified in VkImageCreateInfo when image was created

  • VUID-VkImageMemoryBarrier2-subresourceRange-01724
    If subresourceRange.levelCount is not VK_REMAINING_MIP_LEVELS, subresourceRange.baseMipLevel + subresourceRange.levelCount must be less than or equal to the mipLevels specified in VkImageCreateInfo when image was created

  • VUID-VkImageMemoryBarrier2-subresourceRange-01488
    subresourceRange.baseArrayLayer must be less than the arrayLayers specified in VkImageCreateInfo when image was created

  • VUID-VkImageMemoryBarrier2-subresourceRange-01725
    If subresourceRange.layerCount is not VK_REMAINING_ARRAY_LAYERS, subresourceRange.baseArrayLayer + subresourceRange.layerCount must be less than or equal to the arrayLayers specified in VkImageCreateInfo when image was created

  • VUID-VkImageMemoryBarrier2-image-01932
    If image is non-sparse then it must be bound completely and contiguously to a single VkDeviceMemory object

  • VUID-VkImageMemoryBarrier2-image-09241
    If image has a color format that is single-plane, then the aspectMask member of subresourceRange must be VK_IMAGE_ASPECT_COLOR_BIT

  • VUID-VkImageMemoryBarrier2-image-09242
    If image has a color format and is not disjoint, then the aspectMask member of subresourceRange must be VK_IMAGE_ASPECT_COLOR_BIT

  • VUID-VkImageMemoryBarrier2-image-01672
    If image has a multi-planar format and the image is disjoint, then the aspectMask member of subresourceRange must include at least one multi-planar aspect mask bit or VK_IMAGE_ASPECT_COLOR_BIT

  • VUID-VkImageMemoryBarrier2-image-03320
    If image has a depth/stencil format with both depth and stencil and the separateDepthStencilLayouts feature is not enabled, then the aspectMask member of subresourceRange must include both VK_IMAGE_ASPECT_DEPTH_BIT and VK_IMAGE_ASPECT_STENCIL_BIT

  • VUID-VkImageMemoryBarrier2-image-03319
    If image has a depth/stencil format with both depth and stencil and the separateDepthStencilLayouts feature is enabled, then the aspectMask member of subresourceRange must include either or both VK_IMAGE_ASPECT_DEPTH_BIT and VK_IMAGE_ASPECT_STENCIL_BIT

  • VUID-VkImageMemoryBarrier2-aspectMask-08702
    If the aspectMask member of subresourceRange includes VK_IMAGE_ASPECT_DEPTH_BIT, oldLayout and newLayout must not be one of VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL or VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL

  • VUID-VkImageMemoryBarrier2-aspectMask-08703
    If the aspectMask member of subresourceRange includes VK_IMAGE_ASPECT_STENCIL_BIT, oldLayout and newLayout must not be one of VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL or VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL

  • VUID-VkImageMemoryBarrier2-subresourceRange-09601
    subresourceRange.aspectMask must be valid for the format the image was created with

  • VUID-VkImageMemoryBarrier2-srcStageMask-03854
    If either srcStageMask or dstStageMask includes VK_PIPELINE_STAGE_2_HOST_BIT, srcQueueFamilyIndex and dstQueueFamilyIndex must be equal

  • VUID-VkImageMemoryBarrier2-srcStageMask-03855
    If srcStageMask includes VK_PIPELINE_STAGE_2_HOST_BIT, and srcQueueFamilyIndex and dstQueueFamilyIndex define a queue family ownership transfer or oldLayout and newLayout define an image layout transition, oldLayout must be one of VK_IMAGE_LAYOUT_PREINITIALIZED, VK_IMAGE_LAYOUT_UNDEFINED, or VK_IMAGE_LAYOUT_GENERAL

Valid Usage (Implicit)

  • VUID-VkImageMemoryBarrier2-sType-sType
    sType must be VK_STRUCTURE_TYPE_IMAGE_MEMORY_BARRIER_2

  • VUID-VkImageMemoryBarrier2-pNext-pNext
    Each pNext member of any structure (including this one) in the pNext chain must be either NULL or a pointer to a valid instance of VkExternalMemoryAcquireUnmodifiedEXT or VkSampleLocationsInfoEXT

  • VUID-VkImageMemoryBarrier2-sType-unique
    The sType value of each struct in the pNext chain must be unique

  • VUID-VkImageMemoryBarrier2-srcStageMask-parameter
    srcStageMask must be a valid combination of VkPipelineStageFlagBits2 values

  • VUID-VkImageMemoryBarrier2-srcAccessMask-parameter
    srcAccessMask must be a valid combination of VkAccessFlagBits2 values

  • VUID-VkImageMemoryBarrier2-dstStageMask-parameter
    dstStageMask must be a valid combination of VkPipelineStageFlagBits2 values

  • VUID-VkImageMemoryBarrier2-dstAccessMask-parameter
    dstAccessMask must be a valid combination of VkAccessFlagBits2 values

  • VUID-VkImageMemoryBarrier2-oldLayout-parameter
    oldLayout must be a valid VkImageLayout value

  • VUID-VkImageMemoryBarrier2-newLayout-parameter
    newLayout must be a valid VkImageLayout value

  • VUID-VkImageMemoryBarrier2-image-parameter
    image must be a valid VkImage handle

  • VUID-VkImageMemoryBarrier2-subresourceRange-parameter
    subresourceRange must be a valid VkImageSubresourceRange structure

The VkImageMemoryBarrier structure is defined as:

// Provided by VK_VERSION_1_0
typedef struct VkImageMemoryBarrier {
    VkStructureType            sType;
    const void*                pNext;
    VkAccessFlags              srcAccessMask;
    VkAccessFlags              dstAccessMask;
    VkImageLayout              oldLayout;
    VkImageLayout              newLayout;
    uint32_t                   srcQueueFamilyIndex;
    uint32_t                   dstQueueFamilyIndex;
    VkImage                    image;
    VkImageSubresourceRange    subresourceRange;
} VkImageMemoryBarrier;

The first access scope is limited to access to memory through the specified image subresource range, via access types in the source access mask specified by srcAccessMask. If srcAccessMask includes VK_ACCESS_HOST_WRITE_BIT, memory writes performed by that access type are also made visible, as that access type is not performed through a resource.

The second access scope is limited to access to memory through the specified image subresource range, via access types in the destination access mask specified by dstAccessMask. If dstAccessMask includes VK_ACCESS_HOST_WRITE_BIT or VK_ACCESS_HOST_READ_BIT, available memory writes are also made visible to accesses of those types, as those access types are not performed through a resource.

If srcQueueFamilyIndex is not equal to dstQueueFamilyIndex, and srcQueueFamilyIndex is equal to the current queue family, then the memory barrier defines a queue family release operation for the specified image subresource range, and the second synchronization scope of the calling command does not apply to this operation.

If dstQueueFamilyIndex is not equal to srcQueueFamilyIndex, and dstQueueFamilyIndex is equal to the current queue family, then the memory barrier defines a queue family acquire operation for the specified image subresource range, and the first synchronization scope of the calling command does not apply to this operation.

If the synchronization2 feature is not enabled or oldLayout is not equal to newLayout, oldLayout and newLayout define an image layout transition for the specified image subresource range.

Note

If the synchronization2 feature is enabled, when the old and new layout are equal, the layout values are ignored - data is preserved no matter what values are specified, or what layout the image is currently in.

If image has a multi-planar format and the image is disjoint, then including VK_IMAGE_ASPECT_COLOR_BIT in the aspectMask member of subresourceRange is equivalent to including VK_IMAGE_ASPECT_PLANE_0_BIT, VK_IMAGE_ASPECT_PLANE_1_BIT, and (for three-plane formats only) VK_IMAGE_ASPECT_PLANE_2_BIT.

Valid Usage

  • VUID-VkImageMemoryBarrier-oldLayout-01208
    If srcQueueFamilyIndex and dstQueueFamilyIndex define a queue family ownership transfer or oldLayout and newLayout define an image layout transition, and oldLayout or newLayout is VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL then image must have been created with VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT

  • VUID-VkImageMemoryBarrier-oldLayout-01209
    If srcQueueFamilyIndex and dstQueueFamilyIndex define a queue family ownership transfer or oldLayout and newLayout define an image layout transition, and oldLayout or newLayout is VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL then image must have been created with VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT

  • VUID-VkImageMemoryBarrier-oldLayout-01210
    If srcQueueFamilyIndex and dstQueueFamilyIndex define a queue family ownership transfer or oldLayout and newLayout define an image layout transition, and oldLayout or newLayout is VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL then image must have been created with VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT

  • VUID-VkImageMemoryBarrier-oldLayout-01211
    If srcQueueFamilyIndex and dstQueueFamilyIndex define a queue family ownership transfer or oldLayout and newLayout define an image layout transition, and oldLayout or newLayout is VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL then image must have been created with VK_IMAGE_USAGE_SAMPLED_BIT or VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT

  • VUID-VkImageMemoryBarrier-oldLayout-01212
    If srcQueueFamilyIndex and dstQueueFamilyIndex define a queue family ownership transfer or oldLayout and newLayout define an image layout transition, and oldLayout or newLayout is VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL then image must have been created with VK_IMAGE_USAGE_TRANSFER_SRC_BIT

  • VUID-VkImageMemoryBarrier-oldLayout-01213
    If srcQueueFamilyIndex and dstQueueFamilyIndex define a queue family ownership transfer or oldLayout and newLayout define an image layout transition, and oldLayout or newLayout is VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL then image must have been created with VK_IMAGE_USAGE_TRANSFER_DST_BIT

  • VUID-VkImageMemoryBarrier-oldLayout-01197
    If srcQueueFamilyIndex and dstQueueFamilyIndex define a queue family ownership transfer or oldLayout and newLayout define an image layout transition, oldLayout must be VK_IMAGE_LAYOUT_UNDEFINED or the current layout of the image subresources affected by the barrier

  • VUID-VkImageMemoryBarrier-newLayout-01198
    If srcQueueFamilyIndex and dstQueueFamilyIndex define a queue family ownership transfer or oldLayout and newLayout define an image layout transition, newLayout must not be VK_IMAGE_LAYOUT_UNDEFINED or VK_IMAGE_LAYOUT_PREINITIALIZED

  • VUID-VkImageMemoryBarrier-oldLayout-01658
    If srcQueueFamilyIndex and dstQueueFamilyIndex define a queue family ownership transfer or oldLayout and newLayout define an image layout transition, and oldLayout or newLayout is VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL then image must have been created with VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT

  • VUID-VkImageMemoryBarrier-oldLayout-01659
    If srcQueueFamilyIndex and dstQueueFamilyIndex define a queue family ownership transfer or oldLayout and newLayout define an image layout transition, and oldLayout or newLayout is VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL then image must have been created with VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT

  • VUID-VkImageMemoryBarrier-srcQueueFamilyIndex-04065
    If srcQueueFamilyIndex and dstQueueFamilyIndex define a queue family ownership transfer or oldLayout and newLayout define an image layout transition, and oldLayout or newLayout is VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL then image must have been created with at least one of VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT, VK_IMAGE_USAGE_SAMPLED_BIT, or VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT

  • VUID-VkImageMemoryBarrier-srcQueueFamilyIndex-04066
    If srcQueueFamilyIndex and dstQueueFamilyIndex define a queue family ownership transfer or oldLayout and newLayout define an image layout transition, and oldLayout or newLayout is VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL then image must have been created with VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT set

  • VUID-VkImageMemoryBarrier-srcQueueFamilyIndex-04067
    If srcQueueFamilyIndex and dstQueueFamilyIndex define a queue family ownership transfer or oldLayout and newLayout define an image layout transition, and oldLayout or newLayout is VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL then image must have been created with at least one of VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT, VK_IMAGE_USAGE_SAMPLED_BIT, or VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT

  • VUID-VkImageMemoryBarrier-srcQueueFamilyIndex-04068
    If srcQueueFamilyIndex and dstQueueFamilyIndex define a queue family ownership transfer or oldLayout and newLayout define an image layout transition, and oldLayout or newLayout is VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL then image must have been created with VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT set

  • VUID-VkImageMemoryBarrier-synchronization2-07793
    If the synchronization2 feature is not enabled, oldLayout must not be VK_IMAGE_LAYOUT_ATTACHMENT_OPTIMAL_KHR or VK_IMAGE_LAYOUT_READ_ONLY_OPTIMAL_KHR

  • VUID-VkImageMemoryBarrier-synchronization2-07794
    If the synchronization2 feature is not enabled, newLayout must not be VK_IMAGE_LAYOUT_ATTACHMENT_OPTIMAL_KHR or VK_IMAGE_LAYOUT_READ_ONLY_OPTIMAL_KHR

  • VUID-VkImageMemoryBarrier-srcQueueFamilyIndex-03938
    If srcQueueFamilyIndex and dstQueueFamilyIndex define a queue family ownership transfer or oldLayout and newLayout define an image layout transition, and oldLayout or newLayout is VK_IMAGE_LAYOUT_ATTACHMENT_OPTIMAL, image must have been created with VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT or VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT

  • VUID-VkImageMemoryBarrier-srcQueueFamilyIndex-03939
    If srcQueueFamilyIndex and dstQueueFamilyIndex define a queue family ownership transfer or oldLayout and newLayout define an image layout transition, and oldLayout or newLayout is VK_IMAGE_LAYOUT_READ_ONLY_OPTIMAL, image must have been created with at least one of VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT, VK_IMAGE_USAGE_SAMPLED_BIT, or VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT

  • VUID-VkImageMemoryBarrier-oldLayout-02088
    If srcQueueFamilyIndex and dstQueueFamilyIndex define a queue family ownership transfer or oldLayout and newLayout define an image layout transition, and oldLayout or newLayout is VK_IMAGE_LAYOUT_FRAGMENT_SHADING_RATE_ATTACHMENT_OPTIMAL_KHR then image must have been created with VK_IMAGE_USAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR set

  • VUID-VkImageMemoryBarrier-image-09117
    If image was created with a sharing mode of VK_SHARING_MODE_EXCLUSIVE, and srcQueueFamilyIndex and dstQueueFamilyIndex are not equal, srcQueueFamilyIndex must be VK_QUEUE_FAMILY_EXTERNAL, VK_QUEUE_FAMILY_FOREIGN_EXT, or a valid queue family

  • VUID-VkImageMemoryBarrier-image-09118
    If image was created with a sharing mode of VK_SHARING_MODE_EXCLUSIVE, and srcQueueFamilyIndex and dstQueueFamilyIndex are not equal, dstQueueFamilyIndex must be VK_QUEUE_FAMILY_EXTERNAL, VK_QUEUE_FAMILY_FOREIGN_EXT, or a valid queue family

  • VUID-VkImageMemoryBarrier-srcQueueFamilyIndex-04070
    If srcQueueFamilyIndex is not equal to dstQueueFamilyIndex, at least one of srcQueueFamilyIndex or dstQueueFamilyIndex must not be VK_QUEUE_FAMILY_EXTERNAL or VK_QUEUE_FAMILY_FOREIGN_EXT

  • VUID-VkImageMemoryBarrier-None-09119
    If the VK_KHR_external_memory extension is not enabled, and the value of VkApplicationInfo::apiVersion used to create the VkInstance is not greater than or equal to Version 1.1, srcQueueFamilyIndex must not be VK_QUEUE_FAMILY_EXTERNAL

  • VUID-VkImageMemoryBarrier-None-09120
    If the VK_KHR_external_memory extension is not enabled, and the value of VkApplicationInfo::apiVersion used to create the VkInstance is not greater than or equal to Version 1.1, dstQueueFamilyIndex must not be VK_QUEUE_FAMILY_EXTERNAL

  • VUID-VkImageMemoryBarrier-srcQueueFamilyIndex-09121
    If the VK_EXT_queue_family_foreign extension is not enabled srcQueueFamilyIndex must not be VK_QUEUE_FAMILY_FOREIGN_EXT

  • VUID-VkImageMemoryBarrier-dstQueueFamilyIndex-09122
    If the VK_EXT_queue_family_foreign extension is not enabled dstQueueFamilyIndex must not be VK_QUEUE_FAMILY_FOREIGN_EXT

  • VUID-VkImageMemoryBarrier-srcQueueFamilyIndex-07120
    If srcQueueFamilyIndex and dstQueueFamilyIndex define a queue family ownership transfer or oldLayout and newLayout define an image layout transition, and oldLayout or newLayout is VK_IMAGE_LAYOUT_VIDEO_DECODE_SRC_KHR then image must have been created with VK_IMAGE_USAGE_VIDEO_DECODE_SRC_BIT_KHR

  • VUID-VkImageMemoryBarrier-srcQueueFamilyIndex-07121
    If srcQueueFamilyIndex and dstQueueFamilyIndex define a queue family ownership transfer or oldLayout and newLayout define an image layout transition, and oldLayout or newLayout is VK_IMAGE_LAYOUT_VIDEO_DECODE_DST_KHR then image must have been created with VK_IMAGE_USAGE_VIDEO_DECODE_DST_BIT_KHR

  • VUID-VkImageMemoryBarrier-srcQueueFamilyIndex-07122
    If srcQueueFamilyIndex and dstQueueFamilyIndex define a queue family ownership transfer or oldLayout and newLayout define an image layout transition, and oldLayout or newLayout is VK_IMAGE_LAYOUT_VIDEO_DECODE_DPB_KHR then image must have been created with VK_IMAGE_USAGE_VIDEO_DECODE_DPB_BIT_KHR

  • VUID-VkImageMemoryBarrier-srcQueueFamilyIndex-07123
    If srcQueueFamilyIndex and dstQueueFamilyIndex define a queue family ownership transfer or oldLayout and newLayout define an image layout transition, and oldLayout or newLayout is VK_IMAGE_LAYOUT_VIDEO_ENCODE_SRC_KHR then image must have been created with VK_IMAGE_USAGE_VIDEO_ENCODE_SRC_BIT_KHR

  • VUID-VkImageMemoryBarrier-srcQueueFamilyIndex-07124
    If srcQueueFamilyIndex and dstQueueFamilyIndex define a queue family ownership transfer or oldLayout and newLayout define an image layout transition, and oldLayout or newLayout is VK_IMAGE_LAYOUT_VIDEO_ENCODE_DST_KHR then image must have been created with VK_IMAGE_USAGE_VIDEO_ENCODE_DST_BIT_KHR

  • VUID-VkImageMemoryBarrier-srcQueueFamilyIndex-07125
    If srcQueueFamilyIndex and dstQueueFamilyIndex define a queue family ownership transfer or oldLayout and newLayout define an image layout transition, and oldLayout or newLayout is VK_IMAGE_LAYOUT_VIDEO_ENCODE_DPB_KHR then image must have been created with VK_IMAGE_USAGE_VIDEO_ENCODE_DPB_BIT_KHR

  • VUID-VkImageMemoryBarrier-srcQueueFamilyIndex-07006
    If srcQueueFamilyIndex and dstQueueFamilyIndex define a queue family ownership transfer or oldLayout and newLayout define an image layout transition, and oldLayout or newLayout is VK_IMAGE_LAYOUT_ATTACHMENT_FEEDBACK_LOOP_OPTIMAL_EXT then image must have been created with either the VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT or VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT usage bits, and the VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT or VK_IMAGE_USAGE_SAMPLED_BIT usage bits, and the VK_IMAGE_USAGE_ATTACHMENT_FEEDBACK_LOOP_BIT_EXT usage bit

  • VUID-VkImageMemoryBarrier-attachmentFeedbackLoopLayout-07313
    If the attachmentFeedbackLoopLayout feature is not enabled, newLayout must not be VK_IMAGE_LAYOUT_ATTACHMENT_FEEDBACK_LOOP_OPTIMAL_EXT

  • VUID-VkImageMemoryBarrier-srcQueueFamilyIndex-09550
    If srcQueueFamilyIndex and dstQueueFamilyIndex define a queue family ownership transfer or oldLayout and newLayout define an image layout transition, and oldLayout or newLayout is VK_IMAGE_LAYOUT_RENDERING_LOCAL_READ_KHR then image must have been created with either VK_IMAGE_USAGE_STORAGE_BIT, or with both VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT and either of VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT or VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT

  • VUID-VkImageMemoryBarrier-dynamicRenderingLocalRead-09551
    If the dynamicRenderingLocalRead feature is not enabled, oldLayout must not be VK_IMAGE_LAYOUT_RENDERING_LOCAL_READ_KHR

  • VUID-VkImageMemoryBarrier-dynamicRenderingLocalRead-09552
    If the dynamicRenderingLocalRead feature is not enabled, newLayout must not be VK_IMAGE_LAYOUT_RENDERING_LOCAL_READ_KHR

  • VUID-VkImageMemoryBarrier-subresourceRange-01486
    subresourceRange.baseMipLevel must be less than the mipLevels specified in VkImageCreateInfo when image was created

  • VUID-VkImageMemoryBarrier-subresourceRange-01724
    If subresourceRange.levelCount is not VK_REMAINING_MIP_LEVELS, subresourceRange.baseMipLevel + subresourceRange.levelCount must be less than or equal to the mipLevels specified in VkImageCreateInfo when image was created

  • VUID-VkImageMemoryBarrier-subresourceRange-01488
    subresourceRange.baseArrayLayer must be less than the arrayLayers specified in VkImageCreateInfo when image was created

  • VUID-VkImageMemoryBarrier-subresourceRange-01725
    If subresourceRange.layerCount is not VK_REMAINING_ARRAY_LAYERS, subresourceRange.baseArrayLayer + subresourceRange.layerCount must be less than or equal to the arrayLayers specified in VkImageCreateInfo when image was created

  • VUID-VkImageMemoryBarrier-image-01932
    If image is non-sparse then it must be bound completely and contiguously to a single VkDeviceMemory object

  • VUID-VkImageMemoryBarrier-image-09241
    If image has a color format that is single-plane, then the aspectMask member of subresourceRange must be VK_IMAGE_ASPECT_COLOR_BIT

  • VUID-VkImageMemoryBarrier-image-09242
    If image has a color format and is not disjoint, then the aspectMask member of subresourceRange must be VK_IMAGE_ASPECT_COLOR_BIT

  • VUID-VkImageMemoryBarrier-image-01672
    If image has a multi-planar format and the image is disjoint, then the aspectMask member of subresourceRange must include at least one multi-planar aspect mask bit or VK_IMAGE_ASPECT_COLOR_BIT

  • VUID-VkImageMemoryBarrier-image-03320
    If image has a depth/stencil format with both depth and stencil and the separateDepthStencilLayouts feature is not enabled, then the aspectMask member of subresourceRange must include both VK_IMAGE_ASPECT_DEPTH_BIT and VK_IMAGE_ASPECT_STENCIL_BIT

  • VUID-VkImageMemoryBarrier-image-03319
    If image has a depth/stencil format with both depth and stencil and the separateDepthStencilLayouts feature is enabled, then the aspectMask member of subresourceRange must include either or both VK_IMAGE_ASPECT_DEPTH_BIT and VK_IMAGE_ASPECT_STENCIL_BIT

  • VUID-VkImageMemoryBarrier-aspectMask-08702
    If the aspectMask member of subresourceRange includes VK_IMAGE_ASPECT_DEPTH_BIT, oldLayout and newLayout must not be one of VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL or VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL

  • VUID-VkImageMemoryBarrier-aspectMask-08703
    If the aspectMask member of subresourceRange includes VK_IMAGE_ASPECT_STENCIL_BIT, oldLayout and newLayout must not be one of VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL or VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL

  • VUID-VkImageMemoryBarrier-subresourceRange-09601
    subresourceRange.aspectMask must be valid for the format the image was created with

  • VUID-VkImageMemoryBarrier-None-09052
    If the synchronization2 feature is not enabled, and image was created with a sharing mode of VK_SHARING_MODE_CONCURRENT, at least one of srcQueueFamilyIndex and dstQueueFamilyIndex must be VK_QUEUE_FAMILY_IGNORED

  • VUID-VkImageMemoryBarrier-None-09053
    If the synchronization2 feature is not enabled, and image was created with a sharing mode of VK_SHARING_MODE_CONCURRENT, srcQueueFamilyIndex must be VK_QUEUE_FAMILY_IGNORED or VK_QUEUE_FAMILY_EXTERNAL

  • VUID-VkImageMemoryBarrier-None-09054
    If the synchronization2 feature is not enabled, and image was created with a sharing mode of VK_SHARING_MODE_CONCURRENT, dstQueueFamilyIndex must be VK_QUEUE_FAMILY_IGNORED or VK_QUEUE_FAMILY_EXTERNAL

Valid Usage (Implicit)

  • VUID-VkImageMemoryBarrier-sType-sType
    sType must be VK_STRUCTURE_TYPE_IMAGE_MEMORY_BARRIER

  • VUID-VkImageMemoryBarrier-pNext-pNext
    Each pNext member of any structure (including this one) in the pNext chain must be either NULL or a pointer to a valid instance of VkExternalMemoryAcquireUnmodifiedEXT or VkSampleLocationsInfoEXT

  • VUID-VkImageMemoryBarrier-sType-unique
    The sType value of each struct in the pNext chain must be unique

  • VUID-VkImageMemoryBarrier-oldLayout-parameter
    oldLayout must be a valid VkImageLayout value

  • VUID-VkImageMemoryBarrier-newLayout-parameter
    newLayout must be a valid VkImageLayout value

  • VUID-VkImageMemoryBarrier-image-parameter
    image must be a valid VkImage handle

  • VUID-VkImageMemoryBarrier-subresourceRange-parameter
    subresourceRange must be a valid VkImageSubresourceRange structure

To facilitate usage of images whose memory is initialized on the host, Vulkan allows image layout transitions to be performed by the host as well, albeit supporting limited layouts.

To perform an image layout transition on the host, call:

// Provided by VK_EXT_host_image_copy
VkResult vkTransitionImageLayoutEXT(
    VkDevice                                    device,
    uint32_t                                    transitionCount,
    const VkHostImageLayoutTransitionInfoEXT*   pTransitions);

  • device is the device which owns pTransitions[i].image.

  • transitionCount is the number of image layout transitions to perform.

  • pTransitions is a pointer to an array of VkHostImageLayoutTransitionInfoEXT structures specifying the image and subresource ranges within them to transition.

Valid Usage (Implicit)

  • VUID-vkTransitionImageLayoutEXT-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkTransitionImageLayoutEXT-pTransitions-parameter
    pTransitions must be a valid pointer to an array of transitionCount valid VkHostImageLayoutTransitionInfoEXT structures

  • VUID-vkTransitionImageLayoutEXT-transitionCount-arraylength
    transitionCount must be greater than 0

Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_INITIALIZATION_FAILED

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

  • VK_ERROR_MEMORY_MAP_FAILED

The VkHostImageLayoutTransitionInfoEXT structure is defined as:

// Provided by VK_EXT_host_image_copy
typedef struct VkHostImageLayoutTransitionInfoEXT {
    VkStructureType            sType;
    const void*                pNext;
    VkImage                    image;
    VkImageLayout              oldLayout;
    VkImageLayout              newLayout;
    VkImageSubresourceRange    subresourceRange;
} VkHostImageLayoutTransitionInfoEXT;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • image is a handle to the image affected by this layout transition.

  • oldLayout is the old layout in an image layout transition.

  • newLayout is the new layout in an image layout transition.

  • subresourceRange describes the image subresource range within image that is affected by this layout transition.

vkTransitionImageLayoutEXT does not check whether the device memory associated with an image is currently in use before performing the layout transition. The application must guarantee that any previously submitted command that reads from or writes to this subresource has completed before the host performs the layout transition. The memory of image is accessed by the host as if coherent.

Note

Image layout transitions performed on the host do not require queue family ownership transfers as the physical layout of the image will not vary between queue families for the layouts supported by this function.
Note

If the device has written to the image memory, it is not automatically made available to the host. Before this command can be called, a memory barrier for this image must have been issued on the device with the second synchronization scope including VK_PIPELINE_STAGE_HOST_BIT and VK_ACCESS_HOST_READ_BIT.

Because queue submissions automatically make host memory visible to the device, there would not be a need for a memory barrier before using the results of this layout transition on the device.
Valid Usage

  • VUID-VkHostImageLayoutTransitionInfoEXT-image-09055
    image must have been created with VK_IMAGE_USAGE_HOST_TRANSFER_BIT_EXT

  • VUID-VkHostImageLayoutTransitionInfoEXT-subresourceRange-01486
    subresourceRange.baseMipLevel must be less than the mipLevels specified in VkImageCreateInfo when image was created

  • VUID-VkHostImageLayoutTransitionInfoEXT-subresourceRange-01724
    If subresourceRange.levelCount is not VK_REMAINING_MIP_LEVELS, subresourceRange.baseMipLevel + subresourceRange.levelCount must be less than or equal to the mipLevels specified in VkImageCreateInfo when image was created

  • VUID-VkHostImageLayoutTransitionInfoEXT-subresourceRange-01488
    subresourceRange.baseArrayLayer must be less than the arrayLayers specified in VkImageCreateInfo when image was created

  • VUID-VkHostImageLayoutTransitionInfoEXT-subresourceRange-01725
    If subresourceRange.layerCount is not VK_REMAINING_ARRAY_LAYERS, subresourceRange.baseArrayLayer + subresourceRange.layerCount must be less than or equal to the arrayLayers specified in VkImageCreateInfo when image was created

  • VUID-VkHostImageLayoutTransitionInfoEXT-image-01932
    If image is non-sparse then it must be bound completely and contiguously to a single VkDeviceMemory object

  • VUID-VkHostImageLayoutTransitionInfoEXT-image-09241
    If image has a color format that is single-plane, then the aspectMask member of subresourceRange must be VK_IMAGE_ASPECT_COLOR_BIT

  • VUID-VkHostImageLayoutTransitionInfoEXT-image-09242
    If image has a color format and is not disjoint, then the aspectMask member of subresourceRange must be VK_IMAGE_ASPECT_COLOR_BIT

  • VUID-VkHostImageLayoutTransitionInfoEXT-image-01672
    If image has a multi-planar format and the image is disjoint, then the aspectMask member of subresourceRange must include at least one multi-planar aspect mask bit or VK_IMAGE_ASPECT_COLOR_BIT

  • VUID-VkHostImageLayoutTransitionInfoEXT-image-03320
    If image has a depth/stencil format with both depth and stencil and the separateDepthStencilLayouts feature is not enabled, then the aspectMask member of subresourceRange must include both VK_IMAGE_ASPECT_DEPTH_BIT and VK_IMAGE_ASPECT_STENCIL_BIT

  • VUID-VkHostImageLayoutTransitionInfoEXT-image-03319
    If image has a depth/stencil format with both depth and stencil and the separateDepthStencilLayouts feature is enabled, then the aspectMask member of subresourceRange must include either or both VK_IMAGE_ASPECT_DEPTH_BIT and VK_IMAGE_ASPECT_STENCIL_BIT

  • VUID-VkHostImageLayoutTransitionInfoEXT-aspectMask-08702
    If the aspectMask member of subresourceRange includes VK_IMAGE_ASPECT_DEPTH_BIT, oldLayout and newLayout must not be one of VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL or VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL

  • VUID-VkHostImageLayoutTransitionInfoEXT-aspectMask-08703
    If the aspectMask member of subresourceRange includes VK_IMAGE_ASPECT_STENCIL_BIT, oldLayout and newLayout must not be one of VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL or VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL

  • VUID-VkHostImageLayoutTransitionInfoEXT-subresourceRange-09601
    subresourceRange.aspectMask must be valid for the format the image was created with

  • VUID-VkHostImageLayoutTransitionInfoEXT-oldLayout-09229
    oldLayout must be either VK_IMAGE_LAYOUT_UNDEFINED or the current layout of the image subresources as specified in subresourceRange

  • VUID-VkHostImageLayoutTransitionInfoEXT-oldLayout-09230
    If oldLayout is not VK_IMAGE_LAYOUT_UNDEFINED or VK_IMAGE_LAYOUT_PREINITIALIZED, it must be one of the layouts in VkPhysicalDeviceHostImageCopyPropertiesEXT::pCopySrcLayouts

  • VUID-VkHostImageLayoutTransitionInfoEXT-newLayout-09057
    newLayout must be one of the layouts in VkPhysicalDeviceHostImageCopyPropertiesEXT::pCopyDstLayouts

Valid Usage (Implicit)

  • VUID-VkHostImageLayoutTransitionInfoEXT-sType-sType
    sType must be VK_STRUCTURE_TYPE_HOST_IMAGE_LAYOUT_TRANSITION_INFO_EXT

  • VUID-VkHostImageLayoutTransitionInfoEXT-pNext-pNext
    pNext must be NULL

  • VUID-VkHostImageLayoutTransitionInfoEXT-image-parameter
    image must be a valid VkImage handle

  • VUID-VkHostImageLayoutTransitionInfoEXT-oldLayout-parameter
    oldLayout must be a valid VkImageLayout value

  • VUID-VkHostImageLayoutTransitionInfoEXT-newLayout-parameter
    newLayout must be a valid VkImageLayout value

  • VUID-VkHostImageLayoutTransitionInfoEXT-subresourceRange-parameter
    subresourceRange must be a valid VkImageSubresourceRange structure

7.7.4. Queue Family Ownership Transfer

Resources created with a VkSharingMode of VK_SHARING_MODE_EXCLUSIVE must have their ownership explicitly transferred from one queue family to another in order to access their content in a well-defined manner on a queue in a different queue family.

The special queue family index VK_QUEUE_FAMILY_IGNORED indicates that a queue family parameter or member is ignored.

#define VK_QUEUE_FAMILY_IGNORED           (~0U)

Resources shared with external APIs or instances using external memory must also explicitly manage ownership transfers between local and external queues (or equivalent constructs in external APIs) regardless of the VkSharingMode specified when creating them.

The special queue family index VK_QUEUE_FAMILY_EXTERNAL represents any queue external to the resource’s current Vulkan instance, as long as the queue uses the same underlying device group or physical device, and the same driver version as the resource’s VkDevice, as indicated by VkPhysicalDeviceIDProperties::deviceUUID and VkPhysicalDeviceIDProperties::driverUUID.

#define VK_QUEUE_FAMILY_EXTERNAL          (~1U)

or the equivalent

#define VK_QUEUE_FAMILY_EXTERNAL_KHR      VK_QUEUE_FAMILY_EXTERNAL

The special queue family index VK_QUEUE_FAMILY_FOREIGN_EXT represents any queue external to the resource’s current Vulkan instance, regardless of the queue’s underlying physical device or driver version. This includes, for example, queues for fixed-function image processing devices, media codec devices, and display devices, as well as all queues that use the same underlying device group or physical device, and the same driver version as the resource’s VkDevice.

#define VK_QUEUE_FAMILY_FOREIGN_EXT       (~2U)

If memory dependencies are correctly expressed between uses of such a resource between two queues in different families, but no ownership transfer is defined, the contents of that resource are undefined for any read accesses performed by the second queue family.

Note

If an application does not need the contents of a resource to remain valid when transferring from one queue family to another, then the ownership transfer should be skipped.
Note

Applications should expect transfers to/from VK_QUEUE_FAMILY_FOREIGN_EXT to be more expensive than transfers to/from VK_QUEUE_FAMILY_EXTERNAL_KHR.

A queue family ownership transfer consists of two distinct parts:

  1. Release exclusive ownership from the source queue family

  2. Acquire exclusive ownership for the destination queue family

An application must ensure that these operations occur in the correct order by defining an execution dependency between them, e.g. using a semaphore.

A release operation is used to release exclusive ownership of a range of a buffer or image subresource range. A release operation is defined by executing a buffer memory barrier (for a buffer range) or an image memory barrier (for an image subresource range) using a pipeline barrier command, on a queue from the source queue family. The srcQueueFamilyIndex parameter of the barrier must be set to the source queue family index, and the dstQueueFamilyIndex parameter to the destination queue family index. dstAccessMask is ignored for such a barrier, such that no visibility operation is executed - the value of this mask does not affect the validity of the barrier. The release operation happens-after the availability operation. dstStageMask is also ignored for such a barrier as defined by buffer memory ownership transfer and image memory ownership transfer.

An acquire operation is used to acquire exclusive ownership of a range of a buffer or image subresource range. An acquire operation is defined by executing a buffer memory barrier (for a buffer range) or an image memory barrier (for an image subresource range) using a pipeline barrier command, on a queue from the destination queue family. The buffer range or image subresource range specified in an acquire operation must match exactly that of a previous release operation. The srcQueueFamilyIndex parameter of the barrier must be set to the source queue family index, and the dstQueueFamilyIndex parameter to the destination queue family index. srcAccessMask is ignored for such a barrier, such that no availability operation is executed - the value of this mask does not affect the validity of the barrier. The acquire operation happens-before the visibility operation. srcStageMask is also ignored for such a barrier as defined by buffer memory ownership transfer and image memory ownership transfer. As the first synchronization scope for an acquire operation is empty there is no happens-before dependency. Such a dependency can be introduced by using VK_PIPELINE_STAGE_ALL_COMMANDS_BIT.

Note

Whilst it is not invalid to provide destination or source access masks for memory barriers used for release or acquire operations, respectively, they have no practical effect. Access after a release operation has undefined results, and so visibility for those accesses has no practical effect. Similarly, write access before an acquire operation will produce undefined results for future access, so availability of those writes has no practical use. In an earlier version of the specification, these were required to match on both sides - but this was subsequently relaxed. These masks should be set to 0.
Note

Since a release and acquire operation does not synchronize with second and first scopes respectively, the VK_PIPELINE_STAGE_ALL_COMMANDS_BIT stage must be used to wait for a release operation to complete. Typically, a release and acquire pair is performed by a VkSemaphore signal and wait in their respective queues. Signaling a semaphore with vkQueueSubmit waits for VK_PIPELINE_STAGE_ALL_COMMANDS_BIT. With vkQueueSubmit2, stageMask for the signal semaphore must be VK_PIPELINE_STAGE_ALL_COMMANDS_BIT. Similarly, for the acquire operation, waiting for a semaphore must use VK_PIPELINE_STAGE_ALL_COMMANDS_BIT to make sure the acquire operation is synchronized.

If the transfer is via an image memory barrier, and an image layout transition is desired, then the values of oldLayout and newLayout in the release operation's memory barrier must be equal to values of oldLayout and newLayout in the acquire operation's memory barrier. Although the image layout transition is submitted twice, it will only be executed once. A layout transition specified in this way happens-after the release operation and happens-before the acquire operation.

If the values of srcQueueFamilyIndex and dstQueueFamilyIndex are equal, no ownership transfer is performed, and the barrier operates as if they were both set to VK_QUEUE_FAMILY_IGNORED.

Queue family ownership transfers may perform read and write accesses on all memory bound to the image subresource or buffer range, so applications must ensure that all memory writes have been made available before a queue family ownership transfer is executed. Available memory is automatically made visible to queue family release and acquire operations, and writes performed by those operations are automatically made available.

Once a queue family has acquired ownership of a buffer range or image subresource range of a VK_SHARING_MODE_EXCLUSIVE resource, its contents are undefined to other queue families unless ownership is transferred. The contents of any portion of another resource which aliases memory that is bound to the transferred buffer or image subresource range are undefined after a release or acquire operation.

Note

Because events cannot be used directly for inter-queue synchronization, and because vkCmdSetEvent does not have the queue family index or memory barrier parameters needed by a release operation, the release and acquire operations of a queue family ownership transfer can only be performed using vkCmdPipelineBarrier.

An acquire operation may have a performance penalty when acquiring ownership of a subresource range from one of the special queue families reserved for external memory ownership transfers described above. The application can reduce the performance penalty in some cases by adding a VkExternalMemoryAcquireUnmodifiedEXT structure to the pNext chain of the acquire operation's memory barrier structure.

The VkExternalMemoryAcquireUnmodifiedEXT structure is defined as:

// Provided by VK_EXT_external_memory_acquire_unmodified
typedef struct VkExternalMemoryAcquireUnmodifiedEXT {
    VkStructureType    sType;
    const void*        pNext;
    VkBool32           acquireUnmodifiedMemory;
} VkExternalMemoryAcquireUnmodifiedEXT;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • acquireUnmodifiedMemory specifies, if VK_TRUE, that no range of VkDeviceMemory bound to the resource of the memory barrier’s subresource range was modified at any time since the resource’s most recent release of ownership to the queue family specified by the memory barrier’s srcQueueFamilyIndex. If VK_FALSE, it specifies nothing.

If the application releases ownership of the subresource range to one of the special queue families reserved for external memory ownership transfers with a memory barrier structure, and later re-acquires ownership from the same queue family with a memory barrier structure, and if no range of VkDeviceMemory bound to the resource was modified at any time between the release operation and the acquire operation, then the application should add a VkExternalMemoryAcquireUnmodifiedEXT structure to the pNext chain of the acquire operation's memory barrier structure because this may reduce the performance penalty.

This struct is ignored if acquireUnmodifiedMemory is VK_FALSE. In particular, VK_FALSE does not specify that memory was modified.

This struct is ignored if the memory barrier’s srcQueueFamilyIndex is not a special queue family reserved for external memory ownership transfers.

Note

The method by which the application determines whether memory was modified between the release operation and acquire operation is outside the scope of Vulkan.

For any Vulkan operation that accesses a resource, the application must not assume the implementation accesses the resource’s memory as read-only, even for apparently read-only operations such as transfer commands and shader reads.

The validity of VkExternalMemoryAcquireUnmodifiedEXT::acquireUnmodifiedMemory is independent of memory ranges outside the ranges of VkDeviceMemory bound to the resource. In particular, it is independent of any implementation-private memory associated with the resource.
Valid Usage

  • VUID-VkExternalMemoryAcquireUnmodifiedEXT-acquireUnmodifiedMemory-08922
    If acquireUnmodifiedMemory is VK_TRUE, and the memory barrier’s srcQueueFamilyIndex is a special queue family reserved for external memory ownership transfers (as described in Queue Family Ownership Transfer), then each range of VkDeviceMemory bound to the resource must have remained unmodified during all time since the resource’s most recent release of ownership to the queue family

Valid Usage (Implicit)

  • VUID-VkExternalMemoryAcquireUnmodifiedEXT-sType-sType
    sType must be VK_STRUCTURE_TYPE_EXTERNAL_MEMORY_ACQUIRE_UNMODIFIED_EXT

7.8. Wait Idle Operations

To wait on the host for the completion of outstanding queue operations for a given queue, call:

// Provided by VK_VERSION_1_0
VkResult vkQueueWaitIdle(
    VkQueue                                     queue);

  • queue is the queue on which to wait.

vkQueueWaitIdle is equivalent to having submitted a valid fence to every previously executed queue submission command that accepts a fence, then waiting for all of those fences to signal using vkWaitForFences with an infinite timeout and waitAll set to VK_TRUE.

Valid Usage (Implicit)

  • VUID-vkQueueWaitIdle-queue-parameter
    queue must be a valid VkQueue handle

Host Synchronization

  • Host access to queue must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Video Coding Scope Supported Queue Types Command Type

-

-

-

Any

-
Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

  • VK_ERROR_DEVICE_LOST

To wait on the host for the completion of outstanding queue operations for all queues on a given logical device, call:

// Provided by VK_VERSION_1_0
VkResult vkDeviceWaitIdle(
    VkDevice                                    device);

  • device is the logical device to idle.

vkDeviceWaitIdle is equivalent to calling vkQueueWaitIdle for all queues owned by device.

Valid Usage (Implicit)

  • VUID-vkDeviceWaitIdle-device-parameter
    device must be a valid VkDevice handle

Host Synchronization

  • Host access to all VkQueue objects created from device must be externally synchronized

Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

  • VK_ERROR_DEVICE_LOST

7.9. Host Write Ordering Guarantees

When batches of command buffers are submitted to a queue via a queue submission command, it defines a memory dependency with prior host operations, and execution of command buffers submitted to the queue.

The first synchronization scope includes execution of vkQueueSubmit on the host and anything that happened-before it, as defined by the host memory model.

Note

Some systems allow writes that do not directly integrate with the host memory model; these have to be synchronized by the application manually. One example of this is non-temporal store instructions on x86; to ensure these happen-before submission, applications should call _mm_sfence().

The second synchronization scope includes all commands submitted in the same queue submission, and all commands that occur later in submission order.

The first access scope includes all host writes to mappable device memory that are available to the host memory domain.

The second access scope includes all memory access performed by the device.

7.10. Synchronization and Multiple Physical Devices

If a logical device includes more than one physical device, then fences, semaphores, and events all still have a single instance of the signaled state.

A fence becomes signaled when all physical devices complete the necessary queue operations.

Semaphore wait and signal operations all include a device index that is the sole physical device that performs the operation. These indices are provided in the VkDeviceGroupSubmitInfo and VkDeviceGroupBindSparseInfo structures. Semaphores are not exclusively owned by any physical device. For example, a semaphore can be signaled by one physical device and then waited on by a different physical device.

An event can only be waited on by the same physical device that signaled it (or the host).

7.11. Calibrated Timestamps

In order to be able to correlate the time a particular operation took place at on timelines of different time domains (e.g. a device operation vs. a host operation), Vulkan allows querying calibrated timestamps from multiple time domains.

To query calibrated timestamps from a set of time domains, call:

// Provided by VK_KHR_calibrated_timestamps
VkResult vkGetCalibratedTimestampsKHR(
    VkDevice                                    device,
    uint32_t                                    timestampCount,
    const VkCalibratedTimestampInfoKHR*         pTimestampInfos,
    uint64_t*                                   pTimestamps,
    uint64_t*                                   pMaxDeviation);

or the equivalent command

// Provided by VK_EXT_calibrated_timestamps
VkResult vkGetCalibratedTimestampsEXT(
    VkDevice                                    device,
    uint32_t                                    timestampCount,
    const VkCalibratedTimestampInfoKHR*         pTimestampInfos,
    uint64_t*                                   pTimestamps,
    uint64_t*                                   pMaxDeviation);

  • device is the logical device used to perform the query.

  • timestampCount is the number of timestamps to query.

  • pTimestampInfos is a pointer to an array of timestampCount VkCalibratedTimestampInfoKHR structures, describing the time domains the calibrated timestamps should be captured from.

  • pTimestamps is a pointer to an array of timestampCount 64-bit unsigned integer values in which the requested calibrated timestamp values are returned.

  • pMaxDeviation is a pointer to a 64-bit unsigned integer value in which the strictly positive maximum deviation, in nanoseconds, of the calibrated timestamp values is returned.

Note

The maximum deviation may vary between calls to vkGetCalibratedTimestampsKHR even for the same set of time domains due to implementation and platform specific reasons. It is the application’s responsibility to assess whether the returned maximum deviation makes the timestamp values suitable for any particular purpose and can choose to re-issue the timestamp calibration call pursuing a lower deviation value.

Calibrated timestamp values can be extrapolated to estimate future coinciding timestamp values, however, depending on the nature of the time domains and other properties of the platform extrapolating values over a sufficiently long period of time may no longer be accurate enough to fit any particular purpose, so applications are expected to re-calibrate the timestamps on a regular basis.

Valid Usage

  • VUID-vkGetCalibratedTimestampsEXT-timeDomain-09246
    The timeDomain value of each VkCalibratedTimestampInfoKHR in pTimestampInfos must be unique

Valid Usage (Implicit)

  • VUID-vkGetCalibratedTimestampsKHR-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkGetCalibratedTimestampsKHR-pTimestampInfos-parameter
    pTimestampInfos must be a valid pointer to an array of timestampCount valid VkCalibratedTimestampInfoKHR structures

  • VUID-vkGetCalibratedTimestampsKHR-pTimestamps-parameter
    pTimestamps must be a valid pointer to an array of timestampCount uint64_t values

  • VUID-vkGetCalibratedTimestampsKHR-pMaxDeviation-parameter
    pMaxDeviation must be a valid pointer to a uint64_t value

  • VUID-vkGetCalibratedTimestampsKHR-timestampCount-arraylength
    timestampCount must be greater than 0

Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

The VkCalibratedTimestampInfoKHR structure is defined as:

// Provided by VK_KHR_calibrated_timestamps
typedef struct VkCalibratedTimestampInfoKHR {
    VkStructureType    sType;
    const void*        pNext;
    VkTimeDomainKHR    timeDomain;
} VkCalibratedTimestampInfoKHR;

or the equivalent

// Provided by VK_EXT_calibrated_timestamps
typedef VkCalibratedTimestampInfoKHR VkCalibratedTimestampInfoEXT;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • timeDomain is a VkTimeDomainKHR value specifying the time domain from which the calibrated timestamp value should be returned.

Valid Usage
Valid Usage (Implicit)

  • VUID-VkCalibratedTimestampInfoKHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_CALIBRATED_TIMESTAMP_INFO_KHR

  • VUID-VkCalibratedTimestampInfoKHR-pNext-pNext
    pNext must be NULL

  • VUID-VkCalibratedTimestampInfoKHR-timeDomain-parameter
    timeDomain must be a valid VkTimeDomainKHR value

The set of supported time domains consists of:

// Provided by VK_KHR_calibrated_timestamps
typedef enum VkTimeDomainKHR {
    VK_TIME_DOMAIN_DEVICE_KHR = 0,
    VK_TIME_DOMAIN_CLOCK_MONOTONIC_KHR = 1,
    VK_TIME_DOMAIN_CLOCK_MONOTONIC_RAW_KHR = 2,
    VK_TIME_DOMAIN_QUERY_PERFORMANCE_COUNTER_KHR = 3,
  // Provided by VK_EXT_calibrated_timestamps
    VK_TIME_DOMAIN_DEVICE_EXT = VK_TIME_DOMAIN_DEVICE_KHR,
  // Provided by VK_EXT_calibrated_timestamps
    VK_TIME_DOMAIN_CLOCK_MONOTONIC_EXT = VK_TIME_DOMAIN_CLOCK_MONOTONIC_KHR,
  // Provided by VK_EXT_calibrated_timestamps
    VK_TIME_DOMAIN_CLOCK_MONOTONIC_RAW_EXT = VK_TIME_DOMAIN_CLOCK_MONOTONIC_RAW_KHR,
  // Provided by VK_EXT_calibrated_timestamps
    VK_TIME_DOMAIN_QUERY_PERFORMANCE_COUNTER_EXT = VK_TIME_DOMAIN_QUERY_PERFORMANCE_COUNTER_KHR,
} VkTimeDomainKHR;

or the equivalent

// Provided by VK_EXT_calibrated_timestamps
typedef VkTimeDomainKHR VkTimeDomainEXT;

  • VK_TIME_DOMAIN_DEVICE_KHR specifies the device time domain. Timestamp values in this time domain use the same units and are comparable with device timestamp values captured using vkCmdWriteTimestamp or vkCmdWriteTimestamp2 and are defined to be incrementing according to the timestampPeriod of the device.

  • VK_TIME_DOMAIN_CLOCK_MONOTONIC_KHR specifies the CLOCK_MONOTONIC time domain available on POSIX platforms. Timestamp values in this time domain are in units of nanoseconds and are comparable with platform timestamp values captured using the POSIX clock_gettime API as computed by this example:

Note

An implementation supporting VK_KHR_calibrated_timestamps or VK_EXT_calibrated_timestamps will use the same time domain for all its VkQueue so that timestamp values reported for VK_TIME_DOMAIN_DEVICE_KHR can be matched to any timestamp captured through vkCmdWriteTimestamp or vkCmdWriteTimestamp2 .

 
struct timespec tv;
clock_gettime(CLOCK_MONOTONIC, &tv);
return tv.tv_nsec + tv.tv_sec*1000000000ull;

  • VK_TIME_DOMAIN_CLOCK_MONOTONIC_RAW_KHR specifies the CLOCK_MONOTONIC_RAW time domain available on POSIX platforms. Timestamp values in this time domain are in units of nanoseconds and are comparable with platform timestamp values captured using the POSIX clock_gettime API as computed by this example:

struct timespec tv;
clock_gettime(CLOCK_MONOTONIC_RAW, &tv);
return tv.tv_nsec + tv.tv_sec*1000000000ull;

  • VK_TIME_DOMAIN_QUERY_PERFORMANCE_COUNTER_KHR specifies the performance counter (QPC) time domain available on Windows. Timestamp values in this time domain are in the same units as those provided by the Windows QueryPerformanceCounter API and are comparable with platform timestamp values captured using that API as computed by this example:

LARGE_INTEGER counter;
QueryPerformanceCounter(&counter);
return counter.QuadPart;

8. Render Pass

Draw commands must be recorded within a render pass instance. Each render pass instance defines a set of image resources, referred to as attachments, used during rendering.

To begin a render pass instance, call:

// Provided by VK_VERSION_1_3
void vkCmdBeginRendering(
    VkCommandBuffer                             commandBuffer,
    const VkRenderingInfo*                      pRenderingInfo);

or the equivalent command

// Provided by VK_KHR_dynamic_rendering
void vkCmdBeginRenderingKHR(
    VkCommandBuffer                             commandBuffer,
    const VkRenderingInfo*                      pRenderingInfo);

  • commandBuffer is the command buffer in which to record the command.

  • pRenderingInfo is a pointer to a VkRenderingInfo structure specifying details of the render pass instance to begin.

After beginning a render pass instance, the command buffer is ready to record draw commands.

If pRenderingInfo->flags includes VK_RENDERING_RESUMING_BIT then this render pass is resumed from a render pass instance that has been suspended earlier in submission order.

Valid Usage

  • VUID-vkCmdBeginRendering-dynamicRendering-06446
    The dynamicRendering feature must be enabled

  • VUID-vkCmdBeginRendering-commandBuffer-06068
    If commandBuffer is a secondary command buffer, and the nestedCommandBuffer feature is not enabled, pRenderingInfo->flags must not include VK_RENDERING_CONTENTS_SECONDARY_COMMAND_BUFFERS_BIT

  • VUID-vkCmdBeginRendering-pRenderingInfo-09588
    If pRenderingInfo->pDepthAttachment is not NULL and pRenderingInfo->pDepthAttachment->imageView is not VK_NULL_HANDLE, pRenderingInfo->pDepthAttachment->imageView must be in the layout specified by pRenderingInfo->pDepthAttachment->imageLayout

  • VUID-vkCmdBeginRendering-pRenderingInfo-09589
    If pRenderingInfo->pDepthAttachment is not NULL, pRenderingInfo->pDepthAttachment->imageView is not VK_NULL_HANDLE, pRenderingInfo->pDepthAttachment->imageResolveMode is not VK_RESOLVE_MODE_NONE, and pRenderingInfo->pDepthAttachment->resolveImageView is not VK_NULL_HANDLE, pRenderingInfo->pDepthAttachment->resolveImageView must be in the layout specified by pRenderingInfo->pDepthAttachment->resolveImageLayout

  • VUID-vkCmdBeginRendering-pRenderingInfo-09590
    If pRenderingInfo->pStencilAttachment is not NULL and pRenderingInfo->pStencilAttachment->imageView is not VK_NULL_HANDLE, pRenderingInfo->pStencilAttachment->imageView must be in the layout specified by pRenderingInfo->pStencilAttachment->imageLayout

  • VUID-vkCmdBeginRendering-pRenderingInfo-09591
    If pRenderingInfo->pStencilAttachment is not NULL, pRenderingInfo->pStencilAttachment->imageView is not VK_NULL_HANDLE, pRenderingInfo->pStencilAttachment->imageResolveMode is not VK_RESOLVE_MODE_NONE, and pRenderingInfo->pStencilAttachment->resolveImageView is not VK_NULL_HANDLE, pRenderingInfo->pStencilAttachment->resolveImageView must be in the layout specified by pRenderingInfo->pStencilAttachment->resolveImageLayout

  • VUID-vkCmdBeginRendering-pRenderingInfo-09592
    For any element of pRenderingInfo->pColorAttachments, if imageView is not VK_NULL_HANDLE, that image view must be in the layout specified by imageLayout

  • VUID-vkCmdBeginRendering-pRenderingInfo-09593
    For any element of pRenderingInfo->pColorAttachments, if either imageResolveMode is VK_RESOLVE_MODE_EXTERNAL_FORMAT_DOWNSAMPLE_ANDROID, or imageView is not VK_NULL_HANDLE and resolveMode is not VK_RESOLVE_MODE_NONE, and resolveImageView is not VK_NULL_HANDLE, resolveImageView must be in the layout specified by resolveImageLayout

Valid Usage (Implicit)

  • VUID-vkCmdBeginRendering-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdBeginRendering-pRenderingInfo-parameter
    pRenderingInfo must be a valid pointer to a valid VkRenderingInfo structure

  • VUID-vkCmdBeginRendering-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdBeginRendering-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support graphics operations

  • VUID-vkCmdBeginRendering-renderpass
    This command must only be called outside of a render pass instance

  • VUID-vkCmdBeginRendering-videocoding
    This command must only be called outside of a video coding scope

Host Synchronization

  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Video Coding Scope Supported Queue Types Command Type

Primary
Secondary

Outside

Outside

Graphics

Action
State

The VkRenderingInfo structure is defined as:

// Provided by VK_VERSION_1_3
typedef struct VkRenderingInfo {
    VkStructureType                     sType;
    const void*                         pNext;
    VkRenderingFlags                    flags;
    VkRect2D                            renderArea;
    uint32_t                            layerCount;
    uint32_t                            viewMask;
    uint32_t                            colorAttachmentCount;
    const VkRenderingAttachmentInfo*    pColorAttachments;
    const VkRenderingAttachmentInfo*    pDepthAttachment;
    const VkRenderingAttachmentInfo*    pStencilAttachment;
} VkRenderingInfo;

or the equivalent

// Provided by VK_KHR_dynamic_rendering, VK_QCOM_tile_properties with VK_KHR_dynamic_rendering or VK_VERSION_1_3
typedef VkRenderingInfo VkRenderingInfoKHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • flags is a bitmask of VkRenderingFlagBits.

  • renderArea is the render area that is affected by the render pass instance.

  • layerCount is the number of layers rendered to in each attachment when viewMask is 0.

  • viewMask is the view mask indicating the indices of attachment layers that will be rendered when it is not 0.

  • colorAttachmentCount is the number of elements in pColorAttachments.

  • pColorAttachments is a pointer to an array of colorAttachmentCount VkRenderingAttachmentInfo structures describing any color attachments used.

  • pDepthAttachment is a pointer to a VkRenderingAttachmentInfo structure describing a depth attachment.

  • pStencilAttachment is a pointer to a VkRenderingAttachmentInfo structure describing a stencil attachment.

If viewMask is not 0, multiview is enabled.

If there is an instance of VkDeviceGroupRenderPassBeginInfo included in the pNext chain and its deviceRenderAreaCount member is not 0, then renderArea is ignored, and the render area is defined per-device by that structure.

If multiview is enabled, and the multiviewPerViewRenderAreas feature is enabled, and there is an instance of VkMultiviewPerViewRenderAreasRenderPassBeginInfoQCOM included in the pNext chain with perViewRenderAreaCount not equal to 0, then the elements of VkMultiviewPerViewRenderAreasRenderPassBeginInfoQCOM::pPerViewRenderAreas override renderArea and define a render area for each view. In this case, renderArea must be set to an area at least as large as the union of all the per-view render areas.

Each element of the pColorAttachments array corresponds to an output location in the shader, i.e. if the shader declares an output variable decorated with a Location value of X, then it uses the attachment provided in pColorAttachments[X]. If the imageView member of any element of pColorAttachments is VK_NULL_HANDLE, and resolveMode is not VK_RESOLVE_MODE_EXTERNAL_FORMAT_DOWNSAMPLE_ANDROID, writes to the corresponding location by a fragment are discarded.

Valid Usage

  • VUID-VkRenderingInfo-viewMask-06069
    If viewMask is 0, layerCount must not be 0

  • VUID-VkRenderingInfo-multisampledRenderToSingleSampled-06857
    imageView members of pDepthAttachment, pStencilAttachment, and elements of pColorAttachments that are not VK_NULL_HANDLE must have been created with the same sampleCount , if none of the following are enabled:

  • VUID-VkRenderingInfo-imageView-09429
    imageView members of elements of pColorAttachments that are not VK_NULL_HANDLE must have been created with the same sampleCount , if the multisampledRenderToSingleSampled feature is not enabled

  • VUID-VkRenderingInfo-None-08994
    If VkDeviceGroupRenderPassBeginInfo::deviceRenderAreaCount is 0, renderArea.extent.width must be greater than 0

  • VUID-VkRenderingInfo-None-08995
    If VkDeviceGroupRenderPassBeginInfo::deviceRenderAreaCount is 0, renderArea.extent.height must be greater than 0

  • VUID-VkRenderingInfo-imageView-06858
    If multisampled-render-to-single-sampled is enabled, then all attachments referenced by imageView members of pDepthAttachment, pStencilAttachment, and elements of pColorAttachments that are not VK_NULL_HANDLE must have a sample count that is either VK_SAMPLE_COUNT_1_BIT or equal to VkMultisampledRenderToSingleSampledInfoEXT::rasterizationSamples

  • VUID-VkRenderingInfo-imageView-06859
    If multisampled-render-to-single-sampled is enabled, then all attachments referenced by imageView members of pDepthAttachment, pStencilAttachment, and elements of pColorAttachments that are not VK_NULL_HANDLE and have a sample count of VK_SAMPLE_COUNT_1_BIT must have been created with VK_IMAGE_CREATE_MULTISAMPLED_RENDER_TO_SINGLE_SAMPLED_BIT_EXT in their VkImageCreateInfo::flags

  • VUID-VkRenderingInfo-pNext-06077
    If the pNext chain does not contain VkDeviceGroupRenderPassBeginInfo or its deviceRenderAreaCount member is equal to 0, renderArea.offset.x must be greater than or equal to 0

  • VUID-VkRenderingInfo-pNext-06078
    If the pNext chain does not contain VkDeviceGroupRenderPassBeginInfo or its deviceRenderAreaCount member is equal to 0, renderArea.offset.y must be greater than or equal to 0

  • VUID-VkRenderingInfo-pNext-07815
    If the pNext chain does not contain VkDeviceGroupRenderPassBeginInfo or its deviceRenderAreaCount member is equal to 0, the sum of renderArea.extent.width and renderArea.offset.x must be less than or equal to maxFramebufferWidth

  • VUID-VkRenderingInfo-pNext-07816
    If the pNext chain does not contain VkDeviceGroupRenderPassBeginInfo or its deviceRenderAreaCount member is equal to 0, the sum of renderArea.extent.height and renderArea.offset.y must be less than or equal to maxFramebufferHeight

  • VUID-VkRenderingInfo-pNext-06079
    If the pNext chain does not contain VkDeviceGroupRenderPassBeginInfo or its deviceRenderAreaCount member is equal to 0, the width of the imageView member of any element of pColorAttachments, pDepthAttachment, or pStencilAttachment that is not VK_NULL_HANDLE must be greater than or equal to renderArea.offset.x + renderArea.extent.width

  • VUID-VkRenderingInfo-pNext-06080
    If the pNext chain does not contain VkDeviceGroupRenderPassBeginInfo or its deviceRenderAreaCount member is equal to 0, the height of the imageView member of any element of pColorAttachments, pDepthAttachment, or pStencilAttachment that is not VK_NULL_HANDLE must be greater than or equal to renderArea.offset.y + renderArea.extent.height

  • VUID-VkRenderingInfo-pNext-06083
    If the pNext chain contains VkDeviceGroupRenderPassBeginInfo, the width of the imageView member of any element of pColorAttachments, pDepthAttachment, or pStencilAttachment that is not VK_NULL_HANDLE must be greater than or equal to the sum of the offset.x and extent.width members of each element of pDeviceRenderAreas

  • VUID-VkRenderingInfo-pNext-06084
    If the pNext chain contains VkDeviceGroupRenderPassBeginInfo, the height of the imageView member of any element of pColorAttachments, pDepthAttachment, or pStencilAttachment that is not VK_NULL_HANDLE must be greater than or equal to the sum of the offset.y and extent.height members of each element of pDeviceRenderAreas

  • VUID-VkRenderingInfo-pDepthAttachment-06085
    If neither pDepthAttachment or pStencilAttachment are NULL and the imageView member of either structure is not VK_NULL_HANDLE, the imageView member of each structure must be the same

  • VUID-VkRenderingInfo-pDepthAttachment-06086
    If neither pDepthAttachment or pStencilAttachment are NULL, and the resolveMode member of each is not VK_RESOLVE_MODE_NONE, the resolveImageView member of each structure must be the same

  • VUID-VkRenderingInfo-colorAttachmentCount-06087
    If colorAttachmentCount is not 0 and the imageView member of an element of pColorAttachments is not VK_NULL_HANDLE, that imageView must have been created with VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT

  • VUID-VkRenderingInfo-colorAttachmentCount-09476
    If colorAttachmentCount is not 0 and there is an element of pColorAttachments with either its resolveMode member set to VK_RESOLVE_MODE_EXTERNAL_FORMAT_DOWNSAMPLE_ANDROID, or its imageView member not VK_NULL_HANDLE, and its resolveMode member not set to VK_RESOLVE_MODE_NONE, the resolveImageView member of that element of pColorAttachments must have been created with VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT

  • VUID-VkRenderingInfo-pDepthAttachment-06547
    If pDepthAttachment is not NULL and pDepthAttachment->imageView is not VK_NULL_HANDLE, pDepthAttachment->imageView must have been created with a format that includes a depth component

  • VUID-VkRenderingInfo-pDepthAttachment-06088
    If pDepthAttachment is not NULL and pDepthAttachment->imageView is not VK_NULL_HANDLE, pDepthAttachment->imageView must have been created with VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT

  • VUID-VkRenderingInfo-pDepthAttachment-09477
    If pDepthAttachment is not NULL and pDepthAttachment->resolveMode is not VK_RESOLVE_MODE_NONE, pDepthAttachment->resolveImageView must have been created with VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT

  • VUID-VkRenderingInfo-pStencilAttachment-06548
    If pStencilAttachment is not NULL and pStencilAttachment->imageView is not VK_NULL_HANDLE, pStencilAttachment->imageView must have been created with a format that includes a stencil aspect

  • VUID-VkRenderingInfo-pStencilAttachment-06089
    If pStencilAttachment is not NULL and pStencilAttachment->imageView is not VK_NULL_HANDLE, pStencilAttachment->imageView must have been created with a stencil usage including VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT

  • VUID-VkRenderingInfo-pStencilAttachment-09478
    If pStencilAttachment is not NULL and pStencilAttachment->resolveMode is not VK_RESOLVE_MODE_NONE, pStencilAttachment->resolveImageView must have been created with VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT

  • VUID-VkRenderingInfo-colorAttachmentCount-06090
    If colorAttachmentCount is not 0 and the imageView member of an element of pColorAttachments is not VK_NULL_HANDLE, the layout member of that element of pColorAttachments must not be VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL or VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL

  • VUID-VkRenderingInfo-colorAttachmentCount-06091
    If colorAttachmentCount is not 0 and the imageView member of an element of pColorAttachments is not VK_NULL_HANDLE, if the resolveMode member of that element of pColorAttachments is not VK_RESOLVE_MODE_NONE, its resolveImageLayout member must not be VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL or VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL

  • VUID-VkRenderingInfo-pDepthAttachment-06092
    If pDepthAttachment is not NULL and pDepthAttachment->imageView is not VK_NULL_HANDLE, pDepthAttachment->layout must not be VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL

  • VUID-VkRenderingInfo-pDepthAttachment-06093
    If pDepthAttachment is not NULL, pDepthAttachment->imageView is not VK_NULL_HANDLE, and pDepthAttachment->resolveMode is not VK_RESOLVE_MODE_NONE, pDepthAttachment->resolveImageLayout must not be VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL

  • VUID-VkRenderingInfo-pStencilAttachment-06094
    If pStencilAttachment is not NULL and pStencilAttachment->imageView is not VK_NULL_HANDLE, pStencilAttachment->layout must not be VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL

  • VUID-VkRenderingInfo-pStencilAttachment-06095
    If pStencilAttachment is not NULL, pStencilAttachment->imageView is not VK_NULL_HANDLE, and pStencilAttachment->resolveMode is not VK_RESOLVE_MODE_NONE, pStencilAttachment->resolveImageLayout must not be VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL

  • VUID-VkRenderingInfo-colorAttachmentCount-06096
    If colorAttachmentCount is not 0 and the imageView member of an element of pColorAttachments is not VK_NULL_HANDLE, the layout member of that element of pColorAttachments must not be VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL or VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL

  • VUID-VkRenderingInfo-colorAttachmentCount-06097
    If colorAttachmentCount is not 0 and the imageView member of an element of pColorAttachments is not VK_NULL_HANDLE, if the resolveMode member of that element of pColorAttachments is not VK_RESOLVE_MODE_NONE, its resolveImageLayout member must not be VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL or VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL

  • VUID-VkRenderingInfo-pDepthAttachment-06098
    If pDepthAttachment is not NULL, pDepthAttachment->imageView is not VK_NULL_HANDLE, and pDepthAttachment->resolveMode is not VK_RESOLVE_MODE_NONE, pDepthAttachment->resolveImageLayout must not be VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL

  • VUID-VkRenderingInfo-pStencilAttachment-06099
    If pStencilAttachment is not NULL, pStencilAttachment->imageView is not VK_NULL_HANDLE, and pStencilAttachment->resolveMode is not VK_RESOLVE_MODE_NONE, pStencilAttachment->resolveImageLayout must not be VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL

  • VUID-VkRenderingInfo-colorAttachmentCount-06100
    If colorAttachmentCount is not 0 and the imageView member of an element of pColorAttachments is not VK_NULL_HANDLE, the layout member of that element of pColorAttachments must not be VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL, VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL, or VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL

  • VUID-VkRenderingInfo-colorAttachmentCount-06101
    If colorAttachmentCount is not 0 and the imageView member of an element of pColorAttachments is not VK_NULL_HANDLE, if the resolveMode member of that element of pColorAttachments is not VK_RESOLVE_MODE_NONE, its resolveImageLayout member must not be VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL, VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL, or VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL

  • VUID-VkRenderingInfo-pDepthAttachment-07732
    If pDepthAttachment is not NULL and pDepthAttachment->imageView is not VK_NULL_HANDLE, pDepthAttachment->layout must not be VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL or VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL

  • VUID-VkRenderingInfo-pDepthAttachment-07733
    If pDepthAttachment is not NULL, pDepthAttachment->imageView is not VK_NULL_HANDLE, and pDepthAttachment->resolveMode is not VK_RESOLVE_MODE_NONE, pDepthAttachment->resolveImageLayout must not be VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL or VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL

  • VUID-VkRenderingInfo-pStencilAttachment-07734
    If pStencilAttachment is not NULL and pStencilAttachment->imageView is not VK_NULL_HANDLE, pStencilAttachment->layout must not be VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL or VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL

  • VUID-VkRenderingInfo-pStencilAttachment-07735
    If pStencilAttachment is not NULL, pStencilAttachment->imageView is not VK_NULL_HANDLE, and pStencilAttachment->resolveMode is not VK_RESOLVE_MODE_NONE, pStencilAttachment->resolveImageLayout must not be VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL or VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL

  • VUID-VkRenderingInfo-pDepthAttachment-06102
    If pDepthAttachment is not NULL and pDepthAttachment->imageView is not VK_NULL_HANDLE, pDepthAttachment->resolveMode must be one of the bits set in VkPhysicalDeviceDepthStencilResolveProperties::supportedDepthResolveModes

  • VUID-VkRenderingInfo-pStencilAttachment-06103
    If pStencilAttachment is not NULL and pStencilAttachment->imageView is not VK_NULL_HANDLE, pStencilAttachment->resolveMode must be one of the bits set in VkPhysicalDeviceDepthStencilResolveProperties::supportedStencilResolveModes

  • VUID-VkRenderingInfo-pDepthAttachment-06104
    If pDepthAttachment or pStencilAttachment are both not NULL, pDepthAttachment->imageView and pStencilAttachment->imageView are both not VK_NULL_HANDLE, and VkPhysicalDeviceDepthStencilResolveProperties::independentResolveNone is VK_FALSE, the resolveMode of both structures must be the same value

  • VUID-VkRenderingInfo-pDepthAttachment-06105
    If pDepthAttachment or pStencilAttachment are both not NULL, pDepthAttachment->imageView and pStencilAttachment->imageView are both not VK_NULL_HANDLE, VkPhysicalDeviceDepthStencilResolveProperties::independentResolve is VK_FALSE, and the resolveMode of neither structure is VK_RESOLVE_MODE_NONE, the resolveMode of both structures must be the same value

  • VUID-VkRenderingInfo-colorAttachmentCount-06106
    colorAttachmentCount must be less than or equal to VkPhysicalDeviceLimits::maxColorAttachments

  • VUID-VkRenderingInfo-imageView-06107
    If the imageView member of a VkRenderingFragmentDensityMapAttachmentInfoEXT structure included in the pNext chain is not VK_NULL_HANDLE, and the fragmentDensityMapNonSubsampledImages feature is not enabled, valid imageView and resolveImageView members of pDepthAttachment, pStencilAttachment, and each element of pColorAttachments must be a VkImageView created with VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT

  • VUID-VkRenderingInfo-imageView-06108
    If the imageView member of a VkRenderingFragmentDensityMapAttachmentInfoEXT structure included in the pNext chain is not VK_NULL_HANDLE, and viewMask is not 0, imageView must have a layerCount greater than or equal to the index of the most significant bit in viewMask

  • VUID-VkRenderingInfo-imageView-06109
    If the imageView member of a VkRenderingFragmentDensityMapAttachmentInfoEXT structure included in the pNext chain is not VK_NULL_HANDLE, and viewMask is 0, imageView must have a layerCount equal to 1

  • VUID-VkRenderingInfo-pNext-06112
    If the pNext chain does not contain VkDeviceGroupRenderPassBeginInfo or its deviceRenderAreaCount member is equal to 0 and the imageView member of a VkRenderingFragmentDensityMapAttachmentInfoEXT structure included in the pNext chain is not VK_NULL_HANDLE, imageView must have a width greater than or equal to

  • VUID-VkRenderingInfo-pNext-06114
    If the pNext chain does not contain VkDeviceGroupRenderPassBeginInfo or its deviceRenderAreaCount member is equal to 0 and the imageView member of a VkRenderingFragmentDensityMapAttachmentInfoEXT structure included in the pNext chain is not VK_NULL_HANDLE, imageView must have a height greater than or equal to

  • VUID-VkRenderingInfo-pNext-06113
    If the pNext chain contains a VkDeviceGroupRenderPassBeginInfo structure, its deviceRenderAreaCount member is not 0, and the imageView member of a VkRenderingFragmentDensityMapAttachmentInfoEXT structure included in the pNext chain is not VK_NULL_HANDLE, imageView must have a width greater than or equal to for each element of pDeviceRenderAreas

  • VUID-VkRenderingInfo-pNext-06115
    If the pNext chain contains a VkDeviceGroupRenderPassBeginInfo structure, its deviceRenderAreaCount member is not 0, and the imageView member of a VkRenderingFragmentDensityMapAttachmentInfoEXT structure included in the pNext chain is not VK_NULL_HANDLE, imageView must have a height greater than or equal to for each element of pDeviceRenderAreas

  • VUID-VkRenderingInfo-imageView-06116
    If the imageView member of a VkRenderingFragmentDensityMapAttachmentInfoEXT structure included in the pNext chain is not VK_NULL_HANDLE, it must not be equal to the imageView or resolveImageView member of pDepthAttachment, pStencilAttachment, or any element of pColorAttachments

  • VUID-VkRenderingInfo-pNext-06119
    If maintenance7 is not enabled or the robustFragmentShadingRateAttachmentAccess limit is VK_FALSE or the imageView member of a VkRenderingFragmentShadingRateAttachmentInfoKHR structure was created with VkImageSubresourceRange::baseMipLevel greater than 0, the pNext chain does not contain VkDeviceGroupRenderPassBeginInfo or its deviceRenderAreaCount member is equal to 0, and the imageView member of a VkRenderingFragmentShadingRateAttachmentInfoKHR structure included in the pNext chain is not VK_NULL_HANDLE, imageView must have a width greater than or equal to

  • VUID-VkRenderingInfo-pNext-06121
    If maintenance7 is not enabled or the robustFragmentShadingRateAttachmentAccess limit is VK_FALSE or the imageView member of a VkRenderingFragmentShadingRateAttachmentInfoKHR structure was created with VkImageSubresourceRange::baseMipLevel greater than 0, the pNext chain does not contain VkDeviceGroupRenderPassBeginInfo or its deviceRenderAreaCount member is equal to 0 and the imageView member of a VkRenderingFragmentShadingRateAttachmentInfoKHR structure included in the pNext chain is not VK_NULL_HANDLE, imageView must have a height greater than or equal to

  • VUID-VkRenderingInfo-pNext-06120
    If maintenance7 is not enabled or the robustFragmentShadingRateAttachmentAccess limit is VK_FALSE or the imageView member of a VkRenderingFragmentShadingRateAttachmentInfoKHR structure was created with VkImageSubresourceRange::baseMipLevel greater than 0, the pNext chain contains a VkDeviceGroupRenderPassBeginInfo structure, its deviceRenderAreaCount member is not 0, and the imageView member of a VkRenderingFragmentShadingRateAttachmentInfoKHR structure included in the pNext chain is not VK_NULL_HANDLE, imageView must have a width greater than or equal to for each element of pDeviceRenderAreas

  • VUID-VkRenderingInfo-pNext-06122
    If maintenance7 is not enabled or the robustFragmentShadingRateAttachmentAccess limit is VK_FALSE or the imageView member of a VkRenderingFragmentShadingRateAttachmentInfoKHR structure was created with VkImageSubresourceRange::baseMipLevel greater than 0, the pNext chain contains a VkDeviceGroupRenderPassBeginInfo structure, its deviceRenderAreaCount member is not 0, and the imageView member of a VkRenderingFragmentShadingRateAttachmentInfoKHR structure included in the pNext chain is not VK_NULL_HANDLE, imageView must have a height greater than or equal to for each element of pDeviceRenderAreas

  • VUID-VkRenderingInfo-layerCount-07817
    layerCount must be less than or equal to maxFramebufferLayers

  • VUID-VkRenderingInfo-imageView-06123
    If the imageView member of a VkRenderingFragmentShadingRateAttachmentInfoKHR structure included in the pNext chain is not VK_NULL_HANDLE, and viewMask is 0, imageView must have a layerCount that is either equal to 1 or greater than or equal to layerCount

  • VUID-VkRenderingInfo-imageView-06124
    If the imageView member of a VkRenderingFragmentShadingRateAttachmentInfoKHR structure included in the pNext chain is not VK_NULL_HANDLE, and viewMask is not 0, imageView must have a layerCount that either equal to 1 or greater than or equal to the index of the most significant bit in viewMask

  • VUID-VkRenderingInfo-imageView-06125
    If the imageView member of a VkRenderingFragmentShadingRateAttachmentInfoKHR structure included in the pNext chain is not VK_NULL_HANDLE, it must not be equal to the imageView or resolveImageView member of pDepthAttachment, pStencilAttachment, or any element of pColorAttachments

  • VUID-VkRenderingInfo-imageView-06126
    If the imageView member of a VkRenderingFragmentShadingRateAttachmentInfoKHR structure included in the pNext chain is not VK_NULL_HANDLE, it must not be equal to the imageView member of a VkRenderingFragmentDensityMapAttachmentInfoEXT structure included in the pNext chain

  • VUID-VkRenderingInfo-multiview-06127
    If the multiview feature is not enabled, viewMask must be 0

  • VUID-VkRenderingInfo-viewMask-06128
    The index of the most significant bit in viewMask must be less than maxMultiviewViewCount

  • VUID-VkRenderingInfo-perViewRenderAreaCount-07857
    If the perViewRenderAreaCount member of a VkMultiviewPerViewRenderAreasRenderPassBeginInfoQCOM structure included in the pNext chain is not 0, then the multiviewPerViewRenderAreas feature must be enabled

  • VUID-VkRenderingInfo-perViewRenderAreaCount-07858
    If the perViewRenderAreaCount member of a VkMultiviewPerViewRenderAreasRenderPassBeginInfoQCOM structure included in the pNext chain is not 0, then renderArea must specify a render area that includes the union of all per view render areas

  • VUID-VkRenderingInfo-None-09044
    Valid attachments specified by this structure must not be bound to memory locations that are bound to any other valid attachments specified by this structure

  • VUID-VkRenderingInfo-flags-10012
    If flags includes VK_RENDERING_CONTENTS_INLINE_BIT_KHR then at least one of the following features must be enabled

  • VUID-VkRenderingInfo-pDepthAttachment-09318
    pDepthAttachment->resolveMode must not be VK_RESOLVE_MODE_EXTERNAL_FORMAT_DOWNSAMPLE_ANDROID

  • VUID-VkRenderingInfo-pStencilAttachment-09319
    pStencilAttachment->resolveMode must not be VK_RESOLVE_MODE_EXTERNAL_FORMAT_DOWNSAMPLE_ANDROID

  • VUID-VkRenderingInfo-colorAttachmentCount-09320
    If colorAttachmentCount is not 1, the resolveMode member of any element of pColorAttachments must not be VK_RESOLVE_MODE_EXTERNAL_FORMAT_DOWNSAMPLE_ANDROID

  • VUID-VkRenderingInfo-resolveMode-09321
    If the resolveMode of any element of pColorAttachments is VK_RESOLVE_MODE_EXTERNAL_FORMAT_DOWNSAMPLE_ANDROID, VkRenderingFragmentDensityMapAttachmentInfoEXT::imageView must be VK_NULL_HANDLE

  • VUID-VkRenderingInfo-resolveMode-09322
    If the resolveMode of any element of pColorAttachments is VK_RESOLVE_MODE_EXTERNAL_FORMAT_DOWNSAMPLE_ANDROID, VkRenderingFragmentShadingRateAttachmentInfoKHR::imageView must be VK_NULL_HANDLE

  • VUID-VkRenderingInfo-pNext-09535
    If the pNext chain contains a VkRenderPassStripeBeginInfoARM structure, the union of stripe areas defined by the elements of VkRenderPassStripeInfoARM::pStripeInfos must cover the renderArea

  • VUID-VkRenderingInfo-colorAttachmentCount-09479
    If colorAttachmentCount is not 0 and the imageView member of an element of pColorAttachments is not VK_NULL_HANDLE, that imageView must have been created with the identity swizzle

  • VUID-VkRenderingInfo-colorAttachmentCount-09480
    If colorAttachmentCount is not 0, and there is an element of pColorAttachments with either its resolveMode member set to VK_RESOLVE_MODE_EXTERNAL_FORMAT_DOWNSAMPLE_ANDROID, or its imageView member not set to VK_NULL_HANDLE and its resolveMode member not set to VK_RESOLVE_MODE_NONE, the resolveImageView member of that element of pColorAttachments must have been created with the identity swizzle

  • VUID-VkRenderingInfo-pDepthAttachment-09481
    If pDepthAttachment is not NULL and pDepthAttachment->imageView is not VK_NULL_HANDLE, pDepthAttachment->imageView must have been created with the identity swizzle

  • VUID-VkRenderingInfo-pDepthAttachment-09482
    If pDepthAttachment is not NULL, pDepthAttachment->imageView is not VK_NULL_HANDLE, and pDepthAttachment->resolveMode is not VK_RESOLVE_MODE_NONE, pDepthAttachment->resolveImageView must have been created with the identity swizzle

  • VUID-VkRenderingInfo-pStencilAttachment-09483
    If pStencilAttachment is not NULL and pStencilAttachment->imageView is not VK_NULL_HANDLE, pStencilAttachment->imageView must have been created with the identity swizzle

  • VUID-VkRenderingInfo-pStencilAttachment-09484
    If pStencilAttachment is not NULL, pStencilAttachment->imageView is not VK_NULL_HANDLE, and pStencilAttachment->resolveMode is not VK_RESOLVE_MODE_NONE, pStencilAttachment->resolveImageView must have been created with the identity swizzle

  • VUID-VkRenderingInfo-imageView-09485
    If the imageView member of a VkRenderingFragmentShadingRateAttachmentInfoKHR structure included in the pNext chain is not VK_NULL_HANDLE, it must have been created with the identity swizzle

  • VUID-VkRenderingInfo-imageView-09486
    If the imageView member of a VkRenderingFragmentDensityMapAttachmentInfoEXT structure included in the pNext chain is not VK_NULL_HANDLE, it must have been created with the identity swizzle

Valid Usage (Implicit)

Bits which can be set in VkRenderingInfo::flags describing additional properties of the render pass are:

// Provided by VK_VERSION_1_3
typedef enum VkRenderingFlagBits {
    VK_RENDERING_CONTENTS_SECONDARY_COMMAND_BUFFERS_BIT = 0x00000001,
    VK_RENDERING_SUSPENDING_BIT = 0x00000002,
    VK_RENDERING_RESUMING_BIT = 0x00000004,
  // Provided by VK_EXT_legacy_dithering with (VK_KHR_dynamic_rendering or VK_VERSION_1_3) and VK_KHR_maintenance5
    VK_RENDERING_ENABLE_LEGACY_DITHERING_BIT_EXT = 0x00000008,
  // Provided by VK_KHR_maintenance7
    VK_RENDERING_CONTENTS_INLINE_BIT_KHR = 0x00000010,
    VK_RENDERING_CONTENTS_SECONDARY_COMMAND_BUFFERS_BIT_KHR = VK_RENDERING_CONTENTS_SECONDARY_COMMAND_BUFFERS_BIT,
    VK_RENDERING_SUSPENDING_BIT_KHR = VK_RENDERING_SUSPENDING_BIT,
    VK_RENDERING_RESUMING_BIT_KHR = VK_RENDERING_RESUMING_BIT,
  // Provided by VK_EXT_nested_command_buffer
    VK_RENDERING_CONTENTS_INLINE_BIT_EXT = VK_RENDERING_CONTENTS_INLINE_BIT_KHR,
} VkRenderingFlagBits;

or the equivalent

// Provided by VK_KHR_dynamic_rendering
typedef VkRenderingFlagBits VkRenderingFlagBitsKHR;

  • VK_RENDERING_CONTENTS_SECONDARY_COMMAND_BUFFERS_BIT specifies that draw calls for the render pass instance will be recorded in secondary command buffers. If the nestedCommandBuffer feature is enabled, the draw calls can come from both inline and vkCmdExecuteCommands.

  • VK_RENDERING_RESUMING_BIT specifies that the render pass instance is resuming an earlier suspended render pass instance.

  • VK_RENDERING_SUSPENDING_BIT specifies that the render pass instance will be suspended.

  • VK_RENDERING_ENABLE_LEGACY_DITHERING_BIT_EXT specifies that Legacy Dithering is enabled for the render pass instance.

  • VK_RENDERING_CONTENTS_INLINE_BIT_KHR specifies that draw calls for the render pass instance can be recorded inline within the current command buffer. This can be combined with the VK_RENDERING_CONTENTS_SECONDARY_COMMAND_BUFFERS_BIT bit to allow draw calls to be recorded both inline and in secondary command buffers.

The contents of pRenderingInfo must match between suspended render pass instances and the render pass instances that resume them, other than the presence or absence of the VK_RENDERING_RESUMING_BIT, VK_RENDERING_SUSPENDING_BIT, and VK_RENDERING_CONTENTS_SECONDARY_COMMAND_BUFFERS_BIT flags. No action or synchronization commands, or other render pass instances, are allowed between suspending and resuming render pass instances.

// Provided by VK_VERSION_1_3
typedef VkFlags VkRenderingFlags;

or the equivalent

// Provided by VK_KHR_dynamic_rendering
typedef VkRenderingFlags VkRenderingFlagsKHR;

VkRenderingFlags is a bitmask type for setting a mask of zero or more VkRenderingFlagBits.

The VkRenderingAttachmentInfo structure is defined as:

// Provided by VK_VERSION_1_3
typedef struct VkRenderingAttachmentInfo {
    VkStructureType          sType;
    const void*              pNext;
    VkImageView              imageView;
    VkImageLayout            imageLayout;
    VkResolveModeFlagBits    resolveMode;
    VkImageView              resolveImageView;
    VkImageLayout            resolveImageLayout;
    VkAttachmentLoadOp       loadOp;
    VkAttachmentStoreOp      storeOp;
    VkClearValue             clearValue;
} VkRenderingAttachmentInfo;

or the equivalent

// Provided by VK_KHR_dynamic_rendering
typedef VkRenderingAttachmentInfo VkRenderingAttachmentInfoKHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • imageView is the image view that will be used for rendering.

  • imageLayout is the layout that imageView will be in during rendering.

  • resolveMode is a VkResolveModeFlagBits value defining how data written to imageView will be resolved into resolveImageView.

  • resolveImageView is an image view used to write resolved data at the end of rendering.

  • resolveImageLayout is the layout that resolveImageView will be in during rendering.

  • loadOp is a VkAttachmentLoadOp value defining the load operation for the attachment.

  • storeOp is a VkAttachmentStoreOp value defining the store operation for the attachment.

  • clearValue is a VkClearValue structure defining values used to clear imageView when loadOp is VK_ATTACHMENT_LOAD_OP_CLEAR.

Values in imageView are loaded and stored according to the values of loadOp and storeOp, within the render area for each device specified in VkRenderingInfo. If imageView is VK_NULL_HANDLE, and resolveMode is not VK_RESOLVE_MODE_EXTERNAL_FORMAT_DOWNSAMPLE_ANDROID, other members of this structure are ignored; writes to this attachment will be discarded, and no load, store, or multisample resolve operations will be performed.

If resolveMode is VK_RESOLVE_MODE_NONE, then resolveImageView is ignored. If resolveMode is not VK_RESOLVE_MODE_NONE, and resolveImageView is not VK_NULL_HANDLE, a render pass multisample resolve operation is defined for the attachment subresource. If resolveMode is VK_RESOLVE_MODE_EXTERNAL_FORMAT_DOWNSAMPLE_ANDROID, and the nullColorAttachmentWithExternalFormatResolve limit is VK_TRUE, values are only undefined once load operations have completed.

Note

The resolve mode and store operation are independent; it is valid to write both resolved and unresolved values, and equally valid to discard the unresolved values while writing the resolved ones.

Store and resolve operations are only performed at the end of a render pass instance that does not specify the VK_RENDERING_SUSPENDING_BIT_KHR flag.

Load operations are only performed at the beginning of a render pass instance that does not specify the VK_RENDERING_RESUMING_BIT_KHR flag.

Image contents at the end of a suspended render pass instance remain defined for access by a resuming render pass instance.

If the nullColorAttachmentWithExternalFormatResolve limit is VK_TRUE, and resolveMode is VK_RESOLVE_MODE_EXTERNAL_FORMAT_DOWNSAMPLE_ANDROID, values in the color attachment will be loaded from the resolve attachment at the start of rendering, and may also be reloaded any time after a resolve occurs or the resolve attachment is written to; if this occurs it must happen-before any writes to the color attachment are performed which happen-after the resolve that triggers this. If any color component in the external format is subsampled, values will be read from the nearest sample in the image when they are loaded.

Valid Usage

  • VUID-VkRenderingAttachmentInfo-imageView-06129
    If imageView is not VK_NULL_HANDLE and has a non-integer color format, resolveMode must be VK_RESOLVE_MODE_NONE or VK_RESOLVE_MODE_AVERAGE_BIT

  • VUID-VkRenderingAttachmentInfo-imageView-06130
    If imageView is not VK_NULL_HANDLE and has an integer color format, resolveMode must be VK_RESOLVE_MODE_NONE or VK_RESOLVE_MODE_SAMPLE_ZERO_BIT

  • VUID-VkRenderingAttachmentInfo-imageView-06861
    imageView must not have a sample count of VK_SAMPLE_COUNT_1_BIT if all of the following hold:

  • VUID-VkRenderingAttachmentInfo-imageView-06862
    resolveImageView must not be VK_NULL_HANDLE if all of the following hold:

  • VUID-VkRenderingAttachmentInfo-imageView-06863
    If imageView is not VK_NULL_HANDLE, resolveMode is not VK_RESOLVE_MODE_NONE, the pNext chain of VkRenderingInfo includes a VkMultisampledRenderToSingleSampledInfoEXT structure with the multisampledRenderToSingleSampledEnable field equal to VK_TRUE, and imageView has a sample count of VK_SAMPLE_COUNT_1_BIT, resolveImageView must be VK_NULL_HANDLE

  • VUID-VkRenderingAttachmentInfo-imageView-06864
    If imageView is not VK_NULL_HANDLE, resolveImageView is not VK_NULL_HANDLE, and resolveMode is not VK_RESOLVE_MODE_NONE, resolveImageView must have a sample count of VK_SAMPLE_COUNT_1_BIT

  • VUID-VkRenderingAttachmentInfo-imageView-06865
    If imageView is not VK_NULL_HANDLE, resolveImageView is not VK_NULL_HANDLE, and resolveMode is not VK_RESOLVE_MODE_NONE, imageView and resolveImageView must have the same VkFormat

  • VUID-VkRenderingAttachmentInfo-imageView-06135
    If imageView is not VK_NULL_HANDLE, imageLayout must not be VK_IMAGE_LAYOUT_UNDEFINED, VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL, VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL, VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL, or VK_IMAGE_LAYOUT_PREINITIALIZED

  • VUID-VkRenderingAttachmentInfo-imageView-06136
    If imageView is not VK_NULL_HANDLE and resolveMode is not VK_RESOLVE_MODE_NONE, resolveImageLayout must not be VK_IMAGE_LAYOUT_UNDEFINED, VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL, VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL, VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL, VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL, or VK_IMAGE_LAYOUT_PREINITIALIZED

  • VUID-VkRenderingAttachmentInfo-imageView-06137
    If imageView is not VK_NULL_HANDLE and resolveMode is not VK_RESOLVE_MODE_NONE, resolveImageLayout must not be VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL or VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL

  • VUID-VkRenderingAttachmentInfo-imageView-06138
    If imageView is not VK_NULL_HANDLE, imageLayout must not be VK_IMAGE_LAYOUT_SHADING_RATE_OPTIMAL_NV

  • VUID-VkRenderingAttachmentInfo-imageView-06139
    If imageView is not VK_NULL_HANDLE and resolveMode is not VK_RESOLVE_MODE_NONE, resolveImageLayout must not be VK_IMAGE_LAYOUT_SHADING_RATE_OPTIMAL_NV

  • VUID-VkRenderingAttachmentInfo-imageView-06140
    If imageView is not VK_NULL_HANDLE, imageLayout must not be VK_IMAGE_LAYOUT_FRAGMENT_DENSITY_MAP_OPTIMAL_EXT

  • VUID-VkRenderingAttachmentInfo-imageView-06141
    If imageView is not VK_NULL_HANDLE and resolveMode is not VK_RESOLVE_MODE_NONE, resolveImageLayout must not be VK_IMAGE_LAYOUT_FRAGMENT_DENSITY_MAP_OPTIMAL_EXT

  • VUID-VkRenderingAttachmentInfo-imageView-06142
    If imageView is not VK_NULL_HANDLE and resolveMode is not VK_RESOLVE_MODE_NONE, resolveImageLayout must not be VK_IMAGE_LAYOUT_READ_ONLY_OPTIMAL_KHR

  • VUID-VkRenderingAttachmentInfo-imageView-06143
    If imageView is not VK_NULL_HANDLE, imageLayout must not be VK_IMAGE_LAYOUT_FRAGMENT_SHADING_RATE_ATTACHMENT_OPTIMAL_KHR

  • VUID-VkRenderingAttachmentInfo-imageView-06144
    If imageView is not VK_NULL_HANDLE and resolveMode is not VK_RESOLVE_MODE_NONE, resolveImageLayout must not be VK_IMAGE_LAYOUT_FRAGMENT_SHADING_RATE_ATTACHMENT_OPTIMAL_KHR

  • VUID-VkRenderingAttachmentInfo-imageView-06145
    If imageView is not VK_NULL_HANDLE, imageLayout must not be VK_IMAGE_LAYOUT_PRESENT_SRC_KHR

  • VUID-VkRenderingAttachmentInfo-imageView-06146
    If imageView is not VK_NULL_HANDLE and resolveMode is not VK_RESOLVE_MODE_NONE, resolveImageLayout must not be VK_IMAGE_LAYOUT_PRESENT_SRC_KHR

  • VUID-VkRenderingAttachmentInfo-externalFormatResolve-09323
    If externalFormatResolve is not enabled, resolveMode must not be VK_RESOLVE_MODE_EXTERNAL_FORMAT_DOWNSAMPLE_ANDROID

  • VUID-VkRenderingAttachmentInfo-resolveMode-09324
    If resolveMode is VK_RESOLVE_MODE_EXTERNAL_FORMAT_DOWNSAMPLE_ANDROID, resolveImageView must be a valid image view

  • VUID-VkRenderingAttachmentInfo-nullColorAttachmentWithExternalFormatResolve-09325
    If the nullColorAttachmentWithExternalFormatResolve property is VK_TRUE and resolveMode is VK_RESOLVE_MODE_EXTERNAL_FORMAT_DOWNSAMPLE_ANDROID, resolveImageView must have been created with an image with a samples value of VK_SAMPLE_COUNT_1_BIT

  • VUID-VkRenderingAttachmentInfo-resolveMode-09326
    If resolveMode is VK_RESOLVE_MODE_EXTERNAL_FORMAT_DOWNSAMPLE_ANDROID, resolveImageView must have been created with an external format specified by VkExternalFormatANDROID

  • VUID-VkRenderingAttachmentInfo-resolveMode-09327
    If resolveMode is VK_RESOLVE_MODE_EXTERNAL_FORMAT_DOWNSAMPLE_ANDROID, resolveImageView must have been created with a subresourceRange.layerCount of 1

  • VUID-VkRenderingAttachmentInfo-resolveMode-09328
    If resolveMode is VK_RESOLVE_MODE_EXTERNAL_FORMAT_DOWNSAMPLE_ANDROID and nullColorAttachmentWithExternalFormatResolve is VK_TRUE, imageView must be VK_NULL_HANDLE

  • VUID-VkRenderingAttachmentInfo-resolveMode-09329
    If resolveMode is VK_RESOLVE_MODE_EXTERNAL_FORMAT_DOWNSAMPLE_ANDROID and nullColorAttachmentWithExternalFormatResolve is VK_FALSE, imageView must be a valid VkImageView

  • VUID-VkRenderingAttachmentInfo-resolveMode-09330
    If resolveMode is VK_RESOLVE_MODE_EXTERNAL_FORMAT_DOWNSAMPLE_ANDROID and nullColorAttachmentWithExternalFormatResolve is VK_FALSE, imageView must have a format equal to the value of VkAndroidHardwareBufferFormatResolvePropertiesANDROID::colorAttachmentFormat as returned by a call to vkGetAndroidHardwareBufferPropertiesANDROID for the Android hardware buffer that was used to create resolveImageView

Valid Usage (Implicit)

  • VUID-VkRenderingAttachmentInfo-sType-sType
    sType must be VK_STRUCTURE_TYPE_RENDERING_ATTACHMENT_INFO

  • VUID-VkRenderingAttachmentInfo-pNext-pNext
    pNext must be NULL

  • VUID-VkRenderingAttachmentInfo-imageView-parameter
    If imageView is not VK_NULL_HANDLE, imageView must be a valid VkImageView handle

  • VUID-VkRenderingAttachmentInfo-imageLayout-parameter
    imageLayout must be a valid VkImageLayout value

  • VUID-VkRenderingAttachmentInfo-resolveMode-parameter
    If resolveMode is not 0, resolveMode must be a valid VkResolveModeFlagBits value

  • VUID-VkRenderingAttachmentInfo-resolveImageView-parameter
    If resolveImageView is not VK_NULL_HANDLE, resolveImageView must be a valid VkImageView handle

  • VUID-VkRenderingAttachmentInfo-resolveImageLayout-parameter
    resolveImageLayout must be a valid VkImageLayout value

  • VUID-VkRenderingAttachmentInfo-loadOp-parameter
    loadOp must be a valid VkAttachmentLoadOp value

  • VUID-VkRenderingAttachmentInfo-storeOp-parameter
    storeOp must be a valid VkAttachmentStoreOp value

  • VUID-VkRenderingAttachmentInfo-clearValue-parameter
    clearValue must be a valid VkClearValue union

  • VUID-VkRenderingAttachmentInfo-commonparent
    Both of imageView, and resolveImageView that are valid handles of non-ignored parameters must have been created, allocated, or retrieved from the same VkDevice

The VkRenderingFragmentShadingRateAttachmentInfoKHR structure is defined as:

// Provided by VK_KHR_dynamic_rendering with VK_KHR_fragment_shading_rate
typedef struct VkRenderingFragmentShadingRateAttachmentInfoKHR {
    VkStructureType    sType;
    const void*        pNext;
    VkImageView        imageView;
    VkImageLayout      imageLayout;
    VkExtent2D         shadingRateAttachmentTexelSize;
} VkRenderingFragmentShadingRateAttachmentInfoKHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • imageView is the image view that will be used as a fragment shading rate attachment.

  • imageLayout is the layout that imageView will be in during rendering.

  • shadingRateAttachmentTexelSize specifies the number of pixels corresponding to each texel in imageView.

This structure can be included in the pNext chain of VkRenderingInfo to define a fragment shading rate attachment. If imageView is VK_NULL_HANDLE, or if this structure is not specified, the implementation behaves as if a valid shading rate attachment was specified with all texels specifying a single pixel per fragment.

Valid Usage

  • VUID-VkRenderingFragmentShadingRateAttachmentInfoKHR-imageView-06147
    If imageView is not VK_NULL_HANDLE, layout must be VK_IMAGE_LAYOUT_GENERAL or VK_IMAGE_LAYOUT_FRAGMENT_SHADING_RATE_ATTACHMENT_OPTIMAL_KHR

  • VUID-VkRenderingFragmentShadingRateAttachmentInfoKHR-imageView-06148
    If imageView is not VK_NULL_HANDLE, it must have been created with VK_IMAGE_USAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR

  • VUID-VkRenderingFragmentShadingRateAttachmentInfoKHR-imageView-06149
    If imageView is not VK_NULL_HANDLE, shadingRateAttachmentTexelSize.width must be a power of two value

  • VUID-VkRenderingFragmentShadingRateAttachmentInfoKHR-imageView-06150
    If imageView is not VK_NULL_HANDLE, shadingRateAttachmentTexelSize.width must be less than or equal to maxFragmentShadingRateAttachmentTexelSize.width

  • VUID-VkRenderingFragmentShadingRateAttachmentInfoKHR-imageView-06151
    If imageView is not VK_NULL_HANDLE, shadingRateAttachmentTexelSize.width must be greater than or equal to minFragmentShadingRateAttachmentTexelSize.width

  • VUID-VkRenderingFragmentShadingRateAttachmentInfoKHR-imageView-06152
    If imageView is not VK_NULL_HANDLE, shadingRateAttachmentTexelSize.height must be a power of two value

  • VUID-VkRenderingFragmentShadingRateAttachmentInfoKHR-imageView-06153
    If imageView is not VK_NULL_HANDLE, shadingRateAttachmentTexelSize.height must be less than or equal to maxFragmentShadingRateAttachmentTexelSize.height

  • VUID-VkRenderingFragmentShadingRateAttachmentInfoKHR-imageView-06154
    If imageView is not VK_NULL_HANDLE, shadingRateAttachmentTexelSize.height must be greater than or equal to minFragmentShadingRateAttachmentTexelSize.height

  • VUID-VkRenderingFragmentShadingRateAttachmentInfoKHR-imageView-06155
    If imageView is not VK_NULL_HANDLE, the quotient of shadingRateAttachmentTexelSize.width and shadingRateAttachmentTexelSize.height must be less than or equal to maxFragmentShadingRateAttachmentTexelSizeAspectRatio

  • VUID-VkRenderingFragmentShadingRateAttachmentInfoKHR-imageView-06156
    If imageView is not VK_NULL_HANDLE, the quotient of shadingRateAttachmentTexelSize.height and shadingRateAttachmentTexelSize.width must be less than or equal to maxFragmentShadingRateAttachmentTexelSizeAspectRatio

Valid Usage (Implicit)

  • VUID-VkRenderingFragmentShadingRateAttachmentInfoKHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_RENDERING_FRAGMENT_SHADING_RATE_ATTACHMENT_INFO_KHR

  • VUID-VkRenderingFragmentShadingRateAttachmentInfoKHR-imageView-parameter
    If imageView is not VK_NULL_HANDLE, imageView must be a valid VkImageView handle

  • VUID-VkRenderingFragmentShadingRateAttachmentInfoKHR-imageLayout-parameter
    imageLayout must be a valid VkImageLayout value

The VkRenderingFragmentDensityMapAttachmentInfoEXT structure is defined as:

// Provided by VK_KHR_dynamic_rendering with VK_EXT_fragment_density_map
typedef struct VkRenderingFragmentDensityMapAttachmentInfoEXT {
    VkStructureType    sType;
    const void*        pNext;
    VkImageView        imageView;
    VkImageLayout      imageLayout;
} VkRenderingFragmentDensityMapAttachmentInfoEXT;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • imageView is the image view that will be used as a fragment density map attachment.

  • imageLayout is the layout that imageView will be in during rendering.

This structure can be included in the pNext chain of VkRenderingInfo to define a fragment density map. If this structure is not included in the pNext chain, imageView is treated as VK_NULL_HANDLE.

Valid Usage

  • VUID-VkRenderingFragmentDensityMapAttachmentInfoEXT-imageView-06157
    If imageView is not VK_NULL_HANDLE, imageLayout must be VK_IMAGE_LAYOUT_GENERAL or VK_IMAGE_LAYOUT_FRAGMENT_DENSITY_MAP_OPTIMAL_EXT

  • VUID-VkRenderingFragmentDensityMapAttachmentInfoEXT-imageView-06158
    If imageView is not VK_NULL_HANDLE, it must have been created with VK_IMAGE_USAGE_FRAGMENT_DENSITY_MAP_BIT_EXT

  • VUID-VkRenderingFragmentDensityMapAttachmentInfoEXT-imageView-06159
    If imageView is not VK_NULL_HANDLE, it must not have been created with VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT

  • VUID-VkRenderingFragmentDensityMapAttachmentInfoEXT-apiVersion-07908
    If the multiview feature is not enabled, VkPhysicalDeviceProperties::apiVersion is less than Vulkan 1.1, and imageView is not VK_NULL_HANDLE, it must have a layerCount equal to 1

Valid Usage (Implicit)

  • VUID-VkRenderingFragmentDensityMapAttachmentInfoEXT-sType-sType
    sType must be VK_STRUCTURE_TYPE_RENDERING_FRAGMENT_DENSITY_MAP_ATTACHMENT_INFO_EXT

  • VUID-VkRenderingFragmentDensityMapAttachmentInfoEXT-imageView-parameter
    imageView must be a valid VkImageView handle

  • VUID-VkRenderingFragmentDensityMapAttachmentInfoEXT-imageLayout-parameter
    imageLayout must be a valid VkImageLayout value

To query the render area granularity for a render pass instance, call:

// Provided by VK_KHR_maintenance5
void vkGetRenderingAreaGranularityKHR(
    VkDevice                                    device,
    const VkRenderingAreaInfoKHR*               pRenderingAreaInfo,
    VkExtent2D*                                 pGranularity);

  • device is the logical device that owns the render pass instance.

  • pRenderingAreaInfo is a pointer to a VkRenderingAreaInfoKHR structure specifying details of the render pass instance to query the render area granularity for.

  • pGranularity is a pointer to a VkExtent2D structure in which the granularity is returned.

The conditions leading to an optimal renderArea are:

  • the offset.x member in renderArea is a multiple of the width member of the returned VkExtent2D (the horizontal granularity).

  • the offset.y member in renderArea is a multiple of the height member of the returned VkExtent2D (the vertical granularity).

  • either the extent.width member in renderArea is a multiple of the horizontal granularity or offset.x+extent.width is equal to the width of each attachment used in the render pass instance.

  • either the extent.height member in renderArea is a multiple of the vertical granularity or offset.y+extent.height is equal to the height of each attachment used in the render pass instance.

Valid Usage (Implicit)

  • VUID-vkGetRenderingAreaGranularityKHR-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkGetRenderingAreaGranularityKHR-pRenderingAreaInfo-parameter
    pRenderingAreaInfo must be a valid pointer to a valid VkRenderingAreaInfoKHR structure

  • VUID-vkGetRenderingAreaGranularityKHR-pGranularity-parameter
    pGranularity must be a valid pointer to a VkExtent2D structure

The VkRenderingAreaInfoKHR structure is defined as:

// Provided by VK_KHR_maintenance5
typedef struct VkRenderingAreaInfoKHR {
    VkStructureType    sType;
    const void*        pNext;
    uint32_t           viewMask;
    uint32_t           colorAttachmentCount;
    const VkFormat*    pColorAttachmentFormats;
    VkFormat           depthAttachmentFormat;
    VkFormat           stencilAttachmentFormat;
} VkRenderingAreaInfoKHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • viewMask is the viewMask used for rendering.

  • colorAttachmentCount is the number of entries in pColorAttachmentFormats

  • pColorAttachmentFormats is a pointer to an array of VkFormat values defining the format of color attachments used in the render pass instance.

  • depthAttachmentFormat is a VkFormat value defining the format of the depth attachment used in the render pass instance.

  • stencilAttachmentFormat is a VkFormat value defining the format of the stencil attachment used in the render pass instance.

Valid Usage (Implicit)

  • VUID-VkRenderingAreaInfoKHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_RENDERING_AREA_INFO_KHR

  • VUID-VkRenderingAreaInfoKHR-pNext-pNext
    pNext must be NULL

The VkRenderPassStripeBeginInfoARM structure is defined as:

// Provided by VK_ARM_render_pass_striped
typedef struct VkRenderPassStripeBeginInfoARM {
    VkStructureType                     sType;
    const void*                         pNext;
    uint32_t                            stripeInfoCount;
    const VkRenderPassStripeInfoARM*    pStripeInfos;
} VkRenderPassStripeBeginInfoARM;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • stripeInfoCount is the number of stripes in this render pass instance

  • pStripeInfos is a pointer to an array of stripeInfoCount VkRenderPassStripeInfoARM structures describing the stripes used by the render pass instance.

This structure can be included in the pNext chain of VkRenderPassBeginInfo or VkRenderingInfo to define how the render pass instance is split into stripes.

Valid Usage

  • VUID-VkRenderPassStripeBeginInfoARM-stripeInfoCount-09450
    stripeInfoCount must be less than or equal to VkPhysicalDeviceRenderPassStripedPropertiesARM::maxRenderPassStripes

  • VUID-VkRenderPassStripeBeginInfoARM-stripeArea-09451
    The stripeArea defined by each element of pStripeInfos must not overlap the stripeArea of any other element

Valid Usage (Implicit)

  • VUID-VkRenderPassStripeBeginInfoARM-sType-sType
    sType must be VK_STRUCTURE_TYPE_RENDER_PASS_STRIPE_BEGIN_INFO_ARM

  • VUID-VkRenderPassStripeBeginInfoARM-pStripeInfos-parameter
    pStripeInfos must be a valid pointer to an array of stripeInfoCount valid VkRenderPassStripeInfoARM structures

  • VUID-VkRenderPassStripeBeginInfoARM-stripeInfoCount-arraylength
    stripeInfoCount must be greater than 0

The VkRenderPassStripeInfoARM structure is defined as:

// Provided by VK_ARM_render_pass_striped
typedef struct VkRenderPassStripeInfoARM {
    VkStructureType    sType;
    const void*        pNext;
    VkRect2D           stripeArea;
} VkRenderPassStripeInfoARM;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • stripeArea is the stripe area, and is described in more detail below.

stripeArea is the render area that is affected by this stripe of the render pass instance. It must be a subregion of the renderArea of the render pass instance.

Valid Usage

  • VUID-VkRenderPassStripeInfoARM-stripeArea-09452
    stripeArea.offset.x must be a multiple of VkPhysicalDeviceRenderPassStripedPropertiesARM::renderPassStripeGranularity.width

  • VUID-VkRenderPassStripeInfoARM-stripeArea-09453
    stripeArea.extent.width must be a multiple of VkPhysicalDeviceRenderPassStripedPropertiesARM::renderPassStripeGranularity.width, or the sum of stripeArea.offset.x and stripeArea.extent.width must be equal to the renderArea.extent.width of the render pass instance

  • VUID-VkRenderPassStripeInfoARM-stripeArea-09454
    stripeArea.offset.y must be a multiple of VkPhysicalDeviceRenderPassStripedPropertiesARM::renderPassStripeGranularity.height

  • VUID-VkRenderPassStripeInfoARM-stripeArea-09455
    stripeArea.extent.height must be a multiple of VkPhysicalDeviceRenderPassStripedPropertiesARM::renderPassStripeGranularity.height, or the sum of stripeArea.offset.y and stripeArea.extent.height must be equal to the renderArea.extent.height of the render pass instance

Valid Usage (Implicit)

  • VUID-VkRenderPassStripeInfoARM-sType-sType
    sType must be VK_STRUCTURE_TYPE_RENDER_PASS_STRIPE_INFO_ARM

  • VUID-VkRenderPassStripeInfoARM-pNext-pNext
    pNext must be NULL

To end a render pass instance, call:

// Provided by VK_VERSION_1_3
void vkCmdEndRendering(
    VkCommandBuffer                             commandBuffer);

or the equivalent command

// Provided by VK_KHR_dynamic_rendering
void vkCmdEndRenderingKHR(
    VkCommandBuffer                             commandBuffer);

  • commandBuffer is the command buffer in which to record the command.

If the value of pRenderingInfo->flags used to begin this render pass instance included VK_RENDERING_SUSPENDING_BIT, then this render pass is suspended and will be resumed later in submission order.

Valid Usage

  • VUID-vkCmdEndRendering-None-06161
    The current render pass instance must have been begun with vkCmdBeginRendering

  • VUID-vkCmdEndRendering-commandBuffer-06162
    The current render pass instance must have been begun in commandBuffer

  • VUID-vkCmdEndRendering-None-06781
    This command must not be recorded when transform feedback is active

  • VUID-vkCmdEndRendering-None-06999
    If vkCmdBeginQuery* was called within the render pass, the corresponding vkCmdEndQuery* must have been called subsequently within the same subpass

Valid Usage (Implicit)

  • VUID-vkCmdEndRendering-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdEndRendering-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdEndRendering-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support graphics operations

  • VUID-vkCmdEndRendering-renderpass
    This command must only be called inside of a render pass instance

  • VUID-vkCmdEndRendering-videocoding
    This command must only be called outside of a video coding scope

Host Synchronization

  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Video Coding Scope Supported Queue Types Command Type

Primary
Secondary

Inside

Outside

Graphics

Action
State
Note

For more complex rendering graphs, it is possible to pre-define a static render pass object, which as well as allowing draw commands, allows the definition of framebuffer-local dependencies between multiple subpasses. These objects have a lot of setup cost compared to vkCmdBeginRendering, but use of subpass dependencies can confer important performance benefits on some devices.

The VkTilePropertiesQCOM structure is defined as:

// Provided by VK_QCOM_tile_properties
typedef struct VkTilePropertiesQCOM {
    VkStructureType    sType;
    void*              pNext;
    VkExtent3D         tileSize;
    VkExtent2D         apronSize;
    VkOffset2D         origin;
} VkTilePropertiesQCOM;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • tileSize is the dimensions of a tile, with width and height describing the width and height of a tile in pixels, and depth corresponding to the number of slices the tile spans.

  • apronSize is the dimension of the apron.

  • origin is the top-left corner of the first tile in attachment space.

All tiles will be tightly packed around the first tile, with edges being multiples of tile width and/or height from the origin.

Note

Reported value for apronSize will be zero and its functionality will be described in a future extension.
Valid Usage (Implicit)

  • VUID-VkTilePropertiesQCOM-sType-sType
    sType must be VK_STRUCTURE_TYPE_TILE_PROPERTIES_QCOM

  • VUID-VkTilePropertiesQCOM-pNext-pNext
    pNext must be NULL

To query the tile properties when using dynamic rendering, call:

// Provided by VK_QCOM_tile_properties
VkResult vkGetDynamicRenderingTilePropertiesQCOM(
    VkDevice                                    device,
    const VkRenderingInfo*                      pRenderingInfo,
    VkTilePropertiesQCOM*                       pProperties);

  • device is a logical device associated with the render pass.

  • pRenderingInfo is a pointer to the VkRenderingInfo structure specifying details of the render pass instance in dynamic rendering.

  • pProperties is a pointer to a VkTilePropertiesQCOM structure in which the properties are returned.

Valid Usage (Implicit)

  • VUID-vkGetDynamicRenderingTilePropertiesQCOM-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkGetDynamicRenderingTilePropertiesQCOM-pRenderingInfo-parameter
    pRenderingInfo must be a valid pointer to a valid VkRenderingInfo structure

  • VUID-vkGetDynamicRenderingTilePropertiesQCOM-pProperties-parameter
    pProperties must be a valid pointer to a VkTilePropertiesQCOM structure

Return Codes
Success

  • VK_SUCCESS

Failure

None

8.1. Render Pass Objects

A render pass object represents a collection of attachments, subpasses, and dependencies between the subpasses, and describes how the attachments are used over the course of the subpasses.

Render passes are represented by VkRenderPass handles:

// Provided by VK_VERSION_1_0
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkRenderPass)

An attachment description describes the properties of an attachment including its format, sample count, and how its contents are treated at the beginning and end of each render pass instance.

A subpass represents a phase of rendering that reads and writes a subset of the attachments in a render pass. Rendering commands are recorded into a particular subpass of a render pass instance.

A subpass description describes the subset of attachments that is involved in the execution of a subpass. Each subpass can read from some attachments as input attachments, write to some as color attachments or depth/stencil attachments, perform shader resolve operations to color_attachments or depth/stencil_attachments, and perform multisample resolve operations to resolve attachments. A subpass description can also include a set of preserve attachments, which are attachments that are not read or written by the subpass but whose contents must be preserved throughout the subpass.

A subpass uses an attachment if the attachment is a color, depth/stencil, resolve, depth/stencil resolve, fragment shading rate, or input attachment for that subpass (as determined by the pColorAttachments, pDepthStencilAttachment, pResolveAttachments, VkSubpassDescriptionDepthStencilResolve::pDepthStencilResolveAttachment, VkFragmentShadingRateAttachmentInfoKHR::pFragmentShadingRateAttachment->attachment, and pInputAttachments members of VkSubpassDescription, respectively). A subpass does not use an attachment if that attachment is preserved by the subpass. The first use of an attachment is in the lowest numbered subpass that uses that attachment. Similarly, the last use of an attachment is in the highest numbered subpass that uses that attachment.

The subpasses in a render pass all render to the same dimensions, and fragments for pixel (x,y,layer) in one subpass can only read attachment contents written by previous subpasses at that same (x,y,layer) location. For multi-pixel fragments, the pixel read from an input attachment is selected from the pixels covered by that fragment in an implementation-dependent manner. However, this selection must be made consistently for any fragment with the same shading rate for the lifetime of the VkDevice.

Note

By describing a complete set of subpasses in advance, render passes provide the implementation an opportunity to optimize the storage and transfer of attachment data between subpasses.

In practice, this means that subpasses with a simple framebuffer-space dependency may be merged into a single tiled rendering pass, keeping the attachment data on-chip for the duration of a render pass instance. However, it is also quite common for a render pass to only contain a single subpass.

Subpass dependencies describe execution and memory dependencies between subpasses.

A subpass dependency chain is a sequence of subpass dependencies in a render pass, where the source subpass of each subpass dependency (after the first) equals the destination subpass of the previous dependency.

Execution of subpasses may overlap or execute out of order with regards to other subpasses, unless otherwise enforced by an execution dependency. Each subpass only respects submission order for commands recorded in the same subpass, and the vkCmdBeginRenderPass and vkCmdEndRenderPass commands that delimit the render pass - commands within other subpasses are not included. This affects most other implicit ordering guarantees.

A render pass describes the structure of subpasses and attachments independent of any specific image views for the attachments. The specific image views that will be used for the attachments, and their dimensions, are specified in VkFramebuffer objects. Framebuffers are created with respect to a specific render pass that the framebuffer is compatible with (see Render Pass Compatibility). Collectively, a render pass and a framebuffer define the complete render target state for one or more subpasses as well as the algorithmic dependencies between the subpasses.

The various pipeline stages of the drawing commands for a given subpass may execute concurrently and/or out of order, both within and across drawing commands, whilst still respecting pipeline order. However for a given (x,y,layer,sample) sample location, certain per-sample operations are performed in rasterization order.

VK_ATTACHMENT_UNUSED is a constant indicating that a render pass attachment is not used.

#define VK_ATTACHMENT_UNUSED              (~0U)

8.2. Render Pass Creation

To create a render pass, call:

// Provided by VK_VERSION_1_0
VkResult vkCreateRenderPass(
    VkDevice                                    device,
    const VkRenderPassCreateInfo*               pCreateInfo,
    const VkAllocationCallbacks*                pAllocator,
    VkRenderPass*                               pRenderPass);

  • device is the logical device that creates the render pass.

  • pCreateInfo is a pointer to a VkRenderPassCreateInfo structure describing the parameters of the render pass.

  • pAllocator controls host memory allocation as described in the Memory Allocation chapter.

  • pRenderPass is a pointer to a VkRenderPass handle in which the resulting render pass object is returned.

Valid Usage

  • VUID-vkCreateRenderPass-device-10000
    device must support at least one queue family with the VK_QUEUE_GRAPHICS_BIT capability

Valid Usage (Implicit)

  • VUID-vkCreateRenderPass-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkCreateRenderPass-pCreateInfo-parameter
    pCreateInfo must be a valid pointer to a valid VkRenderPassCreateInfo structure

  • VUID-vkCreateRenderPass-pAllocator-parameter
    If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure

  • VUID-vkCreateRenderPass-pRenderPass-parameter
    pRenderPass must be a valid pointer to a VkRenderPass handle

Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

The VkRenderPassCreateInfo structure is defined as:

// Provided by VK_VERSION_1_0
typedef struct VkRenderPassCreateInfo {
    VkStructureType                   sType;
    const void*                       pNext;
    VkRenderPassCreateFlags           flags;
    uint32_t                          attachmentCount;
    const VkAttachmentDescription*    pAttachments;
    uint32_t                          subpassCount;
    const VkSubpassDescription*       pSubpasses;
    uint32_t                          dependencyCount;
    const VkSubpassDependency*        pDependencies;
} VkRenderPassCreateInfo;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • flags is a bitmask of VkRenderPassCreateFlagBits

  • attachmentCount is the number of attachments used by this render pass.

  • pAttachments is a pointer to an array of attachmentCount VkAttachmentDescription structures describing the attachments used by the render pass.

  • subpassCount is the number of subpasses to create.

  • pSubpasses is a pointer to an array of subpassCount VkSubpassDescription structures describing each subpass.

  • dependencyCount is the number of memory dependencies between pairs of subpasses.

  • pDependencies is a pointer to an array of dependencyCount VkSubpassDependency structures describing dependencies between pairs of subpasses.

Note

Care should be taken to avoid a data race here; if any subpasses access attachments with overlapping memory locations, and one of those accesses is a write, a subpass dependency needs to be included between them.
Valid Usage

  • VUID-VkRenderPassCreateInfo-attachment-00834
    If the attachment member of any element of pInputAttachments, pColorAttachments, pResolveAttachments or pDepthStencilAttachment, or any element of pPreserveAttachments in any element of pSubpasses is not VK_ATTACHMENT_UNUSED, then it must be less than attachmentCount

  • VUID-VkRenderPassCreateInfo-fragmentDensityMapAttachment-06471
    If the pNext chain includes a VkRenderPassFragmentDensityMapCreateInfoEXT structure and the fragmentDensityMapAttachment member is not VK_ATTACHMENT_UNUSED, then attachment must be less than attachmentCount

  • VUID-VkRenderPassCreateInfo-pAttachments-00836
    For any member of pAttachments with a loadOp equal to VK_ATTACHMENT_LOAD_OP_CLEAR, the first use of that attachment must not specify a layout equal to VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL or VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL

  • VUID-VkRenderPassCreateInfo-pAttachments-02511
    For any member of pAttachments with a stencilLoadOp equal to VK_ATTACHMENT_LOAD_OP_CLEAR, the first use of that attachment must not specify a layout equal to VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL or VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL

  • VUID-VkRenderPassCreateInfo-pAttachments-01566
    For any member of pAttachments with a loadOp equal to VK_ATTACHMENT_LOAD_OP_CLEAR, the first use of that attachment must not specify a layout equal to VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL

  • VUID-VkRenderPassCreateInfo-pAttachments-01567
    For any member of pAttachments with a stencilLoadOp equal to VK_ATTACHMENT_LOAD_OP_CLEAR, the first use of that attachment must not specify a layout equal to VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL

  • VUID-VkRenderPassCreateInfo-pNext-01926
    If the pNext chain includes a VkRenderPassInputAttachmentAspectCreateInfo structure, the subpass member of each element of its pAspectReferences member must be less than subpassCount

  • VUID-VkRenderPassCreateInfo-pNext-01927
    If the pNext chain includes a VkRenderPassInputAttachmentAspectCreateInfo structure, the inputAttachmentIndex member of each element of its pAspectReferences member must be less than the value of inputAttachmentCount in the element of pSubpasses identified by its subpass member

  • VUID-VkRenderPassCreateInfo-pNext-01963
    If the pNext chain includes a VkRenderPassInputAttachmentAspectCreateInfo structure, for any element of the pInputAttachments member of any element of pSubpasses where the attachment member is not VK_ATTACHMENT_UNUSED, the aspectMask member of the corresponding element of VkRenderPassInputAttachmentAspectCreateInfo::pAspectReferences must only include aspects that are present in images of the format specified by the element of pAttachments at attachment

  • VUID-VkRenderPassCreateInfo-pNext-01928
    If the pNext chain includes a VkRenderPassMultiviewCreateInfo structure, and its subpassCount member is not zero, that member must be equal to the value of subpassCount

  • VUID-VkRenderPassCreateInfo-pNext-01929
    If the pNext chain includes a VkRenderPassMultiviewCreateInfo structure, if its dependencyCount member is not zero, it must be equal to dependencyCount

  • VUID-VkRenderPassCreateInfo-pNext-01930
    If the pNext chain includes a VkRenderPassMultiviewCreateInfo structure, for each non-zero element of pViewOffsets, the srcSubpass and dstSubpass members of pDependencies at the same index must not be equal

  • VUID-VkRenderPassCreateInfo-pNext-02512
    If the pNext chain includes a VkRenderPassMultiviewCreateInfo structure, for any element of pDependencies with a dependencyFlags member that does not include VK_DEPENDENCY_VIEW_LOCAL_BIT, the corresponding element of the pViewOffsets member of that VkRenderPassMultiviewCreateInfo instance must be 0

  • VUID-VkRenderPassCreateInfo-pNext-02513
    If the pNext chain includes a VkRenderPassMultiviewCreateInfo structure, elements of its pViewMasks member must either all be 0, or all not be 0

  • VUID-VkRenderPassCreateInfo-pNext-02514
    If the pNext chain includes a VkRenderPassMultiviewCreateInfo structure, and each element of its pViewMasks member is 0, the dependencyFlags member of each element of pDependencies must not include VK_DEPENDENCY_VIEW_LOCAL_BIT

  • VUID-VkRenderPassCreateInfo-pNext-02515
    If the pNext chain includes a VkRenderPassMultiviewCreateInfo structure, and each element of its pViewMasks member is 0, its correlationMaskCount member must be 0

  • VUID-VkRenderPassCreateInfo-pDependencies-00837
    For any element of pDependencies, if the srcSubpass is not VK_SUBPASS_EXTERNAL, all stage flags included in the srcStageMask member of that dependency must be a pipeline stage supported by the pipeline identified by the pipelineBindPoint member of the source subpass

  • VUID-VkRenderPassCreateInfo-pDependencies-00838
    For any element of pDependencies, if the dstSubpass is not VK_SUBPASS_EXTERNAL, all stage flags included in the dstStageMask member of that dependency must be a pipeline stage supported by the pipeline identified by the pipelineBindPoint member of the destination subpass

  • VUID-VkRenderPassCreateInfo-pDependencies-06866
    For any element of pDependencies, if its srcSubpass is not VK_SUBPASS_EXTERNAL, it must be less than subpassCount

  • VUID-VkRenderPassCreateInfo-pDependencies-06867
    For any element of pDependencies, if its dstSubpass is not VK_SUBPASS_EXTERNAL, it must be less than subpassCount

Valid Usage (Implicit)

  • VUID-VkRenderPassCreateInfo-sType-sType
    sType must be VK_STRUCTURE_TYPE_RENDER_PASS_CREATE_INFO

  • VUID-VkRenderPassCreateInfo-pNext-pNext
    Each pNext member of any structure (including this one) in the pNext chain must be either NULL or a pointer to a valid instance of VkRenderPassFragmentDensityMapCreateInfoEXT, VkRenderPassInputAttachmentAspectCreateInfo, or VkRenderPassMultiviewCreateInfo

  • VUID-VkRenderPassCreateInfo-sType-unique
    The sType value of each struct in the pNext chain must be unique

  • VUID-VkRenderPassCreateInfo-flags-parameter
    flags must be a valid combination of VkRenderPassCreateFlagBits values

  • VUID-VkRenderPassCreateInfo-pAttachments-parameter
    If attachmentCount is not 0, pAttachments must be a valid pointer to an array of attachmentCount valid VkAttachmentDescription structures

  • VUID-VkRenderPassCreateInfo-pSubpasses-parameter
    pSubpasses must be a valid pointer to an array of subpassCount valid VkSubpassDescription structures

  • VUID-VkRenderPassCreateInfo-pDependencies-parameter
    If dependencyCount is not 0, pDependencies must be a valid pointer to an array of dependencyCount valid VkSubpassDependency structures

  • VUID-VkRenderPassCreateInfo-subpassCount-arraylength
    subpassCount must be greater than 0

Bits which can be set in VkRenderPassCreateInfo::flags, describing additional properties of the render pass, are:

// Provided by VK_VERSION_1_0
typedef enum VkRenderPassCreateFlagBits {
  // Provided by VK_QCOM_render_pass_transform
    VK_RENDER_PASS_CREATE_TRANSFORM_BIT_QCOM = 0x00000002,
} VkRenderPassCreateFlagBits;

  • VK_RENDER_PASS_CREATE_TRANSFORM_BIT_QCOM specifies that the created render pass is compatible with render pass transform.

// Provided by VK_VERSION_1_0
typedef VkFlags VkRenderPassCreateFlags;

VkRenderPassCreateFlags is a bitmask type for setting a mask of zero or more VkRenderPassCreateFlagBits.

If the VkRenderPassCreateInfo::pNext chain includes a VkRenderPassMultiviewCreateInfo structure, then that structure includes an array of view masks, view offsets, and correlation masks for the render pass.

The VkRenderPassMultiviewCreateInfo structure is defined as:

// Provided by VK_VERSION_1_1
typedef struct VkRenderPassMultiviewCreateInfo {
    VkStructureType    sType;
    const void*        pNext;
    uint32_t           subpassCount;
    const uint32_t*    pViewMasks;
    uint32_t           dependencyCount;
    const int32_t*     pViewOffsets;
    uint32_t           correlationMaskCount;
    const uint32_t*    pCorrelationMasks;
} VkRenderPassMultiviewCreateInfo;

or the equivalent

// Provided by VK_KHR_multiview
typedef VkRenderPassMultiviewCreateInfo VkRenderPassMultiviewCreateInfoKHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • subpassCount is zero or the number of subpasses in the render pass.

  • pViewMasks is a pointer to an array of subpassCount view masks, where each mask is a bitfield of view indices describing which views rendering is broadcast to in each subpass, when multiview is enabled. If subpassCount is zero, each view mask is treated as zero.

  • dependencyCount is zero or the number of dependencies in the render pass.

  • pViewOffsets is a pointer to an array of dependencyCount view offsets, one for each dependency. If dependencyCount is zero, each dependency’s view offset is treated as zero. Each view offset controls which views in the source subpass the views in the destination subpass depend on.

  • correlationMaskCount is zero or the number of correlation masks.

  • pCorrelationMasks is a pointer to an array of correlationMaskCount view masks indicating sets of views that may be more efficient to render concurrently.

When a subpass uses a non-zero view mask, multiview functionality is considered to be enabled. Multiview is all-or-nothing for a render pass - that is, either all subpasses must have a non-zero view mask (though some subpasses may have only one view) or all must be zero. Multiview causes all drawing and clear commands in the subpass to behave as if they were broadcast to each view, where a view is represented by one layer of the framebuffer attachments. All draws and clears are broadcast to each view index whose bit is set in the view mask. The view index is provided in the ViewIndex shader input variable, and color, depth/stencil, and input attachments all read/write the layer of the framebuffer corresponding to the view index.

If the view mask is zero for all subpasses, multiview is considered to be disabled and all drawing commands execute normally, without this additional broadcasting.

Some implementations may not support multiview in conjunction with mesh shaders, geometry shaders or tessellation shaders.

When multiview is enabled, the VK_DEPENDENCY_VIEW_LOCAL_BIT bit in a dependency can be used to express a view-local dependency, meaning that each view in the destination subpass depends on a single view in the source subpass. Unlike pipeline barriers, a subpass dependency can potentially have a different view mask in the source subpass and the destination subpass. If the dependency is view-local, then each view (dstView) in the destination subpass depends on the view dstView + pViewOffsets[dependency] in the source subpass. If there is not such a view in the source subpass, then this dependency does not affect that view in the destination subpass. If the dependency is not view-local, then all views in the destination subpass depend on all views in the source subpass, and the view offset is ignored. A non-zero view offset is not allowed in a self-dependency.

The elements of pCorrelationMasks are a set of masks of views indicating that views in the same mask may exhibit spatial coherency between the views, making it more efficient to render them concurrently. Correlation masks must not have a functional effect on the results of the multiview rendering.

When multiview is enabled, at the beginning of each subpass all non-render pass state is undefined. In particular, each time vkCmdBeginRenderPass or vkCmdNextSubpass is called the graphics pipeline must be bound, any relevant descriptor sets or vertex/index buffers must be bound, and any relevant dynamic state or push constants must be set before they are used.

A multiview subpass can declare that its shaders will write per-view attributes for all views in a single invocation, by setting the VK_SUBPASS_DESCRIPTION_PER_VIEW_ATTRIBUTES_BIT_NVX bit in the subpass description. The only supported per-view attributes are position and viewport mask, and per-view position and viewport masks are written to output array variables decorated with PositionPerViewNV and ViewportMaskPerViewNV, respectively. If VK_NV_viewport_array2 is not supported and enabled, ViewportMaskPerViewNV must not be used. Values written to elements of PositionPerViewNV and ViewportMaskPerViewNV must not depend on the ViewIndex. The shader must also write to an output variable decorated with Position, and the value written to Position must equal the value written to PositionPerViewNV[ViewIndex]. Similarly, if ViewportMaskPerViewNV is written to then the shader must also write to an output variable decorated with ViewportMaskNV, and the value written to ViewportMaskNV must equal the value written to ViewportMaskPerViewNV[ViewIndex]. Implementations will either use values taken from Position and ViewportMaskNV and invoke the shader once for each view, or will use values taken from PositionPerViewNV and ViewportMaskPerViewNV and invoke the shader fewer times. The values written to Position and ViewportMaskNV must not depend on the values written to PositionPerViewNV and ViewportMaskPerViewNV, or vice versa (to allow compilers to eliminate the unused outputs). All attributes that do not have *PerViewNV counterparts must not depend on ViewIndex.

Per-view attributes are all-or-nothing for a subpass. That is, all pipelines compiled against a subpass that includes the VK_SUBPASS_DESCRIPTION_PER_VIEW_ATTRIBUTES_BIT_NVX bit must write per-view attributes to the *PerViewNV[] shader outputs, in addition to the non-per-view (e.g. Position) outputs. Pipelines compiled against a subpass that does not include this bit must not include the *PerViewNV[] outputs in their interfaces.

Valid Usage

  • VUID-VkRenderPassMultiviewCreateInfo-pCorrelationMasks-00841
    Each view index must not be set in more than one element of pCorrelationMasks

  • VUID-VkRenderPassMultiviewCreateInfo-multiview-06555
    If the multiview feature is not enabled, each element of pViewMasks must be 0

  • VUID-VkRenderPassMultiviewCreateInfo-pViewMasks-06697
    The index of the most significant bit in each element of pViewMasks must be less than maxMultiviewViewCount

Valid Usage (Implicit)

  • VUID-VkRenderPassMultiviewCreateInfo-sType-sType
    sType must be VK_STRUCTURE_TYPE_RENDER_PASS_MULTIVIEW_CREATE_INFO

  • VUID-VkRenderPassMultiviewCreateInfo-pViewMasks-parameter
    If subpassCount is not 0, pViewMasks must be a valid pointer to an array of subpassCount uint32_t values

  • VUID-VkRenderPassMultiviewCreateInfo-pViewOffsets-parameter
    If dependencyCount is not 0, pViewOffsets must be a valid pointer to an array of dependencyCount int32_t values

  • VUID-VkRenderPassMultiviewCreateInfo-pCorrelationMasks-parameter
    If correlationMaskCount is not 0, pCorrelationMasks must be a valid pointer to an array of correlationMaskCount uint32_t values

The VkMultiviewPerViewAttributesInfoNVX structure is defined as:

// Provided by VK_KHR_dynamic_rendering with VK_NVX_multiview_per_view_attributes
typedef struct VkMultiviewPerViewAttributesInfoNVX {
    VkStructureType    sType;
    const void*        pNext;
    VkBool32           perViewAttributes;
    VkBool32           perViewAttributesPositionXOnly;
} VkMultiviewPerViewAttributesInfoNVX;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • perViewAttributes specifies that shaders compiled for this pipeline write the attributes for all views in a single invocation of each vertex processing stage. All pipelines executed within a render pass instance that includes this bit must write per-view attributes to the *PerViewNV[] shader outputs, in addition to the non-per-view (e.g. Position) outputs.

  • perViewAttributesPositionXOnly specifies that shaders compiled for this pipeline use per-view positions which only differ in value in the x component. Per-view viewport mask can also be used.

When dynamic render pass instances are being used, instead of specifying VK_SUBPASS_DESCRIPTION_PER_VIEW_ATTRIBUTES_BIT_NVX or VK_SUBPASS_DESCRIPTION_PER_VIEW_POSITION_X_ONLY_BIT_NVX in the subpass description flags, the per-attribute properties of the render pass instance must be specified by the VkMultiviewPerViewAttributesInfoNVX structure Include the VkMultiviewPerViewAttributesInfoNVX structure in the pNext chain of VkGraphicsPipelineCreateInfo when creating a graphics pipeline for dynamic rendering, VkRenderingInfo when starting a dynamic render pass instance, and VkCommandBufferInheritanceInfo when specifying the dynamic render pass instance parameters for secondary command buffers.

Valid Usage (Implicit)

  • VUID-VkMultiviewPerViewAttributesInfoNVX-sType-sType
    sType must be VK_STRUCTURE_TYPE_MULTIVIEW_PER_VIEW_ATTRIBUTES_INFO_NVX

If the VkRenderPassCreateInfo::pNext chain includes a VkRenderPassFragmentDensityMapCreateInfoEXT structure, then that structure includes a fragment density map attachment for the render pass.

The VkRenderPassFragmentDensityMapCreateInfoEXT structure is defined as:

// Provided by VK_EXT_fragment_density_map
typedef struct VkRenderPassFragmentDensityMapCreateInfoEXT {
    VkStructureType          sType;
    const void*              pNext;
    VkAttachmentReference    fragmentDensityMapAttachment;
} VkRenderPassFragmentDensityMapCreateInfoEXT;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • fragmentDensityMapAttachment is the fragment density map to use for the render pass.

The fragment density map is read at an implementation-dependent time with the following constraints determined by the attachment’s image view flags:

  • VK_IMAGE_VIEW_CREATE_FRAGMENT_DENSITY_MAP_DYNAMIC_BIT_EXT specifies that the fragment density map will be read by the device during VK_PIPELINE_STAGE_FRAGMENT_DENSITY_PROCESS_BIT_EXT

  • VK_IMAGE_VIEW_CREATE_FRAGMENT_DENSITY_MAP_DEFERRED_BIT_EXT specifies that the fragment density map will be read by the host during vkEndCommandBuffer of the primary command buffer that the render pass is recorded into

  • Otherwise the fragment density map will be read by the host during vkCmdBeginRenderPass

The fragment density map may additionally be read by the device during VK_PIPELINE_STAGE_FRAGMENT_DENSITY_PROCESS_BIT_EXT for any mode.

If this structure is not present, it is as if fragmentDensityMapAttachment was given as VK_ATTACHMENT_UNUSED.

Valid Usage

  • VUID-VkRenderPassFragmentDensityMapCreateInfoEXT-fragmentDensityMapAttachment-02548
    If fragmentDensityMapAttachment is not VK_ATTACHMENT_UNUSED, fragmentDensityMapAttachment must not be an element of VkSubpassDescription::pInputAttachments, VkSubpassDescription::pColorAttachments, VkSubpassDescription::pResolveAttachments, VkSubpassDescription::pDepthStencilAttachment, or VkSubpassDescription::pPreserveAttachments for any subpass

  • VUID-VkRenderPassFragmentDensityMapCreateInfoEXT-fragmentDensityMapAttachment-02549
    If fragmentDensityMapAttachment is not VK_ATTACHMENT_UNUSED, layout must be equal to VK_IMAGE_LAYOUT_FRAGMENT_DENSITY_MAP_OPTIMAL_EXT, or VK_IMAGE_LAYOUT_GENERAL

  • VUID-VkRenderPassFragmentDensityMapCreateInfoEXT-fragmentDensityMapAttachment-02550
    If fragmentDensityMapAttachment is not VK_ATTACHMENT_UNUSED, fragmentDensityMapAttachment must reference an attachment with a loadOp equal to VK_ATTACHMENT_LOAD_OP_LOAD or VK_ATTACHMENT_LOAD_OP_DONT_CARE

  • VUID-VkRenderPassFragmentDensityMapCreateInfoEXT-fragmentDensityMapAttachment-02551
    If fragmentDensityMapAttachment is not VK_ATTACHMENT_UNUSED, fragmentDensityMapAttachment must reference an attachment with a storeOp equal to VK_ATTACHMENT_STORE_OP_DONT_CARE

Valid Usage (Implicit)

  • VUID-VkRenderPassFragmentDensityMapCreateInfoEXT-sType-sType
    sType must be VK_STRUCTURE_TYPE_RENDER_PASS_FRAGMENT_DENSITY_MAP_CREATE_INFO_EXT

  • VUID-VkRenderPassFragmentDensityMapCreateInfoEXT-fragmentDensityMapAttachment-parameter
    fragmentDensityMapAttachment must be a valid VkAttachmentReference structure

The VkAttachmentDescription structure is defined as:

// Provided by VK_VERSION_1_0
typedef struct VkAttachmentDescription {
    VkAttachmentDescriptionFlags    flags;
    VkFormat                        format;
    VkSampleCountFlagBits           samples;
    VkAttachmentLoadOp              loadOp;
    VkAttachmentStoreOp             storeOp;
    VkAttachmentLoadOp              stencilLoadOp;
    VkAttachmentStoreOp             stencilStoreOp;
    VkImageLayout                   initialLayout;
    VkImageLayout                   finalLayout;
} VkAttachmentDescription;

  • flags is a bitmask of VkAttachmentDescriptionFlagBits specifying additional properties of the attachment.

  • format is a VkFormat value specifying the format of the image view that will be used for the attachment.

  • samples is a VkSampleCountFlagBits value specifying the number of samples of the image.

  • loadOp is a VkAttachmentLoadOp value specifying how the contents of color and depth components of the attachment are treated at the beginning of the subpass where it is first used.

  • storeOp is a VkAttachmentStoreOp value specifying how the contents of color and depth components of the attachment are treated at the end of the subpass where it is last used.

  • stencilLoadOp is a VkAttachmentLoadOp value specifying how the contents of stencil components of the attachment are treated at the beginning of the subpass where it is first used.

  • stencilStoreOp is a VkAttachmentStoreOp value specifying how the contents of stencil components of the attachment are treated at the end of the last subpass where it is used.

  • initialLayout is the layout the attachment image subresource will be in when a render pass instance begins.

  • finalLayout is the layout the attachment image subresource will be transitioned to when a render pass instance ends.

If the attachment uses a color format, then loadOp and storeOp are used, and stencilLoadOp and stencilStoreOp are ignored. If the format has depth and/or stencil components, loadOp and storeOp apply only to the depth data, while stencilLoadOp and stencilStoreOp define how the stencil data is handled. loadOp and stencilLoadOp define the load operations for the attachment. storeOp and stencilStoreOp define the store operations for the attachment. If an attachment is not used by any subpass, loadOp, storeOp, stencilStoreOp, and stencilLoadOp will be ignored for that attachment, and no load or store ops will be performed. However, any transition specified by initialLayout and finalLayout will still be executed.

If flags includes VK_ATTACHMENT_DESCRIPTION_MAY_ALIAS_BIT, then the attachment is treated as if it shares physical memory with another attachment in the same render pass. This information limits the ability of the implementation to reorder certain operations (like layout transitions and the loadOp) such that it is not improperly reordered against other uses of the same physical memory via a different attachment. This is described in more detail below.

If a render pass uses multiple attachments that alias the same device memory, those attachments must each include the VK_ATTACHMENT_DESCRIPTION_MAY_ALIAS_BIT bit in their attachment description flags. Attachments aliasing the same memory occurs in multiple ways:

  • Multiple attachments being assigned the same image view as part of framebuffer creation.

  • Attachments using distinct image views that correspond to the same image subresource of an image.

  • Attachments using views of distinct image subresources which are bound to overlapping memory ranges.

Note

Render passes must include subpass dependencies (either directly or via a subpass dependency chain) between any two subpasses that operate on the same attachment or aliasing attachments and those subpass dependencies must include execution and memory dependencies separating uses of the aliases, if at least one of those subpasses writes to one of the aliases. These dependencies must not include the VK_DEPENDENCY_BY_REGION_BIT if the aliases are views of distinct image subresources which overlap in memory.

Multiple attachments that alias the same memory must not be used in a single subpass. A given attachment index must not be used multiple times in a single subpass, with one exception: two subpass attachments can use the same attachment index if at least one use is as an input attachment and neither use is as a resolve or preserve attachment. In other words, the same view can be used simultaneously as an input and color or depth/stencil attachment, but must not be used as multiple color or depth/stencil attachments nor as resolve or preserve attachments.

If a set of attachments alias each other, then all except the first to be used in the render pass must use an initialLayout of VK_IMAGE_LAYOUT_UNDEFINED, since the earlier uses of the other aliases make their contents undefined. Once an alias has been used and a different alias has been used after it, the first alias must not be used in any later subpasses. However, an application can assign the same image view to multiple aliasing attachment indices, which allows that image view to be used multiple times even if other aliases are used in between.

Note

Once an attachment needs the VK_ATTACHMENT_DESCRIPTION_MAY_ALIAS_BIT bit, there should be no additional cost of introducing additional aliases, and using these additional aliases may allow more efficient clearing of the attachments on multiple uses via VK_ATTACHMENT_LOAD_OP_CLEAR.
Valid Usage

  • VUID-VkAttachmentDescription-format-06699
    If format includes a color or depth component and loadOp is VK_ATTACHMENT_LOAD_OP_LOAD, then initialLayout must not be VK_IMAGE_LAYOUT_UNDEFINED

  • VUID-VkAttachmentDescription-finalLayout-00843
    finalLayout must not be VK_IMAGE_LAYOUT_UNDEFINED or VK_IMAGE_LAYOUT_PREINITIALIZED

  • VUID-VkAttachmentDescription-format-03280
    If format is a color format, initialLayout must not be VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL or VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL

  • VUID-VkAttachmentDescription-format-03281
    If format is a depth/stencil format, initialLayout must not be VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL

  • VUID-VkAttachmentDescription-format-03282
    If format is a color format, finalLayout must not be VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL or VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL

  • VUID-VkAttachmentDescription-format-03283
    If format is a depth/stencil format, finalLayout must not be VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL

  • VUID-VkAttachmentDescription-format-06487
    If format is a color format, initialLayout must not be VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL or VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL

  • VUID-VkAttachmentDescription-format-06488
    If format is a color format, finalLayout must not be VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL or VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL

  • VUID-VkAttachmentDescription-separateDepthStencilLayouts-03284
    If the separateDepthStencilLayouts feature is not enabled, initialLayout must not be VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL, VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL, or VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL,

  • VUID-VkAttachmentDescription-separateDepthStencilLayouts-03285
    If the separateDepthStencilLayouts feature is not enabled, finalLayout must not be VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL, VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL, or VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL,

  • VUID-VkAttachmentDescription-format-03286
    If format is a color format, initialLayout must not be VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL, VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL, or VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL

  • VUID-VkAttachmentDescription-format-03287
    If format is a color format, finalLayout must not be VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL, VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL, or VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL

  • VUID-VkAttachmentDescription-format-06906
    If format is a depth/stencil format which includes both depth and stencil components, initialLayout must not be VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL or VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL

  • VUID-VkAttachmentDescription-format-06907
    If format is a depth/stencil format which includes both depth and stencil components, finalLayout must not be VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL or VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL

  • VUID-VkAttachmentDescription-format-03290
    If format is a depth/stencil format which includes only the depth component, initialLayout must not be VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL or VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL

  • VUID-VkAttachmentDescription-format-03291
    If format is a depth/stencil format which includes only the depth component, finalLayout must not be VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL or VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL

  • VUID-VkAttachmentDescription-synchronization2-06908
    If the synchronization2 feature is not enabled, initialLayout must not be VK_IMAGE_LAYOUT_ATTACHMENT_OPTIMAL_KHR or VK_IMAGE_LAYOUT_READ_ONLY_OPTIMAL_KHR

  • VUID-VkAttachmentDescription-synchronization2-06909
    If the synchronization2 feature is not enabled, finalLayout must not be VK_IMAGE_LAYOUT_ATTACHMENT_OPTIMAL_KHR or VK_IMAGE_LAYOUT_READ_ONLY_OPTIMAL_KHR

  • VUID-VkAttachmentDescription-attachmentFeedbackLoopLayout-07309
    If the attachmentFeedbackLoopLayout feature is not enabled, initialLayout must not be VK_IMAGE_LAYOUT_ATTACHMENT_FEEDBACK_LOOP_OPTIMAL_EXT

  • VUID-VkAttachmentDescription-attachmentFeedbackLoopLayout-07310
    If the attachmentFeedbackLoopLayout feature is not enabled, finalLayout must not be VK_IMAGE_LAYOUT_ATTACHMENT_FEEDBACK_LOOP_OPTIMAL_EXT

  • VUID-VkAttachmentDescription-samples-08745
    samples must be a valid VkSampleCountFlagBits value that is set in imageCreateSampleCounts (as defined in Image Creation Limits) for the given format

  • VUID-VkAttachmentDescription-dynamicRenderingLocalRead-09544
    If the dynamicRenderingLocalRead feature is not enabled, initialLayout must not be VK_IMAGE_LAYOUT_RENDERING_LOCAL_READ_KHR

  • VUID-VkAttachmentDescription-dynamicRenderingLocalRead-09545
    If the dynamicRenderingLocalRead feature is not enabled, finalLayout must not be VK_IMAGE_LAYOUT_RENDERING_LOCAL_READ_KHR

  • VUID-VkAttachmentDescription-format-06698
    format must not be VK_FORMAT_UNDEFINED

  • VUID-VkAttachmentDescription-format-06700
    If format includes a stencil component and stencilLoadOp is VK_ATTACHMENT_LOAD_OP_LOAD, then initialLayout must not be VK_IMAGE_LAYOUT_UNDEFINED

  • VUID-VkAttachmentDescription-format-03292
    If format is a depth/stencil format which includes only the stencil component, initialLayout must not be VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL or VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL

  • VUID-VkAttachmentDescription-format-03293
    If format is a depth/stencil format which includes only the stencil component, finalLayout must not be VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL or VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL

  • VUID-VkAttachmentDescription-format-06242
    If format is a depth/stencil format which includes both depth and stencil components, initialLayout must not be VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL or VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL

  • VUID-VkAttachmentDescription-format-06243
    If format is a depth/stencil format which includes both depth and stencil components, finalLayout must not be VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL or VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL

Valid Usage (Implicit)

  • VUID-VkAttachmentDescription-flags-parameter
    flags must be a valid combination of VkAttachmentDescriptionFlagBits values

  • VUID-VkAttachmentDescription-format-parameter
    format must be a valid VkFormat value

  • VUID-VkAttachmentDescription-samples-parameter
    samples must be a valid VkSampleCountFlagBits value

  • VUID-VkAttachmentDescription-loadOp-parameter
    loadOp must be a valid VkAttachmentLoadOp value

  • VUID-VkAttachmentDescription-storeOp-parameter
    storeOp must be a valid VkAttachmentStoreOp value

  • VUID-VkAttachmentDescription-stencilLoadOp-parameter
    stencilLoadOp must be a valid VkAttachmentLoadOp value

  • VUID-VkAttachmentDescription-stencilStoreOp-parameter
    stencilStoreOp must be a valid VkAttachmentStoreOp value

  • VUID-VkAttachmentDescription-initialLayout-parameter
    initialLayout must be a valid VkImageLayout value

  • VUID-VkAttachmentDescription-finalLayout-parameter
    finalLayout must be a valid VkImageLayout value

Bits which can be set in VkAttachmentDescription::flags, describing additional properties of the attachment, are:

// Provided by VK_VERSION_1_0
typedef enum VkAttachmentDescriptionFlagBits {
    VK_ATTACHMENT_DESCRIPTION_MAY_ALIAS_BIT = 0x00000001,
} VkAttachmentDescriptionFlagBits;

  • VK_ATTACHMENT_DESCRIPTION_MAY_ALIAS_BIT specifies that the attachment aliases the same device memory as other attachments.

// Provided by VK_VERSION_1_0
typedef VkFlags VkAttachmentDescriptionFlags;

VkAttachmentDescriptionFlags is a bitmask type for setting a mask of zero or more VkAttachmentDescriptionFlagBits.

The VkRenderPassInputAttachmentAspectCreateInfo structure is defined as:

// Provided by VK_VERSION_1_1
typedef struct VkRenderPassInputAttachmentAspectCreateInfo {
    VkStructureType                            sType;
    const void*                                pNext;
    uint32_t                                   aspectReferenceCount;
    const VkInputAttachmentAspectReference*    pAspectReferences;
} VkRenderPassInputAttachmentAspectCreateInfo;

or the equivalent

// Provided by VK_KHR_maintenance2
typedef VkRenderPassInputAttachmentAspectCreateInfo VkRenderPassInputAttachmentAspectCreateInfoKHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • aspectReferenceCount is the number of elements in the pAspectReferences array.

  • pAspectReferences is a pointer to an array of aspectReferenceCount VkInputAttachmentAspectReference structures containing a mask describing which aspect(s) can be accessed for a given input attachment within a given subpass.

To specify which aspects of an input attachment can be read, add a VkRenderPassInputAttachmentAspectCreateInfo structure to the pNext chain of the VkRenderPassCreateInfo structure:

An application can access any aspect of an input attachment that does not have a specified aspect mask in the pAspectReferences array. Otherwise, an application must not access aspect(s) of an input attachment other than those in its specified aspect mask.

Valid Usage (Implicit)

  • VUID-VkRenderPassInputAttachmentAspectCreateInfo-sType-sType
    sType must be VK_STRUCTURE_TYPE_RENDER_PASS_INPUT_ATTACHMENT_ASPECT_CREATE_INFO

  • VUID-VkRenderPassInputAttachmentAspectCreateInfo-pAspectReferences-parameter
    pAspectReferences must be a valid pointer to an array of aspectReferenceCount valid VkInputAttachmentAspectReference structures

  • VUID-VkRenderPassInputAttachmentAspectCreateInfo-aspectReferenceCount-arraylength
    aspectReferenceCount must be greater than 0

The VkInputAttachmentAspectReference structure is defined as:

// Provided by VK_VERSION_1_1
typedef struct VkInputAttachmentAspectReference {
    uint32_t              subpass;
    uint32_t              inputAttachmentIndex;
    VkImageAspectFlags    aspectMask;
} VkInputAttachmentAspectReference;

or the equivalent

// Provided by VK_KHR_maintenance2
typedef VkInputAttachmentAspectReference VkInputAttachmentAspectReferenceKHR;

  • subpass is an index into the pSubpasses array of the parent VkRenderPassCreateInfo structure.

  • inputAttachmentIndex is an index into the pInputAttachments of the specified subpass.

  • aspectMask is a mask of which aspect(s) can be accessed within the specified subpass.

This structure specifies an aspect mask for a specific input attachment of a specific subpass in the render pass.

subpass and inputAttachmentIndex index into the render pass as:

pCreateInfo->pSubpasses[subpass].pInputAttachments[inputAttachmentIndex]
Valid Usage

  • VUID-VkInputAttachmentAspectReference-aspectMask-01964
    aspectMask must not include VK_IMAGE_ASPECT_METADATA_BIT

  • VUID-VkInputAttachmentAspectReference-aspectMask-02250
    aspectMask must not include VK_IMAGE_ASPECT_MEMORY_PLANE_i_BIT_EXT for any index i

Valid Usage (Implicit)

  • VUID-VkInputAttachmentAspectReference-aspectMask-parameter
    aspectMask must be a valid combination of VkImageAspectFlagBits values

  • VUID-VkInputAttachmentAspectReference-aspectMask-requiredbitmask
    aspectMask must not be 0

The VkSubpassDescription structure is defined as:

// Provided by VK_VERSION_1_0
typedef struct VkSubpassDescription {
    VkSubpassDescriptionFlags       flags;
    VkPipelineBindPoint             pipelineBindPoint;
    uint32_t                        inputAttachmentCount;
    const VkAttachmentReference*    pInputAttachments;
    uint32_t                        colorAttachmentCount;
    const VkAttachmentReference*    pColorAttachments;
    const VkAttachmentReference*    pResolveAttachments;
    const VkAttachmentReference*    pDepthStencilAttachment;
    uint32_t                        preserveAttachmentCount;
    const uint32_t*                 pPreserveAttachments;
} VkSubpassDescription;

  • flags is a bitmask of VkSubpassDescriptionFlagBits specifying usage of the subpass.

  • pipelineBindPoint is a VkPipelineBindPoint value specifying the pipeline type supported for this subpass.

  • inputAttachmentCount is the number of input attachments.

  • pInputAttachments is a pointer to an array of VkAttachmentReference structures defining the input attachments for this subpass and their layouts.

  • colorAttachmentCount is the number of color attachments.

  • pColorAttachments is a pointer to an array of colorAttachmentCount VkAttachmentReference structures defining the color attachments for this subpass and their layouts.

  • pResolveAttachments is NULL or a pointer to an array of colorAttachmentCount VkAttachmentReference structures defining the resolve attachments for this subpass and their layouts.

  • pDepthStencilAttachment is a pointer to a VkAttachmentReference structure specifying the depth/stencil attachment for this subpass and its layout.

  • preserveAttachmentCount is the number of preserved attachments.

  • pPreserveAttachments is a pointer to an array of preserveAttachmentCount render pass attachment indices identifying attachments that are not used by this subpass, but whose contents must be preserved throughout the subpass.

Each element of the pInputAttachments array corresponds to an input attachment index in a fragment shader, i.e. if a shader declares an image variable decorated with a InputAttachmentIndex value of X, then it uses the attachment provided in pInputAttachments[X]. Input attachments must also be bound to the pipeline in a descriptor set. If the attachment member of any element of pInputAttachments is VK_ATTACHMENT_UNUSED, the application must not read from the corresponding input attachment index. Fragment shaders can use subpass input variables to access the contents of an input attachment at the fragment’s (x, y, layer) framebuffer coordinates. Input attachments must not be used by any subpasses within a render pass that enables render pass transform.

Each element of the pColorAttachments array corresponds to an output location in the shader, i.e. if the shader declares an output variable decorated with a Location value of X, then it uses the attachment provided in pColorAttachments[X]. If the attachment member of any element of pColorAttachments is VK_ATTACHMENT_UNUSED, or if Color Write Enable has been disabled for the corresponding attachment index, then writes to the corresponding location by a fragment shader are discarded.

If flags does not include VK_SUBPASS_DESCRIPTION_SHADER_RESOLVE_BIT_QCOM, and if pResolveAttachments is not NULL, each of its elements corresponds to a color attachment (the element in pColorAttachments at the same index), and a multisample resolve operation is defined for each attachment unless the resolve attachment index is VK_ATTACHMENT_UNUSED.

Similarly, if flags does not include VK_SUBPASS_DESCRIPTION_SHADER_RESOLVE_BIT_QCOM, and VkSubpassDescriptionDepthStencilResolve::pDepthStencilResolveAttachment is not NULL and does not have the value VK_ATTACHMENT_UNUSED, it corresponds to the depth/stencil attachment in pDepthStencilAttachment, and multisample resolve operation for depth and stencil are defined by VkSubpassDescriptionDepthStencilResolve::depthResolveMode and VkSubpassDescriptionDepthStencilResolve::stencilResolveMode, respectively. If VkSubpassDescriptionDepthStencilResolve::depthResolveMode is VK_RESOLVE_MODE_NONE or the pDepthStencilResolveAttachment does not have a depth aspect, no resolve operation is performed for the depth attachment. If VkSubpassDescriptionDepthStencilResolve::stencilResolveMode is VK_RESOLVE_MODE_NONE or the pDepthStencilResolveAttachment does not have a stencil aspect, no resolve operation is performed for the stencil attachment.

If the image subresource range referenced by the depth/stencil attachment is created with VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT, then the multisample resolve operation uses the sample locations state specified in the sampleLocationsInfo member of the element of the VkRenderPassSampleLocationsBeginInfoEXT::pPostSubpassSampleLocations for the subpass.

If pDepthStencilAttachment is NULL, or if its attachment index is VK_ATTACHMENT_UNUSED, it indicates that no depth/stencil attachment will be used in the subpass.

The contents of an attachment within the render area become undefined at the start of a subpass S if all of the following conditions are true:

  • The attachment is used as a color, depth/stencil, or resolve attachment in any subpass in the render pass.

  • There is a subpass S1 that uses or preserves the attachment, and a subpass dependency from S1 to S.

  • The attachment is not used or preserved in subpass S.

In addition, the contents of an attachment within the render area become undefined at the start of a subpass S if all of the following conditions are true:

  • VK_SUBPASS_DESCRIPTION_SHADER_RESOLVE_BIT_QCOM is set.

  • The attachment is used as a color or depth/stencil in the subpass.

Once the contents of an attachment become undefined in subpass S, they remain undefined for subpasses in subpass dependency chains starting with subpass S until they are written again. However, they remain valid for subpasses in other subpass dependency chains starting with subpass S1 if those subpasses use or preserve the attachment.

Valid Usage

  • VUID-VkSubpassDescription-attachment-06912
    If the attachment member of an element of pInputAttachments is not VK_ATTACHMENT_UNUSED, its layout member must not be VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL or VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL

  • VUID-VkSubpassDescription-attachment-06913
    If the attachment member of an element of pColorAttachments is not VK_ATTACHMENT_UNUSED, its layout member must not be VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL or VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL

  • VUID-VkSubpassDescription-attachment-06914
    If the attachment member of an element of pResolveAttachments is not VK_ATTACHMENT_UNUSED, its layout member must not be VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL or VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL

  • VUID-VkSubpassDescription-attachment-06915
    If the attachment member of pDepthStencilAttachment is not VK_ATTACHMENT_UNUSED, ts layout member must not be VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL or VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL

  • VUID-VkSubpassDescription-attachment-06916
    If the attachment member of an element of pColorAttachments is not VK_ATTACHMENT_UNUSED, its layout member must not be VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL or VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL

  • VUID-VkSubpassDescription-attachment-06917
    If the attachment member of an element of pResolveAttachments is not VK_ATTACHMENT_UNUSED, its layout member must not be VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL or VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL

  • VUID-VkSubpassDescription-attachment-06918
    If the attachment member of an element of pInputAttachments is not VK_ATTACHMENT_UNUSED, its layout member must not be VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL or VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL

  • VUID-VkSubpassDescription-attachment-06919
    If the attachment member of an element of pColorAttachments is not VK_ATTACHMENT_UNUSED, its layout member must not be VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL, VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL, or VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL

  • VUID-VkSubpassDescription-attachment-06920
    If the attachment member of an element of pResolveAttachments is not VK_ATTACHMENT_UNUSED, its layout member must not be VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL, VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL, or VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL

  • VUID-VkSubpassDescription-attachment-06921
    If the attachment member of an element of pInputAttachments is not VK_ATTACHMENT_UNUSED, its layout member must not be VK_IMAGE_LAYOUT_ATTACHMENT_OPTIMAL_KHR

  • VUID-VkSubpassDescription-attachment-06922
    If the attachment member of an element of pColorAttachments is not VK_ATTACHMENT_UNUSED, its layout member must not be VK_IMAGE_LAYOUT_READ_ONLY_OPTIMAL_KHR

  • VUID-VkSubpassDescription-attachment-06923
    If the attachment member of an element of pResolveAttachments is not VK_ATTACHMENT_UNUSED, its layout member must not be VK_IMAGE_LAYOUT_READ_ONLY_OPTIMAL_KHR

  • VUID-VkSubpassDescription-pipelineBindPoint-04952
    pipelineBindPoint must be VK_PIPELINE_BIND_POINT_GRAPHICS or VK_PIPELINE_BIND_POINT_SUBPASS_SHADING_HUAWEI

  • VUID-VkSubpassDescription-colorAttachmentCount-00845
    colorAttachmentCount must be less than or equal to VkPhysicalDeviceLimits::maxColorAttachments

  • VUID-VkSubpassDescription-loadOp-00846
    If the first use of an attachment in this render pass is as an input attachment, and the attachment is not also used as a color or depth/stencil attachment in the same subpass, then loadOp must not be VK_ATTACHMENT_LOAD_OP_CLEAR

  • VUID-VkSubpassDescription-pResolveAttachments-00847
    If pResolveAttachments is not NULL, for each resolve attachment that is not VK_ATTACHMENT_UNUSED, the corresponding color attachment must not be VK_ATTACHMENT_UNUSED

  • VUID-VkSubpassDescription-pResolveAttachments-00848
    If pResolveAttachments is not NULL, for each resolve attachment that is not VK_ATTACHMENT_UNUSED, the corresponding color attachment must not have a sample count of VK_SAMPLE_COUNT_1_BIT

  • VUID-VkSubpassDescription-pResolveAttachments-00849
    If pResolveAttachments is not NULL, each resolve attachment that is not VK_ATTACHMENT_UNUSED must have a sample count of VK_SAMPLE_COUNT_1_BIT

  • VUID-VkSubpassDescription-pResolveAttachments-00850
    If pResolveAttachments is not NULL, each resolve attachment that is not VK_ATTACHMENT_UNUSED must have the same VkFormat as its corresponding color attachment

  • VUID-VkSubpassDescription-pColorAttachments-09430
    All attachments in pColorAttachments that are not VK_ATTACHMENT_UNUSED must have the same sample count

  • VUID-VkSubpassDescription-pInputAttachments-02647
    All attachments in pInputAttachments that are not VK_ATTACHMENT_UNUSED must have image formats whose potential format features contain at least VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT or VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT

  • VUID-VkSubpassDescription-pColorAttachments-02648
    All attachments in pColorAttachments that are not VK_ATTACHMENT_UNUSED must have image formats whose potential format features contain VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT

  • VUID-VkSubpassDescription-pResolveAttachments-02649
    All attachments in pResolveAttachments that are not VK_ATTACHMENT_UNUSED must have image formats whose potential format features contain VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT

  • VUID-VkSubpassDescription-pDepthStencilAttachment-02650
    If pDepthStencilAttachment is not NULL and the attachment is not VK_ATTACHMENT_UNUSED then it must have an image format whose potential format features contain VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT

  • VUID-VkSubpassDescription-linearColorAttachment-06496
    If the linearColorAttachment feature is enabled and the image is created with VK_IMAGE_TILING_LINEAR, all attachments in pInputAttachments that are not VK_ATTACHMENT_UNUSED must have image formats whose potential format features must contain VK_FORMAT_FEATURE_2_LINEAR_COLOR_ATTACHMENT_BIT_NV

  • VUID-VkSubpassDescription-linearColorAttachment-06497
    If the linearColorAttachment feature is enabled and the image is created with VK_IMAGE_TILING_LINEAR, all attachments in pColorAttachments that are not VK_ATTACHMENT_UNUSED must have image formats whose potential format features must contain VK_FORMAT_FEATURE_2_LINEAR_COLOR_ATTACHMENT_BIT_NV

  • VUID-VkSubpassDescription-linearColorAttachment-06498
    If the linearColorAttachment feature is enabled and the image is created with VK_IMAGE_TILING_LINEAR, all attachments in pResolveAttachments that are not VK_ATTACHMENT_UNUSED must have image formats whose potential format features must contain VK_FORMAT_FEATURE_2_LINEAR_COLOR_ATTACHMENT_BIT_NV

  • VUID-VkSubpassDescription-None-09431
    If either of the following is enabled:

    all attachments in pColorAttachments that are not VK_ATTACHMENT_UNUSED must have a sample count that is smaller than or equal to the sample count of pDepthStencilAttachment if it is not VK_ATTACHMENT_UNUSED

  • VUID-VkSubpassDescription-pDepthStencilAttachment-01418
    If pDepthStencilAttachment is not VK_ATTACHMENT_UNUSED and any attachments in pColorAttachments are not VK_ATTACHMENT_UNUSED, they must have the same sample count , if none of the following are enabled:

  • VUID-VkSubpassDescription-attachment-00853
    Each element of pPreserveAttachments must not be VK_ATTACHMENT_UNUSED

  • VUID-VkSubpassDescription-pPreserveAttachments-00854
    Each element of pPreserveAttachments must not also be an element of any other member of the subpass description

  • VUID-VkSubpassDescription-layout-02519
    If any attachment is used by more than one VkAttachmentReference member, then each use must use the same layout

  • VUID-VkSubpassDescription-flags-00856
    If flags includes VK_SUBPASS_DESCRIPTION_PER_VIEW_POSITION_X_ONLY_BIT_NVX, it must also include VK_SUBPASS_DESCRIPTION_PER_VIEW_ATTRIBUTES_BIT_NVX

  • VUID-VkSubpassDescription-flags-03341
    If flags includes VK_SUBPASS_DESCRIPTION_SHADER_RESOLVE_BIT_QCOM, and if pResolveAttachments is not NULL, then each resolve attachment must be VK_ATTACHMENT_UNUSED

  • VUID-VkSubpassDescription-flags-03343
    If flags includes VK_SUBPASS_DESCRIPTION_SHADER_RESOLVE_BIT_QCOM, then the subpass must be the last subpass in a subpass dependency chain

  • VUID-VkSubpassDescription-pInputAttachments-02868
    If the render pass is created with VK_RENDER_PASS_CREATE_TRANSFORM_BIT_QCOM each of the elements of pInputAttachments must be VK_ATTACHMENT_UNUSED

  • VUID-VkSubpassDescription-pDepthStencilAttachment-04438
    pDepthStencilAttachment and pColorAttachments must not contain references to the same attachment

Valid Usage (Implicit)

  • VUID-VkSubpassDescription-flags-parameter
    flags must be a valid combination of VkSubpassDescriptionFlagBits values

  • VUID-VkSubpassDescription-pipelineBindPoint-parameter
    pipelineBindPoint must be a valid VkPipelineBindPoint value

  • VUID-VkSubpassDescription-pInputAttachments-parameter
    If inputAttachmentCount is not 0, pInputAttachments must be a valid pointer to an array of inputAttachmentCount valid VkAttachmentReference structures

  • VUID-VkSubpassDescription-pColorAttachments-parameter
    If colorAttachmentCount is not 0, pColorAttachments must be a valid pointer to an array of colorAttachmentCount valid VkAttachmentReference structures

  • VUID-VkSubpassDescription-pResolveAttachments-parameter
    If colorAttachmentCount is not 0, and pResolveAttachments is not NULL, pResolveAttachments must be a valid pointer to an array of colorAttachmentCount valid VkAttachmentReference structures

  • VUID-VkSubpassDescription-pDepthStencilAttachment-parameter
    If pDepthStencilAttachment is not NULL, pDepthStencilAttachment must be a valid pointer to a valid VkAttachmentReference structure

  • VUID-VkSubpassDescription-pPreserveAttachments-parameter
    If preserveAttachmentCount is not 0, pPreserveAttachments must be a valid pointer to an array of preserveAttachmentCount uint32_t values

Bits which can be set in VkSubpassDescription::flags, specifying usage of the subpass, are:

// Provided by VK_VERSION_1_0
typedef enum VkSubpassDescriptionFlagBits {
  // Provided by VK_NVX_multiview_per_view_attributes
    VK_SUBPASS_DESCRIPTION_PER_VIEW_ATTRIBUTES_BIT_NVX = 0x00000001,
  // Provided by VK_NVX_multiview_per_view_attributes
    VK_SUBPASS_DESCRIPTION_PER_VIEW_POSITION_X_ONLY_BIT_NVX = 0x00000002,
  // Provided by VK_QCOM_render_pass_shader_resolve
    VK_SUBPASS_DESCRIPTION_FRAGMENT_REGION_BIT_QCOM = 0x00000004,
  // Provided by VK_QCOM_render_pass_shader_resolve
    VK_SUBPASS_DESCRIPTION_SHADER_RESOLVE_BIT_QCOM = 0x00000008,
  // Provided by VK_EXT_rasterization_order_attachment_access
    VK_SUBPASS_DESCRIPTION_RASTERIZATION_ORDER_ATTACHMENT_COLOR_ACCESS_BIT_EXT = 0x00000010,
  // Provided by VK_EXT_rasterization_order_attachment_access
    VK_SUBPASS_DESCRIPTION_RASTERIZATION_ORDER_ATTACHMENT_DEPTH_ACCESS_BIT_EXT = 0x00000020,
  // Provided by VK_EXT_rasterization_order_attachment_access
    VK_SUBPASS_DESCRIPTION_RASTERIZATION_ORDER_ATTACHMENT_STENCIL_ACCESS_BIT_EXT = 0x00000040,
  // Provided by VK_EXT_legacy_dithering
    VK_SUBPASS_DESCRIPTION_ENABLE_LEGACY_DITHERING_BIT_EXT = 0x00000080,
  // Provided by VK_ARM_rasterization_order_attachment_access
    VK_SUBPASS_DESCRIPTION_RASTERIZATION_ORDER_ATTACHMENT_COLOR_ACCESS_BIT_ARM = VK_SUBPASS_DESCRIPTION_RASTERIZATION_ORDER_ATTACHMENT_COLOR_ACCESS_BIT_EXT,
  // Provided by VK_ARM_rasterization_order_attachment_access
    VK_SUBPASS_DESCRIPTION_RASTERIZATION_ORDER_ATTACHMENT_DEPTH_ACCESS_BIT_ARM = VK_SUBPASS_DESCRIPTION_RASTERIZATION_ORDER_ATTACHMENT_DEPTH_ACCESS_BIT_EXT,
  // Provided by VK_ARM_rasterization_order_attachment_access
    VK_SUBPASS_DESCRIPTION_RASTERIZATION_ORDER_ATTACHMENT_STENCIL_ACCESS_BIT_ARM = VK_SUBPASS_DESCRIPTION_RASTERIZATION_ORDER_ATTACHMENT_STENCIL_ACCESS_BIT_EXT,
} VkSubpassDescriptionFlagBits;

  • VK_SUBPASS_DESCRIPTION_PER_VIEW_ATTRIBUTES_BIT_NVX specifies that shaders compiled for this subpass write the attributes for all views in a single invocation of each pre-rasterization shader stage. All pipelines compiled against a subpass that includes this bit must write per-view attributes to the *PerViewNV[] shader outputs, in addition to the non-per-view (e.g. Position) outputs.

  • VK_SUBPASS_DESCRIPTION_PER_VIEW_POSITION_X_ONLY_BIT_NVX specifies that shaders compiled for this subpass use per-view positions which only differ in value in the x component. Per-view viewport mask can also be used.

  • VK_SUBPASS_DESCRIPTION_FRAGMENT_REGION_BIT_QCOM specifies that the framebuffer region is the fragment region, that is, the minimum region dependencies are by pixel rather than by sample, such that any fragment shader invocation can access any sample associated with that fragment shader invocation.

  • VK_SUBPASS_DESCRIPTION_SHADER_RESOLVE_BIT_QCOM specifies that the subpass performs shader resolve operations.

  • VK_SUBPASS_DESCRIPTION_RASTERIZATION_ORDER_ATTACHMENT_COLOR_ACCESS_BIT_EXT specifies that this subpass supports pipelines created with VK_PIPELINE_COLOR_BLEND_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_ACCESS_BIT_EXT.

  • VK_SUBPASS_DESCRIPTION_RASTERIZATION_ORDER_ATTACHMENT_DEPTH_ACCESS_BIT_EXT specifies that this subpass supports pipelines created with VK_PIPELINE_DEPTH_STENCIL_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_DEPTH_ACCESS_BIT_EXT.

  • VK_SUBPASS_DESCRIPTION_RASTERIZATION_ORDER_ATTACHMENT_STENCIL_ACCESS_BIT_EXT specifies that this subpass supports pipelines created with VK_PIPELINE_DEPTH_STENCIL_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_STENCIL_ACCESS_BIT_EXT.

  • VK_SUBPASS_DESCRIPTION_ENABLE_LEGACY_DITHERING_BIT_EXT specifies that Legacy Dithering is enabled for this subpass.

Note

Shader resolve operations allow for custom resolve operations, but overdrawing pixels may have a performance and/or power cost. Furthermore, since the content of any depth stencil attachment or color attachment is undefined at the beginning of a shader resolve subpass, any depth testing, stencil testing, or blending operation which sources these undefined values also has undefined result value.

 
// Provided by VK_VERSION_1_0
typedef VkFlags VkSubpassDescriptionFlags;

VkSubpassDescriptionFlags is a bitmask type for setting a mask of zero or more VkSubpassDescriptionFlagBits.

The VkAttachmentReference structure is defined as:

// Provided by VK_VERSION_1_0
typedef struct VkAttachmentReference {
    uint32_t         attachment;
    VkImageLayout    layout;
} VkAttachmentReference;

  • attachment is either an integer value identifying an attachment at the corresponding index in VkRenderPassCreateInfo::pAttachments, or VK_ATTACHMENT_UNUSED to signify that this attachment is not used.

  • layout is a VkImageLayout value specifying the layout the attachment uses during the subpass.

Valid Usage

  • VUID-VkAttachmentReference-layout-03077
    If attachment is not VK_ATTACHMENT_UNUSED, layout must not be VK_IMAGE_LAYOUT_UNDEFINED, VK_IMAGE_LAYOUT_PREINITIALIZED, or VK_IMAGE_LAYOUT_PRESENT_SRC_KHR

  • VUID-VkAttachmentReference-separateDepthStencilLayouts-03313
    If the separateDepthStencilLayouts feature is not enabled, and attachment is not VK_ATTACHMENT_UNUSED, layout must not be VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL, VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL, or VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL,

  • VUID-VkAttachmentReference-synchronization2-06910
    If the synchronization2 feature is not enabled, layout must not be VK_IMAGE_LAYOUT_ATTACHMENT_OPTIMAL_KHR or VK_IMAGE_LAYOUT_READ_ONLY_OPTIMAL_KHR

  • VUID-VkAttachmentReference-attachmentFeedbackLoopLayout-07311
    If the attachmentFeedbackLoopLayout feature is not enabled, layout must not be VK_IMAGE_LAYOUT_ATTACHMENT_FEEDBACK_LOOP_OPTIMAL_EXT

  • VUID-VkAttachmentReference-dynamicRenderingLocalRead-09546
    If the dynamicRenderingLocalRead feature is not enabled, layout must not be VK_IMAGE_LAYOUT_RENDERING_LOCAL_READ_KHR

Valid Usage (Implicit)

  • VUID-VkAttachmentReference-layout-parameter
    layout must be a valid VkImageLayout value

VK_SUBPASS_EXTERNAL is a special subpass index value expanding synchronization scope outside a subpass. It is described in more detail by VkSubpassDependency.

#define VK_SUBPASS_EXTERNAL               (~0U)

The VkSubpassDependency structure is defined as:

// Provided by VK_VERSION_1_0
typedef struct VkSubpassDependency {
    uint32_t                srcSubpass;
    uint32_t                dstSubpass;
    VkPipelineStageFlags    srcStageMask;
    VkPipelineStageFlags    dstStageMask;
    VkAccessFlags           srcAccessMask;
    VkAccessFlags           dstAccessMask;
    VkDependencyFlags       dependencyFlags;
} VkSubpassDependency;

If srcSubpass is equal to dstSubpass then the VkSubpassDependency does not directly define a dependency. Instead, it enables pipeline barriers to be used in a render pass instance within the identified subpass, where the scopes of one pipeline barrier must be a subset of those described by one subpass dependency. Subpass dependencies specified in this way that include framebuffer-space stages in the srcStageMask must only include framebuffer-space stages in dstStageMask, and must include VK_DEPENDENCY_BY_REGION_BIT. When a subpass dependency is specified in this way for a subpass that has more than one view in its view mask, its dependencyFlags must include VK_DEPENDENCY_VIEW_LOCAL_BIT.

If srcSubpass and dstSubpass are not equal, when a render pass instance which includes a subpass dependency is submitted to a queue, it defines a dependency between the subpasses identified by srcSubpass and dstSubpass.

If srcSubpass is equal to VK_SUBPASS_EXTERNAL, the first synchronization scope includes commands that occur earlier in submission order than the vkCmdBeginRenderPass used to begin the render pass instance. Otherwise, the first set of commands includes all commands submitted as part of the subpass instance identified by srcSubpass and any load, store, or multisample resolve operations on attachments used in srcSubpass. In either case, the first synchronization scope is limited to operations on the pipeline stages determined by the source stage mask specified by srcStageMask.

If dstSubpass is equal to VK_SUBPASS_EXTERNAL, the second synchronization scope includes commands that occur later in submission order than the vkCmdEndRenderPass used to end the render pass instance. Otherwise, the second set of commands includes all commands submitted as part of the subpass instance identified by dstSubpass and any load, store, and multisample resolve operations on attachments used in dstSubpass. In either case, the second synchronization scope is limited to operations on the pipeline stages determined by the destination stage mask specified by dstStageMask.

The first access scope is limited to accesses in the pipeline stages determined by the source stage mask specified by srcStageMask. It is also limited to access types in the source access mask specified by srcAccessMask.

The second access scope is limited to accesses in the pipeline stages determined by the destination stage mask specified by dstStageMask. It is also limited to access types in the destination access mask specified by dstAccessMask.

The availability and visibility operations defined by a subpass dependency affect the execution of image layout transitions within the render pass.

Note

For non-attachment resources, the memory dependency expressed by subpass dependency is nearly identical to that of a VkMemoryBarrier (with matching srcAccessMask and dstAccessMask parameters) submitted as a part of a vkCmdPipelineBarrier (with matching srcStageMask and dstStageMask parameters). The only difference being that its scopes are limited to the identified subpasses rather than potentially affecting everything before and after.

For attachments however, subpass dependencies work more like a VkImageMemoryBarrier defined similarly to the VkMemoryBarrier above, the queue family indices set to VK_QUEUE_FAMILY_IGNORED, and layouts as follows:

  • The equivalent to oldLayout is the attachment’s layout according to the subpass description for srcSubpass.

  • The equivalent to newLayout is the attachment’s layout according to the subpass description for dstSubpass.
Valid Usage

  • VUID-VkSubpassDependency-srcStageMask-04090
    If the geometryShader feature is not enabled, srcStageMask must not contain VK_PIPELINE_STAGE_GEOMETRY_SHADER_BIT

  • VUID-VkSubpassDependency-srcStageMask-04091
    If the tessellationShader feature is not enabled, srcStageMask must not contain VK_PIPELINE_STAGE_TESSELLATION_CONTROL_SHADER_BIT or VK_PIPELINE_STAGE_TESSELLATION_EVALUATION_SHADER_BIT

  • VUID-VkSubpassDependency-srcStageMask-04092
    If the conditionalRendering feature is not enabled, srcStageMask must not contain VK_PIPELINE_STAGE_CONDITIONAL_RENDERING_BIT_EXT

  • VUID-VkSubpassDependency-srcStageMask-04093
    If the fragmentDensityMap feature is not enabled, srcStageMask must not contain VK_PIPELINE_STAGE_FRAGMENT_DENSITY_PROCESS_BIT_EXT

  • VUID-VkSubpassDependency-srcStageMask-04094
    If the transformFeedback feature is not enabled, srcStageMask must not contain VK_PIPELINE_STAGE_TRANSFORM_FEEDBACK_BIT_EXT

  • VUID-VkSubpassDependency-srcStageMask-04095
    If the meshShader feature is not enabled, srcStageMask must not contain VK_PIPELINE_STAGE_MESH_SHADER_BIT_EXT

  • VUID-VkSubpassDependency-srcStageMask-04096
    If the taskShader feature is not enabled, srcStageMask must not contain VK_PIPELINE_STAGE_TASK_SHADER_BIT_EXT

  • VUID-VkSubpassDependency-srcStageMask-07318
    If neither the shadingRateImage or attachmentFragmentShadingRate are enabled, srcStageMask must not contain VK_PIPELINE_STAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR

  • VUID-VkSubpassDependency-srcStageMask-03937
    If the synchronization2 feature is not enabled, srcStageMask must not be 0

  • VUID-VkSubpassDependency-srcStageMask-07949
    If neither the VK_NV_ray_tracing extension or rayTracingPipeline feature are enabled, srcStageMask must not contain VK_PIPELINE_STAGE_RAY_TRACING_SHADER_BIT_KHR

  • VUID-VkSubpassDependency-dstStageMask-04090
    If the geometryShader feature is not enabled, dstStageMask must not contain VK_PIPELINE_STAGE_GEOMETRY_SHADER_BIT

  • VUID-VkSubpassDependency-dstStageMask-04091
    If the tessellationShader feature is not enabled, dstStageMask must not contain VK_PIPELINE_STAGE_TESSELLATION_CONTROL_SHADER_BIT or VK_PIPELINE_STAGE_TESSELLATION_EVALUATION_SHADER_BIT

  • VUID-VkSubpassDependency-dstStageMask-04092
    If the conditionalRendering feature is not enabled, dstStageMask must not contain VK_PIPELINE_STAGE_CONDITIONAL_RENDERING_BIT_EXT

  • VUID-VkSubpassDependency-dstStageMask-04093
    If the fragmentDensityMap feature is not enabled, dstStageMask must not contain VK_PIPELINE_STAGE_FRAGMENT_DENSITY_PROCESS_BIT_EXT

  • VUID-VkSubpassDependency-dstStageMask-04094
    If the transformFeedback feature is not enabled, dstStageMask must not contain VK_PIPELINE_STAGE_TRANSFORM_FEEDBACK_BIT_EXT

  • VUID-VkSubpassDependency-dstStageMask-04095
    If the meshShader feature is not enabled, dstStageMask must not contain VK_PIPELINE_STAGE_MESH_SHADER_BIT_EXT

  • VUID-VkSubpassDependency-dstStageMask-04096
    If the taskShader feature is not enabled, dstStageMask must not contain VK_PIPELINE_STAGE_TASK_SHADER_BIT_EXT

  • VUID-VkSubpassDependency-dstStageMask-07318
    If neither the shadingRateImage or attachmentFragmentShadingRate are enabled, dstStageMask must not contain VK_PIPELINE_STAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR

  • VUID-VkSubpassDependency-dstStageMask-03937
    If the synchronization2 feature is not enabled, dstStageMask must not be 0

  • VUID-VkSubpassDependency-dstStageMask-07949
    If neither the VK_NV_ray_tracing extension or rayTracingPipeline feature are enabled, dstStageMask must not contain VK_PIPELINE_STAGE_RAY_TRACING_SHADER_BIT_KHR

  • VUID-VkSubpassDependency-srcSubpass-00864
    srcSubpass must be less than or equal to dstSubpass, unless one of them is VK_SUBPASS_EXTERNAL, to avoid cyclic dependencies and ensure a valid execution order

  • VUID-VkSubpassDependency-srcSubpass-00865
    srcSubpass and dstSubpass must not both be equal to VK_SUBPASS_EXTERNAL

  • VUID-VkSubpassDependency-srcSubpass-06809
    If srcSubpass is equal to dstSubpass and srcStageMask includes a framebuffer-space stage, dstStageMask must only contain framebuffer-space stages

  • VUID-VkSubpassDependency-srcAccessMask-00868
    Any access flag included in srcAccessMask must be supported by one of the pipeline stages in srcStageMask, as specified in the table of supported access types

  • VUID-VkSubpassDependency-dstAccessMask-00869
    Any access flag included in dstAccessMask must be supported by one of the pipeline stages in dstStageMask, as specified in the table of supported access types

  • VUID-VkSubpassDependency-srcSubpass-02243
    If srcSubpass equals dstSubpass, and srcStageMask and dstStageMask both include a framebuffer-space stage, then dependencyFlags must include VK_DEPENDENCY_BY_REGION_BIT

  • VUID-VkSubpassDependency-dependencyFlags-02520
    If dependencyFlags includes VK_DEPENDENCY_VIEW_LOCAL_BIT, srcSubpass must not be equal to VK_SUBPASS_EXTERNAL

  • VUID-VkSubpassDependency-dependencyFlags-02521
    If dependencyFlags includes VK_DEPENDENCY_VIEW_LOCAL_BIT, dstSubpass must not be equal to VK_SUBPASS_EXTERNAL

  • VUID-VkSubpassDependency-srcSubpass-00872
    If srcSubpass equals dstSubpass and that subpass has more than one bit set in the view mask, then dependencyFlags must include VK_DEPENDENCY_VIEW_LOCAL_BIT

Valid Usage (Implicit)

  • VUID-VkSubpassDependency-srcStageMask-parameter
    srcStageMask must be a valid combination of VkPipelineStageFlagBits values

  • VUID-VkSubpassDependency-dstStageMask-parameter
    dstStageMask must be a valid combination of VkPipelineStageFlagBits values

  • VUID-VkSubpassDependency-srcAccessMask-parameter
    srcAccessMask must be a valid combination of VkAccessFlagBits values

  • VUID-VkSubpassDependency-dstAccessMask-parameter
    dstAccessMask must be a valid combination of VkAccessFlagBits values

  • VUID-VkSubpassDependency-dependencyFlags-parameter
    dependencyFlags must be a valid combination of VkDependencyFlagBits values

When multiview is enabled, the execution of the multiple views of one subpass may not occur simultaneously or even back-to-back, and rather may be interleaved with the execution of other subpasses. The load and store operations apply to attachments on a per-view basis. For example, an attachment using VK_ATTACHMENT_LOAD_OP_CLEAR will have each view cleared on first use, but the first use of one view may be temporally distant from the first use of another view.

Note

A good mental model for multiview is to think of a multiview subpass as if it were a collection of individual (per-view) subpasses that are logically grouped together and described as a single multiview subpass in the API. Similarly, a multiview attachment can be thought of like several individual attachments that happen to be layers in a single image. A view-local dependency between two multiview subpasses acts like a set of one-to-one dependencies between corresponding pairs of per-view subpasses. A view-global dependency between two multiview subpasses acts like a set of N × M dependencies between all pairs of per-view subpasses in the source and destination. Thus, it is a more compact representation which also makes clear the commonality and reuse that is present between views in a subpass. This interpretation motivates the answers to questions like “when does the load op apply” - it is on the first use of each view of an attachment, as if each view was a separate attachment.

The content of each view follows the description in attachment content behavior. In particular, if an attachment is preserved, all views within the attachment are preserved.

If any two subpasses of a render pass activate transform feedback to the same bound transform feedback buffers, a subpass dependency must be included (either directly or via some intermediate subpasses) between them.

If there is no subpass dependency from VK_SUBPASS_EXTERNAL to the first subpass that uses an attachment, then an implicit subpass dependency exists from VK_SUBPASS_EXTERNAL to the first subpass it is used in. The implicit subpass dependency only exists if there exists an automatic layout transition away from initialLayout. The subpass dependency operates as if defined with the following parameters:

VkSubpassDependency implicitDependency = {
    .srcSubpass = VK_SUBPASS_EXTERNAL,
    .dstSubpass = firstSubpass, // First subpass attachment is used in
    .srcStageMask = VK_PIPELINE_STAGE_NONE,
    .dstStageMask = VK_PIPELINE_STAGE_ALL_COMMANDS_BIT,
    .srcAccessMask = 0,
    .dstAccessMask = VK_ACCESS_INPUT_ATTACHMENT_READ_BIT |
                     VK_ACCESS_COLOR_ATTACHMENT_READ_BIT |
                     VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT |
                     VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_READ_BIT |
                     VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_WRITE_BIT,
    .dependencyFlags = 0
};

Similarly, if there is no subpass dependency from the last subpass that uses an attachment to VK_SUBPASS_EXTERNAL, then an implicit subpass dependency exists from the last subpass it is used in to VK_SUBPASS_EXTERNAL. The implicit subpass dependency only exists if there exists an automatic layout transition into finalLayout. The subpass dependency operates as if defined with the following parameters:

VkSubpassDependency implicitDependency = {
    .srcSubpass = lastSubpass, // Last subpass attachment is used in
    .dstSubpass = VK_SUBPASS_EXTERNAL,
    .srcStageMask = VK_PIPELINE_STAGE_ALL_COMMANDS_BIT,
    .dstStageMask = VK_PIPELINE_STAGE_NONE,
    .srcAccessMask = VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT |
                     VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_WRITE_BIT,
    .dstAccessMask = 0,
    .dependencyFlags = 0
};

As subpasses may overlap or execute out of order with regards to other subpasses unless a subpass dependency chain describes otherwise, the layout transitions required between subpasses cannot be known to an application. Instead, an application provides the layout that each attachment must be in at the start and end of a render pass, and the layout it must be in during each subpass it is used in. The implementation then must execute layout transitions between subpasses in order to guarantee that the images are in the layouts required by each subpass, and in the final layout at the end of the render pass.

Automatic layout transitions apply to the entire image subresource attached to the framebuffer. If multiview is not enabled and the attachment is a view of a 1D or 2D image, the automatic layout transitions apply to the number of layers specified by VkFramebufferCreateInfo::layers. If multiview is enabled and the attachment is a view of a 1D or 2D image, the automatic layout transitions apply to the layers corresponding to views which are used by some subpass in the render pass, even if that subpass does not reference the given attachment. If the attachment view is a 2D or 2D array view of a 3D image, even if the attachment view only refers to a subset of the slices of the selected mip level of the 3D image, automatic layout transitions apply to the entire subresource referenced which is the entire mip level in this case.

Automatic layout transitions away from the layout used in a subpass happen-after the availability operations for all dependencies with that subpass as the srcSubpass.

Automatic layout transitions into the layout used in a subpass happen-before the visibility operations for all dependencies with that subpass as the dstSubpass.

Automatic layout transitions away from initialLayout happen-after the availability operations for all dependencies with a srcSubpass equal to VK_SUBPASS_EXTERNAL, where dstSubpass uses the attachment that will be transitioned. For attachments created with VK_ATTACHMENT_DESCRIPTION_MAY_ALIAS_BIT, automatic layout transitions away from initialLayout happen-after the availability operations for all dependencies with a srcSubpass equal to VK_SUBPASS_EXTERNAL, where dstSubpass uses any aliased attachment.

Automatic layout transitions into finalLayout happen-before the visibility operations for all dependencies with a dstSubpass equal to VK_SUBPASS_EXTERNAL, where srcSubpass uses the attachment that will be transitioned. For attachments created with VK_ATTACHMENT_DESCRIPTION_MAY_ALIAS_BIT, automatic layout transitions into finalLayout happen-before the visibility operations for all dependencies with a dstSubpass equal to VK_SUBPASS_EXTERNAL, where srcSubpass uses any aliased attachment.

The image layout of the depth aspect of a depth/stencil attachment referring to an image created with VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT is dependent on the last sample locations used to render to the attachment, thus automatic layout transitions use the sample locations state specified in VkRenderPassSampleLocationsBeginInfoEXT.

Automatic layout transitions of an attachment referring to a depth/stencil image created with VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT use the sample locations the image subresource range referenced by the attachment was last rendered with. If the current render pass does not use the attachment as a depth/stencil attachment in any subpass that happens-before, the automatic layout transition uses the sample locations state specified in the sampleLocationsInfo member of the element of the VkRenderPassSampleLocationsBeginInfoEXT::pAttachmentInitialSampleLocations array for which the attachmentIndex member equals the attachment index of the attachment, if one is specified. Otherwise, the automatic layout transition uses the sample locations state specified in the sampleLocationsInfo member of the element of the VkRenderPassSampleLocationsBeginInfoEXT::pPostSubpassSampleLocations array for which the subpassIndex member equals the index of the subpass that last used the attachment as a depth/stencil attachment, if one is specified.

If no sample locations state has been specified for an automatic layout transition performed on an attachment referring to a depth/stencil image created with VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT the contents of the depth aspect of the depth/stencil attachment become undefined as if the layout of the attachment was transitioned from the VK_IMAGE_LAYOUT_UNDEFINED layout.

If two subpasses use the same attachment, and both subpasses use the attachment in a read-only layout, no subpass dependency needs to be specified between those subpasses. If an implementation treats those layouts separately, it must insert an implicit subpass dependency between those subpasses to separate the uses in each layout. The subpass dependency operates as if defined with the following parameters:

// Used for input attachments
VkPipelineStageFlags inputAttachmentStages = VK_PIPELINE_STAGE_FRAGMENT_SHADER_BIT;
VkAccessFlags inputAttachmentDstAccess = VK_ACCESS_INPUT_ATTACHMENT_READ_BIT;

// Used for depth/stencil attachments
VkPipelineStageFlags depthStencilAttachmentStages = VK_PIPELINE_STAGE_EARLY_FRAGMENT_TESTS_BIT | VK_PIPELINE_STAGE_LATE_FRAGMENT_TESTS_BIT;
VkAccessFlags depthStencilAttachmentDstAccess = VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_READ_BIT;

VkSubpassDependency implicitDependency = {
    .srcSubpass = firstSubpass;
    .dstSubpass = secondSubpass;
    .srcStageMask = inputAttachmentStages | depthStencilAttachmentStages;
    .dstStageMask = inputAttachmentStages | depthStencilAttachmentStages;
    .srcAccessMask = 0;
    .dstAccessMask = inputAttachmentDstAccess | depthStencilAttachmentDstAccess;
    .dependencyFlags = 0;
};

When drawing using shader objects, or when the graphics pipeline is created with VK_DYNAMIC_STATE_ATTACHMENT_FEEDBACK_LOOP_ENABLE_EXT set in VkPipelineDynamicStateCreateInfo::pDynamicStates, the application must specify which types of attachments that are written to during a render pass will also be accessed as non-attachments in the render pass.

To dynamically set whether a pipeline can access a resource as a non-attachment while it is also used as an attachment that is written to, call:

// Provided by VK_EXT_attachment_feedback_loop_dynamic_state
void vkCmdSetAttachmentFeedbackLoopEnableEXT(
    VkCommandBuffer                             commandBuffer,
    VkImageAspectFlags                          aspectMask);

  • commandBuffer is the command buffer into which the command will be recorded.

  • aspectMask specifies the types of attachments for which feedback loops will be enabled. Attachment types whose aspects are not included in aspectMask will have feedback loops disabled.

For attachments that are written to in a render pass, only attachments with the aspects specified in aspectMask can be accessed as non-attachments by subsequent drawing commands.

Valid Usage

  • VUID-vkCmdSetAttachmentFeedbackLoopEnableEXT-attachmentFeedbackLoopDynamicState-08862
    The attachmentFeedbackLoopDynamicState feature must be enabled

  • VUID-vkCmdSetAttachmentFeedbackLoopEnableEXT-aspectMask-08863
    aspectMask must only include VK_IMAGE_ASPECT_NONE, VK_IMAGE_ASPECT_COLOR_BIT, VK_IMAGE_ASPECT_DEPTH_BIT, and VK_IMAGE_ASPECT_STENCIL_BIT

  • VUID-vkCmdSetAttachmentFeedbackLoopEnableEXT-attachmentFeedbackLoopLayout-08864
    If the attachmentFeedbackLoopLayout feature is not enabled, aspectMask must be VK_IMAGE_ASPECT_NONE

Valid Usage (Implicit)

  • VUID-vkCmdSetAttachmentFeedbackLoopEnableEXT-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdSetAttachmentFeedbackLoopEnableEXT-aspectMask-parameter
    aspectMask must be a valid combination of VkImageAspectFlagBits values

  • VUID-vkCmdSetAttachmentFeedbackLoopEnableEXT-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdSetAttachmentFeedbackLoopEnableEXT-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support graphics operations

  • VUID-vkCmdSetAttachmentFeedbackLoopEnableEXT-videocoding
    This command must only be called outside of a video coding scope

Host Synchronization

  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Video Coding Scope Supported Queue Types Command Type

Primary
Secondary

Both

Outside

Graphics

State

A more extensible version of render pass creation is also defined below.

To create a render pass, call:

// Provided by VK_VERSION_1_2
VkResult vkCreateRenderPass2(
    VkDevice                                    device,
    const VkRenderPassCreateInfo2*              pCreateInfo,
    const VkAllocationCallbacks*                pAllocator,
    VkRenderPass*                               pRenderPass);

or the equivalent command

// Provided by VK_KHR_create_renderpass2
VkResult vkCreateRenderPass2KHR(
    VkDevice                                    device,
    const VkRenderPassCreateInfo2*              pCreateInfo,
    const VkAllocationCallbacks*                pAllocator,
    VkRenderPass*                               pRenderPass);

  • device is the logical device that creates the render pass.

  • pCreateInfo is a pointer to a VkRenderPassCreateInfo2 structure describing the parameters of the render pass.

  • pAllocator controls host memory allocation as described in the Memory Allocation chapter.

  • pRenderPass is a pointer to a VkRenderPass handle in which the resulting render pass object is returned.

This command is functionally identical to vkCreateRenderPass, but includes extensible sub-structures that include sType and pNext parameters, allowing them to be more easily extended.

Valid Usage

  • VUID-vkCreateRenderPass2-device-10001
    device must support at least one queue family with the VK_QUEUE_GRAPHICS_BIT capability

Valid Usage (Implicit)

  • VUID-vkCreateRenderPass2-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkCreateRenderPass2-pCreateInfo-parameter
    pCreateInfo must be a valid pointer to a valid VkRenderPassCreateInfo2 structure

  • VUID-vkCreateRenderPass2-pAllocator-parameter
    If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure

  • VUID-vkCreateRenderPass2-pRenderPass-parameter
    pRenderPass must be a valid pointer to a VkRenderPass handle

Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

The VkRenderPassCreateInfo2 structure is defined as:

// Provided by VK_VERSION_1_2
typedef struct VkRenderPassCreateInfo2 {
    VkStructureType                    sType;
    const void*                        pNext;
    VkRenderPassCreateFlags            flags;
    uint32_t                           attachmentCount;
    const VkAttachmentDescription2*    pAttachments;
    uint32_t                           subpassCount;
    const VkSubpassDescription2*       pSubpasses;
    uint32_t                           dependencyCount;
    const VkSubpassDependency2*        pDependencies;
    uint32_t                           correlatedViewMaskCount;
    const uint32_t*                    pCorrelatedViewMasks;
} VkRenderPassCreateInfo2;

or the equivalent

// Provided by VK_KHR_create_renderpass2
typedef VkRenderPassCreateInfo2 VkRenderPassCreateInfo2KHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • flags is reserved for future use.

  • attachmentCount is the number of attachments used by this render pass.

  • pAttachments is a pointer to an array of attachmentCount VkAttachmentDescription2 structures describing the attachments used by the render pass.

  • subpassCount is the number of subpasses to create.

  • pSubpasses is a pointer to an array of subpassCount VkSubpassDescription2 structures describing each subpass.

  • dependencyCount is the number of dependencies between pairs of subpasses.

  • pDependencies is a pointer to an array of dependencyCount VkSubpassDependency2 structures describing dependencies between pairs of subpasses.

  • correlatedViewMaskCount is the number of correlation masks.

  • pCorrelatedViewMasks is a pointer to an array of view masks indicating sets of views that may be more efficient to render concurrently.

Parameters defined by this structure with the same name as those in VkRenderPassCreateInfo have the identical effect to those parameters; the child structures are variants of those used in VkRenderPassCreateInfo which add sType and pNext parameters, allowing them to be extended.

If the VkSubpassDescription2::viewMask member of any element of pSubpasses is not zero, multiview functionality is considered to be enabled for this render pass.

correlatedViewMaskCount and pCorrelatedViewMasks have the same effect as VkRenderPassMultiviewCreateInfo::correlationMaskCount and VkRenderPassMultiviewCreateInfo::pCorrelationMasks, respectively.

Valid Usage

  • VUID-VkRenderPassCreateInfo2-None-03049
    If any two subpasses operate on attachments with overlapping ranges of the same VkDeviceMemory object, and at least one subpass writes to that area of VkDeviceMemory, a subpass dependency must be included (either directly or via some intermediate subpasses) between them

  • VUID-VkRenderPassCreateInfo2-attachment-03050
    If the attachment member of any element of pInputAttachments, pColorAttachments, pResolveAttachments or pDepthStencilAttachment, or the attachment indexed by any element of pPreserveAttachments in any element of pSubpasses is bound to a range of a VkDeviceMemory object that overlaps with any other attachment in any subpass (including the same subpass), the VkAttachmentDescription2 structures describing them must include VK_ATTACHMENT_DESCRIPTION_MAY_ALIAS_BIT in flags

  • VUID-VkRenderPassCreateInfo2-attachment-03051
    If the attachment member of any element of pInputAttachments, pColorAttachments, pResolveAttachments or pDepthStencilAttachment, or any element of pPreserveAttachments in any element of pSubpasses is not VK_ATTACHMENT_UNUSED, then it must be less than attachmentCount

  • VUID-VkRenderPassCreateInfo2-fragmentDensityMapAttachment-06472
    If the pNext chain includes a VkRenderPassFragmentDensityMapCreateInfoEXT structure and the fragmentDensityMapAttachment member is not VK_ATTACHMENT_UNUSED, then attachment must be less than attachmentCount

  • VUID-VkRenderPassCreateInfo2-pSubpasses-06473
    If the pSubpasses pNext chain includes a VkSubpassDescriptionDepthStencilResolve structure and the pDepthStencilResolveAttachment member is not NULL and does not have the value VK_ATTACHMENT_UNUSED, then attachment must be less than attachmentCount

  • VUID-VkRenderPassCreateInfo2-pAttachments-02522
    For any member of pAttachments with a loadOp equal to VK_ATTACHMENT_LOAD_OP_CLEAR, the first use of that attachment must not specify a layout equal to VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL, VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL, or VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL

  • VUID-VkRenderPassCreateInfo2-pAttachments-02523
    For any member of pAttachments with a stencilLoadOp equal to VK_ATTACHMENT_LOAD_OP_CLEAR, the first use of that attachment must not specify a layout equal to VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL, VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL, or VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL

  • VUID-VkRenderPassCreateInfo2-pDependencies-03054
    For any element of pDependencies, if the srcSubpass is not VK_SUBPASS_EXTERNAL, all stage flags included in the srcStageMask member of that dependency must be a pipeline stage supported by the pipeline identified by the pipelineBindPoint member of the source subpass

  • VUID-VkRenderPassCreateInfo2-pDependencies-03055
    For any element of pDependencies, if the dstSubpass is not VK_SUBPASS_EXTERNAL, all stage flags included in the dstStageMask member of that dependency must be a pipeline stage supported by the pipeline identified by the pipelineBindPoint member of the destination subpass

  • VUID-VkRenderPassCreateInfo2-pCorrelatedViewMasks-03056
    The set of bits included in any element of pCorrelatedViewMasks must not overlap with the set of bits included in any other element of pCorrelatedViewMasks

  • VUID-VkRenderPassCreateInfo2-viewMask-03057
    If the VkSubpassDescription2::viewMask member of all elements of pSubpasses is 0, correlatedViewMaskCount must be 0

  • VUID-VkRenderPassCreateInfo2-viewMask-03058
    The VkSubpassDescription2::viewMask member of all elements of pSubpasses must either all be 0, or all not be 0

  • VUID-VkRenderPassCreateInfo2-viewMask-03059
    If the VkSubpassDescription2::viewMask member of all elements of pSubpasses is 0, the dependencyFlags member of any element of pDependencies must not include VK_DEPENDENCY_VIEW_LOCAL_BIT

  • VUID-VkRenderPassCreateInfo2-pDependencies-03060
    For any element of pDependencies where its srcSubpass member equals its dstSubpass member, if the viewMask member of the corresponding element of pSubpasses includes more than one bit, its dependencyFlags member must include VK_DEPENDENCY_VIEW_LOCAL_BIT

  • VUID-VkRenderPassCreateInfo2-attachment-02525
    If the attachment member of any element of the pInputAttachments member of any element of pSubpasses is not VK_ATTACHMENT_UNUSED, the aspectMask member of that element of pInputAttachments must only include aspects that are present in images of the format specified by the element of pAttachments specified by attachment

  • VUID-VkRenderPassCreateInfo2-srcSubpass-02526
    The srcSubpass member of each element of pDependencies must be less than subpassCount

  • VUID-VkRenderPassCreateInfo2-dstSubpass-02527
    The dstSubpass member of each element of pDependencies must be less than subpassCount

  • VUID-VkRenderPassCreateInfo2-pAttachments-04585
    If any element of pAttachments is used as a fragment shading rate attachment in any subpass, it must not be used as any other attachment in the render pass

  • VUID-VkRenderPassCreateInfo2-pAttachments-09387
    If any element of pAttachments is used as a fragment shading rate attachment, the loadOp for that attachment must not be VK_ATTACHMENT_LOAD_OP_CLEAR

  • VUID-VkRenderPassCreateInfo2-flags-04521
    If flags includes VK_RENDER_PASS_CREATE_TRANSFORM_BIT_QCOM, an element of pSubpasses includes an instance of VkFragmentShadingRateAttachmentInfoKHR in its pNext chain, and the pFragmentShadingRateAttachment member of that structure is not equal to NULL, the attachment member of pFragmentShadingRateAttachment must be VK_ATTACHMENT_UNUSED

  • VUID-VkRenderPassCreateInfo2-pAttachments-04586
    If any element of pAttachments is used as a fragment shading rate attachment in any subpass, it must have an image format whose potential format features contain VK_FORMAT_FEATURE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR

  • VUID-VkRenderPassCreateInfo2-rasterizationSamples-04905
    If the pipeline is being created with fragment shader state, and the VK_QCOM_render_pass_shader_resolve extension is enabled, and if subpass has any input attachments, and if the subpass description contains VK_SUBPASS_DESCRIPTION_FRAGMENT_REGION_BIT_QCOM, then the sample count of the input attachments must equal rasterizationSamples

  • VUID-VkRenderPassCreateInfo2-sampleShadingEnable-04906
    If the pipeline is being created with fragment shader state, and the VK_QCOM_render_pass_shader_resolve extension is enabled, and if the subpass description contains VK_SUBPASS_DESCRIPTION_FRAGMENT_REGION_BIT_QCOM, then sampleShadingEnable must be false

  • VUID-VkRenderPassCreateInfo2-flags-04907
    If flags includes VK_SUBPASS_DESCRIPTION_SHADER_RESOLVE_BIT_QCOM, and if pResolveAttachments is not NULL, then each resolve attachment must be VK_ATTACHMENT_UNUSED

  • VUID-VkRenderPassCreateInfo2-flags-04908
    If flags includes VK_SUBPASS_DESCRIPTION_SHADER_RESOLVE_BIT_QCOM, and if pDepthStencilResolveAttachment is not NULL, then the depth/stencil resolve attachment must be VK_ATTACHMENT_UNUSED

  • VUID-VkRenderPassCreateInfo2-flags-04909
    If flags includes VK_SUBPASS_DESCRIPTION_SHADER_RESOLVE_BIT_QCOM, then the subpass must be the last subpass in a subpass dependency chain

  • VUID-VkRenderPassCreateInfo2-attachment-06244
    If the attachment member of the pDepthStencilAttachment member of an element of pSubpasses is not VK_ATTACHMENT_UNUSED, the layout member of that same structure is either VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL or VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, and the pNext chain of that structure does not include a VkAttachmentReferenceStencilLayout structure, then the element of pAttachments with an index equal to attachment must not have a format that includes both depth and stencil components

  • VUID-VkRenderPassCreateInfo2-attachment-06245
    If the attachment member of the pDepthStencilAttachment member of an element of pSubpasses is not VK_ATTACHMENT_UNUSED and the layout member of that same structure is either VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL or VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL, then the element of pAttachments with an index equal to attachment must have a format that includes only a stencil component

  • VUID-VkRenderPassCreateInfo2-attachment-06246
    If the attachment member of the pDepthStencilAttachment member of an element of pSubpasses is not VK_ATTACHMENT_UNUSED and the layout member of that same structure is either VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL or VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, then the element of pAttachments with an index equal to attachment must not have a format that includes only a stencil component

  • VUID-VkRenderPassCreateInfo2-pResolveAttachments-09331
    If any element of pResolveAttachments of any element of pSubpasses references an attachment description with a format of VK_FORMAT_UNDEFINED, VkRenderPassFragmentDensityMapCreateInfoEXT::fragmentDensityMapAttachment->attachment must be VK_ATTACHMENT_UNUSED

Valid Usage (Implicit)

  • VUID-VkRenderPassCreateInfo2-sType-sType
    sType must be VK_STRUCTURE_TYPE_RENDER_PASS_CREATE_INFO_2

  • VUID-VkRenderPassCreateInfo2-pNext-pNext
    Each pNext member of any structure (including this one) in the pNext chain must be either NULL or a pointer to a valid instance of VkRenderPassCreationControlEXT, VkRenderPassCreationFeedbackCreateInfoEXT, or VkRenderPassFragmentDensityMapCreateInfoEXT

  • VUID-VkRenderPassCreateInfo2-sType-unique
    The sType value of each struct in the pNext chain must be unique

  • VUID-VkRenderPassCreateInfo2-flags-parameter
    flags must be a valid combination of VkRenderPassCreateFlagBits values

  • VUID-VkRenderPassCreateInfo2-pAttachments-parameter
    If attachmentCount is not 0, pAttachments must be a valid pointer to an array of attachmentCount valid VkAttachmentDescription2 structures

  • VUID-VkRenderPassCreateInfo2-pSubpasses-parameter
    pSubpasses must be a valid pointer to an array of subpassCount valid VkSubpassDescription2 structures

  • VUID-VkRenderPassCreateInfo2-pDependencies-parameter
    If dependencyCount is not 0, pDependencies must be a valid pointer to an array of dependencyCount valid VkSubpassDependency2 structures

  • VUID-VkRenderPassCreateInfo2-pCorrelatedViewMasks-parameter
    If correlatedViewMaskCount is not 0, pCorrelatedViewMasks must be a valid pointer to an array of correlatedViewMaskCount uint32_t values

  • VUID-VkRenderPassCreateInfo2-subpassCount-arraylength
    subpassCount must be greater than 0

The VkAttachmentDescription2 structure is defined as:

// Provided by VK_VERSION_1_2
typedef struct VkAttachmentDescription2 {
    VkStructureType                 sType;
    const void*                     pNext;
    VkAttachmentDescriptionFlags    flags;
    VkFormat                        format;
    VkSampleCountFlagBits           samples;
    VkAttachmentLoadOp              loadOp;
    VkAttachmentStoreOp             storeOp;
    VkAttachmentLoadOp              stencilLoadOp;
    VkAttachmentStoreOp             stencilStoreOp;
    VkImageLayout                   initialLayout;
    VkImageLayout                   finalLayout;
} VkAttachmentDescription2;

or the equivalent

// Provided by VK_KHR_create_renderpass2
typedef VkAttachmentDescription2 VkAttachmentDescription2KHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • flags is a bitmask of VkAttachmentDescriptionFlagBits specifying additional properties of the attachment.

  • format is a VkFormat value specifying the format of the image that will be used for the attachment.

  • samples is a VkSampleCountFlagBits value specifying the number of samples of the image.

  • loadOp is a VkAttachmentLoadOp value specifying how the contents of color and depth components of the attachment are treated at the beginning of the subpass where it is first used.

  • storeOp is a VkAttachmentStoreOp value specifying how the contents of color and depth components of the attachment are treated at the end of the subpass where it is last used.

  • stencilLoadOp is a VkAttachmentLoadOp value specifying how the contents of stencil components of the attachment are treated at the beginning of the subpass where it is first used.

  • stencilStoreOp is a VkAttachmentStoreOp value specifying how the contents of stencil components of the attachment are treated at the end of the last subpass where it is used.

  • initialLayout is the layout the attachment image subresource will be in when a render pass instance begins.

  • finalLayout is the layout the attachment image subresource will be transitioned to when a render pass instance ends.

Parameters defined by this structure with the same name as those in VkAttachmentDescription have the identical effect to those parameters.

If the separateDepthStencilLayouts feature is enabled, and format is a depth/stencil format, initialLayout and finalLayout can be set to a layout that only specifies the layout of the depth aspect.

If the pNext chain includes a VkAttachmentDescriptionStencilLayout structure, then the stencilInitialLayout and stencilFinalLayout members specify the initial and final layouts of the stencil aspect of a depth/stencil format, and initialLayout and finalLayout only apply to the depth aspect. For depth-only formats, the VkAttachmentDescriptionStencilLayout structure is ignored. For stencil-only formats, the initial and final layouts of the stencil aspect are taken from the VkAttachmentDescriptionStencilLayout structure if present, or initialLayout and finalLayout if not present.

If format is a depth/stencil format, and either initialLayout or finalLayout does not specify a layout for the stencil aspect, then the application must specify the initial and final layouts of the stencil aspect by including a VkAttachmentDescriptionStencilLayout structure in the pNext chain.

loadOp and storeOp are ignored for fragment shading rate attachments. No access to the shading rate attachment is performed in loadOp and storeOp. Instead, access to VK_ACCESS_FRAGMENT_SHADING_RATE_ATTACHMENT_READ_BIT_KHR is performed as fragments are rasterized.

Valid Usage

  • VUID-VkAttachmentDescription2-format-06699
    If format includes a color or depth component and loadOp is VK_ATTACHMENT_LOAD_OP_LOAD, then initialLayout must not be VK_IMAGE_LAYOUT_UNDEFINED

  • VUID-VkAttachmentDescription2-finalLayout-00843
    finalLayout must not be VK_IMAGE_LAYOUT_UNDEFINED or VK_IMAGE_LAYOUT_PREINITIALIZED

  • VUID-VkAttachmentDescription2-format-03280
    If format is a color format, initialLayout must not be VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL or VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL

  • VUID-VkAttachmentDescription2-format-03281
    If format is a depth/stencil format, initialLayout must not be VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL

  • VUID-VkAttachmentDescription2-format-03282
    If format is a color format, finalLayout must not be VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL or VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL

  • VUID-VkAttachmentDescription2-format-03283
    If format is a depth/stencil format, finalLayout must not be VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL

  • VUID-VkAttachmentDescription2-format-06487
    If format is a color format, initialLayout must not be VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL or VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL

  • VUID-VkAttachmentDescription2-format-06488
    If format is a color format, finalLayout must not be VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL or VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL

  • VUID-VkAttachmentDescription2-separateDepthStencilLayouts-03284
    If the separateDepthStencilLayouts feature is not enabled, initialLayout must not be VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL, VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL, or VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL,

  • VUID-VkAttachmentDescription2-separateDepthStencilLayouts-03285
    If the separateDepthStencilLayouts feature is not enabled, finalLayout must not be VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL, VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL, or VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL,

  • VUID-VkAttachmentDescription2-format-03286
    If format is a color format, initialLayout must not be VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL, VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL, or VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL

  • VUID-VkAttachmentDescription2-format-03287
    If format is a color format, finalLayout must not be VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL, VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL, or VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL

  • VUID-VkAttachmentDescription2-format-06906
    If format is a depth/stencil format which includes both depth and stencil components, initialLayout must not be VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL or VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL

  • VUID-VkAttachmentDescription2-format-06907
    If format is a depth/stencil format which includes both depth and stencil components, finalLayout must not be VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL or VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL

  • VUID-VkAttachmentDescription2-format-03290
    If format is a depth/stencil format which includes only the depth component, initialLayout must not be VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL or VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL

  • VUID-VkAttachmentDescription2-format-03291
    If format is a depth/stencil format which includes only the depth component, finalLayout must not be VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL or VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL

  • VUID-VkAttachmentDescription2-synchronization2-06908
    If the synchronization2 feature is not enabled, initialLayout must not be VK_IMAGE_LAYOUT_ATTACHMENT_OPTIMAL_KHR or VK_IMAGE_LAYOUT_READ_ONLY_OPTIMAL_KHR

  • VUID-VkAttachmentDescription2-synchronization2-06909
    If the synchronization2 feature is not enabled, finalLayout must not be VK_IMAGE_LAYOUT_ATTACHMENT_OPTIMAL_KHR or VK_IMAGE_LAYOUT_READ_ONLY_OPTIMAL_KHR

  • VUID-VkAttachmentDescription2-attachmentFeedbackLoopLayout-07309
    If the attachmentFeedbackLoopLayout feature is not enabled, initialLayout must not be VK_IMAGE_LAYOUT_ATTACHMENT_FEEDBACK_LOOP_OPTIMAL_EXT

  • VUID-VkAttachmentDescription2-attachmentFeedbackLoopLayout-07310
    If the attachmentFeedbackLoopLayout feature is not enabled, finalLayout must not be VK_IMAGE_LAYOUT_ATTACHMENT_FEEDBACK_LOOP_OPTIMAL_EXT

  • VUID-VkAttachmentDescription2-samples-08745
    samples must be a valid VkSampleCountFlagBits value that is set in imageCreateSampleCounts (as defined in Image Creation Limits) for the given format

  • VUID-VkAttachmentDescription2-dynamicRenderingLocalRead-09544
    If the dynamicRenderingLocalRead feature is not enabled, initialLayout must not be VK_IMAGE_LAYOUT_RENDERING_LOCAL_READ_KHR

  • VUID-VkAttachmentDescription2-dynamicRenderingLocalRead-09545
    If the dynamicRenderingLocalRead feature is not enabled, finalLayout must not be VK_IMAGE_LAYOUT_RENDERING_LOCAL_READ_KHR

  • VUID-VkAttachmentDescription2-pNext-06704
    If the pNext chain does not include a VkAttachmentDescriptionStencilLayout structure, format includes a stencil component, and stencilLoadOp is VK_ATTACHMENT_LOAD_OP_LOAD, then initialLayout must not be VK_IMAGE_LAYOUT_UNDEFINED

  • VUID-VkAttachmentDescription2-pNext-06705
    If the pNext chain includes a VkAttachmentDescriptionStencilLayout structure, format includes a stencil component, and stencilLoadOp is VK_ATTACHMENT_LOAD_OP_LOAD, then VkAttachmentDescriptionStencilLayout::stencilInitialLayout must not be VK_IMAGE_LAYOUT_UNDEFINED

  • VUID-VkAttachmentDescription2-format-06249
    If format is a depth/stencil format which includes both depth and stencil components, and initialLayout is VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL or VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, the pNext chain must include a VkAttachmentDescriptionStencilLayout structure

  • VUID-VkAttachmentDescription2-format-06250
    If format is a depth/stencil format which includes both depth and stencil components, and finalLayout is VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL or VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, the pNext chain must include a VkAttachmentDescriptionStencilLayout structure

  • VUID-VkAttachmentDescription2-format-06247
    If the pNext chain does not include a VkAttachmentDescriptionStencilLayout structure and format only includes a stencil component, initialLayout must not be VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL or VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL

  • VUID-VkAttachmentDescription2-format-06248
    If the pNext chain does not include a VkAttachmentDescriptionStencilLayout structure and format only includes a stencil component, finalLayout must not be VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL or VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL

  • VUID-VkAttachmentDescription2-format-09332
    If externalFormatResolve is not enabled, format must not be VK_FORMAT_UNDEFINED

  • VUID-VkAttachmentDescription2-format-09334
    If format is VK_FORMAT_UNDEFINED, there must be a VkExternalFormatANDROID structure in the pNext chain with a externalFormat that is not equal to 0

Valid Usage (Implicit)

  • VUID-VkAttachmentDescription2-sType-sType
    sType must be VK_STRUCTURE_TYPE_ATTACHMENT_DESCRIPTION_2

  • VUID-VkAttachmentDescription2-pNext-pNext
    Each pNext member of any structure (including this one) in the pNext chain must be either NULL or a pointer to a valid instance of VkAttachmentDescriptionStencilLayout or VkExternalFormatANDROID

  • VUID-VkAttachmentDescription2-sType-unique
    The sType value of each struct in the pNext chain must be unique

  • VUID-VkAttachmentDescription2-flags-parameter
    flags must be a valid combination of VkAttachmentDescriptionFlagBits values

  • VUID-VkAttachmentDescription2-format-parameter
    format must be a valid VkFormat value

  • VUID-VkAttachmentDescription2-samples-parameter
    samples must be a valid VkSampleCountFlagBits value

  • VUID-VkAttachmentDescription2-loadOp-parameter
    loadOp must be a valid VkAttachmentLoadOp value

  • VUID-VkAttachmentDescription2-storeOp-parameter
    storeOp must be a valid VkAttachmentStoreOp value

  • VUID-VkAttachmentDescription2-stencilLoadOp-parameter
    stencilLoadOp must be a valid VkAttachmentLoadOp value

  • VUID-VkAttachmentDescription2-stencilStoreOp-parameter
    stencilStoreOp must be a valid VkAttachmentStoreOp value

  • VUID-VkAttachmentDescription2-initialLayout-parameter
    initialLayout must be a valid VkImageLayout value

  • VUID-VkAttachmentDescription2-finalLayout-parameter
    finalLayout must be a valid VkImageLayout value

The VkAttachmentDescriptionStencilLayout structure is defined as:

// Provided by VK_VERSION_1_2
typedef struct VkAttachmentDescriptionStencilLayout {
    VkStructureType    sType;
    void*              pNext;
    VkImageLayout      stencilInitialLayout;
    VkImageLayout      stencilFinalLayout;
} VkAttachmentDescriptionStencilLayout;

or the equivalent

// Provided by VK_KHR_separate_depth_stencil_layouts
typedef VkAttachmentDescriptionStencilLayout VkAttachmentDescriptionStencilLayoutKHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • stencilInitialLayout is the layout the stencil aspect of the attachment image subresource will be in when a render pass instance begins.

  • stencilFinalLayout is the layout the stencil aspect of the attachment image subresource will be transitioned to when a render pass instance ends.

Valid Usage

  • VUID-VkAttachmentDescriptionStencilLayout-stencilInitialLayout-03308
    stencilInitialLayout must not be VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL, VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL, VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL, VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL, VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL, or VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL

  • VUID-VkAttachmentDescriptionStencilLayout-stencilFinalLayout-03309
    stencilFinalLayout must not be VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL, VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL, VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL, VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL, VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL, or VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL

  • VUID-VkAttachmentDescriptionStencilLayout-stencilFinalLayout-03310
    stencilFinalLayout must not be VK_IMAGE_LAYOUT_UNDEFINED or VK_IMAGE_LAYOUT_PREINITIALIZED

Valid Usage (Implicit)

  • VUID-VkAttachmentDescriptionStencilLayout-sType-sType
    sType must be VK_STRUCTURE_TYPE_ATTACHMENT_DESCRIPTION_STENCIL_LAYOUT

  • VUID-VkAttachmentDescriptionStencilLayout-stencilInitialLayout-parameter
    stencilInitialLayout must be a valid VkImageLayout value

  • VUID-VkAttachmentDescriptionStencilLayout-stencilFinalLayout-parameter
    stencilFinalLayout must be a valid VkImageLayout value

The VkSubpassDescription2 structure is defined as:

// Provided by VK_VERSION_1_2
typedef struct VkSubpassDescription2 {
    VkStructureType                  sType;
    const void*                      pNext;
    VkSubpassDescriptionFlags        flags;
    VkPipelineBindPoint              pipelineBindPoint;
    uint32_t                         viewMask;
    uint32_t                         inputAttachmentCount;
    const VkAttachmentReference2*    pInputAttachments;
    uint32_t                         colorAttachmentCount;
    const VkAttachmentReference2*    pColorAttachments;
    const VkAttachmentReference2*    pResolveAttachments;
    const VkAttachmentReference2*    pDepthStencilAttachment;
    uint32_t                         preserveAttachmentCount;
    const uint32_t*                  pPreserveAttachments;
} VkSubpassDescription2;

or the equivalent

// Provided by VK_KHR_create_renderpass2
typedef VkSubpassDescription2 VkSubpassDescription2KHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • flags is a bitmask of VkSubpassDescriptionFlagBits specifying usage of the subpass.

  • pipelineBindPoint is a VkPipelineBindPoint value specifying the pipeline type supported for this subpass.

  • viewMask is a bitfield of view indices describing which views rendering is broadcast to in this subpass, when multiview is enabled.

  • inputAttachmentCount is the number of input attachments.

  • pInputAttachments is a pointer to an array of VkAttachmentReference2 structures defining the input attachments for this subpass and their layouts.

  • colorAttachmentCount is the number of color attachments.

  • pColorAttachments is a pointer to an array of colorAttachmentCount VkAttachmentReference2 structures defining the color attachments for this subpass and their layouts.

  • pResolveAttachments is NULL or a pointer to an array of colorAttachmentCount VkAttachmentReference2 structures defining the resolve attachments for this subpass and their layouts.

  • pDepthStencilAttachment is a pointer to a VkAttachmentReference2 structure specifying the depth/stencil attachment for this subpass and its layout.

  • preserveAttachmentCount is the number of preserved attachments.

  • pPreserveAttachments is a pointer to an array of preserveAttachmentCount render pass attachment indices identifying attachments that are not used by this subpass, but whose contents must be preserved throughout the subpass.

Parameters defined by this structure with the same name as those in VkSubpassDescription have the identical effect to those parameters.

viewMask has the same effect for the described subpass as VkRenderPassMultiviewCreateInfo::pViewMasks has on each corresponding subpass.

If a VkFragmentShadingRateAttachmentInfoKHR structure is included in the pNext chain, pFragmentShadingRateAttachment is not NULL, and its attachment member is not VK_ATTACHMENT_UNUSED, the identified attachment defines a fragment shading rate attachment for that subpass.

If any element of pResolveAttachments is an image specified with an VkExternalFormatANDROID, values in the corresponding color attachment will be resolved to the resolve attachment in the same manner as specified for VK_RESOLVE_MODE_EXTERNAL_FORMAT_DOWNSAMPLE_ANDROID.

If the nullColorAttachmentWithExternalFormatResolve limit is VK_TRUE, values in the color attachment will be loaded from the resolve attachment at the start of rendering, and may also be reloaded any time after a resolve occurs or the resolve attachment is written to; if this occurs it must happen-before any writes to the color attachment are performed which happen-after the resolve that triggers this. If any color component in the external format is subsampled, values will be read from the nearest sample in the image when they are loaded. If the color attachment is also used as an input attachment, the same behavior applies.

Setting the color attachment to VK_ATTACHMENT_UNUSED when an external resolve attachment is used and the nullColorAttachmentWithExternalFormatResolve limit is VK_TRUE will not result in color attachment writes to be discarded for that attachment.

When nullColorAttachmentWithExternalFormatResolve is VK_TRUE, the color output from the subpass can still be read via an input attachment; but the application cannot bind an image view for the color attachment as there is no such image view bound. Instead to access the data as an input attachment applications can use the resolve attachment in its place - using the resolve attachment image for the descriptor, and setting the corresponding element of pInputAttachments to the index of the resolve attachment.

Loads or input attachment reads from the resolve attachment are performed as if using a VkSamplerYcbcrConversionCreateInfo with the following parameters:

VkSamplerYcbcrConversionCreateInfo createInfo = {
    .sType = VK_STRUCTURE_TYPE_SAMPLER_YCBCR_CONVERSION_CREATE_INFO,
    .pNext = NULL,
    .format = VK_FORMAT_UNDEFINED,
    .ycbcrModel = VK_SAMPLER_YCBCR_MODEL_CONVERSION_RGB_IDENTITY,
    .ycbcrRange = VK_SAMPLER_YCBCR_RANGE_ITU_FULL,
    .components = {
        .r = VK_COMPONENT_SWIZZLE_B
        .g = VK_COMPONENT_SWIZZLE_R
        .b = VK_COMPONENT_SWIZZLE_G
        .a = VK_COMPONENT_SWIZZLE_IDENTITY},
    .xChromaOffset = properties.chromaOffsetX,
    .yChromaOffset = properties.chromaOffsetY,
    .chromaFilter = VK_FILTER_NEAREST,
    .forceExplicitReconstruction = ... };

where properties is equal to VkPhysicalDeviceExternalFormatResolvePropertiesANDROID returned by the device and forceExplicitReconstruction is effectively ignored as the VK_SAMPLER_YCBCR_MODEL_CONVERSION_RGB_IDENTITY model is used. The applied swizzle is the same effective swizzle that would be applied by the VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_IDENTITY model, but no range expansion is applied.

Valid Usage

  • VUID-VkSubpassDescription2-attachment-06912
    If the attachment member of an element of pInputAttachments is not VK_ATTACHMENT_UNUSED, its layout member must not be VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL or VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL

  • VUID-VkSubpassDescription2-attachment-06913
    If the attachment member of an element of pColorAttachments is not VK_ATTACHMENT_UNUSED, its layout member must not be VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL or VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL

  • VUID-VkSubpassDescription2-attachment-06914
    If the attachment member of an element of pResolveAttachments is not VK_ATTACHMENT_UNUSED, its layout member must not be VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL or VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL

  • VUID-VkSubpassDescription2-attachment-06915
    If the attachment member of pDepthStencilAttachment is not VK_ATTACHMENT_UNUSED, ts layout member must not be VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL or VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL

  • VUID-VkSubpassDescription2-attachment-06916
    If the attachment member of an element of pColorAttachments is not VK_ATTACHMENT_UNUSED, its layout member must not be VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL or VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL

  • VUID-VkSubpassDescription2-attachment-06917
    If the attachment member of an element of pResolveAttachments is not VK_ATTACHMENT_UNUSED, its layout member must not be VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL or VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL

  • VUID-VkSubpassDescription2-attachment-06918
    If the attachment member of an element of pInputAttachments is not VK_ATTACHMENT_UNUSED, its layout member must not be VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL or VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL

  • VUID-VkSubpassDescription2-attachment-06919
    If the attachment member of an element of pColorAttachments is not VK_ATTACHMENT_UNUSED, its layout member must not be VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL, VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL, or VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL

  • VUID-VkSubpassDescription2-attachment-06920
    If the attachment member of an element of pResolveAttachments is not VK_ATTACHMENT_UNUSED, its layout member must not be VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL, VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL, or VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL

  • VUID-VkSubpassDescription2-attachment-06921
    If the attachment member of an element of pInputAttachments is not VK_ATTACHMENT_UNUSED, its layout member must not be VK_IMAGE_LAYOUT_ATTACHMENT_OPTIMAL_KHR

  • VUID-VkSubpassDescription2-attachment-06922
    If the attachment member of an element of pColorAttachments is not VK_ATTACHMENT_UNUSED, its layout member must not be VK_IMAGE_LAYOUT_READ_ONLY_OPTIMAL_KHR

  • VUID-VkSubpassDescription2-attachment-06923
    If the attachment member of an element of pResolveAttachments is not VK_ATTACHMENT_UNUSED, its layout member must not be VK_IMAGE_LAYOUT_READ_ONLY_OPTIMAL_KHR

  • VUID-VkSubpassDescription2-attachment-06251
    If the attachment member of pDepthStencilAttachment is not VK_ATTACHMENT_UNUSED and its pNext chain includes a VkAttachmentReferenceStencilLayout structure, the layout member of pDepthStencilAttachment must not be VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL or VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL

  • VUID-VkSubpassDescription2-pipelineBindPoint-04953
    pipelineBindPoint must be VK_PIPELINE_BIND_POINT_GRAPHICS or VK_PIPELINE_BIND_POINT_SUBPASS_SHADING_HUAWEI

  • VUID-VkSubpassDescription2-colorAttachmentCount-03063
    colorAttachmentCount must be less than or equal to VkPhysicalDeviceLimits::maxColorAttachments

  • VUID-VkSubpassDescription2-loadOp-03064
    If the first use of an attachment in this render pass is as an input attachment, and the attachment is not also used as a color or depth/stencil attachment in the same subpass, then loadOp must not be VK_ATTACHMENT_LOAD_OP_CLEAR

  • VUID-VkSubpassDescription2-pResolveAttachments-03067
    If pResolveAttachments is not NULL, each resolve attachment that is not VK_ATTACHMENT_UNUSED must have a sample count of VK_SAMPLE_COUNT_1_BIT

  • VUID-VkSubpassDescription2-externalFormatResolve-09335
    If externalFormatResolve is not enabled and pResolveAttachments is not NULL, for each resolve attachment that does not have the value VK_ATTACHMENT_UNUSED, the corresponding color attachment must not have the value VK_ATTACHMENT_UNUSED

  • VUID-VkSubpassDescription2-nullColorAttachmentWithExternalFormatResolve-09336
    If the nullColorAttachmentWithExternalFormatResolve property is VK_FALSE and pResolveAttachments is not NULL, for each resolve attachment that has a format of VK_FORMAT_UNDEFINED, the corresponding color attachment must not have the value VK_ATTACHMENT_UNUSED

  • VUID-VkSubpassDescription2-nullColorAttachmentWithExternalFormatResolve-09337
    If the nullColorAttachmentWithExternalFormatResolve property is VK_TRUE and pResolveAttachments is not NULL, for each resolve attachment that has a format of VK_FORMAT_UNDEFINED, the corresponding color attachment must have the value VK_ATTACHMENT_UNUSED

  • VUID-VkSubpassDescription2-externalFormatResolve-09338
    If externalFormatResolve is not enabled and pResolveAttachments is not NULL, for each resolve attachment that is not VK_ATTACHMENT_UNUSED, the corresponding color attachment must not have a sample count of VK_SAMPLE_COUNT_1_BIT

  • VUID-VkSubpassDescription2-externalFormatResolve-09339
    If externalFormatResolve is not enabled, each element of pResolveAttachments must have the same VkFormat as its corresponding color attachment

  • VUID-VkSubpassDescription2-multisampledRenderToSingleSampled-06869
    If the multisampledRenderToSingleSampled feature is not enabled, all attachments in pColorAttachments that are not VK_ATTACHMENT_UNUSED must have the same sample count

  • VUID-VkSubpassDescription2-pInputAttachments-02897
    All attachments in pInputAttachments that are not VK_ATTACHMENT_UNUSED and any of the following is true:

    must have image formats whose potential format features contain at least VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT or VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT

  • VUID-VkSubpassDescription2-pColorAttachments-02898
    All attachments in pColorAttachments that are not VK_ATTACHMENT_UNUSED must have image formats whose potential format features contain VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT

  • VUID-VkSubpassDescription2-pResolveAttachments-09343
    All attachments in pResolveAttachments that are not VK_ATTACHMENT_UNUSED and do not have an image format of VK_FORMAT_UNDEFINED must have image formats whose potential format features contain VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT

  • VUID-VkSubpassDescription2-pDepthStencilAttachment-02900
    If pDepthStencilAttachment is not NULL and the attachment is not VK_ATTACHMENT_UNUSED then it must have an image format whose potential format features contain VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT

  • VUID-VkSubpassDescription2-linearColorAttachment-06499
    If the linearColorAttachment feature is enabled and the image is created with VK_IMAGE_TILING_LINEAR, all attachments in pInputAttachments that are not VK_ATTACHMENT_UNUSED must have image formats whose potential format features must contain VK_FORMAT_FEATURE_2_LINEAR_COLOR_ATTACHMENT_BIT_NV

  • VUID-VkSubpassDescription2-linearColorAttachment-06500
    If the linearColorAttachment feature is enabled and the image is created with VK_IMAGE_TILING_LINEAR, all attachments in pColorAttachments that are not VK_ATTACHMENT_UNUSED must have image formats whose potential format features must contain VK_FORMAT_FEATURE_2_LINEAR_COLOR_ATTACHMENT_BIT_NV

  • VUID-VkSubpassDescription2-linearColorAttachment-06501
    If the linearColorAttachment feature is enabled and the image is created with VK_IMAGE_TILING_LINEAR, all attachments in pResolveAttachments that are not VK_ATTACHMENT_UNUSED must have image formats whose potential format features must contain VK_FORMAT_FEATURE_2_LINEAR_COLOR_ATTACHMENT_BIT_NV

  • VUID-VkSubpassDescription2-None-09456
    If either of the following is enabled:

    all attachments in pColorAttachments that are not VK_ATTACHMENT_UNUSED must have a sample count that is smaller than or equal to the sample count of pDepthStencilAttachment if it is not VK_ATTACHMENT_UNUSED

  • VUID-VkSubpassDescription2-pNext-06870
    If the pNext chain includes a VkMultisampledRenderToSingleSampledInfoEXT structure with multisampledRenderToSingleSampledEnable equal to VK_TRUE, then all attachments in pColorAttachments and pDepthStencilAttachment that are not VK_ATTACHMENT_UNUSED must have a sample count that is either VK_SAMPLE_COUNT_1_BIT or equal to VkMultisampledRenderToSingleSampledInfoEXT::rasterizationSamples

  • VUID-VkSubpassDescription2-pNext-06871
    If the pNext chain includes a VkMultisampledRenderToSingleSampledInfoEXT structure with multisampledRenderToSingleSampledEnable equal to VK_TRUE, and pDepthStencilAttachment is not NULL, does not have the value VK_ATTACHMENT_UNUSED, and has a sample count of VK_SAMPLE_COUNT_1_BIT, the pNext chain must also include a VkSubpassDescriptionDepthStencilResolve structure with pDepthStencilResolveAttachment that is either NULL or has the value VK_ATTACHMENT_UNUSED

  • VUID-VkSubpassDescription2-multisampledRenderToSingleSampled-06872
    All attachments in pDepthStencilAttachment or pColorAttachments that are not VK_ATTACHMENT_UNUSED must have the same sample count , if none of the following are enabled:

  • VUID-VkSubpassDescription2-attachment-03073
    Each element of pPreserveAttachments must not be VK_ATTACHMENT_UNUSED

  • VUID-VkSubpassDescription2-pPreserveAttachments-03074
    Each element of pPreserveAttachments must not also be an element of any other member of the subpass description

  • VUID-VkSubpassDescription2-layout-02528
    If any attachment is used by more than one VkAttachmentReference2 member, then each use must use the same layout

  • VUID-VkSubpassDescription2-flags-03076
    If flags includes VK_SUBPASS_DESCRIPTION_PER_VIEW_POSITION_X_ONLY_BIT_NVX, it must also include VK_SUBPASS_DESCRIPTION_PER_VIEW_ATTRIBUTES_BIT_NVX

  • VUID-VkSubpassDescription2-attachment-02799
    If the attachment member of any element of pInputAttachments is not VK_ATTACHMENT_UNUSED, then the aspectMask member must be a valid combination of VkImageAspectFlagBits

  • VUID-VkSubpassDescription2-attachment-02800
    If the attachment member of any element of pInputAttachments is not VK_ATTACHMENT_UNUSED, then the aspectMask member must not be 0

  • VUID-VkSubpassDescription2-attachment-02801
    If the attachment member of any element of pInputAttachments is not VK_ATTACHMENT_UNUSED, then the aspectMask member must not include VK_IMAGE_ASPECT_METADATA_BIT

  • VUID-VkSubpassDescription2-attachment-04563
    If the attachment member of any element of pInputAttachments is not VK_ATTACHMENT_UNUSED, then the aspectMask member must not include VK_IMAGE_ASPECT_MEMORY_PLANE_i_BIT_EXT for any index i

  • VUID-VkSubpassDescription2-pDepthStencilAttachment-04440
    An attachment must not be used in both pDepthStencilAttachment and pColorAttachments

  • VUID-VkSubpassDescription2-multiview-06558
    If the multiview feature is not enabled, viewMask must be 0

  • VUID-VkSubpassDescription2-viewMask-06706
    The index of the most significant bit in viewMask must be less than maxMultiviewViewCount

  • VUID-VkSubpassDescription2-externalFormatResolve-09344
    If externalFormatResolve is enabled, pResolveAttachments is not NULL, and colorAttachmentCount is not 1, any element of pResolveAttachments that is not VK_ATTACHMENT_UNUSED, must not have a format of VK_FORMAT_UNDEFINED

  • VUID-VkSubpassDescription2-externalFormatResolve-09345
    If externalFormatResolve is enabled, pResolveAttachments is not NULL, any element of pResolveAttachments is not VK_ATTACHMENT_UNUSED and has a format of VK_FORMAT_UNDEFINED, and the corresponding element of pColorAttachments is not VK_ATTACHMENT_UNUSED, the color attachment must have a samples value of 1

  • VUID-VkSubpassDescription2-externalFormatResolve-09346
    If externalFormatResolve is enabled, pResolveAttachments is not NULL, and any element of pResolveAttachments is not VK_ATTACHMENT_UNUSED and has a format of VK_FORMAT_UNDEFINED, viewMask must be 0

  • VUID-VkSubpassDescription2-externalFormatResolve-09347
    If externalFormatResolve is enabled, pResolveAttachments is not NULL, and any element of pResolveAttachments is not VK_ATTACHMENT_UNUSED and has a format of VK_FORMAT_UNDEFINED, VkFragmentShadingRateAttachmentInfoKHR::pFragmentShadingRateAttachment must either be NULL or a VkAttachmentReference2 structure with an attachment value of VK_ATTACHMENT_UNUSED

  • VUID-VkSubpassDescription2-externalFormatResolve-09348
    If externalFormatResolve is enabled, pResolveAttachments is not NULL, and any element of pResolveAttachments is not VK_ATTACHMENT_UNUSED and has a format of VK_FORMAT_UNDEFINED, elements of pInputAttachments referencing either a color attachment or resolve attachment used in this subpass must not include VK_IMAGE_ASPECT_PLANE_i_BIT for any index i in its aspectMask

Valid Usage (Implicit)

  • VUID-VkSubpassDescription2-sType-sType
    sType must be VK_STRUCTURE_TYPE_SUBPASS_DESCRIPTION_2

  • VUID-VkSubpassDescription2-pNext-pNext
    Each pNext member of any structure (including this one) in the pNext chain must be either NULL or a pointer to a valid instance of VkFragmentShadingRateAttachmentInfoKHR, VkMultisampledRenderToSingleSampledInfoEXT, VkRenderPassCreationControlEXT, VkRenderPassSubpassFeedbackCreateInfoEXT, or VkSubpassDescriptionDepthStencilResolve

  • VUID-VkSubpassDescription2-sType-unique
    The sType value of each struct in the pNext chain must be unique

  • VUID-VkSubpassDescription2-flags-parameter
    flags must be a valid combination of VkSubpassDescriptionFlagBits values

  • VUID-VkSubpassDescription2-pipelineBindPoint-parameter
    pipelineBindPoint must be a valid VkPipelineBindPoint value

  • VUID-VkSubpassDescription2-pInputAttachments-parameter
    If inputAttachmentCount is not 0, pInputAttachments must be a valid pointer to an array of inputAttachmentCount valid VkAttachmentReference2 structures

  • VUID-VkSubpassDescription2-pColorAttachments-parameter
    If colorAttachmentCount is not 0, pColorAttachments must be a valid pointer to an array of colorAttachmentCount valid VkAttachmentReference2 structures

  • VUID-VkSubpassDescription2-pResolveAttachments-parameter
    If colorAttachmentCount is not 0, and pResolveAttachments is not NULL, pResolveAttachments must be a valid pointer to an array of colorAttachmentCount valid VkAttachmentReference2 structures

  • VUID-VkSubpassDescription2-pDepthStencilAttachment-parameter
    If pDepthStencilAttachment is not NULL, pDepthStencilAttachment must be a valid pointer to a valid VkAttachmentReference2 structure

  • VUID-VkSubpassDescription2-pPreserveAttachments-parameter
    If preserveAttachmentCount is not 0, pPreserveAttachments must be a valid pointer to an array of preserveAttachmentCount uint32_t values

The VkSubpassDescriptionDepthStencilResolve structure is defined as:

// Provided by VK_VERSION_1_2
typedef struct VkSubpassDescriptionDepthStencilResolve {
    VkStructureType                  sType;
    const void*                      pNext;
    VkResolveModeFlagBits            depthResolveMode;
    VkResolveModeFlagBits            stencilResolveMode;
    const VkAttachmentReference2*    pDepthStencilResolveAttachment;
} VkSubpassDescriptionDepthStencilResolve;

or the equivalent

// Provided by VK_KHR_depth_stencil_resolve
typedef VkSubpassDescriptionDepthStencilResolve VkSubpassDescriptionDepthStencilResolveKHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • depthResolveMode is a VkResolveModeFlagBits value describing the depth resolve mode.

  • stencilResolveMode is a VkResolveModeFlagBits value describing the stencil resolve mode.

  • pDepthStencilResolveAttachment is NULL or a pointer to a VkAttachmentReference2 structure defining the depth/stencil resolve attachment for this subpass and its layout.

If the pNext chain of VkSubpassDescription2 includes a VkSubpassDescriptionDepthStencilResolve structure, then that structure describes multisample resolve operations for the depth/stencil attachment in a subpass. If this structure is not included in the pNext chain of VkSubpassDescription2, or if it is and either pDepthStencilResolveAttachment is NULL or its attachment index is VK_ATTACHMENT_UNUSED, it indicates that no depth/stencil resolve attachment will be used in the subpass.

Valid Usage

  • VUID-VkSubpassDescriptionDepthStencilResolve-pDepthStencilResolveAttachment-03177
    If pDepthStencilResolveAttachment is not NULL and does not have the value VK_ATTACHMENT_UNUSED, pDepthStencilAttachment must not be NULL or have the value VK_ATTACHMENT_UNUSED

  • VUID-VkSubpassDescriptionDepthStencilResolve-pDepthStencilResolveAttachment-03179
    If pDepthStencilResolveAttachment is not NULL and does not have the value VK_ATTACHMENT_UNUSED, pDepthStencilAttachment must not have a sample count of VK_SAMPLE_COUNT_1_BIT

  • VUID-VkSubpassDescriptionDepthStencilResolve-pDepthStencilResolveAttachment-03180
    If pDepthStencilResolveAttachment is not NULL and does not have the value VK_ATTACHMENT_UNUSED, pDepthStencilResolveAttachment must have a sample count of VK_SAMPLE_COUNT_1_BIT

  • VUID-VkSubpassDescriptionDepthStencilResolve-pDepthStencilResolveAttachment-02651
    If pDepthStencilResolveAttachment is not NULL and does not have the value VK_ATTACHMENT_UNUSED then it must have an image format whose potential format features contain VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT

  • VUID-VkSubpassDescriptionDepthStencilResolve-pDepthStencilResolveAttachment-03181
    If pDepthStencilResolveAttachment is not NULL and does not have the value VK_ATTACHMENT_UNUSED and VkFormat of pDepthStencilResolveAttachment has a depth component, then the VkFormat of pDepthStencilAttachment must have a depth component with the same number of bits and numeric format

  • VUID-VkSubpassDescriptionDepthStencilResolve-pDepthStencilResolveAttachment-03182
    If pDepthStencilResolveAttachment is not NULL and does not have the value VK_ATTACHMENT_UNUSED, and VkFormat of pDepthStencilResolveAttachment has a stencil component, then the VkFormat of pDepthStencilAttachment must have a stencil component with the same number of bits and numeric format

  • VUID-VkSubpassDescriptionDepthStencilResolve-pDepthStencilResolveAttachment-03178
    If pDepthStencilResolveAttachment is not NULL and does not have the value VK_ATTACHMENT_UNUSED, depthResolveMode and stencilResolveMode must not both be VK_RESOLVE_MODE_NONE

  • VUID-VkSubpassDescriptionDepthStencilResolve-depthResolveMode-03183
    If pDepthStencilResolveAttachment is not NULL and does not have the value VK_ATTACHMENT_UNUSED and the VkFormat of pDepthStencilResolveAttachment has a depth component, then the value of depthResolveMode must be one of the bits set in VkPhysicalDeviceDepthStencilResolveProperties::supportedDepthResolveModes or VK_RESOLVE_MODE_NONE

  • VUID-VkSubpassDescriptionDepthStencilResolve-stencilResolveMode-03184
    If pDepthStencilResolveAttachment is not NULL and does not have the value VK_ATTACHMENT_UNUSED and the VkFormat of pDepthStencilResolveAttachment has a stencil component, then the value of stencilResolveMode must be one of the bits set in VkPhysicalDeviceDepthStencilResolveProperties::supportedStencilResolveModes or VK_RESOLVE_MODE_NONE

  • VUID-VkSubpassDescriptionDepthStencilResolve-pDepthStencilResolveAttachment-03185
    If pDepthStencilResolveAttachment is not NULL and does not have the value VK_ATTACHMENT_UNUSED, the VkFormat of pDepthStencilResolveAttachment has both depth and stencil components, VkPhysicalDeviceDepthStencilResolveProperties::independentResolve is VK_FALSE, and VkPhysicalDeviceDepthStencilResolveProperties::independentResolveNone is VK_FALSE, then the values of depthResolveMode and stencilResolveMode must be identical

  • VUID-VkSubpassDescriptionDepthStencilResolve-pDepthStencilResolveAttachment-03186
    If pDepthStencilResolveAttachment is not NULL and does not have the value VK_ATTACHMENT_UNUSED, the VkFormat of pDepthStencilResolveAttachment has both depth and stencil components, VkPhysicalDeviceDepthStencilResolveProperties::independentResolve is VK_FALSE and VkPhysicalDeviceDepthStencilResolveProperties::independentResolveNone is VK_TRUE, then the values of depthResolveMode and stencilResolveMode must be identical or one of them must be VK_RESOLVE_MODE_NONE

  • VUID-VkSubpassDescriptionDepthStencilResolve-pNext-06873
    If the pNext chain of VkSubpassDescription2 includes a VkMultisampledRenderToSingleSampledInfoEXT structure, the multisampledRenderToSingleSampledEnable field is VK_TRUE, and pDepthStencilAttachment is not NULL and does not have the value VK_ATTACHMENT_UNUSED, depthResolveMode and stencilResolveMode must not both be VK_RESOLVE_MODE_NONE

  • VUID-VkSubpassDescriptionDepthStencilResolve-pNext-06874
    If the pNext chain of VkSubpassDescription2 includes a VkMultisampledRenderToSingleSampledInfoEXT structure whose multisampledRenderToSingleSampledEnable field is VK_TRUE, and pDepthStencilAttachment is not NULL, does not have the value VK_ATTACHMENT_UNUSED, and has a VkFormat that has a depth component, then the value of depthResolveMode must be one of the bits set in VkPhysicalDeviceDepthStencilResolveProperties::supportedDepthResolveModes or VK_RESOLVE_MODE_NONE

  • VUID-VkSubpassDescriptionDepthStencilResolve-pNext-06875
    If the pNext chain of VkSubpassDescription2 includes a VkMultisampledRenderToSingleSampledInfoEXT structure whose multisampledRenderToSingleSampledEnable field is VK_TRUE, and pDepthStencilAttachment is not NULL, does not have the value VK_ATTACHMENT_UNUSED, and has a VkFormat with a stencil component, then the value of stencilResolveMode must be one of the bits set in VkPhysicalDeviceDepthStencilResolveProperties::supportedStencilResolveModes or VK_RESOLVE_MODE_NONE

  • VUID-VkSubpassDescriptionDepthStencilResolve-pNext-06876
    If the pNext chain of VkSubpassDescription2 includes a VkMultisampledRenderToSingleSampledInfoEXT structure whose multisampledRenderToSingleSampledEnable field is VK_TRUE, pDepthStencilAttachment is not NULL, does not have the value VK_ATTACHMENT_UNUSED, and has a VkFormat with both depth and stencil components, and both VkPhysicalDeviceDepthStencilResolveProperties::independentResolve and VkPhysicalDeviceDepthStencilResolveProperties::independentResolveNone are VK_FALSE, then the values of depthResolveMode and stencilResolveMode must be identical

  • VUID-VkSubpassDescriptionDepthStencilResolve-pNext-06877
    If the pNext chain of VkSubpassDescription2 includes a VkMultisampledRenderToSingleSampledInfoEXT structure whose multisampledRenderToSingleSampledEnable field is VK_TRUE, pDepthStencilAttachment is not NULL, does not have the value VK_ATTACHMENT_UNUSED, and has a VkFormat with both depth and stencil components, VkPhysicalDeviceDepthStencilResolveProperties::independentResolve is VK_FALSE, and VkPhysicalDeviceDepthStencilResolveProperties::independentResolveNone is VK_TRUE, then the values of depthResolveMode and stencilResolveMode must be identical or one of them must be VK_RESOLVE_MODE_NONE

Valid Usage (Implicit)

  • VUID-VkSubpassDescriptionDepthStencilResolve-sType-sType
    sType must be VK_STRUCTURE_TYPE_SUBPASS_DESCRIPTION_DEPTH_STENCIL_RESOLVE

  • VUID-VkSubpassDescriptionDepthStencilResolve-pDepthStencilResolveAttachment-parameter
    If pDepthStencilResolveAttachment is not NULL, pDepthStencilResolveAttachment must be a valid pointer to a valid VkAttachmentReference2 structure

The VkFragmentShadingRateAttachmentInfoKHR structure is defined as:

// Provided by VK_KHR_fragment_shading_rate
typedef struct VkFragmentShadingRateAttachmentInfoKHR {
    VkStructureType                  sType;
    const void*                      pNext;
    const VkAttachmentReference2*    pFragmentShadingRateAttachment;
    VkExtent2D                       shadingRateAttachmentTexelSize;
} VkFragmentShadingRateAttachmentInfoKHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • pFragmentShadingRateAttachment is NULL or a pointer to a VkAttachmentReference2 structure defining the fragment shading rate attachment for this subpass.

  • shadingRateAttachmentTexelSize specifies the size of the portion of the framebuffer corresponding to each texel in pFragmentShadingRateAttachment.

If no shading rate attachment is specified, or if this structure is not specified, the implementation behaves as if a valid shading rate attachment was specified with all texels specifying a single pixel per fragment.

Valid Usage

  • VUID-VkFragmentShadingRateAttachmentInfoKHR-pFragmentShadingRateAttachment-04524
    If pFragmentShadingRateAttachment is not NULL and its attachment member is not VK_ATTACHMENT_UNUSED, its layout member must be equal to VK_IMAGE_LAYOUT_GENERAL or VK_IMAGE_LAYOUT_FRAGMENT_SHADING_RATE_ATTACHMENT_OPTIMAL_KHR

  • VUID-VkFragmentShadingRateAttachmentInfoKHR-pFragmentShadingRateAttachment-04525
    If pFragmentShadingRateAttachment is not NULL and its attachment member is not VK_ATTACHMENT_UNUSED, shadingRateAttachmentTexelSize.width must be a power of two value

  • VUID-VkFragmentShadingRateAttachmentInfoKHR-pFragmentShadingRateAttachment-04526
    If pFragmentShadingRateAttachment is not NULL and its attachment member is not VK_ATTACHMENT_UNUSED, shadingRateAttachmentTexelSize.width must be less than or equal to maxFragmentShadingRateAttachmentTexelSize.width

  • VUID-VkFragmentShadingRateAttachmentInfoKHR-pFragmentShadingRateAttachment-04527
    If pFragmentShadingRateAttachment is not NULL and its attachment member is not VK_ATTACHMENT_UNUSED, shadingRateAttachmentTexelSize.width must be greater than or equal to minFragmentShadingRateAttachmentTexelSize.width

  • VUID-VkFragmentShadingRateAttachmentInfoKHR-pFragmentShadingRateAttachment-04528
    If pFragmentShadingRateAttachment is not NULL and its attachment member is not VK_ATTACHMENT_UNUSED, shadingRateAttachmentTexelSize.height must be a power of two value

  • VUID-VkFragmentShadingRateAttachmentInfoKHR-pFragmentShadingRateAttachment-04529
    If pFragmentShadingRateAttachment is not NULL and its attachment member is not VK_ATTACHMENT_UNUSED, shadingRateAttachmentTexelSize.height must be less than or equal to maxFragmentShadingRateAttachmentTexelSize.height

  • VUID-VkFragmentShadingRateAttachmentInfoKHR-pFragmentShadingRateAttachment-04530
    If pFragmentShadingRateAttachment is not NULL and its attachment member is not VK_ATTACHMENT_UNUSED, shadingRateAttachmentTexelSize.height must be greater than or equal to minFragmentShadingRateAttachmentTexelSize.height

  • VUID-VkFragmentShadingRateAttachmentInfoKHR-pFragmentShadingRateAttachment-04531
    If pFragmentShadingRateAttachment is not NULL and its attachment member is not VK_ATTACHMENT_UNUSED, the quotient of shadingRateAttachmentTexelSize.width and shadingRateAttachmentTexelSize.height must be less than or equal to maxFragmentShadingRateAttachmentTexelSizeAspectRatio

  • VUID-VkFragmentShadingRateAttachmentInfoKHR-pFragmentShadingRateAttachment-04532
    If pFragmentShadingRateAttachment is not NULL and its attachment member is not VK_ATTACHMENT_UNUSED, the quotient of shadingRateAttachmentTexelSize.height and shadingRateAttachmentTexelSize.width must be less than or equal to maxFragmentShadingRateAttachmentTexelSizeAspectRatio

Valid Usage (Implicit)

  • VUID-VkFragmentShadingRateAttachmentInfoKHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_FRAGMENT_SHADING_RATE_ATTACHMENT_INFO_KHR

  • VUID-VkFragmentShadingRateAttachmentInfoKHR-pFragmentShadingRateAttachment-parameter
    If pFragmentShadingRateAttachment is not NULL, pFragmentShadingRateAttachment must be a valid pointer to a valid VkAttachmentReference2 structure

If the pNext chain of VkSubpassDescription2 or VkRenderingInfo includes a VkMultisampledRenderToSingleSampledInfoEXT structure, then that structure describes how multisampled rendering is performed on single sampled attachments in that subpass.

The VkMultisampledRenderToSingleSampledInfoEXT structure is defined as:

// Provided by VK_EXT_multisampled_render_to_single_sampled
typedef struct VkMultisampledRenderToSingleSampledInfoEXT {
    VkStructureType          sType;
    const void*              pNext;
    VkBool32                 multisampledRenderToSingleSampledEnable;
    VkSampleCountFlagBits    rasterizationSamples;
} VkMultisampledRenderToSingleSampledInfoEXT;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • multisampledRenderToSingleSampledEnable controls whether multisampled rendering to single-sampled attachments is performed as described below.

  • rasterizationSamples is a VkSampleCountFlagBits specifying the number of samples used in rasterization.

Valid Usage

  • VUID-VkMultisampledRenderToSingleSampledInfoEXT-rasterizationSamples-06878
    The value of rasterizationSamples must not be VK_SAMPLE_COUNT_1_BIT

  • VUID-VkMultisampledRenderToSingleSampledInfoEXT-pNext-06880
    If added to the pNext chain of VkRenderingInfo, each imageView member of any element of VkRenderingInfo::pColorAttachments, VkRenderingInfo::pDepthAttachment, or VkRenderingInfo::pStencilAttachment that is not VK_NULL_HANDLE must have a format that supports the sample count specified in rasterizationSamples

Valid Usage (Implicit)

  • VUID-VkMultisampledRenderToSingleSampledInfoEXT-sType-sType
    sType must be VK_STRUCTURE_TYPE_MULTISAMPLED_RENDER_TO_SINGLE_SAMPLED_INFO_EXT

  • VUID-VkMultisampledRenderToSingleSampledInfoEXT-rasterizationSamples-parameter
    rasterizationSamples must be a valid VkSampleCountFlagBits value

If the pNext chain of VkSubpassDescription2 or VkRenderingInfo includes a VkMultisampledRenderToSingleSampledInfoEXT structure whose multisampledRenderToSingleSampledEnable field is VK_TRUE, the graphics pipelines must have VkGraphicsPipelineCreateInfo::rasterizationSamples equal to VkMultisampledRenderToSingleSampledInfoEXT::rasterizationSamples, and the subpass attachments can have a sample count of VK_SAMPLE_COUNT_1_BIT. For attachments with a sample count of VK_SAMPLE_COUNT_1_BIT, multisampled rendering is performed to an intermediate multisampled image with VkMultisampledRenderToSingleSampledInfoEXT::rasterizationSamples samples, implicitly allocated by the implementation for the duration of the subpass. For such attachments:

  • If loadOp equals to VK_ATTACHMENT_LOAD_OP_LOAD, samples of the implicit image are initialized by replicating the value from the corresponding pixel in the attachment.

  • If storeOp or stencilStoreOp is equal to VK_ATTACHMENT_STORE_OP_STORE, the implicit image is implicitly resolved prior to storage in the attachment.

Memory constraints due to high primitive counts may result in an implicit split of the subpass. This is the equivalent of partial rasterization of geometry in a render pass that ends in storeOp and stencilStoreOp equal to VK_ATTACHMENT_STORE_OP_STORE, followed by another render pass with loadOp and stencilLoadOp equal to VK_ATTACHMENT_LOAD_OP_LOAD with appropriate barriers in between. When VkMultisampledRenderToSingleSampledInfoEXT is used, the implementation is allowed to resolve attachments with a sample count of VK_SAMPLE_COUNT_1_BIT and lose multisampled data on such splits. The implementation may similarly split the render pass at subpass boundaries even if they use the same value for VkMultisampledRenderToSingleSampledInfoEXT::rasterizationSamples.

The VkAttachmentReference2 structure is defined as:

// Provided by VK_VERSION_1_2
typedef struct VkAttachmentReference2 {
    VkStructureType       sType;
    const void*           pNext;
    uint32_t              attachment;
    VkImageLayout         layout;
    VkImageAspectFlags    aspectMask;
} VkAttachmentReference2;

or the equivalent

// Provided by VK_KHR_create_renderpass2
typedef VkAttachmentReference2 VkAttachmentReference2KHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • attachment is either an integer value identifying an attachment at the corresponding index in VkRenderPassCreateInfo2::pAttachments, or VK_ATTACHMENT_UNUSED to signify that this attachment is not used.

  • layout is a VkImageLayout value specifying the layout the attachment uses during the subpass.

  • aspectMask is a mask of which aspect(s) can be accessed within the specified subpass as an input attachment.

Parameters defined by this structure with the same name as those in VkAttachmentReference have the identical effect to those parameters.

aspectMask is ignored when this structure is used to describe anything other than an input attachment reference.

If the separateDepthStencilLayouts feature is enabled, and attachment has a depth/stencil format, layout can be set to a layout that only specifies the layout of the depth aspect.

If layout only specifies the layout of the depth aspect of the attachment, the layout of the stencil aspect is specified by the stencilLayout member of a VkAttachmentReferenceStencilLayout structure included in the pNext chain. Otherwise, layout describes the layout for all relevant image aspects.

Valid Usage

  • VUID-VkAttachmentReference2-layout-03077
    If attachment is not VK_ATTACHMENT_UNUSED, layout must not be VK_IMAGE_LAYOUT_UNDEFINED, VK_IMAGE_LAYOUT_PREINITIALIZED, or VK_IMAGE_LAYOUT_PRESENT_SRC_KHR

  • VUID-VkAttachmentReference2-separateDepthStencilLayouts-03313
    If the separateDepthStencilLayouts feature is not enabled, and attachment is not VK_ATTACHMENT_UNUSED, layout must not be VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL, VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL, or VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL,

  • VUID-VkAttachmentReference2-synchronization2-06910
    If the synchronization2 feature is not enabled, layout must not be VK_IMAGE_LAYOUT_ATTACHMENT_OPTIMAL_KHR or VK_IMAGE_LAYOUT_READ_ONLY_OPTIMAL_KHR

  • VUID-VkAttachmentReference2-attachmentFeedbackLoopLayout-07311
    If the attachmentFeedbackLoopLayout feature is not enabled, layout must not be VK_IMAGE_LAYOUT_ATTACHMENT_FEEDBACK_LOOP_OPTIMAL_EXT

  • VUID-VkAttachmentReference2-dynamicRenderingLocalRead-09546
    If the dynamicRenderingLocalRead feature is not enabled, layout must not be VK_IMAGE_LAYOUT_RENDERING_LOCAL_READ_KHR

Valid Usage (Implicit)

  • VUID-VkAttachmentReference2-sType-sType
    sType must be VK_STRUCTURE_TYPE_ATTACHMENT_REFERENCE_2

  • VUID-VkAttachmentReference2-pNext-pNext
    pNext must be NULL or a pointer to a valid instance of VkAttachmentReferenceStencilLayout

  • VUID-VkAttachmentReference2-sType-unique
    The sType value of each struct in the pNext chain must be unique

  • VUID-VkAttachmentReference2-layout-parameter
    layout must be a valid VkImageLayout value

The VkAttachmentReferenceStencilLayout structure is defined as:

// Provided by VK_VERSION_1_2
typedef struct VkAttachmentReferenceStencilLayout {
    VkStructureType    sType;
    void*              pNext;
    VkImageLayout      stencilLayout;
} VkAttachmentReferenceStencilLayout;

or the equivalent

// Provided by VK_KHR_separate_depth_stencil_layouts
typedef VkAttachmentReferenceStencilLayout VkAttachmentReferenceStencilLayoutKHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • stencilLayout is a VkImageLayout value specifying the layout the stencil aspect of the attachment uses during the subpass.

Valid Usage

  • VUID-VkAttachmentReferenceStencilLayout-stencilLayout-03318
    stencilLayout must not be VK_IMAGE_LAYOUT_UNDEFINED, VK_IMAGE_LAYOUT_PREINITIALIZED, VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL, VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL, VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL, VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL, VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL, VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL, or VK_IMAGE_LAYOUT_PRESENT_SRC_KHR

Valid Usage (Implicit)

  • VUID-VkAttachmentReferenceStencilLayout-sType-sType
    sType must be VK_STRUCTURE_TYPE_ATTACHMENT_REFERENCE_STENCIL_LAYOUT

  • VUID-VkAttachmentReferenceStencilLayout-stencilLayout-parameter
    stencilLayout must be a valid VkImageLayout value

The VkSubpassDependency2 structure is defined as:

// Provided by VK_VERSION_1_2
typedef struct VkSubpassDependency2 {
    VkStructureType         sType;
    const void*             pNext;
    uint32_t                srcSubpass;
    uint32_t                dstSubpass;
    VkPipelineStageFlags    srcStageMask;
    VkPipelineStageFlags    dstStageMask;
    VkAccessFlags           srcAccessMask;
    VkAccessFlags           dstAccessMask;
    VkDependencyFlags       dependencyFlags;
    int32_t                 viewOffset;
} VkSubpassDependency2;

or the equivalent

// Provided by VK_KHR_create_renderpass2
typedef VkSubpassDependency2 VkSubpassDependency2KHR;

Parameters defined by this structure with the same name as those in VkSubpassDependency have the identical effect to those parameters.

viewOffset has the same effect for the described subpass dependency as VkRenderPassMultiviewCreateInfo::pViewOffsets has on each corresponding subpass dependency.

If a VkMemoryBarrier2 is included in the pNext chain, srcStageMask, dstStageMask, srcAccessMask, and dstAccessMask parameters are ignored. The synchronization and access scopes instead are defined by the parameters of VkMemoryBarrier2.

Valid Usage

  • VUID-VkSubpassDependency2-srcStageMask-04090
    If the geometryShader feature is not enabled, srcStageMask must not contain VK_PIPELINE_STAGE_GEOMETRY_SHADER_BIT

  • VUID-VkSubpassDependency2-srcStageMask-04091
    If the tessellationShader feature is not enabled, srcStageMask must not contain VK_PIPELINE_STAGE_TESSELLATION_CONTROL_SHADER_BIT or VK_PIPELINE_STAGE_TESSELLATION_EVALUATION_SHADER_BIT

  • VUID-VkSubpassDependency2-srcStageMask-04092
    If the conditionalRendering feature is not enabled, srcStageMask must not contain VK_PIPELINE_STAGE_CONDITIONAL_RENDERING_BIT_EXT

  • VUID-VkSubpassDependency2-srcStageMask-04093
    If the fragmentDensityMap feature is not enabled, srcStageMask must not contain VK_PIPELINE_STAGE_FRAGMENT_DENSITY_PROCESS_BIT_EXT

  • VUID-VkSubpassDependency2-srcStageMask-04094
    If the transformFeedback feature is not enabled, srcStageMask must not contain VK_PIPELINE_STAGE_TRANSFORM_FEEDBACK_BIT_EXT

  • VUID-VkSubpassDependency2-srcStageMask-04095
    If the meshShader feature is not enabled, srcStageMask must not contain VK_PIPELINE_STAGE_MESH_SHADER_BIT_EXT

  • VUID-VkSubpassDependency2-srcStageMask-04096
    If the taskShader feature is not enabled, srcStageMask must not contain VK_PIPELINE_STAGE_TASK_SHADER_BIT_EXT

  • VUID-VkSubpassDependency2-srcStageMask-07318
    If neither the shadingRateImage or attachmentFragmentShadingRate are enabled, srcStageMask must not contain VK_PIPELINE_STAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR

  • VUID-VkSubpassDependency2-srcStageMask-03937
    If the synchronization2 feature is not enabled, srcStageMask must not be 0

  • VUID-VkSubpassDependency2-srcStageMask-07949
    If neither the VK_NV_ray_tracing extension or rayTracingPipeline feature are enabled, srcStageMask must not contain VK_PIPELINE_STAGE_RAY_TRACING_SHADER_BIT_KHR

  • VUID-VkSubpassDependency2-dstStageMask-04090
    If the geometryShader feature is not enabled, dstStageMask must not contain VK_PIPELINE_STAGE_GEOMETRY_SHADER_BIT

  • VUID-VkSubpassDependency2-dstStageMask-04091
    If the tessellationShader feature is not enabled, dstStageMask must not contain VK_PIPELINE_STAGE_TESSELLATION_CONTROL_SHADER_BIT or VK_PIPELINE_STAGE_TESSELLATION_EVALUATION_SHADER_BIT

  • VUID-VkSubpassDependency2-dstStageMask-04092
    If the conditionalRendering feature is not enabled, dstStageMask must not contain VK_PIPELINE_STAGE_CONDITIONAL_RENDERING_BIT_EXT

  • VUID-VkSubpassDependency2-dstStageMask-04093
    If the fragmentDensityMap feature is not enabled, dstStageMask must not contain VK_PIPELINE_STAGE_FRAGMENT_DENSITY_PROCESS_BIT_EXT

  • VUID-VkSubpassDependency2-dstStageMask-04094
    If the transformFeedback feature is not enabled, dstStageMask must not contain VK_PIPELINE_STAGE_TRANSFORM_FEEDBACK_BIT_EXT

  • VUID-VkSubpassDependency2-dstStageMask-04095
    If the meshShader feature is not enabled, dstStageMask must not contain VK_PIPELINE_STAGE_MESH_SHADER_BIT_EXT

  • VUID-VkSubpassDependency2-dstStageMask-04096
    If the taskShader feature is not enabled, dstStageMask must not contain VK_PIPELINE_STAGE_TASK_SHADER_BIT_EXT

  • VUID-VkSubpassDependency2-dstStageMask-07318
    If neither the shadingRateImage or attachmentFragmentShadingRate are enabled, dstStageMask must not contain VK_PIPELINE_STAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR

  • VUID-VkSubpassDependency2-dstStageMask-03937
    If the synchronization2 feature is not enabled, dstStageMask must not be 0

  • VUID-VkSubpassDependency2-dstStageMask-07949
    If neither the VK_NV_ray_tracing extension or rayTracingPipeline feature are enabled, dstStageMask must not contain VK_PIPELINE_STAGE_RAY_TRACING_SHADER_BIT_KHR

  • VUID-VkSubpassDependency2-srcSubpass-03084
    srcSubpass must be less than or equal to dstSubpass, unless one of them is VK_SUBPASS_EXTERNAL, to avoid cyclic dependencies and ensure a valid execution order

  • VUID-VkSubpassDependency2-srcSubpass-03085
    srcSubpass and dstSubpass must not both be equal to VK_SUBPASS_EXTERNAL

  • VUID-VkSubpassDependency2-srcSubpass-06810
    If srcSubpass is equal to dstSubpass and srcStageMask includes a framebuffer-space stage, dstStageMask must only contain framebuffer-space stages

  • VUID-VkSubpassDependency2-srcAccessMask-03088
    Any access flag included in srcAccessMask must be supported by one of the pipeline stages in srcStageMask, as specified in the table of supported access types

  • VUID-VkSubpassDependency2-dstAccessMask-03089
    Any access flag included in dstAccessMask must be supported by one of the pipeline stages in dstStageMask, as specified in the table of supported access types

  • VUID-VkSubpassDependency2-dependencyFlags-03090
    If dependencyFlags includes VK_DEPENDENCY_VIEW_LOCAL_BIT, srcSubpass must not be equal to VK_SUBPASS_EXTERNAL

  • VUID-VkSubpassDependency2-dependencyFlags-03091
    If dependencyFlags includes VK_DEPENDENCY_VIEW_LOCAL_BIT, dstSubpass must not be equal to VK_SUBPASS_EXTERNAL

  • VUID-VkSubpassDependency2-srcSubpass-02245
    If srcSubpass equals dstSubpass, and srcStageMask and dstStageMask both include a framebuffer-space stage, then dependencyFlags must include VK_DEPENDENCY_BY_REGION_BIT

  • VUID-VkSubpassDependency2-viewOffset-02530
    If viewOffset is not equal to 0, srcSubpass must not be equal to dstSubpass

  • VUID-VkSubpassDependency2-dependencyFlags-03092
    If dependencyFlags does not include VK_DEPENDENCY_VIEW_LOCAL_BIT, viewOffset must be 0

Valid Usage (Implicit)

  • VUID-VkSubpassDependency2-sType-sType
    sType must be VK_STRUCTURE_TYPE_SUBPASS_DEPENDENCY_2

  • VUID-VkSubpassDependency2-pNext-pNext
    pNext must be NULL or a pointer to a valid instance of VkMemoryBarrier2

  • VUID-VkSubpassDependency2-sType-unique
    The sType value of each struct in the pNext chain must be unique

  • VUID-VkSubpassDependency2-srcStageMask-parameter
    srcStageMask must be a valid combination of VkPipelineStageFlagBits values

  • VUID-VkSubpassDependency2-dstStageMask-parameter
    dstStageMask must be a valid combination of VkPipelineStageFlagBits values

  • VUID-VkSubpassDependency2-srcAccessMask-parameter
    srcAccessMask must be a valid combination of VkAccessFlagBits values

  • VUID-VkSubpassDependency2-dstAccessMask-parameter
    dstAccessMask must be a valid combination of VkAccessFlagBits values

  • VUID-VkSubpassDependency2-dependencyFlags-parameter
    dependencyFlags must be a valid combination of VkDependencyFlagBits values

To destroy a render pass, call:

// Provided by VK_VERSION_1_0
void vkDestroyRenderPass(
    VkDevice                                    device,
    VkRenderPass                                renderPass,
    const VkAllocationCallbacks*                pAllocator);

  • device is the logical device that destroys the render pass.

  • renderPass is the handle of the render pass to destroy.

  • pAllocator controls host memory allocation as described in the Memory Allocation chapter.

Valid Usage

  • VUID-vkDestroyRenderPass-renderPass-00873
    All submitted commands that refer to renderPass must have completed execution

  • VUID-vkDestroyRenderPass-renderPass-00874
    If VkAllocationCallbacks were provided when renderPass was created, a compatible set of callbacks must be provided here

  • VUID-vkDestroyRenderPass-renderPass-00875
    If no VkAllocationCallbacks were provided when renderPass was created, pAllocator must be NULL

Valid Usage (Implicit)

  • VUID-vkDestroyRenderPass-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkDestroyRenderPass-renderPass-parameter
    If renderPass is not VK_NULL_HANDLE, renderPass must be a valid VkRenderPass handle

  • VUID-vkDestroyRenderPass-pAllocator-parameter
    If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure

  • VUID-vkDestroyRenderPass-renderPass-parent
    If renderPass is a valid handle, it must have been created, allocated, or retrieved from device

Host Synchronization

  • Host access to renderPass must be externally synchronized

8.3. Render Pass Compatibility

Framebuffers and graphics pipelines are created based on a specific render pass object. They must only be used with that render pass object, or one compatible with it.

Two attachment references are compatible if they have matching format and sample count, or are both VK_ATTACHMENT_UNUSED or the pointer that would contain the reference is NULL.

Two arrays of attachment references are compatible if all corresponding pairs of attachments are compatible. If the arrays are of different lengths, attachment references not present in the smaller array are treated as VK_ATTACHMENT_UNUSED.

Two render passes are compatible if their corresponding color, input, resolve, and depth/stencil attachment references are compatible and if they are otherwise identical except for:

  • Initial and final image layout in attachment descriptions

  • Load and store operations in attachment descriptions

  • Image layout in attachment references

As an additional special case, if two render passes have a single subpass, the resolve attachment reference and depth/stencil resolve mode compatibility requirements are ignored.

A framebuffer is compatible with a render pass if it was created using the same render pass or a compatible render pass.

8.4. Framebuffers

Render passes operate in conjunction with framebuffers. Framebuffers represent a collection of specific memory attachments that a render pass instance uses.

Framebuffers are represented by VkFramebuffer handles:

// Provided by VK_VERSION_1_0
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkFramebuffer)

To create a framebuffer, call:

// Provided by VK_VERSION_1_0
VkResult vkCreateFramebuffer(
    VkDevice                                    device,
    const VkFramebufferCreateInfo*              pCreateInfo,
    const VkAllocationCallbacks*                pAllocator,
    VkFramebuffer*                              pFramebuffer);

  • device is the logical device that creates the framebuffer.

  • pCreateInfo is a pointer to a VkFramebufferCreateInfo structure describing additional information about framebuffer creation.

  • pAllocator controls host memory allocation as described in the Memory Allocation chapter.

  • pFramebuffer is a pointer to a VkFramebuffer handle in which the resulting framebuffer object is returned.

Valid Usage

  • VUID-vkCreateFramebuffer-device-10002
    device must support at least one queue family with the VK_QUEUE_GRAPHICS_BIT capability

  • VUID-vkCreateFramebuffer-pCreateInfo-02777
    If pCreateInfo->flags does not include VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, and attachmentCount is not 0, each element of pCreateInfo->pAttachments must have been created on device

Valid Usage (Implicit)

  • VUID-vkCreateFramebuffer-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkCreateFramebuffer-pCreateInfo-parameter
    pCreateInfo must be a valid pointer to a valid VkFramebufferCreateInfo structure

  • VUID-vkCreateFramebuffer-pAllocator-parameter
    If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure

  • VUID-vkCreateFramebuffer-pFramebuffer-parameter
    pFramebuffer must be a valid pointer to a VkFramebuffer handle

Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

The VkFramebufferCreateInfo structure is defined as:

// Provided by VK_VERSION_1_0
typedef struct VkFramebufferCreateInfo {
    VkStructureType             sType;
    const void*                 pNext;
    VkFramebufferCreateFlags    flags;
    VkRenderPass                renderPass;
    uint32_t                    attachmentCount;
    const VkImageView*          pAttachments;
    uint32_t                    width;
    uint32_t                    height;
    uint32_t                    layers;
} VkFramebufferCreateInfo;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • flags is a bitmask of VkFramebufferCreateFlagBits

  • renderPass is a render pass defining what render passes the framebuffer will be compatible with. See Render Pass Compatibility for details.

  • attachmentCount is the number of attachments.

  • pAttachments is a pointer to an array of VkImageView handles, each of which will be used as the corresponding attachment in a render pass instance. If flags includes VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, this parameter is ignored.

  • width, height and layers define the dimensions of the framebuffer. If the render pass uses multiview, then layers must be one and each attachment requires a number of layers that is greater than the maximum bit index set in the view mask in the subpasses in which it is used.

It is legal for a subpass to use no color or depth/stencil attachments, either because it has no attachment references or because all of them are VK_ATTACHMENT_UNUSED. This kind of subpass can use shader side effects such as image stores and atomics to produce an output. In this case, the subpass continues to use the width, height, and layers of the framebuffer to define the dimensions of the rendering area, and the rasterizationSamples from each pipeline’s VkPipelineMultisampleStateCreateInfo to define the number of samples used in rasterization; however, if VkPhysicalDeviceFeatures::variableMultisampleRate is VK_FALSE, then all pipelines to be bound with the subpass must have the same value for VkPipelineMultisampleStateCreateInfo::rasterizationSamples. In all such cases, rasterizationSamples must be a valid VkSampleCountFlagBits value that is set in VkPhysicalDeviceLimits::framebufferNoAttachmentsSampleCounts.

Valid Usage

  • VUID-VkFramebufferCreateInfo-attachmentCount-00876
    attachmentCount must be equal to the attachment count specified in renderPass

  • VUID-VkFramebufferCreateInfo-flags-02778
    If flags does not include VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT and attachmentCount is not 0, pAttachments must be a valid pointer to an array of attachmentCount valid VkImageView handles

  • VUID-VkFramebufferCreateInfo-pAttachments-00877
    If flags does not include VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, each element of pAttachments that is used as a color attachment or resolve attachment by renderPass must have been created with a usage value including VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT

  • VUID-VkFramebufferCreateInfo-pAttachments-02633
    If flags does not include VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, each element of pAttachments that is used as a depth/stencil attachment by renderPass must have been created with a usage value including VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT

  • VUID-VkFramebufferCreateInfo-pAttachments-02634
    If flags does not include VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, each element of pAttachments that is used as a depth/stencil resolve attachment by renderPass must have been created with a usage value including VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT

  • VUID-VkFramebufferCreateInfo-pAttachments-00879
    If renderpass is not VK_NULL_HANDLE, flags does not include VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, each element of pAttachments that is used as an input attachment by renderPass must have been created with a usage value including VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT

  • VUID-VkFramebufferCreateInfo-pAttachments-02552
    Each element of pAttachments that is used as a fragment density map attachment by renderPass must not have been created with a flags value including VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT

  • VUID-VkFramebufferCreateInfo-renderPass-02553
    If renderPass has a fragment density map attachment and the fragmentDensityMapNonSubsampledImages feature is not enabled, each element of pAttachments must have been created with a flags value including VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT unless that element is the fragment density map attachment

  • VUID-VkFramebufferCreateInfo-renderPass-06502
    If renderPass was created with fragment density map offsets other than (0,0), each element of pAttachments must have been created with a flags value including VK_IMAGE_CREATE_FRAGMENT_DENSITY_MAP_OFFSET_BIT_QCOM

  • VUID-VkFramebufferCreateInfo-pAttachments-00880
    If flags does not include VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, each element of pAttachments must have been created with a VkFormat value that matches the VkFormat specified by the corresponding VkAttachmentDescription in renderPass

  • VUID-VkFramebufferCreateInfo-pAttachments-00881
    If flags does not include VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, each element of pAttachments must have been created with a samples value that matches the samples value specified by the corresponding VkAttachmentDescription in renderPass

  • VUID-VkFramebufferCreateInfo-flags-04533
    If flags does not include VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, each element of pAttachments that is used as an input, color, resolve, or depth/stencil attachment by renderPass must have been created with a VkImageCreateInfo::extent.width greater than or equal to width

  • VUID-VkFramebufferCreateInfo-flags-04534
    If flags does not include VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, each element of pAttachments that is used as an input, color, resolve, or depth/stencil attachment by renderPass must have been created with a VkImageCreateInfo::extent.height greater than or equal to height

  • VUID-VkFramebufferCreateInfo-flags-04535
    If flags does not include VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, each element of pAttachments that is used as an input, color, resolve, or depth/stencil attachment by renderPass must have been created with a VkImageViewCreateInfo::subresourceRange.layerCount greater than or equal to layers

  • VUID-VkFramebufferCreateInfo-renderPass-04536
    If renderPass was specified with non-zero view masks, each element of pAttachments that is used as an input, color, resolve, or depth/stencil attachment by renderPass must have a layerCount greater than the index of the most significant bit set in any of those view masks

  • VUID-VkFramebufferCreateInfo-renderPass-02746
    Each element of pAttachments that is referenced by fragmentDensityMapAttachment must have a layerCount equal to 1 or if renderPass was specified with non-zero view masks, greater than the index of the most significant bit set in any of those view masks

  • VUID-VkFramebufferCreateInfo-pAttachments-02555
    If flags does not include VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, an element of pAttachments that is referenced by fragmentDensityMapAttachment must have a width at least as large as

  • VUID-VkFramebufferCreateInfo-pAttachments-02556
    If flags does not include VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, an element of pAttachments that is referenced by fragmentDensityMapAttachment must have a height at least as large as

  • VUID-VkFramebufferCreateInfo-flags-04537
    If flags does not include VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, and renderPass was specified with non-zero view masks, each element of pAttachments that is used as a fragment shading rate attachment by renderPass must have a layerCount that is either 1, or greater than the index of the most significant bit set in any of those view masks

  • VUID-VkFramebufferCreateInfo-flags-04538
    If flags does not include VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, and renderPass was not specified with non-zero view masks, each element of pAttachments that is used as a fragment shading rate attachment by renderPass must have a layerCount that is either 1, or greater than layers

  • VUID-VkFramebufferCreateInfo-flags-04539
    If maintenance7 is not enabled or the robustFragmentShadingRateAttachmentAccess limit is VK_FALSE or the imageView member of a VkRenderingFragmentShadingRateAttachmentInfoKHR structure was created with VkImageSubresourceRange::baseMipLevel greater than 0, flags does not include VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, an element of pAttachments that is used as a fragment shading rate attachment must have a width at least as large as ⌈width / texelWidth⌉, where texelWidth is the largest value of shadingRateAttachmentTexelSize.width in a VkFragmentShadingRateAttachmentInfoKHR which references that attachment

  • VUID-VkFramebufferCreateInfo-flags-04540
    If maintenance7 is not enabled or the robustFragmentShadingRateAttachmentAccess limit is VK_FALSE or the imageView member of a VkRenderingFragmentShadingRateAttachmentInfoKHR structure was created with VkImageSubresourceRange::baseMipLevel greater than 0, flags does not include VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, an element of pAttachments that is used as a fragment shading rate attachment must have a height at least as large as ⌈height / texelHeight⌉, where texelHeight is the largest value of shadingRateAttachmentTexelSize.height in a VkFragmentShadingRateAttachmentInfoKHR which references that attachment

  • VUID-VkFramebufferCreateInfo-pAttachments-00883
    If flags does not include VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, each element of pAttachments must only specify a single mip level

  • VUID-VkFramebufferCreateInfo-pAttachments-00884
    If flags does not include VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, each element of pAttachments must have been created with the identity swizzle

  • VUID-VkFramebufferCreateInfo-width-00885
    width must be greater than 0

  • VUID-VkFramebufferCreateInfo-width-00886
    width must be less than or equal to maxFramebufferWidth

  • VUID-VkFramebufferCreateInfo-height-00887
    height must be greater than 0

  • VUID-VkFramebufferCreateInfo-height-00888
    height must be less than or equal to maxFramebufferHeight

  • VUID-VkFramebufferCreateInfo-layers-00889
    layers must be greater than 0

  • VUID-VkFramebufferCreateInfo-layers-00890
    layers must be less than or equal to maxFramebufferLayers

  • VUID-VkFramebufferCreateInfo-renderPass-02531
    If renderPass was specified with non-zero view masks, layers must be 1

  • VUID-VkFramebufferCreateInfo-pAttachments-00891
    If flags does not include VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, each element of pAttachments that is a 2D or 2D array image view taken from a 3D image must not be a depth/stencil format

  • VUID-VkFramebufferCreateInfo-flags-03189
    If the imagelessFramebuffer feature is not enabled, flags must not include VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT

  • VUID-VkFramebufferCreateInfo-flags-03190
    If flags includes VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, the pNext chain must include a VkFramebufferAttachmentsCreateInfo structure

  • VUID-VkFramebufferCreateInfo-flags-03191
    If flags includes VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, the attachmentImageInfoCount member of a VkFramebufferAttachmentsCreateInfo structure in the pNext chain must be equal to either zero or attachmentCount

  • VUID-VkFramebufferCreateInfo-flags-04541
    If flags includes VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, the width member of any element of the pAttachmentImageInfos member of a VkFramebufferAttachmentsCreateInfo structure in the pNext chain that is used as an input, color, resolve or depth/stencil attachment in renderPass must be greater than or equal to width

  • VUID-VkFramebufferCreateInfo-flags-04542
    If flags includes VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, the height member of any element of the pAttachmentImageInfos member of a VkFramebufferAttachmentsCreateInfo structure in the pNext chain that is used as an input, color, resolve or depth/stencil attachment in renderPass must be greater than or equal to height

  • VUID-VkFramebufferCreateInfo-flags-03196
    If flags includes VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, the width member of any element of the pAttachmentImageInfos member of a VkFramebufferAttachmentsCreateInfo structure in the pNext chain that is referenced by VkRenderPassFragmentDensityMapCreateInfoEXT::fragmentDensityMapAttachment in renderPass must be greater than or equal to

  • VUID-VkFramebufferCreateInfo-flags-03197
    If flags includes VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, the height member of any element of the pAttachmentImageInfos member of a VkFramebufferAttachmentsCreateInfo structure included in the pNext chain that is referenced by VkRenderPassFragmentDensityMapCreateInfoEXT::fragmentDensityMapAttachment in renderPass must be greater than or equal to

  • VUID-VkFramebufferCreateInfo-flags-04543
    If maintenance7 is not enabled or the robustFragmentShadingRateAttachmentAccess limit is VK_FALSE or the imageView member of a VkRenderingFragmentShadingRateAttachmentInfoKHR structure was created with VkImageSubresourceRange::baseMipLevel greater than 0, and flags includes VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, the width member of any element of the pAttachmentImageInfos member of a VkFramebufferAttachmentsCreateInfo structure in the pNext chain that is used as a fragment shading rate attachment must be greater than or equal to ⌈width / texelWidth⌉, where texelWidth is the largest value of shadingRateAttachmentTexelSize.width in a VkFragmentShadingRateAttachmentInfoKHR which references that attachment

  • VUID-VkFramebufferCreateInfo-flags-04544
    If maintenance7 is not enabled or the robustFragmentShadingRateAttachmentAccess limit is VK_FALSE or the imageView member of a VkRenderingFragmentShadingRateAttachmentInfoKHR structure was created with VkImageSubresourceRange::baseMipLevel greater than 0, and flags includes VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, the height member of any element of the pAttachmentImageInfos member of a VkFramebufferAttachmentsCreateInfo structure in the pNext chain that is used as a fragment shading rate attachment must be greater than or equal to ⌈height / texelHeight⌉, where texelHeight is the largest value of shadingRateAttachmentTexelSize.height in a VkFragmentShadingRateAttachmentInfoKHR which references that attachment

  • VUID-VkFramebufferCreateInfo-flags-04545
    If flags includes VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, the layerCount member of any element of the pAttachmentImageInfos member of a VkFramebufferAttachmentsCreateInfo structure in the pNext chain that is used as a fragment shading rate attachment must be either 1, or greater than or equal to layers

  • VUID-VkFramebufferCreateInfo-flags-04587
    If flags includes VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT and renderPass was specified with non-zero view masks, the layerCount member of any element of the pAttachmentImageInfos member of a VkFramebufferAttachmentsCreateInfo structure in the pNext chain that is used as a fragment shading rate attachment must be either 1, or greater than the index of the most significant bit set in any of those view masks

  • VUID-VkFramebufferCreateInfo-renderPass-03198
    If multiview is enabled for renderPass and flags includes VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, the layerCount member of any element of the pAttachmentImageInfos member of a VkFramebufferAttachmentsCreateInfo structure included in the pNext chain used as an input, color, resolve, or depth/stencil attachment in renderPass must be greater than the maximum bit index set in the view mask in the subpasses in which it is used in renderPass

  • VUID-VkFramebufferCreateInfo-renderPass-04546
    If multiview is not enabled for renderPass and flags includes VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, the layerCount member of any element of the pAttachmentImageInfos member of a VkFramebufferAttachmentsCreateInfo structure included in the pNext chain used as an input, color, resolve, or depth/stencil attachment in renderPass must be greater than or equal to layers

  • VUID-VkFramebufferCreateInfo-flags-03201
    If flags includes VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, the usage member of any element of the pAttachmentImageInfos member of a VkFramebufferAttachmentsCreateInfo structure included in the pNext chain that refers to an attachment used as a color attachment or resolve attachment by renderPass must include VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT

  • VUID-VkFramebufferCreateInfo-flags-03202
    If flags includes VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, the usage member of any element of the pAttachmentImageInfos member of a VkFramebufferAttachmentsCreateInfo structure included in the pNext chain that refers to an attachment used as a depth/stencil attachment by renderPass must include VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT

  • VUID-VkFramebufferCreateInfo-flags-03203
    If flags includes VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, the usage member of any element of the pAttachmentImageInfos member of a VkFramebufferAttachmentsCreateInfo structure included in the pNext chain that refers to an attachment used as a depth/stencil resolve attachment by renderPass must include VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT

  • VUID-VkFramebufferCreateInfo-flags-03204
    If flags includes VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, the usage member of any element of the pAttachmentImageInfos member of a VkFramebufferAttachmentsCreateInfo structure included in the pNext chain that refers to an attachment used as an input attachment by renderPass must include VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT

  • VUID-VkFramebufferCreateInfo-flags-03205
    If flags includes VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, at least one element of the pViewFormats member of any element of the pAttachmentImageInfos member of a VkFramebufferAttachmentsCreateInfo structure included in the pNext chain must be equal to the corresponding value of VkAttachmentDescription::format used to create renderPass

  • VUID-VkFramebufferCreateInfo-flags-04113
    If flags does not include VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, each element of pAttachments must have been created with VkImageViewCreateInfo::viewType not equal to VK_IMAGE_VIEW_TYPE_3D

  • VUID-VkFramebufferCreateInfo-flags-04548
    If flags does not include VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, each element of pAttachments that is used as a fragment shading rate attachment by renderPass must have been created with a usage value including VK_IMAGE_USAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR

  • VUID-VkFramebufferCreateInfo-flags-04549
    If flags includes VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, the usage member of any element of the pAttachmentImageInfos member of a VkFramebufferAttachmentsCreateInfo structure included in the pNext chain that refers to an attachment used as a fragment shading rate attachment by renderPass must include VK_IMAGE_USAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR

  • VUID-VkFramebufferCreateInfo-samples-06881
    If multisampled-render-to-single-sampled is enabled for any subpass, all color, depth/stencil and input attachments used in that subpass which have VkAttachmentDescription::samples or VkAttachmentDescription2::samples equal to VK_SAMPLE_COUNT_1_BIT must have been created with VK_IMAGE_CREATE_MULTISAMPLED_RENDER_TO_SINGLE_SAMPLED_BIT_EXT in their VkImageCreateInfo::flags

  • VUID-VkFramebufferCreateInfo-samples-07009
    If multisampled-render-to-single-sampled is enabled for any subpass, all color, depth/stencil and input attachments used in that subpass which have VkAttachmentDescription::samples or VkAttachmentDescription2::samples equal to VK_SAMPLE_COUNT_1_BIT must have a format that supports the sample count specified in VkMultisampledRenderToSingleSampledInfoEXT::rasterizationSamples

  • VUID-VkFramebufferCreateInfo-nullColorAttachmentWithExternalFormatResolve-09349
    If the nullColorAttachmentWithExternalFormatResolve is VK_FALSE, and flags does not include VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, the format of the color attachment for each subpass in renderPass that includes an external format image as a resolve attachment must have a format equal to the value of VkAndroidHardwareBufferFormatResolvePropertiesANDROID::colorAttachmentFormat as returned by a call to vkGetAndroidHardwareBufferPropertiesANDROID for the Android hardware buffer that was used to create the image view use as its resolve attachment

  • VUID-VkFramebufferCreateInfo-pAttachments-09350
    If flags does not include VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, then if an element of pAttachments has a format of VK_FORMAT_UNDEFINED, it must have been created with a VkExternalFormatANDROID::externalFormat value identical to that provided in the VkExternalFormatANDROID::externalFormat specified by the corresponding VkAttachmentDescription2 in renderPass

Valid Usage (Implicit)

  • VUID-VkFramebufferCreateInfo-sType-sType
    sType must be VK_STRUCTURE_TYPE_FRAMEBUFFER_CREATE_INFO

  • VUID-VkFramebufferCreateInfo-pNext-pNext
    pNext must be NULL or a pointer to a valid instance of VkFramebufferAttachmentsCreateInfo

  • VUID-VkFramebufferCreateInfo-sType-unique
    The sType value of each struct in the pNext chain must be unique

  • VUID-VkFramebufferCreateInfo-flags-parameter
    flags must be a valid combination of VkFramebufferCreateFlagBits values

  • VUID-VkFramebufferCreateInfo-renderPass-parameter
    renderPass must be a valid VkRenderPass handle

  • VUID-VkFramebufferCreateInfo-commonparent
    Both of renderPass, and the elements of pAttachments that are valid handles of non-ignored parameters must have been created, allocated, or retrieved from the same VkDevice

The VkFramebufferAttachmentsCreateInfo structure is defined as:

// Provided by VK_VERSION_1_2
typedef struct VkFramebufferAttachmentsCreateInfo {
    VkStructureType                            sType;
    const void*                                pNext;
    uint32_t                                   attachmentImageInfoCount;
    const VkFramebufferAttachmentImageInfo*    pAttachmentImageInfos;
} VkFramebufferAttachmentsCreateInfo;

or the equivalent

// Provided by VK_KHR_imageless_framebuffer
typedef VkFramebufferAttachmentsCreateInfo VkFramebufferAttachmentsCreateInfoKHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • attachmentImageInfoCount is the number of attachments being described.

  • pAttachmentImageInfos is a pointer to an array of VkFramebufferAttachmentImageInfo structures, each structure describing a number of parameters of the corresponding attachment in a render pass instance.

Valid Usage (Implicit)

  • VUID-VkFramebufferAttachmentsCreateInfo-sType-sType
    sType must be VK_STRUCTURE_TYPE_FRAMEBUFFER_ATTACHMENTS_CREATE_INFO

  • VUID-VkFramebufferAttachmentsCreateInfo-pAttachmentImageInfos-parameter
    If attachmentImageInfoCount is not 0, pAttachmentImageInfos must be a valid pointer to an array of attachmentImageInfoCount valid VkFramebufferAttachmentImageInfo structures

The VkFramebufferAttachmentImageInfo structure is defined as:

// Provided by VK_VERSION_1_2
typedef struct VkFramebufferAttachmentImageInfo {
    VkStructureType       sType;
    const void*           pNext;
    VkImageCreateFlags    flags;
    VkImageUsageFlags     usage;
    uint32_t              width;
    uint32_t              height;
    uint32_t              layerCount;
    uint32_t              viewFormatCount;
    const VkFormat*       pViewFormats;
} VkFramebufferAttachmentImageInfo;

or the equivalent

// Provided by VK_KHR_imageless_framebuffer
typedef VkFramebufferAttachmentImageInfo VkFramebufferAttachmentImageInfoKHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • flags is a bitmask of VkImageCreateFlagBits, matching the value of VkImageCreateInfo::flags used to create an image that will be used with this framebuffer.

  • usage is a bitmask of VkImageUsageFlagBits, matching the value of VkImageCreateInfo::usage used to create an image used with this framebuffer.

  • width is the width of the image view used for rendering.

  • height is the height of the image view used for rendering.

  • layerCount is the number of array layers of the image view used for rendering.

  • viewFormatCount is the number of entries in the pViewFormats array, matching the value of VkImageFormatListCreateInfo::viewFormatCount used to create an image used with this framebuffer.

  • pViewFormats is a pointer to an array of VkFormat values specifying all of the formats which can be used when creating views of the image, matching the value of VkImageFormatListCreateInfo::pViewFormats used to create an image used with this framebuffer.

Images that can be used with the framebuffer when beginning a render pass, as specified by VkRenderPassAttachmentBeginInfo, must be created with parameters that are identical to those specified here.

Valid Usage

  • VUID-VkFramebufferAttachmentImageInfo-viewFormatCount-09536
    If viewFormatCount is not 0, and the render pass is not being used with an external format resolve attachment, each element of pViewFormats must not be VK_FORMAT_UNDEFINED

Valid Usage (Implicit)

  • VUID-VkFramebufferAttachmentImageInfo-sType-sType
    sType must be VK_STRUCTURE_TYPE_FRAMEBUFFER_ATTACHMENT_IMAGE_INFO

  • VUID-VkFramebufferAttachmentImageInfo-pNext-pNext
    pNext must be NULL

  • VUID-VkFramebufferAttachmentImageInfo-flags-parameter
    flags must be a valid combination of VkImageCreateFlagBits values

  • VUID-VkFramebufferAttachmentImageInfo-usage-parameter
    usage must be a valid combination of VkImageUsageFlagBits values

  • VUID-VkFramebufferAttachmentImageInfo-usage-requiredbitmask
    usage must not be 0

  • VUID-VkFramebufferAttachmentImageInfo-pViewFormats-parameter
    If viewFormatCount is not 0, pViewFormats must be a valid pointer to an array of viewFormatCount valid VkFormat values

Bits which can be set in VkFramebufferCreateInfo::flags, specifying options for framebuffers, are:

// Provided by VK_VERSION_1_0
typedef enum VkFramebufferCreateFlagBits {
  // Provided by VK_VERSION_1_2
    VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT = 0x00000001,
  // Provided by VK_KHR_imageless_framebuffer
    VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT_KHR = VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT,
} VkFramebufferCreateFlagBits;

  • VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT specifies that image views are not specified, and only attachment compatibility information will be provided via a VkFramebufferAttachmentImageInfo structure.

// Provided by VK_VERSION_1_0
typedef VkFlags VkFramebufferCreateFlags;

VkFramebufferCreateFlags is a bitmask type for setting a mask of zero or more VkFramebufferCreateFlagBits.

To destroy a framebuffer, call:

// Provided by VK_VERSION_1_0
void vkDestroyFramebuffer(
    VkDevice                                    device,
    VkFramebuffer                               framebuffer,
    const VkAllocationCallbacks*                pAllocator);

  • device is the logical device that destroys the framebuffer.

  • framebuffer is the handle of the framebuffer to destroy.

  • pAllocator controls host memory allocation as described in the Memory Allocation chapter.

Valid Usage

  • VUID-vkDestroyFramebuffer-framebuffer-00892
    All submitted commands that refer to framebuffer must have completed execution

  • VUID-vkDestroyFramebuffer-framebuffer-00893
    If VkAllocationCallbacks were provided when framebuffer was created, a compatible set of callbacks must be provided here

  • VUID-vkDestroyFramebuffer-framebuffer-00894
    If no VkAllocationCallbacks were provided when framebuffer was created, pAllocator must be NULL

Valid Usage (Implicit)

  • VUID-vkDestroyFramebuffer-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkDestroyFramebuffer-framebuffer-parameter
    If framebuffer is not VK_NULL_HANDLE, framebuffer must be a valid VkFramebuffer handle

  • VUID-vkDestroyFramebuffer-pAllocator-parameter
    If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure

  • VUID-vkDestroyFramebuffer-framebuffer-parent
    If framebuffer is a valid handle, it must have been created, allocated, or retrieved from device

Host Synchronization

  • Host access to framebuffer must be externally synchronized

8.5. Render Pass Load Operations

Render pass load operations define the initial values of an attachment during a render pass instance.

Load operations for attachments with a depth/stencil format execute in the VK_PIPELINE_STAGE_EARLY_FRAGMENT_TESTS_BIT pipeline stage. Load operations for attachments with a color format execute in the VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT pipeline stage. The load operation for each sample in an attachment happens-before any recorded command which accesses the sample in that render pass instance via that attachment or an alias.

Note

Because load operations always happen first, external synchronization with attachment access only needs to synchronize the load operations with previous commands; not the operations within the render pass instance. This does not apply when using VK_ATTACHMENT_LOAD_OP_NONE_KHR.

Load operations only update values within the defined render area for the render pass instance. However, any writes performed by a load operation (as defined by its access masks) to a given attachment may read and write back any memory locations within the image subresource bound for that attachment. For depth/stencil images, if maintenance7 is not enabled on the device or separateDepthStencilAttachmentAccess is VK_FALSE, writes to one aspect may also result in read-modify-write operations for the other aspect. If the subresource is in the VK_IMAGE_LAYOUT_ATTACHMENT_FEEDBACK_LOOP_OPTIMAL_EXT layout, implementations must not access pixels outside of the render area.

Note

As entire subresources could be accessed by load operations, applications cannot safely access values outside of the render area during a render pass instance when a load operation that modifies values is used.

Load operations that can be used for a render pass are:

// Provided by VK_VERSION_1_0
typedef enum VkAttachmentLoadOp {
    VK_ATTACHMENT_LOAD_OP_LOAD = 0,
    VK_ATTACHMENT_LOAD_OP_CLEAR = 1,
    VK_ATTACHMENT_LOAD_OP_DONT_CARE = 2,
  // Provided by VK_KHR_load_store_op_none
    VK_ATTACHMENT_LOAD_OP_NONE_KHR = 1000400000,
  // Provided by VK_EXT_load_store_op_none
    VK_ATTACHMENT_LOAD_OP_NONE_EXT = VK_ATTACHMENT_LOAD_OP_NONE_KHR,
} VkAttachmentLoadOp;

  • VK_ATTACHMENT_LOAD_OP_LOAD specifies that the previous contents of the image within the render area will be preserved as the initial values. For attachments with a depth/stencil format, this uses the access type VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_READ_BIT. For attachments with a color format, this uses the access type VK_ACCESS_COLOR_ATTACHMENT_READ_BIT.

  • VK_ATTACHMENT_LOAD_OP_CLEAR specifies that the contents within the render area will be cleared to a uniform value, which is specified when a render pass instance is begun. For attachments with a depth/stencil format, this uses the access type VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_WRITE_BIT. For attachments with a color format, this uses the access type VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT.

  • VK_ATTACHMENT_LOAD_OP_DONT_CARE specifies that the previous contents within the area need not be preserved; the contents of the attachment will be undefined inside the render area. For attachments with a depth/stencil format, this uses the access type VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_WRITE_BIT. For attachments with a color format, this uses the access type VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT.

  • VK_ATTACHMENT_LOAD_OP_NONE_KHR specifies that the previous contents of the image will be undefined inside the render pass. No access type is used as the image is not accessed.

During a render pass instance, input and color attachments with color formats that have a component size of 8, 16, or 32 bits must be represented in the attachment’s format throughout the instance. Attachments with other floating- or fixed-point color formats, or with depth components may be represented in a format with a precision higher than the attachment format, but must be represented with the same range. When such a component is loaded via the loadOp, it will be converted into an implementation-dependent format used by the render pass. Such components must be converted from the render pass format, to the format of the attachment, before they are resolved or stored at the end of a render pass instance via storeOp. Conversions occur as described in Numeric Representation and Computation and Fixed-Point Data Conversions.

8.6. Render Pass Store Operations

Render pass store operations define how values written to an attachment during a render pass instance are stored to memory.

Store operations for attachments with a depth/stencil format execute in the VK_PIPELINE_STAGE_LATE_FRAGMENT_TESTS_BIT pipeline stage. Store operations for attachments with a color format execute in the VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT pipeline stage. The store operation for each sample in an attachment happens-after any recorded command which accesses the sample via that attachment or an alias.

Note

Because store operations always happen after other accesses in a render pass instance, external synchronization with attachment access in an earlier render pass only needs to synchronize with the store operations; not the operations within the render pass instance. This does not apply when using VK_ATTACHMENT_STORE_OP_NONE.

Store operations only update values within the defined render area for the render pass instance. However, any writes performed by a store operation (as defined by its access masks) to a given attachment may read and write back any memory locations within the image subresource bound for that attachment. For depth/stencil images, if separateDepthStencilAttachmentAccess is VK_FALSE, writes to one aspect may also result in read-modify-write operations for the other aspect. If the subresource is in the VK_IMAGE_LAYOUT_ATTACHMENT_FEEDBACK_LOOP_OPTIMAL_EXT layout, implementations must not access pixels outside of the render area.

Note

As entire subresources could be accessed by store operations, applications cannot safely access values outside of the render area via aliased resources during a render pass instance when a store operation that modifies values is used.

Possible values of VkAttachmentDescription::storeOp and stencilStoreOp, specifying how the contents of the attachment are treated, are:

// Provided by VK_VERSION_1_0
typedef enum VkAttachmentStoreOp {
    VK_ATTACHMENT_STORE_OP_STORE = 0,
    VK_ATTACHMENT_STORE_OP_DONT_CARE = 1,
  // Provided by VK_VERSION_1_3
    VK_ATTACHMENT_STORE_OP_NONE = 1000301000,
  // Provided by VK_KHR_dynamic_rendering, VK_KHR_load_store_op_none
    VK_ATTACHMENT_STORE_OP_NONE_KHR = VK_ATTACHMENT_STORE_OP_NONE,
  // Provided by VK_QCOM_render_pass_store_ops
    VK_ATTACHMENT_STORE_OP_NONE_QCOM = VK_ATTACHMENT_STORE_OP_NONE,
  // Provided by VK_EXT_load_store_op_none
    VK_ATTACHMENT_STORE_OP_NONE_EXT = VK_ATTACHMENT_STORE_OP_NONE,
} VkAttachmentStoreOp;

  • VK_ATTACHMENT_STORE_OP_STORE specifies the contents generated during the render pass and within the render area are written to memory. For attachments with a depth/stencil format, this uses the access type VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_WRITE_BIT. For attachments with a color format, this uses the access type VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT.

  • VK_ATTACHMENT_STORE_OP_DONT_CARE specifies the contents within the render area are not needed after rendering, and may be discarded; the contents of the attachment will be undefined inside the render area. For attachments with a depth/stencil format, this uses the access type VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_WRITE_BIT. For attachments with a color format, this uses the access type VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT.

  • VK_ATTACHMENT_STORE_OP_NONE specifies the contents within the render area are not accessed by the store operation as long as no values are written to the attachment during the render pass. If values are written during the render pass, this behaves identically to VK_ATTACHMENT_STORE_OP_DONT_CARE and with matching access semantics.

Note

VK_ATTACHMENT_STORE_OP_DONT_CARE can cause contents generated during previous render passes to be discarded before reaching memory, even if no write to the attachment occurs during the current render pass.

8.7. Render Pass Multisample Resolve Operations

Render pass multisample resolve operations combine sample values from a single pixel in a multisample attachment and store the result to the corresponding pixel in a single sample attachment.

Multisample resolve operations for attachments execute in the VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT pipeline stage. A final resolve operation for all pixels in the render area happens-after any recorded command which writes a pixel via the multisample attachment to be resolved or an explicit alias of it in the subpass that it is specified. Any single sample attachment specified for use in a multisample resolve operation may have its contents modified at any point once rendering begins for the render pass instance. Reads from the multisample attachment can be synchronized with VK_ACCESS_COLOR_ATTACHMENT_READ_BIT. Access to the single sample attachment can be synchronized with VK_ACCESS_COLOR_ATTACHMENT_READ_BIT and VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT. These pipeline stage and access types are used whether the attachments are color or depth/stencil attachments.

When using render pass objects, a subpass dependency specified with the above pipeline stages and access flags will ensure synchronization with multisample resolve operations for any attachments that were last accessed by that subpass. This allows later subpasses to read resolved values as input attachments.

Resolve operations only update values within the defined render area for the render pass instance. However, any writes performed by a resolve operation (as defined by its access masks) to a given attachment may read and write back any memory locations within the image subresource bound for that attachment. For depth/stencil images, if separateDepthStencilAttachmentAccess is VK_FALSE, writes to one aspect may also result in read-modify-write operations for the other aspect. If the subresource is in the VK_IMAGE_LAYOUT_ATTACHMENT_FEEDBACK_LOOP_OPTIMAL_EXT layout, implementations must not access pixels outside of the render area.

Note

As entire subresources could be accessed by multisample resolve operations, applications cannot safely access values outside of the render area via aliased resources during a render pass instance when a multisample resolve operation is performed.

Multisample values in a multisample attachment are combined according to the resolve mode used:

// Provided by VK_VERSION_1_2
typedef enum VkResolveModeFlagBits {
    VK_RESOLVE_MODE_NONE = 0,
    VK_RESOLVE_MODE_SAMPLE_ZERO_BIT = 0x00000001,
    VK_RESOLVE_MODE_AVERAGE_BIT = 0x00000002,
    VK_RESOLVE_MODE_MIN_BIT = 0x00000004,
    VK_RESOLVE_MODE_MAX_BIT = 0x00000008,
  // Provided by VK_ANDROID_external_format_resolve with VK_KHR_dynamic_rendering or VK_VERSION_1_3
    VK_RESOLVE_MODE_EXTERNAL_FORMAT_DOWNSAMPLE_ANDROID = 0x00000010,
  // Provided by VK_KHR_depth_stencil_resolve
    VK_RESOLVE_MODE_NONE_KHR = VK_RESOLVE_MODE_NONE,
  // Provided by VK_KHR_depth_stencil_resolve
    VK_RESOLVE_MODE_SAMPLE_ZERO_BIT_KHR = VK_RESOLVE_MODE_SAMPLE_ZERO_BIT,
  // Provided by VK_KHR_depth_stencil_resolve
    VK_RESOLVE_MODE_AVERAGE_BIT_KHR = VK_RESOLVE_MODE_AVERAGE_BIT,
  // Provided by VK_KHR_depth_stencil_resolve
    VK_RESOLVE_MODE_MIN_BIT_KHR = VK_RESOLVE_MODE_MIN_BIT,
  // Provided by VK_KHR_depth_stencil_resolve
    VK_RESOLVE_MODE_MAX_BIT_KHR = VK_RESOLVE_MODE_MAX_BIT,
} VkResolveModeFlagBits;

or the equivalent

// Provided by VK_KHR_depth_stencil_resolve
typedef VkResolveModeFlagBits VkResolveModeFlagBitsKHR;

  • VK_RESOLVE_MODE_NONE indicates that no resolve operation is done.

  • VK_RESOLVE_MODE_SAMPLE_ZERO_BIT indicates that result of the resolve operation is equal to the value of sample 0.

  • VK_RESOLVE_MODE_AVERAGE_BIT indicates that result of the resolve operation is the average of the sample values.

  • VK_RESOLVE_MODE_MIN_BIT indicates that result of the resolve operation is the minimum of the sample values.

  • VK_RESOLVE_MODE_MAX_BIT indicates that result of the resolve operation is the maximum of the sample values.

  • VK_RESOLVE_MODE_EXTERNAL_FORMAT_DOWNSAMPLE_ANDROID indicates that rather than a multisample resolve, a single sampled color attachment will be downsampled into a Y′CBCR format image specified by an external Android format. Unlike other resolve modes, implementations can resolve multiple times during rendering, or even bypass writing to the color attachment altogether, as long as the final value is resolved to the resolve attachment. Values in the G, B, and R channels of the color attachment will be written to the Y, CB, and CR channels of the external format image, respectively. Chroma values are calculated as if sampling with a linear filter from the color attachment at full rate, at the location the chroma values sit according to VkPhysicalDeviceExternalFormatResolvePropertiesANDROID::chromaOffsetX, VkPhysicalDeviceExternalFormatResolvePropertiesANDROID::chromaOffsetY, and the chroma sample rate of the resolved image.

If no resolve mode is otherwise specified, VK_RESOLVE_MODE_AVERAGE_BIT is used.

Note

No range compression or Y′CBCR model conversion is performed by VK_RESOLVE_MODE_EXTERNAL_FORMAT_DOWNSAMPLE_ANDROID; applications have to do these conversions themselves. Value outputs are expected to match those that would be read through a Y′CBCR sampler using VK_SAMPLER_YCBCR_MODEL_CONVERSION_RGB_IDENTITY. The color space that the values should be in is defined by the platform and is not exposed via Vulkan.

 
// Provided by VK_VERSION_1_2
typedef VkFlags VkResolveModeFlags;

or the equivalent

// Provided by VK_KHR_depth_stencil_resolve
typedef VkResolveModeFlags VkResolveModeFlagsKHR;

VkResolveModeFlags is a bitmask type for setting a mask of zero or more VkResolveModeFlagBits.

8.8. Render Pass Commands

An application records the commands for a render pass instance one subpass at a time, by beginning a render pass instance, iterating over the subpasses to record commands for that subpass, and then ending the render pass instance.

To begin a render pass instance, call:

// Provided by VK_VERSION_1_0
void vkCmdBeginRenderPass(
    VkCommandBuffer                             commandBuffer,
    const VkRenderPassBeginInfo*                pRenderPassBegin,
    VkSubpassContents                           contents);

  • commandBuffer is the command buffer in which to record the command.

  • pRenderPassBegin is a pointer to a VkRenderPassBeginInfo structure specifying the render pass to begin an instance of, and the framebuffer the instance uses.

  • contents is a VkSubpassContents value specifying how the commands in the first subpass will be provided.

After beginning a render pass instance, the command buffer is ready to record the commands for the first subpass of that render pass.

Valid Usage

  • VUID-vkCmdBeginRenderPass-initialLayout-00895
    If any of the initialLayout or finalLayout member of the VkAttachmentDescription structures or the layout member of the VkAttachmentReference structures specified when creating the render pass specified in the renderPass member of pRenderPassBegin is VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL then the corresponding attachment image view of the framebuffer specified in the framebuffer member of pRenderPassBegin must have been created with a usage value including VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT

  • VUID-vkCmdBeginRenderPass-initialLayout-01758
    If any of the initialLayout or finalLayout member of the VkAttachmentDescription structures or the layout member of the VkAttachmentReference structures specified when creating the render pass specified in the renderPass member of pRenderPassBegin is VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL, VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL, VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL, or VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL then the corresponding attachment image view of the framebuffer specified in the framebuffer member of pRenderPassBegin must have been created with a usage value including VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT

  • VUID-vkCmdBeginRenderPass-initialLayout-02842
    If any of the initialLayout or finalLayout member of the VkAttachmentDescription structures or the layout member of the VkAttachmentReference structures specified when creating the render pass specified in the renderPass member of pRenderPassBegin is VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL, or VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL, or VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL then the corresponding attachment image view of the framebuffer specified in the framebuffer member of pRenderPassBegin must have been created with a usage value including VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT

  • VUID-vkCmdBeginRenderPass-stencilInitialLayout-02843
    If any of the stencilInitialLayout or stencilFinalLayout member of the VkAttachmentDescriptionStencilLayout structures or the stencilLayout member of the VkAttachmentReferenceStencilLayout structures specified when creating the render pass specified in the renderPass member of pRenderPassBegin is VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL, or VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL then the corresponding attachment image view of the framebuffer specified in the framebuffer member of pRenderPassBegin must have been created with a usage value including VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT

  • VUID-vkCmdBeginRenderPass-initialLayout-00897
    If any of the initialLayout or finalLayout member of the VkAttachmentDescription structures or the layout member of the VkAttachmentReference structures specified when creating the render pass specified in the renderPass member of pRenderPassBegin is VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL then the corresponding attachment image view of the framebuffer specified in the framebuffer member of pRenderPassBegin must have been created with a usage value including VK_IMAGE_USAGE_SAMPLED_BIT or VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT

  • VUID-vkCmdBeginRenderPass-initialLayout-00898
    If any of the initialLayout or finalLayout member of the VkAttachmentDescription structures or the layout member of the VkAttachmentReference structures specified when creating the render pass specified in the renderPass member of pRenderPassBegin is VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL then the corresponding attachment image view of the framebuffer specified in the framebuffer member of pRenderPassBegin must have been created with a usage value including VK_IMAGE_USAGE_TRANSFER_SRC_BIT

  • VUID-vkCmdBeginRenderPass-initialLayout-00899
    If any of the initialLayout or finalLayout member of the VkAttachmentDescription structures or the layout member of the VkAttachmentReference structures specified when creating the render pass specified in the renderPass member of pRenderPassBegin is VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL then the corresponding attachment image view of the framebuffer specified in the framebuffer member of pRenderPassBegin must have been created with a usage value including VK_IMAGE_USAGE_TRANSFER_DST_BIT

  • VUID-vkCmdBeginRenderPass-initialLayout-00900
    If the initialLayout member of any of the VkAttachmentDescription structures specified when creating the render pass specified in the renderPass member of pRenderPassBegin is not VK_IMAGE_LAYOUT_UNDEFINED, then each such initialLayout must be equal to the current layout of the corresponding attachment image subresource of the framebuffer specified in the framebuffer member of pRenderPassBegin

  • VUID-vkCmdBeginRenderPass-srcStageMask-06451
    The srcStageMask members of any element of the pDependencies member of VkRenderPassCreateInfo used to create renderPass must be supported by the capabilities of the queue family identified by the queueFamilyIndex member of the VkCommandPoolCreateInfo used to create the command pool which commandBuffer was allocated from

  • VUID-vkCmdBeginRenderPass-dstStageMask-06452
    The dstStageMask members of any element of the pDependencies member of VkRenderPassCreateInfo used to create renderPass must be supported by the capabilities of the queue family identified by the queueFamilyIndex member of the VkCommandPoolCreateInfo used to create the command pool which commandBuffer was allocated from

  • VUID-vkCmdBeginRenderPass-framebuffer-02532
    For any attachment in framebuffer that is used by renderPass and is bound to memory locations that are also bound to another attachment used by renderPass, and if at least one of those uses causes either attachment to be written to, both attachments must have had the VK_ATTACHMENT_DESCRIPTION_MAY_ALIAS_BIT set

  • VUID-vkCmdBeginRenderPass-framebuffer-09045
    If any attachments specified in framebuffer are used by renderPass and are bound to overlapping memory locations, there must be only one that is used as a color attachment, depth/stencil, or resolve attachment in any subpass

  • VUID-vkCmdBeginRenderPass-initialLayout-07000
    If any of the initialLayout or finalLayout member of the VkAttachmentDescription structures or the layout member of the VkAttachmentReference structures specified when creating the render pass specified in the renderPass member of pRenderPassBegin is VK_IMAGE_LAYOUT_ATTACHMENT_FEEDBACK_LOOP_OPTIMAL_EXT then the corresponding attachment image view of the framebuffer specified in the framebuffer member of pRenderPassBegin must have been created with a usage value including either the VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT or VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT and either the VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT or VK_IMAGE_USAGE_SAMPLED_BIT usage bits

  • VUID-vkCmdBeginRenderPass-initialLayout-07001
    If any of the initialLayout or finalLayout member of the VkAttachmentDescription structures or the layout member of the VkAttachmentReference structures specified when creating the render pass specified in the renderPass member of pRenderPassBegin is VK_IMAGE_LAYOUT_ATTACHMENT_FEEDBACK_LOOP_OPTIMAL_EXT then the corresponding attachment image view of the framebuffer specified in the framebuffer member of pRenderPassBegin must have been created with a usage value the VK_IMAGE_USAGE_ATTACHMENT_FEEDBACK_LOOP_BIT_EXT usage bit

  • VUID-vkCmdBeginRenderPass-initialLayout-09537
    If any of the initialLayout or finalLayout member of the VkAttachmentDescription structures or the layout member of the VkAttachmentReference structures specified when creating the render pass specified in the renderPass member of pRenderPassBegin is VK_IMAGE_LAYOUT_RENDERING_LOCAL_READ_KHR then the corresponding attachment image view of the framebuffer specified in the framebuffer member of pRenderPassBegin must have been created with a usage value including either VK_IMAGE_USAGE_STORAGE_BIT, or both VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT and either of VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT or VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT

  • VUID-vkCmdBeginRenderPass-contents-09640
    If contents is VK_SUBPASS_CONTENTS_INLINE_AND_SECONDARY_COMMAND_BUFFERS_KHR, then at least one of the following features must be enabled:

Valid Usage (Implicit)

  • VUID-vkCmdBeginRenderPass-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdBeginRenderPass-pRenderPassBegin-parameter
    pRenderPassBegin must be a valid pointer to a valid VkRenderPassBeginInfo structure

  • VUID-vkCmdBeginRenderPass-contents-parameter
    contents must be a valid VkSubpassContents value

  • VUID-vkCmdBeginRenderPass-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdBeginRenderPass-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support graphics operations

  • VUID-vkCmdBeginRenderPass-renderpass
    This command must only be called outside of a render pass instance

  • VUID-vkCmdBeginRenderPass-videocoding
    This command must only be called outside of a video coding scope

  • VUID-vkCmdBeginRenderPass-bufferlevel
    commandBuffer must be a primary VkCommandBuffer

Host Synchronization

  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Video Coding Scope Supported Queue Types Command Type

Primary

Outside

Outside

Graphics

Action
State
Synchronization

Alternatively to begin a render pass, call:

// Provided by VK_VERSION_1_2
void vkCmdBeginRenderPass2(
    VkCommandBuffer                             commandBuffer,
    const VkRenderPassBeginInfo*                pRenderPassBegin,
    const VkSubpassBeginInfo*                   pSubpassBeginInfo);

or the equivalent command

// Provided by VK_KHR_create_renderpass2
void vkCmdBeginRenderPass2KHR(
    VkCommandBuffer                             commandBuffer,
    const VkRenderPassBeginInfo*                pRenderPassBegin,
    const VkSubpassBeginInfo*                   pSubpassBeginInfo);

  • commandBuffer is the command buffer in which to record the command.

  • pRenderPassBegin is a pointer to a VkRenderPassBeginInfo structure specifying the render pass to begin an instance of, and the framebuffer the instance uses.

  • pSubpassBeginInfo is a pointer to a VkSubpassBeginInfo structure containing information about the subpass which is about to begin rendering.

After beginning a render pass instance, the command buffer is ready to record the commands for the first subpass of that render pass.

Valid Usage

  • VUID-vkCmdBeginRenderPass2-framebuffer-02779
    Both the framebuffer and renderPass members of pRenderPassBegin must have been created on the same VkDevice that commandBuffer was allocated on

  • VUID-vkCmdBeginRenderPass2-initialLayout-03094
    If any of the initialLayout or finalLayout member of the VkAttachmentDescription structures or the layout member of the VkAttachmentReference structures specified when creating the render pass specified in the renderPass member of pRenderPassBegin is VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL then the corresponding attachment image view of the framebuffer specified in the framebuffer member of pRenderPassBegin must have been created with a usage value including VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT

  • VUID-vkCmdBeginRenderPass2-initialLayout-03096
    If any of the initialLayout or finalLayout member of the VkAttachmentDescription structures or the layout member of the VkAttachmentReference structures specified when creating the render pass specified in the renderPass member of pRenderPassBegin is VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL, VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL, VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL, or VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL then the corresponding attachment image view of the framebuffer specified in the framebuffer member of pRenderPassBegin must have been created with a usage value including VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT

  • VUID-vkCmdBeginRenderPass2-initialLayout-02844
    If any of the initialLayout or finalLayout member of the VkAttachmentDescription structures or the layout member of the VkAttachmentReference structures specified when creating the render pass specified in the renderPass member of pRenderPassBegin is VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL, or VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL, or VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL then the corresponding attachment image view of the framebuffer specified in the framebuffer member of pRenderPassBegin must have been created with a usage value including VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT

  • VUID-vkCmdBeginRenderPass2-stencilInitialLayout-02845
    If any of the stencilInitialLayout or stencilFinalLayout member of the VkAttachmentDescriptionStencilLayout structures or the stencilLayout member of the VkAttachmentReferenceStencilLayout structures specified when creating the render pass specified in the renderPass member of pRenderPassBegin is VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL, or VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL then the corresponding attachment image view of the framebuffer specified in the framebuffer member of pRenderPassBegin must have been created with a usage value including VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT

  • VUID-vkCmdBeginRenderPass2-initialLayout-03097
    If any of the initialLayout or finalLayout member of the VkAttachmentDescription structures or the layout member of the VkAttachmentReference structures specified when creating the render pass specified in the renderPass member of pRenderPassBegin is VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL then the corresponding attachment image view of the framebuffer specified in the framebuffer member of pRenderPassBegin must have been created with a usage value including VK_IMAGE_USAGE_SAMPLED_BIT or VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT

  • VUID-vkCmdBeginRenderPass2-initialLayout-03098
    If any of the initialLayout or finalLayout member of the VkAttachmentDescription structures or the layout member of the VkAttachmentReference structures specified when creating the render pass specified in the renderPass member of pRenderPassBegin is VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL then the corresponding attachment image view of the framebuffer specified in the framebuffer member of pRenderPassBegin must have been created with a usage value including VK_IMAGE_USAGE_TRANSFER_SRC_BIT

  • VUID-vkCmdBeginRenderPass2-initialLayout-03099
    If any of the initialLayout or finalLayout member of the VkAttachmentDescription structures or the layout member of the VkAttachmentReference structures specified when creating the render pass specified in the renderPass member of pRenderPassBegin is VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL then the corresponding attachment image view of the framebuffer specified in the framebuffer member of pRenderPassBegin must have been created with a usage value including VK_IMAGE_USAGE_TRANSFER_DST_BIT

  • VUID-vkCmdBeginRenderPass2-initialLayout-03100
    If the initialLayout member of any of the VkAttachmentDescription structures specified when creating the render pass specified in the renderPass member of pRenderPassBegin is not VK_IMAGE_LAYOUT_UNDEFINED, then each such initialLayout must be equal to the current layout of the corresponding attachment image subresource of the framebuffer specified in the framebuffer member of pRenderPassBegin

  • VUID-vkCmdBeginRenderPass2-srcStageMask-06453
    The srcStageMask members of any element of the pDependencies member of VkRenderPassCreateInfo used to create renderPass must be supported by the capabilities of the queue family identified by the queueFamilyIndex member of the VkCommandPoolCreateInfo used to create the command pool which commandBuffer was allocated from

  • VUID-vkCmdBeginRenderPass2-dstStageMask-06454
    The dstStageMask members of any element of the pDependencies member of VkRenderPassCreateInfo used to create renderPass must be supported by the capabilities of the queue family identified by the queueFamilyIndex member of the VkCommandPoolCreateInfo used to create the command pool which commandBuffer was allocated from

  • VUID-vkCmdBeginRenderPass2-framebuffer-02533
    For any attachment in framebuffer that is used by renderPass and is bound to memory locations that are also bound to another attachment used by renderPass, and if at least one of those uses causes either attachment to be written to, both attachments must have had the VK_ATTACHMENT_DESCRIPTION_MAY_ALIAS_BIT set

  • VUID-vkCmdBeginRenderPass2-framebuffer-09046
    If any attachments specified in framebuffer are used by renderPass and are bound to overlapping memory locations, there must be only one that is used as a color attachment, depth/stencil, or resolve attachment in any subpass

  • VUID-vkCmdBeginRenderPass2-initialLayout-07002
    If any of the initialLayout or finalLayout member of the VkAttachmentDescription structures or the layout member of the VkAttachmentReference structures specified when creating the render pass specified in the renderPass member of pRenderPassBegin is VK_IMAGE_LAYOUT_ATTACHMENT_FEEDBACK_LOOP_OPTIMAL_EXT then the corresponding attachment image view of the framebuffer specified in the framebuffer member of pRenderPassBegin must have been created with a usage value including either the VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT or VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT and either the VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT or VK_IMAGE_USAGE_SAMPLED_BIT usage bits

  • VUID-vkCmdBeginRenderPass2-initialLayout-07003
    If any of the initialLayout or finalLayout member of the VkAttachmentDescription structures or the layout member of the VkAttachmentReference structures specified when creating the render pass specified in the renderPass member of pRenderPassBegin is VK_IMAGE_LAYOUT_ATTACHMENT_FEEDBACK_LOOP_OPTIMAL_EXT then the corresponding attachment image view of the framebuffer specified in the framebuffer member of pRenderPassBegin must have been created with a usage value the VK_IMAGE_USAGE_ATTACHMENT_FEEDBACK_LOOP_BIT_EXT usage bit

  • VUID-vkCmdBeginRenderPass2-initialLayout-09538
    If any of the initialLayout or finalLayout member of the VkAttachmentDescription structures or the layout member of the VkAttachmentReference structures specified when creating the render pass specified in the renderPass member of pRenderPassBegin is VK_IMAGE_LAYOUT_RENDERING_LOCAL_READ_KHR then the corresponding attachment image view of the framebuffer specified in the framebuffer member of pRenderPassBegin must have been created with a usage value including either VK_IMAGE_USAGE_STORAGE_BIT, or both VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT and either of VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT or VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT

Valid Usage (Implicit)

  • VUID-vkCmdBeginRenderPass2-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdBeginRenderPass2-pRenderPassBegin-parameter
    pRenderPassBegin must be a valid pointer to a valid VkRenderPassBeginInfo structure

  • VUID-vkCmdBeginRenderPass2-pSubpassBeginInfo-parameter
    pSubpassBeginInfo must be a valid pointer to a valid VkSubpassBeginInfo structure

  • VUID-vkCmdBeginRenderPass2-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdBeginRenderPass2-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support graphics operations

  • VUID-vkCmdBeginRenderPass2-renderpass
    This command must only be called outside of a render pass instance

  • VUID-vkCmdBeginRenderPass2-videocoding
    This command must only be called outside of a video coding scope

  • VUID-vkCmdBeginRenderPass2-bufferlevel
    commandBuffer must be a primary VkCommandBuffer

Host Synchronization

  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Video Coding Scope Supported Queue Types Command Type

Primary

Outside

Outside

Graphics

Action
State
Synchronization

The VkRenderPassBeginInfo structure is defined as:

// Provided by VK_VERSION_1_0
typedef struct VkRenderPassBeginInfo {
    VkStructureType        sType;
    const void*            pNext;
    VkRenderPass           renderPass;
    VkFramebuffer          framebuffer;
    VkRect2D               renderArea;
    uint32_t               clearValueCount;
    const VkClearValue*    pClearValues;
} VkRenderPassBeginInfo;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • renderPass is the render pass to begin an instance of.

  • framebuffer is the framebuffer containing the attachments that are used with the render pass.

  • renderArea is the render area that is affected by the render pass instance, and is described in more detail below.

  • clearValueCount is the number of elements in pClearValues.

  • pClearValues is a pointer to an array of clearValueCount VkClearValue structures containing clear values for each attachment, if the attachment uses a loadOp value of VK_ATTACHMENT_LOAD_OP_CLEAR or if the attachment has a depth/stencil format and uses a stencilLoadOp value of VK_ATTACHMENT_LOAD_OP_CLEAR. The array is indexed by attachment number. Only elements corresponding to cleared attachments are used. Other elements of pClearValues are ignored.

renderArea is the render area that is affected by the render pass instance. The effects of attachment load, store and multisample resolve operations are restricted to the pixels whose x and y coordinates fall within the render area on all attachments. The render area extends to all layers of framebuffer. The application must ensure (using scissor if necessary) that all rendering is contained within the render area. The render area, after any transform specified by VkRenderPassTransformBeginInfoQCOM::transform is applied, must be contained within the framebuffer dimensions.

If render pass transform is enabled, then renderArea must equal the framebuffer pre-transformed dimensions. After renderArea has been transformed by VkRenderPassTransformBeginInfoQCOM::transform, the resulting render area must be equal to the framebuffer dimensions.

If multiview is enabled in renderPass, and multiviewPerViewRenderAreas feature is enabled, and there is an instance of VkMultiviewPerViewRenderAreasRenderPassBeginInfoQCOM included in the pNext chain with perViewRenderAreaCount not equal to 0, then the elements of VkMultiviewPerViewRenderAreasRenderPassBeginInfoQCOM::pPerViewRenderAreas override renderArea and define a render area for each view. In this case, renderArea must be set to an area at least as large as the union of all the per-view render areas.

If the subpassShading feature is enabled, then renderArea must equal the framebuffer dimensions.

Note

There may be a performance cost for using a render area smaller than the framebuffer, unless it matches the render area granularity for the render pass.
Valid Usage
Valid Usage (Implicit)

The image layout of the depth aspect of a depth/stencil attachment referring to an image created with VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT is dependent on the last sample locations used to render to the image subresource, thus preserving the contents of such depth/stencil attachments across subpass boundaries requires the application to specify these sample locations whenever a layout transition of the attachment may occur. This information can be provided by adding a VkRenderPassSampleLocationsBeginInfoEXT structure to the pNext chain of VkRenderPassBeginInfo.

The VkRenderPassSampleLocationsBeginInfoEXT structure is defined as:

// Provided by VK_EXT_sample_locations
typedef struct VkRenderPassSampleLocationsBeginInfoEXT {
    VkStructureType                          sType;
    const void*                              pNext;
    uint32_t                                 attachmentInitialSampleLocationsCount;
    const VkAttachmentSampleLocationsEXT*    pAttachmentInitialSampleLocations;
    uint32_t                                 postSubpassSampleLocationsCount;
    const VkSubpassSampleLocationsEXT*       pPostSubpassSampleLocations;
} VkRenderPassSampleLocationsBeginInfoEXT;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • attachmentInitialSampleLocationsCount is the number of elements in the pAttachmentInitialSampleLocations array.

  • pAttachmentInitialSampleLocations is a pointer to an array of attachmentInitialSampleLocationsCount VkAttachmentSampleLocationsEXT structures specifying the attachment indices and their corresponding sample location state. Each element of pAttachmentInitialSampleLocations can specify the sample location state to use in the automatic layout transition performed to transition a depth/stencil attachment from the initial layout of the attachment to the image layout specified for the attachment in the first subpass using it.

  • postSubpassSampleLocationsCount is the number of elements in the pPostSubpassSampleLocations array.

  • pPostSubpassSampleLocations is a pointer to an array of postSubpassSampleLocationsCount VkSubpassSampleLocationsEXT structures specifying the subpass indices and their corresponding sample location state. Each element of pPostSubpassSampleLocations can specify the sample location state to use in the automatic layout transition performed to transition the depth/stencil attachment used by the specified subpass to the image layout specified in a dependent subpass or to the final layout of the attachment in case the specified subpass is the last subpass using that attachment. In addition, if VkPhysicalDeviceSampleLocationsPropertiesEXT::variableSampleLocations is VK_FALSE, each element of pPostSubpassSampleLocations must specify the sample location state that matches the sample locations used by all pipelines that will be bound to a command buffer during the specified subpass. If variableSampleLocations is VK_TRUE, the sample locations used for rasterization do not depend on pPostSubpassSampleLocations.

Valid Usage (Implicit)

  • VUID-VkRenderPassSampleLocationsBeginInfoEXT-sType-sType
    sType must be VK_STRUCTURE_TYPE_RENDER_PASS_SAMPLE_LOCATIONS_BEGIN_INFO_EXT

  • VUID-VkRenderPassSampleLocationsBeginInfoEXT-pAttachmentInitialSampleLocations-parameter
    If attachmentInitialSampleLocationsCount is not 0, pAttachmentInitialSampleLocations must be a valid pointer to an array of attachmentInitialSampleLocationsCount valid VkAttachmentSampleLocationsEXT structures

  • VUID-VkRenderPassSampleLocationsBeginInfoEXT-pPostSubpassSampleLocations-parameter
    If postSubpassSampleLocationsCount is not 0, pPostSubpassSampleLocations must be a valid pointer to an array of postSubpassSampleLocationsCount valid VkSubpassSampleLocationsEXT structures

The VkAttachmentSampleLocationsEXT structure is defined as:

// Provided by VK_EXT_sample_locations
typedef struct VkAttachmentSampleLocationsEXT {
    uint32_t                    attachmentIndex;
    VkSampleLocationsInfoEXT    sampleLocationsInfo;
} VkAttachmentSampleLocationsEXT;

  • attachmentIndex is the index of the attachment for which the sample locations state is provided.

  • sampleLocationsInfo is the sample locations state to use for the layout transition of the given attachment from the initial layout of the attachment to the image layout specified for the attachment in the first subpass using it.

If the image referenced by the framebuffer attachment at index attachmentIndex was not created with VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT then the values specified in sampleLocationsInfo are ignored.

Valid Usage

  • VUID-VkAttachmentSampleLocationsEXT-attachmentIndex-01531
    attachmentIndex must be less than the attachmentCount specified in VkRenderPassCreateInfo the render pass specified by VkRenderPassBeginInfo::renderPass was created with

Valid Usage (Implicit)

  • VUID-VkAttachmentSampleLocationsEXT-sampleLocationsInfo-parameter
    sampleLocationsInfo must be a valid VkSampleLocationsInfoEXT structure

The VkSubpassSampleLocationsEXT structure is defined as:

// Provided by VK_EXT_sample_locations
typedef struct VkSubpassSampleLocationsEXT {
    uint32_t                    subpassIndex;
    VkSampleLocationsInfoEXT    sampleLocationsInfo;
} VkSubpassSampleLocationsEXT;

  • subpassIndex is the index of the subpass for which the sample locations state is provided.

  • sampleLocationsInfo is the sample locations state to use for the layout transition of the depth/stencil attachment away from the image layout the attachment is used with in the subpass specified in subpassIndex.

If the image referenced by the depth/stencil attachment used in the subpass identified by subpassIndex was not created with VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT or if the subpass does not use a depth/stencil attachment, and VkPhysicalDeviceSampleLocationsPropertiesEXT::variableSampleLocations is VK_TRUE then the values specified in sampleLocationsInfo are ignored.

Valid Usage

  • VUID-VkSubpassSampleLocationsEXT-subpassIndex-01532
    subpassIndex must be less than the subpassCount specified in VkRenderPassCreateInfo the render pass specified by VkRenderPassBeginInfo::renderPass was created with

Valid Usage (Implicit)

  • VUID-VkSubpassSampleLocationsEXT-sampleLocationsInfo-parameter
    sampleLocationsInfo must be a valid VkSampleLocationsInfoEXT structure

To begin a render pass instance with render pass transform enabled, add the VkRenderPassTransformBeginInfoQCOM to the pNext chain of VkRenderPassBeginInfo structure passed to the vkCmdBeginRenderPass command specifying the render pass transform.

The VkRenderPassTransformBeginInfoQCOM structure is defined as:

// Provided by VK_QCOM_render_pass_transform
typedef struct VkRenderPassTransformBeginInfoQCOM {
    VkStructureType                  sType;
    void*                            pNext;
    VkSurfaceTransformFlagBitsKHR    transform;
} VkRenderPassTransformBeginInfoQCOM;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • transform is a VkSurfaceTransformFlagBitsKHR value describing the transform to be applied to rasterization.

Valid Usage

  • VUID-VkRenderPassTransformBeginInfoQCOM-transform-02871
    transform must be VK_SURFACE_TRANSFORM_IDENTITY_BIT_KHR, VK_SURFACE_TRANSFORM_ROTATE_90_BIT_KHR, VK_SURFACE_TRANSFORM_ROTATE_180_BIT_KHR, or VK_SURFACE_TRANSFORM_ROTATE_270_BIT_KHR

  • VUID-VkRenderPassTransformBeginInfoQCOM-flags-02872
    The renderpass must have been created with VkRenderPassCreateInfo::flags containing VK_RENDER_PASS_CREATE_TRANSFORM_BIT_QCOM

Valid Usage (Implicit)

  • VUID-VkRenderPassTransformBeginInfoQCOM-sType-sType
    sType must be VK_STRUCTURE_TYPE_RENDER_PASS_TRANSFORM_BEGIN_INFO_QCOM

The VkSubpassBeginInfo structure is defined as:

// Provided by VK_VERSION_1_2
typedef struct VkSubpassBeginInfo {
    VkStructureType      sType;
    const void*          pNext;
    VkSubpassContents    contents;
} VkSubpassBeginInfo;

or the equivalent

// Provided by VK_KHR_create_renderpass2
typedef VkSubpassBeginInfo VkSubpassBeginInfoKHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • contents is a VkSubpassContents value specifying how the commands in the next subpass will be provided.

Valid Usage

  • VUID-VkSubpassBeginInfo-contents-09382
    If contents is VK_SUBPASS_CONTENTS_INLINE_AND_SECONDARY_COMMAND_BUFFERS_KHR, then at least one of the following features must be enabled:

Valid Usage (Implicit)

  • VUID-VkSubpassBeginInfo-sType-sType
    sType must be VK_STRUCTURE_TYPE_SUBPASS_BEGIN_INFO

  • VUID-VkSubpassBeginInfo-pNext-pNext
    pNext must be NULL

  • VUID-VkSubpassBeginInfo-contents-parameter
    contents must be a valid VkSubpassContents value

Possible values of vkCmdBeginRenderPass::contents, specifying how the commands in the first subpass will be provided, are:

// Provided by VK_VERSION_1_0
typedef enum VkSubpassContents {
    VK_SUBPASS_CONTENTS_INLINE = 0,
    VK_SUBPASS_CONTENTS_SECONDARY_COMMAND_BUFFERS = 1,
  // Provided by VK_KHR_maintenance7
    VK_SUBPASS_CONTENTS_INLINE_AND_SECONDARY_COMMAND_BUFFERS_KHR = 1000451000,
  // Provided by VK_EXT_nested_command_buffer
    VK_SUBPASS_CONTENTS_INLINE_AND_SECONDARY_COMMAND_BUFFERS_EXT = VK_SUBPASS_CONTENTS_INLINE_AND_SECONDARY_COMMAND_BUFFERS_KHR,
} VkSubpassContents;

  • VK_SUBPASS_CONTENTS_INLINE specifies that the contents of the subpass will be recorded inline in the primary command buffer, and secondary command buffers must not be executed within the subpass.

  • VK_SUBPASS_CONTENTS_SECONDARY_COMMAND_BUFFERS specifies that the contents are recorded in secondary command buffers that will be called from the primary command buffer, and vkCmdExecuteCommands is the only valid command in the command buffer until vkCmdNextSubpass or vkCmdEndRenderPass.

  • VK_SUBPASS_CONTENTS_INLINE_AND_SECONDARY_COMMAND_BUFFERS_KHR specifies that the contents of the subpass can be recorded both inline and in secondary command buffers executed from this command buffer with vkCmdExecuteCommands.

If the pNext chain of VkRenderPassBeginInfo or VkRenderingInfo includes a VkDeviceGroupRenderPassBeginInfo structure, then that structure includes a device mask and set of render areas for the render pass instance.

The VkDeviceGroupRenderPassBeginInfo structure is defined as:

// Provided by VK_VERSION_1_1
typedef struct VkDeviceGroupRenderPassBeginInfo {
    VkStructureType    sType;
    const void*        pNext;
    uint32_t           deviceMask;
    uint32_t           deviceRenderAreaCount;
    const VkRect2D*    pDeviceRenderAreas;
} VkDeviceGroupRenderPassBeginInfo;

or the equivalent

// Provided by VK_KHR_device_group
typedef VkDeviceGroupRenderPassBeginInfo VkDeviceGroupRenderPassBeginInfoKHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • deviceMask is the device mask for the render pass instance.

  • deviceRenderAreaCount is the number of elements in the pDeviceRenderAreas array.

  • pDeviceRenderAreas is a pointer to an array of VkRect2D structures defining the render area for each physical device.

The deviceMask serves several purposes. It is an upper bound on the set of physical devices that can be used during the render pass instance, and the initial device mask when the render pass instance begins. In addition, commands transitioning to the next subpass in a render pass instance and commands ending the render pass instance, and, accordingly render pass load, store, and multisample resolve operations and subpass dependencies corresponding to the render pass instance, are executed on the physical devices included in the device mask provided here.

If deviceRenderAreaCount is not zero, then the elements of pDeviceRenderAreas override the value of VkRenderPassBeginInfo::renderArea, and provide a render area specific to each physical device. These render areas serve the same purpose as VkRenderPassBeginInfo::renderArea, including controlling the region of attachments that are cleared by VK_ATTACHMENT_LOAD_OP_CLEAR and that are resolved into resolve attachments.

If this structure is not present, the render pass instance’s device mask is the value of VkDeviceGroupCommandBufferBeginInfo::deviceMask. If this structure is not present or if deviceRenderAreaCount is zero, VkRenderPassBeginInfo::renderArea is used for all physical devices.

Valid Usage

  • VUID-VkDeviceGroupRenderPassBeginInfo-deviceMask-00905
    deviceMask must be a valid device mask value

  • VUID-VkDeviceGroupRenderPassBeginInfo-deviceMask-00906
    deviceMask must not be zero

  • VUID-VkDeviceGroupRenderPassBeginInfo-deviceMask-00907
    deviceMask must be a subset of the command buffer’s initial device mask

  • VUID-VkDeviceGroupRenderPassBeginInfo-deviceRenderAreaCount-00908
    deviceRenderAreaCount must either be zero or equal to the number of physical devices in the logical device

  • VUID-VkDeviceGroupRenderPassBeginInfo-offset-06166
    The offset.x member of any element of pDeviceRenderAreas must be greater than or equal to 0

  • VUID-VkDeviceGroupRenderPassBeginInfo-offset-06167
    The offset.y member of any element of pDeviceRenderAreas must be greater than or equal to 0

  • VUID-VkDeviceGroupRenderPassBeginInfo-offset-06168
    The sum of the offset.x and extent.width members of any element of pDeviceRenderAreas must be less than or equal to maxFramebufferWidth

  • VUID-VkDeviceGroupRenderPassBeginInfo-offset-06169
    The sum of the offset.y and extent.height members of any element of pDeviceRenderAreas must be less than or equal to maxFramebufferHeight

  • VUID-VkDeviceGroupRenderPassBeginInfo-extent-08998
    The extent.width member of any element of pDeviceRenderAreas must be greater than 0

  • VUID-VkDeviceGroupRenderPassBeginInfo-extent-08999
    The extent.height member of any element of pDeviceRenderAreas must be greater than 0

Valid Usage (Implicit)

  • VUID-VkDeviceGroupRenderPassBeginInfo-sType-sType
    sType must be VK_STRUCTURE_TYPE_DEVICE_GROUP_RENDER_PASS_BEGIN_INFO

  • VUID-VkDeviceGroupRenderPassBeginInfo-pDeviceRenderAreas-parameter
    If deviceRenderAreaCount is not 0, pDeviceRenderAreas must be a valid pointer to an array of deviceRenderAreaCount VkRect2D structures

The VkRenderPassAttachmentBeginInfo structure is defined as:

// Provided by VK_VERSION_1_2
typedef struct VkRenderPassAttachmentBeginInfo {
    VkStructureType       sType;
    const void*           pNext;
    uint32_t              attachmentCount;
    const VkImageView*    pAttachments;
} VkRenderPassAttachmentBeginInfo;

or the equivalent

// Provided by VK_KHR_imageless_framebuffer
typedef VkRenderPassAttachmentBeginInfo VkRenderPassAttachmentBeginInfoKHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • attachmentCount is the number of attachments.

  • pAttachments is a pointer to an array of VkImageView handles, each of which will be used as the corresponding attachment in the render pass instance.

Valid Usage

  • VUID-VkRenderPassAttachmentBeginInfo-pAttachments-03218
    Each element of pAttachments must only specify a single mip level

  • VUID-VkRenderPassAttachmentBeginInfo-pAttachments-03219
    Each element of pAttachments must have been created with the identity swizzle

  • VUID-VkRenderPassAttachmentBeginInfo-pAttachments-04114
    Each element of pAttachments must have been created with VkImageViewCreateInfo::viewType not equal to VK_IMAGE_VIEW_TYPE_3D

  • VUID-VkRenderPassAttachmentBeginInfo-pAttachments-07010
    If multisampled-render-to-single-sampled is enabled for any subpass, all element of pAttachments which have a sample count equal to VK_SAMPLE_COUNT_1_BIT must have a format that supports the sample count specified in VkMultisampledRenderToSingleSampledInfoEXT::rasterizationSamples

Valid Usage (Implicit)

  • VUID-VkRenderPassAttachmentBeginInfo-sType-sType
    sType must be VK_STRUCTURE_TYPE_RENDER_PASS_ATTACHMENT_BEGIN_INFO

  • VUID-VkRenderPassAttachmentBeginInfo-pAttachments-parameter
    If attachmentCount is not 0, pAttachments must be a valid pointer to an array of attachmentCount valid VkImageView handles

If a render pass instance enables multiview and if the multiviewPerViewRenderAreas feature is enabled, the VkMultiviewPerViewRenderAreasRenderPassBeginInfoQCOM structure can be included in the pNext chain of VkRenderPassBeginInfo or VkRenderingInfo

The VkMultiviewPerViewRenderAreasRenderPassBeginInfoQCOM structure is defined as:

// Provided by VK_QCOM_multiview_per_view_render_areas
typedef struct VkMultiviewPerViewRenderAreasRenderPassBeginInfoQCOM {
    VkStructureType    sType;
    const void*        pNext;
    uint32_t           perViewRenderAreaCount;
    const VkRect2D*    pPerViewRenderAreas;
} VkMultiviewPerViewRenderAreasRenderPassBeginInfoQCOM;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • perViewRenderAreaCount is the number of elements in the pPerViewRenderAreas array.

  • pPerViewRenderAreas is a pointer to an array of VkRect2D structures defining the render area for each view.

If perViewRenderAreaCount is not zero, then the elements of pPerViewRenderAreas override the value of VkRenderPassBeginInfo::renderArea or VkRenderingInfo::renderArea and define per-view render areas for the individual views of a multiview render pass. The render area for the view with view index i is specified by pPerViewRenderAreas[i].

The per-view render areas define per-view regions of attachments that are loaded, stored, and resolved according to the loadOp, storeOp, and resolveMode values of the render pass instance. When per-view render areas are defined, the value of VkRenderPassBeginInfo::renderArea or VkRenderingInfo::renderArea must be set to a render area that includes the union of all per-view render areas, may be used by the implementation for optimizations, but does not affect loads, stores, or resolves.

If this structure is present and if perViewRenderAreaCount is not zero, then perViewRenderAreaCount must be at least one greater than the most significant bit set in any element of VkRenderPassMultiviewCreateInfo::pViewMasks. or VkRenderingInfo::viewMask

If this structure is not present or if perViewRenderAreaCount is zero, VkRenderPassBeginInfo::renderArea or VkRenderingInfo::renderArea is used for all views.

Valid Usage

  • VUID-VkMultiviewPerViewRenderAreasRenderPassBeginInfoQCOM-offset-07861
    The offset.x member of any element of pPerViewRenderAreas must be greater than or equal to 0

  • VUID-VkMultiviewPerViewRenderAreasRenderPassBeginInfoQCOM-offset-07862
    The offset.y member of any element of pPerViewRenderAreas must be greater than or equal to 0

  • VUID-VkMultiviewPerViewRenderAreasRenderPassBeginInfoQCOM-offset-07863
    The sum of the offset.x and extent.width members of any element of pPerViewRenderAreas must be less than or equal to maxFramebufferWidth

  • VUID-VkMultiviewPerViewRenderAreasRenderPassBeginInfoQCOM-offset-07864
    The sum of the offset.y and extent.height members of any element of pPerViewRenderAreas must be less than or equal to maxFramebufferHeight

  • VUID-VkMultiviewPerViewRenderAreasRenderPassBeginInfoQCOM-pNext-07865
    If this structure is in the pNext chain of VkRenderPassBeginInfo and if the render pass object included an element in VkRenderPassMultiviewCreateInfo::pViewMasks that set bit n, then perViewRenderAreaCount must be at least equal to n+1

  • VUID-VkMultiviewPerViewRenderAreasRenderPassBeginInfoQCOM-pNext-07866
    If this structure is in the pNext chain of VkRenderingInfo and if VkRenderingInfo::viewMask set bit n, then perViewRenderAreaCount must be at least equal to n+1

Valid Usage (Implicit)

  • VUID-VkMultiviewPerViewRenderAreasRenderPassBeginInfoQCOM-sType-sType
    sType must be VK_STRUCTURE_TYPE_MULTIVIEW_PER_VIEW_RENDER_AREAS_RENDER_PASS_BEGIN_INFO_QCOM

  • VUID-VkMultiviewPerViewRenderAreasRenderPassBeginInfoQCOM-pPerViewRenderAreas-parameter
    If perViewRenderAreaCount is not 0, pPerViewRenderAreas must be a valid pointer to an array of perViewRenderAreaCount VkRect2D structures

To query the render area granularity, call:

// Provided by VK_VERSION_1_0
void vkGetRenderAreaGranularity(
    VkDevice                                    device,
    VkRenderPass                                renderPass,
    VkExtent2D*                                 pGranularity);

  • device is the logical device that owns the render pass.

  • renderPass is a handle to a render pass.

  • pGranularity is a pointer to a VkExtent2D structure in which the granularity is returned.

The conditions leading to an optimal renderArea are:

  • the offset.x member in renderArea is a multiple of the width member of the returned VkExtent2D (the horizontal granularity).

  • the offset.y member in renderArea is a multiple of the height member of the returned VkExtent2D (the vertical granularity).

  • either the extent.width member in renderArea is a multiple of the horizontal granularity or offset.x+extent.width is equal to the width of the framebuffer in the VkRenderPassBeginInfo.

  • either the extent.height member in renderArea is a multiple of the vertical granularity or offset.y+extent.height is equal to the height of the framebuffer in the VkRenderPassBeginInfo.

Subpass dependencies are not affected by the render area, and apply to the entire image subresources attached to the framebuffer as specified in the description of automatic layout transitions. Similarly, pipeline barriers are valid even if their effect extends outside the render area.

Valid Usage (Implicit)

  • VUID-vkGetRenderAreaGranularity-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkGetRenderAreaGranularity-renderPass-parameter
    renderPass must be a valid VkRenderPass handle

  • VUID-vkGetRenderAreaGranularity-pGranularity-parameter
    pGranularity must be a valid pointer to a VkExtent2D structure

  • VUID-vkGetRenderAreaGranularity-renderPass-parent
    renderPass must have been created, allocated, or retrieved from device

To transition to the next subpass in the render pass instance after recording the commands for a subpass, call:

// Provided by VK_VERSION_1_0
void vkCmdNextSubpass(
    VkCommandBuffer                             commandBuffer,
    VkSubpassContents                           contents);

  • commandBuffer is the command buffer in which to record the command.

  • contents specifies how the commands in the next subpass will be provided, in the same fashion as the corresponding parameter of vkCmdBeginRenderPass.

The subpass index for a render pass begins at zero when vkCmdBeginRenderPass is recorded, and increments each time vkCmdNextSubpass is recorded.

After transitioning to the next subpass, the application can record the commands for that subpass.

Valid Usage

  • VUID-vkCmdNextSubpass-None-00909
    The current subpass index must be less than the number of subpasses in the render pass minus one

  • VUID-vkCmdNextSubpass-None-02349
    This command must not be recorded when transform feedback is active

Valid Usage (Implicit)

  • VUID-vkCmdNextSubpass-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdNextSubpass-contents-parameter
    contents must be a valid VkSubpassContents value

  • VUID-vkCmdNextSubpass-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdNextSubpass-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support graphics operations

  • VUID-vkCmdNextSubpass-renderpass
    This command must only be called inside of a render pass instance

  • VUID-vkCmdNextSubpass-videocoding
    This command must only be called outside of a video coding scope

  • VUID-vkCmdNextSubpass-bufferlevel
    commandBuffer must be a primary VkCommandBuffer

Host Synchronization

  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Video Coding Scope Supported Queue Types Command Type

Primary

Inside

Outside

Graphics

Action
State
Synchronization

To transition to the next subpass in the render pass instance after recording the commands for a subpass, call:

// Provided by VK_VERSION_1_2
void vkCmdNextSubpass2(
    VkCommandBuffer                             commandBuffer,
    const VkSubpassBeginInfo*                   pSubpassBeginInfo,
    const VkSubpassEndInfo*                     pSubpassEndInfo);

or the equivalent command

// Provided by VK_KHR_create_renderpass2
void vkCmdNextSubpass2KHR(
    VkCommandBuffer                             commandBuffer,
    const VkSubpassBeginInfo*                   pSubpassBeginInfo,
    const VkSubpassEndInfo*                     pSubpassEndInfo);

  • commandBuffer is the command buffer in which to record the command.

  • pSubpassBeginInfo is a pointer to a VkSubpassBeginInfo structure containing information about the subpass which is about to begin rendering.

  • pSubpassEndInfo is a pointer to a VkSubpassEndInfo structure containing information about how the previous subpass will be ended.

vkCmdNextSubpass2 is semantically identical to vkCmdNextSubpass, except that it is extensible, and that contents is provided as part of an extensible structure instead of as a flat parameter.

Valid Usage

  • VUID-vkCmdNextSubpass2-None-03102
    The current subpass index must be less than the number of subpasses in the render pass minus one

  • VUID-vkCmdNextSubpass2-None-02350
    This command must not be recorded when transform feedback is active

Valid Usage (Implicit)

  • VUID-vkCmdNextSubpass2-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdNextSubpass2-pSubpassBeginInfo-parameter
    pSubpassBeginInfo must be a valid pointer to a valid VkSubpassBeginInfo structure

  • VUID-vkCmdNextSubpass2-pSubpassEndInfo-parameter
    pSubpassEndInfo must be a valid pointer to a valid VkSubpassEndInfo structure

  • VUID-vkCmdNextSubpass2-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdNextSubpass2-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support graphics operations

  • VUID-vkCmdNextSubpass2-renderpass
    This command must only be called inside of a render pass instance

  • VUID-vkCmdNextSubpass2-videocoding
    This command must only be called outside of a video coding scope

  • VUID-vkCmdNextSubpass2-bufferlevel
    commandBuffer must be a primary VkCommandBuffer

Host Synchronization

  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Video Coding Scope Supported Queue Types Command Type

Primary

Inside

Outside

Graphics

Action
State
Synchronization

To record a command to end a render pass instance after recording the commands for the last subpass, call:

// Provided by VK_VERSION_1_0
void vkCmdEndRenderPass(
    VkCommandBuffer                             commandBuffer);

  • commandBuffer is the command buffer in which to end the current render pass instance.

Ending a render pass instance performs any multisample resolve operations on the final subpass.

Valid Usage

  • VUID-vkCmdEndRenderPass-None-00910
    The current subpass index must be equal to the number of subpasses in the render pass minus one

  • VUID-vkCmdEndRenderPass-None-02351
    This command must not be recorded when transform feedback is active

  • VUID-vkCmdEndRenderPass-None-06170
    The current render pass instance must not have been begun with vkCmdBeginRendering

  • VUID-vkCmdEndRenderPass-None-07004
    If vkCmdBeginQuery* was called within a subpass of the render pass, the corresponding vkCmdEndQuery* must have been called subsequently within the same subpass

Valid Usage (Implicit)

  • VUID-vkCmdEndRenderPass-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdEndRenderPass-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdEndRenderPass-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support graphics operations

  • VUID-vkCmdEndRenderPass-renderpass
    This command must only be called inside of a render pass instance

  • VUID-vkCmdEndRenderPass-videocoding
    This command must only be called outside of a video coding scope

  • VUID-vkCmdEndRenderPass-bufferlevel
    commandBuffer must be a primary VkCommandBuffer

Host Synchronization

  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Video Coding Scope Supported Queue Types Command Type

Primary

Inside

Outside

Graphics

Action
State
Synchronization

To record a command to end a render pass instance after recording the commands for the last subpass, call:

// Provided by VK_VERSION_1_2
void vkCmdEndRenderPass2(
    VkCommandBuffer                             commandBuffer,
    const VkSubpassEndInfo*                     pSubpassEndInfo);

or the equivalent command

// Provided by VK_KHR_create_renderpass2
void vkCmdEndRenderPass2KHR(
    VkCommandBuffer                             commandBuffer,
    const VkSubpassEndInfo*                     pSubpassEndInfo);

  • commandBuffer is the command buffer in which to end the current render pass instance.

  • pSubpassEndInfo is a pointer to a VkSubpassEndInfo structure containing information about how the last subpass will be ended.

vkCmdEndRenderPass2 is semantically identical to vkCmdEndRenderPass, except that it is extensible.

Valid Usage

  • VUID-vkCmdEndRenderPass2-None-03103
    The current subpass index must be equal to the number of subpasses in the render pass minus one

  • VUID-vkCmdEndRenderPass2-None-02352
    This command must not be recorded when transform feedback is active

  • VUID-vkCmdEndRenderPass2-None-06171
    The current render pass instance must not have been begun with vkCmdBeginRendering

  • VUID-vkCmdEndRenderPass2-None-07005
    If vkCmdBeginQuery* was called within a subpass of the render pass, the corresponding vkCmdEndQuery* must have been called subsequently within the same subpass

Valid Usage (Implicit)

  • VUID-vkCmdEndRenderPass2-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdEndRenderPass2-pSubpassEndInfo-parameter
    pSubpassEndInfo must be a valid pointer to a valid VkSubpassEndInfo structure

  • VUID-vkCmdEndRenderPass2-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdEndRenderPass2-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support graphics operations

  • VUID-vkCmdEndRenderPass2-renderpass
    This command must only be called inside of a render pass instance

  • VUID-vkCmdEndRenderPass2-videocoding
    This command must only be called outside of a video coding scope

  • VUID-vkCmdEndRenderPass2-bufferlevel
    commandBuffer must be a primary VkCommandBuffer

Host Synchronization

  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Video Coding Scope Supported Queue Types Command Type

Primary

Inside

Outside

Graphics

Action
State
Synchronization

The VkSubpassEndInfo structure is defined as:

// Provided by VK_VERSION_1_2
typedef struct VkSubpassEndInfo {
    VkStructureType    sType;
    const void*        pNext;
} VkSubpassEndInfo;

or the equivalent

// Provided by VK_KHR_create_renderpass2
typedef VkSubpassEndInfo VkSubpassEndInfoKHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

Valid Usage (Implicit)

  • VUID-VkSubpassEndInfo-sType-sType
    sType must be VK_STRUCTURE_TYPE_SUBPASS_END_INFO

  • VUID-VkSubpassEndInfo-pNext-pNext
    pNext must be NULL or a pointer to a valid instance of VkSubpassFragmentDensityMapOffsetEndInfoQCOM

  • VUID-VkSubpassEndInfo-sType-unique
    The sType value of each struct in the pNext chain must be unique

If the VkSubpassEndInfo::pNext chain includes a VkSubpassFragmentDensityMapOffsetEndInfoQCOM structure, then that structure includes an array of fragment density map offsets per layer for the render pass.

The VkSubpassFragmentDensityMapOffsetEndInfoQCOM structure is defined as:

// Provided by VK_QCOM_fragment_density_map_offset
typedef struct VkSubpassFragmentDensityMapOffsetEndInfoQCOM {
    VkStructureType      sType;
    const void*          pNext;
    uint32_t             fragmentDensityOffsetCount;
    const VkOffset2D*    pFragmentDensityOffsets;
} VkSubpassFragmentDensityMapOffsetEndInfoQCOM;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • fragmentDensityOffsetCount is the number of offsets being specified.

  • pFragmentDensityOffsets is a pointer to an array of VkOffset2D structs, each of which describes the offset per layer.

The array elements are given per layer as defined by Fetch Density Value, where index = layer. Each (x,y) offset is in framebuffer pixels and shifts the fetch of the fragment density map by that amount. Offsets can be positive or negative.

Offset values specified for any subpass that is not the last subpass in the render pass are ignored. If the VkSubpassEndInfo::pNext chain for the last subpass of a render pass does not include VkSubpassFragmentDensityMapOffsetEndInfoQCOM, or if fragmentDensityOffsetCount is zero, then the offset (0,0) is used for Fetch Density Value.

Valid Usage

  • VUID-VkSubpassFragmentDensityMapOffsetEndInfoQCOM-fragmentDensityMapOffsets-06503
    If the fragmentDensityMapOffset feature is not enabled or fragment density map is not enabled in the render pass, fragmentDensityOffsetCount must equal 0

  • VUID-VkSubpassFragmentDensityMapOffsetEndInfoQCOM-fragmentDensityMapAttachment-06504
    If VkSubpassDescription::fragmentDensityMapAttachment is not is not VK_ATTACHMENT_UNUSED and was not created with VK_IMAGE_CREATE_FRAGMENT_DENSITY_MAP_OFFSET_BIT_QCOM, fragmentDensityOffsetCount must equal 0

  • VUID-VkSubpassFragmentDensityMapOffsetEndInfoQCOM-pDepthStencilAttachment-06505
    If VkSubpassDescription::pDepthStencilAttachment is not is not VK_ATTACHMENT_UNUSED and was not created with VK_IMAGE_CREATE_FRAGMENT_DENSITY_MAP_OFFSET_BIT_QCOM, fragmentDensityOffsetCount must equal 0

  • VUID-VkSubpassFragmentDensityMapOffsetEndInfoQCOM-pInputAttachments-06506
    If any element of VkSubpassDescription::pInputAttachments is not is not VK_ATTACHMENT_UNUSED and was not created with VK_IMAGE_CREATE_FRAGMENT_DENSITY_MAP_OFFSET_BIT_QCOM, fragmentDensityOffsetCount must equal 0

  • VUID-VkSubpassFragmentDensityMapOffsetEndInfoQCOM-pColorAttachments-06507
    If any element of VkSubpassDescription::pColorAttachments is not is not VK_ATTACHMENT_UNUSED and was not created with VK_IMAGE_CREATE_FRAGMENT_DENSITY_MAP_OFFSET_BIT_QCOM, fragmentDensityOffsetCount must equal 0

  • VUID-VkSubpassFragmentDensityMapOffsetEndInfoQCOM-pResolveAttachments-06508
    If any element of VkSubpassDescription::pResolveAttachments is not is not VK_ATTACHMENT_UNUSED and was not created with VK_IMAGE_CREATE_FRAGMENT_DENSITY_MAP_OFFSET_BIT_QCOM, fragmentDensityOffsetCount must equal 0

  • VUID-VkSubpassFragmentDensityMapOffsetEndInfoQCOM-pPreserveAttachments-06509
    If any element of VkSubpassDescription::pPreserveAttachments is not is not VK_ATTACHMENT_UNUSED and was not created with VK_IMAGE_CREATE_FRAGMENT_DENSITY_MAP_OFFSET_BIT_QCOM, fragmentDensityOffsetCount must equal 0

  • VUID-VkSubpassFragmentDensityMapOffsetEndInfoQCOM-fragmentDensityOffsetCount-06510
    If fragmentDensityOffsetCount is not 0 and multiview is enabled for the render pass, fragmentDensityOffsetCount must equal the layerCount that was specified in creating the fragment density map attachment view

  • VUID-VkSubpassFragmentDensityMapOffsetEndInfoQCOM-fragmentDensityOffsetCount-06511
    If fragmentDensityOffsetCount is not 0 and multiview is not enabled for the render pass, fragmentDensityOffsetCount must equal 1

  • VUID-VkSubpassFragmentDensityMapOffsetEndInfoQCOM-x-06512
    The x component of each element of pFragmentDensityOffsets must be an integer multiple of fragmentDensityOffsetGranularity.width

  • VUID-VkSubpassFragmentDensityMapOffsetEndInfoQCOM-y-06513
    The y component of each element of pFragmentDensityOffsets must be an integer multiple of fragmentDensityOffsetGranularity.height

Valid Usage (Implicit)

  • VUID-VkSubpassFragmentDensityMapOffsetEndInfoQCOM-sType-sType
    sType must be VK_STRUCTURE_TYPE_SUBPASS_FRAGMENT_DENSITY_MAP_OFFSET_END_INFO_QCOM

  • VUID-VkSubpassFragmentDensityMapOffsetEndInfoQCOM-pFragmentDensityOffsets-parameter
    If fragmentDensityOffsetCount is not 0, pFragmentDensityOffsets must be a valid pointer to an array of fragmentDensityOffsetCount VkOffset2D structures

8.9. Render Pass Creation Feedback

A VkRenderPassCreationControlEXT structure can be included in the pNext chain of VkRenderPassCreateInfo2 or pNext chain of VkSubpassDescription2. The VkRenderPassCreationControlEXT structure is defined as:

// Provided by VK_EXT_subpass_merge_feedback
typedef struct VkRenderPassCreationControlEXT {
    VkStructureType    sType;
    const void*        pNext;
    VkBool32           disallowMerging;
} VkRenderPassCreationControlEXT;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • disallowMerging is a boolean value indicating whether subpass merging will be disabled.

If a VkRenderPassCreationControlEXT structure is included in the pNext chain of VkRenderPassCreateInfo2 and its value of disallowMerging is VK_TRUE, the implementation will disable subpass merging for the entire render pass. If a VkRenderPassCreationControlEXT structure is included in the pNext chain of VkSubpassDescription2 and its value of disallowMerging is VK_TRUE, the implementation will disable merging the described subpass with previous subpasses in the render pass.

Valid Usage (Implicit)

  • VUID-VkRenderPassCreationControlEXT-sType-sType
    sType must be VK_STRUCTURE_TYPE_RENDER_PASS_CREATION_CONTROL_EXT

To obtain feedback about the creation of a render pass, include a VkRenderPassCreationFeedbackCreateInfoEXT structure in the pNext chain of VkRenderPassCreateInfo2. The VkRenderPassCreationFeedbackCreateInfoEXT structure is defined as:

// Provided by VK_EXT_subpass_merge_feedback
typedef struct VkRenderPassCreationFeedbackCreateInfoEXT {
    VkStructureType                         sType;
    const void*                             pNext;
    VkRenderPassCreationFeedbackInfoEXT*    pRenderPassFeedback;
} VkRenderPassCreationFeedbackCreateInfoEXT;
Valid Usage (Implicit)

  • VUID-VkRenderPassCreationFeedbackCreateInfoEXT-sType-sType
    sType must be VK_STRUCTURE_TYPE_RENDER_PASS_CREATION_FEEDBACK_CREATE_INFO_EXT

  • VUID-VkRenderPassCreationFeedbackCreateInfoEXT-pRenderPassFeedback-parameter
    pRenderPassFeedback must be a valid pointer to a VkRenderPassCreationFeedbackInfoEXT structure

The VkRenderPassCreationFeedbackInfoEXT structure is defined as:

// Provided by VK_EXT_subpass_merge_feedback
typedef struct VkRenderPassCreationFeedbackInfoEXT {
    uint32_t    postMergeSubpassCount;
} VkRenderPassCreationFeedbackInfoEXT;

  • postMergeSubpassCount is the subpass count after merge.

Feedback about the creation of a subpass can be obtained by including a VkRenderPassSubpassFeedbackCreateInfoEXT structure in the pNext chain of VkSubpassDescription2. VkRenderPassSubpassFeedbackCreateInfoEXT structure is defined as:

// Provided by VK_EXT_subpass_merge_feedback
typedef struct VkRenderPassSubpassFeedbackCreateInfoEXT {
    VkStructureType                        sType;
    const void*                            pNext;
    VkRenderPassSubpassFeedbackInfoEXT*    pSubpassFeedback;
} VkRenderPassSubpassFeedbackCreateInfoEXT;
Valid Usage (Implicit)

  • VUID-VkRenderPassSubpassFeedbackCreateInfoEXT-sType-sType
    sType must be VK_STRUCTURE_TYPE_RENDER_PASS_SUBPASS_FEEDBACK_CREATE_INFO_EXT

  • VUID-VkRenderPassSubpassFeedbackCreateInfoEXT-pSubpassFeedback-parameter
    pSubpassFeedback must be a valid pointer to a VkRenderPassSubpassFeedbackInfoEXT structure

The VkRenderPassSubpassFeedbackInfoEXT structure is defined as:

// Provided by VK_EXT_subpass_merge_feedback
typedef struct VkRenderPassSubpassFeedbackInfoEXT {
    VkSubpassMergeStatusEXT    subpassMergeStatus;
    char                       description[VK_MAX_DESCRIPTION_SIZE];
    uint32_t                   postMergeIndex;
} VkRenderPassSubpassFeedbackInfoEXT;

  • subpassMergeStatus is a VkSubpassMergeStatusEXT value specifying information about whether the subpass is merged with previous subpass and the reason why it is not merged.

  • description is an array of VK_MAX_DESCRIPTION_SIZE char containing a null-terminated UTF-8 string which provides additional details.

  • postMergeIndex is the subpass index after the subpass merging.

Possible values of VkRenderPassSubpassFeedbackInfoEXT:subpassMergeStatus are:

// Provided by VK_EXT_subpass_merge_feedback
typedef enum VkSubpassMergeStatusEXT {
    VK_SUBPASS_MERGE_STATUS_MERGED_EXT = 0,
    VK_SUBPASS_MERGE_STATUS_DISALLOWED_EXT = 1,
    VK_SUBPASS_MERGE_STATUS_NOT_MERGED_SIDE_EFFECTS_EXT = 2,
    VK_SUBPASS_MERGE_STATUS_NOT_MERGED_SAMPLES_MISMATCH_EXT = 3,
    VK_SUBPASS_MERGE_STATUS_NOT_MERGED_VIEWS_MISMATCH_EXT = 4,
    VK_SUBPASS_MERGE_STATUS_NOT_MERGED_ALIASING_EXT = 5,
    VK_SUBPASS_MERGE_STATUS_NOT_MERGED_DEPENDENCIES_EXT = 6,
    VK_SUBPASS_MERGE_STATUS_NOT_MERGED_INCOMPATIBLE_INPUT_ATTACHMENT_EXT = 7,
    VK_SUBPASS_MERGE_STATUS_NOT_MERGED_TOO_MANY_ATTACHMENTS_EXT = 8,
    VK_SUBPASS_MERGE_STATUS_NOT_MERGED_INSUFFICIENT_STORAGE_EXT = 9,
    VK_SUBPASS_MERGE_STATUS_NOT_MERGED_DEPTH_STENCIL_COUNT_EXT = 10,
    VK_SUBPASS_MERGE_STATUS_NOT_MERGED_RESOLVE_ATTACHMENT_REUSE_EXT = 11,
    VK_SUBPASS_MERGE_STATUS_NOT_MERGED_SINGLE_SUBPASS_EXT = 12,
    VK_SUBPASS_MERGE_STATUS_NOT_MERGED_UNSPECIFIED_EXT = 13,
} VkSubpassMergeStatusEXT;

  • VK_SUBPASS_MERGE_STATUS_MERGED_EXT specifies the subpass is merged with a previous subpass.

  • VK_SUBPASS_MERGE_STATUS_DISALLOWED_EXT specifies the subpass is disallowed to merge with previous subpass. If the render pass does not allow subpass merging, then all subpass statuses are set to this value. If a subpass description does not allow subpass merging, then only that subpass’s status is set to this value.

  • VK_SUBPASS_MERGE_STATUS_NOT_MERGED_SIDE_EFFECTS_EXT specifies the subpass is not merged because it contains side effects.

  • VK_SUBPASS_MERGE_STATUS_NOT_MERGED_SAMPLES_MISMATCH_EXT specifies the subpass is not merged because sample count is not compatible with previous subpass.

  • VK_SUBPASS_MERGE_STATUS_NOT_MERGED_VIEWS_MISMATCH_EXT specifies the subpass is not merged because view masks do not match with previous subpass.

  • VK_SUBPASS_MERGE_STATUS_NOT_MERGED_ALIASING_EXT specifies the subpass is not merged because of attachments aliasing between them.

  • VK_SUBPASS_MERGE_STATUS_NOT_MERGED_DEPENDENCIES_EXT specifies the subpass is not merged because subpass dependencies do not allow merging.

  • VK_SUBPASS_MERGE_STATUS_NOT_MERGED_INCOMPATIBLE_INPUT_ATTACHMENT_EXT specifies the subpass is not merged because input attachment is not a color attachment from previous subpass or the formats are incompatible.

  • VK_SUBPASS_MERGE_STATUS_NOT_MERGED_TOO_MANY_ATTACHMENTS_EXT specifies the subpass is not merged because of too many attachments.

  • VK_SUBPASS_MERGE_STATUS_NOT_MERGED_INSUFFICIENT_STORAGE_EXT specifies the subpass is not merged because of insufficient memory.

  • VK_SUBPASS_MERGE_STATUS_NOT_MERGED_DEPTH_STENCIL_COUNT_EXT specifies the subpass is not merged because of too many depth/stencil attachments.

  • VK_SUBPASS_MERGE_STATUS_NOT_MERGED_RESOLVE_ATTACHMENT_REUSE_EXT specifies the subpass is not merged because a resolve attachment is reused as an input attachment in a subsequent subpass.

  • VK_SUBPASS_MERGE_STATUS_NOT_MERGED_SINGLE_SUBPASS_EXT specifies the subpass is not merged because the render pass has only one subpass.

  • VK_SUBPASS_MERGE_STATUS_NOT_MERGED_UNSPECIFIED_EXT specifies other reasons why subpass is not merged. It is also the recommended default value that should be reported when a subpass is not merged and when no other value is appropriate.

8.10. Common Render Pass Data Races (Informative)

Due to the complexity of how rendering is performed, there are several ways an application can accidentally introduce a data race, usually by doing something that may seem benign but actually cannot be supported. This section indicates a number of the more common cases as guidelines to help avoid them.

8.10.1. Sampling From a Read-only Attachment

Vulkan includes read-only layouts for depth/stencil images, that allow the images to be both read during a render pass for the purposes of depth/stencil tests, and read as a non-attachment.

However, because VK_ATTACHMENT_STORE_OP_STORE and VK_ATTACHMENT_STORE_OP_DONT_CARE may perform write operations, even if no recorded command writes to an attachment, reading from an image while also using it as an attachment with these store operations can result in a data race. If the reads from the non-attachment are performed in a fragment shader where the accessed samples match those covered by the fragment shader, no data race will occur as store operations are guaranteed to operate after fragment shader execution for the set of samples the fragment covers. Notably, input attachments can also be used for this case. Reading other samples or in any other shader stage can result in unexpected behavior due to the potential for a data race, and validation errors should be generated for doing so. In practice, many applications have shipped reading samples outside of the covered fragment without any observable issue, but there is no guarantee that this will always work, and it is not advisable to rely on this in new or re-worked code bases. As VK_ATTACHMENT_STORE_OP_NONE is guaranteed to perform no writes, applications wishing to read an image as both an attachment and a non-attachment should make use of this store operation, coupled with a load operation that also performs no writes.

8.10.2. Non-overlapping Access Between Resources

When relying on non-overlapping accesses between attachments and other resources, it is important to note that load and store operations have fairly wide alignment requirements - potentially affecting entire subresources and adjacent depth/stencil aspects. This makes it invalid to access a non-attachment subresource that is simultaneously being used as an attachment where either access performs a write operation.

The only exception to this is if a subresource is in the VK_IMAGE_LAYOUT_ATTACHMENT_FEEDBACK_LOOP_OPTIMAL_EXT image layout, in which case the overlap is defined to occur at a per-pixel granularity, and applications can read data from pixels outside the render area without introducing a data race.

8.10.3. Depth/Stencil and Input Attachments

When rendering to only the depth OR stencil aspect of an image, an input attachment accessing the other aspect will not cause a data race only under very specific conditions. To avoid a data race, the aspect not being written must be in a read-only layout, and writes to it must be disabled in the draw state. For example, to read from stencil while writing depth, the attachment must be in VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL (or equivalent), and the stencil write mask must be set to 0. Similarly to read from depth while writing stencil, the attachment must be in VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL (or equivalent), and depth write enable must be VK_FALSE.

8.10.4. Synchronization Options

There are several synchronization options available to synchronize between accesses to resources within a render pass. Some of the options are outlined below:

  • A VkSubpassDependency in a render pass object can synchronize attachment writes and multisample resolve operations from a prior subpass for subsequent input attachment reads.

  • A vkCmdPipelineBarrier inside a subpass can synchronize prior attachment writes in the subpass with subsequent input attachment reads.

  • A vkCmdPipelineBarrier inside a subpass can synchronize prior attachment writes in the subpass with subsequent non-attachment reads if the attachment is in the VK_IMAGE_LAYOUT_ATTACHMENT_FEEDBACK_LOOP_OPTIMAL_EXT image layout.

  • If a subresource is used as a color and input attachment, and the pipeline performing the read was created with VK_PIPELINE_COLOR_BLEND_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_ACCESS_BIT_EXT

  • If a subresource is used as a depth and input attachment, and the pipeline performing the read was created with VK_PIPELINE_DEPTH_STENCIL_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_DEPTH_ACCESS_BIT_EXT

  • If a subresource is used as a stencil and input attachment, and the pipeline performing the read was created with VK_PIPELINE_DEPTH_STENCIL_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_STENCIL_ACCESS_BIT_EXT

  • If a subresource is used as two separate non-attachment resources, writes to a pixel or individual sample in a fragment shader can be synchronized with access to the same pixel or sample in another fragment shader by using one of the fragment interlock execution modes.

9. Shaders

A shader specifies programmable operations that execute for each vertex, control point, tessellated vertex, primitive, fragment, or workgroup in the corresponding stage(s) of the graphics and compute pipelines.

Graphics pipelines include vertex shader execution as a result of primitive assembly, followed, if enabled, by tessellation control and evaluation shaders operating on patches, geometry shaders, if enabled, operating on primitives, and fragment shaders, if present, operating on fragments generated by Rasterization. In this specification, vertex, tessellation control, tessellation evaluation and geometry shaders are collectively referred to as pre-rasterization shader stages and occur in the logical pipeline before rasterization. The fragment shader occurs logically after rasterization.

Only the compute shader stage is included in a compute pipeline. Compute shaders operate on compute invocations in a workgroup.

Shaders can read from input variables, and read from and write to output variables. Input and output variables can be used to transfer data between shader stages, or to allow the shader to interact with values that exist in the execution environment. Similarly, the execution environment provides constants describing capabilities.

Shader variables are associated with execution environment-provided inputs and outputs using built-in decorations in the shader. The available decorations for each stage are documented in the following subsections.

9.1. Shader Objects

Shaders may be compiled and linked into pipeline objects as described in Pipelines chapter, or if the shaderObject feature is enabled they may be compiled into individual per-stage shader objects which can be bound on a command buffer independently from one another. Unlike pipelines, shader objects are not intrinsically tied to any specific set of state. Instead, state is specified dynamically in the command buffer.

Each shader object represents a single compiled shader stage, which may optionally be linked with one or more other stages.

Shader objects are represented by VkShaderEXT handles:

// Provided by VK_EXT_shader_object
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkShaderEXT)

9.1.1. Shader Object Creation

Shader objects may be created from shader code provided as SPIR-V, or in an opaque, implementation-defined binary format specific to the physical device.

To create one or more shader objects, call:

// Provided by VK_EXT_shader_object
VkResult vkCreateShadersEXT(
    VkDevice                                    device,
    uint32_t                                    createInfoCount,
    const VkShaderCreateInfoEXT*                pCreateInfos,
    const VkAllocationCallbacks*                pAllocator,
    VkShaderEXT*                                pShaders);

  • device is the logical device that creates the shader objects.

  • createInfoCount is the length of the pCreateInfos and pShaders arrays.

  • pCreateInfos is a pointer to an array of VkShaderCreateInfoEXT structures.

  • pAllocator controls host memory allocation as described in the Memory Allocation chapter.

  • pShaders is a pointer to an array of VkShaderEXT handles in which the resulting shader objects are returned.

When this function returns, whether or not it succeeds, it is guaranteed that every element of pShaders will have been overwritten by either VK_NULL_HANDLE or a valid VkShaderEXT handle.

This means that whenever shader creation fails, the application can determine which shader the returned error pertains to by locating the first VK_NULL_HANDLE element in pShaders. It also means that an application can reliably clean up from a failed call by iterating over the pShaders array and destroying every element that is not VK_NULL_HANDLE.

Valid Usage

  • VUID-vkCreateShadersEXT-device-09669
    device must support at least one queue family with one of the VK_QUEUE_COMPUTE_BIT or VK_QUEUE_GRAPHICS_BIT capabilities

  • VUID-vkCreateShadersEXT-stage-09670
    If the stage member of any element of pCreateInfos is VK_SHADER_STAGE_COMPUTE_BIT, device must support at least one queue family with the VK_QUEUE_COMPUTE_BIT capability

  • VUID-vkCreateShadersEXT-stage-09671
    If the stage member of any element of pCreateInfos is VK_SHADER_STAGE_TASK_BIT_EXT, VK_SHADER_STAGE_MESH_BIT_EXT, VK_SHADER_STAGE_VERTEX_BIT, VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT, VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT, VK_SHADER_STAGE_GEOMETRY_BIT, or VK_SHADER_STAGE_FRAGMENT_BIT, device must support at least one queue family with the VK_QUEUE_GRAPHICS_BIT capability

  • VUID-vkCreateShadersEXT-None-08400
    The shaderObject feature must be enabled

  • VUID-vkCreateShadersEXT-pCreateInfos-08402
    If the flags member of any element of pCreateInfos includes VK_SHADER_CREATE_LINK_STAGE_BIT_EXT, the flags member of all other elements of pCreateInfos whose stage is VK_SHADER_STAGE_VERTEX_BIT, VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT, VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT, VK_SHADER_STAGE_GEOMETRY_BIT, or VK_SHADER_STAGE_FRAGMENT_BIT must also include VK_SHADER_CREATE_LINK_STAGE_BIT_EXT

  • VUID-vkCreateShadersEXT-pCreateInfos-08403
    If the flags member of any element of pCreateInfos includes VK_SHADER_CREATE_LINK_STAGE_BIT_EXT, the flags member of all other elements of pCreateInfos whose stage is VK_SHADER_STAGE_TASK_BIT_EXT or VK_SHADER_STAGE_MESH_BIT_EXT must also include VK_SHADER_CREATE_LINK_STAGE_BIT_EXT

  • VUID-vkCreateShadersEXT-pCreateInfos-08404
    If the flags member of any element of pCreateInfos whose stage is VK_SHADER_STAGE_TASK_BIT_EXT or VK_SHADER_STAGE_MESH_BIT_EXT includes VK_SHADER_CREATE_LINK_STAGE_BIT_EXT, there must be no member of pCreateInfos whose stage is VK_SHADER_STAGE_VERTEX_BIT and whose flags member includes VK_SHADER_CREATE_LINK_STAGE_BIT_EXT

  • VUID-vkCreateShadersEXT-pCreateInfos-08405
    If there is any element of pCreateInfos whose stage is VK_SHADER_STAGE_MESH_BIT_EXT and whose flags member includes both VK_SHADER_CREATE_LINK_STAGE_BIT_EXT and VK_SHADER_CREATE_NO_TASK_SHADER_BIT_EXT, there must be no element of pCreateInfos whose stage is VK_SHADER_STAGE_TASK_BIT_EXT and whose flags member includes VK_SHADER_CREATE_LINK_STAGE_BIT_EXT

  • VUID-vkCreateShadersEXT-pCreateInfos-08409
    For each element of pCreateInfos whose flags member includes VK_SHADER_CREATE_LINK_STAGE_BIT_EXT, if there is any other element of pCreateInfos whose stage is logically later than the stage of the former and whose flags member also includes VK_SHADER_CREATE_LINK_STAGE_BIT_EXT, the nextStage of the former must be equal to the stage of the element with the logically earliest stage following the stage of the former whose flags member also includes VK_SHADER_CREATE_LINK_STAGE_BIT_EXT

  • VUID-vkCreateShadersEXT-pCreateInfos-08410
    The stage member of each element of pCreateInfos whose flags member includes VK_SHADER_CREATE_LINK_STAGE_BIT_EXT must be unique

  • VUID-vkCreateShadersEXT-pCreateInfos-08411
    The codeType member of all elements of pCreateInfos whose flags member includes VK_SHADER_CREATE_LINK_STAGE_BIT_EXT must be the same

  • VUID-vkCreateShadersEXT-pCreateInfos-08867
    If pCreateInfos contains elements with both VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT and VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT, both elements' flags include VK_SHADER_CREATE_LINK_STAGE_BIT_EXT, both elements' codeType is VK_SHADER_CODE_TYPE_SPIRV_EXT, and the VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT stage’s pCode contains an OpExecutionMode instruction specifying the type of subdivision, it must match the subdivision type specified in the VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT stage

  • VUID-vkCreateShadersEXT-pCreateInfos-08868
    If pCreateInfos contains elements with both VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT and VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT, both elements' flags include VK_SHADER_CREATE_LINK_STAGE_BIT_EXT, both elements' codeType is VK_SHADER_CODE_TYPE_SPIRV_EXT, and the VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT stage’s pCode contains an OpExecutionMode instruction specifying the orientation of triangles, it must match the triangle orientation specified in the VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT stage

  • VUID-vkCreateShadersEXT-pCreateInfos-08869
    If pCreateInfos contains elements with both VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT and VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT, both elements' flags include VK_SHADER_CREATE_LINK_STAGE_BIT_EXT, both elements' codeType is VK_SHADER_CODE_TYPE_SPIRV_EXT, and the VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT stage’s pCode contains an OpExecutionMode instruction specifying PointMode, the VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT stage must also contain an OpExecutionMode instruction specifying PointMode

  • VUID-vkCreateShadersEXT-pCreateInfos-08870
    If pCreateInfos contains elements with both VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT and VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT, both elements' flags include VK_SHADER_CREATE_LINK_STAGE_BIT_EXT, both elements' codeType is VK_SHADER_CODE_TYPE_SPIRV_EXT, and the VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT stage’s pCode contains an OpExecutionMode instruction specifying the spacing of segments on the edges of tessellated primitives, it must match the segment spacing specified in the VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT stage

  • VUID-vkCreateShadersEXT-pCreateInfos-08871
    If pCreateInfos contains elements with both VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT and VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT, both elements' flags include VK_SHADER_CREATE_LINK_STAGE_BIT_EXT, both elements' codeType is VK_SHADER_CODE_TYPE_SPIRV_EXT, and the VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT stage’s pCode contains an OpExecutionMode instruction specifying the output patch size, it must match the output patch size specified in the VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT stage

  • VUID-vkCreateShadersEXT-pCreateInfos-09632
    If pCreateInfos contains a VK_SHADER_STAGE_MESH_BIT_EXT with codeType of VK_SHADER_CODE_TYPE_SPIRV_EXT and VK_SHADER_CREATE_NO_TASK_SHADER_BIT_EXT is not set, then the mesh shader’s entry point must not declare a variable with a DrawIndex BuiltIn decoration

Valid Usage (Implicit)

  • VUID-vkCreateShadersEXT-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkCreateShadersEXT-pCreateInfos-parameter
    pCreateInfos must be a valid pointer to an array of createInfoCount valid VkShaderCreateInfoEXT structures

  • VUID-vkCreateShadersEXT-pAllocator-parameter
    If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure

  • VUID-vkCreateShadersEXT-pShaders-parameter
    pShaders must be a valid pointer to an array of createInfoCount VkShaderEXT handles

  • VUID-vkCreateShadersEXT-createInfoCount-arraylength
    createInfoCount must be greater than 0

Return Codes
Success

  • VK_SUCCESS

  • VK_INCOMPATIBLE_SHADER_BINARY_EXT

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

  • VK_ERROR_INITIALIZATION_FAILED

The VkShaderCreateInfoEXT structure is defined as:

// Provided by VK_EXT_shader_object
typedef struct VkShaderCreateInfoEXT {
    VkStructureType                 sType;
    const void*                     pNext;
    VkShaderCreateFlagsEXT          flags;
    VkShaderStageFlagBits           stage;
    VkShaderStageFlags              nextStage;
    VkShaderCodeTypeEXT             codeType;
    size_t                          codeSize;
    const void*                     pCode;
    const char*                     pName;
    uint32_t                        setLayoutCount;
    const VkDescriptorSetLayout*    pSetLayouts;
    uint32_t                        pushConstantRangeCount;
    const VkPushConstantRange*      pPushConstantRanges;
    const VkSpecializationInfo*     pSpecializationInfo;
} VkShaderCreateInfoEXT;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • flags is a bitmask of VkShaderCreateFlagBitsEXT describing additional parameters of the shader.

  • stage is a VkShaderStageFlagBits value specifying a single shader stage.

  • nextStage is a bitmask of VkShaderStageFlagBits specifying zero or stages which may be used as a logically next bound stage when drawing with the shader bound.

  • codeType is a VkShaderCodeTypeEXT value specifying the type of the shader code pointed to be pCode.

  • codeSize is the size in bytes of the shader code pointed to be pCode.

  • pCode is a pointer to the shader code to use to create the shader.

  • pName is a pointer to a null-terminated UTF-8 string specifying the entry point name of the shader for this stage.

  • setLayoutCount is the number of descriptor set layouts pointed to by pSetLayouts.

  • pSetLayouts is a pointer to an array of VkDescriptorSetLayout objects used by the shader stage.

  • pushConstantRangeCount is the number of push constant ranges pointed to by pPushConstantRanges.

  • pPushConstantRanges is a pointer to an array of VkPushConstantRange structures used by the shader stage.

  • pSpecializationInfo is a pointer to a VkSpecializationInfo structure, as described in Specialization Constants, or NULL.

Valid Usage

  • VUID-VkShaderCreateInfoEXT-codeSize-08735
    If codeType is VK_SHADER_CODE_TYPE_SPIRV_EXT, codeSize must be a multiple of 4

  • VUID-VkShaderCreateInfoEXT-pCode-08736
    If codeType is VK_SHADER_CODE_TYPE_SPIRV_EXT, pCode must point to valid SPIR-V code, formatted and packed as described by the Khronos SPIR-V Specification

  • VUID-VkShaderCreateInfoEXT-pCode-08737
    If codeType is VK_SHADER_CODE_TYPE_SPIRV_EXT, pCode must adhere to the validation rules described by the Validation Rules within a Module section of the SPIR-V Environment appendix

  • VUID-VkShaderCreateInfoEXT-pCode-08738
    If codeType is VK_SHADER_CODE_TYPE_SPIRV_EXT, pCode must declare the Shader capability for SPIR-V code

  • VUID-VkShaderCreateInfoEXT-pCode-08739
    If codeType is VK_SHADER_CODE_TYPE_SPIRV_EXT, pCode must not declare any capability that is not supported by the API, as described by the Capabilities section of the SPIR-V Environment appendix

  • VUID-VkShaderCreateInfoEXT-pCode-08740
    If codeType is VK_SHADER_CODE_TYPE_SPIRV_EXT, and pCode declares any of the capabilities listed in the SPIR-V Environment appendix, one of the corresponding requirements must be satisfied

  • VUID-VkShaderCreateInfoEXT-pCode-08741
    If codeType is VK_SHADER_CODE_TYPE_SPIRV_EXT, pCode must not declare any SPIR-V extension that is not supported by the API, as described by the Extension section of the SPIR-V Environment appendix

  • VUID-VkShaderCreateInfoEXT-pCode-08742
    If codeType is VK_SHADER_CODE_TYPE_SPIRV_EXT, and pCode declares any of the SPIR-V extensions listed in the SPIR-V Environment appendix, one of the corresponding requirements must be satisfied

  • VUID-VkShaderCreateInfoEXT-flags-08412
    If stage is not VK_SHADER_STAGE_TASK_BIT_EXT, VK_SHADER_STAGE_MESH_BIT_EXT, VK_SHADER_STAGE_VERTEX_BIT, VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT, VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT, VK_SHADER_STAGE_GEOMETRY_BIT, or VK_SHADER_STAGE_FRAGMENT_BIT, flags must not include VK_SHADER_CREATE_LINK_STAGE_BIT_EXT

  • VUID-VkShaderCreateInfoEXT-flags-08486
    If stage is not VK_SHADER_STAGE_FRAGMENT_BIT, flags must not include VK_SHADER_CREATE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_EXT

  • VUID-VkShaderCreateInfoEXT-flags-08487
    If the attachmentFragmentShadingRate feature is not enabled, flags must not include VK_SHADER_CREATE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_EXT

  • VUID-VkShaderCreateInfoEXT-flags-08488
    If stage is not VK_SHADER_STAGE_FRAGMENT_BIT, flags must not include VK_SHADER_CREATE_FRAGMENT_DENSITY_MAP_ATTACHMENT_BIT_EXT

  • VUID-VkShaderCreateInfoEXT-flags-08489
    If the fragmentDensityMap feature is not enabled, flags must not include VK_SHADER_CREATE_FRAGMENT_DENSITY_MAP_ATTACHMENT_BIT_EXT

  • VUID-VkShaderCreateInfoEXT-flags-09404
    If flags includes VK_SHADER_CREATE_ALLOW_VARYING_SUBGROUP_SIZE_BIT_EXT, the subgroupSizeControl feature must be enabled

  • VUID-VkShaderCreateInfoEXT-flags-09405
    If flags includes VK_SHADER_CREATE_REQUIRE_FULL_SUBGROUPS_BIT_EXT, the computeFullSubgroups feature must be enabled

  • VUID-VkShaderCreateInfoEXT-flags-11005
    If flags includes VK_SHADER_CREATE_INDIRECT_BINDABLE_BIT_EXT, then the deviceGeneratedCommands feature must be enabled

  • VUID-VkShaderCreateInfoEXT-flags-11006
    If flags includes VK_SHADER_CREATE_INDIRECT_BINDABLE_BIT_EXT, then the identified entry point must not specify Xfb execution mode

  • VUID-VkShaderCreateInfoEXT-flags-08992
    If flags includes VK_SHADER_CREATE_REQUIRE_FULL_SUBGROUPS_BIT_EXT, stage must be one of VK_SHADER_STAGE_MESH_BIT_EXT, VK_SHADER_STAGE_TASK_BIT_EXT, or VK_SHADER_STAGE_COMPUTE_BIT

  • VUID-VkShaderCreateInfoEXT-flags-08485
    If stage is not VK_SHADER_STAGE_COMPUTE_BIT, flags must not include VK_SHADER_CREATE_DISPATCH_BASE_BIT_EXT

  • VUID-VkShaderCreateInfoEXT-flags-08414
    If stage is not VK_SHADER_STAGE_MESH_BIT_EXT, flags must not include VK_SHADER_CREATE_NO_TASK_SHADER_BIT_EXT

  • VUID-VkShaderCreateInfoEXT-flags-08416
    If flags includes both VK_SHADER_CREATE_ALLOW_VARYING_SUBGROUP_SIZE_BIT_EXT and VK_SHADER_CREATE_REQUIRE_FULL_SUBGROUPS_BIT_EXT, the local workgroup size in the X dimension of the shader must be a multiple of maxSubgroupSize

  • VUID-VkShaderCreateInfoEXT-flags-08417
    If flags includes VK_SHADER_CREATE_REQUIRE_FULL_SUBGROUPS_BIT_EXT but not VK_SHADER_CREATE_ALLOW_VARYING_SUBGROUP_SIZE_BIT_EXT and no VkShaderRequiredSubgroupSizeCreateInfoEXT structure is included in the pNext chain, the local workgroup size in the X dimension of the shader must be a multiple of subgroupSize

  • VUID-VkShaderCreateInfoEXT-stage-08418
    stage must not be VK_SHADER_STAGE_ALL_GRAPHICS or VK_SHADER_STAGE_ALL

  • VUID-VkShaderCreateInfoEXT-stage-08419
    If the tessellationShader feature is not enabled, stage must not be VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT or VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT

  • VUID-VkShaderCreateInfoEXT-stage-08420
    If the geometryShader feature is not enabled, stage must not be VK_SHADER_STAGE_GEOMETRY_BIT

  • VUID-VkShaderCreateInfoEXT-stage-08421
    If the taskShader feature is not enabled, stage must not be VK_SHADER_STAGE_TASK_BIT_EXT

  • VUID-VkShaderCreateInfoEXT-stage-08422
    If the meshShader feature is not enabled, stage must not be VK_SHADER_STAGE_MESH_BIT_EXT

  • VUID-VkShaderCreateInfoEXT-stage-08425
    stage must not be VK_SHADER_STAGE_SUBPASS_SHADING_BIT_HUAWEI

  • VUID-VkShaderCreateInfoEXT-stage-08426
    stage must not be VK_SHADER_STAGE_CLUSTER_CULLING_BIT_HUAWEI

  • VUID-VkShaderCreateInfoEXT-nextStage-08427
    If stage is VK_SHADER_STAGE_VERTEX_BIT, nextStage must not include any bits other than VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT, VK_SHADER_STAGE_GEOMETRY_BIT, and VK_SHADER_STAGE_FRAGMENT_BIT

  • VUID-VkShaderCreateInfoEXT-nextStage-08428
    If the tessellationShader feature is not enabled, nextStage must not include VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT or VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT

  • VUID-VkShaderCreateInfoEXT-nextStage-08429
    If the geometryShader feature is not enabled, nextStage must not include VK_SHADER_STAGE_GEOMETRY_BIT

  • VUID-VkShaderCreateInfoEXT-nextStage-08430
    If stage is VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT, nextStage must not include any bits other than VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT

  • VUID-VkShaderCreateInfoEXT-nextStage-08431
    If stage is VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT, nextStage must not include any bits other than VK_SHADER_STAGE_GEOMETRY_BIT and VK_SHADER_STAGE_FRAGMENT_BIT

  • VUID-VkShaderCreateInfoEXT-nextStage-08433
    If stage is VK_SHADER_STAGE_GEOMETRY_BIT, nextStage must not include any bits other than VK_SHADER_STAGE_FRAGMENT_BIT

  • VUID-VkShaderCreateInfoEXT-nextStage-08434
    If stage is VK_SHADER_STAGE_FRAGMENT_BIT or VK_SHADER_STAGE_COMPUTE_BIT, nextStage must be 0

  • VUID-VkShaderCreateInfoEXT-nextStage-08435
    If stage is VK_SHADER_STAGE_TASK_BIT_EXT, nextStage must not include any bits other than VK_SHADER_STAGE_MESH_BIT_EXT

  • VUID-VkShaderCreateInfoEXT-nextStage-08436
    If stage is VK_SHADER_STAGE_MESH_BIT_EXT, nextStage must not include any bits other than VK_SHADER_STAGE_FRAGMENT_BIT

  • VUID-VkShaderCreateInfoEXT-pName-08440
    If codeType is VK_SHADER_CODE_TYPE_SPIRV_EXT, pName must be the name of an OpEntryPoint in pCode with an execution model that matches stage

  • VUID-VkShaderCreateInfoEXT-pCode-08492
    If codeType is VK_SHADER_CODE_TYPE_BINARY_EXT, pCode must be aligned to 16 bytes

  • VUID-VkShaderCreateInfoEXT-pCode-08493
    If codeType is VK_SHADER_CODE_TYPE_SPIRV_EXT, pCode must be aligned to 4 bytes

  • VUID-VkShaderCreateInfoEXT-pCode-08448
    If codeType is VK_SHADER_CODE_TYPE_SPIRV_EXT, and the identified entry point includes any variable in its interface that is declared with the ClipDistance BuiltIn decoration, that variable must not have an array size greater than VkPhysicalDeviceLimits::maxClipDistances

  • VUID-VkShaderCreateInfoEXT-pCode-08449
    If codeType is VK_SHADER_CODE_TYPE_SPIRV_EXT, and the identified entry point includes any variable in its interface that is declared with the CullDistance BuiltIn decoration, that variable must not have an array size greater than VkPhysicalDeviceLimits::maxCullDistances

  • VUID-VkShaderCreateInfoEXT-pCode-08450
    If codeType is VK_SHADER_CODE_TYPE_SPIRV_EXT, and the identified entry point includes variables in its interface that are declared with the ClipDistance BuiltIn decoration and variables in its interface that are declared with the CullDistance BuiltIn decoration, those variables must not have array sizes which sum to more than VkPhysicalDeviceLimits::maxCombinedClipAndCullDistances

  • VUID-VkShaderCreateInfoEXT-pCode-08451
    If codeType is VK_SHADER_CODE_TYPE_SPIRV_EXT, and the identified entry point includes any variable in its interface that is declared with the SampleMask BuiltIn decoration, that variable must not have an array size greater than VkPhysicalDeviceLimits::maxSampleMaskWords

  • VUID-VkShaderCreateInfoEXT-pCode-08452
    If codeType is VK_SHADER_CODE_TYPE_SPIRV_EXT, and stage is VK_SHADER_STAGE_VERTEX_BIT, the identified entry point must not include any input variable in its interface that is decorated with CullDistance

  • VUID-VkShaderCreateInfoEXT-pCode-08453
    If codeType is VK_SHADER_CODE_TYPE_SPIRV_EXT, and stage is VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT or VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT, and the identified entry point has an OpExecutionMode instruction specifying a patch size with OutputVertices, the patch size must be greater than 0 and less than or equal to VkPhysicalDeviceLimits::maxTessellationPatchSize

  • VUID-VkShaderCreateInfoEXT-pCode-08454
    If codeType is VK_SHADER_CODE_TYPE_SPIRV_EXT, and stage is VK_SHADER_STAGE_GEOMETRY_BIT, the identified entry point must have an OpExecutionMode instruction specifying a maximum output vertex count that is greater than 0 and less than or equal to VkPhysicalDeviceLimits::maxGeometryOutputVertices

  • VUID-VkShaderCreateInfoEXT-pCode-08455
    If codeType is VK_SHADER_CODE_TYPE_SPIRV_EXT, and stage is VK_SHADER_STAGE_GEOMETRY_BIT, the identified entry point must have an OpExecutionMode instruction specifying an invocation count that is greater than 0 and less than or equal to VkPhysicalDeviceLimits::maxGeometryShaderInvocations

  • VUID-VkShaderCreateInfoEXT-pCode-08456
    If codeType is VK_SHADER_CODE_TYPE_SPIRV_EXT, and stage is a pre-rasterization shader stage, and the identified entry point writes to Layer for any primitive, it must write the same value to Layer for all vertices of a given primitive

  • VUID-VkShaderCreateInfoEXT-pCode-08457
    If codeType is VK_SHADER_CODE_TYPE_SPIRV_EXT, and stage is a pre-rasterization shader stage, and the identified entry point writes to ViewportIndex for any primitive, it must write the same value to ViewportIndex for all vertices of a given primitive

  • VUID-VkShaderCreateInfoEXT-pCode-08458
    If codeType is VK_SHADER_CODE_TYPE_SPIRV_EXT, and stage is VK_SHADER_STAGE_FRAGMENT_BIT, the identified entry point must not include any output variables in its interface decorated with CullDistance

  • VUID-VkShaderCreateInfoEXT-pCode-08459
    If codeType is VK_SHADER_CODE_TYPE_SPIRV_EXT, and stage is VK_SHADER_STAGE_FRAGMENT_BIT, and the identified entry point writes to FragDepth in any execution path, all execution paths that are not exclusive to helper invocations must either discard the fragment, or write or initialize the value of FragDepth

  • VUID-VkShaderCreateInfoEXT-pCode-08460
    If codeType is VK_SHADER_CODE_TYPE_SPIRV_EXT, the shader code in pCode must be valid as described by the Khronos SPIR-V Specification after applying the specializations provided in pSpecializationInfo, if any, and then converting all specialization constants into fixed constants

  • VUID-VkShaderCreateInfoEXT-codeType-08872
    If codeType is VK_SHADER_CODE_TYPE_SPIRV_EXT, and stage is VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT, pCode must contain an OpExecutionMode instruction specifying the type of subdivision

  • VUID-VkShaderCreateInfoEXT-codeType-08873
    If codeType is VK_SHADER_CODE_TYPE_SPIRV_EXT, and stage is VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT, pCode must contain an OpExecutionMode instruction specifying the orientation of triangles generated by the tessellator

  • VUID-VkShaderCreateInfoEXT-codeType-08874
    If codeType is VK_SHADER_CODE_TYPE_SPIRV_EXT, and stage is VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT, pCode must contain an OpExecutionMode instruction specifying the spacing of segments on the edges of tessellated primitives

  • VUID-VkShaderCreateInfoEXT-codeType-08875
    If codeType is VK_SHADER_CODE_TYPE_SPIRV_EXT, and stage is VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT, pCode must contain an OpExecutionMode instruction specifying the output patch size

  • VUID-VkShaderCreateInfoEXT-pPushConstantRanges-10063
    Any two elements of pPushConstantRanges must not include the same stage in stageFlags

  • VUID-VkShaderCreateInfoEXT-codeType-10064
    If codeType is VK_SHADER_CODE_TYPE_SPIRV_EXT, and if a push constant block is declared in a shader, then an element of pPushConstantRanges::stageFlags must match pname::stage

  • VUID-VkShaderCreateInfoEXT-codeType-10065
    If codeType is VK_SHADER_CODE_TYPE_SPIRV_EXT, and if a push constant block is declared in a shader, the block must be contained inside the element of pPushConstantRanges that matches the stage

Valid Usage (Implicit)

  • VUID-VkShaderCreateInfoEXT-sType-sType
    sType must be VK_STRUCTURE_TYPE_SHADER_CREATE_INFO_EXT

  • VUID-VkShaderCreateInfoEXT-pNext-pNext
    Each pNext member of any structure (including this one) in the pNext chain must be either NULL or a pointer to a valid instance of VkPipelineShaderStageRequiredSubgroupSizeCreateInfo or VkValidationFeaturesEXT

  • VUID-VkShaderCreateInfoEXT-sType-unique
    The sType value of each struct in the pNext chain must be unique

  • VUID-VkShaderCreateInfoEXT-flags-parameter
    flags must be a valid combination of VkShaderCreateFlagBitsEXT values

  • VUID-VkShaderCreateInfoEXT-stage-parameter
    stage must be a valid VkShaderStageFlagBits value

  • VUID-VkShaderCreateInfoEXT-nextStage-parameter
    nextStage must be a valid combination of VkShaderStageFlagBits values

  • VUID-VkShaderCreateInfoEXT-codeType-parameter
    codeType must be a valid VkShaderCodeTypeEXT value

  • VUID-VkShaderCreateInfoEXT-pCode-parameter
    pCode must be a valid pointer to an array of codeSize bytes

  • VUID-VkShaderCreateInfoEXT-pName-parameter
    If pName is not NULL, pName must be a null-terminated UTF-8 string

  • VUID-VkShaderCreateInfoEXT-pSetLayouts-parameter
    If setLayoutCount is not 0, and pSetLayouts is not NULL, pSetLayouts must be a valid pointer to an array of setLayoutCount valid VkDescriptorSetLayout handles

  • VUID-VkShaderCreateInfoEXT-pPushConstantRanges-parameter
    If pushConstantRangeCount is not 0, and pPushConstantRanges is not NULL, pPushConstantRanges must be a valid pointer to an array of pushConstantRangeCount valid VkPushConstantRange structures

  • VUID-VkShaderCreateInfoEXT-pSpecializationInfo-parameter
    If pSpecializationInfo is not NULL, pSpecializationInfo must be a valid pointer to a valid VkSpecializationInfo structure

  • VUID-VkShaderCreateInfoEXT-codeSize-arraylength
    codeSize must be greater than 0

// Provided by VK_EXT_shader_object
typedef VkFlags VkShaderCreateFlagsEXT;

VkShaderCreateFlagsEXT is a bitmask type for setting a mask of zero or more VkShaderCreateFlagBitsEXT.

Possible values of the flags member of VkShaderCreateInfoEXT specifying how a shader object is created, are:

// Provided by VK_EXT_shader_object
typedef enum VkShaderCreateFlagBitsEXT {
    VK_SHADER_CREATE_LINK_STAGE_BIT_EXT = 0x00000001,
  // Provided by VK_EXT_shader_object with VK_EXT_subgroup_size_control or VK_VERSION_1_3
    VK_SHADER_CREATE_ALLOW_VARYING_SUBGROUP_SIZE_BIT_EXT = 0x00000002,
  // Provided by VK_EXT_shader_object with VK_EXT_subgroup_size_control or VK_VERSION_1_3
    VK_SHADER_CREATE_REQUIRE_FULL_SUBGROUPS_BIT_EXT = 0x00000004,
  // Provided by VK_EXT_shader_object with VK_EXT_mesh_shader or VK_NV_mesh_shader
    VK_SHADER_CREATE_NO_TASK_SHADER_BIT_EXT = 0x00000008,
  // Provided by VK_EXT_shader_object with VK_KHR_device_group or VK_VERSION_1_1
    VK_SHADER_CREATE_DISPATCH_BASE_BIT_EXT = 0x00000010,
  // Provided by VK_KHR_fragment_shading_rate with VK_EXT_shader_object
    VK_SHADER_CREATE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_EXT = 0x00000020,
  // Provided by VK_EXT_fragment_density_map with VK_EXT_shader_object
    VK_SHADER_CREATE_FRAGMENT_DENSITY_MAP_ATTACHMENT_BIT_EXT = 0x00000040,
  // Provided by VK_EXT_device_generated_commands
    VK_SHADER_CREATE_INDIRECT_BINDABLE_BIT_EXT = 0x00000080,
} VkShaderCreateFlagBitsEXT;

  • VK_SHADER_CREATE_LINK_STAGE_BIT_EXT specifies that a shader is linked to all other shaders created in the same vkCreateShadersEXT call whose VkShaderCreateInfoEXT structures' flags include VK_SHADER_CREATE_LINK_STAGE_BIT_EXT.

  • VK_SHADER_CREATE_ALLOW_VARYING_SUBGROUP_SIZE_BIT_EXT specifies that the SubgroupSize may vary in a task, mesh, or compute shader.

  • VK_SHADER_CREATE_REQUIRE_FULL_SUBGROUPS_BIT_EXT specifies that the subgroup sizes must be launched with all invocations active in a task, mesh, or compute shader.

  • VK_SHADER_CREATE_NO_TASK_SHADER_BIT_EXT specifies that a mesh shader must only be used without a task shader. Otherwise, the mesh shader must only be used with a task shader.

  • VK_SHADER_CREATE_DISPATCH_BASE_BIT_EXT specifies that a compute shader can be used with vkCmdDispatchBase with a non-zero base workgroup.

  • VK_SHADER_CREATE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_EXT specifies that a fragment shader can be used with a fragment shading rate attachment.

  • VK_SHADER_CREATE_FRAGMENT_DENSITY_MAP_ATTACHMENT_BIT_EXT specifies that a fragment shader can be used with a fragment density map attachment.

  • VK_SHADER_CREATE_INDIRECT_BINDABLE_BIT_EXT specifies that the shader can be used in combination with Device-Generated Commands.

Note

The behavior of VK_SHADER_CREATE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_EXT and VK_SHADER_CREATE_FRAGMENT_DENSITY_MAP_ATTACHMENT_BIT_EXT differs subtly from the behavior of VK_PIPELINE_CREATE_RENDERING_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR and VK_PIPELINE_CREATE_RENDERING_FRAGMENT_DENSITY_MAP_ATTACHMENT_BIT_EXT in that the shader bit allows, but does not require the shader to be used with that type of attachment. This means that the application need not create multiple shaders when it does not know in advance whether the shader will be used with or without the attachment type, or when it needs the same shader to be compatible with usage both with and without. This may come at some performance cost on some implementations, so applications should still only set bits that are actually necessary.

Shader objects can be created using different types of shader code. Possible values of VkShaderCreateInfoEXT::codeType, are:

// Provided by VK_EXT_shader_object
typedef enum VkShaderCodeTypeEXT {
    VK_SHADER_CODE_TYPE_BINARY_EXT = 0,
    VK_SHADER_CODE_TYPE_SPIRV_EXT = 1,
} VkShaderCodeTypeEXT;

  • VK_SHADER_CODE_TYPE_BINARY_EXT specifies shader code in an opaque, implementation-defined binary format specific to the physical device.

  • VK_SHADER_CODE_TYPE_SPIRV_EXT specifies shader code in SPIR-V format.

9.1.2. Binary Shader Code

Binary shader code can be retrieved from a shader object using the command:

// Provided by VK_EXT_shader_object
VkResult vkGetShaderBinaryDataEXT(
    VkDevice                                    device,
    VkShaderEXT                                 shader,
    size_t*                                     pDataSize,
    void*                                       pData);

  • device is the logical device that shader object was created from.

  • shader is the shader object to retrieve binary shader code from.

  • pDataSize is a pointer to a size_t value related to the size of the binary shader code, as described below.

  • pData is either NULL or a pointer to a buffer.

If pData is NULL, then the size of the binary shader code of the shader object, in bytes, is returned in pDataSize. Otherwise, pDataSize must point to a variable set by the application to the size of the buffer, in bytes, pointed to by pData, and on return the variable is overwritten with the amount of data actually written to pData. If pDataSize is less than the size of the binary shader code, nothing is written to pData, and VK_INCOMPLETE will be returned instead of VK_SUCCESS.

Note

The behavior of this command when pDataSize is too small differs from how some other getter-type commands work in Vulkan. Because shader binary data is only usable in its entirety, it would never be useful for the implementation to return partial data. Because of this, nothing is written to pData unless pDataSize is large enough to fit the data in its entirety.

Binary shader code retrieved using vkGetShaderBinaryDataEXT can be passed to a subsequent call to vkCreateShadersEXT on a compatible physical device by specifying VK_SHADER_CODE_TYPE_BINARY_EXT in the codeType member of VkShaderCreateInfoEXT.

The shader code returned by repeated calls to this function with the same VkShaderEXT is guaranteed to be invariant for the lifetime of the VkShaderEXT object.

Valid Usage

  • VUID-vkGetShaderBinaryDataEXT-None-08461
    The shaderObject feature must be enabled

  • VUID-vkGetShaderBinaryDataEXT-None-08499
    If pData is not NULL, it must be aligned to 16 bytes

Valid Usage (Implicit)

  • VUID-vkGetShaderBinaryDataEXT-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkGetShaderBinaryDataEXT-shader-parameter
    shader must be a valid VkShaderEXT handle

  • VUID-vkGetShaderBinaryDataEXT-pDataSize-parameter
    pDataSize must be a valid pointer to a size_t value

  • VUID-vkGetShaderBinaryDataEXT-pData-parameter
    If the value referenced by pDataSize is not 0, and pData is not NULL, pData must be a valid pointer to an array of pDataSize bytes

  • VUID-vkGetShaderBinaryDataEXT-shader-parent
    shader must have been created, allocated, or retrieved from device

Return Codes
Success

  • VK_SUCCESS

  • VK_INCOMPLETE

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

9.1.3. Binary Shader Compatibility

Binary shader compatibility means that binary shader code returned from a call to vkGetShaderBinaryDataEXT can be passed to a later call to vkCreateShadersEXT, potentially on a different logical and/or physical device, and that this will result in the successful creation of a shader object functionally equivalent to the shader object that the code was originally queried from.

Binary shader code queried from vkGetShaderBinaryDataEXT is not guaranteed to be compatible across all devices, but implementations are required to provide some compatibility guarantees. Applications may determine binary shader compatibility using either (or both) of two mechanisms.

Guaranteed compatibility of shader binaries is expressed through a combination of the shaderBinaryUUID and shaderBinaryVersion members of the VkPhysicalDeviceShaderObjectPropertiesEXT structure queried from a physical device. Binary shaders retrieved from a physical device with a certain shaderBinaryUUID are guaranteed to be compatible with all other physical devices reporting the same shaderBinaryUUID and the same or higher shaderBinaryVersion.

Whenever a new version of an implementation incorporates any changes that affect the output of vkGetShaderBinaryDataEXT, the implementation should either increment shaderBinaryVersion if binary shader code retrieved from older versions remains compatible with the new implementation, or else replace shaderBinaryUUID with a new value if backward compatibility has been broken. Binary shader code queried from a device with a matching shaderBinaryUUID and lower shaderBinaryVersion relative to the device on which vkCreateShadersEXT is being called may be suboptimal for the new device in ways that do not change shader functionality, but it is still guaranteed to be usable to successfully create the shader object(s).

Note

Implementations are encouraged to share shaderBinaryUUID between devices and driver versions to the maximum extent their hardware naturally allows, and are strongly discouraged from ever changing the shaderBinaryUUID for the same hardware except unless absolutely necessary.

In addition to the shader compatibility guarantees described above, it is valid for an application to call vkCreateShadersEXT with binary shader code created on a device with a different or unknown shaderBinaryUUID and/or higher shaderBinaryVersion. In this case, the implementation may use any unspecified means of its choosing to determine whether the provided binary shader code is usable. If it is, vkCreateShadersEXT must return VK_SUCCESS, and the created shader object is guaranteed to be valid. Otherwise, in the absence of some error, vkCreateShadersEXT must return VK_INCOMPATIBLE_SHADER_BINARY_EXT to indicate that the provided binary shader code is not compatible with the device.

9.1.4. Binding Shader Objects

Once shader objects have been created, they can be bound to the command buffer using the command:

// Provided by VK_EXT_shader_object
void vkCmdBindShadersEXT(
    VkCommandBuffer                             commandBuffer,
    uint32_t                                    stageCount,
    const VkShaderStageFlagBits*                pStages,
    const VkShaderEXT*                          pShaders);

  • commandBuffer is the command buffer that the shader object will be bound to.

  • stageCount is the length of the pStages and pShaders arrays.

  • pStages is a pointer to an array of VkShaderStageFlagBits values specifying one stage per array index that is affected by the corresponding value in the pShaders array.

  • pShaders is a pointer to an array of VkShaderEXT handles and/or VK_NULL_HANDLE values describing the shader binding operations to be performed on each stage in pStages.

When binding linked shaders, an application may bind them in any combination of one or more calls to vkCmdBindShadersEXT (i.e., shaders that were created linked together do not need to be bound in the same vkCmdBindShadersEXT call).

Any shader object bound to a particular stage may be unbound by setting its value in pShaders to VK_NULL_HANDLE. If pShaders is NULL, vkCmdBindShadersEXT behaves as if pShaders was an array of stageCount VK_NULL_HANDLE values (i.e., any shaders bound to the stages specified in pStages are unbound).

Valid Usage

  • VUID-vkCmdBindShadersEXT-None-08462
    The shaderObject feature must be enabled

  • VUID-vkCmdBindShadersEXT-pStages-08463
    Every element of pStages must be unique

  • VUID-vkCmdBindShadersEXT-pStages-08464
    pStages must not contain VK_SHADER_STAGE_ALL_GRAPHICS or VK_SHADER_STAGE_ALL

  • VUID-vkCmdBindShadersEXT-pStages-08465
    pStages must not contain VK_SHADER_STAGE_RAYGEN_BIT_KHR, VK_SHADER_STAGE_ANY_HIT_BIT_KHR, VK_SHADER_STAGE_CLOSEST_HIT_BIT_KHR, VK_SHADER_STAGE_MISS_BIT_KHR, VK_SHADER_STAGE_INTERSECTION_BIT_KHR, or VK_SHADER_STAGE_CALLABLE_BIT_KHR

  • VUID-vkCmdBindShadersEXT-pStages-08467
    pStages must not contain VK_SHADER_STAGE_SUBPASS_SHADING_BIT_HUAWEI

  • VUID-vkCmdBindShadersEXT-pStages-08468
    pStages must not contain VK_SHADER_STAGE_CLUSTER_CULLING_BIT_HUAWEI

  • VUID-vkCmdBindShadersEXT-pShaders-08469
    For each element of pStages, if pShaders is not NULL, and the element of the pShaders array with the same index is not VK_NULL_HANDLE, it must have been created with a stage equal to the corresponding element of pStages

  • VUID-vkCmdBindShadersEXT-pShaders-08470
    If pStages contains both VK_SHADER_STAGE_TASK_BIT_EXT and VK_SHADER_STAGE_VERTEX_BIT, and pShaders is not NULL, and the same index in pShaders as VK_SHADER_STAGE_TASK_BIT_EXT in pStages is not VK_NULL_HANDLE, the same index in pShaders as VK_SHADER_STAGE_VERTEX_BIT in pStages must be VK_NULL_HANDLE

  • VUID-vkCmdBindShadersEXT-pShaders-08471
    If pStages contains both VK_SHADER_STAGE_MESH_BIT_EXT and VK_SHADER_STAGE_VERTEX_BIT, and pShaders is not NULL, and the same index in pShaders as VK_SHADER_STAGE_MESH_BIT_EXT in pStages is not VK_NULL_HANDLE, the same index in pShaders as VK_SHADER_STAGE_VERTEX_BIT in pStages must be VK_NULL_HANDLE

  • VUID-vkCmdBindShadersEXT-pShaders-08474
    If the tessellationShader feature is not enabled, and pStages contains VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT or VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT, and pShaders is not NULL, the same index or indices in pShaders must be VK_NULL_HANDLE

  • VUID-vkCmdBindShadersEXT-pShaders-08475
    If the geometryShader feature is not enabled, and pStages contains VK_SHADER_STAGE_GEOMETRY_BIT, and pShaders is not NULL, the same index in pShaders must be VK_NULL_HANDLE

  • VUID-vkCmdBindShadersEXT-pShaders-08490
    If the taskShader feature is not enabled, and pStages contains VK_SHADER_STAGE_TASK_BIT_EXT, and pShaders is not NULL, the same index in pShaders must be VK_NULL_HANDLE

  • VUID-vkCmdBindShadersEXT-pShaders-08491
    If the meshShader feature is not enabled, and pStages contains VK_SHADER_STAGE_MESH_BIT_EXT, and pShaders is not NULL, the same index in pShaders must be VK_NULL_HANDLE

  • VUID-vkCmdBindShadersEXT-pShaders-08476
    If pStages contains VK_SHADER_STAGE_COMPUTE_BIT, the VkCommandPool that commandBuffer was allocated from must support compute operations

  • VUID-vkCmdBindShadersEXT-pShaders-08477
    If pStages contains VK_SHADER_STAGE_VERTEX_BIT, VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT, VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT, VK_SHADER_STAGE_GEOMETRY_BIT, or VK_SHADER_STAGE_FRAGMENT_BIT, the VkCommandPool that commandBuffer was allocated from must support graphics operations

  • VUID-vkCmdBindShadersEXT-pShaders-08478
    If pStages contains VK_SHADER_STAGE_MESH_BIT_EXT or VK_SHADER_STAGE_TASK_BIT_EXT, the VkCommandPool that commandBuffer was allocated from must support graphics operations

Valid Usage (Implicit)

  • VUID-vkCmdBindShadersEXT-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdBindShadersEXT-pStages-parameter
    pStages must be a valid pointer to an array of stageCount valid VkShaderStageFlagBits values

  • VUID-vkCmdBindShadersEXT-pShaders-parameter
    If pShaders is not NULL, pShaders must be a valid pointer to an array of stageCount valid or VK_NULL_HANDLE VkShaderEXT handles

  • VUID-vkCmdBindShadersEXT-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdBindShadersEXT-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support graphics, or compute operations

  • VUID-vkCmdBindShadersEXT-videocoding
    This command must only be called outside of a video coding scope

  • VUID-vkCmdBindShadersEXT-stageCount-arraylength
    stageCount must be greater than 0

  • VUID-vkCmdBindShadersEXT-commonparent
    Both of commandBuffer, and the elements of pShaders that are valid handles of non-ignored parameters must have been created, allocated, or retrieved from the same VkDevice

Host Synchronization

  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Video Coding Scope Supported Queue Types Command Type

Primary
Secondary

Both

Outside

Graphics
Compute

State

9.1.5. Setting State

Whenever shader objects are used to issue drawing commands, the appropriate dynamic state setting commands must have been called to set the relevant state in the command buffer prior to drawing:

If a shader is bound to the VK_SHADER_STAGE_VERTEX_BIT stage, the following commands must have been called in the command buffer prior to drawing:

If a shader is bound to the VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT stage, the following command must have been called in the command buffer prior to drawing:

If a shader is bound to the VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT stage, the following command must have been called in the command buffer prior to drawing:

If rasterizerDiscardEnable is VK_FALSE, the following commands must have been called in the command buffer prior to drawing:

If a shader is bound to the VK_SHADER_STAGE_FRAGMENT_BIT stage, and rasterizerDiscardEnable is VK_FALSE, the following commands must have been called in the command buffer prior to drawing:

If the pipelineFragmentShadingRate feature is enabled on the device, and a shader is bound to the VK_SHADER_STAGE_FRAGMENT_BIT stage, and rasterizerDiscardEnable is VK_FALSE, the following command must have been called in the command buffer prior to drawing:

If the geometryStreams feature is enabled on the device, and a shader is bound to the VK_SHADER_STAGE_GEOMETRY_BIT stage, the following command must have been called in the command buffer prior to drawing:

If the VK_EXT_discard_rectangles extension is enabled on the device, and rasterizerDiscardEnable is VK_FALSE, the following commands must have been called in the command buffer prior to drawing:

If VK_EXT_conservative_rasterization extension is enabled on the device, and rasterizerDiscardEnable is VK_FALSE, the following commands must have been called in the command buffer prior to drawing:

If the depthClipEnable feature is enabled on the device, the following command must have been called in the command buffer prior to drawing:

If the VK_EXT_sample_locations extension is enabled on the device, and rasterizerDiscardEnable is VK_FALSE, the following commands must have been called in the command buffer prior to drawing:

If the VK_EXT_provoking_vertex extension is enabled on the device, and rasterizerDiscardEnable is VK_FALSE, and a shader is bound to the VK_SHADER_STAGE_VERTEX_BIT stage, the following command must have been called in the command buffer prior to drawing:

If the VK_KHR_line_rasterization or VK_EXT_line_rasterization extension is enabled on the device, and rasterizerDiscardEnable is VK_FALSE, and if polygonMode is VK_POLYGON_MODE_LINE or a shader is bound to the VK_SHADER_STAGE_VERTEX_BIT stage and primitiveTopology is a line topology or a shader which outputs line primitives is bound to the VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT or VK_SHADER_STAGE_GEOMETRY_BIT stage, the following commands must have been called in the command buffer prior to drawing:

If the depthClipControl feature is enabled on the device, the following command must have been called in the command buffer prior to drawing:

If the colorWriteEnable feature is enabled on the device, and a shader is bound to the VK_SHADER_STAGE_FRAGMENT_BIT stage, and rasterizerDiscardEnable is VK_FALSE, the following command must have been called in the command buffer prior to drawing:

If the attachmentFeedbackLoopDynamicState feature is enabled on the device, and a shader is bound to the VK_SHADER_STAGE_FRAGMENT_BIT stage, and rasterizerDiscardEnable is VK_FALSE, the following command must have been called in the command buffer prior to drawing:

If the VK_NV_clip_space_w_scaling extension is enabled on the device, the following commands must have been called in the command buffer prior to drawing:

If the depthClamp and depthClampControl feature are enabled on the device, and depthClampEnable is VK_TRUE, the following command must have been called in the command buffer prior to drawing:

If the VK_NV_viewport_swizzle extension is enabled on the device, the following command must have been called in the command buffer prior to drawing:

If the VK_NV_fragment_coverage_to_color extension is enabled on the device, and a shader is bound to the VK_SHADER_STAGE_FRAGMENT_BIT stage, and rasterizerDiscardEnable is VK_FALSE, the following commands must have been called in the command buffer prior to drawing:

If the VK_NV_framebuffer_mixed_samples extension is enabled on the device, and rasterizerDiscardEnable is VK_FALSE, the following commands must have been called in the command buffer prior to drawing:

If the coverageReductionMode feature is enabled on the device, and rasterizerDiscardEnable is VK_FALSE, the following command must have been called in the command buffer prior to drawing:

If the representativeFragmentTest feature is enabled on the device, and rasterizerDiscardEnable is VK_FALSE, the following command must have been called in the command buffer prior to drawing:

If the shadingRateImage feature is enabled on the device, and rasterizerDiscardEnable is VK_FALSE, the following commands must have been called in the command buffer prior to drawing:

If the exclusiveScissor feature is enabled on the device, the following commands must have been called in the command buffer prior to drawing:

State can be set either at any time before or after shader objects are bound, but all required state must be set prior to issuing drawing commands.

If the commandBufferInheritance feature is enabled, graphics and compute state is inherited from the previously executed command buffer in the queue. Any valid state inherited in this way does not need to be set again in the current command buffer.

9.1.6. Interaction With Pipelines

Calling vkCmdBindShadersEXT causes the pipeline bind points corresponding to each stage in pStages to be disturbed, meaning that any pipelines that had previously been bound to those pipeline bind points are no longer bound.

If VK_PIPELINE_BIND_POINT_GRAPHICS is disturbed (i.e., if pStages contains any graphics stage), any graphics pipeline state that the previously bound pipeline did not specify as dynamic becomes undefined, and must be set in the command buffer before issuing drawing commands using shader objects.

Calls to vkCmdBindPipeline likewise disturb the shader stage(s) corresponding to pipelineBindPoint, meaning that any shaders that had previously been bound to any of those stages are no longer bound, even if the pipeline was created without shaders for some of those stages.

9.1.7. Shader Object Destruction

To destroy a shader object, call:

// Provided by VK_EXT_shader_object
void vkDestroyShaderEXT(
    VkDevice                                    device,
    VkShaderEXT                                 shader,
    const VkAllocationCallbacks*                pAllocator);

  • device is the logical device that destroys the shader object.

  • shader is the handle of the shader object to destroy.

  • pAllocator controls host memory allocation as described in the Memory Allocation chapter.

Destroying a shader object used by one or more command buffers in the recording or executable state causes those command buffers to move into the invalid state.

Valid Usage

  • VUID-vkDestroyShaderEXT-None-08481
    The shaderObject feature must be enabled

  • VUID-vkDestroyShaderEXT-shader-08482
    All submitted commands that refer to shader must have completed execution

  • VUID-vkDestroyShaderEXT-pAllocator-08483
    If VkAllocationCallbacks were provided when shader was created, a compatible set of callbacks must be provided here

  • VUID-vkDestroyShaderEXT-pAllocator-08484
    If no VkAllocationCallbacks were provided when shader was created, pAllocator must be NULL

Valid Usage (Implicit)

  • VUID-vkDestroyShaderEXT-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkDestroyShaderEXT-shader-parameter
    If shader is not VK_NULL_HANDLE, shader must be a valid VkShaderEXT handle

  • VUID-vkDestroyShaderEXT-pAllocator-parameter
    If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure

  • VUID-vkDestroyShaderEXT-shader-parent
    If shader is a valid handle, it must have been created, allocated, or retrieved from device

Host Synchronization

  • Host access to shader must be externally synchronized

9.2. Shader Modules

Shader modules contain shader code and one or more entry points. Shaders are selected from a shader module by specifying an entry point as part of pipeline creation. The stages of a pipeline can use shaders that come from different modules. The shader code defining a shader module must be in the SPIR-V format, as described by the Vulkan Environment for SPIR-V appendix.

Shader modules are represented by VkShaderModule handles:

// Provided by VK_VERSION_1_0
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkShaderModule)

To create a shader module, call:

// Provided by VK_VERSION_1_0
VkResult vkCreateShaderModule(
    VkDevice                                    device,
    const VkShaderModuleCreateInfo*             pCreateInfo,
    const VkAllocationCallbacks*                pAllocator,
    VkShaderModule*                             pShaderModule);

  • device is the logical device that creates the shader module.

  • pCreateInfo is a pointer to a VkShaderModuleCreateInfo structure.

  • pAllocator controls host memory allocation as described in the Memory Allocation chapter.

  • pShaderModule is a pointer to a VkShaderModule handle in which the resulting shader module object is returned.

Once a shader module has been created, any entry points it contains can be used in pipeline shader stages as described in Compute Pipelines and Graphics Pipelines.

Note

If the maintenance5 feature is enabled, shader module creation can be omitted entirely. Instead, applications should provide the VkShaderModuleCreateInfo structure directly in to pipeline creation by chaining it to VkPipelineShaderStageCreateInfo. This avoids the overhead of creating and managing an additional object.
Valid Usage
Valid Usage (Implicit)

  • VUID-vkCreateShaderModule-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkCreateShaderModule-pCreateInfo-parameter
    pCreateInfo must be a valid pointer to a valid VkShaderModuleCreateInfo structure

  • VUID-vkCreateShaderModule-pAllocator-parameter
    If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure

  • VUID-vkCreateShaderModule-pShaderModule-parameter
    pShaderModule must be a valid pointer to a VkShaderModule handle

Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

  • VK_ERROR_INVALID_SHADER_NV

The VkShaderModuleCreateInfo structure is defined as:

// Provided by VK_VERSION_1_0
typedef struct VkShaderModuleCreateInfo {
    VkStructureType              sType;
    const void*                  pNext;
    VkShaderModuleCreateFlags    flags;
    size_t                       codeSize;
    const uint32_t*              pCode;
} VkShaderModuleCreateInfo;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • flags is reserved for future use.

  • codeSize is the size, in bytes, of the code pointed to by pCode.

  • pCode is a pointer to code that is used to create the shader module. The type and format of the code is determined from the content of the memory addressed by pCode.

Valid Usage

  • VUID-VkShaderModuleCreateInfo-codeSize-08735
    If pCode is a pointer to SPIR-V code, codeSize must be a multiple of 4

  • VUID-VkShaderModuleCreateInfo-pCode-08736
    If pCode is a pointer to SPIR-V code, pCode must point to valid SPIR-V code, formatted and packed as described by the Khronos SPIR-V Specification

  • VUID-VkShaderModuleCreateInfo-pCode-08737
    If pCode is a pointer to SPIR-V code, pCode must adhere to the validation rules described by the Validation Rules within a Module section of the SPIR-V Environment appendix

  • VUID-VkShaderModuleCreateInfo-pCode-08738
    If pCode is a pointer to SPIR-V code, pCode must declare the Shader capability for SPIR-V code

  • VUID-VkShaderModuleCreateInfo-pCode-08739
    If pCode is a pointer to SPIR-V code, pCode must not declare any capability that is not supported by the API, as described by the Capabilities section of the SPIR-V Environment appendix

  • VUID-VkShaderModuleCreateInfo-pCode-08740
    If pCode is a pointer to SPIR-V code, and pCode declares any of the capabilities listed in the SPIR-V Environment appendix, one of the corresponding requirements must be satisfied

  • VUID-VkShaderModuleCreateInfo-pCode-08741
    If pCode is a pointer to SPIR-V code, pCode must not declare any SPIR-V extension that is not supported by the API, as described by the Extension section of the SPIR-V Environment appendix

  • VUID-VkShaderModuleCreateInfo-pCode-08742
    If pCode is a pointer to SPIR-V code, and pCode declares any of the SPIR-V extensions listed in the SPIR-V Environment appendix, one of the corresponding requirements must be satisfied

  • VUID-VkShaderModuleCreateInfo-pCode-07912
    If the VK_NV_glsl_shader extension is not enabled, pCode must be a pointer to SPIR-V code

  • VUID-VkShaderModuleCreateInfo-pCode-01379
    If pCode is a pointer to GLSL code, it must be valid GLSL code written to the GL_KHR_vulkan_glsl GLSL extension specification

  • VUID-VkShaderModuleCreateInfo-codeSize-01085
    codeSize must be greater than 0

Valid Usage (Implicit)

  • VUID-VkShaderModuleCreateInfo-sType-sType
    sType must be VK_STRUCTURE_TYPE_SHADER_MODULE_CREATE_INFO

  • VUID-VkShaderModuleCreateInfo-flags-zerobitmask
    flags must be 0

  • VUID-VkShaderModuleCreateInfo-pCode-parameter
    pCode must be a valid pointer to an array of uint32_t values

// Provided by VK_VERSION_1_0
typedef VkFlags VkShaderModuleCreateFlags;

VkShaderModuleCreateFlags is a bitmask type for setting a mask, but is currently reserved for future use.

To use a VkValidationCacheEXT to cache shader validation results, add a VkShaderModuleValidationCacheCreateInfoEXT structure to the pNext chain of the VkShaderModuleCreateInfo structure, specifying the cache object to use.

The VkShaderModuleValidationCacheCreateInfoEXT struct is defined as:

// Provided by VK_EXT_validation_cache
typedef struct VkShaderModuleValidationCacheCreateInfoEXT {
    VkStructureType         sType;
    const void*             pNext;
    VkValidationCacheEXT    validationCache;
} VkShaderModuleValidationCacheCreateInfoEXT;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • validationCache is the validation cache object from which the results of prior validation attempts will be written, and to which new validation results for this VkShaderModule will be written (if not already present).

Valid Usage (Implicit)

  • VUID-VkShaderModuleValidationCacheCreateInfoEXT-sType-sType
    sType must be VK_STRUCTURE_TYPE_SHADER_MODULE_VALIDATION_CACHE_CREATE_INFO_EXT

  • VUID-VkShaderModuleValidationCacheCreateInfoEXT-validationCache-parameter
    validationCache must be a valid VkValidationCacheEXT handle

To destroy a shader module, call:

// Provided by VK_VERSION_1_0
void vkDestroyShaderModule(
    VkDevice                                    device,
    VkShaderModule                              shaderModule,
    const VkAllocationCallbacks*                pAllocator);

  • device is the logical device that destroys the shader module.

  • shaderModule is the handle of the shader module to destroy.

  • pAllocator controls host memory allocation as described in the Memory Allocation chapter.

A shader module can be destroyed while pipelines created using its shaders are still in use.

Valid Usage

  • VUID-vkDestroyShaderModule-shaderModule-01092
    If VkAllocationCallbacks were provided when shaderModule was created, a compatible set of callbacks must be provided here

  • VUID-vkDestroyShaderModule-shaderModule-01093
    If no VkAllocationCallbacks were provided when shaderModule was created, pAllocator must be NULL

Valid Usage (Implicit)

  • VUID-vkDestroyShaderModule-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkDestroyShaderModule-shaderModule-parameter
    If shaderModule is not VK_NULL_HANDLE, shaderModule must be a valid VkShaderModule handle

  • VUID-vkDestroyShaderModule-pAllocator-parameter
    If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure

  • VUID-vkDestroyShaderModule-shaderModule-parent
    If shaderModule is a valid handle, it must have been created, allocated, or retrieved from device

Host Synchronization

  • Host access to shaderModule must be externally synchronized

9.3. Shader Module Identifiers

Shader modules have unique identifiers associated with them. To query an implementation provided identifier, call:

// Provided by VK_EXT_shader_module_identifier
void vkGetShaderModuleIdentifierEXT(
    VkDevice                                    device,
    VkShaderModule                              shaderModule,
    VkShaderModuleIdentifierEXT*                pIdentifier);

  • device is the logical device that created the shader module.

  • shaderModule is the handle of the shader module.

  • pIdentifier is a pointer to the returned VkShaderModuleIdentifierEXT.

The identifier returned by the implementation must only depend on shaderIdentifierAlgorithmUUID and information provided in the VkShaderModuleCreateInfo which created shaderModule. The implementation may return equal identifiers for two different VkShaderModuleCreateInfo structures if the difference does not affect pipeline compilation. Identifiers are only meaningful on different VkDevice objects if the device the identifier was queried from had the same shaderModuleIdentifierAlgorithmUUID as the device consuming the identifier.

Valid Usage

  • VUID-vkGetShaderModuleIdentifierEXT-shaderModuleIdentifier-06884
    shaderModuleIdentifier feature must be enabled

Valid Usage (Implicit)

  • VUID-vkGetShaderModuleIdentifierEXT-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkGetShaderModuleIdentifierEXT-shaderModule-parameter
    shaderModule must be a valid VkShaderModule handle

  • VUID-vkGetShaderModuleIdentifierEXT-pIdentifier-parameter
    pIdentifier must be a valid pointer to a VkShaderModuleIdentifierEXT structure

  • VUID-vkGetShaderModuleIdentifierEXT-shaderModule-parent
    shaderModule must have been created, allocated, or retrieved from device

VkShaderModuleCreateInfo structures have unique identifiers associated with them. To query an implementation provided identifier, call:

// Provided by VK_EXT_shader_module_identifier
void vkGetShaderModuleCreateInfoIdentifierEXT(
    VkDevice                                    device,
    const VkShaderModuleCreateInfo*             pCreateInfo,
    VkShaderModuleIdentifierEXT*                pIdentifier);

The identifier returned by implementation must only depend on shaderIdentifierAlgorithmUUID and information provided in the VkShaderModuleCreateInfo. The implementation may return equal identifiers for two different VkShaderModuleCreateInfo structures if the difference does not affect pipeline compilation. Identifiers are only meaningful on different VkDevice objects if the device the identifier was queried from had the same shaderModuleIdentifierAlgorithmUUID as the device consuming the identifier.

The identifier returned by the implementation in vkGetShaderModuleCreateInfoIdentifierEXT must be equal to the identifier returned by vkGetShaderModuleIdentifierEXT given equivalent definitions of VkShaderModuleCreateInfo and any chained pNext structures.

Valid Usage

  • VUID-vkGetShaderModuleCreateInfoIdentifierEXT-shaderModuleIdentifier-06885
    shaderModuleIdentifier feature must be enabled

Valid Usage (Implicit)

  • VUID-vkGetShaderModuleCreateInfoIdentifierEXT-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkGetShaderModuleCreateInfoIdentifierEXT-pCreateInfo-parameter
    pCreateInfo must be a valid pointer to a valid VkShaderModuleCreateInfo structure

  • VUID-vkGetShaderModuleCreateInfoIdentifierEXT-pIdentifier-parameter
    pIdentifier must be a valid pointer to a VkShaderModuleIdentifierEXT structure

VkShaderModuleIdentifierEXT represents a shader module identifier returned by the implementation.

// Provided by VK_EXT_shader_module_identifier
typedef struct VkShaderModuleIdentifierEXT {
    VkStructureType    sType;
    void*              pNext;
    uint32_t           identifierSize;
    uint8_t            identifier[VK_MAX_SHADER_MODULE_IDENTIFIER_SIZE_EXT];
} VkShaderModuleIdentifierEXT;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • identifierSize is the size, in bytes, of valid data returned in identifier.

  • identifier is a buffer of opaque data specifying an identifier.

Any returned values beyond the first identifierSize bytes are undefined. Implementations must return an identifierSize greater than 0, and less-or-equal to VK_MAX_SHADER_MODULE_IDENTIFIER_SIZE_EXT.

Two identifiers are considered equal if identifierSize is equal and the first identifierSize bytes of identifier compare equal.

Implementations may return a different identifierSize for different modules. Implementations should ensure that identifierSize is large enough to uniquely define a shader module.

Valid Usage (Implicit)

  • VUID-VkShaderModuleIdentifierEXT-sType-sType
    sType must be VK_STRUCTURE_TYPE_SHADER_MODULE_IDENTIFIER_EXT

  • VUID-VkShaderModuleIdentifierEXT-pNext-pNext
    pNext must be NULL

VK_MAX_SHADER_MODULE_IDENTIFIER_SIZE_EXT is the length in bytes of a shader module identifier, as returned in VkShaderModuleIdentifierEXT::identifierSize.

#define VK_MAX_SHADER_MODULE_IDENTIFIER_SIZE_EXT 32U

9.4. Binding Shaders

Before a shader can be used it must be first bound to the command buffer.

Calling vkCmdBindPipeline binds all stages corresponding to the VkPipelineBindPoint. Calling vkCmdBindShadersEXT binds all stages in pStages

The following table describes the relationship between shader stages and pipeline bind points:

Shader stage Pipeline bind point behavior controlled

  • VK_SHADER_STAGE_VERTEX_BIT

  • VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT

  • VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT

  • VK_SHADER_STAGE_GEOMETRY_BIT

  • VK_SHADER_STAGE_FRAGMENT_BIT

  • VK_SHADER_STAGE_TASK_BIT_EXT

  • VK_SHADER_STAGE_MESH_BIT_EXT

VK_PIPELINE_BIND_POINT_GRAPHICS

all drawing commands

  • VK_SHADER_STAGE_COMPUTE_BIT

VK_PIPELINE_BIND_POINT_COMPUTE

all dispatch commands

  • VK_SHADER_STAGE_ANY_HIT_BIT_KHR

  • VK_SHADER_STAGE_CALLABLE_BIT_KHR

  • VK_SHADER_STAGE_CLOSEST_HIT_BIT_KHR

  • VK_SHADER_STAGE_INTERSECTION_BIT_KHR

  • VK_SHADER_STAGE_MISS_BIT_KHR

  • VK_SHADER_STAGE_RAYGEN_BIT_KHR

VK_PIPELINE_BIND_POINT_RAY_TRACING_KHR

vkCmdTraceRaysKHR and vkCmdTraceRaysIndirectKHR

  • VK_SHADER_STAGE_SUBPASS_SHADING_BIT_HUAWEI

  • VK_SHADER_STAGE_CLUSTER_CULLING_BIT_HUAWEI

VK_PIPELINE_BIND_POINT_SUBPASS_SHADING_HUAWEI

vkCmdSubpassShadingHUAWEI

  • VK_SHADER_STAGE_COMPUTE_BIT

VK_PIPELINE_BIND_POINT_EXECUTION_GRAPH_AMDX

all execution graph commands

9.5. Shader Execution

At each stage of the pipeline, multiple invocations of a shader may execute simultaneously. Further, invocations of a single shader produced as the result of different commands may execute simultaneously. The relative execution order of invocations of the same shader type is undefined. Shader invocations may complete in a different order than that in which the primitives they originated from were drawn or dispatched by the application. However, fragment shader outputs are written to attachments in rasterization order.

The relative execution order of invocations of different shader types is largely undefined. However, when invoking a shader whose inputs are generated from a previous pipeline stage, the shader invocations from the previous stage are guaranteed to have executed far enough to generate input values for all required inputs.

9.5.1. Shader Termination

A shader invocation that is terminated has finished executing instructions.

Executing OpReturn in the entry point, or executing OpTerminateInvocation in any function will terminate an invocation. Implementations may also terminate a shader invocation when OpKill is executed in any function; otherwise it becomes a helper invocation.

In addition to the above conditions, helper invocations may be terminated when all non-helper invocations in the same derivative group either terminate or become helper invocations.

A shader stage for a given command completes execution when all invocations for that stage have terminated.

Note

OpKill will behave the same as either OpTerminateInvocation or OpDemoteToHelperInvocation depending on the implementation. It is recommended that shader authors use OpTerminateInvocation or OpDemoteToHelperInvocation instead of OpKill whenever possible to produce more predictable behavior.

9.6. Shader Memory Access Ordering

The order in which image or buffer memory is read or written by shaders is largely undefined. For some shader types (vertex, tessellation evaluation, and in some cases, fragment), even the number of shader invocations that may perform loads and stores is undefined.

In particular, the following rules apply:

  • Vertex and tessellation evaluation shaders will be invoked at least once for each unique vertex, as defined in those sections.

  • Fragment shaders will be invoked zero or more times, as defined in that section.

  • The relative execution order of invocations of the same shader type is undefined. A store issued by a shader when working on primitive B might complete prior to a store for primitive A, even if primitive A is specified prior to primitive B. This applies even to fragment shaders; while fragment shader outputs are always written to the framebuffer in rasterization order, stores executed by fragment shader invocations are not.

  • The relative execution order of invocations of different shader types is largely undefined.

Note

The above limitations on shader invocation order make some forms of synchronization between shader invocations within a single set of primitives unimplementable. For example, having one invocation poll memory written by another invocation assumes that the other invocation has been launched and will complete its writes in finite time.

The Memory Model appendix defines the terminology and rules for how to correctly communicate between shader invocations, such as when a write is Visible-To a read, and what constitutes a Data Race.

Applications must not cause a data race.

The SPIR-V SubgroupMemory, CrossWorkgroupMemory, and AtomicCounterMemory memory semantics are ignored. Sequentially consistent atomics and barriers are not supported and SequentiallyConsistent is treated as AcquireRelease. SequentiallyConsistent should not be used.

9.7. Shader Inputs and Outputs

Data is passed into and out of shaders using variables with input or output storage class, respectively. User-defined inputs and outputs are connected between stages by matching their Location decorations. Additionally, data can be provided by or communicated to special functions provided by the execution environment using BuiltIn decorations.

In many cases, the same BuiltIn decoration can be used in multiple shader stages with similar meaning. The specific behavior of variables decorated as BuiltIn is documented in the following sections.

9.8. Task Shaders

Task shaders operate in conjunction with the mesh shaders to produce a collection of primitives that will be processed by subsequent stages of the graphics pipeline. Its primary purpose is to create a variable amount of subsequent mesh shader invocations.

Task shaders are invoked via the execution of the programmable mesh shading pipeline.

The task shader has no fixed-function inputs other than variables identifying the specific workgroup and invocation. In the TaskNV Execution Model the number of mesh shader workgroups to create is specified via a TaskCountNV decorated output variable. In the TaskEXT Execution Model the number of mesh shader workgroups to create is specified via the OpEmitMeshTasksEXT instruction.

The task shader can write additional outputs to task memory, which can be read by all of the mesh shader workgroups it created.

9.8.1. Task Shader Execution

Task workloads are formed from groups of work items called workgroups and processed by the task shader in the current graphics pipeline. A workgroup is a collection of shader invocations that execute the same shader, potentially in parallel. Task shaders execute in global workgroups which are divided into a number of local workgroups with a size that can be set by assigning a value to the LocalSize or LocalSizeId execution mode or via an object decorated by the WorkgroupSize decoration. An invocation within a local workgroup can share data with other members of the local workgroup through shared variables and issue memory and control flow barriers to synchronize with other members of the local workgroup. If the subpass includes multiple views in its view mask, a Task shader using TaskEXT Execution Model may be invoked separately for each view.

9.9. Mesh Shaders

Mesh shaders operate in workgroups to produce a collection of primitives that will be processed by subsequent stages of the graphics pipeline. Each workgroup emits zero or more output primitives and the group of vertices and their associated data required for each output primitive.

Mesh shaders are invoked via the execution of the programmable mesh shading pipeline.

The only inputs available to the mesh shader are variables identifying the specific workgroup and invocation and, if applicable, any outputs written to task memory by the task shader that spawned the mesh shader’s workgroup. The mesh shader can operate without a task shader as well.

The invocations of the mesh shader workgroup write an output mesh, comprising a set of primitives with per-primitive attributes, a set of vertices with per-vertex attributes, and an array of indices identifying the mesh vertices that belong to each primitive. The primitives of this mesh are then processed by subsequent graphics pipeline stages, where the outputs of the mesh shader form an interface with the fragment shader.

9.9.1. Mesh Shader Execution

Mesh workloads are formed from groups of work items called workgroups and processed by the mesh shader in the current graphics pipeline. A workgroup is a collection of shader invocations that execute the same shader, potentially in parallel. Mesh shaders execute in global workgroups which are divided into a number of local workgroups with a size that can be set by assigning a value to the LocalSize or LocalSizeId execution mode or via an object decorated by the WorkgroupSize decoration. An invocation within a local workgroup can share data with other members of the local workgroup through shared variables and issue memory and control flow barriers to synchronize with other members of the local workgroup.

The global workgroups may be generated explicitly via the API, or implicitly through the task shader’s work creation mechanism. If the subpass includes multiple views in its view mask, a Mesh shader using MeshEXT Execution Model may be invoked separately for each view.

9.10. Cluster Culling Shaders

Cluster Culling shaders are invoked via the execution of the Programmable Cluster Culling Shading pipeline.

The only inputs available to the cluster culling shader are variables identifying the specific workgroup and invocation.

Cluster Culling shaders operate in workgroups to perform cluster-based culling and produce zero or more cluster drawing command that will be processed by subsequent stages of the graphics pipeline.

The Cluster Drawing Command(CDC) is very similar to the MDI command, invocations in workgroup can emit zero of more CDC to draw zero or more visible cluster.

9.10.1. Cluster Culling Shader Execution

Cluster Culling workloads are formed from groups of work items called workgroups and processed by the cluster culling shader in the current graphics pipeline. A workgroup is a collection of shader invocations that execute the same shader, potentially in parallel. Cluster Culling shaders execute in global workgroups which are divided into a number of local workgroups with a size that can be set by assigning a value to the LocalSize or LocalSizeId execution mode or via an object decorated by the WorkgroupSize decoration. An invocation within a local workgroup can share data with other members of the local workgroup through shared variables and issue memory and control flow barriers to synchronize with other members of the local workgroup.

9.11. Vertex Shaders

Each vertex shader invocation operates on one vertex and its associated vertex attribute data, and outputs one vertex and associated data. Graphics pipelines using primitive shading must include a vertex shader, and the vertex shader stage is always the first shader stage in the graphics pipeline.

9.11.1. Vertex Shader Execution

A vertex shader must be executed at least once for each vertex specified by a drawing command. If the subpass includes multiple views in its view mask, the shader may be invoked separately for each view. During execution, the shader is presented with the index of the vertex and instance for which it has been invoked. Input variables declared in the vertex shader are filled by the implementation with the values of vertex attributes associated with the invocation being executed.

If the same vertex is specified multiple times in a drawing command (e.g. by including the same index value multiple times in an index buffer) the implementation may reuse the results of vertex shading if it can statically determine that the vertex shader invocations will produce identical results.

Note

It is implementation-dependent when and if results of vertex shading are reused, and thus how many times the vertex shader will be executed. This is true also if the vertex shader contains stores or atomic operations (see vertexPipelineStoresAndAtomics).

9.12. Tessellation Control Shaders

The tessellation control shader is used to read an input patch provided by the application and to produce an output patch. Each tessellation control shader invocation operates on an input patch (after all control points in the patch are processed by a vertex shader) and its associated data, and outputs a single control point of the output patch and its associated data, and can also output additional per-patch data. The input patch is sized according to the patchControlPoints member of VkPipelineTessellationStateCreateInfo, as part of input assembly.

The input patch can also be dynamically sized with patchControlPoints parameter of vkCmdSetPatchControlPointsEXT.

To dynamically set the number of control points per patch, call:

// Provided by VK_EXT_extended_dynamic_state2, VK_EXT_shader_object
void vkCmdSetPatchControlPointsEXT(
    VkCommandBuffer                             commandBuffer,
    uint32_t                                    patchControlPoints);

  • commandBuffer is the command buffer into which the command will be recorded.

  • patchControlPoints specifies the number of control points per patch.

This command sets the number of control points per patch for subsequent drawing commands when drawing using shader objects, or when the graphics pipeline is created with VK_DYNAMIC_STATE_PATCH_CONTROL_POINTS_EXT set in VkPipelineDynamicStateCreateInfo::pDynamicStates. Otherwise, this state is specified by the VkPipelineTessellationStateCreateInfo::patchControlPoints value used to create the currently active pipeline.

Valid Usage

  • VUID-vkCmdSetPatchControlPointsEXT-None-09422
    At least one of the following must be true:

  • VUID-vkCmdSetPatchControlPointsEXT-patchControlPoints-04874
    patchControlPoints must be greater than zero and less than or equal to VkPhysicalDeviceLimits::maxTessellationPatchSize

Valid Usage (Implicit)

  • VUID-vkCmdSetPatchControlPointsEXT-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdSetPatchControlPointsEXT-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdSetPatchControlPointsEXT-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support graphics operations

  • VUID-vkCmdSetPatchControlPointsEXT-videocoding
    This command must only be called outside of a video coding scope

Host Synchronization

  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Video Coding Scope Supported Queue Types Command Type

Primary
Secondary

Both

Outside

Graphics

State

The size of the output patch is controlled by the OpExecutionMode OutputVertices specified in the tessellation control or tessellation evaluation shaders, which must be specified in at least one of the shaders. The size of the input and output patches must each be greater than zero and less than or equal to VkPhysicalDeviceLimits::maxTessellationPatchSize.

9.12.1. Tessellation Control Shader Execution

A tessellation control shader is invoked at least once for each output vertex in a patch. If the subpass includes multiple views in its view mask, the shader may be invoked separately for each view.

Inputs to the tessellation control shader are generated by the vertex shader. Each invocation of the tessellation control shader can read the attributes of any incoming vertices and their associated data. The invocations corresponding to a given patch execute logically in parallel, with undefined relative execution order. However, the OpControlBarrier instruction can be used to provide limited control of the execution order by synchronizing invocations within a patch, effectively dividing tessellation control shader execution into a set of phases. Tessellation control shaders will read undefined values if one invocation reads a per-vertex or per-patch output written by another invocation at any point during the same phase, or if two invocations attempt to write different values to the same per-patch output in a single phase.

9.13. Tessellation Evaluation Shaders

The Tessellation Evaluation Shader operates on an input patch of control points and their associated data, and a single input barycentric coordinate indicating the invocation’s relative position within the subdivided patch, and outputs a single vertex and its associated data.

9.13.1. Tessellation Evaluation Shader Execution

A tessellation evaluation shader is invoked at least once for each unique vertex generated by the tessellator. If the subpass includes multiple views in its view mask, the shader may be invoked separately for each view.

9.14. Geometry Shaders

The geometry shader operates on a group of vertices and their associated data assembled from a single input primitive, and emits zero or more output primitives and the group of vertices and their associated data required for each output primitive.

9.14.1. Geometry Shader Execution

A geometry shader is invoked at least once for each primitive produced by the tessellation stages, or at least once for each primitive generated by primitive assembly when tessellation is not in use. A shader can request that the geometry shader runs multiple instances. A geometry shader is invoked at least once for each instance. If the subpass includes multiple views in its view mask, the shader may be invoked separately for each view.

9.15. Fragment Shaders

Fragment shaders are invoked as a fragment operation in a graphics pipeline. Each fragment shader invocation operates on a single fragment and its associated data. With few exceptions, fragment shaders do not have access to any data associated with other fragments and are considered to execute in isolation of fragment shader invocations associated with other fragments.

9.16. Compute Shaders

Compute shaders are invoked via vkCmdDispatch and vkCmdDispatchIndirect commands. In general, they have access to similar resources as shader stages executing as part of a graphics pipeline.

Compute workloads are formed from groups of work items called workgroups and processed by the compute shader in the current compute pipeline. A workgroup is a collection of shader invocations that execute the same shader, potentially in parallel. Compute shaders execute in global workgroups which are divided into a number of local workgroups with a size that can be set by assigning a value to the LocalSize or LocalSizeId execution mode or via an object decorated by the WorkgroupSize decoration. An invocation within a local workgroup can share data with other members of the local workgroup through shared variables and issue memory and control flow barriers to synchronize with other members of the local workgroup.

9.17. Ray Generation Shaders

A ray generation shader is similar to a compute shader. Its main purpose is to execute ray tracing queries using pipeline trace ray instructions (such as OpTraceRayKHR) and process the results.

9.17.1. Ray Generation Shader Execution

One ray generation shader is executed per ray tracing dispatch. Its location in the shader binding table (see Shader Binding Table for details) is passed directly into vkCmdTraceRaysKHR using the pRaygenShaderBindingTable parameter or vkCmdTraceRaysNV using the raygenShaderBindingTableBuffer and raygenShaderBindingOffset parameters .

9.18. Intersection Shaders

Intersection shaders enable the implementation of arbitrary, application defined geometric primitives. An intersection shader for a primitive is executed whenever its axis-aligned bounding box is hit by a ray.

Like other ray tracing shader domains, an intersection shader operates on a single ray at a time. It also operates on a single primitive at a time. It is therefore the purpose of an intersection shader to compute the ray-primitive intersections and report them. To report an intersection, the shader calls the OpReportIntersectionKHR instruction.

An intersection shader communicates with any-hit and closest shaders by generating attribute values that they can read. Intersection shaders cannot read or modify the ray payload.

9.18.1. Intersection Shader Execution

The order in which intersections are found along a ray, and therefore the order in which intersection shaders are executed, is unspecified.

The intersection shader of the closest AABB which intersects the ray is guaranteed to be executed at some point during traversal, unless the ray is forcibly terminated.

9.19. Any-Hit Shaders

The any-hit shader is executed after the intersection shader reports an intersection that lies within the current [tmin,tmax] of the ray. The main use of any-hit shaders is to programmatically decide whether or not an intersection will be accepted. The intersection will be accepted unless the shader calls the OpIgnoreIntersectionKHR instruction. Any-hit shaders have read-only access to the attributes generated by the corresponding intersection shader, and can read or modify the ray payload.

9.19.1. Any-Hit Shader Execution

The order in which intersections are found along a ray, and therefore the order in which any-hit shaders are executed, is unspecified.

The any-hit shader of the closest hit is guaranteed to be executed at some point during traversal, unless the ray is forcibly terminated.

9.20. Closest Hit Shaders

Closest hit shaders have read-only access to the attributes generated by the corresponding intersection shader, and can read or modify the ray payload. They also have access to a number of system-generated values. Closest hit shaders can call pipeline trace ray instructions to recursively trace rays.

9.20.1. Closest Hit Shader Execution

Exactly one closest hit shader is executed when traversal is finished and an intersection has been found and accepted.

9.21. Miss Shaders

Miss shaders can access the ray payload and can trace new rays through the pipeline trace ray instructions, but cannot access attributes since they are not associated with an intersection.

9.21.1. Miss Shader Execution

A miss shader is executed instead of a closest hit shader if no intersection was found during traversal.

9.22. Callable Shaders

Callable shaders can access a callable payload that works similarly to ray payloads to do subroutine work.

9.22.1. Callable Shader Execution

A callable shader is executed by calling OpExecuteCallableKHR from an allowed shader stage.

9.23. Interpolation Decorations

Variables in the Input storage class in a fragment shader’s interface are interpolated from the values specified by the primitive being rasterized.

Note

Interpolation decorations can be present on input and output variables in pre-rasterization shaders but have no effect on the interpolation performed.

An undecorated input variable will be interpolated with perspective-correct interpolation according to the primitive type being rasterized. Lines and polygons are interpolated in the same way as the primitive’s clip coordinates. If the NoPerspective decoration is present, linear interpolation is instead used for lines and polygons. For points, as there is only a single vertex, input values are never interpolated and instead take the value written for the single vertex.

If the Flat decoration is present on an input variable, the value is not interpolated, and instead takes its value directly from the provoking vertex. Fragment shader inputs that are signed or unsigned integers, integer vectors, or any double-precision floating-point type must be decorated with Flat.

Interpolation of input variables is performed at an implementation-defined position within the fragment area being shaded. The position is further constrained as follows:

  • If the Centroid decoration is used, the interpolation position used for the variable must also fall within the bounds of the primitive being rasterized.

  • If the Sample decoration is used, the interpolation position used for the variable must be at the position of the sample being shaded by the current fragment shader invocation.

  • If a sample count of 1 is used, the interpolation position must be at the center of the fragment area.

Note

As Centroid restricts the possible interpolation position to the covered area of the primitive, the position can be forced to vary between neighboring fragments when it otherwise would not. Derivatives calculated based on these differing locations can produce inconsistent results compared to undecorated inputs. It is recommended that input variables used in derivative calculations are not decorated with Centroid.

If the PerVertexKHR decoration is present on an input variable, the value is not interpolated, and instead values from all input vertices are available in an array. Each index of the array corresponds to one of the vertices of the primitive that produced the fragment.

If the CustomInterpAMD decoration is present on an input variable, the value cannot be accessed directly; instead the extended instruction InterpolateAtVertexAMD must be used to obtain values from the input vertices.

9.24. Static Use

A SPIR-V module declares a global object in memory using the OpVariable instruction, which results in a pointer x to that object. A specific entry point in a SPIR-V module is said to statically use that object if that entry point’s call tree contains a function containing a instruction with x as an id operand. A shader entry point also statically uses any variables explicitly declared in its interface.

9.25. Scope

A scope describes a set of shader invocations, where each such set is a scope instance. Each invocation belongs to one or more scope instances, but belongs to no more than one scope instance for each scope.

The operations available between invocations in a given scope instance vary, with smaller scopes generally able to perform more operations, and with greater efficiency.

9.25.1. Cross Device

All invocations executed in a Vulkan instance fall into a single cross device scope instance.

Whilst the CrossDevice scope is defined in SPIR-V, it is disallowed in Vulkan. API synchronization commands can be used to communicate between devices.

9.25.2. Device

All invocations executed on a single device form a device scope instance.

If the vulkanMemoryModel and vulkanMemoryModelDeviceScope features are enabled, this scope is represented in SPIR-V by the Device Scope, which can be used as a Memory Scope for barrier and atomic operations.

If both the shaderDeviceClock and vulkanMemoryModelDeviceScope features are enabled, using the Device Scope with the OpReadClockKHR instruction will read from a clock that is consistent across invocations in the same device scope instance.

There is no method to synchronize the execution of these invocations within SPIR-V, and this can only be done with API synchronization primitives.

Invocations executing on different devices in a device group operate in separate device scope instances.

9.25.3. Queue Family

Invocations executed by queues in a given queue family form a queue family scope instance.

This scope is identified in SPIR-V as the QueueFamily Scope if the vulkanMemoryModel feature is enabled, or if not, the Device Scope, which can be used as a Memory Scope for barrier and atomic operations.

If the shaderDeviceClock feature is enabled, but the vulkanMemoryModelDeviceScope feature is not enabled, using the Device Scope with the OpReadClockKHR instruction will read from a clock that is consistent across invocations in the same queue family scope instance.

There is no method to synchronize the execution of these invocations within SPIR-V, and this can only be done with API synchronization primitives.

Each invocation in a queue family scope instance must be in the same device scope instance.

9.25.4. Command

Any shader invocations executed as the result of a single command such as vkCmdDispatch or vkCmdDraw form a command scope instance. For indirect drawing commands with drawCount greater than one, invocations from separate draws are in separate command scope instances. For ray tracing shaders, an invocation group is an implementation-dependent subset of the set of shader invocations of a given shader stage which are produced by a single trace rays command.

There is no specific Scope for communication across invocations in a command scope instance. As this has a clear boundary at the API level, coordination here can be performed in the API, rather than in SPIR-V.

Each invocation in a command scope instance must be in the same queue-family scope instance.

For shaders without defined workgroups, this set of invocations forms an invocation group as defined in the SPIR-V specification.

9.25.5. Primitive

Any fragment shader invocations executed as the result of rasterization of a single primitive form a primitive scope instance.

There is no specific Scope for communication across invocations in a primitive scope instance.

Any generated helper invocations are included in this scope instance.

Each invocation in a primitive scope instance must be in the same command scope instance.

Any input variables decorated with Flat are uniform within a primitive scope instance.

9.25.6. Shader Call

Any shader-call-related invocations that are executed in one or more ray tracing execution models form a shader call scope instance.

The ShaderCallKHR Scope can be used as Memory Scope for barrier and atomic operations.

Each invocation in a shader call scope instance must be in the same queue family scope instance.

9.25.7. Workgroup

A local workgroup is a set of invocations that can synchronize and share data with each other using memory in the Workgroup storage class.

The Workgroup Scope can be used as both an Execution Scope and Memory Scope for barrier and atomic operations.

Each invocation in a local workgroup must be in the same command scope instance.

Only task, mesh, and compute shaders have defined workgroups - other shader types cannot use workgroup functionality. For shaders that have defined workgroups, this set of invocations forms an invocation group as defined in the SPIR-V specification.

When variables declared with the Workgroup storage class are explicitly laid out (hence they are also decorated with Block), the amount of storage consumed is the size of the largest Block variable, not counting any padding at the end. The amount of storage consumed by the non-Block variables declared with the Workgroup storage class is implementation-dependent. However, the amount of storage consumed may not exceed the largest block size that would be obtained if all active non-Block variables declared with Workgroup storage class were assigned offsets in an arbitrary order by successively taking the smallest valid offset according to the Standard Storage Buffer Layout rules, and with Boolean values considered as 32-bit integer values for the purpose of this calculation. (This is equivalent to using the GLSL std430 layout rules.)

9.25.8. Subgroup

A subgroup (see the subsection “Control Flow” of section 2 of the SPIR-V 1.3 Revision 1 specification) is a set of invocations that can synchronize and share data with each other efficiently.

The Subgroup Scope can be used as both an Execution Scope and Memory Scope for barrier and atomic operations. Other subgroup features allow the use of group operations with subgroup scope.

If the shaderSubgroupClock feature is enabled, using the Subgroup Scope with the OpReadClockKHR instruction will read from a clock that is consistent across invocations in the same subgroup.

For shaders that have defined workgroups, each invocation in a subgroup must be in the same local workgroup.

In other shader stages, each invocation in a subgroup must be in the same device scope instance.

Only shader stages that support subgroup operations have defined subgroups.

Note

Subgroups are not guaranteed to be a subset of a single command in shaders that do not have defined workgroups. Values that are guaranteed to be uniform for a given command or sub command may then not be uniform for the subgroup, and vice versa. As such, applications must take care when dealing with mixed uniformity.

A somewhat common example of this would something like trying to optimize access to per-draw data using subgroup operations:

buffer { uint draw_data[]; };

flat in int vDrawID; // Passed through from vertex shader

void main()
{
    uint local_draw_data = subgroupBroadcastFirst(draw_data[local_draw_data]);
}

This can be done in an attempt to optimize the shader to only perform the loads once per subgroup. However, if the implementation packs multiple draws into a single subgroup, invocations from draws with a different drawID are now receiving data from the wrong invocation. Applications should rely on implementations to do this kind of optimization automatically where the implementation can, rather than trying to force it.

9.25.9. Quad

A quad scope instance is formed of four shader invocations.

In a fragment shader, each invocation in a quad scope instance is formed of invocations in neighboring framebuffer locations (xi, yi), where:

  • i is the index of the invocation within the scope instance.

  • w and h are the number of pixels the fragment covers in the x and y axes.

  • w and h are identical for all participating invocations.

  • (x0) = (x1 - w) = (x2) = (x3 - w)

  • (y0) = (y1) = (y2 - h) = (y3 - h)

  • Each invocation has the same layer and sample indices.

In a mesh, task, or compute shader, if the DerivativeGroupQuadsKHR execution mode is specified, each invocation in a quad scope instance is formed of invocations with adjacent local invocation IDs (xi, yi), where:

  • i is the index of the invocation within the quad scope instance.

  • (x0) = (x1 - 1) = (x2) = (x3 - 1)

  • (y0) = (y1) = (y2 - 1) = (y3 - 1)

  • x0 and y0 are integer multiples of 2.

  • Each invocation has the same z coordinate.

In a mesh, task, or compute shader, if the DerivativeGroupLinearKHR execution mode is specified, each invocation in a quad scope instance is formed of invocations with adjacent local invocation indices (li), where:

  • i is the index of the invocation within the quad scope instance.

  • (l0) = (l1 - 1) = (l2 - 2) = (l3 - 3)

  • l0 is an integer multiple of 4.

In all shaders, each invocation in a quad scope instance is formed of invocations in adjacent subgroup invocation indices (si), where:

  • i is the index of the invocation within the quad scope instance.

  • (s0) = (s1 - 1) = (s2 - 2) = (s3 - 3)

  • s0 is an integer multiple of 4.

Each invocation in a quad scope instance must be in the same subgroup.

In a fragment shader, each invocation in a quad scope instance must be in the same primitive scope instance.

Fragment , mesh, task, and compute shaders have defined quad scope instances. If the quadOperationsInAllStages limit is supported, any shader stages that support subgroup operations also have defined quad scope instances.

9.25.10. Fragment Interlock

A fragment interlock scope instance is formed of fragment shader invocations based on their framebuffer locations (x,y,layer,sample), executed by commands inside a single subpass.

The specific set of invocations included varies based on the execution mode as follows:

  • If the SampleInterlockOrderedEXT or SampleInterlockUnorderedEXT execution modes are used, only invocations with identical framebuffer locations (x,y,layer,sample) are included.

  • If the PixelInterlockOrderedEXT or PixelInterlockUnorderedEXT execution modes are used, fragments with different sample ids are also included.

  • If the ShadingRateInterlockOrderedEXT or ShadingRateInterlockUnorderedEXT execution modes are used, fragments from neighboring framebuffer locations are also included. The shading rate image or fragment shading rate determines these fragments.

Only fragment shaders with one of the above execution modes have defined fragment interlock scope instances.

There is no specific Scope value for communication across invocations in a fragment interlock scope instance. However, this is implicitly used as a memory scope by OpBeginInvocationInterlockEXT and OpEndInvocationInterlockEXT.

Each invocation in a fragment interlock scope instance must be in the same queue family scope instance.

9.25.11. Invocation

The smallest scope is a single invocation; this is represented by the Invocation Scope in SPIR-V.

Fragment shader invocations must be in a primitive scope instance.

Invocations in fragment shaders that have a defined fragment interlock scope must be in a fragment interlock scope instance.

Invocations in shaders that have defined workgroups must be in a local workgroup.

Invocations in shaders that have a defined subgroup scope must be in a subgroup.

Invocations in shaders that have a defined quad scope must be in a quad scope instance.

All invocations in all stages must be in a command scope instance.

9.26. Group Operations

Group operations are executed by multiple invocations within a scope instance; with each invocation involved in calculating the result. This provides a mechanism for efficient communication between invocations in a particular scope instance.

Group operations all take a Scope defining the desired scope instance to operate within. Only the Subgroup scope can be used for these operations; the subgroupSupportedOperations limit defines which types of operation can be used.

9.26.1. Basic Group Operations

Basic group operations include the use of OpGroupNonUniformElect, OpControlBarrier, OpMemoryBarrier, and atomic operations.

OpGroupNonUniformElect can be used to choose a single invocation to perform a task for the whole group. Only the invocation with the lowest id in the group will return true.

The Memory Model appendix defines the operation of barriers and atomics.

9.26.2. Vote Group Operations

The vote group operations allow invocations within a group to compare values across a group. The types of votes enabled are:

  • Do all active group invocations agree that an expression is true?

  • Do any active group invocations evaluate an expression to true?

  • Do all active group invocations have the same value of an expression?

Note

These operations are useful in combination with control flow in that they allow for developers to check whether conditions match across the group and choose potentially faster code-paths in these cases.

9.26.3. Arithmetic Group Operations

The arithmetic group operations allow invocations to perform scans and reductions across a group. The operators supported are add, mul, min, max, and, or, xor.

For reductions, every invocation in a group will obtain the cumulative result of these operators applied to all values in the group. For exclusive scans, each invocation in a group will obtain the cumulative result of these operators applied to all values in invocations with a lower index in the group. Inclusive scans are identical to exclusive scans, except the cumulative result includes the operator applied to the value in the current invocation.

The order in which these operators are applied is implementation-dependent.

9.26.4. Ballot Group Operations

The ballot group operations allow invocations to perform more complex votes across the group. The ballot functionality allows all invocations within a group to provide a boolean value and get as a result what each invocation provided as their boolean value. The broadcast functionality allows values to be broadcast from an invocation to all other invocations within the group.

9.26.5. Shuffle Group Operations

The shuffle group operations allow invocations to read values from other invocations within a group.

9.26.6. Shuffle Relative Group Operations

The shuffle relative group operations allow invocations to read values from other invocations within the group relative to the current invocation in the group. The relative operations supported allow data to be shifted up and down through the invocations within a group.

9.26.7. Clustered Group Operations

The clustered group operations allow invocations to perform an operation among partitions of a group, such that the operation is only performed within the group invocations within a partition. The partitions for clustered group operations are consecutive power-of-two size groups of invocations and the cluster size must be known at pipeline creation time. The operations supported are add, mul, min, max, and, or, xor.

9.26.8. Rotate Group Operations

The rotate group operations allow invocations to read values from other invocations within the group relative to the current invocation and modulo the size of the group. Clustered rotate group operations perform the same operation within individual partitions of a group.

The partitions for clustered rotate group operations are consecutive power-of-two size groups of invocations and the cluster size must be known at pipeline creation time.

9.27. Quad Group Operations

Quad group operations (OpGroupNonUniformQuad*) are a specialized type of group operations that only operate on quad scope instances. Whilst these instructions do include a Scope parameter, this scope is always overridden; only the quad scope instance is included in its execution scope.

Fragment shaders that statically execute either OpGroupNonUniformQuadBroadcast or OpGroupNonUniformQuadSwap must launch sufficient invocations to ensure their correct operation; additional helper invocations are launched for framebuffer locations not covered by rasterized fragments if necessary.

The index used to select participating invocations is i, as described for a quad scope instance, defined as the quad index in the SPIR-V specification.

For OpGroupNonUniformQuadBroadcast this value is equal to Index. For OpGroupNonUniformQuadSwap, it is equal to the implicit Index used by each participating invocation.

9.28. Derivative Operations

Derivative operations calculate the partial derivative for an expression P as a function of an invocation’s x and y coordinates.

Derivative operations operate on a set of invocations known as a derivative group as defined in the SPIR-V specification.

A derivative group in a fragment shader is equivalent to the quad scope instance if the QuadDerivativesKHR execution mode is specified, otherwise it is equivalent to the primitive scope instance. A derivative group in a mesh, task, or compute shader is equivalent to the quad scope instance.

Derivatives are calculated assuming that P is piecewise linear and continuous within the derivative group.

The following control-flow restrictions apply to derivative operations:

  • If the QuadDerivativesKHR execution mode is specified, dynamic instances of any derivative operations must be executed in control flow that is uniform within the current quad scope instance.

  • If the QuadDerivativesKHR execution mode is not specified:

    • dynamic instances of explicit derivative instructions (OpDPdx*, OpDPdy*, and OpFwidth*) must be executed in control flow that is uniform within a derivative group.

    • dynamic instances of implicit derivative operations can be executed in control flow that is not uniform within the derivative group, but results are undefined.

Fragment shaders that statically execute derivative operations must launch sufficient invocations to ensure their correct operation; additional helper invocations are launched for framebuffer locations not covered by rasterized fragments if necessary.

Note

In a mesh, task, or compute shader, it is the application’s responsibility to ensure that sufficient invocations are launched.

Derivative operations calculate their results as the difference between the result of P across invocations in the quad. For fine derivative operations (OpDPdxFine and OpDPdyFine), the values of DPdx(Pi) are calculated as

DPdx(P0) = DPdx(P1) = P1 - P0

DPdx(P2) = DPdx(P3) = P3 - P2

and the values of DPdy(Pi) are calculated as

DPdy(P0) = DPdy(P2) = P2 - P0

DPdy(P1) = DPdy(P3) = P3 - P1

where i is the index of each invocation as described in Quad.

Coarse derivative operations (OpDPdxCoarse and OpDPdyCoarse), calculate their results in roughly the same manner, but may only calculate two values instead of four (one for each of DPdx and DPdy), reusing the same result no matter the originating invocation. If an implementation does this, it should use the fine derivative calculations described for P0.

Note

Derivative values are calculated between fragments rather than pixels. If the fragment shader invocations involved in the calculation cover multiple pixels, these operations cover a wider area, resulting in larger derivative values. This in turn will result in a coarser LOD being selected for image sampling operations using derivatives.

Applications may want to account for this when using multi-pixel fragments; if pixel derivatives are desired, applications should use explicit derivative operations and divide the results by the size of the fragment in each dimension as follows:

DPdx(Pn)' = DPdx(Pn) / w

DPdy(Pn)' = DPdy(Pn) / h

where w and h are the size of the fragments in the quad, and DPdx(Pn)' and DPdy(Pn)' are the pixel derivatives.

The results for OpDPdx and OpDPdy may be calculated as either fine or coarse derivatives, with implementations favoring the most efficient approach. Implementations must choose coarse or fine consistently between the two.

Executing OpFwidthFine, OpFwidthCoarse, or OpFwidth is equivalent to executing the corresponding OpDPdx* and OpDPdy* instructions, taking the absolute value of the results, and summing them.

Executing an OpImage*Sample*ImplicitLod instruction is equivalent to executing OpDPdx(Coordinate) and OpDPdy(Coordinate), and passing the results as the Grad operands dx and dy.

Note

It is expected that using the ImplicitLod variants of sampling functions will be substantially more efficient than using the ExplicitLod variants with explicitly generated derivatives.

9.29. Helper Invocations

When performing derivative or quad group operations in a fragment shader, additional invocations may be spawned in order to ensure correct results. These additional invocations are known as helper invocations and can be identified by a non-zero value in the HelperInvocation built-in. Stores and atomics performed by helper invocations must not have any effect on memory except for the Function, Private and Output storage classes, and values returned by atomic instructions in helper invocations are undefined.

Note

While storage to Output storage class has an effect even in helper invocations, it does not mean that helper invocations have an effect on the framebuffer. Output variables in fragment shaders can be read from as well, and they behave more like Private variables for the duration of the shader invocation.

If the MaximallyReconvergesKHR execution mode is applied to the entry point, helper invocations must remain active for all instructions for the lifetime of the quad scope instance they are a part of. If the MaximallyReconvergesKHR execution mode is not applied to the entry point, helper invocations may be considered inactive for group operations other than derivative and quad group operations. All invocations in a quad scope instance may become permanently inactive at any point once the only remaining invocations in that quad scope instance are helper invocations.

9.30. Cooperative Matrices

A cooperative matrix type is a SPIR-V type where the storage for and computations performed on the matrix are spread across the invocations in a scope instance. These types give the implementation freedom in how to optimize matrix multiplies.

SPIR-V defines the types and instructions, but does not specify rules about what sizes/combinations are valid, and it is expected that different implementations may support different sizes.

To enumerate the supported cooperative matrix types and operations, call:

// Provided by VK_KHR_cooperative_matrix
VkResult vkGetPhysicalDeviceCooperativeMatrixPropertiesKHR(
    VkPhysicalDevice                            physicalDevice,
    uint32_t*                                   pPropertyCount,
    VkCooperativeMatrixPropertiesKHR*           pProperties);

  • physicalDevice is the physical device.

  • pPropertyCount is a pointer to an integer related to the number of cooperative matrix properties available or queried.

  • pProperties is either NULL or a pointer to an array of VkCooperativeMatrixPropertiesKHR structures.

If pProperties is NULL, then the number of cooperative matrix properties available is returned in pPropertyCount. Otherwise, pPropertyCount must point to a variable set by the application to the number of elements in the pProperties array, and on return the variable is overwritten with the number of structures actually written to pProperties. If pPropertyCount is less than the number of cooperative matrix properties available, at most pPropertyCount structures will be written, and VK_INCOMPLETE will be returned instead of VK_SUCCESS, to indicate that not all the available cooperative matrix properties were returned.

Valid Usage (Implicit)

  • VUID-vkGetPhysicalDeviceCooperativeMatrixPropertiesKHR-physicalDevice-parameter
    physicalDevice must be a valid VkPhysicalDevice handle

  • VUID-vkGetPhysicalDeviceCooperativeMatrixPropertiesKHR-pPropertyCount-parameter
    pPropertyCount must be a valid pointer to a uint32_t value

  • VUID-vkGetPhysicalDeviceCooperativeMatrixPropertiesKHR-pProperties-parameter
    If the value referenced by pPropertyCount is not 0, and pProperties is not NULL, pProperties must be a valid pointer to an array of pPropertyCount VkCooperativeMatrixPropertiesKHR structures

Return Codes
Success

  • VK_SUCCESS

  • VK_INCOMPLETE

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

To enumerate the supported cooperative matrix types and operations, call:

// Provided by VK_NV_cooperative_matrix
VkResult vkGetPhysicalDeviceCooperativeMatrixPropertiesNV(
    VkPhysicalDevice                            physicalDevice,
    uint32_t*                                   pPropertyCount,
    VkCooperativeMatrixPropertiesNV*            pProperties);

  • physicalDevice is the physical device.

  • pPropertyCount is a pointer to an integer related to the number of cooperative matrix properties available or queried.

  • pProperties is either NULL or a pointer to an array of VkCooperativeMatrixPropertiesNV structures.

If pProperties is NULL, then the number of cooperative matrix properties available is returned in pPropertyCount. Otherwise, pPropertyCount must point to a variable set by the application to the number of elements in the pProperties array, and on return the variable is overwritten with the number of structures actually written to pProperties. If pPropertyCount is less than the number of cooperative matrix properties available, at most pPropertyCount structures will be written, and VK_INCOMPLETE will be returned instead of VK_SUCCESS, to indicate that not all the available cooperative matrix properties were returned.

Valid Usage (Implicit)

  • VUID-vkGetPhysicalDeviceCooperativeMatrixPropertiesNV-physicalDevice-parameter
    physicalDevice must be a valid VkPhysicalDevice handle

  • VUID-vkGetPhysicalDeviceCooperativeMatrixPropertiesNV-pPropertyCount-parameter
    pPropertyCount must be a valid pointer to a uint32_t value

  • VUID-vkGetPhysicalDeviceCooperativeMatrixPropertiesNV-pProperties-parameter
    If the value referenced by pPropertyCount is not 0, and pProperties is not NULL, pProperties must be a valid pointer to an array of pPropertyCount VkCooperativeMatrixPropertiesNV structures

Return Codes
Success

  • VK_SUCCESS

  • VK_INCOMPLETE

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

Each VkCooperativeMatrixPropertiesKHR or VkCooperativeMatrixPropertiesNV structure describes a single supported combination of types for a matrix multiply/add operation ( OpCooperativeMatrixMulAddKHR or OpCooperativeMatrixMulAddNV ). The multiply can be described in terms of the following variables and types (in SPIR-V pseudocode):

    %A is of type OpTypeCooperativeMatrixKHR %AType %scope %MSize %KSize %MatrixAKHR
    %B is of type OpTypeCooperativeMatrixKHR %BType %scope %KSize %NSize %MatrixBKHR
    %C is of type OpTypeCooperativeMatrixKHR %CType %scope %MSize %NSize %MatrixAccumulatorKHR
    %Result is of type OpTypeCooperativeMatrixKHR %ResultType %scope %MSize %NSize %MatrixAccumulatorKHR

    %Result = %A * %B + %C // using OpCooperativeMatrixMulAddKHR
    %A is of type OpTypeCooperativeMatrixNV %AType %scope %MSize %KSize
    %B is of type OpTypeCooperativeMatrixNV %BType %scope %KSize %NSize
    %C is of type OpTypeCooperativeMatrixNV %CType %scope %MSize %NSize
    %D is of type OpTypeCooperativeMatrixNV %DType %scope %MSize %NSize

    %D = %A * %B + %C // using OpCooperativeMatrixMulAddNV

A matrix multiply with these dimensions is known as an MxNxK matrix multiply.

The VkCooperativeMatrixPropertiesKHR structure is defined as:

// Provided by VK_KHR_cooperative_matrix
typedef struct VkCooperativeMatrixPropertiesKHR {
    VkStructureType       sType;
    void*                 pNext;
    uint32_t              MSize;
    uint32_t              NSize;
    uint32_t              KSize;
    VkComponentTypeKHR    AType;
    VkComponentTypeKHR    BType;
    VkComponentTypeKHR    CType;
    VkComponentTypeKHR    ResultType;
    VkBool32              saturatingAccumulation;
    VkScopeKHR            scope;
} VkCooperativeMatrixPropertiesKHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • MSize is the number of rows in matrices A, C, and Result.

  • KSize is the number of columns in matrix A and rows in matrix B.

  • NSize is the number of columns in matrices B, C, Result.

  • AType is the component type of matrix A, of type VkComponentTypeKHR.

  • BType is the component type of matrix B, of type VkComponentTypeKHR.

  • CType is the component type of matrix C, of type VkComponentTypeKHR.

  • ResultType is the component type of matrix Result, of type VkComponentTypeKHR.

  • saturatingAccumulation indicates whether the SaturatingAccumulation operand to OpCooperativeMatrixMulAddKHR must be present or not. If it is VK_TRUE, the SaturatingAccumulation operand must be present. If it is VK_FALSE, the SaturatingAccumulation operand must not be present.

  • scope is the scope of all the matrix types, of type VkScopeKHR.

If some types are preferred over other types (e.g. for performance), they should appear earlier in the list enumerated by vkGetPhysicalDeviceCooperativeMatrixPropertiesKHR.

At least one entry in the list must have power of two values for all of MSize, KSize, and NSize.

scope must be VK_SCOPE_SUBGROUP_KHR.

Valid Usage (Implicit)

  • VUID-VkCooperativeMatrixPropertiesKHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_COOPERATIVE_MATRIX_PROPERTIES_KHR

  • VUID-VkCooperativeMatrixPropertiesKHR-pNext-pNext
    pNext must be NULL

The VkCooperativeMatrixPropertiesNV structure is defined as:

// Provided by VK_NV_cooperative_matrix
typedef struct VkCooperativeMatrixPropertiesNV {
    VkStructureType      sType;
    void*                pNext;
    uint32_t             MSize;
    uint32_t             NSize;
    uint32_t             KSize;
    VkComponentTypeNV    AType;
    VkComponentTypeNV    BType;
    VkComponentTypeNV    CType;
    VkComponentTypeNV    DType;
    VkScopeNV            scope;
} VkCooperativeMatrixPropertiesNV;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • MSize is the number of rows in matrices A, C, and D.

  • KSize is the number of columns in matrix A and rows in matrix B.

  • NSize is the number of columns in matrices B, C, D.

  • AType is the component type of matrix A, of type VkComponentTypeNV.

  • BType is the component type of matrix B, of type VkComponentTypeNV.

  • CType is the component type of matrix C, of type VkComponentTypeNV.

  • DType is the component type of matrix D, of type VkComponentTypeNV.

  • scope is the scope of all the matrix types, of type VkScopeNV.

If some types are preferred over other types (e.g. for performance), they should appear earlier in the list enumerated by vkGetPhysicalDeviceCooperativeMatrixPropertiesNV.

At least one entry in the list must have power of two values for all of MSize, KSize, and NSize.

Valid Usage (Implicit)

  • VUID-VkCooperativeMatrixPropertiesNV-sType-sType
    sType must be VK_STRUCTURE_TYPE_COOPERATIVE_MATRIX_PROPERTIES_NV

  • VUID-VkCooperativeMatrixPropertiesNV-pNext-pNext
    pNext must be NULL

Possible values for VkScopeKHR include:

// Provided by VK_KHR_cooperative_matrix
typedef enum VkScopeKHR {
    VK_SCOPE_DEVICE_KHR = 1,
    VK_SCOPE_WORKGROUP_KHR = 2,
    VK_SCOPE_SUBGROUP_KHR = 3,
    VK_SCOPE_QUEUE_FAMILY_KHR = 5,
  // Provided by VK_NV_cooperative_matrix
    VK_SCOPE_DEVICE_NV = VK_SCOPE_DEVICE_KHR,
  // Provided by VK_NV_cooperative_matrix
    VK_SCOPE_WORKGROUP_NV = VK_SCOPE_WORKGROUP_KHR,
  // Provided by VK_NV_cooperative_matrix
    VK_SCOPE_SUBGROUP_NV = VK_SCOPE_SUBGROUP_KHR,
  // Provided by VK_NV_cooperative_matrix
    VK_SCOPE_QUEUE_FAMILY_NV = VK_SCOPE_QUEUE_FAMILY_KHR,
} VkScopeKHR;

or the equivalent

// Provided by VK_NV_cooperative_matrix
typedef VkScopeKHR VkScopeNV;

  • VK_SCOPE_DEVICE_KHR corresponds to SPIR-V Device scope.

  • VK_SCOPE_WORKGROUP_KHR corresponds to SPIR-V Workgroup scope.

  • VK_SCOPE_SUBGROUP_KHR corresponds to SPIR-V Subgroup scope.

  • VK_SCOPE_QUEUE_FAMILY_KHR corresponds to SPIR-V QueueFamily scope.

All enum values match the corresponding SPIR-V value.

Possible values for VkComponentTypeKHR include:

// Provided by VK_KHR_cooperative_matrix
typedef enum VkComponentTypeKHR {
    VK_COMPONENT_TYPE_FLOAT16_KHR = 0,
    VK_COMPONENT_TYPE_FLOAT32_KHR = 1,
    VK_COMPONENT_TYPE_FLOAT64_KHR = 2,
    VK_COMPONENT_TYPE_SINT8_KHR = 3,
    VK_COMPONENT_TYPE_SINT16_KHR = 4,
    VK_COMPONENT_TYPE_SINT32_KHR = 5,
    VK_COMPONENT_TYPE_SINT64_KHR = 6,
    VK_COMPONENT_TYPE_UINT8_KHR = 7,
    VK_COMPONENT_TYPE_UINT16_KHR = 8,
    VK_COMPONENT_TYPE_UINT32_KHR = 9,
    VK_COMPONENT_TYPE_UINT64_KHR = 10,
  // Provided by VK_NV_cooperative_matrix
    VK_COMPONENT_TYPE_FLOAT16_NV = VK_COMPONENT_TYPE_FLOAT16_KHR,
  // Provided by VK_NV_cooperative_matrix
    VK_COMPONENT_TYPE_FLOAT32_NV = VK_COMPONENT_TYPE_FLOAT32_KHR,
  // Provided by VK_NV_cooperative_matrix
    VK_COMPONENT_TYPE_FLOAT64_NV = VK_COMPONENT_TYPE_FLOAT64_KHR,
  // Provided by VK_NV_cooperative_matrix
    VK_COMPONENT_TYPE_SINT8_NV = VK_COMPONENT_TYPE_SINT8_KHR,
  // Provided by VK_NV_cooperative_matrix
    VK_COMPONENT_TYPE_SINT16_NV = VK_COMPONENT_TYPE_SINT16_KHR,
  // Provided by VK_NV_cooperative_matrix
    VK_COMPONENT_TYPE_SINT32_NV = VK_COMPONENT_TYPE_SINT32_KHR,
  // Provided by VK_NV_cooperative_matrix
    VK_COMPONENT_TYPE_SINT64_NV = VK_COMPONENT_TYPE_SINT64_KHR,
  // Provided by VK_NV_cooperative_matrix
    VK_COMPONENT_TYPE_UINT8_NV = VK_COMPONENT_TYPE_UINT8_KHR,
  // Provided by VK_NV_cooperative_matrix
    VK_COMPONENT_TYPE_UINT16_NV = VK_COMPONENT_TYPE_UINT16_KHR,
  // Provided by VK_NV_cooperative_matrix
    VK_COMPONENT_TYPE_UINT32_NV = VK_COMPONENT_TYPE_UINT32_KHR,
  // Provided by VK_NV_cooperative_matrix
    VK_COMPONENT_TYPE_UINT64_NV = VK_COMPONENT_TYPE_UINT64_KHR,
} VkComponentTypeKHR;

or the equivalent

// Provided by VK_NV_cooperative_matrix
typedef VkComponentTypeKHR VkComponentTypeNV;

  • VK_COMPONENT_TYPE_FLOAT16_KHR corresponds to SPIR-V OpTypeFloat 16.

  • VK_COMPONENT_TYPE_FLOAT32_KHR corresponds to SPIR-V OpTypeFloat 32.

  • VK_COMPONENT_TYPE_FLOAT64_KHR corresponds to SPIR-V OpTypeFloat 64.

  • VK_COMPONENT_TYPE_SINT8_KHR corresponds to SPIR-V OpTypeInt 8 0/1.

  • VK_COMPONENT_TYPE_SINT16_KHR corresponds to SPIR-V OpTypeInt 16 0/1.

  • VK_COMPONENT_TYPE_SINT32_KHR corresponds to SPIR-V OpTypeInt 32 0/1.

  • VK_COMPONENT_TYPE_SINT64_KHR corresponds to SPIR-V OpTypeInt 64 0/1.

  • VK_COMPONENT_TYPE_UINT8_KHR corresponds to SPIR-V OpTypeInt 8 0/1.

  • VK_COMPONENT_TYPE_UINT16_KHR corresponds to SPIR-V OpTypeInt 16 0/1.

  • VK_COMPONENT_TYPE_UINT32_KHR corresponds to SPIR-V OpTypeInt 32 0/1.

  • VK_COMPONENT_TYPE_UINT64_KHR corresponds to SPIR-V OpTypeInt 64 0/1.

9.31. Validation Cache

Validation cache objects allow the result of internal validation to be reused, both within a single application run and between multiple runs. Reuse within a single run is achieved by passing the same validation cache object when creating supported Vulkan objects. Reuse across runs of an application is achieved by retrieving validation cache contents in one run of an application, saving the contents, and using them to preinitialize a validation cache on a subsequent run. The contents of the validation cache objects are managed by the validation layers. Applications can manage the host memory consumed by a validation cache object and control the amount of data retrieved from a validation cache object.

Validation cache objects are represented by VkValidationCacheEXT handles:

// Provided by VK_EXT_validation_cache
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkValidationCacheEXT)

To create validation cache objects, call:

// Provided by VK_EXT_validation_cache
VkResult vkCreateValidationCacheEXT(
    VkDevice                                    device,
    const VkValidationCacheCreateInfoEXT*       pCreateInfo,
    const VkAllocationCallbacks*                pAllocator,
    VkValidationCacheEXT*                       pValidationCache);

  • device is the logical device that creates the validation cache object.

  • pCreateInfo is a pointer to a VkValidationCacheCreateInfoEXT structure containing the initial parameters for the validation cache object.

  • pAllocator controls host memory allocation as described in the Memory Allocation chapter.

  • pValidationCache is a pointer to a VkValidationCacheEXT handle in which the resulting validation cache object is returned.

Note

Applications can track and manage the total host memory size of a validation cache object using the pAllocator. Applications can limit the amount of data retrieved from a validation cache object in vkGetValidationCacheDataEXT. Implementations should not internally limit the total number of entries added to a validation cache object or the total host memory consumed.

Once created, a validation cache can be passed to the vkCreateShaderModule command by adding this object to the VkShaderModuleCreateInfo structure’s pNext chain. If a VkShaderModuleValidationCacheCreateInfoEXT object is included in the VkShaderModuleCreateInfo::pNext chain, and its validationCache field is not VK_NULL_HANDLE, the implementation will query it for possible reuse opportunities and update it with new content. The use of the validation cache object in these commands is internally synchronized, and the same validation cache object can be used in multiple threads simultaneously.

Note

Implementations should make every effort to limit any critical sections to the actual accesses to the cache, which is expected to be significantly shorter than the duration of the vkCreateShaderModule command.
Valid Usage (Implicit)

  • VUID-vkCreateValidationCacheEXT-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkCreateValidationCacheEXT-pCreateInfo-parameter
    pCreateInfo must be a valid pointer to a valid VkValidationCacheCreateInfoEXT structure

  • VUID-vkCreateValidationCacheEXT-pAllocator-parameter
    If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure

  • VUID-vkCreateValidationCacheEXT-pValidationCache-parameter
    pValidationCache must be a valid pointer to a VkValidationCacheEXT handle

Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

The VkValidationCacheCreateInfoEXT structure is defined as:

// Provided by VK_EXT_validation_cache
typedef struct VkValidationCacheCreateInfoEXT {
    VkStructureType                    sType;
    const void*                        pNext;
    VkValidationCacheCreateFlagsEXT    flags;
    size_t                             initialDataSize;
    const void*                        pInitialData;
} VkValidationCacheCreateInfoEXT;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • flags is reserved for future use.

  • initialDataSize is the number of bytes in pInitialData. If initialDataSize is zero, the validation cache will initially be empty.

  • pInitialData is a pointer to previously retrieved validation cache data. If the validation cache data is incompatible (as defined below) with the device, the validation cache will be initially empty. If initialDataSize is zero, pInitialData is ignored.

Valid Usage

  • VUID-VkValidationCacheCreateInfoEXT-initialDataSize-01534
    If initialDataSize is not 0, it must be equal to the size of pInitialData, as returned by vkGetValidationCacheDataEXT when pInitialData was originally retrieved

  • VUID-VkValidationCacheCreateInfoEXT-initialDataSize-01535
    If initialDataSize is not 0, pInitialData must have been retrieved from a previous call to vkGetValidationCacheDataEXT

Valid Usage (Implicit)

  • VUID-VkValidationCacheCreateInfoEXT-sType-sType
    sType must be VK_STRUCTURE_TYPE_VALIDATION_CACHE_CREATE_INFO_EXT

  • VUID-VkValidationCacheCreateInfoEXT-pNext-pNext
    pNext must be NULL

  • VUID-VkValidationCacheCreateInfoEXT-flags-zerobitmask
    flags must be 0

  • VUID-VkValidationCacheCreateInfoEXT-pInitialData-parameter
    If initialDataSize is not 0, pInitialData must be a valid pointer to an array of initialDataSize bytes

// Provided by VK_EXT_validation_cache
typedef VkFlags VkValidationCacheCreateFlagsEXT;

VkValidationCacheCreateFlagsEXT is a bitmask type for setting a mask, but is currently reserved for future use.

Validation cache objects can be merged using the command:

// Provided by VK_EXT_validation_cache
VkResult vkMergeValidationCachesEXT(
    VkDevice                                    device,
    VkValidationCacheEXT                        dstCache,
    uint32_t                                    srcCacheCount,
    const VkValidationCacheEXT*                 pSrcCaches);

  • device is the logical device that owns the validation cache objects.

  • dstCache is the handle of the validation cache to merge results into.

  • srcCacheCount is the length of the pSrcCaches array.

  • pSrcCaches is a pointer to an array of validation cache handles, which will be merged into dstCache. The previous contents of dstCache are included after the merge.

Note

The details of the merge operation are implementation-dependent, but implementations should merge the contents of the specified validation caches and prune duplicate entries.
Valid Usage

  • VUID-vkMergeValidationCachesEXT-dstCache-01536
    dstCache must not appear in the list of source caches

Valid Usage (Implicit)

  • VUID-vkMergeValidationCachesEXT-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkMergeValidationCachesEXT-dstCache-parameter
    dstCache must be a valid VkValidationCacheEXT handle

  • VUID-vkMergeValidationCachesEXT-pSrcCaches-parameter
    pSrcCaches must be a valid pointer to an array of srcCacheCount valid VkValidationCacheEXT handles

  • VUID-vkMergeValidationCachesEXT-srcCacheCount-arraylength
    srcCacheCount must be greater than 0

  • VUID-vkMergeValidationCachesEXT-dstCache-parent
    dstCache must have been created, allocated, or retrieved from device

  • VUID-vkMergeValidationCachesEXT-pSrcCaches-parent
    Each element of pSrcCaches must have been created, allocated, or retrieved from device

Host Synchronization

  • Host access to dstCache must be externally synchronized

Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

Data can be retrieved from a validation cache object using the command:

// Provided by VK_EXT_validation_cache
VkResult vkGetValidationCacheDataEXT(
    VkDevice                                    device,
    VkValidationCacheEXT                        validationCache,
    size_t*                                     pDataSize,
    void*                                       pData);

  • device is the logical device that owns the validation cache.

  • validationCache is the validation cache to retrieve data from.

  • pDataSize is a pointer to a value related to the amount of data in the validation cache, as described below.

  • pData is either NULL or a pointer to a buffer.

If pData is NULL, then the maximum size of the data that can be retrieved from the validation cache, in bytes, is returned in pDataSize. Otherwise, pDataSize must point to a variable set by the application to the size of the buffer, in bytes, pointed to by pData, and on return the variable is overwritten with the amount of data actually written to pData. If pDataSize is less than the maximum size that can be retrieved by the validation cache, at most pDataSize bytes will be written to pData, and vkGetValidationCacheDataEXT will return VK_INCOMPLETE instead of VK_SUCCESS, to indicate that not all of the validation cache was returned.

Any data written to pData is valid and can be provided as the pInitialData member of the VkValidationCacheCreateInfoEXT structure passed to vkCreateValidationCacheEXT.

Two calls to vkGetValidationCacheDataEXT with the same parameters must retrieve the same data unless a command that modifies the contents of the cache is called between them.

Applications can store the data retrieved from the validation cache, and use these data, possibly in a future run of the application, to populate new validation cache objects. The results of validation, however, may depend on the vendor ID, device ID, driver version, and other details of the device. To enable applications to detect when previously retrieved data is incompatible with the device, the initial bytes written to pData must be a header consisting of the following members:

Table 12. Layout for Validation Cache Header Version VK_VALIDATION_CACHE_HEADER_VERSION_ONE_EXT
Offset Size Meaning

0

4

length in bytes of the entire validation cache header written as a stream of bytes, with the least significant byte first

4

4

a VkValidationCacheHeaderVersionEXT value written as a stream of bytes, with the least significant byte first

8

VK_UUID_SIZE

a layer commit ID expressed as a UUID, which uniquely identifies the version of the validation layers used to generate these validation results

The first four bytes encode the length of the entire validation cache header, in bytes. This value includes all fields in the header including the validation cache version field and the size of the length field.

The next four bytes encode the validation cache version, as described for VkValidationCacheHeaderVersionEXT. A consumer of the validation cache should use the cache version to interpret the remainder of the cache header.

If pDataSize is less than what is necessary to store this header, nothing will be written to pData and zero will be written to pDataSize.

Valid Usage (Implicit)

  • VUID-vkGetValidationCacheDataEXT-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkGetValidationCacheDataEXT-validationCache-parameter
    validationCache must be a valid VkValidationCacheEXT handle

  • VUID-vkGetValidationCacheDataEXT-pDataSize-parameter
    pDataSize must be a valid pointer to a size_t value

  • VUID-vkGetValidationCacheDataEXT-pData-parameter
    If the value referenced by pDataSize is not 0, and pData is not NULL, pData must be a valid pointer to an array of pDataSize bytes

  • VUID-vkGetValidationCacheDataEXT-validationCache-parent
    validationCache must have been created, allocated, or retrieved from device

Return Codes
Success

  • VK_SUCCESS

  • VK_INCOMPLETE

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

Possible values of the second group of four bytes in the header returned by vkGetValidationCacheDataEXT, encoding the validation cache version, are:

// Provided by VK_EXT_validation_cache
typedef enum VkValidationCacheHeaderVersionEXT {
    VK_VALIDATION_CACHE_HEADER_VERSION_ONE_EXT = 1,
} VkValidationCacheHeaderVersionEXT;

  • VK_VALIDATION_CACHE_HEADER_VERSION_ONE_EXT specifies version one of the validation cache.

To destroy a validation cache, call:

// Provided by VK_EXT_validation_cache
void vkDestroyValidationCacheEXT(
    VkDevice                                    device,
    VkValidationCacheEXT                        validationCache,
    const VkAllocationCallbacks*                pAllocator);

  • device is the logical device that destroys the validation cache object.

  • validationCache is the handle of the validation cache to destroy.

  • pAllocator controls host memory allocation as described in the Memory Allocation chapter.

Valid Usage

  • VUID-vkDestroyValidationCacheEXT-validationCache-01537
    If VkAllocationCallbacks were provided when validationCache was created, a compatible set of callbacks must be provided here

  • VUID-vkDestroyValidationCacheEXT-validationCache-01538
    If no VkAllocationCallbacks were provided when validationCache was created, pAllocator must be NULL

Valid Usage (Implicit)

  • VUID-vkDestroyValidationCacheEXT-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkDestroyValidationCacheEXT-validationCache-parameter
    If validationCache is not VK_NULL_HANDLE, validationCache must be a valid VkValidationCacheEXT handle

  • VUID-vkDestroyValidationCacheEXT-pAllocator-parameter
    If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure

  • VUID-vkDestroyValidationCacheEXT-validationCache-parent
    If validationCache is a valid handle, it must have been created, allocated, or retrieved from device

Host Synchronization

  • Host access to validationCache must be externally synchronized

9.32. CUDA Modules

9.32.1. Creating a CUDA Module

CUDA modules must contain some kernel code and must expose at least one function entry point.

CUDA modules are represented by VkCudaModuleNV handles:

// Provided by VK_NV_cuda_kernel_launch
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkCudaModuleNV)

To create a CUDA module, call:

// Provided by VK_NV_cuda_kernel_launch
VkResult vkCreateCudaModuleNV(
    VkDevice                                    device,
    const VkCudaModuleCreateInfoNV*             pCreateInfo,
    const VkAllocationCallbacks*                pAllocator,
    VkCudaModuleNV*                             pModule);

  • device is the logical device that creates the shader module.

  • pCreateInfo is a pointer to a VkCudaModuleCreateInfoNV structure.

  • pAllocator controls host memory allocation as described in the Memory Allocation chapter.

  • pModule is a pointer to a VkCudaModuleNV handle in which the resulting CUDA module object is returned.

Once a CUDA module has been created, the application may create the function entry point, which must refer to one function in the module.

Valid Usage (Implicit)

  • VUID-vkCreateCudaModuleNV-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkCreateCudaModuleNV-pCreateInfo-parameter
    pCreateInfo must be a valid pointer to a valid VkCudaModuleCreateInfoNV structure

  • VUID-vkCreateCudaModuleNV-pAllocator-parameter
    If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure

  • VUID-vkCreateCudaModuleNV-pModule-parameter
    pModule must be a valid pointer to a VkCudaModuleNV handle

Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_INITIALIZATION_FAILED

  • VK_ERROR_OUT_OF_HOST_MEMORY

The VkCudaModuleCreateInfoNV structure is defined as:

// Provided by VK_NV_cuda_kernel_launch
typedef struct VkCudaModuleCreateInfoNV {
    VkStructureType    sType;
    const void*        pNext;
    size_t             dataSize;
    const void*        pData;
} VkCudaModuleCreateInfoNV;

  • sType is a VkStructureType value identifying this structure.

  • pNext may be NULL or may be a pointer to a structure extending this structure.

  • dataSize is the length of the pData array.

  • pData is a pointer to CUDA code

Valid Usage

  • VUID-VkCudaModuleCreateInfoNV-dataSize-09413
    dataSize must be the total size in bytes of the PTX files or binary cache passed to pData

Valid Usage (Implicit)

  • VUID-VkCudaModuleCreateInfoNV-sType-sType
    sType must be VK_STRUCTURE_TYPE_CUDA_MODULE_CREATE_INFO_NV

  • VUID-VkCudaModuleCreateInfoNV-pNext-pNext
    pNext must be NULL

  • VUID-VkCudaModuleCreateInfoNV-pData-parameter
    pData must be a valid pointer to an array of dataSize bytes

  • VUID-VkCudaModuleCreateInfoNV-dataSize-arraylength
    dataSize must be greater than 0

9.32.2. Creating a CUDA Function Handle

CUDA functions are represented by VkCudaFunctionNV handles. Handles to global functions may then be used to issue a kernel launch (i.e. dispatch) from a commandbuffer. See Dispatching Command for CUDA PTX kernel.

// Provided by VK_NV_cuda_kernel_launch
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkCudaFunctionNV)

To create a CUDA function, call:

// Provided by VK_NV_cuda_kernel_launch
VkResult vkCreateCudaFunctionNV(
    VkDevice                                    device,
    const VkCudaFunctionCreateInfoNV*           pCreateInfo,
    const VkAllocationCallbacks*                pAllocator,
    VkCudaFunctionNV*                           pFunction);

  • device is the logical device that creates the shader module.

  • pCreateInfo is a pointer to a VkCudaFunctionCreateInfoNV structure.

  • pAllocator controls host memory allocation as described in the Memory Allocation chapter.

  • pFunction is a pointer to a VkCudaFunctionNV handle in which the resulting CUDA function object is returned.

Valid Usage (Implicit)

  • VUID-vkCreateCudaFunctionNV-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkCreateCudaFunctionNV-pCreateInfo-parameter
    pCreateInfo must be a valid pointer to a valid VkCudaFunctionCreateInfoNV structure

  • VUID-vkCreateCudaFunctionNV-pAllocator-parameter
    If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure

  • VUID-vkCreateCudaFunctionNV-pFunction-parameter
    pFunction must be a valid pointer to a VkCudaFunctionNV handle

Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_INITIALIZATION_FAILED

  • VK_ERROR_OUT_OF_HOST_MEMORY

The VkCudaFunctionCreateInfoNV structure is defined as:

// Provided by VK_NV_cuda_kernel_launch
typedef struct VkCudaFunctionCreateInfoNV {
    VkStructureType    sType;
    const void*        pNext;
    VkCudaModuleNV     module;
    const char*        pName;
} VkCudaFunctionCreateInfoNV;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • module is the CUDA VkCudaModuleNV module in which the function resides.

  • pName is a null-terminated UTF-8 string containing the name of the shader entry point for this stage.

Valid Usage (Implicit)

  • VUID-VkCudaFunctionCreateInfoNV-sType-sType
    sType must be VK_STRUCTURE_TYPE_CUDA_FUNCTION_CREATE_INFO_NV

  • VUID-VkCudaFunctionCreateInfoNV-pNext-pNext
    pNext must be NULL

  • VUID-VkCudaFunctionCreateInfoNV-module-parameter
    module must be a valid VkCudaModuleNV handle

  • VUID-VkCudaFunctionCreateInfoNV-pName-parameter
    pName must be a null-terminated UTF-8 string

9.32.3. Destroying a CUDA Function

To destroy a CUDA function handle, call:

// Provided by VK_NV_cuda_kernel_launch
void vkDestroyCudaFunctionNV(
    VkDevice                                    device,
    VkCudaFunctionNV                            function,
    const VkAllocationCallbacks*                pAllocator);

  • device is the logical device that destroys the Function.

  • function is the handle of the CUDA function to destroy.

  • pAllocator controls host memory allocation as described in the Memory Allocation chapter.

Valid Usage (Implicit)

  • VUID-vkDestroyCudaFunctionNV-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkDestroyCudaFunctionNV-function-parameter
    function must be a valid VkCudaFunctionNV handle

  • VUID-vkDestroyCudaFunctionNV-pAllocator-parameter
    If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure

  • VUID-vkDestroyCudaFunctionNV-function-parent
    function must have been created, allocated, or retrieved from device

9.32.4. Destroying a CUDA Module

To destroy a CUDA shader module, call:

// Provided by VK_NV_cuda_kernel_launch
void vkDestroyCudaModuleNV(
    VkDevice                                    device,
    VkCudaModuleNV                              module,
    const VkAllocationCallbacks*                pAllocator);

  • device is the logical device that destroys the shader module.

  • module is the handle of the CUDA module to destroy.

  • pAllocator controls host memory allocation as described in the Memory Allocation chapter.

Valid Usage (Implicit)

  • VUID-vkDestroyCudaModuleNV-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkDestroyCudaModuleNV-module-parameter
    module must be a valid VkCudaModuleNV handle

  • VUID-vkDestroyCudaModuleNV-pAllocator-parameter
    If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure

  • VUID-vkDestroyCudaModuleNV-module-parent
    module must have been created, allocated, or retrieved from device

9.32.5. Reading back CUDA Module Cache

After uploading the PTX kernel code, the module compiles the code to generate a binary cache with all the necessary information for the device to execute it. It is possible to read back this cache for later use, such as accelerating the initialization of further executions.

To get the CUDA module cache call:

// Provided by VK_NV_cuda_kernel_launch
VkResult vkGetCudaModuleCacheNV(
    VkDevice                                    device,
    VkCudaModuleNV                              module,
    size_t*                                     pCacheSize,
    void*                                       pCacheData);

  • device is the logical device that destroys the Function.

  • module is the CUDA module.

  • pCacheSize is a pointer containing the amount of bytes to be copied in pCacheData

  • pCacheData is a pointer to a buffer in which to copy the binary cache

If pCacheData is NULL, then the size of the binary cache, in bytes, is returned in pCacheSize. Otherwise, pCacheSize must point to a variable set by the application to the size of the buffer, in bytes, pointed to by pCacheData, and on return the variable is overwritten with the amount of data actually written to pCacheData. If pCacheSize is less than the size of the binary shader code, nothing is written to pCacheData, and VK_INCOMPLETE will be returned instead of VK_SUCCESS.

The returned cache may then be used later for further initialization of the CUDA module, by sending this cache instead of the PTX code when using vkCreateCudaModuleNV.

Note

Using the binary cache instead of the original PTX code should significantly speed up initialization of the CUDA module, given that the whole compilation and validation will not be necessary.

As with VkPipelineCache, the binary cache depends on the specific implementation. The application must assume the cache upload might fail in many circumstances and thus may have to get ready for falling back to the original PTX code if necessary. Most often, the cache may succeed if the same device driver and architecture is used between the cache generation from PTX and the use of this cache. In the event of a new driver version or if using a different device architecture, this cache may become invalid.
Valid Usage (Implicit)

  • VUID-vkGetCudaModuleCacheNV-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkGetCudaModuleCacheNV-module-parameter
    module must be a valid VkCudaModuleNV handle

  • VUID-vkGetCudaModuleCacheNV-pCacheSize-parameter
    pCacheSize must be a valid pointer to a size_t value

  • VUID-vkGetCudaModuleCacheNV-pCacheData-parameter
    If the value referenced by pCacheSize is not 0, and pCacheData is not NULL, pCacheData must be a valid pointer to an array of pCacheSize bytes

  • VUID-vkGetCudaModuleCacheNV-module-parent
    module must have been created, allocated, or retrieved from device

Return Codes
Success

  • VK_SUCCESS

  • VK_INCOMPLETE

Failure

  • VK_ERROR_INITIALIZATION_FAILED

9.32.6. Limitations

CUDA and Vulkan do not use the device in the same configuration. The following limitations must be taken into account:

  • It is not possible to read or write global parameters from Vulkan. The only way to share resources or send values to the PTX kernel is to pass them as arguments of the function. See Resources sharing between CUDA Kernel and Vulkan for more details.

  • No calls to functions external to the module PTX are supported.

  • Vulkan disables some shader/kernel exceptions, which could break CUDA kernels relying on exceptions.

  • CUDA kernels submitted to Vulkan are limited to the amount of shared memory, which can be queried from the physical capabilities. It may be less than what CUDA can offer.

  • CUDA instruction-level preemption (CILP) does not work.

  • CUDA Unified Memory will not work in this extension.

  • CUDA Dynamic parallelism is not supported.

  • vk*DispatchIndirect is not available.

10. Pipelines

The following figure shows a block diagram of the Vulkan pipelines. Some Vulkan commands specify geometric objects to be drawn or computational work to be performed, while others specify state controlling how objects are handled by the various pipeline stages, or control data transfer between memory organized as images and buffers. Commands are effectively sent through a processing pipeline, either a graphics pipeline, a ray tracing pipeline, or a compute pipeline.

The graphics pipeline can be operated in two modes, as either primitive shading or mesh shading pipeline.

Primitive Shading

The first stage of the graphics pipeline (Input Assembler) assembles vertices to form geometric primitives such as points, lines, and triangles, based on a requested primitive topology. In the next stage (Vertex Shader) vertices can be transformed, computing positions and attributes for each vertex. If tessellation and/or geometry shaders are supported, they can then generate multiple primitives from a single input primitive, possibly changing the primitive topology or generating additional attribute data in the process.

Cluster Culling Shading

When using the Cluster Culling Shader, a compute-like shader will perform cluster-based culling, a set of new built-in output variables are used to express visible cluster, in addition, a new built-in function is used to emit these variables from the cluster culling shader to the Input Assembler(IA) stage, then IA can use these variables to fetches vertices of visible cluster and drive vertex shader to work.

Mesh Shading

When using the mesh shading pipeline input primitives are not assembled implicitly, but explicitly through the (Mesh Shader). The work on the mesh pipeline is initiated by the application drawing a set of mesh tasks.

If an optional (Task Shader) is active, each task triggers the execution of a task shader workgroup that will generate a new set of tasks upon completion. Each of these spawned tasks, or each of the original dispatched tasks if no task shader is present, triggers the execution of a mesh shader workgroup that produces an output mesh with a variable-sized number of primitives assembled from vertices stored in the output mesh.

Common

The final resulting primitives are clipped to a clip volume in preparation for the next stage, Rasterization. The rasterizer produces a series of fragments associated with a region of the framebuffer, from a two-dimensional description of a point, line segment, or triangle. These fragments are processed by fragment operations to determine whether generated values will be written to the framebuffer. Fragment shading determines the values to be written to the framebuffer attachments. Framebuffer operations then read and write the color and depth/stencil attachments of the framebuffer for a given subpass of a render pass instance. The attachments can be used as input attachments in the fragment shader in a later subpass of the same render pass.

The compute pipeline is a separate pipeline from the graphics pipeline, which operates on one-, two-, or three-dimensional workgroups which can read from and write to buffer and image memory.

This ordering is meant only as a tool for describing Vulkan, not as a strict rule of how Vulkan is implemented, and we present it only as a means to organize the various operations of the pipelines. Actual ordering guarantees between pipeline stages are explained in detail in the synchronization chapter.

image/svg+xml Vertex Shader Draw Input Assembler Tessellation Control Shader Tessellation Primitive Generator Tessellation Evaluation Shader Rasterization Indirect Buffer Legend Geometry Shader Vertex Post-Processing Early Per-Fragment Tests Fragment Shader Late Per-Fragment Tests Blending Index Buffer Vertex Buffers Task Shader DrawMeshTasks Depth/Stencil Attachments Input Attachments Color Attachments Fixed Function Stage Shader Stage Resource Compute Shader Dispatch Task Assembler Mesh Assembler Mesh Shader Descriptor Sets Push Constants Uniform Buffers Uniform Texel Buffers Sampled Images Storage Buffers Storage Texel Buffers Storage Images
Figure 2. Block diagram of the Vulkan pipeline

Each pipeline is controlled by a monolithic object created from a description of all of the shader stages and any relevant fixed-function stages. Linking the whole pipeline together allows the optimization of shaders based on their input/outputs and eliminates expensive draw time state validation.

A pipeline object is bound to the current state using vkCmdBindPipeline. Any pipeline object state that is specified as dynamic is not applied to the current state when the pipeline object is bound, but is instead set by dynamic state setting commands.

If the commandBufferInheritance feature is not enabled, then no state, including dynamic state, is inherited from one command buffer to another.

If the commandBufferInheritance feature is enabled, then all graphics and compute state that is valid at the end of the command buffer executed in a queue is inherited and valid at beginning of the command buffer next executed in the same queue. This applies to both primary and secondary command buffers, where a primary command buffer submitted to a queue will inherit state from the previously submitted command buffer to that queue, secondary command buffers will inherit state from the primary or seconard command buffer they are executed in, and after a seconard command buffer is executed, its state inherited by the primary or secondary command buffer that executed it. Command buffers executed in one queue do not inherit state from any command buffers executed in another queue.

Compute, ray tracing, and graphics pipelines are each represented by VkPipeline handles:

// Provided by VK_VERSION_1_0
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkPipeline)

10.1. Multiple Pipeline Creation

Multiple pipelines can be created in a single call by commands such as vkCreateExecutionGraphPipelinesAMDX, vkCreateRayTracingPipelinesKHR, vkCreateRayTracingPipelinesNV, vkCreateComputePipelines, and vkCreateGraphicsPipelines.

The creation commands are passed an array pCreateInfos of Vk*PipelineCreateInfo structures specifying parameters of each pipeline to be created, and return a corresponding array of handles in pPipelines. Each element index i of pPipelines is created based on the corresponding element i of pCreateInfos.

Applications can group together similar pipelines to be created in a single call, and implementations are encouraged to look for reuse opportunities when creating a group.

When attempting to create many pipelines in a single command, it is possible that creation may fail for a subset of them. In this case, the corresponding elements of pPipelines will be set to VK_NULL_HANDLE. If creation fails for a pipeline despite valid arguments (for example, due to out of memory errors), the VkResult code returned by the pipeline creation command will indicate why. The implementation will attempt to create all pipelines, and only return VK_NULL_HANDLE values for those that actually failed.

If creation fails for a pipeline that has the VK_PIPELINE_CREATE_EARLY_RETURN_ON_FAILURE_BIT set in its Vk*PipelineCreateInfo, pipelines at an index in the pPipelines array greater than or equal to that of the failing pipeline will be set to VK_NULL_HANDLE.

If creation fails for multiple pipelines, the returned VkResult must be the return value of any one of the pipelines which did not succeed. An application can reliably clean up from a failed call by iterating over the pPipelines array and destroying every element that is not VK_NULL_HANDLE.

If the entire command fails and no pipelines are created, all elements of pPipelines will be set to VK_NULL_HANDLE.

10.2. Compute Pipelines

Compute pipelines consist of a single static compute shader stage and the pipeline layout.

The compute pipeline represents a compute shader and is created by calling vkCreateComputePipelines with module and pName selecting an entry point from a shader module, where that entry point defines a valid compute shader, in the VkPipelineShaderStageCreateInfo structure contained within the VkComputePipelineCreateInfo structure.

To create compute pipelines, call:

// Provided by VK_VERSION_1_0
VkResult vkCreateComputePipelines(
    VkDevice                                    device,
    VkPipelineCache                             pipelineCache,
    uint32_t                                    createInfoCount,
    const VkComputePipelineCreateInfo*          pCreateInfos,
    const VkAllocationCallbacks*                pAllocator,
    VkPipeline*                                 pPipelines);

  • device is the logical device that creates the compute pipelines.

  • pipelineCache is either VK_NULL_HANDLE, indicating that pipeline caching is disabled; or the handle of a valid pipeline cache object, in which case use of that cache is enabled for the duration of the command.

  • createInfoCount is the length of the pCreateInfos and pPipelines arrays.

  • pCreateInfos is a pointer to an array of VkComputePipelineCreateInfo structures.

  • pAllocator controls host memory allocation as described in the Memory Allocation chapter.

  • pPipelines is a pointer to an array of VkPipeline handles in which the resulting compute pipeline objects are returned.

Pipelines are created and returned as described for Multiple Pipeline Creation.

Valid Usage

  • VUID-vkCreateComputePipelines-device-09661
    device must support at least one queue family with the VK_QUEUE_COMPUTE_BIT capability

  • VUID-vkCreateComputePipelines-flags-00695
    If the flags member of any element of pCreateInfos contains the VK_PIPELINE_CREATE_DERIVATIVE_BIT flag, and the basePipelineIndex member of that same element is not -1, basePipelineIndex must be less than the index into pCreateInfos that corresponds to that element

  • VUID-vkCreateComputePipelines-flags-00696
    If the flags member of any element of pCreateInfos contains the VK_PIPELINE_CREATE_DERIVATIVE_BIT flag, the base pipeline must have been created with the VK_PIPELINE_CREATE_ALLOW_DERIVATIVES_BIT flag set

  • VUID-vkCreateComputePipelines-pipelineCache-02873
    If pipelineCache was created with VK_PIPELINE_CACHE_CREATE_EXTERNALLY_SYNCHRONIZED_BIT, host access to pipelineCache must be externally synchronized

  • VUID-vkCreateComputePipelines-pNext-09616
    If VkPipelineBinaryInfoKHR::binaryCount is not 0 for any element of pCreateInfos, pipelineCache must be VK_NULL_HANDLE

  • VUID-vkCreateComputePipelines-pNext-09617
    If a VkPipelineCreateFlags2CreateInfoKHR structure with the VK_PIPELINE_CREATE_2_CAPTURE_DATA_BIT_KHR flag set is included in the pNext chain of any element of pCreateInfos, pipelineCache must be VK_NULL_HANDLE

  • VUID-vkCreateComputePipelines-binaryCount-09620
    If VkPipelineBinaryInfoKHR::binaryCount is not 0 for any element of pCreateInfos, VK_PIPELINE_CREATION_FEEDBACK_APPLICATION_PIPELINE_CACHE_HIT_BIT must not be set in the flags of that element

  • VUID-vkCreateComputePipelines-binaryCount-09621
    If VkPipelineBinaryInfoKHR::binaryCount is not 0 for any element of pCreateInfos, VK_PIPELINE_CREATION_FEEDBACK_BASE_PIPELINE_ACCELERATION_BIT must not be set in the flags of that element

  • VUID-vkCreateComputePipelines-binaryCount-09622
    If VkPipelineBinaryInfoKHR::binaryCount is not 0 for any element of pCreateInfos, VK_PIPELINE_CREATE_FAIL_ON_PIPELINE_COMPILE_REQUIRED_BIT_EXT must not be set in the flags of that element

Valid Usage (Implicit)

  • VUID-vkCreateComputePipelines-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkCreateComputePipelines-pipelineCache-parameter
    If pipelineCache is not VK_NULL_HANDLE, pipelineCache must be a valid VkPipelineCache handle

  • VUID-vkCreateComputePipelines-pCreateInfos-parameter
    pCreateInfos must be a valid pointer to an array of createInfoCount valid VkComputePipelineCreateInfo structures

  • VUID-vkCreateComputePipelines-pAllocator-parameter
    If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure

  • VUID-vkCreateComputePipelines-pPipelines-parameter
    pPipelines must be a valid pointer to an array of createInfoCount VkPipeline handles

  • VUID-vkCreateComputePipelines-createInfoCount-arraylength
    createInfoCount must be greater than 0

  • VUID-vkCreateComputePipelines-pipelineCache-parent
    If pipelineCache is a valid handle, it must have been created, allocated, or retrieved from device

Return Codes
Success

  • VK_SUCCESS

  • VK_PIPELINE_COMPILE_REQUIRED_EXT

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

  • VK_ERROR_INVALID_SHADER_NV

The VkComputePipelineCreateInfo structure is defined as:

// Provided by VK_VERSION_1_0
typedef struct VkComputePipelineCreateInfo {
    VkStructureType                    sType;
    const void*                        pNext;
    VkPipelineCreateFlags              flags;
    VkPipelineShaderStageCreateInfo    stage;
    VkPipelineLayout                   layout;
    VkPipeline                         basePipelineHandle;
    int32_t                            basePipelineIndex;
} VkComputePipelineCreateInfo;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • flags is a bitmask of VkPipelineCreateFlagBits specifying how the pipeline will be generated.

  • stage is a VkPipelineShaderStageCreateInfo structure describing the compute shader.

  • layout is the description of binding locations used by both the pipeline and descriptor sets used with the pipeline.

  • basePipelineHandle is a pipeline to derive from.

  • basePipelineIndex is an index into the pCreateInfos parameter to use as a pipeline to derive from.

The parameters basePipelineHandle and basePipelineIndex are described in more detail in Pipeline Derivatives.

If the pNext chain includes a VkPipelineCreateFlags2CreateInfoKHR structure, VkPipelineCreateFlags2CreateInfoKHR::flags from that structure is used instead of flags from this structure.

Valid Usage

  • VUID-VkComputePipelineCreateInfo-None-09497
    If the pNext chain does not include a VkPipelineCreateFlags2CreateInfoKHR structure, flags must be a valid combination of VkPipelineCreateFlagBits values

  • VUID-VkComputePipelineCreateInfo-flags-07984
    If flags contains the VK_PIPELINE_CREATE_DERIVATIVE_BIT flag, and basePipelineIndex is -1, basePipelineHandle must be a valid compute VkPipeline handle

  • VUID-VkComputePipelineCreateInfo-flags-07985
    If flags contains the VK_PIPELINE_CREATE_DERIVATIVE_BIT flag, and basePipelineHandle is VK_NULL_HANDLE, basePipelineIndex must be a valid index into the calling command’s pCreateInfos parameter

  • VUID-VkComputePipelineCreateInfo-flags-07986
    If flags contains the VK_PIPELINE_CREATE_DERIVATIVE_BIT flag, basePipelineIndex must be -1 or basePipelineHandle must be VK_NULL_HANDLE

  • VUID-VkComputePipelineCreateInfo-layout-07987
    If a push constant block is declared in a shader, a push constant range in layout must match the shader stage

  • VUID-VkComputePipelineCreateInfo-layout-10069
    If a push constant block is declared in a shader, the block must be contained inside the push constant range in layout that matches the stage

  • VUID-VkComputePipelineCreateInfo-layout-07988
    If a resource variables is declared in a shader, a descriptor slot in layout must match the shader stage

  • VUID-VkComputePipelineCreateInfo-layout-07990
    If a resource variables is declared in a shader, and the descriptor type is not VK_DESCRIPTOR_TYPE_MUTABLE_EXT, a descriptor slot in layout must match the descriptor type

  • VUID-VkComputePipelineCreateInfo-layout-07991
    If a resource variables is declared in a shader as an array, a descriptor slot in layout must match the descriptor count

  • VUID-VkComputePipelineCreateInfo-flags-03365
    flags must not include VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_ANY_HIT_SHADERS_BIT_KHR

  • VUID-VkComputePipelineCreateInfo-flags-03366
    flags must not include VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_CLOSEST_HIT_SHADERS_BIT_KHR

  • VUID-VkComputePipelineCreateInfo-flags-03367
    flags must not include VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_MISS_SHADERS_BIT_KHR

  • VUID-VkComputePipelineCreateInfo-flags-03368
    flags must not include VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_INTERSECTION_SHADERS_BIT_KHR

  • VUID-VkComputePipelineCreateInfo-flags-03369
    flags must not include VK_PIPELINE_CREATE_RAY_TRACING_SKIP_TRIANGLES_BIT_KHR

  • VUID-VkComputePipelineCreateInfo-flags-03370
    flags must not include VK_PIPELINE_CREATE_RAY_TRACING_SKIP_AABBS_BIT_KHR

  • VUID-VkComputePipelineCreateInfo-flags-03576
    flags must not include VK_PIPELINE_CREATE_RAY_TRACING_SHADER_GROUP_HANDLE_CAPTURE_REPLAY_BIT_KHR

  • VUID-VkComputePipelineCreateInfo-flags-04945
    flags must not include VK_PIPELINE_CREATE_RAY_TRACING_ALLOW_MOTION_BIT_NV

  • VUID-VkComputePipelineCreateInfo-flags-09007
    If the VkPhysicalDeviceDeviceGeneratedCommandsComputeFeaturesNV::deviceGeneratedComputePipelines is not enabled, flags must not include VK_PIPELINE_CREATE_INDIRECT_BINDABLE_BIT_NV

  • VUID-VkComputePipelineCreateInfo-flags-09008
    If flags includes VK_PIPELINE_CREATE_INDIRECT_BINDABLE_BIT_NV, then the pNext chain must include a pointer to a valid instance of VkComputePipelineIndirectBufferInfoNV specifying the address where the pipeline’s metadata will be saved

  • VUID-VkComputePipelineCreateInfo-flags-11007
    If flags includes VK_PIPELINE_CREATE_2_INDIRECT_BINDABLE_BIT_EXT, then the deviceGeneratedCommands feature must be enabled

  • VUID-VkComputePipelineCreateInfo-pipelineCreationCacheControl-02875
    If the pipelineCreationCacheControl feature is not enabled, flags must not include VK_PIPELINE_CREATE_FAIL_ON_PIPELINE_COMPILE_REQUIRED_BIT or VK_PIPELINE_CREATE_EARLY_RETURN_ON_FAILURE_BIT

  • VUID-VkComputePipelineCreateInfo-stage-00701
    The stage member of stage must be VK_SHADER_STAGE_COMPUTE_BIT

  • VUID-VkComputePipelineCreateInfo-stage-00702
    The shader code for the entry point identified by stage and the rest of the state identified by this structure must adhere to the pipeline linking rules described in the Shader Interfaces chapter

  • VUID-VkComputePipelineCreateInfo-layout-01687
    The number of resources in layout accessible to the compute shader stage must be less than or equal to VkPhysicalDeviceLimits::maxPerStageResources

  • VUID-VkComputePipelineCreateInfo-shaderEnqueue-09177
    If shaderEnqueue is not enabled, flags must not include VK_PIPELINE_CREATE_LIBRARY_BIT_KHR

  • VUID-VkComputePipelineCreateInfo-flags-09178
    If flags does not include VK_PIPELINE_CREATE_LIBRARY_BIT_KHR, the shader specified by stage must not declare the ShaderEnqueueAMDX capability

  • VUID-VkComputePipelineCreateInfo-pipelineStageCreationFeedbackCount-06566
    If VkPipelineCreationFeedbackCreateInfo::pipelineStageCreationFeedbackCount is not 0, it must be 1

  • VUID-VkComputePipelineCreateInfo-flags-07367
    flags must not include VK_PIPELINE_CREATE_RAY_TRACING_OPACITY_MICROMAP_BIT_EXT

  • VUID-VkComputePipelineCreateInfo-flags-07996
    flags must not include VK_PIPELINE_CREATE_RAY_TRACING_DISPLACEMENT_MICROMAP_BIT_NV

Valid Usage (Implicit)

The VkPipelineShaderStageCreateInfo structure is defined as:

// Provided by VK_VERSION_1_0
typedef struct VkPipelineShaderStageCreateInfo {
    VkStructureType                     sType;
    const void*                         pNext;
    VkPipelineShaderStageCreateFlags    flags;
    VkShaderStageFlagBits               stage;
    VkShaderModule                      module;
    const char*                         pName;
    const VkSpecializationInfo*         pSpecializationInfo;
} VkPipelineShaderStageCreateInfo;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • flags is a bitmask of VkPipelineShaderStageCreateFlagBits specifying how the pipeline shader stage will be generated.

  • stage is a VkShaderStageFlagBits value specifying a single pipeline stage.

  • module is optionally a VkShaderModule object containing the shader code for this stage.

  • pName is a pointer to a null-terminated UTF-8 string specifying the entry point name of the shader for this stage.

  • pSpecializationInfo is a pointer to a VkSpecializationInfo structure, as described in Specialization Constants, or NULL.

If module is not VK_NULL_HANDLE, the shader code used by the pipeline is defined by module. If module is VK_NULL_HANDLE, the shader code is defined by the chained VkShaderModuleCreateInfo if present.

If the shaderModuleIdentifier feature is enabled, applications can omit shader code for stage and instead provide a module identifier. This is done by including a VkPipelineShaderStageModuleIdentifierCreateInfoEXT struct with identifierSize not equal to 0 in the pNext chain. A shader stage created in this way is equivalent to one created using a shader module with the same identifier. The identifier allows an implementation to look up a pipeline without consuming a valid SPIR-V module. If a pipeline is not found, pipeline compilation is not possible and the implementation must fail as specified by VK_PIPELINE_CREATE_FAIL_ON_PIPELINE_COMPILE_REQUIRED_BIT.

When an identifier is used in lieu of a shader module, implementations may fail pipeline compilation with VK_PIPELINE_COMPILE_REQUIRED for any reason.

Note

The rationale for the relaxed requirement on implementations to return a pipeline with VkPipelineShaderStageModuleIdentifierCreateInfoEXT is that layers or tools may intercept pipeline creation calls and require the full SPIR-V context to operate correctly. ICDs are not expected to fail pipeline compilation if the pipeline exists in a cache somewhere.

Applications can use identifiers when creating pipelines with VK_PIPELINE_CREATE_LIBRARY_BIT_KHR. When creating such pipelines, VK_SUCCESS may be returned, but subsequently fail when referencing the pipeline in a VkPipelineLibraryCreateInfoKHR struct. Applications must allow pipeline compilation to fail during link steps with VK_PIPELINE_CREATE_FAIL_ON_PIPELINE_COMPILE_REQUIRED_BIT as it may not be possible to determine if a pipeline can be created from identifiers until the link step.

Valid Usage

  • VUID-VkPipelineShaderStageCreateInfo-stage-00704
    If the geometryShader feature is not enabled, stage must not be VK_SHADER_STAGE_GEOMETRY_BIT

  • VUID-VkPipelineShaderStageCreateInfo-stage-00705
    If the tessellationShader feature is not enabled, stage must not be VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT or VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT

  • VUID-VkPipelineShaderStageCreateInfo-stage-02091
    If the meshShaders feature is not enabled, stage must not be VK_SHADER_STAGE_MESH_BIT_EXT

  • VUID-VkPipelineShaderStageCreateInfo-stage-02092
    If the taskShaders feature is not enabled, stage must not be VK_SHADER_STAGE_TASK_BIT_EXT

  • VUID-VkPipelineShaderStageCreateInfo-clustercullingShader-07813
    If the clustercullingShader feature is not enabled, stage must not be VK_SHADER_STAGE_CLUSTER_CULLING_BIT_HUAWEI

  • VUID-VkPipelineShaderStageCreateInfo-stage-00706
    stage must not be VK_SHADER_STAGE_ALL_GRAPHICS, or VK_SHADER_STAGE_ALL

  • VUID-VkPipelineShaderStageCreateInfo-pName-00707
    pName must be the name of an OpEntryPoint in module with an execution model that matches stage

  • VUID-VkPipelineShaderStageCreateInfo-maxClipDistances-00708
    If the identified entry point includes any variable in its interface that is declared with the ClipDistance BuiltIn decoration, that variable must not have an array size greater than VkPhysicalDeviceLimits::maxClipDistances

  • VUID-VkPipelineShaderStageCreateInfo-maxCullDistances-00709
    If the identified entry point includes any variable in its interface that is declared with the CullDistance BuiltIn decoration, that variable must not have an array size greater than VkPhysicalDeviceLimits::maxCullDistances

  • VUID-VkPipelineShaderStageCreateInfo-maxCombinedClipAndCullDistances-00710
    If the identified entry point includes variables in its interface that are declared with the ClipDistance BuiltIn decoration and variables in its interface that are declared with the CullDistance BuiltIn decoration, those variables must not have array sizes which sum to more than VkPhysicalDeviceLimits::maxCombinedClipAndCullDistances

  • VUID-VkPipelineShaderStageCreateInfo-maxSampleMaskWords-00711
    If the identified entry point includes any variable in its interface that is declared with the SampleMask BuiltIn decoration, that variable must not have an array size greater than VkPhysicalDeviceLimits::maxSampleMaskWords

  • VUID-VkPipelineShaderStageCreateInfo-stage-00713
    If stage is VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT or VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT, and the identified entry point has an OpExecutionMode instruction specifying a patch size with OutputVertices, the patch size must be greater than 0 and less than or equal to VkPhysicalDeviceLimits::maxTessellationPatchSize

  • VUID-VkPipelineShaderStageCreateInfo-stage-00714
    If stage is VK_SHADER_STAGE_GEOMETRY_BIT, the identified entry point must have an OpExecutionMode instruction specifying a maximum output vertex count that is greater than 0 and less than or equal to VkPhysicalDeviceLimits::maxGeometryOutputVertices

  • VUID-VkPipelineShaderStageCreateInfo-stage-00715
    If stage is VK_SHADER_STAGE_GEOMETRY_BIT, the identified entry point must have an OpExecutionMode instruction specifying an invocation count that is greater than 0 and less than or equal to VkPhysicalDeviceLimits::maxGeometryShaderInvocations

  • VUID-VkPipelineShaderStageCreateInfo-stage-02596
    If stage is either VK_SHADER_STAGE_VERTEX_BIT, VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT, VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT, or VK_SHADER_STAGE_GEOMETRY_BIT, and the identified entry point writes to Layer for any primitive, it must write the same value to Layer for all vertices of a given primitive

  • VUID-VkPipelineShaderStageCreateInfo-stage-02597
    If stage is either VK_SHADER_STAGE_VERTEX_BIT, VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT, VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT, or VK_SHADER_STAGE_GEOMETRY_BIT, and the identified entry point writes to ViewportIndex for any primitive, it must write the same value to ViewportIndex for all vertices of a given primitive

  • VUID-VkPipelineShaderStageCreateInfo-stage-06685
    If stage is VK_SHADER_STAGE_FRAGMENT_BIT, and the identified entry point writes to FragDepth in any execution path, all execution paths that are not exclusive to helper invocations must either discard the fragment, or write or initialize the value of FragDepth

  • VUID-VkPipelineShaderStageCreateInfo-stage-06686
    If stage is VK_SHADER_STAGE_FRAGMENT_BIT, and the identified entry point writes to FragStencilRefEXT in any execution path, all execution paths that are not exclusive to helper invocations must either discard the fragment, or write or initialize the value of FragStencilRefEXT

  • VUID-VkPipelineShaderStageCreateInfo-flags-02784
    If flags has the VK_PIPELINE_SHADER_STAGE_CREATE_ALLOW_VARYING_SUBGROUP_SIZE_BIT flag set, the subgroupSizeControl feature must be enabled

  • VUID-VkPipelineShaderStageCreateInfo-flags-02785
    If flags has the VK_PIPELINE_SHADER_STAGE_CREATE_REQUIRE_FULL_SUBGROUPS_BIT flag set, the computeFullSubgroups feature must be enabled

  • VUID-VkPipelineShaderStageCreateInfo-flags-08988
    If flags includes VK_PIPELINE_SHADER_STAGE_CREATE_REQUIRE_FULL_SUBGROUPS_BIT, stage must be one of VK_SHADER_STAGE_MESH_BIT_EXT, VK_SHADER_STAGE_TASK_BIT_EXT, or VK_SHADER_STAGE_COMPUTE_BIT

  • VUID-VkPipelineShaderStageCreateInfo-pNext-02754
    If a VkPipelineShaderStageRequiredSubgroupSizeCreateInfo structure is included in the pNext chain, flags must not have the VK_PIPELINE_SHADER_STAGE_CREATE_ALLOW_VARYING_SUBGROUP_SIZE_BIT flag set

  • VUID-VkPipelineShaderStageCreateInfo-pNext-02755
    If a VkPipelineShaderStageRequiredSubgroupSizeCreateInfo structure is included in the pNext chain, the subgroupSizeControl feature must be enabled, and stage must be a valid bit specified in requiredSubgroupSizeStages

  • VUID-VkPipelineShaderStageCreateInfo-pNext-02756
    If a VkPipelineShaderStageRequiredSubgroupSizeCreateInfo structure is included in the pNext chain and stage is VK_SHADER_STAGE_COMPUTE_BIT, VK_SHADER_STAGE_MESH_BIT_EXT, or VK_SHADER_STAGE_TASK_BIT_EXT, the local workgroup size of the shader must be less than or equal to the product of VkPipelineShaderStageRequiredSubgroupSizeCreateInfo::requiredSubgroupSize and maxComputeWorkgroupSubgroups

  • VUID-VkPipelineShaderStageCreateInfo-pNext-02757
    If a VkPipelineShaderStageRequiredSubgroupSizeCreateInfo structure is included in the pNext chain, and flags has the VK_PIPELINE_SHADER_STAGE_CREATE_REQUIRE_FULL_SUBGROUPS_BIT flag set, the local workgroup size in the X dimension of the pipeline must be a multiple of VkPipelineShaderStageRequiredSubgroupSizeCreateInfo::requiredSubgroupSize

  • VUID-VkPipelineShaderStageCreateInfo-flags-02758
    If flags has both the VK_PIPELINE_SHADER_STAGE_CREATE_REQUIRE_FULL_SUBGROUPS_BIT and VK_PIPELINE_SHADER_STAGE_CREATE_ALLOW_VARYING_SUBGROUP_SIZE_BIT flags set, the local workgroup size in the X dimension of the pipeline must be a multiple of maxSubgroupSize

  • VUID-VkPipelineShaderStageCreateInfo-flags-02759
    If flags has the VK_PIPELINE_SHADER_STAGE_CREATE_REQUIRE_FULL_SUBGROUPS_BIT flag set and flags does not have the VK_PIPELINE_SHADER_STAGE_CREATE_ALLOW_VARYING_SUBGROUP_SIZE_BIT flag set and no VkPipelineShaderStageRequiredSubgroupSizeCreateInfo structure is included in the pNext chain, the local workgroup size in the X dimension of the pipeline must be a multiple of subgroupSize

  • VUID-VkPipelineShaderStageCreateInfo-module-08987
    If module uses the OpTypeCooperativeMatrixKHR instruction with a Scope equal to Subgroup, then the local workgroup size in the X dimension of the pipeline must be a multiple of subgroupSize

  • VUID-VkPipelineShaderStageCreateInfo-stage-08771
    If a shader module identifier is not specified for this stage, module must be a valid VkShaderModule , or the pNext chain of the parent Vk*CreateInfo structure must set VkPipelineBinaryInfoKHR::binaryCount to a value greater than 0, if none of the following features are enabled:

  • VUID-VkPipelineShaderStageCreateInfo-stage-06845
    If a shader module identifier is not specified for this stage, module must be a valid VkShaderModule, or there must be a valid VkShaderModuleCreateInfo structure in the pNext chain , or the pNext chain of the parent Vk*CreateInfo structure must set VkPipelineBinaryInfoKHR::binaryCount to a value greater than 0,

  • VUID-VkPipelineShaderStageCreateInfo-stage-06844
    If a shader module identifier is specified for this stage, the pNext chain must not include a VkShaderModuleCreateInfo structure

  • VUID-VkPipelineShaderStageCreateInfo-stage-06848
    If a shader module identifier is specified for this stage, module must be VK_NULL_HANDLE

  • VUID-VkPipelineShaderStageCreateInfo-pSpecializationInfo-06849
    If a shader module identifier is not specified, the shader code used by the pipeline must be valid as described by the Khronos SPIR-V Specification after applying the specializations provided in pSpecializationInfo, if any, and then converting all specialization constants into fixed constants

Valid Usage (Implicit)
// Provided by VK_VERSION_1_0
typedef VkFlags VkPipelineShaderStageCreateFlags;

VkPipelineShaderStageCreateFlags is a bitmask type for setting a mask of zero or more VkPipelineShaderStageCreateFlagBits.

Possible values of the flags member of VkPipelineShaderStageCreateInfo specifying how a pipeline shader stage is created, are:

// Provided by VK_VERSION_1_0
typedef enum VkPipelineShaderStageCreateFlagBits {
  // Provided by VK_VERSION_1_3
    VK_PIPELINE_SHADER_STAGE_CREATE_ALLOW_VARYING_SUBGROUP_SIZE_BIT = 0x00000001,
  // Provided by VK_VERSION_1_3
    VK_PIPELINE_SHADER_STAGE_CREATE_REQUIRE_FULL_SUBGROUPS_BIT = 0x00000002,
  // Provided by VK_EXT_subgroup_size_control
    VK_PIPELINE_SHADER_STAGE_CREATE_ALLOW_VARYING_SUBGROUP_SIZE_BIT_EXT = VK_PIPELINE_SHADER_STAGE_CREATE_ALLOW_VARYING_SUBGROUP_SIZE_BIT,
  // Provided by VK_EXT_subgroup_size_control
    VK_PIPELINE_SHADER_STAGE_CREATE_REQUIRE_FULL_SUBGROUPS_BIT_EXT = VK_PIPELINE_SHADER_STAGE_CREATE_REQUIRE_FULL_SUBGROUPS_BIT,
} VkPipelineShaderStageCreateFlagBits;

  • VK_PIPELINE_SHADER_STAGE_CREATE_ALLOW_VARYING_SUBGROUP_SIZE_BIT specifies that the SubgroupSize may vary in the shader stage.

  • VK_PIPELINE_SHADER_STAGE_CREATE_REQUIRE_FULL_SUBGROUPS_BIT specifies that the subgroup sizes must be launched with all invocations active in the task, mesh, or compute stage.

Note

If VK_PIPELINE_SHADER_STAGE_CREATE_ALLOW_VARYING_SUBGROUP_SIZE_BIT_EXT and VK_PIPELINE_SHADER_STAGE_CREATE_REQUIRE_FULL_SUBGROUPS_BIT_EXT are specified and minSubgroupSize does not equal maxSubgroupSize and no required subgroup size is specified, then the only way to guarantee that the 'X' dimension of the local workgroup size is a multiple of SubgroupSize is to make it a multiple of maxSubgroupSize. Under these conditions, you are guaranteed full subgroups but not any particular subgroup size.

Bits which can be set by commands and structures, specifying one or more shader stages, are:

// Provided by VK_VERSION_1_0
typedef enum VkShaderStageFlagBits {
    VK_SHADER_STAGE_VERTEX_BIT = 0x00000001,
    VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT = 0x00000002,
    VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT = 0x00000004,
    VK_SHADER_STAGE_GEOMETRY_BIT = 0x00000008,
    VK_SHADER_STAGE_FRAGMENT_BIT = 0x00000010,
    VK_SHADER_STAGE_COMPUTE_BIT = 0x00000020,
    VK_SHADER_STAGE_ALL_GRAPHICS = 0x0000001F,
    VK_SHADER_STAGE_ALL = 0x7FFFFFFF,
  // Provided by VK_KHR_ray_tracing_pipeline
    VK_SHADER_STAGE_RAYGEN_BIT_KHR = 0x00000100,
  // Provided by VK_KHR_ray_tracing_pipeline
    VK_SHADER_STAGE_ANY_HIT_BIT_KHR = 0x00000200,
  // Provided by VK_KHR_ray_tracing_pipeline
    VK_SHADER_STAGE_CLOSEST_HIT_BIT_KHR = 0x00000400,
  // Provided by VK_KHR_ray_tracing_pipeline
    VK_SHADER_STAGE_MISS_BIT_KHR = 0x00000800,
  // Provided by VK_KHR_ray_tracing_pipeline
    VK_SHADER_STAGE_INTERSECTION_BIT_KHR = 0x00001000,
  // Provided by VK_KHR_ray_tracing_pipeline
    VK_SHADER_STAGE_CALLABLE_BIT_KHR = 0x00002000,
  // Provided by VK_EXT_mesh_shader
    VK_SHADER_STAGE_TASK_BIT_EXT = 0x00000040,
  // Provided by VK_EXT_mesh_shader
    VK_SHADER_STAGE_MESH_BIT_EXT = 0x00000080,
  // Provided by VK_HUAWEI_subpass_shading
    VK_SHADER_STAGE_SUBPASS_SHADING_BIT_HUAWEI = 0x00004000,
  // Provided by VK_HUAWEI_cluster_culling_shader
    VK_SHADER_STAGE_CLUSTER_CULLING_BIT_HUAWEI = 0x00080000,
  // Provided by VK_NV_ray_tracing
    VK_SHADER_STAGE_RAYGEN_BIT_NV = VK_SHADER_STAGE_RAYGEN_BIT_KHR,
  // Provided by VK_NV_ray_tracing
    VK_SHADER_STAGE_ANY_HIT_BIT_NV = VK_SHADER_STAGE_ANY_HIT_BIT_KHR,
  // Provided by VK_NV_ray_tracing
    VK_SHADER_STAGE_CLOSEST_HIT_BIT_NV = VK_SHADER_STAGE_CLOSEST_HIT_BIT_KHR,
  // Provided by VK_NV_ray_tracing
    VK_SHADER_STAGE_MISS_BIT_NV = VK_SHADER_STAGE_MISS_BIT_KHR,
  // Provided by VK_NV_ray_tracing
    VK_SHADER_STAGE_INTERSECTION_BIT_NV = VK_SHADER_STAGE_INTERSECTION_BIT_KHR,
  // Provided by VK_NV_ray_tracing
    VK_SHADER_STAGE_CALLABLE_BIT_NV = VK_SHADER_STAGE_CALLABLE_BIT_KHR,
  // Provided by VK_NV_mesh_shader
    VK_SHADER_STAGE_TASK_BIT_NV = VK_SHADER_STAGE_TASK_BIT_EXT,
  // Provided by VK_NV_mesh_shader
    VK_SHADER_STAGE_MESH_BIT_NV = VK_SHADER_STAGE_MESH_BIT_EXT,
} VkShaderStageFlagBits;

  • VK_SHADER_STAGE_VERTEX_BIT specifies the vertex stage.

  • VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT specifies the tessellation control stage.

  • VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT specifies the tessellation evaluation stage.

  • VK_SHADER_STAGE_GEOMETRY_BIT specifies the geometry stage.

  • VK_SHADER_STAGE_FRAGMENT_BIT specifies the fragment stage.

  • VK_SHADER_STAGE_COMPUTE_BIT specifies the compute stage.

  • VK_SHADER_STAGE_ALL_GRAPHICS is a combination of bits used as shorthand to specify all graphics stages defined above (excluding the compute stage).

  • VK_SHADER_STAGE_ALL is a combination of bits used as shorthand to specify all shader stages supported by the device, including all additional stages which are introduced by extensions.

  • VK_SHADER_STAGE_TASK_BIT_EXT specifies the task stage.

  • VK_SHADER_STAGE_MESH_BIT_EXT specifies the mesh stage.

  • VK_SHADER_STAGE_CLUSTER_CULLING_BIT_HUAWEI specifies the cluster culling stage.

  • VK_SHADER_STAGE_RAYGEN_BIT_KHR specifies the ray generation stage.

  • VK_SHADER_STAGE_ANY_HIT_BIT_KHR specifies the any-hit stage.

  • VK_SHADER_STAGE_CLOSEST_HIT_BIT_KHR specifies the closest hit stage.

  • VK_SHADER_STAGE_MISS_BIT_KHR specifies the miss stage.

  • VK_SHADER_STAGE_INTERSECTION_BIT_KHR specifies the intersection stage.

  • VK_SHADER_STAGE_CALLABLE_BIT_KHR specifies the callable stage.

Note

VK_SHADER_STAGE_ALL_GRAPHICS only includes the original five graphics stages included in Vulkan 1.0, and not any stages added by extensions. Thus, it may not have the desired effect in all cases.

 
// Provided by VK_VERSION_1_0
typedef VkFlags VkShaderStageFlags;

VkShaderStageFlags is a bitmask type for setting a mask of zero or more VkShaderStageFlagBits.

The VkPipelineShaderStageRequiredSubgroupSizeCreateInfo structure is defined as:

// Provided by VK_VERSION_1_3
typedef struct VkPipelineShaderStageRequiredSubgroupSizeCreateInfo {
    VkStructureType    sType;
    void*              pNext;
    uint32_t           requiredSubgroupSize;
} VkPipelineShaderStageRequiredSubgroupSizeCreateInfo;

or the equivalent

// Provided by VK_EXT_subgroup_size_control
typedef VkPipelineShaderStageRequiredSubgroupSizeCreateInfo VkPipelineShaderStageRequiredSubgroupSizeCreateInfoEXT;

or the equiavlent

// Provided by VK_EXT_shader_object
typedef VkPipelineShaderStageRequiredSubgroupSizeCreateInfo VkShaderRequiredSubgroupSizeCreateInfoEXT;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • requiredSubgroupSize is an unsigned integer value specifying the required subgroup size for the newly created pipeline shader stage.

If a VkPipelineShaderStageRequiredSubgroupSizeCreateInfo structure is included in the pNext chain of VkPipelineShaderStageCreateInfo, it specifies that the pipeline shader stage being compiled has a required subgroup size.

If a VkShaderRequiredSubgroupSizeCreateInfoEXT structure is included in the pNext chain of VkShaderCreateInfoEXT, it specifies that the shader being compiled has a required subgroup size.

Valid Usage

  • VUID-VkPipelineShaderStageRequiredSubgroupSizeCreateInfo-requiredSubgroupSize-02760
    requiredSubgroupSize must be a power-of-two integer

  • VUID-VkPipelineShaderStageRequiredSubgroupSizeCreateInfo-requiredSubgroupSize-02761
    requiredSubgroupSize must be greater or equal to minSubgroupSize

  • VUID-VkPipelineShaderStageRequiredSubgroupSizeCreateInfo-requiredSubgroupSize-02762
    requiredSubgroupSize must be less than or equal to maxSubgroupSize

Valid Usage (Implicit)

  • VUID-VkPipelineShaderStageRequiredSubgroupSizeCreateInfo-sType-sType
    sType must be VK_STRUCTURE_TYPE_PIPELINE_SHADER_STAGE_REQUIRED_SUBGROUP_SIZE_CREATE_INFO

A subpass shading pipeline is a compute pipeline which must be called only in a subpass of a render pass with work dimensions specified by render area size. The subpass shading pipeline shader is a compute shader allowed to access input attachments specified in the calling subpass. To create a subpass shading pipeline, call vkCreateComputePipelines with VkSubpassShadingPipelineCreateInfoHUAWEI in the pNext chain of VkComputePipelineCreateInfo.

The VkSubpassShadingPipelineCreateInfoHUAWEI structure is defined as:

// Provided by VK_HUAWEI_subpass_shading
typedef struct VkSubpassShadingPipelineCreateInfoHUAWEI {
    VkStructureType    sType;
    void*              pNext;
    VkRenderPass       renderPass;
    uint32_t           subpass;
} VkSubpassShadingPipelineCreateInfoHUAWEI;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • renderPass is a handle to a render pass object describing the environment in which the pipeline will be used. The pipeline must only be used with a render pass instance compatible with the one provided. See Render Pass Compatibility for more information.

  • subpass is the index of the subpass in the render pass where this pipeline will be used.

Valid Usage

  • VUID-VkSubpassShadingPipelineCreateInfoHUAWEI-subpass-04946
    subpass must be created with VK_PIPELINE_BIND_POINT_SUBPASS_SHADING_HUAWEI bind point

Valid Usage (Implicit)

  • VUID-VkSubpassShadingPipelineCreateInfoHUAWEI-sType-sType
    sType must be VK_STRUCTURE_TYPE_SUBPASS_SHADING_PIPELINE_CREATE_INFO_HUAWEI

  • VUID-VkSubpassShadingPipelineCreateInfoHUAWEI-renderPass-parameter
    renderPass must be a valid VkRenderPass handle

A subpass shading pipeline’s workgroup size is a 2D vector with number of power-of-two in width and height. The maximum number of width and height is implementation-dependent, and may vary for different formats and sample counts of attachments in a render pass.

To query the maximum workgroup size, call:

// Provided by VK_HUAWEI_subpass_shading
VkResult vkGetDeviceSubpassShadingMaxWorkgroupSizeHUAWEI(
    VkDevice                                    device,
    VkRenderPass                                renderpass,
    VkExtent2D*                                 pMaxWorkgroupSize);

  • device is a handle to a local device object that was used to create the given render pass.

  • renderPass is a handle to a render pass object describing the environment in which the pipeline will be used. The pipeline must only be used with a render pass instance compatible with the one provided. See Render Pass Compatibility for more information.

  • pMaxWorkgroupSize is a pointer to a VkExtent2D structure.

Valid Usage (Implicit)

  • VUID-vkGetDeviceSubpassShadingMaxWorkgroupSizeHUAWEI-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkGetDeviceSubpassShadingMaxWorkgroupSizeHUAWEI-renderpass-parameter
    renderpass must be a valid VkRenderPass handle

  • VUID-vkGetDeviceSubpassShadingMaxWorkgroupSizeHUAWEI-pMaxWorkgroupSize-parameter
    pMaxWorkgroupSize must be a valid pointer to VkExtent2D structures

  • VUID-vkGetDeviceSubpassShadingMaxWorkgroupSizeHUAWEI-renderpass-parent
    renderpass must have been created, allocated, or retrieved from device

Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

  • VK_ERROR_SURFACE_LOST_KHR

The VkPipelineRobustnessCreateInfoEXT structure is defined as:

// Provided by VK_EXT_pipeline_robustness
typedef struct VkPipelineRobustnessCreateInfoEXT {
    VkStructureType                          sType;
    const void*                              pNext;
    VkPipelineRobustnessBufferBehaviorEXT    storageBuffers;
    VkPipelineRobustnessBufferBehaviorEXT    uniformBuffers;
    VkPipelineRobustnessBufferBehaviorEXT    vertexInputs;
    VkPipelineRobustnessImageBehaviorEXT     images;
} VkPipelineRobustnessCreateInfoEXT;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • storageBuffers sets the behavior of out of bounds accesses made to resources bound as:

    • VK_DESCRIPTOR_TYPE_STORAGE_BUFFER

    • VK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER

    • VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC

  • uniformBuffers describes the behavior of out of bounds accesses made to resources bound as:

    • VK_DESCRIPTOR_TYPE_UNIFORM_TEXEL_BUFFER

    • VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER

    • VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC

    • VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK

  • vertexInputs describes the behavior of out of bounds accesses made to vertex input attributes

  • images describes the behavior of out of bounds accesses made to resources bound as:

    • VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE

    • VK_DESCRIPTOR_TYPE_STORAGE_IMAGE

Resources bound as VK_DESCRIPTOR_TYPE_MUTABLE_EXT will have the robustness behavior that covers its active descriptor type.

The scope of the effect of VkPipelineRobustnessCreateInfoEXT depends on which structure’s pNext chain it is included in.

  • VkGraphicsPipelineCreateInfo, VkRayTracingPipelineCreateInfoKHR, VkComputePipelineCreateInfo:
    The robustness behavior described by VkPipelineRobustnessCreateInfoEXT applies to all accesses through this pipeline

  • VkPipelineShaderStageCreateInfo:
    The robustness behavior described by VkPipelineRobustnessCreateInfoEXT applies to all accesses emanating from the shader code of this shader stage

If VkPipelineRobustnessCreateInfoEXT is specified for both a pipeline and a pipeline stage, the VkPipelineRobustnessCreateInfoEXT specified for the pipeline stage will take precedence.

When VkPipelineRobustnessCreateInfoEXT is specified for a pipeline, it only affects the subset of the pipeline that is specified by the create info, as opposed to subsets linked from pipeline libraries. For VkGraphicsPipelineCreateInfo, that subset is specified by VkGraphicsPipelineLibraryCreateInfoEXT::flags. For VkRayTracingPipelineCreateInfoKHR, that subset is specified by the specific stages in VkRayTracingPipelineCreateInfoKHR::pStages.

Valid Usage

  • VUID-VkPipelineRobustnessCreateInfoEXT-pipelineRobustness-06926
    If the pipelineRobustness feature is not enabled, storageBuffers must be VK_PIPELINE_ROBUSTNESS_BUFFER_BEHAVIOR_DEVICE_DEFAULT_EXT

  • VUID-VkPipelineRobustnessCreateInfoEXT-pipelineRobustness-06927
    If the pipelineRobustness feature is not enabled, uniformBuffers must be VK_PIPELINE_ROBUSTNESS_BUFFER_BEHAVIOR_DEVICE_DEFAULT_EXT

  • VUID-VkPipelineRobustnessCreateInfoEXT-pipelineRobustness-06928
    If the pipelineRobustness feature is not enabled, vertexInputs must be VK_PIPELINE_ROBUSTNESS_BUFFER_BEHAVIOR_DEVICE_DEFAULT_EXT

  • VUID-VkPipelineRobustnessCreateInfoEXT-pipelineRobustness-06929
    If the pipelineRobustness feature is not enabled, images must be VK_PIPELINE_ROBUSTNESS_IMAGE_BEHAVIOR_DEVICE_DEFAULT_EXT

  • VUID-VkPipelineRobustnessCreateInfoEXT-robustImageAccess-06930
    If the robustImageAccess feature is not supported, images must not be VK_PIPELINE_ROBUSTNESS_IMAGE_BEHAVIOR_ROBUST_IMAGE_ACCESS_EXT

  • VUID-VkPipelineRobustnessCreateInfoEXT-robustBufferAccess2-06931
    If the robustBufferAccess2 feature is not supported, storageBuffers must not be VK_PIPELINE_ROBUSTNESS_BUFFER_BEHAVIOR_ROBUST_BUFFER_ACCESS_2_EXT

  • VUID-VkPipelineRobustnessCreateInfoEXT-robustBufferAccess2-06932
    If the robustBufferAccess2 feature is not supported, uniformBuffers must not be VK_PIPELINE_ROBUSTNESS_BUFFER_BEHAVIOR_ROBUST_BUFFER_ACCESS_2_EXT

  • VUID-VkPipelineRobustnessCreateInfoEXT-robustBufferAccess2-06933
    If the robustBufferAccess2 feature is not supported, vertexInputs must not be VK_PIPELINE_ROBUSTNESS_BUFFER_BEHAVIOR_ROBUST_BUFFER_ACCESS_2_EXT

  • VUID-VkPipelineRobustnessCreateInfoEXT-robustImageAccess2-06934
    If the robustImageAccess2 feature is not supported, images must not be VK_PIPELINE_ROBUSTNESS_IMAGE_BEHAVIOR_ROBUST_IMAGE_ACCESS_2_EXT

Valid Usage (Implicit)

Possible values of the storageBuffers, uniformBuffers, and vertexInputs members of VkPipelineRobustnessCreateInfoEXT are:

// Provided by VK_EXT_pipeline_robustness
typedef enum VkPipelineRobustnessBufferBehaviorEXT {
    VK_PIPELINE_ROBUSTNESS_BUFFER_BEHAVIOR_DEVICE_DEFAULT_EXT = 0,
    VK_PIPELINE_ROBUSTNESS_BUFFER_BEHAVIOR_DISABLED_EXT = 1,
    VK_PIPELINE_ROBUSTNESS_BUFFER_BEHAVIOR_ROBUST_BUFFER_ACCESS_EXT = 2,
    VK_PIPELINE_ROBUSTNESS_BUFFER_BEHAVIOR_ROBUST_BUFFER_ACCESS_2_EXT = 3,
} VkPipelineRobustnessBufferBehaviorEXT;

  • VK_PIPELINE_ROBUSTNESS_BUFFER_BEHAVIOR_DEVICE_DEFAULT_EXT specifies that this pipeline stage follows the behavior of robustness features that are enabled on the device that created this pipeline

  • VK_PIPELINE_ROBUSTNESS_BUFFER_BEHAVIOR_DISABLED_EXT specifies that buffer accesses by this pipeline stage to the relevant resource types must not be out of bounds

  • VK_PIPELINE_ROBUSTNESS_BUFFER_BEHAVIOR_ROBUST_BUFFER_ACCESS_EXT specifies that out of bounds accesses by this pipeline stage to the relevant resource types behave as if the robustBufferAccess feature is enabled

  • VK_PIPELINE_ROBUSTNESS_BUFFER_BEHAVIOR_ROBUST_BUFFER_ACCESS_2_EXT specifies that out of bounds accesses by this pipeline stage to the relevant resource types behave as if the robustBufferAccess2 feature is enabled

Possible values of the images member of VkPipelineRobustnessCreateInfoEXT are:

// Provided by VK_EXT_pipeline_robustness
typedef enum VkPipelineRobustnessImageBehaviorEXT {
    VK_PIPELINE_ROBUSTNESS_IMAGE_BEHAVIOR_DEVICE_DEFAULT_EXT = 0,
    VK_PIPELINE_ROBUSTNESS_IMAGE_BEHAVIOR_DISABLED_EXT = 1,
    VK_PIPELINE_ROBUSTNESS_IMAGE_BEHAVIOR_ROBUST_IMAGE_ACCESS_EXT = 2,
    VK_PIPELINE_ROBUSTNESS_IMAGE_BEHAVIOR_ROBUST_IMAGE_ACCESS_2_EXT = 3,
} VkPipelineRobustnessImageBehaviorEXT;

  • VK_PIPELINE_ROBUSTNESS_IMAGE_BEHAVIOR_DEVICE_DEFAULT_EXT specifies that this pipeline stage follows the behavior of robustness features that are enabled on the device that created this pipeline

  • VK_PIPELINE_ROBUSTNESS_IMAGE_BEHAVIOR_DISABLED_EXT specifies that image accesses by this pipeline stage to the relevant resource types must not be out of bounds

  • VK_PIPELINE_ROBUSTNESS_IMAGE_BEHAVIOR_ROBUST_IMAGE_ACCESS_EXT specifies that out of bounds accesses by this pipeline stage to images behave as if the robustImageAccess feature is enabled

  • VK_PIPELINE_ROBUSTNESS_IMAGE_BEHAVIOR_ROBUST_IMAGE_ACCESS_2_EXT specifies that out of bounds accesses by this pipeline stage to images behave as if the robustImageAccess2 feature is enabled

An identifier can be provided instead of shader code in an attempt to compile pipelines without providing complete SPIR-V to the implementation.

The VkPipelineShaderStageModuleIdentifierCreateInfoEXT structure is defined as:

// Provided by VK_EXT_shader_module_identifier
typedef struct VkPipelineShaderStageModuleIdentifierCreateInfoEXT {
    VkStructureType    sType;
    const void*        pNext;
    uint32_t           identifierSize;
    const uint8_t*     pIdentifier;
} VkPipelineShaderStageModuleIdentifierCreateInfoEXT;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • identifierSize is the size, in bytes, of the buffer pointed to by pIdentifier.

  • pIdentifier is a pointer to a buffer of opaque data specifying an identifier.

Any identifier can be used. If the pipeline being created with identifier requires compilation to complete the pipeline creation call, pipeline compilation must fail as defined by VK_PIPELINE_CREATE_FAIL_ON_PIPELINE_COMPILE_REQUIRED_BIT.

pIdentifier and identifierSize can be obtained from an VkShaderModuleIdentifierEXT queried earlier.

Valid Usage

  • VUID-VkPipelineShaderStageModuleIdentifierCreateInfoEXT-pNext-06850
    If this structure is included in a pNext chain and identifierSize is not equal to 0, the shaderModuleIdentifier feature must be enabled

  • VUID-VkPipelineShaderStageModuleIdentifierCreateInfoEXT-pNext-06851
    If this struct is included in a pNext chain of VkPipelineShaderStageCreateInfo and identifierSize is not equal to 0, the pipeline must be created with the VK_PIPELINE_CREATE_FAIL_ON_PIPELINE_COMPILE_REQUIRED_BIT flag set

  • VUID-VkPipelineShaderStageModuleIdentifierCreateInfoEXT-identifierSize-06852
    identifierSize must be less-or-equal to VK_MAX_SHADER_MODULE_IDENTIFIER_SIZE_EXT

Valid Usage (Implicit)

  • VUID-VkPipelineShaderStageModuleIdentifierCreateInfoEXT-sType-sType
    sType must be VK_STRUCTURE_TYPE_PIPELINE_SHADER_STAGE_MODULE_IDENTIFIER_CREATE_INFO_EXT

  • VUID-VkPipelineShaderStageModuleIdentifierCreateInfoEXT-pIdentifier-parameter
    If identifierSize is not 0, pIdentifier must be a valid pointer to an array of identifierSize uint8_t values

If a compute pipeline is going to be used in Device-Generated Commands by specifying its pipeline token with VkBindPipelineIndirectCommandNV, then that pipeline’s associated metadata must be saved at a specified buffer device address for later use in indirect command generation. The buffer device address must be specified at the time of compute pipeline creation with VkComputePipelineIndirectBufferInfoNV structure in the pNext chain of VkComputePipelineCreateInfo.

The VkComputePipelineIndirectBufferInfoNV structure is defined as:

// Provided by VK_NV_device_generated_commands_compute
typedef struct VkComputePipelineIndirectBufferInfoNV {
    VkStructureType    sType;
    const void*        pNext;
    VkDeviceAddress    deviceAddress;
    VkDeviceSize       size;
    VkDeviceAddress    pipelineDeviceAddressCaptureReplay;
} VkComputePipelineIndirectBufferInfoNV;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • deviceAddress is the address where the pipeline’s metadata will be stored.

  • size is the size of pipeline’s metadata that was queried using vkGetPipelineIndirectMemoryRequirementsNV.

  • pipelineDeviceAddressCaptureReplay is the device address where pipeline’s metadata was originally saved and can now be used to re-populate deviceAddress for replay.

If pipelineDeviceAddressCaptureReplay is zero, no specific address is requested. If pipelineDeviceAddressCaptureReplay is not zero, then it must be an address retrieved from an identically created pipeline on the same implementation. The pipeline metadata must also be placed on an identically created buffer and at the same offset using the vkCmdUpdatePipelineIndirectBufferNV command.

Valid Usage

  • VUID-VkComputePipelineIndirectBufferInfoNV-deviceGeneratedComputePipelines-09009
    The VkPhysicalDeviceDeviceGeneratedCommandsComputeFeaturesNV::deviceGeneratedComputePipelines feature must be enabled

  • VUID-VkComputePipelineIndirectBufferInfoNV-flags-09010
    The pipeline creation flags in VkComputePipelineCreateInfo::flags must include VK_PIPELINE_CREATE_INDIRECT_BINDABLE_BIT_NV

  • VUID-VkComputePipelineIndirectBufferInfoNV-deviceAddress-09011
    deviceAddress must be aligned to the VkMemoryRequirements2::alignment, as returned by vkGetPipelineIndirectMemoryRequirementsNV

  • VUID-VkComputePipelineIndirectBufferInfoNV-deviceAddress-09012
    deviceAddress must have been allocated from a buffer that was created with usage VK_BUFFER_USAGE_TRANSFER_DST_BIT and VK_BUFFER_USAGE_INDIRECT_BUFFER_BIT

  • VUID-VkComputePipelineIndirectBufferInfoNV-size-09013
    size must be greater than or equal to the VkMemoryRequirements2::size, as returned by vkGetPipelineIndirectMemoryRequirementsNV

  • VUID-VkComputePipelineIndirectBufferInfoNV-pipelineDeviceAddressCaptureReplay-09014
    If pipelineDeviceAddressCaptureReplay is non-zero then the VkPhysicalDeviceDeviceGeneratedCommandsComputeFeaturesNV::deviceGeneratedComputeCaptureReplay feature must be enabled

  • VUID-VkComputePipelineIndirectBufferInfoNV-pipelineDeviceAddressCaptureReplay-09015
    If pipelineDeviceAddressCaptureReplay is non-zero then that address must have been allocated with flag VK_MEMORY_ALLOCATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT set

  • VUID-VkComputePipelineIndirectBufferInfoNV-pipelineDeviceAddressCaptureReplay-09016
    If pipelineDeviceAddressCaptureReplay is non-zero, the pipeline must have been recreated for replay

  • VUID-VkComputePipelineIndirectBufferInfoNV-pipelineDeviceAddressCaptureReplay-09017
    pipelineDeviceAddressCaptureReplay must satisfy the alignment and size requirements similar to deviceAddress

Valid Usage (Implicit)

  • VUID-VkComputePipelineIndirectBufferInfoNV-sType-sType
    sType must be VK_STRUCTURE_TYPE_COMPUTE_PIPELINE_INDIRECT_BUFFER_INFO_NV

To save a compute pipeline’s metadata at a device address call:

// Provided by VK_NV_device_generated_commands_compute
void vkCmdUpdatePipelineIndirectBufferNV(
    VkCommandBuffer                             commandBuffer,
    VkPipelineBindPoint                         pipelineBindPoint,
    VkPipeline                                  pipeline);

  • commandBuffer is the command buffer into which the command will be recorded.

  • pipelineBindPoint is a VkPipelineBindPoint value specifying the type of pipeline whose metadata will be saved.

  • pipeline is the pipeline whose metadata will be saved.

vkCmdUpdatePipelineIndirectBufferNV is only allowed outside of a render pass. This command is treated as a “transfer” operation for the purposes of synchronization barriers. The writes to the address must be synchronized using stages VK_PIPELINE_STAGE_2_COPY_BIT and VK_PIPELINE_STAGE_COMMAND_PREPROCESS_BIT_NV and with access masks VK_ACCESS_MEMORY_WRITE_BIT and VK_ACCESS_COMMAND_PREPROCESS_READ_BIT_NV respectively before using the results in preprocessing.

Valid Usage

  • VUID-vkCmdUpdatePipelineIndirectBufferNV-pipelineBindPoint-09018
    pipelineBindPoint must be VK_PIPELINE_BIND_POINT_COMPUTE

  • VUID-vkCmdUpdatePipelineIndirectBufferNV-pipeline-09019
    pipeline must have been created with VK_PIPELINE_CREATE_INDIRECT_BINDABLE_BIT_NV flag set

  • VUID-vkCmdUpdatePipelineIndirectBufferNV-pipeline-09020
    pipeline must have been created with VkComputePipelineIndirectBufferInfoNV structure specifying a valid address where its metadata will be saved

  • VUID-vkCmdUpdatePipelineIndirectBufferNV-deviceGeneratedComputePipelines-09021
    The VkPhysicalDeviceDeviceGeneratedCommandsComputeFeaturesNV::deviceGeneratedComputePipelines feature must be enabled

Valid Usage (Implicit)

  • VUID-vkCmdUpdatePipelineIndirectBufferNV-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdUpdatePipelineIndirectBufferNV-pipelineBindPoint-parameter
    pipelineBindPoint must be a valid VkPipelineBindPoint value

  • VUID-vkCmdUpdatePipelineIndirectBufferNV-pipeline-parameter
    pipeline must be a valid VkPipeline handle

  • VUID-vkCmdUpdatePipelineIndirectBufferNV-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdUpdatePipelineIndirectBufferNV-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support transfer, graphics, or compute operations

  • VUID-vkCmdUpdatePipelineIndirectBufferNV-renderpass
    This command must only be called outside of a render pass instance

  • VUID-vkCmdUpdatePipelineIndirectBufferNV-videocoding
    This command must only be called outside of a video coding scope

  • VUID-vkCmdUpdatePipelineIndirectBufferNV-commonparent
    Both of commandBuffer, and pipeline must have been created, allocated, or retrieved from the same VkDevice

Host Synchronization

  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Video Coding Scope Supported Queue Types Command Type

Primary
Secondary

Outside

Outside

Transfer
Graphics
Compute

Action

10.3. Graphics Pipelines

Graphics pipelines consist of multiple shader stages, multiple fixed-function pipeline stages, and a pipeline layout.

To create graphics pipelines, call:

// Provided by VK_VERSION_1_0
VkResult vkCreateGraphicsPipelines(
    VkDevice                                    device,
    VkPipelineCache                             pipelineCache,
    uint32_t                                    createInfoCount,
    const VkGraphicsPipelineCreateInfo*         pCreateInfos,
    const VkAllocationCallbacks*                pAllocator,
    VkPipeline*                                 pPipelines);

  • device is the logical device that creates the graphics pipelines.

  • pipelineCache is either VK_NULL_HANDLE, indicating that pipeline caching is disabled; or the handle of a valid pipeline cache object, in which case use of that cache is enabled for the duration of the command.

  • createInfoCount is the length of the pCreateInfos and pPipelines arrays.

  • pCreateInfos is a pointer to an array of VkGraphicsPipelineCreateInfo structures.

  • pAllocator controls host memory allocation as described in the Memory Allocation chapter.

  • pPipelines is a pointer to an array of VkPipeline handles in which the resulting graphics pipeline objects are returned.

The VkGraphicsPipelineCreateInfo structure includes an array of VkPipelineShaderStageCreateInfo structures for each of the desired active shader stages, as well as creation information for all relevant fixed-function stages, and a pipeline layout.

Pipelines are created and returned as described for Multiple Pipeline Creation.

Valid Usage

  • VUID-vkCreateGraphicsPipelines-device-09662
    device must support at least one queue family with the VK_QUEUE_GRAPHICS_BIT capability

  • VUID-vkCreateGraphicsPipelines-flags-00720
    If the flags member of any element of pCreateInfos contains the VK_PIPELINE_CREATE_DERIVATIVE_BIT flag, and the basePipelineIndex member of that same element is not -1, basePipelineIndex must be less than the index into pCreateInfos that corresponds to that element

  • VUID-vkCreateGraphicsPipelines-flags-00721
    If the flags member of any element of pCreateInfos contains the VK_PIPELINE_CREATE_DERIVATIVE_BIT flag, the base pipeline must have been created with the VK_PIPELINE_CREATE_ALLOW_DERIVATIVES_BIT flag set

  • VUID-vkCreateGraphicsPipelines-pipelineCache-02876
    If pipelineCache was created with VK_PIPELINE_CACHE_CREATE_EXTERNALLY_SYNCHRONIZED_BIT, host access to pipelineCache must be externally synchronized

  • VUID-vkCreateGraphicsPipelines-pNext-09616
    If VkPipelineBinaryInfoKHR::binaryCount is not 0 for any element of pCreateInfos, pipelineCache must be VK_NULL_HANDLE

  • VUID-vkCreateGraphicsPipelines-pNext-09617
    If a VkPipelineCreateFlags2CreateInfoKHR structure with the VK_PIPELINE_CREATE_2_CAPTURE_DATA_BIT_KHR flag set is included in the pNext chain of any element of pCreateInfos, pipelineCache must be VK_NULL_HANDLE

  • VUID-vkCreateGraphicsPipelines-binaryCount-09620
    If VkPipelineBinaryInfoKHR::binaryCount is not 0 for any element of pCreateInfos, VK_PIPELINE_CREATION_FEEDBACK_APPLICATION_PIPELINE_CACHE_HIT_BIT must not be set in the flags of that element

  • VUID-vkCreateGraphicsPipelines-binaryCount-09621
    If VkPipelineBinaryInfoKHR::binaryCount is not 0 for any element of pCreateInfos, VK_PIPELINE_CREATION_FEEDBACK_BASE_PIPELINE_ACCELERATION_BIT must not be set in the flags of that element

  • VUID-vkCreateGraphicsPipelines-binaryCount-09622
    If VkPipelineBinaryInfoKHR::binaryCount is not 0 for any element of pCreateInfos, VK_PIPELINE_CREATE_FAIL_ON_PIPELINE_COMPILE_REQUIRED_BIT_EXT must not be set in the flags of that element

Note

An implicit cache may be provided by the implementation or a layer. For this reason, it is still valid to set VK_PIPELINE_CREATE_FAIL_ON_PIPELINE_COMPILE_REQUIRED_BIT on flags for any element of pCreateInfos while passing VK_NULL_HANDLE for pipelineCache.
Valid Usage (Implicit)

  • VUID-vkCreateGraphicsPipelines-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkCreateGraphicsPipelines-pipelineCache-parameter
    If pipelineCache is not VK_NULL_HANDLE, pipelineCache must be a valid VkPipelineCache handle

  • VUID-vkCreateGraphicsPipelines-pCreateInfos-parameter
    pCreateInfos must be a valid pointer to an array of createInfoCount valid VkGraphicsPipelineCreateInfo structures

  • VUID-vkCreateGraphicsPipelines-pAllocator-parameter
    If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure

  • VUID-vkCreateGraphicsPipelines-pPipelines-parameter
    pPipelines must be a valid pointer to an array of createInfoCount VkPipeline handles

  • VUID-vkCreateGraphicsPipelines-createInfoCount-arraylength
    createInfoCount must be greater than 0

  • VUID-vkCreateGraphicsPipelines-pipelineCache-parent
    If pipelineCache is a valid handle, it must have been created, allocated, or retrieved from device

Return Codes
Success

  • VK_SUCCESS

  • VK_PIPELINE_COMPILE_REQUIRED_EXT

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

  • VK_ERROR_INVALID_SHADER_NV

The VkGraphicsPipelineCreateInfo structure is defined as:

// Provided by VK_VERSION_1_0
typedef struct VkGraphicsPipelineCreateInfo {
    VkStructureType                                  sType;
    const void*                                      pNext;
    VkPipelineCreateFlags                            flags;
    uint32_t                                         stageCount;
    const VkPipelineShaderStageCreateInfo*           pStages;
    const VkPipelineVertexInputStateCreateInfo*      pVertexInputState;
    const VkPipelineInputAssemblyStateCreateInfo*    pInputAssemblyState;
    const VkPipelineTessellationStateCreateInfo*     pTessellationState;
    const VkPipelineViewportStateCreateInfo*         pViewportState;
    const VkPipelineRasterizationStateCreateInfo*    pRasterizationState;
    const VkPipelineMultisampleStateCreateInfo*      pMultisampleState;
    const VkPipelineDepthStencilStateCreateInfo*     pDepthStencilState;
    const VkPipelineColorBlendStateCreateInfo*       pColorBlendState;
    const VkPipelineDynamicStateCreateInfo*          pDynamicState;
    VkPipelineLayout                                 layout;
    VkRenderPass                                     renderPass;
    uint32_t                                         subpass;
    VkPipeline                                       basePipelineHandle;
    int32_t                                          basePipelineIndex;
} VkGraphicsPipelineCreateInfo;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • flags is a bitmask of VkPipelineCreateFlagBits specifying how the pipeline will be generated.

  • stageCount is the number of entries in the pStages array.

  • pStages is a pointer to an array of stageCount VkPipelineShaderStageCreateInfo structures describing the set of the shader stages to be included in the graphics pipeline.

  • pVertexInputState is a pointer to a VkPipelineVertexInputStateCreateInfo structure. It is ignored if the pipeline includes a mesh shader stage. It can be NULL if the pipeline is created with the VK_DYNAMIC_STATE_VERTEX_INPUT_EXT dynamic state set.

  • pInputAssemblyState is a pointer to a VkPipelineInputAssemblyStateCreateInfo structure which determines input assembly behavior for vertex shading, as described in Drawing Commands. If the VK_EXT_extended_dynamic_state3 extension is enabled, it can be NULL if the pipeline is created with both VK_DYNAMIC_STATE_PRIMITIVE_RESTART_ENABLE, and VK_DYNAMIC_STATE_PRIMITIVE_TOPOLOGY dynamic states set and dynamicPrimitiveTopologyUnrestricted is VK_TRUE. It is ignored if the pipeline includes a mesh shader stage.

  • pTessellationState is a pointer to a VkPipelineTessellationStateCreateInfo structure defining tessellation state used by tessellation shaders. It can be NULL if the pipeline is created with the VK_DYNAMIC_STATE_PATCH_CONTROL_POINTS_EXT dynamic state set.

  • pViewportState is a pointer to a VkPipelineViewportStateCreateInfo structure defining viewport state used when rasterization is enabled. If the VK_EXT_extended_dynamic_state3 extension is enabled, it can be NULL if the pipeline is created with both VK_DYNAMIC_STATE_VIEWPORT_WITH_COUNT, and VK_DYNAMIC_STATE_SCISSOR_WITH_COUNT dynamic states set.

  • pRasterizationState is a pointer to a VkPipelineRasterizationStateCreateInfo structure defining rasterization state. If the VK_EXT_extended_dynamic_state3 extension is enabled, it can be NULL if the pipeline is created with all of VK_DYNAMIC_STATE_DEPTH_CLAMP_ENABLE_EXT, VK_DYNAMIC_STATE_RASTERIZER_DISCARD_ENABLE, VK_DYNAMIC_STATE_POLYGON_MODE_EXT, VK_DYNAMIC_STATE_CULL_MODE, VK_DYNAMIC_STATE_FRONT_FACE, VK_DYNAMIC_STATE_DEPTH_BIAS_ENABLE, VK_DYNAMIC_STATE_DEPTH_BIAS, and VK_DYNAMIC_STATE_LINE_WIDTH dynamic states set.

  • pMultisampleState is a pointer to a VkPipelineMultisampleStateCreateInfo structure defining multisample state used when rasterization is enabled. If the VK_EXT_extended_dynamic_state3 extension is enabled, it can be NULL if the pipeline is created with all of VK_DYNAMIC_STATE_RASTERIZATION_SAMPLES_EXT, VK_DYNAMIC_STATE_SAMPLE_MASK_EXT, and VK_DYNAMIC_STATE_ALPHA_TO_COVERAGE_ENABLE_EXT dynamic states set, and either alphaToOne is disabled on the device or VK_DYNAMIC_STATE_ALPHA_TO_ONE_ENABLE_EXT is set, in which case VkPipelineMultisampleStateCreateInfo::sampleShadingEnable is assumed to be VK_FALSE.

  • pDepthStencilState is a pointer to a VkPipelineDepthStencilStateCreateInfo structure defining depth/stencil state used when rasterization is enabled for depth or stencil attachments accessed during rendering. If the VK_EXT_extended_dynamic_state3 extension is enabled, it can be NULL if the pipeline is created with all of VK_DYNAMIC_STATE_DEPTH_TEST_ENABLE, VK_DYNAMIC_STATE_DEPTH_WRITE_ENABLE, VK_DYNAMIC_STATE_DEPTH_COMPARE_OP, VK_DYNAMIC_STATE_DEPTH_BOUNDS_TEST_ENABLE, VK_DYNAMIC_STATE_STENCIL_TEST_ENABLE, VK_DYNAMIC_STATE_STENCIL_OP, and VK_DYNAMIC_STATE_DEPTH_BOUNDS dynamic states set.

  • pColorBlendState is a pointer to a VkPipelineColorBlendStateCreateInfo structure defining color blend state used when rasterization is enabled for any color attachments accessed during rendering. If the VK_EXT_extended_dynamic_state3 extension is enabled, it can be NULL if the pipeline is created with all of VK_DYNAMIC_STATE_LOGIC_OP_ENABLE_EXT, VK_DYNAMIC_STATE_LOGIC_OP_EXT, VK_DYNAMIC_STATE_COLOR_BLEND_ENABLE_EXT, VK_DYNAMIC_STATE_COLOR_BLEND_EQUATION_EXT, VK_DYNAMIC_STATE_COLOR_WRITE_MASK_EXT, and VK_DYNAMIC_STATE_BLEND_CONSTANTS dynamic states set.

  • pDynamicState is a pointer to a VkPipelineDynamicStateCreateInfo structure defining which properties of the pipeline state object are dynamic and can be changed independently of the pipeline state. This can be NULL, which means no state in the pipeline is considered dynamic.

  • layout is the description of binding locations used by both the pipeline and descriptor sets used with the pipeline.

  • renderPass is a handle to a render pass object describing the environment in which the pipeline will be used. The pipeline must only be used with a render pass instance compatible with the one provided. See Render Pass Compatibility for more information.

  • subpass is the index of the subpass in the render pass where this pipeline will be used.

  • basePipelineHandle is a pipeline to derive from.

  • basePipelineIndex is an index into the pCreateInfos parameter to use as a pipeline to derive from.

The parameters basePipelineHandle and basePipelineIndex are described in more detail in Pipeline Derivatives.

If any shader stage fails to compile, the compile log will be reported back to the application, and VK_ERROR_INVALID_SHADER_NV will be generated.

Note

With VK_EXT_extended_dynamic_state3, it is possible that many of the VkGraphicsPipelineCreateInfo members above can be NULL because all their state is dynamic and therefore ignored. This is optional so the application can still use a valid pointer if it needs to set the pNext or flags fields to specify state for other extensions.

The state required for a graphics pipeline is divided into vertex input state, pre-rasterization shader state, fragment shader state, and fragment output state.

Vertex Input State

Vertex input state is defined by:

If this pipeline specifies pre-rasterization state either directly or by including it as a pipeline library and its pStages includes a vertex shader, this state must be specified to create a complete graphics pipeline.

If a pipeline includes VK_GRAPHICS_PIPELINE_LIBRARY_VERTEX_INPUT_INTERFACE_BIT_EXT in VkGraphicsPipelineLibraryCreateInfoEXT::flags either explicitly or as a default, and either the conditions requiring this state for a complete graphics pipeline are met or this pipeline does not specify pre-rasterization state in any way, that pipeline must specify this state directly.

Pre-Rasterization Shader State

Pre-rasterization shader state is defined by:

This state must be specified to create a complete graphics pipeline.

If either the pNext chain includes a VkGraphicsPipelineLibraryCreateInfoEXT structure with VK_GRAPHICS_PIPELINE_LIBRARY_PRE_RASTERIZATION_SHADERS_BIT_EXT included in flags, or it is not specified and would default to include that value, this state must be specified in the pipeline.

Fragment Shader State

Fragment shader state is defined by:

If a pipeline specifies pre-rasterization state either directly or by including it as a pipeline library and rasterizerDiscardEnable is set to VK_FALSE or VK_DYNAMIC_STATE_RASTERIZER_DISCARD_ENABLE is used, this state must be specified to create a complete graphics pipeline.

If a pipeline includes VK_GRAPHICS_PIPELINE_LIBRARY_FRAGMENT_SHADER_BIT_EXT in VkGraphicsPipelineLibraryCreateInfoEXT::flags either explicitly or as a default, and either the conditions requiring this state for a complete graphics pipeline are met or this pipeline does not specify pre-rasterization state in any way, that pipeline must specify this state directly.

Fragment Output State

Fragment output state is defined by:

If a pipeline specifies pre-rasterization state either directly or by including it as a pipeline library and rasterizerDiscardEnable is set to VK_FALSE or VK_DYNAMIC_STATE_RASTERIZER_DISCARD_ENABLE is used, this state must be specified to create a complete graphics pipeline.

If a pipeline includes VK_GRAPHICS_PIPELINE_LIBRARY_FRAGMENT_OUTPUT_INTERFACE_BIT_EXT in VkGraphicsPipelineLibraryCreateInfoEXT::flags either explicitly or as a default, and either the conditions requiring this state for a complete graphics pipeline are met or this pipeline does not specify pre-rasterization state in any way, that pipeline must specify this state directly.

Dynamic State

Dynamic state values set via pDynamicState must be ignored if the state they correspond to is not otherwise statically set by one of the state subsets used to create the pipeline. Additionally, setting dynamic state values must not modify whether state in a linked library is static or dynamic; this is set and unchangeable when the library is created. For example, if a pipeline only included pre-rasterization shader state, then any dynamic state value corresponding to depth or stencil testing has no effect. Any linked library that has dynamic state enabled that same dynamic state must also be enabled in all the other linked libraries to which that dynamic state applies.

Complete Graphics Pipelines

A complete graphics pipeline always includes pre-rasterization shader state, with other subsets included depending on that state as specified in the above sections.

Graphics Pipeline Library Layouts

If different subsets are linked together with pipeline layouts created with VK_PIPELINE_LAYOUT_CREATE_INDEPENDENT_SETS_BIT_EXT, the final effective pipeline layout is effectively the union of the linked pipeline layouts. When binding descriptor sets for this pipeline, the pipeline layout used must be compatible with this union. This pipeline layout can be overridden when linking with VK_PIPELINE_CREATE_LINK_TIME_OPTIMIZATION_BIT_EXT by providing a VkPipelineLayout that is compatible with this union other than VK_PIPELINE_LAYOUT_CREATE_INDEPENDENT_SETS_BIT_EXT, or when linking without VK_PIPELINE_CREATE_LINK_TIME_OPTIMIZATION_BIT_EXT by providing a VkPipelineLayout that is fully compatible with this union.

If the pNext chain includes a VkPipelineCreateFlags2CreateInfoKHR structure, VkPipelineCreateFlags2CreateInfoKHR::flags from that structure is used instead of flags from this structure.

Valid Usage

  • VUID-VkGraphicsPipelineCreateInfo-None-09497
    If the pNext chain does not include a VkPipelineCreateFlags2CreateInfoKHR structure, flags must be a valid combination of VkPipelineCreateFlagBits values

  • VUID-VkGraphicsPipelineCreateInfo-flags-07984
    If flags contains the VK_PIPELINE_CREATE_DERIVATIVE_BIT flag, and basePipelineIndex is -1, basePipelineHandle must be a valid graphics VkPipeline handle

  • VUID-VkGraphicsPipelineCreateInfo-flags-07985
    If flags contains the VK_PIPELINE_CREATE_DERIVATIVE_BIT flag, and basePipelineHandle is VK_NULL_HANDLE, basePipelineIndex must be a valid index into the calling command’s pCreateInfos parameter

  • VUID-VkGraphicsPipelineCreateInfo-flags-07986
    If flags contains the VK_PIPELINE_CREATE_DERIVATIVE_BIT flag, basePipelineIndex must be -1 or basePipelineHandle must be VK_NULL_HANDLE

  • VUID-VkGraphicsPipelineCreateInfo-layout-07987
    If a push constant block is declared in a shader, a push constant range in layout must match the shader stage

  • VUID-VkGraphicsPipelineCreateInfo-layout-10069
    If a push constant block is declared in a shader, the block must be contained inside the push constant range in layout that matches the stage

  • VUID-VkGraphicsPipelineCreateInfo-layout-07988
    If a resource variables is declared in a shader, a descriptor slot in layout must match the shader stage

  • VUID-VkGraphicsPipelineCreateInfo-layout-07990
    If a resource variables is declared in a shader, and the descriptor type is not VK_DESCRIPTOR_TYPE_MUTABLE_EXT, a descriptor slot in layout must match the descriptor type

  • VUID-VkGraphicsPipelineCreateInfo-layout-07991
    If a resource variables is declared in a shader as an array, a descriptor slot in layout must match the descriptor count

  • VUID-VkGraphicsPipelineCreateInfo-stage-02096
    If the pipeline requires pre-rasterization shader state the stage member of one element of pStages must be VK_SHADER_STAGE_VERTEX_BIT or VK_SHADER_STAGE_MESH_BIT_EXT

  • VUID-VkGraphicsPipelineCreateInfo-pStages-02095
    If the pipeline requires pre-rasterization shader state the geometric shader stages provided in pStages must be either from the mesh shading pipeline (stage is VK_SHADER_STAGE_TASK_BIT_EXT or VK_SHADER_STAGE_MESH_BIT_EXT) or from the primitive shading pipeline (stage is VK_SHADER_STAGE_VERTEX_BIT, VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT, VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT, or VK_SHADER_STAGE_GEOMETRY_BIT)

  • VUID-VkGraphicsPipelineCreateInfo-pStages-09631
    If the pipeline requires pre-rasterization shader state and pStages contains both VK_SHADER_STAGE_TASK_BIT_EXT and VK_SHADER_STAGE_MESH_BIT_EXT, then the mesh shader’s entry point must not declare a variable with a DrawIndex BuiltIn decoration

  • VUID-VkGraphicsPipelineCreateInfo-TaskNV-07063
    The shader stages for VK_SHADER_STAGE_TASK_BIT_EXT or VK_SHADER_STAGE_MESH_BIT_EXT must use either the TaskNV and MeshNV Execution Model or the TaskEXT and MeshEXT Execution Model, but must not use both

  • VUID-VkGraphicsPipelineCreateInfo-pStages-00729
    If the pipeline requires pre-rasterization shader state and pStages includes a tessellation control shader stage, it must include a tessellation evaluation shader stage

  • VUID-VkGraphicsPipelineCreateInfo-pStages-00730
    If the pipeline requires pre-rasterization shader state and pStages includes a tessellation evaluation shader stage, it must include a tessellation control shader stage

  • VUID-VkGraphicsPipelineCreateInfo-pStages-09022
    If the pipeline requires pre-rasterization shader state and pStages includes a tessellation control shader stage, and the VK_EXT_extended_dynamic_state3 extension is not enabled or the VK_DYNAMIC_STATE_PATCH_CONTROL_POINTS_EXT dynamic state is not set, pTessellationState must be a valid pointer to a valid VkPipelineTessellationStateCreateInfo structure

  • VUID-VkGraphicsPipelineCreateInfo-pTessellationState-09023
    If pTessellationState is not NULL it must be a pointer to a valid VkPipelineTessellationStateCreateInfo structure

  • VUID-VkGraphicsPipelineCreateInfo-pStages-00732
    If the pipeline requires pre-rasterization shader state and pStages includes tessellation shader stages, the shader code of at least one stage must contain an OpExecutionMode instruction specifying the type of subdivision in the pipeline

  • VUID-VkGraphicsPipelineCreateInfo-pStages-00733
    If the pipeline requires pre-rasterization shader state and pStages includes tessellation shader stages, and the shader code of both stages contain an OpExecutionMode instruction specifying the type of subdivision in the pipeline, they must both specify the same subdivision mode

  • VUID-VkGraphicsPipelineCreateInfo-pStages-00734
    If the pipeline requires pre-rasterization shader state and pStages includes tessellation shader stages, the shader code of at least one stage must contain an OpExecutionMode instruction specifying the output patch size in the pipeline

  • VUID-VkGraphicsPipelineCreateInfo-pStages-00735
    If the pipeline requires pre-rasterization shader state and pStages includes tessellation shader stages, and the shader code of both contain an OpExecutionMode instruction specifying the out patch size in the pipeline, they must both specify the same patch size

  • VUID-VkGraphicsPipelineCreateInfo-pStages-08888
    If the pipeline is being created with pre-rasterization shader state and vertex input state and pStages includes tessellation shader stages, and either VK_DYNAMIC_STATE_PRIMITIVE_TOPOLOGY dynamic state is not enabled or dynamicPrimitiveTopologyUnrestricted is VK_FALSE, the topology member of pInputAssembly must be VK_PRIMITIVE_TOPOLOGY_PATCH_LIST

  • VUID-VkGraphicsPipelineCreateInfo-topology-08889
    If the pipeline is being created with pre-rasterization shader state and vertex input state and the topology member of pInputAssembly is VK_PRIMITIVE_TOPOLOGY_PATCH_LIST, and either VK_DYNAMIC_STATE_PRIMITIVE_TOPOLOGY dynamic state is not enabled or dynamicPrimitiveTopologyUnrestricted is VK_FALSE, then pStages must include tessellation shader stages

  • VUID-VkGraphicsPipelineCreateInfo-TessellationEvaluation-07723
    If the pipeline is being created with a TessellationEvaluation Execution Model, no Geometry Execution Model, uses the PointMode Execution Mode, and shaderTessellationAndGeometryPointSize is enabled, a PointSize decorated variable must be written to if maintenance5 is not enabled

  • VUID-VkGraphicsPipelineCreateInfo-topology-08773
    If the pipeline is being created with a Vertex Execution Model and no TessellationEvaluation or Geometry Execution Model, and the topology member of pInputAssembly is VK_PRIMITIVE_TOPOLOGY_POINT_LIST, and either VK_DYNAMIC_STATE_PRIMITIVE_TOPOLOGY dynamic state is not enabled or dynamicPrimitiveTopologyUnrestricted is VK_FALSE, a PointSize decorated variable must be written to if maintenance5 is not enabled

  • VUID-VkGraphicsPipelineCreateInfo-maintenance5-08775
    If maintenance5 is enabled and a PointSize decorated variable is written to, all execution paths must write to a PointSize decorated variable

  • VUID-VkGraphicsPipelineCreateInfo-TessellationEvaluation-07724
    If the pipeline is being created with a TessellationEvaluation Execution Model, no Geometry Execution Model, uses the PointMode Execution Mode, and shaderTessellationAndGeometryPointSize is not enabled, a PointSize decorated variable must not be written to

  • VUID-VkGraphicsPipelineCreateInfo-shaderTessellationAndGeometryPointSize-08776
    If the pipeline is being created with a Geometry Execution Model, uses the OutputPoints Execution Mode, and shaderTessellationAndGeometryPointSize is enabled, a PointSize decorated variable must be written to for every vertex emitted if maintenance5 is not enabled

  • VUID-VkGraphicsPipelineCreateInfo-Geometry-07726
    If the pipeline is being created with a Geometry Execution Model, uses the OutputPoints Execution Mode, and shaderTessellationAndGeometryPointSize is not enabled, a PointSize decorated variable must not be written to

  • VUID-VkGraphicsPipelineCreateInfo-pStages-00738
    If the pipeline requires pre-rasterization shader state and pStages includes a geometry shader stage, and does not include any tessellation shader stages, its shader code must contain an OpExecutionMode instruction specifying an input primitive type that is compatible with the primitive topology specified in pInputAssembly

  • VUID-VkGraphicsPipelineCreateInfo-pStages-00739
    If the pipeline requires pre-rasterization shader state and pStages includes a geometry shader stage, and also includes tessellation shader stages, its shader code must contain an OpExecutionMode instruction specifying an input primitive type that is compatible with the primitive topology that is output by the tessellation stages

  • VUID-VkGraphicsPipelineCreateInfo-pStages-00740
    If the pipeline requires pre-rasterization shader state and fragment shader state, it includes both a fragment shader and a geometry shader, and the fragment shader code reads from an input variable that is decorated with PrimitiveId, then the geometry shader code must write to a matching output variable, decorated with PrimitiveId, in all execution paths

  • VUID-VkGraphicsPipelineCreateInfo-PrimitiveId-06264
    If the pipeline requires pre-rasterization shader state, it includes a mesh shader and the fragment shader code reads from an input variable that is decorated with PrimitiveId, then the mesh shader code must write to a matching output variable, decorated with PrimitiveId, in all execution paths

  • VUID-VkGraphicsPipelineCreateInfo-renderPass-06038
    If renderPass is not VK_NULL_HANDLE and the pipeline is being created with fragment shader state the fragment shader must not read from any input attachment that is defined as VK_ATTACHMENT_UNUSED in subpass

  • VUID-VkGraphicsPipelineCreateInfo-pStages-00742
    If the pipeline requires pre-rasterization shader state and multiple pre-rasterization shader stages are included in pStages, the shader code for the entry points identified by those pStages and the rest of the state identified by this structure must adhere to the pipeline linking rules described in the Shader Interfaces chapter

  • VUID-VkGraphicsPipelineCreateInfo-None-04889
    If the pipeline requires pre-rasterization shader state and fragment shader state, the fragment shader and last pre-rasterization shader stage and any relevant state must adhere to the pipeline linking rules described in the Shader Interfaces chapter

  • VUID-VkGraphicsPipelineCreateInfo-renderPass-06041
    If renderPass is not VK_NULL_HANDLE, and the pipeline is being created with fragment output interface state, then for each color attachment in the subpass, if the potential format features of the format of the corresponding attachment description do not contain VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BLEND_BIT, then the blendEnable member of the corresponding element of the pAttachments member of pColorBlendState must be VK_FALSE

  • VUID-VkGraphicsPipelineCreateInfo-renderPass-07609
    If renderPass is not VK_NULL_HANDLE, the pipeline is being created with fragment output interface state, the pColorBlendState pointer is not NULL, the attachmentCount member of pColorBlendState is not ignored, and the subpass uses color attachments, the attachmentCount member of pColorBlendState must be equal to the colorAttachmentCount used to create subpass

  • VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-04130
    If the pipeline requires pre-rasterization shader state, and pViewportState->pViewports is not dynamic, then pViewportState->pViewports must be a valid pointer to an array of pViewportState->viewportCount valid VkViewport structures

  • VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-04131
    If the pipeline requires pre-rasterization shader state, and pViewportState->pScissors is not dynamic, then pViewportState->pScissors must be a valid pointer to an array of pViewportState->scissorCount VkRect2D structures

  • VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-00749
    If the pipeline requires pre-rasterization shader state, and the wideLines feature is not enabled, and no element of the pDynamicStates member of pDynamicState is VK_DYNAMIC_STATE_LINE_WIDTH, the lineWidth member of pRasterizationState must be 1.0

  • VUID-VkGraphicsPipelineCreateInfo-rasterizerDiscardEnable-09024
    If the pipeline requires pre-rasterization shader state, and the VK_DYNAMIC_STATE_RASTERIZER_DISCARD_ENABLE dynamic state is enabled or the rasterizerDiscardEnable member of pRasterizationState is VK_FALSE, and related dynamic state is not set, pViewportState must be a valid pointer to a valid VkPipelineViewportStateCreateInfo structure

  • VUID-VkGraphicsPipelineCreateInfo-pViewportState-09025
    If pViewportState is not NULL it must be a valid pointer to a valid VkPipelineViewportStateCreateInfo structure

  • VUID-VkGraphicsPipelineCreateInfo-pMultisampleState-09026
    If the pipeline requires fragment output interface state, and the VK_EXT_extended_dynamic_state3 extension is not enabled or any of the VK_DYNAMIC_STATE_RASTERIZATION_SAMPLES_EXT, VK_DYNAMIC_STATE_SAMPLE_MASK_EXT, or VK_DYNAMIC_STATE_ALPHA_TO_COVERAGE_ENABLE_EXT dynamic states is not set, or alphaToOne is enabled on the device and VK_DYNAMIC_STATE_ALPHA_TO_ONE_ENABLE_EXT is not set, pMultisampleState must be a valid pointer to a valid VkPipelineMultisampleStateCreateInfo structure

  • VUID-VkGraphicsPipelineCreateInfo-pMultisampleState-09027
    If pMultisampleState is not NULL it must be a valid pointer to a valid VkPipelineMultisampleStateCreateInfo structure

  • VUID-VkGraphicsPipelineCreateInfo-alphaToCoverageEnable-08891
    If the pipeline is being created with fragment shader state, the VkPipelineMultisampleStateCreateInfo::alphaToCoverageEnable is not ignored and is VK_TRUE, then the Fragment Output Interface must contain a variable for the alpha Component word in Location 0 at Index 0

  • VUID-VkGraphicsPipelineCreateInfo-renderPass-09028
    If renderPass is not VK_NULL_HANDLE, the pipeline is being created with fragment shader state, and subpass uses a depth/stencil attachment, and related dynamic state is not set, pDepthStencilState must be a valid pointer to a valid VkPipelineDepthStencilStateCreateInfo structure

  • VUID-VkGraphicsPipelineCreateInfo-pDepthStencilState-09029
    If pDepthStencilState is not NULL it must be a valid pointer to a valid VkPipelineDepthStencilStateCreateInfo structure

  • VUID-VkGraphicsPipelineCreateInfo-renderPass-09030
    If renderPass is not VK_NULL_HANDLE, the pipeline is being created with fragment output interface state, and subpass uses color attachments, and related dynamic state is not set, pColorBlendState must be a valid pointer to a valid VkPipelineColorBlendStateCreateInfo structure

  • VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-00754
    If the pipeline requires pre-rasterization shader state, the depthBiasClamp feature is not enabled, no element of the pDynamicStates member of pDynamicState is VK_DYNAMIC_STATE_DEPTH_BIAS, and the depthBiasEnable member of pRasterizationState is VK_TRUE, the depthBiasClamp member of pRasterizationState must be 0.0

  • VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-02510
    If the pipeline requires fragment shader state, the VK_EXT_depth_range_unrestricted extension is not enabled and no element of the pDynamicStates member of pDynamicState is VK_DYNAMIC_STATE_DEPTH_BOUNDS, and the depthBoundsTestEnable member of pDepthStencilState is VK_TRUE, the minDepthBounds and maxDepthBounds members of pDepthStencilState must be between 0.0 and 1.0, inclusive

  • VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-07610
    If the pipeline requires fragment shader state or fragment output interface state, and rasterizationSamples and sampleLocationsInfo are not dynamic, and VkPipelineSampleLocationsStateCreateInfoEXT::sampleLocationsEnable included in the pNext chain of pMultisampleState is VK_TRUE, sampleLocationsInfo.sampleLocationGridSize.width must evenly divide VkMultisamplePropertiesEXT::sampleLocationGridSize.width as returned by vkGetPhysicalDeviceMultisamplePropertiesEXT with a samples parameter equaling rasterizationSamples

  • VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-07611
    If the pipeline requires fragment shader state or fragment output interface state, and rasterizationSamples and sampleLocationsInfo are not dynamic, and VkPipelineSampleLocationsStateCreateInfoEXT::sampleLocationsEnable the included in the pNext chain of pMultisampleState is VK_TRUE or VK_DYNAMIC_STATE_SAMPLE_LOCATIONS_ENABLE_EXT is used, sampleLocationsInfo.sampleLocationGridSize.height must evenly divide VkMultisamplePropertiesEXT::sampleLocationGridSize.height as returned by vkGetPhysicalDeviceMultisamplePropertiesEXT with a samples parameter equaling rasterizationSamples

  • VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-07612
    If the pipeline requires fragment shader state or fragment output interface state, and rasterizationSamples and sampleLocationsInfo are not dynamic, and VkPipelineSampleLocationsStateCreateInfoEXT::sampleLocationsEnable included in the pNext chain of pMultisampleState is VK_TRUE or VK_DYNAMIC_STATE_SAMPLE_LOCATIONS_ENABLE_EXT is used, sampleLocationsInfo.sampleLocationsPerPixel must equal rasterizationSamples

  • VUID-VkGraphicsPipelineCreateInfo-sampleLocationsEnable-01524
    If the pipeline requires fragment shader state, and the sampleLocationsEnable member of a VkPipelineSampleLocationsStateCreateInfoEXT structure included in the pNext chain of pMultisampleState is VK_TRUE, the fragment shader code must not statically use the extended instruction InterpolateAtSample

  • VUID-VkGraphicsPipelineCreateInfo-multisampledRenderToSingleSampled-06853
    If the pipeline requires fragment output interface state, and none of the VK_AMD_mixed_attachment_samples extension, the VK_NV_framebuffer_mixed_samples extension, or the multisampledRenderToSingleSampled feature are enabled, rasterizationSamples is not dynamic, and if subpass uses color and/or depth/stencil attachments, then the rasterizationSamples member of pMultisampleState must be the same as the sample count for those subpass attachments

  • VUID-VkGraphicsPipelineCreateInfo-subpass-01505
    If the pipeline requires fragment output interface state, and the VK_AMD_mixed_attachment_samples extension is enabled, rasterizationSamples is not dynamic, and if subpass uses color and/or depth/stencil attachments, then the rasterizationSamples member of pMultisampleState must equal the maximum of the sample counts of those subpass attachments

  • VUID-VkGraphicsPipelineCreateInfo-renderPass-06854
    If renderPass is not VK_NULL_HANDLE, the VK_EXT_multisampled_render_to_single_sampled extension is enabled, rasterizationSamples is not dynamic, and subpass has a VkMultisampledRenderToSingleSampledInfoEXT structure included in the VkSubpassDescription2::pNext chain with multisampledRenderToSingleSampledEnable equal to VK_TRUE, then the rasterizationSamples member of pMultisampleState must be equal to VkMultisampledRenderToSingleSampledInfoEXT::rasterizationSamples

  • VUID-VkGraphicsPipelineCreateInfo-subpass-01411
    If the pipeline requires fragment output interface state, the VK_NV_framebuffer_mixed_samples extension is enabled, rasterizationSamples is not dynamic, and if subpass has a depth/stencil attachment and depth test, stencil test, or depth bounds test are enabled, then the rasterizationSamples member of pMultisampleState must be the same as the sample count of the depth/stencil attachment

  • VUID-VkGraphicsPipelineCreateInfo-subpass-01412
    If the pipeline requires fragment output interface state, the VK_NV_framebuffer_mixed_samples extension is enabled, rasterizationSamples is not dynamic, and if subpass has any color attachments, then the rasterizationSamples member of pMultisampleState must be greater than or equal to the sample count for those subpass attachments

  • VUID-VkGraphicsPipelineCreateInfo-coverageReductionMode-02722
    If the pipeline requires fragment output interface state, the VK_NV_coverage_reduction_mode extension is enabled, and rasterizationSamples is not dynamic, the coverage reduction mode specified by VkPipelineCoverageReductionStateCreateInfoNV::coverageReductionMode, the rasterizationSamples member of pMultisampleState and the sample counts for the color and depth/stencil attachments (if the subpass has them) must be a valid combination returned by vkGetPhysicalDeviceSupportedFramebufferMixedSamplesCombinationsNV

  • VUID-VkGraphicsPipelineCreateInfo-subpass-00758
    If the pipeline requires fragment output interface state, rasterizationSamples is not dynamic, and subpass does not use any color and/or depth/stencil attachments, then the rasterizationSamples member of pMultisampleState must follow the rules for a zero-attachment subpass

  • VUID-VkGraphicsPipelineCreateInfo-renderPass-06046
    If renderPass is not VK_NULL_HANDLE, subpass must be a valid subpass within renderPass

  • VUID-VkGraphicsPipelineCreateInfo-renderPass-06047
    If renderPass is not VK_NULL_HANDLE, the pipeline is being created with pre-rasterization shader state, subpass viewMask is not 0, and multiviewTessellationShader is not enabled, then pStages must not include tessellation shaders

  • VUID-VkGraphicsPipelineCreateInfo-renderPass-06048
    If renderPass is not VK_NULL_HANDLE, the pipeline is being created with pre-rasterization shader state, subpass viewMask is not 0, and multiviewGeometryShader is not enabled, then pStages must not include a geometry shader

  • VUID-VkGraphicsPipelineCreateInfo-renderPass-06050
    If renderPass is not VK_NULL_HANDLE and the pipeline is being created with pre-rasterization shader state, and subpass viewMask is not 0, then all of the shaders in the pipeline must not include variables decorated with the Layer built-in decoration in their interfaces

  • VUID-VkGraphicsPipelineCreateInfo-renderPass-07064
    If renderPass is not VK_NULL_HANDLE, the pipeline is being created with pre-rasterization shader state, subpass viewMask is not 0, and multiviewMeshShader is not enabled, then pStages must not include a mesh shader

  • VUID-VkGraphicsPipelineCreateInfo-flags-00764
    flags must not contain the VK_PIPELINE_CREATE_DISPATCH_BASE flag

  • VUID-VkGraphicsPipelineCreateInfo-pStages-01565
    If the pipeline requires fragment shader state and an input attachment was referenced by an aspectMask at renderPass creation time, the fragment shader must only read from the aspects that were specified for that input attachment

  • VUID-VkGraphicsPipelineCreateInfo-layout-01688
    The number of resources in layout accessible to each shader stage that is used by the pipeline must be less than or equal to VkPhysicalDeviceLimits::maxPerStageResources

  • VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-01715
    If the pipeline requires pre-rasterization shader state, and no element of the pDynamicStates member of pDynamicState is VK_DYNAMIC_STATE_VIEWPORT_W_SCALING_NV, and the viewportWScalingEnable member of a VkPipelineViewportWScalingStateCreateInfoNV structure, included in the pNext chain of pViewportState, is VK_TRUE, the pViewportWScalings member of the VkPipelineViewportWScalingStateCreateInfoNV must be a pointer to an array of VkPipelineViewportWScalingStateCreateInfoNV::viewportCount valid VkViewportWScalingNV structures

  • VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-04056
    If the pipeline requires pre-rasterization shader state, and no element of the pDynamicStates member of pDynamicState is VK_DYNAMIC_STATE_EXCLUSIVE_SCISSOR_NV, and if pViewportState->pNext chain includes a VkPipelineViewportExclusiveScissorStateCreateInfoNV structure, and if its exclusiveScissorCount member is not 0, then its pExclusiveScissors member must be a valid pointer to an array of exclusiveScissorCount VkRect2D structures

  • VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-07854
    If VK_DYNAMIC_STATE_EXCLUSIVE_SCISSOR_ENABLE_NV is included in the pDynamicStates array then the implementation must support at least specVersion 2 of the VK_NV_scissor_exclusive extension

  • VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-04057
    If the pipeline requires pre-rasterization shader state, and no element of the pDynamicStates member of pDynamicState is VK_DYNAMIC_STATE_VIEWPORT_SHADING_RATE_PALETTE_NV, and if pViewportState->pNext chain includes a VkPipelineViewportShadingRateImageStateCreateInfoNV structure, then its pShadingRatePalettes member must be a valid pointer to an array of viewportCount valid VkShadingRatePaletteNV structures

  • VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-04058
    If the pipeline requires pre-rasterization shader state, and no element of the pDynamicStates member of pDynamicState is VK_DYNAMIC_STATE_DISCARD_RECTANGLE_EXT, and if pNext chain includes a VkPipelineDiscardRectangleStateCreateInfoEXT structure, and if its discardRectangleCount member is not 0, then its pDiscardRectangles member must be a valid pointer to an array of discardRectangleCount VkRect2D structures

  • VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-07855
    If VK_DYNAMIC_STATE_DISCARD_RECTANGLE_ENABLE_EXT is included in the pDynamicStates array then the implementation must support at least specVersion 2 of the VK_EXT_discard_rectangles extension

  • VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-07856
    If VK_DYNAMIC_STATE_DISCARD_RECTANGLE_MODE_EXT is included in the pDynamicStates array then the implementation must support at least specVersion 2 of the VK_EXT_discard_rectangles extension

  • VUID-VkGraphicsPipelineCreateInfo-pStages-02097
    If the pipeline requires vertex input state, and pVertexInputState is not dynamic, then pVertexInputState must be a valid pointer to a valid VkPipelineVertexInputStateCreateInfo structure

  • VUID-VkGraphicsPipelineCreateInfo-Input-07904
    If the pipeline is being created with vertex input state and pVertexInputState is not dynamic, then all variables with the Input storage class decorated with Location in the Vertex Execution Model OpEntryPoint must contain a location in VkVertexInputAttributeDescription::location

  • VUID-VkGraphicsPipelineCreateInfo-Input-08733
    If the pipeline requires vertex input state and pVertexInputState is not dynamic, then the numeric type associated with all Input variables of the corresponding Location in the Vertex Execution Model OpEntryPoint must be the same as VkVertexInputAttributeDescription::format

  • VUID-VkGraphicsPipelineCreateInfo-pVertexInputState-08929
    If the pipeline is being created with vertex input state and pVertexInputState is not dynamic, and VkVertexInputAttributeDescription::format has a 64-bit component, then the scalar width associated with all Input variables of the corresponding Location in the Vertex Execution Model OpEntryPoint must be 64-bit

  • VUID-VkGraphicsPipelineCreateInfo-pVertexInputState-08930
    If the pipeline is being created with vertex input state and pVertexInputState is not dynamic, and the scalar width associated with a Location decorated Input variable in the Vertex Execution Model OpEntryPoint is 64-bit, then the corresponding VkVertexInputAttributeDescription::format must have a 64-bit component

  • VUID-VkGraphicsPipelineCreateInfo-pVertexInputState-09198
    If the pipeline is being created with vertex input state and pVertexInputState is not dynamic, and VkVertexInputAttributeDescription::format has a 64-bit component, then all Input variables at the corresponding Location in the Vertex Execution Model OpEntryPoint must not use components that are not present in the format

  • VUID-VkGraphicsPipelineCreateInfo-dynamicPrimitiveTopologyUnrestricted-09031
    If the pipeline requires vertex input state, and related dynamic state is not set, pInputAssemblyState must be a valid pointer to a valid VkPipelineInputAssemblyStateCreateInfo structure

  • VUID-VkGraphicsPipelineCreateInfo-pInputAssemblyState-09032
    If pInputAssemblyState is not NULL it must be a valid pointer to a valid VkPipelineInputAssemblyStateCreateInfo structure

  • VUID-VkGraphicsPipelineCreateInfo-pStages-02317
    If the pipeline requires pre-rasterization shader state, the Xfb execution mode can be specified by no more than one shader stage in pStages

  • VUID-VkGraphicsPipelineCreateInfo-pStages-02318
    If the pipeline requires pre-rasterization shader state, and any shader stage in pStages specifies Xfb execution mode it must be the last pre-rasterization shader stage

  • VUID-VkGraphicsPipelineCreateInfo-rasterizationStream-02319
    If the pipeline requires pre-rasterization shader state, and a VkPipelineRasterizationStateStreamCreateInfoEXT::rasterizationStream value other than zero is specified, all variables in the output interface of the entry point being compiled decorated with Position, PointSize, ClipDistance, or CullDistance must be decorated with identical Stream values that match the rasterizationStream

  • VUID-VkGraphicsPipelineCreateInfo-rasterizationStream-02320
    If the pipeline requires pre-rasterization shader state, and VkPipelineRasterizationStateStreamCreateInfoEXT::rasterizationStream is zero, or not specified, all variables in the output interface of the entry point being compiled decorated with Position, PointSize, ClipDistance, or CullDistance must be decorated with a Stream value of zero, or must not specify the Stream decoration

  • VUID-VkGraphicsPipelineCreateInfo-geometryStreams-02321
    If the pipeline requires pre-rasterization shader state, and the last pre-rasterization shader stage is a geometry shader, and that geometry shader uses the GeometryStreams capability, then VkPhysicalDeviceTransformFeedbackFeaturesEXT::geometryStreams feature must be enabled

  • VUID-VkGraphicsPipelineCreateInfo-None-02322
    If the pipeline requires pre-rasterization shader state, and there are any mesh shader stages in the pipeline there must not be any shader stage in the pipeline with a Xfb execution mode

  • VUID-VkGraphicsPipelineCreateInfo-lineRasterizationMode-02766
    If the pipeline requires pre-rasterization shader state and at least one of fragment output interface state or fragment shader state, and pMultisampleState is not NULL, the lineRasterizationMode member of a VkPipelineRasterizationLineStateCreateInfoKHR structure included in the pNext chain of pRasterizationState is VK_LINE_RASTERIZATION_MODE_BRESENHAM_KHR or VK_LINE_RASTERIZATION_MODE_RECTANGULAR_SMOOTH_KHR, then the alphaToCoverageEnable, alphaToOneEnable, and sampleShadingEnable members of pMultisampleState must all be VK_FALSE

  • VUID-VkGraphicsPipelineCreateInfo-stippledLineEnable-02767
    If the pipeline requires pre-rasterization shader state, the stippledLineEnable member of VkPipelineRasterizationLineStateCreateInfoKHR is VK_TRUE, and no element of the pDynamicStates member of pDynamicState is VK_DYNAMIC_STATE_LINE_STIPPLE_EXT, then the lineStippleFactor member of VkPipelineRasterizationLineStateCreateInfoKHR must be in the range [1,256]

  • VUID-VkGraphicsPipelineCreateInfo-flags-03372
    flags must not include VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_ANY_HIT_SHADERS_BIT_KHR

  • VUID-VkGraphicsPipelineCreateInfo-flags-03373
    flags must not include VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_CLOSEST_HIT_SHADERS_BIT_KHR

  • VUID-VkGraphicsPipelineCreateInfo-flags-03374
    flags must not include VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_MISS_SHADERS_BIT_KHR

  • VUID-VkGraphicsPipelineCreateInfo-flags-03375
    flags must not include VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_INTERSECTION_SHADERS_BIT_KHR

  • VUID-VkGraphicsPipelineCreateInfo-flags-03376
    flags must not include VK_PIPELINE_CREATE_RAY_TRACING_SKIP_TRIANGLES_BIT_KHR

  • VUID-VkGraphicsPipelineCreateInfo-flags-03377
    flags must not include VK_PIPELINE_CREATE_RAY_TRACING_SKIP_AABBS_BIT_KHR

  • VUID-VkGraphicsPipelineCreateInfo-flags-03577
    flags must not include VK_PIPELINE_CREATE_RAY_TRACING_SHADER_GROUP_HANDLE_CAPTURE_REPLAY_BIT_KHR

  • VUID-VkGraphicsPipelineCreateInfo-flags-04947
    flags must not include VK_PIPELINE_CREATE_RAY_TRACING_ALLOW_MOTION_BIT_NV

  • VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-03378
    If the extendedDynamicState feature is not enabled, and the value of VkApplicationInfo::apiVersion used to create the VkInstance is less than Version 1.3 there must be no element of the pDynamicStates member of pDynamicState set to VK_DYNAMIC_STATE_CULL_MODE, VK_DYNAMIC_STATE_FRONT_FACE, VK_DYNAMIC_STATE_PRIMITIVE_TOPOLOGY, VK_DYNAMIC_STATE_VIEWPORT_WITH_COUNT, VK_DYNAMIC_STATE_SCISSOR_WITH_COUNT, VK_DYNAMIC_STATE_VERTEX_INPUT_BINDING_STRIDE, VK_DYNAMIC_STATE_DEPTH_TEST_ENABLE, VK_DYNAMIC_STATE_DEPTH_WRITE_ENABLE, VK_DYNAMIC_STATE_DEPTH_COMPARE_OP, VK_DYNAMIC_STATE_DEPTH_BOUNDS_TEST_ENABLE, VK_DYNAMIC_STATE_STENCIL_TEST_ENABLE, or VK_DYNAMIC_STATE_STENCIL_OP

  • VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-03379
    If the pipeline requires pre-rasterization shader state, and VK_DYNAMIC_STATE_VIEWPORT_WITH_COUNT is included in the pDynamicStates array then viewportCount must be zero

  • VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-03380
    If the pipeline requires pre-rasterization shader state, and VK_DYNAMIC_STATE_SCISSOR_WITH_COUNT is included in the pDynamicStates array then scissorCount must be zero

  • VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-04132
    If the pipeline requires pre-rasterization shader state, and VK_DYNAMIC_STATE_VIEWPORT_WITH_COUNT is included in the pDynamicStates array then VK_DYNAMIC_STATE_VIEWPORT must not be present

  • VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-04133
    If the pipeline requires pre-rasterization shader state, and VK_DYNAMIC_STATE_SCISSOR_WITH_COUNT is included in the pDynamicStates array then VK_DYNAMIC_STATE_SCISSOR must not be present

  • VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-07065
    If the pipeline requires pre-rasterization shader state, and includes a mesh shader, there must be no element of the pDynamicStates member of pDynamicState set to VK_DYNAMIC_STATE_PRIMITIVE_TOPOLOGY, or VK_DYNAMIC_STATE_VERTEX_INPUT_BINDING_STRIDE

  • VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-04868
    If the extendedDynamicState2 feature is not enabled, and the value of VkApplicationInfo::apiVersion used to create the VkInstance is less than Version 1.3 there must be no element of the pDynamicStates member of pDynamicState set to VK_DYNAMIC_STATE_DEPTH_BIAS_ENABLE, VK_DYNAMIC_STATE_PRIMITIVE_RESTART_ENABLE, or VK_DYNAMIC_STATE_RASTERIZER_DISCARD_ENABLE

  • VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-04869
    If the extendedDynamicState2LogicOp feature is not enabled, there must be no element of the pDynamicStates member of pDynamicState set to VK_DYNAMIC_STATE_LOGIC_OP_EXT

  • VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-04870
    If the extendedDynamicState2PatchControlPoints feature is not enabled, there must be no element of the pDynamicStates member of pDynamicState set to VK_DYNAMIC_STATE_PATCH_CONTROL_POINTS_EXT

  • VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-07066
    If the pipeline requires pre-rasterization shader state, and includes a mesh shader, there must be no element of the pDynamicStates member of pDynamicState set to VK_DYNAMIC_STATE_PRIMITIVE_RESTART_ENABLE, or VK_DYNAMIC_STATE_PATCH_CONTROL_POINTS_EXT

  • VUID-VkGraphicsPipelineCreateInfo-flags-02877
    If flags includes VK_PIPELINE_CREATE_INDIRECT_BINDABLE_BIT_NV, then the deviceGeneratedCommands feature must be enabled

  • VUID-VkGraphicsPipelineCreateInfo-flags-02966
    If the pipeline requires pre-rasterization shader state and flags includes VK_PIPELINE_CREATE_INDIRECT_BINDABLE_BIT_NV, then all stages must not specify Xfb execution mode

  • VUID-VkGraphicsPipelineCreateInfo-libraryCount-06648
    If the pipeline is not created with a complete set of state, or VkPipelineLibraryCreateInfoKHR::libraryCount is not 0, VkGraphicsPipelineShaderGroupsCreateInfoNV::groupCount and VkGraphicsPipelineShaderGroupsCreateInfoNV::pipelineCount must be 0

  • VUID-VkGraphicsPipelineCreateInfo-libraryCount-06649
    If the pipeline is created with a complete set of state, and VkPipelineLibraryCreateInfoKHR::libraryCount is 0, and the pNext chain includes an instance of VkGraphicsPipelineShaderGroupsCreateInfoNV, VkGraphicsPipelineShaderGroupsCreateInfoNV::groupCount must be greater than 0

  • VUID-VkGraphicsPipelineCreateInfo-flags-11000
    If flags includes VK_PIPELINE_CREATE_2_INDIRECT_BINDABLE_BIT_EXT, then the deviceGeneratedCommands feature must be enabled

  • VUID-VkGraphicsPipelineCreateInfo-flags-11001
    If the pipeline requires pre-rasterization shader state and flags includes VK_PIPELINE_CREATE_2_INDIRECT_BINDABLE_BIT_EXT, then all stages must not specify Xfb execution mode

  • VUID-VkGraphicsPipelineCreateInfo-pipelineCreationCacheControl-02878
    If the pipelineCreationCacheControl feature is not enabled, flags must not include VK_PIPELINE_CREATE_FAIL_ON_PIPELINE_COMPILE_REQUIRED_BIT or VK_PIPELINE_CREATE_EARLY_RETURN_ON_FAILURE_BIT

  • VUID-VkGraphicsPipelineCreateInfo-pipelineProtectedAccess-07368
    If the pipelineProtectedAccess feature is not enabled, flags must not include VK_PIPELINE_CREATE_NO_PROTECTED_ACCESS_BIT_EXT or VK_PIPELINE_CREATE_PROTECTED_ACCESS_ONLY_BIT_EXT

  • VUID-VkGraphicsPipelineCreateInfo-flags-07369
    flags must not include both VK_PIPELINE_CREATE_NO_PROTECTED_ACCESS_BIT_EXT and VK_PIPELINE_CREATE_PROTECTED_ACCESS_ONLY_BIT_EXT

  • VUID-VkGraphicsPipelineCreateInfo-pDynamicState-04494
    If the pipeline requires pre-rasterization shader state or fragment shader state and VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR is not included in pDynamicState->pDynamicStates, VkPipelineFragmentShadingRateStateCreateInfoKHR::fragmentSize.width must be greater than or equal to 1

  • VUID-VkGraphicsPipelineCreateInfo-pDynamicState-04495
    If the pipeline requires pre-rasterization shader state or fragment shader state and VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR is not included in pDynamicState->pDynamicStates, VkPipelineFragmentShadingRateStateCreateInfoKHR::fragmentSize.height must be greater than or equal to 1

  • VUID-VkGraphicsPipelineCreateInfo-pDynamicState-04496
    If the pipeline requires pre-rasterization shader state or fragment shader state and VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR is not included in pDynamicState->pDynamicStates, VkPipelineFragmentShadingRateStateCreateInfoKHR::fragmentSize.width must be a power-of-two value

  • VUID-VkGraphicsPipelineCreateInfo-pDynamicState-04497
    If the pipeline requires pre-rasterization shader state or fragment shader state and VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR is not included in pDynamicState->pDynamicStates, VkPipelineFragmentShadingRateStateCreateInfoKHR::fragmentSize.height must be a power-of-two value

  • VUID-VkGraphicsPipelineCreateInfo-pDynamicState-04498
    If the pipeline requires pre-rasterization shader state or fragment shader state and VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR is not included in pDynamicState->pDynamicStates, VkPipelineFragmentShadingRateStateCreateInfoKHR::fragmentSize.width must be less than or equal to 4

  • VUID-VkGraphicsPipelineCreateInfo-pDynamicState-04499
    If the pipeline requires pre-rasterization shader state or fragment shader state and VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR is not included in pDynamicState->pDynamicStates, VkPipelineFragmentShadingRateStateCreateInfoKHR::fragmentSize.height must be less than or equal to 4

  • VUID-VkGraphicsPipelineCreateInfo-pDynamicState-04500
    If the pipeline requires pre-rasterization shader state or fragment shader state and VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR is not included in pDynamicState->pDynamicStates, and the pipelineFragmentShadingRate feature is not enabled, VkPipelineFragmentShadingRateStateCreateInfoKHR::fragmentSize.width and VkPipelineFragmentShadingRateStateCreateInfoKHR::fragmentSize.height must both be equal to 1

  • VUID-VkGraphicsPipelineCreateInfo-pDynamicState-06567
    If the pipeline requires pre-rasterization shader state or fragment shader state and VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR is not included in pDynamicState->pDynamicStates, VkPipelineFragmentShadingRateStateCreateInfoKHR::combinerOps[0] must be a valid VkFragmentShadingRateCombinerOpKHR value

  • VUID-VkGraphicsPipelineCreateInfo-pDynamicState-06568
    If the pipeline requires pre-rasterization shader state or fragment shader state and VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR is not included in pDynamicState->pDynamicStates, VkPipelineFragmentShadingRateStateCreateInfoKHR::combinerOps[1] must be a valid VkFragmentShadingRateCombinerOpKHR value

  • VUID-VkGraphicsPipelineCreateInfo-pDynamicState-04501
    If the pipeline requires pre-rasterization shader state or fragment shader state and VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR is not included in pDynamicState->pDynamicStates, and the primitiveFragmentShadingRate feature is not enabled, VkPipelineFragmentShadingRateStateCreateInfoKHR::combinerOps[0] must be VK_FRAGMENT_SHADING_RATE_COMBINER_OP_KEEP_KHR

  • VUID-VkGraphicsPipelineCreateInfo-pDynamicState-04502
    If the pipeline requires pre-rasterization shader state or fragment shader state and VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR is not included in pDynamicState->pDynamicStates, and the attachmentFragmentShadingRate feature is not enabled, VkPipelineFragmentShadingRateStateCreateInfoKHR::combinerOps[1] must be VK_FRAGMENT_SHADING_RATE_COMBINER_OP_KEEP_KHR

  • VUID-VkGraphicsPipelineCreateInfo-primitiveFragmentShadingRateWithMultipleViewports-04503
    If the pipeline requires pre-rasterization shader state and the primitiveFragmentShadingRateWithMultipleViewports limit is not supported, VK_DYNAMIC_STATE_VIEWPORT_WITH_COUNT is not included in pDynamicState->pDynamicStates, and VkPipelineViewportStateCreateInfo::viewportCount is greater than 1, entry points specified in pStages must not write to the PrimitiveShadingRateKHR built-in

  • VUID-VkGraphicsPipelineCreateInfo-primitiveFragmentShadingRateWithMultipleViewports-04504
    If the pipeline requires pre-rasterization shader state and the primitiveFragmentShadingRateWithMultipleViewports limit is not supported, and entry points specified in pStages write to the ViewportIndex built-in, they must not also write to the PrimitiveShadingRateKHR built-in

  • VUID-VkGraphicsPipelineCreateInfo-primitiveFragmentShadingRateWithMultipleViewports-04505
    If the pipeline requires pre-rasterization shader state and the primitiveFragmentShadingRateWithMultipleViewports limit is not supported, and entry points specified in pStages write to the ViewportMaskNV built-in, they must not also write to the PrimitiveShadingRateKHR built-in

  • VUID-VkGraphicsPipelineCreateInfo-fragmentShadingRateNonTrivialCombinerOps-04506
    If the pipeline requires pre-rasterization shader state or fragment shader state, the fragmentShadingRateNonTrivialCombinerOps limit is not supported, and VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR is not included in pDynamicState->pDynamicStates, elements of VkPipelineFragmentShadingRateStateCreateInfoKHR::combinerOps must be VK_FRAGMENT_SHADING_RATE_COMBINER_OP_KEEP_KHR or VK_FRAGMENT_SHADING_RATE_COMBINER_OP_REPLACE_KHR

  • VUID-VkGraphicsPipelineCreateInfo-None-06569
    If the pipeline requires fragment shader state and VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR is not included in pDynamicState->pDynamicStates, VkPipelineFragmentShadingRateEnumStateCreateInfoNV::shadingRateType must be a valid VkFragmentShadingRateTypeNV value

  • VUID-VkGraphicsPipelineCreateInfo-pDynamicState-06570
    If the pipeline requires fragment shader state and VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR is not included in pDynamicState->pDynamicStates, VkPipelineFragmentShadingRateEnumStateCreateInfoNV::shadingRate must be a valid VkFragmentShadingRateNV value

  • VUID-VkGraphicsPipelineCreateInfo-pDynamicState-06571
    If the pipeline requires fragment shader state and VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR is not included in pDynamicState->pDynamicStates, VkPipelineFragmentShadingRateEnumStateCreateInfoNV::combinerOps[0] must be a valid VkFragmentShadingRateCombinerOpKHR value

  • VUID-VkGraphicsPipelineCreateInfo-pDynamicState-06572
    If the pipeline requires fragment shader state and VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR is not included in pDynamicState->pDynamicStates, VkPipelineFragmentShadingRateEnumStateCreateInfoNV::combinerOps[1] must be a valid VkFragmentShadingRateCombinerOpKHR value

  • VUID-VkGraphicsPipelineCreateInfo-pDynamicState-04569
    If the pipeline requires fragment shader state and VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR is not included in pDynamicState->pDynamicStates, and the fragmentShadingRateEnums feature is not enabled, VkPipelineFragmentShadingRateEnumStateCreateInfoNV::shadingRateType must be equal to VK_FRAGMENT_SHADING_RATE_TYPE_FRAGMENT_SIZE_NV

  • VUID-VkGraphicsPipelineCreateInfo-pDynamicState-04570
    If the pipeline requires fragment shader state and VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR is not included in pDynamicState->pDynamicStates, and the pipelineFragmentShadingRate feature is not enabled, VkPipelineFragmentShadingRateEnumStateCreateInfoNV::shadingRate must be equal to VK_FRAGMENT_SHADING_RATE_1_INVOCATION_PER_PIXEL_NV

  • VUID-VkGraphicsPipelineCreateInfo-pDynamicState-04571
    If the pipeline requires fragment shader state and VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR is not included in pDynamicState->pDynamicStates, and the primitiveFragmentShadingRate feature is not enabled, VkPipelineFragmentShadingRateEnumStateCreateInfoNV::combinerOps[0] must be VK_FRAGMENT_SHADING_RATE_COMBINER_OP_KEEP_KHR

  • VUID-VkGraphicsPipelineCreateInfo-pDynamicState-04572
    If the pipeline requires fragment shader state and VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR is not included in pDynamicState->pDynamicStates, and the attachmentFragmentShadingRate feature is not enabled, VkPipelineFragmentShadingRateEnumStateCreateInfoNV::combinerOps[1] must be VK_FRAGMENT_SHADING_RATE_COMBINER_OP_KEEP_KHR

  • VUID-VkGraphicsPipelineCreateInfo-fragmentShadingRateNonTrivialCombinerOps-04573
    If the pipeline requires fragment shader state, and the fragmentShadingRateNonTrivialCombinerOps limit is not supported and VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR is not included in pDynamicState->pDynamicStates, elements of VkPipelineFragmentShadingRateEnumStateCreateInfoNV::combinerOps must be VK_FRAGMENT_SHADING_RATE_COMBINER_OP_KEEP_KHR or VK_FRAGMENT_SHADING_RATE_COMBINER_OP_REPLACE_KHR

  • VUID-VkGraphicsPipelineCreateInfo-None-04574
    If the pipeline requires fragment shader state, and the supersampleFragmentShadingRates feature is not enabled, VkPipelineFragmentShadingRateEnumStateCreateInfoNV::shadingRate must not be equal to VK_FRAGMENT_SHADING_RATE_2_INVOCATIONS_PER_PIXEL_NV, VK_FRAGMENT_SHADING_RATE_4_INVOCATIONS_PER_PIXEL_NV, VK_FRAGMENT_SHADING_RATE_8_INVOCATIONS_PER_PIXEL_NV, or VK_FRAGMENT_SHADING_RATE_16_INVOCATIONS_PER_PIXEL_NV

  • VUID-VkGraphicsPipelineCreateInfo-None-04575
    If the pipeline requires fragment shader state, and the noInvocationFragmentShadingRates feature is not enabled, VkPipelineFragmentShadingRateEnumStateCreateInfoNV::shadingRate must not be equal to VK_FRAGMENT_SHADING_RATE_NO_INVOCATIONS_NV

  • VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-03578
    All elements of the pDynamicStates member of pDynamicState must not be VK_DYNAMIC_STATE_RAY_TRACING_PIPELINE_STACK_SIZE_KHR

  • VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-04807
    If the pipeline requires pre-rasterization shader state and the vertexInputDynamicState feature is not enabled, there must be no element of the pDynamicStates member of pDynamicState set to VK_DYNAMIC_STATE_VERTEX_INPUT_EXT

  • VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-07067
    If the pipeline requires pre-rasterization shader state, and includes a mesh shader, there must be no element of the pDynamicStates member of pDynamicState set to VK_DYNAMIC_STATE_VERTEX_INPUT_EXT

  • VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-04800
    If the colorWriteEnable feature is not enabled, there must be no element of the pDynamicStates member of pDynamicState set to VK_DYNAMIC_STATE_COLOR_WRITE_ENABLE_EXT

  • VUID-VkGraphicsPipelineCreateInfo-rasterizationSamples-04899
    If the pipeline requires fragment shader state, and the VK_QCOM_render_pass_shader_resolve extension is enabled, rasterizationSamples is not dynamic, and if subpass has any input attachments, and if the subpass description contains VK_SUBPASS_DESCRIPTION_FRAGMENT_REGION_BIT_QCOM, then the sample count of the input attachments must equal rasterizationSamples

  • VUID-VkGraphicsPipelineCreateInfo-sampleShadingEnable-04900
    If the pipeline requires fragment shader state, and the VK_QCOM_render_pass_shader_resolve extension is enabled, and if the subpass description contains VK_SUBPASS_DESCRIPTION_FRAGMENT_REGION_BIT_QCOM, then sampleShadingEnable must be false

  • VUID-VkGraphicsPipelineCreateInfo-flags-04901
    If flags includes VK_SUBPASS_DESCRIPTION_SHADER_RESOLVE_BIT_QCOM, then the subpass must be the last subpass in a subpass dependency chain

  • VUID-VkGraphicsPipelineCreateInfo-flags-04902
    If flags includes VK_SUBPASS_DESCRIPTION_SHADER_RESOLVE_BIT_QCOM, and if pResolveAttachments is not NULL, then each resolve attachment must be VK_ATTACHMENT_UNUSED

  • VUID-VkGraphicsPipelineCreateInfo-dynamicRendering-06576
    If the dynamicRendering feature is not enabled and the pipeline requires pre-rasterization shader state, fragment shader state, or fragment output interface state, renderPass must not be VK_NULL_HANDLE

  • VUID-VkGraphicsPipelineCreateInfo-multiview-06577
    If the multiview feature is not enabled, the pipeline requires pre-rasterization shader state, fragment shader state, or fragment output interface state, and renderPass is VK_NULL_HANDLE, VkPipelineRenderingCreateInfo::viewMask must be 0

  • VUID-VkGraphicsPipelineCreateInfo-renderPass-06578
    If the pipeline requires pre-rasterization shader state, fragment shader state, or fragment output interface state, and renderPass is VK_NULL_HANDLE, the index of the most significant bit in VkPipelineRenderingCreateInfo::viewMask must be less than maxMultiviewViewCount

  • VUID-VkGraphicsPipelineCreateInfo-renderPass-06579
    If the pipeline requires fragment output interface state, and renderPass is VK_NULL_HANDLE, and VkPipelineRenderingCreateInfo::colorAttachmentCount is not 0, VkPipelineRenderingCreateInfo::pColorAttachmentFormats must be a valid pointer to an array of colorAttachmentCount valid VkFormat values

  • VUID-VkGraphicsPipelineCreateInfo-renderPass-06580
    If the pipeline requires fragment output interface state, and renderPass is VK_NULL_HANDLE, each element of VkPipelineRenderingCreateInfo::pColorAttachmentFormats must be a valid VkFormat value

  • VUID-VkGraphicsPipelineCreateInfo-renderPass-06582
    If the pipeline requires fragment output interface state, renderPass is VK_NULL_HANDLE, and any element of VkPipelineRenderingCreateInfo::pColorAttachmentFormats is not VK_FORMAT_UNDEFINED, that format must be a format with potential format features that include VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT or VK_FORMAT_FEATURE_2_LINEAR_COLOR_ATTACHMENT_BIT_NV

  • VUID-VkGraphicsPipelineCreateInfo-renderPass-06583
    If the pipeline requires fragment output interface state, and renderPass is VK_NULL_HANDLE, VkPipelineRenderingCreateInfo::depthAttachmentFormat must be a valid VkFormat value

  • VUID-VkGraphicsPipelineCreateInfo-renderPass-06584
    If the pipeline requires fragment output interface state, and renderPass is VK_NULL_HANDLE, VkPipelineRenderingCreateInfo::stencilAttachmentFormat must be a valid VkFormat value

  • VUID-VkGraphicsPipelineCreateInfo-renderPass-06585
    If the pipeline requires fragment output interface state, renderPass is VK_NULL_HANDLE, and VkPipelineRenderingCreateInfo::depthAttachmentFormat is not VK_FORMAT_UNDEFINED, it must be a format with potential format features that include VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT

  • VUID-VkGraphicsPipelineCreateInfo-renderPass-06586
    If the pipeline requires fragment output interface state, renderPass is VK_NULL_HANDLE, and VkPipelineRenderingCreateInfo::stencilAttachmentFormat is not VK_FORMAT_UNDEFINED, it must be a format with potential format features that include VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT

  • VUID-VkGraphicsPipelineCreateInfo-renderPass-06587
    If the pipeline requires fragment output interface state, renderPass is VK_NULL_HANDLE, and VkPipelineRenderingCreateInfo::depthAttachmentFormat is not VK_FORMAT_UNDEFINED, it must be a format that includes a depth component

  • VUID-VkGraphicsPipelineCreateInfo-renderPass-06588
    If the pipeline requires fragment output interface state, renderPass is VK_NULL_HANDLE, and VkPipelineRenderingCreateInfo::stencilAttachmentFormat is not VK_FORMAT_UNDEFINED, it must be a format that includes a stencil component

  • VUID-VkGraphicsPipelineCreateInfo-renderPass-06589
    If the pipeline requires fragment output interface state, renderPass is VK_NULL_HANDLE, VkPipelineRenderingCreateInfo::depthAttachmentFormat is not VK_FORMAT_UNDEFINED, and VkPipelineRenderingCreateInfo::stencilAttachmentFormat is not VK_FORMAT_UNDEFINED, depthAttachmentFormat must equal stencilAttachmentFormat

  • VUID-VkGraphicsPipelineCreateInfo-renderPass-09033
    If renderPass is VK_NULL_HANDLE, the pipeline is being created with fragment shader state and fragment output interface state, and either of VkPipelineRenderingCreateInfo::depthAttachmentFormat or VkPipelineRenderingCreateInfo::stencilAttachmentFormat are not VK_FORMAT_UNDEFINED, and the VK_EXT_extended_dynamic_state3 extension is not enabled or any of the VK_DYNAMIC_STATE_DEPTH_TEST_ENABLE, VK_DYNAMIC_STATE_DEPTH_WRITE_ENABLE, VK_DYNAMIC_STATE_DEPTH_COMPARE_OP, VK_DYNAMIC_STATE_DEPTH_BOUNDS_TEST_ENABLE, VK_DYNAMIC_STATE_STENCIL_TEST_ENABLE, VK_DYNAMIC_STATE_STENCIL_OP, or VK_DYNAMIC_STATE_DEPTH_BOUNDS dynamic states are not set, pDepthStencilState must be a valid pointer to a valid VkPipelineDepthStencilStateCreateInfo structure

  • VUID-VkGraphicsPipelineCreateInfo-pDepthStencilState-09034
    If pDepthStencilState is not NULL it must be a valid pointer to a valid VkPipelineDepthStencilStateCreateInfo structure

  • VUID-VkGraphicsPipelineCreateInfo-renderPass-09035
    If renderPass is VK_NULL_HANDLE and the pipeline is being created with fragment shader state but not fragment output interface state, and the VK_EXT_extended_dynamic_state3 extension is not enabled, or any of the VK_DYNAMIC_STATE_DEPTH_TEST_ENABLE, VK_DYNAMIC_STATE_DEPTH_WRITE_ENABLE, VK_DYNAMIC_STATE_DEPTH_COMPARE_OP, VK_DYNAMIC_STATE_DEPTH_BOUNDS_TEST_ENABLE, VK_DYNAMIC_STATE_STENCIL_TEST_ENABLE, VK_DYNAMIC_STATE_STENCIL_OP, or VK_DYNAMIC_STATE_DEPTH_BOUNDS dynamic states are not set, pDepthStencilState must be a valid pointer to a valid VkPipelineDepthStencilStateCreateInfo structure

  • VUID-VkGraphicsPipelineCreateInfo-pDepthStencilState-09036
    If pDepthStencilState is not NULL it must be a valid pointer to a valid VkPipelineDepthStencilStateCreateInfo structure

  • VUID-VkGraphicsPipelineCreateInfo-renderPass-09037
    If renderPass is VK_NULL_HANDLE, the pipeline is being created with fragment output interface state, and any element of VkPipelineRenderingCreateInfo::pColorAttachmentFormats is not VK_FORMAT_UNDEFINED, and the VK_EXT_extended_dynamic_state3 extension is not enabled, or any of the VK_DYNAMIC_STATE_LOGIC_OP_ENABLE_EXT, VK_DYNAMIC_STATE_LOGIC_OP_EXT, VK_DYNAMIC_STATE_COLOR_BLEND_ENABLE_EXT, VK_DYNAMIC_STATE_COLOR_BLEND_EQUATION_EXT, VK_DYNAMIC_STATE_COLOR_WRITE_MASK_EXT, or VK_DYNAMIC_STATE_BLEND_CONSTANTS dynamic states are not set, pColorBlendState must be a valid pointer to a valid VkPipelineColorBlendStateCreateInfo structure

  • VUID-VkGraphicsPipelineCreateInfo-pColorBlendState-09038
    If pColorBlendState is not NULL it must be a valid pointer to a valid VkPipelineColorBlendStateCreateInfo structure

  • VUID-VkGraphicsPipelineCreateInfo-renderPass-06055
    If renderPass is VK_NULL_HANDLE, pColorBlendState is not dynamic, and the pipeline is being created with fragment output interface state, pColorBlendState->attachmentCount must be equal to VkPipelineRenderingCreateInfo::colorAttachmentCount

  • VUID-VkGraphicsPipelineCreateInfo-renderPass-06057
    If renderPass is VK_NULL_HANDLE, the pipeline is being created with pre-rasterization shader state, VkPipelineRenderingCreateInfo::viewMask is not 0, and the multiviewTessellationShader feature is not enabled, then pStages must not include tessellation shaders

  • VUID-VkGraphicsPipelineCreateInfo-renderPass-06058
    If renderPass is VK_NULL_HANDLE, the pipeline is being created with pre-rasterization shader state, VkPipelineRenderingCreateInfo::viewMask is not 0, and the multiviewGeometryShader feature is not enabled, then pStages must not include a geometry shader

  • VUID-VkGraphicsPipelineCreateInfo-renderPass-06059
    If renderPass is VK_NULL_HANDLE, the pipeline is being created with pre-rasterization shader state, and VkPipelineRenderingCreateInfo::viewMask is not 0, all of the shaders in the pipeline must not include variables decorated with the Layer built-in decoration in their interfaces

  • VUID-VkGraphicsPipelineCreateInfo-renderPass-07720
    If renderPass is VK_NULL_HANDLE, the pipeline is being created with pre-rasterization shader state, and VkPipelineRenderingCreateInfo::viewMask is not 0, and multiviewMeshShader is not enabled, then pStages must not include a mesh shader

  • VUID-VkGraphicsPipelineCreateInfo-renderPass-06061
    If the dynamicRenderingLocalRead feature is not enabled, the pipeline requires fragment shader state, and renderPass is VK_NULL_HANDLE, fragment shaders in pStages must not include the InputAttachment capability

  • VUID-VkGraphicsPipelineCreateInfo-renderPass-08710
    If the pipeline requires fragment shader state and renderPass is not VK_NULL_HANDLE, fragment shaders in pStages must not include any of the TileImageColorReadAccessEXT, TileImageDepthReadAccessEXT, or TileImageStencilReadAccessEXT capabilities

  • VUID-VkGraphicsPipelineCreateInfo-renderPass-06062
    If the pipeline requires fragment output interface state and renderPass is VK_NULL_HANDLE, for each color attachment format defined by the pColorAttachmentFormats member of VkPipelineRenderingCreateInfo, if its potential format features do not contain VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BLEND_BIT, then the blendEnable member of the corresponding element of the pAttachments member of pColorBlendState must be VK_FALSE

  • VUID-VkGraphicsPipelineCreateInfo-renderPass-06063
    If the pipeline requires fragment output interface state and renderPass is VK_NULL_HANDLE, if the pNext chain includes VkAttachmentSampleCountInfoAMD or VkAttachmentSampleCountInfoNV, the colorAttachmentCount member of that structure must be equal to the value of VkPipelineRenderingCreateInfo::colorAttachmentCount

  • VUID-VkGraphicsPipelineCreateInfo-flags-06591
    If pStages includes a fragment shader stage, and the fragment shader declares the EarlyFragmentTests execution mode, the flags member of VkPipelineDepthStencilStateCreateInfo must not include VK_PIPELINE_DEPTH_STENCIL_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_DEPTH_ACCESS_BIT_EXT or VK_PIPELINE_DEPTH_STENCIL_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_STENCIL_ACCESS_BIT_EXT

  • VUID-VkGraphicsPipelineCreateInfo-flags-06482
    If the dynamicRenderingLocalRead feature is not enabled, the pipeline requires fragment output interface state, and the flags member of VkPipelineColorBlendStateCreateInfo includes VK_PIPELINE_COLOR_BLEND_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_ACCESS_BIT_EXT, renderPass must not be VK_NULL_HANDLE

  • VUID-VkGraphicsPipelineCreateInfo-None-09526
    If the dynamicRenderingLocalRead feature is not enabled, the pipeline requires fragment output interface state, and the flags member of VkPipelineDepthStencilStateCreateInfo includes VK_PIPELINE_DEPTH_STENCIL_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_DEPTH_ACCESS_BIT_EXT or VK_PIPELINE_DEPTH_STENCIL_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_STENCIL_ACCESS_BIT_EXT, renderPass must not be VK_NULL_HANDLE

  • VUID-VkGraphicsPipelineCreateInfo-pColorAttachmentSamples-06592
    If the fragment output interface state, elements of the pColorAttachmentSamples member of VkAttachmentSampleCountInfoAMD or VkAttachmentSampleCountInfoNV must be valid VkSampleCountFlagBits values

  • VUID-VkGraphicsPipelineCreateInfo-depthStencilAttachmentSamples-06593
    If the fragment output interface state and the depthStencilAttachmentSamples member of VkAttachmentSampleCountInfoAMD or VkAttachmentSampleCountInfoNV is not 0, it must be a valid VkSampleCountFlagBits value

  • VUID-VkGraphicsPipelineCreateInfo-renderPass-09527
    If the pipeline requires fragment output interface state, renderPass is not VK_NULL_HANDLE, and the flags member of VkPipelineColorBlendStateCreateInfo includes VK_PIPELINE_COLOR_BLEND_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_ACCESS_BIT_EXT subpass must have been created with VK_SUBPASS_DESCRIPTION_RASTERIZATION_ORDER_ATTACHMENT_COLOR_ACCESS_BIT_EXT

  • VUID-VkGraphicsPipelineCreateInfo-renderPass-09528
    If the pipeline requires fragment shader state, renderPass is not VK_NULL_HANDLE, and the flags member of VkPipelineDepthStencilStateCreateInfo includes VK_PIPELINE_DEPTH_STENCIL_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_DEPTH_ACCESS_BIT_EXT, subpass must have been created with VK_SUBPASS_DESCRIPTION_RASTERIZATION_ORDER_ATTACHMENT_DEPTH_ACCESS_BIT_EXT

  • VUID-VkGraphicsPipelineCreateInfo-renderPass-09529
    If the pipeline requires fragment shader state, renderPass is not VK_NULL_HANDLE, and the flags member of VkPipelineDepthStencilStateCreateInfo includes VK_PIPELINE_DEPTH_STENCIL_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_STENCIL_ACCESS_BIT_EXT, subpass must have been created with VK_SUBPASS_DESCRIPTION_RASTERIZATION_ORDER_ATTACHMENT_STENCIL_ACCESS_BIT_EXT

  • VUID-VkGraphicsPipelineCreateInfo-pipelineStageCreationFeedbackCount-06594
    If VkPipelineCreationFeedbackCreateInfo::pipelineStageCreationFeedbackCount is not 0, it must be equal to stageCount

  • VUID-VkGraphicsPipelineCreateInfo-renderPass-06595
    If renderPass is VK_NULL_HANDLE, the pipeline is being created with pre-rasterization shader state or fragment shader state, and VkMultiviewPerViewAttributesInfoNVX::perViewAttributesPositionXOnly is VK_TRUE then VkMultiviewPerViewAttributesInfoNVX::perViewAttributes must also be VK_TRUE

  • VUID-VkGraphicsPipelineCreateInfo-flags-06596
    If VkGraphicsPipelineLibraryCreateInfoEXT::flags includes only one of VK_GRAPHICS_PIPELINE_LIBRARY_PRE_RASTERIZATION_SHADERS_BIT_EXT or VK_GRAPHICS_PIPELINE_LIBRARY_FRAGMENT_SHADER_BIT_EXT, and an element of VkPipelineLibraryCreateInfoKHR::pLibraries includes the other flag, the value of VkMultiviewPerViewAttributesInfoNVX::perViewAttributes specified in both this pipeline and the library must be equal

  • VUID-VkGraphicsPipelineCreateInfo-pLibraries-06597
    If one element of VkPipelineLibraryCreateInfoKHR::pLibraries includes VK_GRAPHICS_PIPELINE_LIBRARY_PRE_RASTERIZATION_SHADERS_BIT_EXT and another element includes VK_GRAPHICS_PIPELINE_LIBRARY_FRAGMENT_SHADER_BIT_EXT, the value of VkMultiviewPerViewAttributesInfoNVX::perViewAttributes specified in both libraries must be equal

  • VUID-VkGraphicsPipelineCreateInfo-flags-06598
    If VkGraphicsPipelineLibraryCreateInfoEXT::flags includes only one of VK_GRAPHICS_PIPELINE_LIBRARY_PRE_RASTERIZATION_SHADERS_BIT_EXT or VK_GRAPHICS_PIPELINE_LIBRARY_FRAGMENT_SHADER_BIT_EXT, and an element of VkPipelineLibraryCreateInfoKHR::pLibraries includes the other flag, the value of VkMultiviewPerViewAttributesInfoNVX::perViewAttributesPositionXOnly specified in both this pipeline and the library must be equal

  • VUID-VkGraphicsPipelineCreateInfo-pLibraries-06599
    If one element of VkPipelineLibraryCreateInfoKHR::pLibraries includes VK_GRAPHICS_PIPELINE_LIBRARY_PRE_RASTERIZATION_SHADERS_BIT_EXT and another element includes VK_GRAPHICS_PIPELINE_LIBRARY_FRAGMENT_SHADER_BIT_EXT, the value of VkMultiviewPerViewAttributesInfoNVX::perViewAttributesPositionXOnly specified in both libraries must be equal

  • VUID-VkGraphicsPipelineCreateInfo-pStages-06600
    If the pipeline requires pre-rasterization shader state or fragment shader state, pStages must be a valid pointer to an array of stageCount valid VkPipelineShaderStageCreateInfo structures

  • VUID-VkGraphicsPipelineCreateInfo-stageCount-09587
    If the pipeline does not require pre-rasterization shader state or fragment shader state, stageCount must be zero

  • VUID-VkGraphicsPipelineCreateInfo-pRasterizationState-06601
    If the pipeline requires pre-rasterization shader state, and related dynamic state is not set, pRasterizationState must be a valid pointer to a valid VkPipelineRasterizationStateCreateInfo structure

  • VUID-VkGraphicsPipelineCreateInfo-pRasterizationState-09039
    If VkGraphicsPipelineLibraryCreateInfoEXT::flags includes VK_GRAPHICS_PIPELINE_LIBRARY_PRE_RASTERIZATION_SHADERS_BIT_EXT, and related dynamic state is not set, then pMultisampleState must be a valid pointer to a valid VkPipelineMultisampleStateCreateInfo structure

  • VUID-VkGraphicsPipelineCreateInfo-pRasterizationState-09040
    If pRasterizationState is not NULL it must be a valid pointer to a valid VkPipelineRasterizationStateCreateInfo structure

  • VUID-VkGraphicsPipelineCreateInfo-layout-06602
    If the pipeline requires fragment shader state or pre-rasterization shader state, layout must be a valid VkPipelineLayout handle

  • VUID-VkGraphicsPipelineCreateInfo-renderPass-06603
    If the pipeline requires pre-rasterization shader state, fragment shader state, or fragment output state, and renderPass is not VK_NULL_HANDLE, renderPass must be a valid VkRenderPass handle

  • VUID-VkGraphicsPipelineCreateInfo-stageCount-09530
    If the pipeline requires pre-rasterization shader state, stageCount must be greater than 0

  • VUID-VkGraphicsPipelineCreateInfo-graphicsPipelineLibrary-06606
    If the graphicsPipelineLibrary feature is not enabled, flags must not include VK_PIPELINE_CREATE_LIBRARY_BIT_KHR

  • VUID-VkGraphicsPipelineCreateInfo-flags-06608
    If the pipeline defines, or includes as libraries, all the state subsets required for a complete graphics pipeline, flags must not include VK_PIPELINE_CREATE_LIBRARY_BIT_KHR

  • VUID-VkGraphicsPipelineCreateInfo-flags-06609
    If flags includes VK_PIPELINE_CREATE_LINK_TIME_OPTIMIZATION_BIT_EXT, pipeline libraries included via VkPipelineLibraryCreateInfoKHR must have been created with VK_PIPELINE_CREATE_RETAIN_LINK_TIME_OPTIMIZATION_INFO_BIT_EXT

  • VUID-VkGraphicsPipelineCreateInfo-flags-09245
    If flags includes VK_PIPELINE_CREATE_RETAIN_LINK_TIME_OPTIMIZATION_INFO_BIT_EXT, flags must also include VK_PIPELINE_CREATE_LIBRARY_BIT_KHR

  • VUID-VkGraphicsPipelineCreateInfo-flags-06610
    If flags includes VK_PIPELINE_CREATE_RETAIN_LINK_TIME_OPTIMIZATION_INFO_BIT_EXT, pipeline libraries included via VkPipelineLibraryCreateInfoKHR must have been created with VK_PIPELINE_CREATE_RETAIN_LINK_TIME_OPTIMIZATION_INFO_BIT_EXT

  • VUID-VkGraphicsPipelineCreateInfo-pLibraries-06611
    Any pipeline libraries included via VkPipelineLibraryCreateInfoKHR::pLibraries must not include any state subset already defined by this structure or defined by any other pipeline library in VkPipelineLibraryCreateInfoKHR::pLibraries

  • VUID-VkGraphicsPipelineCreateInfo-flags-06612
    If VkGraphicsPipelineLibraryCreateInfoEXT::flags includes only one of VK_GRAPHICS_PIPELINE_LIBRARY_PRE_RASTERIZATION_SHADERS_BIT_EXT or VK_GRAPHICS_PIPELINE_LIBRARY_FRAGMENT_SHADER_BIT_EXT, and an element of VkPipelineLibraryCreateInfoKHR::pLibraries includes the other flag, and layout was not created with VK_PIPELINE_LAYOUT_CREATE_INDEPENDENT_SETS_BIT_EXT, then the layout used by this pipeline and the library must be identically defined

  • VUID-VkGraphicsPipelineCreateInfo-pLibraries-06613
    If one element of VkPipelineLibraryCreateInfoKHR::pLibraries includes VK_GRAPHICS_PIPELINE_LIBRARY_PRE_RASTERIZATION_SHADERS_BIT_EXT and another element includes VK_GRAPHICS_PIPELINE_LIBRARY_FRAGMENT_SHADER_BIT_EXT, and the layout specified by either library was not created with VK_PIPELINE_LAYOUT_CREATE_INDEPENDENT_SETS_BIT_EXT, then the layout used by each library must be identically defined

  • VUID-VkGraphicsPipelineCreateInfo-flags-06614
    If VkGraphicsPipelineLibraryCreateInfoEXT::flags includes only one of VK_GRAPHICS_PIPELINE_LIBRARY_PRE_RASTERIZATION_SHADERS_BIT_EXT or VK_GRAPHICS_PIPELINE_LIBRARY_FRAGMENT_SHADER_BIT_EXT, an element of VkPipelineLibraryCreateInfoKHR::pLibraries includes the other subset, and layout was created with VK_PIPELINE_LAYOUT_CREATE_INDEPENDENT_SETS_BIT_EXT, then the layout used by the library must also have been created with VK_PIPELINE_LAYOUT_CREATE_INDEPENDENT_SETS_BIT_EXT

  • VUID-VkGraphicsPipelineCreateInfo-pLibraries-06615
    If one element of VkPipelineLibraryCreateInfoKHR::pLibraries includes VK_GRAPHICS_PIPELINE_LIBRARY_PRE_RASTERIZATION_SHADERS_BIT_EXT and another element includes VK_GRAPHICS_PIPELINE_LIBRARY_FRAGMENT_SHADER_BIT_EXT, and the layout specified by either library was created with VK_PIPELINE_LAYOUT_CREATE_INDEPENDENT_SETS_BIT_EXT, then the layout used by both libraries must have been created with VK_PIPELINE_LAYOUT_CREATE_INDEPENDENT_SETS_BIT_EXT

  • VUID-VkGraphicsPipelineCreateInfo-flags-06616
    If VkGraphicsPipelineLibraryCreateInfoEXT::flags includes only one of VK_GRAPHICS_PIPELINE_LIBRARY_PRE_RASTERIZATION_SHADERS_BIT_EXT or VK_GRAPHICS_PIPELINE_LIBRARY_FRAGMENT_SHADER_BIT_EXT, an element of VkPipelineLibraryCreateInfoKHR::pLibraries includes the other subset, and layout was created with VK_PIPELINE_LAYOUT_CREATE_INDEPENDENT_SETS_BIT_EXT, elements of the pSetLayouts array which layout was created with that are not VK_NULL_HANDLE must be identically defined to the element at the same index of pSetLayouts used to create the library’s layout

  • VUID-VkGraphicsPipelineCreateInfo-pLibraries-06617
    If one element of VkPipelineLibraryCreateInfoKHR::pLibraries includes VK_GRAPHICS_PIPELINE_LIBRARY_PRE_RASTERIZATION_SHADERS_BIT_EXT and another element includes VK_GRAPHICS_PIPELINE_LIBRARY_FRAGMENT_SHADER_BIT_EXT, and the layout specified by either library was created with VK_PIPELINE_LAYOUT_CREATE_INDEPENDENT_SETS_BIT_EXT, elements of the pSetLayouts array which either layout was created with that are not VK_NULL_HANDLE must be identically defined to the element at the same index of pSetLayouts used to create the other library’s layout

  • VUID-VkGraphicsPipelineCreateInfo-flags-06618
    If VkGraphicsPipelineLibraryCreateInfoEXT::flags includes only one of VK_GRAPHICS_PIPELINE_LIBRARY_PRE_RASTERIZATION_SHADERS_BIT_EXT or VK_GRAPHICS_PIPELINE_LIBRARY_FRAGMENT_SHADER_BIT_EXT, and an element of VkPipelineLibraryCreateInfoKHR::pLibraries includes the other flag, any descriptor set layout N specified by layout in both this pipeline and the library which include bindings accessed by shader stages in each must be identically defined

  • VUID-VkGraphicsPipelineCreateInfo-pLibraries-06619
    If one element of VkPipelineLibraryCreateInfoKHR::pLibraries includes VK_GRAPHICS_PIPELINE_LIBRARY_PRE_RASTERIZATION_SHADERS_BIT_EXT and another element includes VK_GRAPHICS_PIPELINE_LIBRARY_FRAGMENT_SHADER_BIT_EXT, any descriptor set layout N specified by layout in both libraries which include bindings accessed by shader stages in each must be identically defined

  • VUID-VkGraphicsPipelineCreateInfo-flags-06620
    If VkGraphicsPipelineLibraryCreateInfoEXT::flags includes only one of VK_GRAPHICS_PIPELINE_LIBRARY_PRE_RASTERIZATION_SHADERS_BIT_EXT or VK_GRAPHICS_PIPELINE_LIBRARY_FRAGMENT_SHADER_BIT_EXT, and an element of VkPipelineLibraryCreateInfoKHR::pLibraries includes the other flag, push constants specified in layout in both this pipeline and the library which are available to shader stages in each must be identically defined

  • VUID-VkGraphicsPipelineCreateInfo-pLibraries-06621
    If one element of VkPipelineLibraryCreateInfoKHR::pLibraries includes VK_GRAPHICS_PIPELINE_LIBRARY_PRE_RASTERIZATION_SHADERS_BIT_EXT and another element includes VK_GRAPHICS_PIPELINE_LIBRARY_FRAGMENT_SHADER_BIT_EXT, push constants specified in layout in both this pipeline and the library which are available to shader stages in each must be identically defined

  • VUID-VkGraphicsPipelineCreateInfo-flags-06679
    If VkGraphicsPipelineLibraryCreateInfoEXT::flags includes only one of VK_GRAPHICS_PIPELINE_LIBRARY_PRE_RASTERIZATION_SHADERS_BIT_EXT or VK_GRAPHICS_PIPELINE_LIBRARY_FRAGMENT_SHADER_BIT_EXT, an element of VkPipelineLibraryCreateInfoKHR::pLibraries includes the other subset, any element of the pSetLayouts array when layout was created and the corresponding element of the pSetLayouts array used to create the library’s layout must not both be VK_NULL_HANDLE

  • VUID-VkGraphicsPipelineCreateInfo-pLibraries-06681
    If one element of VkPipelineLibraryCreateInfoKHR::pLibraries includes VK_GRAPHICS_PIPELINE_LIBRARY_PRE_RASTERIZATION_SHADERS_BIT_EXT and another element includes VK_GRAPHICS_PIPELINE_LIBRARY_FRAGMENT_SHADER_BIT_EXT, and any element of the pSetLayouts array used to create each library’s layout was VK_NULL_HANDLE, then the corresponding element of the pSetLayouts array used to create the other library’s layout must not be VK_NULL_HANDLE

  • VUID-VkGraphicsPipelineCreateInfo-flags-06756
    If VkGraphicsPipelineLibraryCreateInfoEXT::flags includes only one of VK_GRAPHICS_PIPELINE_LIBRARY_PRE_RASTERIZATION_SHADERS_BIT_EXT or VK_GRAPHICS_PIPELINE_LIBRARY_FRAGMENT_SHADER_BIT_EXT, an element of VkPipelineLibraryCreateInfoKHR::pLibraries includes the other subset, and any element of the pSetLayouts array which layout was created with was VK_NULL_HANDLE, then the corresponding element of the pSetLayouts array used to create the library’s layout must not have shader bindings for shaders in the other subset

  • VUID-VkGraphicsPipelineCreateInfo-flags-06757
    If VkGraphicsPipelineLibraryCreateInfoEXT::flags includes only one of VK_GRAPHICS_PIPELINE_LIBRARY_PRE_RASTERIZATION_SHADERS_BIT_EXT or VK_GRAPHICS_PIPELINE_LIBRARY_FRAGMENT_SHADER_BIT_EXT, an element of VkPipelineLibraryCreateInfoKHR::pLibraries includes the other subset, and any element of the pSetLayouts array used to create the library’s layout was VK_NULL_HANDLE, then the corresponding element of the pSetLayouts array used to create this pipeline’s layout must not have shader bindings for shaders in the other subset

  • VUID-VkGraphicsPipelineCreateInfo-pLibraries-06758
    If one element of VkPipelineLibraryCreateInfoKHR::pLibraries includes VK_GRAPHICS_PIPELINE_LIBRARY_PRE_RASTERIZATION_SHADERS_BIT_EXT and another element includes VK_GRAPHICS_PIPELINE_LIBRARY_FRAGMENT_SHADER_BIT_EXT, and any element of the pSetLayouts array used to create each library’s layout was VK_NULL_HANDLE, then the corresponding element of the pSetLayouts array used to create the other library’s layout must not have shader bindings for shaders in the other subset

  • VUID-VkGraphicsPipelineCreateInfo-flags-06682
    If VkGraphicsPipelineLibraryCreateInfoEXT::flags includes both VK_GRAPHICS_PIPELINE_LIBRARY_PRE_RASTERIZATION_SHADERS_BIT_EXT and VK_GRAPHICS_PIPELINE_LIBRARY_FRAGMENT_SHADER_BIT_EXT, layout must have been created with no elements of the pSetLayouts array set to VK_NULL_HANDLE

  • VUID-VkGraphicsPipelineCreateInfo-flags-06683
    If VkGraphicsPipelineLibraryCreateInfoEXT::flags includes VK_GRAPHICS_PIPELINE_LIBRARY_PRE_RASTERIZATION_SHADERS_BIT_EXT and pRasterizationState->rasterizerDiscardEnable is VK_TRUE, layout must have been created with no elements of the pSetLayouts array set to VK_NULL_HANDLE

  • VUID-VkGraphicsPipelineCreateInfo-flags-06684
    If VkGraphicsPipelineLibraryCreateInfoEXT::flags includes at least one of and no more than two of VK_GRAPHICS_PIPELINE_LIBRARY_PRE_RASTERIZATION_SHADERS_BIT_EXT, VK_GRAPHICS_PIPELINE_LIBRARY_FRAGMENT_SHADER_BIT_EXT, or VK_GRAPHICS_PIPELINE_LIBRARY_FRAGMENT_OUTPUT_INTERFACE_BIT_EXT, and an element of VkPipelineLibraryCreateInfoKHR::pLibraries includes one of the other flags, the value of subpass must be equal to that used to create the library

  • VUID-VkGraphicsPipelineCreateInfo-pLibraries-06623
    If one element of VkPipelineLibraryCreateInfoKHR::pLibraries includes at least one of and no more than two of VK_GRAPHICS_PIPELINE_LIBRARY_PRE_RASTERIZATION_SHADERS_BIT_EXT, VK_GRAPHICS_PIPELINE_LIBRARY_FRAGMENT_SHADER_BIT_EXT, or VK_GRAPHICS_PIPELINE_LIBRARY_FRAGMENT_OUTPUT_INTERFACE_BIT_EXT, and another element of VkPipelineLibraryCreateInfoKHR::pLibraries includes one of the other flags, the value of subpass used to create each library must be identical

  • VUID-VkGraphicsPipelineCreateInfo-renderpass-06624
    If renderpass is not VK_NULL_HANDLE, VkGraphicsPipelineLibraryCreateInfoEXT::flags includes at least one of and no more than two of VK_GRAPHICS_PIPELINE_LIBRARY_PRE_RASTERIZATION_SHADERS_BIT_EXT, VK_GRAPHICS_PIPELINE_LIBRARY_FRAGMENT_SHADER_BIT_EXT, or VK_GRAPHICS_PIPELINE_LIBRARY_FRAGMENT_OUTPUT_INTERFACE_BIT_EXT, and an element of VkPipelineLibraryCreateInfoKHR::pLibraries includes one of the other flags, renderPass must be compatible with that used to create the library

  • VUID-VkGraphicsPipelineCreateInfo-renderpass-06625
    If renderpass is VK_NULL_HANDLE, VkGraphicsPipelineLibraryCreateInfoEXT::flags includes at least one of and no more than two of VK_GRAPHICS_PIPELINE_LIBRARY_PRE_RASTERIZATION_SHADERS_BIT_EXT, VK_GRAPHICS_PIPELINE_LIBRARY_FRAGMENT_SHADER_BIT_EXT, or VK_GRAPHICS_PIPELINE_LIBRARY_FRAGMENT_OUTPUT_INTERFACE_BIT_EXT, and an element of VkPipelineLibraryCreateInfoKHR::pLibraries includes one of the other flags, the value of renderPass used to create that library must also be VK_NULL_HANDLE

  • VUID-VkGraphicsPipelineCreateInfo-flags-06626
    If VkGraphicsPipelineLibraryCreateInfoEXT::flags includes at least one of and no more than two of VK_GRAPHICS_PIPELINE_LIBRARY_PRE_RASTERIZATION_SHADERS_BIT_EXT, VK_GRAPHICS_PIPELINE_LIBRARY_FRAGMENT_SHADER_BIT_EXT, or VK_GRAPHICS_PIPELINE_LIBRARY_FRAGMENT_OUTPUT_INTERFACE_BIT_EXT, an element of VkPipelineLibraryCreateInfoKHR::pLibraries includes one of the other flags, and renderPass is VK_NULL_HANDLE, the value of VkPipelineRenderingCreateInfo::viewMask used by this pipeline and that specified by the library must be identical

  • VUID-VkGraphicsPipelineCreateInfo-pLibraries-06627
    If one element of VkPipelineLibraryCreateInfoKHR::pLibraries includes at least one of and no more than two of VK_GRAPHICS_PIPELINE_LIBRARY_PRE_RASTERIZATION_SHADERS_BIT_EXT, VK_GRAPHICS_PIPELINE_LIBRARY_FRAGMENT_SHADER_BIT_EXT, or VK_GRAPHICS_PIPELINE_LIBRARY_FRAGMENT_OUTPUT_INTERFACE_BIT_EXT, another element of VkPipelineLibraryCreateInfoKHR::pLibraries includes one of the other flags, and renderPass was VK_NULL_HANDLE for both libraries, the value of VkPipelineRenderingCreateInfo::viewMask set by each library must be identical

  • VUID-VkGraphicsPipelineCreateInfo-pLibraries-06628
    If one element of VkPipelineLibraryCreateInfoKHR::pLibraries includes at least one of and no more than two of VK_GRAPHICS_PIPELINE_LIBRARY_PRE_RASTERIZATION_SHADERS_BIT_EXT, VK_GRAPHICS_PIPELINE_LIBRARY_FRAGMENT_SHADER_BIT_EXT, or VK_GRAPHICS_PIPELINE_LIBRARY_FRAGMENT_OUTPUT_INTERFACE_BIT_EXT, and another element of VkPipelineLibraryCreateInfoKHR::pLibraries includes one of the other flags, the renderPass objects used to create each library must be compatible or all equal to VK_NULL_HANDLE

  • VUID-VkGraphicsPipelineCreateInfo-renderpass-06631
    If renderPass is not VK_NULL_HANDLE, the pipeline requires fragment shader state, and the VK_EXT_extended_dynamic_state3 extension is not enabled or any of the VK_DYNAMIC_STATE_RASTERIZATION_SAMPLES_EXT, VK_DYNAMIC_STATE_SAMPLE_MASK_EXT, or VK_DYNAMIC_STATE_ALPHA_TO_COVERAGE_ENABLE_EXT dynamic states is not set, or alphaToOne is enabled on the device and VK_DYNAMIC_STATE_ALPHA_TO_ONE_ENABLE_EXT is not set, then pMultisampleState must be a valid pointer to a valid VkPipelineMultisampleStateCreateInfo structure

  • VUID-VkGraphicsPipelineCreateInfo-Input-06632
    If the pipeline requires fragment shader state with a fragment shader that either enables sample shading or decorates any variable in the Input storage class with Sample, and the VK_EXT_extended_dynamic_state3 extension is not enabled or any of the VK_DYNAMIC_STATE_RASTERIZATION_SAMPLES_EXT, VK_DYNAMIC_STATE_SAMPLE_MASK_EXT, or VK_DYNAMIC_STATE_ALPHA_TO_COVERAGE_ENABLE_EXT dynamic states is not set, or alphaToOne is enabled on the device and VK_DYNAMIC_STATE_ALPHA_TO_ONE_ENABLE_EXT is not set, then pMultisampleState must be a valid pointer to a valid VkPipelineMultisampleStateCreateInfo structure

  • VUID-VkGraphicsPipelineCreateInfo-flags-06633
    If VkGraphicsPipelineLibraryCreateInfoEXT::flags includes VK_GRAPHICS_PIPELINE_LIBRARY_FRAGMENT_SHADER_BIT_EXT with a pMultisampleState that was not NULL, and an element of VkPipelineLibraryCreateInfoKHR::pLibraries was created with VK_GRAPHICS_PIPELINE_LIBRARY_FRAGMENT_OUTPUT_INTERFACE_BIT_EXT, pMultisampleState must be identically defined to that used to create the library

  • VUID-VkGraphicsPipelineCreateInfo-pLibraries-06634
    If an element of VkPipelineLibraryCreateInfoKHR::pLibraries was created with VK_GRAPHICS_PIPELINE_LIBRARY_FRAGMENT_SHADER_BIT_EXT with a pMultisampleState that was not NULL, and if VkGraphicsPipelineLibraryCreateInfoEXT::flags includes VK_GRAPHICS_PIPELINE_LIBRARY_FRAGMENT_OUTPUT_INTERFACE_BIT_EXT, pMultisampleState must be identically defined to that used to create the library

  • VUID-VkGraphicsPipelineCreateInfo-pLibraries-06635
    If one element of VkPipelineLibraryCreateInfoKHR::pLibraries was created with VK_GRAPHICS_PIPELINE_LIBRARY_FRAGMENT_SHADER_BIT_EXT with a pMultisampleState that was not NULL, and if a different element of VkPipelineLibraryCreateInfoKHR::pLibraries was created with VK_GRAPHICS_PIPELINE_LIBRARY_FRAGMENT_OUTPUT_INTERFACE_BIT_EXT, the pMultisampleState used to create each library must be identically defined

  • VUID-VkGraphicsPipelineCreateInfo-pLibraries-06636
    If one element of VkPipelineLibraryCreateInfoKHR::pLibraries was created with VK_GRAPHICS_PIPELINE_LIBRARY_FRAGMENT_OUTPUT_INTERFACE_BIT_EXT and a value of pMultisampleState->sampleShadingEnable equal VK_TRUE, and if a different element of VkPipelineLibraryCreateInfoKHR::pLibraries was created with VK_GRAPHICS_PIPELINE_LIBRARY_FRAGMENT_SHADER_BIT_EXT, the pMultisampleState used to create each library must be identically defined

  • VUID-VkGraphicsPipelineCreateInfo-flags-06637
    If VkGraphicsPipelineLibraryCreateInfoEXT::flags includes VK_GRAPHICS_PIPELINE_LIBRARY_FRAGMENT_OUTPUT_INTERFACE_BIT_EXT, pMultisampleState->sampleShadingEnable is VK_TRUE, and an element of VkPipelineLibraryCreateInfoKHR::pLibraries was created with VK_GRAPHICS_PIPELINE_LIBRARY_FRAGMENT_SHADER_BIT_EXT, pMultisampleState must be identically defined to that used to create the library

  • VUID-VkGraphicsPipelineCreateInfo-pLibraries-09567
    If one element of VkPipelineLibraryCreateInfoKHR::pLibraries was created with VK_GRAPHICS_PIPELINE_LIBRARY_FRAGMENT_OUTPUT_INTERFACE_BIT_EXT and a value of pMultisampleState->sampleShadingEnable equal VK_TRUE, and if VkGraphicsPipelineLibraryCreateInfoEXT::flags includes VK_GRAPHICS_PIPELINE_LIBRARY_FRAGMENT_SHADER_BIT_EXT, pMultisampleState must be identically defined to that used to create the library

  • VUID-VkGraphicsPipelineCreateInfo-flags-06638
    If VkGraphicsPipelineLibraryCreateInfoEXT::flags includes only one of VK_GRAPHICS_PIPELINE_LIBRARY_PRE_RASTERIZATION_SHADERS_BIT_EXT or VK_GRAPHICS_PIPELINE_LIBRARY_FRAGMENT_SHADER_BIT_EXT, and an element of VkPipelineLibraryCreateInfoKHR::pLibraries includes the other flag, values specified in VkPipelineFragmentShadingRateStateCreateInfoKHR for both this pipeline and that library must be identical

  • VUID-VkGraphicsPipelineCreateInfo-pLibraries-06639
    If one element of VkPipelineLibraryCreateInfoKHR::pLibraries includes VK_GRAPHICS_PIPELINE_LIBRARY_PRE_RASTERIZATION_SHADERS_BIT_EXT and another element includes VK_GRAPHICS_PIPELINE_LIBRARY_FRAGMENT_SHADER_BIT_EXT, values specified in VkPipelineFragmentShadingRateStateCreateInfoKHR for both this pipeline and that library must be identical

  • VUID-VkGraphicsPipelineCreateInfo-flags-06640
    If VkGraphicsPipelineLibraryCreateInfoEXT::flags includes VK_GRAPHICS_PIPELINE_LIBRARY_PRE_RASTERIZATION_SHADERS_BIT_EXT or VK_GRAPHICS_PIPELINE_LIBRARY_FRAGMENT_SHADER_BIT_EXT, pStages must be a valid pointer to an array of stageCount valid VkPipelineShaderStageCreateInfo structures

  • VUID-VkGraphicsPipelineCreateInfo-flags-06642
    If VkGraphicsPipelineLibraryCreateInfoEXT::flags includes VK_GRAPHICS_PIPELINE_LIBRARY_PRE_RASTERIZATION_SHADERS_BIT_EXT or VK_GRAPHICS_PIPELINE_LIBRARY_FRAGMENT_SHADER_BIT_EXT, layout must be a valid VkPipelineLayout handle

  • VUID-VkGraphicsPipelineCreateInfo-flags-06643
    If VkGraphicsPipelineLibraryCreateInfoEXT::flags includes VK_GRAPHICS_PIPELINE_LIBRARY_PRE_RASTERIZATION_SHADERS_BIT_EXT, or VK_GRAPHICS_PIPELINE_LIBRARY_FRAGMENT_SHADER_BIT_EXT, VK_GRAPHICS_PIPELINE_LIBRARY_FRAGMENT_OUTPUT_INTERFACE_BIT_EXT, and renderPass is not VK_NULL_HANDLE, renderPass must be a valid VkRenderPass handle

  • VUID-VkGraphicsPipelineCreateInfo-flags-06644
    If VkGraphicsPipelineLibraryCreateInfoEXT::flags includes VK_GRAPHICS_PIPELINE_LIBRARY_PRE_RASTERIZATION_SHADERS_BIT_EXT or VK_GRAPHICS_PIPELINE_LIBRARY_FRAGMENT_SHADER_BIT_EXT, stageCount must be greater than 0

  • VUID-VkGraphicsPipelineCreateInfo-flags-06645
    If VkGraphicsPipelineLibraryCreateInfoEXT::flags is non-zero, if flags includes VK_PIPELINE_CREATE_CAPTURE_INTERNAL_REPRESENTATIONS_BIT_KHR, any libraries must have also been created with VK_PIPELINE_CREATE_CAPTURE_INTERNAL_REPRESENTATIONS_BIT_KHR

  • VUID-VkGraphicsPipelineCreateInfo-pLibraries-06646
    If VkPipelineLibraryCreateInfoKHR::pLibraries includes more than one library, and any library was created with VK_PIPELINE_CREATE_CAPTURE_INTERNAL_REPRESENTATIONS_BIT_KHR, all libraries must have also been created with VK_PIPELINE_CREATE_CAPTURE_INTERNAL_REPRESENTATIONS_BIT_KHR

  • VUID-VkGraphicsPipelineCreateInfo-pLibraries-06647
    If VkPipelineLibraryCreateInfoKHR::pLibraries includes at least one library, VkGraphicsPipelineLibraryCreateInfoEXT::flags is non-zero, and any library was created with VK_PIPELINE_CREATE_CAPTURE_INTERNAL_REPRESENTATIONS_BIT_KHR, flags must include VK_PIPELINE_CREATE_CAPTURE_INTERNAL_REPRESENTATIONS_BIT_KHR

  • VUID-VkGraphicsPipelineCreateInfo-None-07826
    If the pipeline includes a complete set of state, and there are no libraries included in VkPipelineLibraryCreateInfoKHR::pLibraries, then VkPipelineLayout must be a valid pipeline layout

  • VUID-VkGraphicsPipelineCreateInfo-layout-07827
    If the pipeline includes a complete set of state specified entirely by libraries, and each library was created with a VkPipelineLayout created without VK_PIPELINE_LAYOUT_CREATE_INDEPENDENT_SETS_BIT_EXT, then layout must be compatible with the layouts in those libraries

  • VUID-VkGraphicsPipelineCreateInfo-flags-06729
    If flags includes VK_PIPELINE_CREATE_LINK_TIME_OPTIMIZATION_BIT_EXT, the pipeline includes a complete set of state specified entirely by libraries, and each library was created with a VkPipelineLayout created with VK_PIPELINE_LAYOUT_CREATE_INDEPENDENT_SETS_BIT_EXT, then layout must be compatible with the union of the libraries' pipeline layouts other than the inclusion/exclusion of VK_PIPELINE_LAYOUT_CREATE_INDEPENDENT_SETS_BIT_EXT

  • VUID-VkGraphicsPipelineCreateInfo-flags-06730
    If flags does not include VK_PIPELINE_CREATE_LINK_TIME_OPTIMIZATION_BIT_EXT, the pipeline includes a complete set of state specified entirely by libraries, and each library was created with a VkPipelineLayout created with VK_PIPELINE_LAYOUT_CREATE_INDEPENDENT_SETS_BIT_EXT, then layout must be compatible with the union of the libraries' pipeline layouts

  • VUID-VkGraphicsPipelineCreateInfo-conservativePointAndLineRasterization-08892
    If conservativePointAndLineRasterization is not supported; the pipeline is being created with vertex input state and pre-rasterization shader state; the pipeline does not include a geometry shader; and the value of VkPipelineInputAssemblyStateCreateInfo::topology is VK_PRIMITIVE_TOPOLOGY_POINT_LIST, VK_PRIMITIVE_TOPOLOGY_LINE_LIST, or VK_PRIMITIVE_TOPOLOGY_LINE_STRIP, and either VK_DYNAMIC_STATE_PRIMITIVE_TOPOLOGY dynamic state is not enabled or dynamicPrimitiveTopologyUnrestricted is VK_FALSE, then VkPipelineRasterizationConservativeStateCreateInfoEXT::conservativeRasterizationMode must be VK_CONSERVATIVE_RASTERIZATION_MODE_DISABLED_EXT

  • VUID-VkGraphicsPipelineCreateInfo-conservativePointAndLineRasterization-06760
    If conservativePointAndLineRasterization is not supported, the pipeline requires pre-rasterization shader state, and the pipeline includes a geometry shader with either the OutputPoints or OutputLineStrip execution modes, VkPipelineRasterizationConservativeStateCreateInfoEXT::conservativeRasterizationMode must be VK_CONSERVATIVE_RASTERIZATION_MODE_DISABLED_EXT

  • VUID-VkGraphicsPipelineCreateInfo-conservativePointAndLineRasterization-06761
    If conservativePointAndLineRasterization is not supported, the pipeline requires pre-rasterization shader state, and the pipeline includes a mesh shader with either the OutputPoints or OutputLinesNV execution modes, VkPipelineRasterizationConservativeStateCreateInfoEXT::conservativeRasterizationMode must be VK_CONSERVATIVE_RASTERIZATION_MODE_DISABLED_EXT

  • VUID-VkGraphicsPipelineCreateInfo-pStages-06894
    If the pipeline requires pre-rasterization shader state but not fragment shader state, elements of pStages must not have stage set to VK_SHADER_STAGE_FRAGMENT_BIT

  • VUID-VkGraphicsPipelineCreateInfo-pStages-06895
    If the pipeline requires fragment shader state but not pre-rasterization shader state, elements of pStages must not have stage set to a shader stage which participates in pre-rasterization

  • VUID-VkGraphicsPipelineCreateInfo-pStages-06896
    If the pipeline requires pre-rasterization shader state, all elements of pStages must have a stage set to a shader stage which participates in fragment shader state or pre-rasterization shader state

  • VUID-VkGraphicsPipelineCreateInfo-stage-06897
    If the pipeline requires fragment shader state and/or pre-rasterization shader state, any value of stage must not be set in more than one element of pStages

  • VUID-VkGraphicsPipelineCreateInfo-extendedDynamicState3TessellationDomainOrigin-07370
    If the extendedDynamicState3TessellationDomainOrigin feature is not enabled, there must be no element of the pDynamicStates member of pDynamicState set to VK_DYNAMIC_STATE_TESSELLATION_DOMAIN_ORIGIN_EXT

  • VUID-VkGraphicsPipelineCreateInfo-extendedDynamicState3DepthClampEnable-07371
    If the extendedDynamicState3DepthClampEnable feature is not enabled, there must be no element of the pDynamicStates member of pDynamicState set to VK_DYNAMIC_STATE_DEPTH_CLAMP_ENABLE_EXT

  • VUID-VkGraphicsPipelineCreateInfo-extendedDynamicState3PolygonMode-07372
    If the extendedDynamicState3PolygonMode feature is not enabled, there must be no element of the pDynamicStates member of pDynamicState set to VK_DYNAMIC_STATE_POLYGON_MODE_EXT

  • VUID-VkGraphicsPipelineCreateInfo-extendedDynamicState3RasterizationSamples-07373
    If the extendedDynamicState3RasterizationSamples feature is not enabled, there must be no element of the pDynamicStates member of pDynamicState set to VK_DYNAMIC_STATE_RASTERIZATION_SAMPLES_EXT

  • VUID-VkGraphicsPipelineCreateInfo-extendedDynamicState3SampleMask-07374
    If the extendedDynamicState3SampleMask feature is not enabled, there must be no element of the pDynamicStates member of pDynamicState set to VK_DYNAMIC_STATE_SAMPLE_MASK_EXT

  • VUID-VkGraphicsPipelineCreateInfo-extendedDynamicState3AlphaToCoverageEnable-07375
    If the extendedDynamicState3AlphaToCoverageEnable feature is not enabled, there must be no element of the pDynamicStates member of pDynamicState set to VK_DYNAMIC_STATE_ALPHA_TO_COVERAGE_ENABLE_EXT

  • VUID-VkGraphicsPipelineCreateInfo-extendedDynamicState3AlphaToOneEnable-07376
    If the extendedDynamicState3AlphaToOneEnable feature is not enabled, there must be no element of the pDynamicStates member of pDynamicState set to VK_DYNAMIC_STATE_ALPHA_TO_ONE_ENABLE_EXT

  • VUID-VkGraphicsPipelineCreateInfo-extendedDynamicState3LogicOpEnable-07377
    If the extendedDynamicState3LogicOpEnable feature is not enabled, there must be no element of the pDynamicStates member of pDynamicState set to VK_DYNAMIC_STATE_LOGIC_OP_ENABLE_EXT

  • VUID-VkGraphicsPipelineCreateInfo-extendedDynamicState3ColorBlendEnable-07378
    If the extendedDynamicState3ColorBlendEnable feature is not enabled, there must be no element of the pDynamicStates member of pDynamicState set to VK_DYNAMIC_STATE_COLOR_BLEND_ENABLE_EXT

  • VUID-VkGraphicsPipelineCreateInfo-extendedDynamicState3ColorBlendEquation-07379
    If the extendedDynamicState3ColorBlendEquation feature is not enabled, there must be no element of the pDynamicStates member of pDynamicState set to VK_DYNAMIC_STATE_COLOR_BLEND_EQUATION_EXT

  • VUID-VkGraphicsPipelineCreateInfo-extendedDynamicState3ColorWriteMask-07380
    If the extendedDynamicState3ColorWriteMask feature is not enabled, there must be no element of the pDynamicStates member of pDynamicState set to VK_DYNAMIC_STATE_COLOR_WRITE_MASK_EXT

  • VUID-VkGraphicsPipelineCreateInfo-extendedDynamicState3RasterizationStream-07381
    If the extendedDynamicState3RasterizationStream feature is not enabled, there must be no element of the pDynamicStates member of pDynamicState set to VK_DYNAMIC_STATE_RASTERIZATION_STREAM_EXT

  • VUID-VkGraphicsPipelineCreateInfo-extendedDynamicState3ConservativeRasterizationMode-07382
    If the extendedDynamicState3ConservativeRasterizationMode feature is not enabled, there must be no element of the pDynamicStates member of pDynamicState set to VK_DYNAMIC_STATE_CONSERVATIVE_RASTERIZATION_MODE_EXT

  • VUID-VkGraphicsPipelineCreateInfo-extendedDynamicState3ExtraPrimitiveOverestimationSize-07383
    If the extendedDynamicState3ExtraPrimitiveOverestimationSize feature is not enabled, there must be no element of the pDynamicStates member of pDynamicState set to VK_DYNAMIC_STATE_EXTRA_PRIMITIVE_OVERESTIMATION_SIZE_EXT

  • VUID-VkGraphicsPipelineCreateInfo-pDynamicState-09639
    If the pipeline requires pre-rasterization shader state, pDynamicState includes VK_DYNAMIC_STATE_CONSERVATIVE_RASTERIZATION_MODE_EXT, and pDynamicState does not include VK_DYNAMIC_STATE_EXTRA_PRIMITIVE_OVERESTIMATION_SIZE_EXT, pRasterizationState must include a VkPipelineRasterizationConservativeStateCreateInfoEXT in its pNext chain

  • VUID-VkGraphicsPipelineCreateInfo-extendedDynamicState3DepthClipEnable-07384
    If the extendedDynamicState3DepthClipEnable feature is not enabled, there must be no element of the pDynamicStates member of pDynamicState set to VK_DYNAMIC_STATE_DEPTH_CLIP_ENABLE_EXT

  • VUID-VkGraphicsPipelineCreateInfo-extendedDynamicState3SampleLocationsEnable-07385
    If the extendedDynamicState3SampleLocationsEnable feature is not enabled, there must be no element of the pDynamicStates member of pDynamicState set to VK_DYNAMIC_STATE_SAMPLE_LOCATIONS_ENABLE_EXT

  • VUID-VkGraphicsPipelineCreateInfo-extendedDynamicState3ColorBlendAdvanced-07386
    If the extendedDynamicState3ColorBlendAdvanced feature is not enabled, there must be no element of the pDynamicStates member of pDynamicState set to VK_DYNAMIC_STATE_COLOR_BLEND_ADVANCED_EXT

  • VUID-VkGraphicsPipelineCreateInfo-extendedDynamicState3ProvokingVertexMode-07387
    If the extendedDynamicState3ProvokingVertexMode feature is not enabled, there must be no element of the pDynamicStates member of pDynamicState set to VK_DYNAMIC_STATE_PROVOKING_VERTEX_MODE_EXT

  • VUID-VkGraphicsPipelineCreateInfo-extendedDynamicState3LineRasterizationMode-07388
    If the extendedDynamicState3LineRasterizationMode feature is not enabled, there must be no element of the pDynamicStates member of pDynamicState set to VK_DYNAMIC_STATE_LINE_RASTERIZATION_MODE_EXT

  • VUID-VkGraphicsPipelineCreateInfo-extendedDynamicState3LineStippleEnable-07389
    If the extendedDynamicState3LineStippleEnable feature is not enabled, there must be no element of the pDynamicStates member of pDynamicState set to VK_DYNAMIC_STATE_LINE_STIPPLE_ENABLE_EXT

  • VUID-VkGraphicsPipelineCreateInfo-extendedDynamicState3DepthClipNegativeOneToOne-07390
    If the extendedDynamicState3DepthClipNegativeOneToOne feature is not enabled, there must be no element of the pDynamicStates member of pDynamicState set to VK_DYNAMIC_STATE_DEPTH_CLIP_NEGATIVE_ONE_TO_ONE_EXT

  • VUID-VkGraphicsPipelineCreateInfo-extendedDynamicState3ViewportWScalingEnable-07391
    If the extendedDynamicState3ViewportWScalingEnable feature is not enabled, there must be no element of the pDynamicStates member of pDynamicState set to VK_DYNAMIC_STATE_VIEWPORT_W_SCALING_ENABLE_NV

  • VUID-VkGraphicsPipelineCreateInfo-extendedDynamicState3ViewportSwizzle-07392
    If the extendedDynamicState3ViewportSwizzle feature is not enabled, there must be no element of the pDynamicStates member of pDynamicState set to VK_DYNAMIC_STATE_VIEWPORT_SWIZZLE_NV

  • VUID-VkGraphicsPipelineCreateInfo-extendedDynamicState3CoverageToColorEnable-07393
    If the extendedDynamicState3CoverageToColorEnable feature is not enabled, there must be no element of the pDynamicStates member of pDynamicState set to VK_DYNAMIC_STATE_COVERAGE_TO_COLOR_ENABLE_NV

  • VUID-VkGraphicsPipelineCreateInfo-extendedDynamicState3CoverageToColorLocation-07394
    If the extendedDynamicState3CoverageToColorLocation feature is not enabled, there must be no element of the pDynamicStates member of pDynamicState set to VK_DYNAMIC_STATE_COVERAGE_TO_COLOR_LOCATION_NV

  • VUID-VkGraphicsPipelineCreateInfo-extendedDynamicState3CoverageModulationMode-07395
    If the extendedDynamicState3CoverageModulationMode feature is not enabled, there must be no element of the pDynamicStates member of pDynamicState set to VK_DYNAMIC_STATE_COVERAGE_MODULATION_MODE_NV

  • VUID-VkGraphicsPipelineCreateInfo-extendedDynamicState3CoverageModulationTableEnable-07396
    If the extendedDynamicState3CoverageModulationTableEnable feature is not enabled, there must be no element of the pDynamicStates member of pDynamicState set to VK_DYNAMIC_STATE_COVERAGE_MODULATION_TABLE_ENABLE_NV

  • VUID-VkGraphicsPipelineCreateInfo-extendedDynamicState3CoverageModulationTable-07397
    If the extendedDynamicState3CoverageModulationTable feature is not enabled, there must be no element of the pDynamicStates member of pDynamicState set to VK_DYNAMIC_STATE_COVERAGE_MODULATION_TABLE_NV

  • VUID-VkGraphicsPipelineCreateInfo-extendedDynamicState3CoverageReductionMode-07398
    If the extendedDynamicState3CoverageReductionMode feature is not enabled, there must be no element of the pDynamicStates member of pDynamicState set to VK_DYNAMIC_STATE_COVERAGE_REDUCTION_MODE_NV

  • VUID-VkGraphicsPipelineCreateInfo-extendedDynamicState3RepresentativeFragmentTestEnable-07399
    If the extendedDynamicState3RepresentativeFragmentTestEnable feature is not enabled, there must be no element of the pDynamicStates member of pDynamicState set to VK_DYNAMIC_STATE_REPRESENTATIVE_FRAGMENT_TEST_ENABLE_NV

  • VUID-VkGraphicsPipelineCreateInfo-extendedDynamicState3ShadingRateImageEnable-07400
    If the extendedDynamicState3ShadingRateImageEnable feature is not enabled, there must be no element of the pDynamicStates member of pDynamicState set to VK_DYNAMIC_STATE_SHADING_RATE_IMAGE_ENABLE_NV

  • VUID-VkGraphicsPipelineCreateInfo-flags-07401
    flags must not include VK_PIPELINE_CREATE_RAY_TRACING_OPACITY_MICROMAP_BIT_EXT

  • VUID-VkGraphicsPipelineCreateInfo-flags-07997
    flags must not include VK_PIPELINE_CREATE_RAY_TRACING_DISPLACEMENT_MICROMAP_BIT_NV

  • VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-07730
    If the pipeline requires pre-rasterization shader state, and no element of the pDynamicStates member of pDynamicState is VK_DYNAMIC_STATE_VIEWPORT or VK_DYNAMIC_STATE_VIEWPORT_WITH_COUNT, and if multiviewPerViewViewports is enabled, then the index of the most significant bit in each element of VkRenderPassMultiviewCreateInfo::pViewMasks must be less than pViewportState->viewportCount

  • VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-07731
    If the pipeline requires pre-rasterization shader state, and no element of the pDynamicStates member of pDynamicState is VK_DYNAMIC_STATE_SCISSOR or VK_DYNAMIC_STATE_SCISSOR_WITH_COUNT, and if multiviewPerViewViewports is enabled, then the index of the most significant bit in each element of VkRenderPassMultiviewCreateInfo::pViewMasks must be less than pViewportState->scissorCount

  • VUID-VkGraphicsPipelineCreateInfo-pStages-08711
    If pStages includes a fragment shader stage, VK_DYNAMIC_STATE_DEPTH_WRITE_ENABLE is not set in VkPipelineDynamicStateCreateInfo::pDynamicStates, and the fragment shader declares the EarlyFragmentTests execution mode and uses OpDepthAttachmentReadEXT, the depthWriteEnable member of VkPipelineDepthStencilStateCreateInfo must be VK_FALSE

  • VUID-VkGraphicsPipelineCreateInfo-pStages-08712
    If pStages includes a fragment shader stage, VK_DYNAMIC_STATE_STENCIL_WRITE_MASK is not set in VkPipelineDynamicStateCreateInfo::pDynamicStates, and the fragment shader declares the EarlyFragmentTests execution mode and uses OpStencilAttachmentReadEXT, the value of VkStencilOpState::writeMask for both front and back in VkPipelineDepthStencilStateCreateInfo must be 0

  • VUID-VkGraphicsPipelineCreateInfo-renderPass-08744
    If renderPass is VK_NULL_HANDLE, the pipeline requires fragment output state or fragment shader state, the pipeline enables sample shading, rasterizationSamples is not dynamic, and the pNext chain includes a VkPipelineRenderingCreateInfo structure, rasterizationSamples must be a valid VkSampleCountFlagBits value that is set in imageCreateSampleCounts (as defined in Image Creation Limits) for every element of depthAttachmentFormat, stencilAttachmentFormat and the pColorAttachmentFormats array which is not VK_FORMAT_UNDEFINED

  • VUID-VkGraphicsPipelineCreateInfo-flags-08897
    If VkGraphicsPipelineLibraryCreateInfoEXT::flags includes VK_GRAPHICS_PIPELINE_LIBRARY_VERTEX_INPUT_INTERFACE_BIT_EXT, pre-rasterization shader state is specified either in a library or by the inclusion of VK_GRAPHICS_PIPELINE_LIBRARY_PRE_RASTERIZATION_SHADERS_BIT_EXT, and that state includes a vertex shader stage in pStages, the pipeline must define vertex input state

  • VUID-VkGraphicsPipelineCreateInfo-flags-08898
    If VkGraphicsPipelineLibraryCreateInfoEXT::flags includes VK_GRAPHICS_PIPELINE_LIBRARY_VERTEX_INPUT_INTERFACE_BIT_EXT, and pre-rasterization shader state is not specified, the pipeline must define vertex input state

  • VUID-VkGraphicsPipelineCreateInfo-flags-08899
    If flags does not include VK_PIPELINE_CREATE_LIBRARY_BIT_KHR, pre-rasterization shader state is specified either in a library or by the inclusion of VK_GRAPHICS_PIPELINE_LIBRARY_PRE_RASTERIZATION_SHADERS_BIT_EXT, and that state includes a vertex shader stage in pStages, the pipeline must either define vertex input state or include that state in a linked pipeline library

  • VUID-VkGraphicsPipelineCreateInfo-flags-08900
    If VkGraphicsPipelineLibraryCreateInfoEXT::flags includes VK_GRAPHICS_PIPELINE_LIBRARY_PRE_RASTERIZATION_SHADERS_BIT_EXT the pipeline must define pre-rasterization shader state

  • VUID-VkGraphicsPipelineCreateInfo-flags-08901
    If flags does not include VK_PIPELINE_CREATE_LIBRARY_BIT_KHR, the pipeline must either define pre-rasterization shader state or include that state in a linked pipeline library

  • VUID-VkGraphicsPipelineCreateInfo-flags-08903
    If VkGraphicsPipelineLibraryCreateInfoEXT::flags includes VK_GRAPHICS_PIPELINE_LIBRARY_FRAGMENT_SHADER_BIT_EXT, pre-rasterization shader state is specified either in a library or by the inclusion of VK_GRAPHICS_PIPELINE_LIBRARY_PRE_RASTERIZATION_SHADERS_BIT_EXT, and that state either includes VK_DYNAMIC_STATE_RASTERIZER_DISCARD_ENABLE or has pRasterizationState->rasterizerDiscardEnable set to VK_FALSE, the pipeline must define fragment shader state

  • VUID-VkGraphicsPipelineCreateInfo-flags-08904
    If VkGraphicsPipelineLibraryCreateInfoEXT::flags includes VK_GRAPHICS_PIPELINE_LIBRARY_FRAGMENT_SHADER_BIT_EXT, and pre-rasterization shader state is not specified, the pipeline must define fragment shader state

  • VUID-VkGraphicsPipelineCreateInfo-flags-08906
    If VkGraphicsPipelineLibraryCreateInfoEXT::flags includes VK_GRAPHICS_PIPELINE_LIBRARY_FRAGMENT_SHADER_BIT_EXT, pre-rasterization shader state is specified either in a library or by the inclusion of VK_GRAPHICS_PIPELINE_LIBRARY_FRAGMENT_OUTPUT_INTERFACE_BIT_EXT, and that state either includes VK_DYNAMIC_STATE_RASTERIZER_DISCARD_ENABLE or has pRasterizationState->rasterizerDiscardEnable set to VK_FALSE, the pipeline must define fragment output interface state

  • VUID-VkGraphicsPipelineCreateInfo-flags-08907
    If VkGraphicsPipelineLibraryCreateInfoEXT::flags includes VK_GRAPHICS_PIPELINE_LIBRARY_FRAGMENT_SHADER_BIT_EXT, and pre-rasterization shader state is not specified, the pipeline must define fragment output interface state

  • VUID-VkGraphicsPipelineCreateInfo-flags-08909
    If flags does not include VK_PIPELINE_CREATE_LIBRARY_BIT_KHR, pre-rasterization shader state is specified either in a library or by the inclusion of VK_GRAPHICS_PIPELINE_LIBRARY_PRE_RASTERIZATION_SHADERS_BIT_EXT, and that state either includes VK_DYNAMIC_STATE_RASTERIZER_DISCARD_ENABLE or has pRasterizationState->rasterizerDiscardEnable set to VK_FALSE, the pipeline must define fragment output interface state and fragment shader state or include those states in linked pipeline libraries

  • VUID-VkGraphicsPipelineCreateInfo-None-09043
    If pDynamicState->pDynamicStates does not include VK_DYNAMIC_STATE_COLOR_WRITE_MASK_EXT, and the format of any color attachment is VK_FORMAT_E5B9G9R9_UFLOAT_PACK32, the colorWriteMask member of the corresponding element of pColorBlendState->pAttachments must either include all of VK_COLOR_COMPONENT_R_BIT, VK_COLOR_COMPONENT_G_BIT, and VK_COLOR_COMPONENT_B_BIT, or none of them

  • VUID-VkGraphicsPipelineCreateInfo-externalFormatResolve-09301
    If the externalFormatResolve feature is enabled, the pipeline requires fragment output interface state, renderPass is VK_NULL_HANDLE, and VkExternalFormatANDROID::externalFormat is not 0, VkPipelineRenderingCreateInfo::viewMask must be 0

  • VUID-VkGraphicsPipelineCreateInfo-externalFormatResolve-09304
    If the externalFormatResolve feature is enabled, the pipeline requires fragment output interface state, renderPass is VK_NULL_HANDLE, VkExternalFormatANDROID::externalFormat is not 0, and rasterizationSamples is not dynamic, VkPipelineMultisampleStateCreateInfo::rasterizationSamples must be 1

  • VUID-VkGraphicsPipelineCreateInfo-externalFormatResolve-09305
    If the externalFormatResolve feature is enabled, the pipeline requires fragment output interface state, renderPass is VK_NULL_HANDLE, and VkExternalFormatANDROID::externalFormat is not 0, and blendEnable is not dynamic, the blendEnable member of each element of pColorBlendState->pAttachments must be VK_FALSE

  • VUID-VkGraphicsPipelineCreateInfo-externalFormatResolve-09306
    If the externalFormatResolve feature is enabled, the pipeline requires fragment output interface state, renderPass is VK_NULL_HANDLE, and VkExternalFormatANDROID::externalFormat is not 0, and pDynamicState->pDynamicStates does not include VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR, VkPipelineFragmentShadingRateStateCreateInfoKHR::width must be 1

  • VUID-VkGraphicsPipelineCreateInfo-externalFormatResolve-09307
    If the externalFormatResolve feature is enabled, the pipeline requires fragment output interface state, renderPass is VK_NULL_HANDLE, and VkExternalFormatANDROID::externalFormat is not 0, and pDynamicState->pDynamicStates does not include VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR, VkPipelineFragmentShadingRateStateCreateInfoKHR::height must be 1

  • VUID-VkGraphicsPipelineCreateInfo-externalFormatResolve-09308
    If the externalFormatResolve feature is enabled, the pipeline requires pre-rasterization shader state and fragment output interface state, renderPass is VK_NULL_HANDLE, and VkExternalFormatANDROID::externalFormat is not 0, the last pre-rasterization shader stage must not statically use a variable with the PrimitiveShadingRateKHR built-in

  • VUID-VkGraphicsPipelineCreateInfo-externalFormatResolve-09309
    If the externalFormatResolve feature is enabled, the pipeline requires fragment output interface state, renderPass is VK_NULL_HANDLE, and VkExternalFormatANDROID::externalFormat is not 0, VkPipelineRenderingCreateInfo::colorAttachmentCount must be 1

  • VUID-VkGraphicsPipelineCreateInfo-externalFormatResolve-09310
    If the externalFormatResolve feature is enabled, the pipeline requires fragment shader state and fragment output interface state, renderPass is VK_NULL_HANDLE, and VkExternalFormatANDROID::externalFormat is not 0, the fragment shader must not declare the DepthReplacing or StencilRefReplacingEXT execution modes

  • VUID-VkGraphicsPipelineCreateInfo-externalFormatResolve-09313
    If the externalFormatResolve feature is enabled, the pipeline requires fragment output interface state, renderPass is not VK_NULL_HANDLE, subpass includes an external format resolve attachment, and rasterizationSamples is not dynamic, VkPipelineMultisampleStateCreateInfo::rasterizationSamples must be VK_SAMPLE_COUNT_1_BIT

  • VUID-VkGraphicsPipelineCreateInfo-externalFormatResolve-09314
    If the externalFormatResolve feature is enabled, the pipeline requires fragment output interface state, renderPass is not VK_NULL_HANDLE, subpass includes an external format resolve attachment, and blendEnable is not dynamic, the blendEnable member of each element of pColorBlendState->pAttachments must be VK_FALSE

  • VUID-VkGraphicsPipelineCreateInfo-externalFormatResolve-09315
    If the externalFormatResolve feature is enabled, the pipeline requires fragment output interface state, renderPass is not VK_NULL_HANDLE, subpass includes an external format resolve attachment, and pDynamicState->pDynamicStates does not include VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR, VkPipelineFragmentShadingRateStateCreateInfoKHR::width must be 1

  • VUID-VkGraphicsPipelineCreateInfo-externalFormatResolve-09316
    If the externalFormatResolve feature is enabled, the pipeline requires fragment output interface state, renderPass is not VK_NULL_HANDLE, subpass includes an external format resolve attachment, and pDynamicState->pDynamicStates does not include VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR, VkPipelineFragmentShadingRateStateCreateInfoKHR::height must be 1

  • VUID-VkGraphicsPipelineCreateInfo-externalFormatResolve-09317
    If the externalFormatResolve feature is enabled, the pipeline requires pre-rasterization shader state and fragment output interface state, renderPass is not VK_NULL_HANDLE, and subpass includes an external format resolve attachment, the last pre-rasterization shader stage must not statically use a variable with the PrimitiveShadingRateKHR built-in

  • VUID-VkGraphicsPipelineCreateInfo-renderPass-09531
    If the pipeline is being created with fragment shader state and fragment output state, the value of renderPass is VK_NULL_HANDLE, and VkRenderingInputAttachmentIndexInfoKHR is included, VkRenderingInputAttachmentIndexInfoKHR::colorAttachmentCount must be equal to VkPipelineRenderingCreateInfo::colorAttachmentCount

  • VUID-VkGraphicsPipelineCreateInfo-renderPass-09652
    If the pipeline is being created with fragment shader state and fragment output state, the value of renderPass is VK_NULL_HANDLE, and VkRenderingInputAttachmentIndexInfoKHR is not included, the fragment shader must not contain any input attachments with a InputAttachmentIndex greater than or equal to VkPipelineRenderingCreateInfo::colorAttachmentCount

  • VUID-VkGraphicsPipelineCreateInfo-renderPass-09532
    If the pipeline is being created with fragment output state, and the value of renderPass is VK_NULL_HANDLE, VkRenderingAttachmentLocationInfoKHR::colorAttachmentCount must be equal to VkPipelineRenderingCreateInfo::colorAttachmentCount

Valid Usage (Implicit)

The VkPipelineRenderingCreateInfo structure is defined as:

// Provided by VK_VERSION_1_3
typedef struct VkPipelineRenderingCreateInfo {
    VkStructureType    sType;
    const void*        pNext;
    uint32_t           viewMask;
    uint32_t           colorAttachmentCount;
    const VkFormat*    pColorAttachmentFormats;
    VkFormat           depthAttachmentFormat;
    VkFormat           stencilAttachmentFormat;
} VkPipelineRenderingCreateInfo;

or the equivalent

// Provided by VK_KHR_dynamic_rendering
typedef VkPipelineRenderingCreateInfo VkPipelineRenderingCreateInfoKHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • viewMask is the viewMask used for rendering.

  • colorAttachmentCount is the number of entries in pColorAttachmentFormats

  • pColorAttachmentFormats is a pointer to an array of VkFormat values defining the format of color attachments used in this pipeline.

  • depthAttachmentFormat is a VkFormat value defining the format of the depth attachment used in this pipeline.

  • stencilAttachmentFormat is a VkFormat value defining the format of the stencil attachment used in this pipeline.

When a pipeline is created without a VkRenderPass, if the pNext chain of VkGraphicsPipelineCreateInfo includes this structure, it specifies the view mask and format of attachments used for rendering. If this structure is not specified, and the pipeline does not include a VkRenderPass, viewMask and colorAttachmentCount are 0, and depthAttachmentFormat and stencilAttachmentFormat are VK_FORMAT_UNDEFINED. If a graphics pipeline is created with a valid VkRenderPass, parameters of this structure are ignored.

If depthAttachmentFormat, stencilAttachmentFormat, or any element of pColorAttachmentFormats is VK_FORMAT_UNDEFINED, it indicates that the corresponding attachment is unused within the render pass. Valid formats indicate that an attachment can be used - but it is still valid to set the attachment to NULL when beginning rendering.

If the render pass is going to be used with an external format resolve attachment, a VkExternalFormatANDROID structure must also be included in the pNext chain of VkGraphicsPipelineCreateInfo, defining the external format of the resolve attachment that will be used.

Valid Usage

  • VUID-VkPipelineRenderingCreateInfo-colorAttachmentCount-09533
    colorAttachmentCount must be less than or equal to maxColorAttachments

Valid Usage (Implicit)

  • VUID-VkPipelineRenderingCreateInfo-sType-sType
    sType must be VK_STRUCTURE_TYPE_PIPELINE_RENDERING_CREATE_INFO

The VkPipelineCreateFlags2CreateInfoKHR structure is defined as:

// Provided by VK_KHR_maintenance5
typedef struct VkPipelineCreateFlags2CreateInfoKHR {
    VkStructureType              sType;
    const void*                  pNext;
    VkPipelineCreateFlags2KHR    flags;
} VkPipelineCreateFlags2CreateInfoKHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • flags is a bitmask of VkPipelineCreateFlagBits2KHR specifying how a pipeline will be generated.

If this structure is included in the pNext chain of a pipeline creation structure, flags is used instead of the corresponding flags value passed in that creation structure, allowing additional creation flags to be specified.

Valid Usage (Implicit)

  • VUID-VkPipelineCreateFlags2CreateInfoKHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_PIPELINE_CREATE_FLAGS_2_CREATE_INFO_KHR

  • VUID-VkPipelineCreateFlags2CreateInfoKHR-flags-parameter
    flags must be a valid combination of VkPipelineCreateFlagBits2KHR values

  • VUID-VkPipelineCreateFlags2CreateInfoKHR-flags-requiredbitmask
    flags must not be 0

Bits which can be set in VkPipelineCreateFlags2CreateInfoKHR::flags, specifying how a pipeline is created, are:

// Provided by VK_KHR_maintenance5
// Flag bits for VkPipelineCreateFlagBits2KHR
typedef VkFlags64 VkPipelineCreateFlagBits2KHR;
static const VkPipelineCreateFlagBits2KHR VK_PIPELINE_CREATE_2_DISABLE_OPTIMIZATION_BIT_KHR = 0x00000001ULL;
static const VkPipelineCreateFlagBits2KHR VK_PIPELINE_CREATE_2_ALLOW_DERIVATIVES_BIT_KHR = 0x00000002ULL;
static const VkPipelineCreateFlagBits2KHR VK_PIPELINE_CREATE_2_DERIVATIVE_BIT_KHR = 0x00000004ULL;
// Provided by VK_EXT_legacy_dithering with (VK_KHR_dynamic_rendering or VK_VERSION_1_3) and VK_KHR_maintenance5
static const VkPipelineCreateFlagBits2KHR VK_PIPELINE_CREATE_2_ENABLE_LEGACY_DITHERING_BIT_EXT = 0x400000000ULL;
// Provided by VK_KHR_maintenance5 with VK_VERSION_1_1 or VK_KHR_device_group
static const VkPipelineCreateFlagBits2KHR VK_PIPELINE_CREATE_2_VIEW_INDEX_FROM_DEVICE_INDEX_BIT_KHR = 0x00000008ULL;
// Provided by VK_KHR_maintenance5 with VK_VERSION_1_1 or VK_KHR_device_group
static const VkPipelineCreateFlagBits2KHR VK_PIPELINE_CREATE_2_DISPATCH_BASE_BIT_KHR = 0x00000010ULL;
// Provided by VK_KHR_maintenance5 with VK_NV_ray_tracing
static const VkPipelineCreateFlagBits2KHR VK_PIPELINE_CREATE_2_DEFER_COMPILE_BIT_NV = 0x00000020ULL;
// Provided by VK_KHR_maintenance5 with VK_KHR_pipeline_executable_properties
static const VkPipelineCreateFlagBits2KHR VK_PIPELINE_CREATE_2_CAPTURE_STATISTICS_BIT_KHR = 0x00000040ULL;
// Provided by VK_KHR_maintenance5 with VK_KHR_pipeline_executable_properties
static const VkPipelineCreateFlagBits2KHR VK_PIPELINE_CREATE_2_CAPTURE_INTERNAL_REPRESENTATIONS_BIT_KHR = 0x00000080ULL;
// Provided by VK_KHR_maintenance5 with VK_VERSION_1_3 or VK_EXT_pipeline_creation_cache_control
static const VkPipelineCreateFlagBits2KHR VK_PIPELINE_CREATE_2_FAIL_ON_PIPELINE_COMPILE_REQUIRED_BIT_KHR = 0x00000100ULL;
// Provided by VK_KHR_maintenance5 with VK_VERSION_1_3 or VK_EXT_pipeline_creation_cache_control
static const VkPipelineCreateFlagBits2KHR VK_PIPELINE_CREATE_2_EARLY_RETURN_ON_FAILURE_BIT_KHR = 0x00000200ULL;
// Provided by VK_KHR_maintenance5 with VK_EXT_graphics_pipeline_library
static const VkPipelineCreateFlagBits2KHR VK_PIPELINE_CREATE_2_LINK_TIME_OPTIMIZATION_BIT_EXT = 0x00000400ULL;
// Provided by VK_KHR_maintenance5 with VK_EXT_graphics_pipeline_library
static const VkPipelineCreateFlagBits2KHR VK_PIPELINE_CREATE_2_RETAIN_LINK_TIME_OPTIMIZATION_INFO_BIT_EXT = 0x00800000ULL;
// Provided by VK_KHR_maintenance5 with VK_KHR_pipeline_library
static const VkPipelineCreateFlagBits2KHR VK_PIPELINE_CREATE_2_LIBRARY_BIT_KHR = 0x00000800ULL;
// Provided by VK_KHR_maintenance5 with VK_KHR_ray_tracing_pipeline
static const VkPipelineCreateFlagBits2KHR VK_PIPELINE_CREATE_2_RAY_TRACING_SKIP_TRIANGLES_BIT_KHR = 0x00001000ULL;
// Provided by VK_KHR_maintenance5 with VK_KHR_ray_tracing_pipeline
static const VkPipelineCreateFlagBits2KHR VK_PIPELINE_CREATE_2_RAY_TRACING_SKIP_AABBS_BIT_KHR = 0x00002000ULL;
// Provided by VK_KHR_maintenance5 with VK_KHR_ray_tracing_pipeline
static const VkPipelineCreateFlagBits2KHR VK_PIPELINE_CREATE_2_RAY_TRACING_NO_NULL_ANY_HIT_SHADERS_BIT_KHR = 0x00004000ULL;
// Provided by VK_KHR_maintenance5 with VK_KHR_ray_tracing_pipeline
static const VkPipelineCreateFlagBits2KHR VK_PIPELINE_CREATE_2_RAY_TRACING_NO_NULL_CLOSEST_HIT_SHADERS_BIT_KHR = 0x00008000ULL;
// Provided by VK_KHR_maintenance5 with VK_KHR_ray_tracing_pipeline
static const VkPipelineCreateFlagBits2KHR VK_PIPELINE_CREATE_2_RAY_TRACING_NO_NULL_MISS_SHADERS_BIT_KHR = 0x00010000ULL;
// Provided by VK_KHR_maintenance5 with VK_KHR_ray_tracing_pipeline
static const VkPipelineCreateFlagBits2KHR VK_PIPELINE_CREATE_2_RAY_TRACING_NO_NULL_INTERSECTION_SHADERS_BIT_KHR = 0x00020000ULL;
// Provided by VK_KHR_maintenance5 with VK_KHR_ray_tracing_pipeline
static const VkPipelineCreateFlagBits2KHR VK_PIPELINE_CREATE_2_RAY_TRACING_SHADER_GROUP_HANDLE_CAPTURE_REPLAY_BIT_KHR = 0x00080000ULL;
// Provided by VK_KHR_maintenance5 with VK_NV_device_generated_commands
static const VkPipelineCreateFlagBits2KHR VK_PIPELINE_CREATE_2_INDIRECT_BINDABLE_BIT_NV = 0x00040000ULL;
// Provided by VK_KHR_maintenance5 with VK_NV_ray_tracing_motion_blur
static const VkPipelineCreateFlagBits2KHR VK_PIPELINE_CREATE_2_RAY_TRACING_ALLOW_MOTION_BIT_NV = 0x00100000ULL;
// Provided by VK_KHR_maintenance5 with (VK_KHR_dynamic_rendering or VK_VERSION_1_3) and VK_KHR_fragment_shading_rate
static const VkPipelineCreateFlagBits2KHR VK_PIPELINE_CREATE_2_RENDERING_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR = 0x00200000ULL;
// Provided by VK_KHR_maintenance5 with (VK_KHR_dynamic_rendering or VK_VERSION_1_3) and VK_EXT_fragment_density_map
static const VkPipelineCreateFlagBits2KHR VK_PIPELINE_CREATE_2_RENDERING_FRAGMENT_DENSITY_MAP_ATTACHMENT_BIT_EXT = 0x00400000ULL;
// Provided by VK_KHR_maintenance5 with VK_EXT_opacity_micromap
static const VkPipelineCreateFlagBits2KHR VK_PIPELINE_CREATE_2_RAY_TRACING_OPACITY_MICROMAP_BIT_EXT = 0x01000000ULL;
// Provided by VK_KHR_maintenance5 with VK_EXT_attachment_feedback_loop_layout
static const VkPipelineCreateFlagBits2KHR VK_PIPELINE_CREATE_2_COLOR_ATTACHMENT_FEEDBACK_LOOP_BIT_EXT = 0x02000000ULL;
// Provided by VK_KHR_maintenance5 with VK_EXT_attachment_feedback_loop_layout
static const VkPipelineCreateFlagBits2KHR VK_PIPELINE_CREATE_2_DEPTH_STENCIL_ATTACHMENT_FEEDBACK_LOOP_BIT_EXT = 0x04000000ULL;
// Provided by VK_KHR_maintenance5 with VK_EXT_pipeline_protected_access
static const VkPipelineCreateFlagBits2KHR VK_PIPELINE_CREATE_2_NO_PROTECTED_ACCESS_BIT_EXT = 0x08000000ULL;
// Provided by VK_KHR_maintenance5 with VK_EXT_pipeline_protected_access
static const VkPipelineCreateFlagBits2KHR VK_PIPELINE_CREATE_2_PROTECTED_ACCESS_ONLY_BIT_EXT = 0x40000000ULL;
// Provided by VK_KHR_maintenance5 with VK_NV_displacement_micromap
static const VkPipelineCreateFlagBits2KHR VK_PIPELINE_CREATE_2_RAY_TRACING_DISPLACEMENT_MICROMAP_BIT_NV = 0x10000000ULL;
// Provided by VK_KHR_maintenance5 with VK_EXT_descriptor_buffer
static const VkPipelineCreateFlagBits2KHR VK_PIPELINE_CREATE_2_DESCRIPTOR_BUFFER_BIT_EXT = 0x20000000ULL;
// Provided by VK_KHR_pipeline_binary
static const VkPipelineCreateFlagBits2KHR VK_PIPELINE_CREATE_2_CAPTURE_DATA_BIT_KHR = 0x80000000ULL;
// Provided by VK_EXT_device_generated_commands
static const VkPipelineCreateFlagBits2KHR VK_PIPELINE_CREATE_2_INDIRECT_BINDABLE_BIT_EXT = 0x4000000000ULL;

  • VK_PIPELINE_CREATE_2_DISABLE_OPTIMIZATION_BIT_KHR specifies that the created pipeline will not be optimized. Using this flag may reduce the time taken to create the pipeline.

  • VK_PIPELINE_CREATE_2_ALLOW_DERIVATIVES_BIT_KHR specifies that the pipeline to be created is allowed to be the parent of a pipeline that will be created in a subsequent pipeline creation call.

  • VK_PIPELINE_CREATE_2_DERIVATIVE_BIT_KHR specifies that the pipeline to be created will be a child of a previously created parent pipeline.

  • VK_PIPELINE_CREATE_2_VIEW_INDEX_FROM_DEVICE_INDEX_BIT_KHR specifies that any shader input variables decorated as ViewIndex will be assigned values as if they were decorated as DeviceIndex.

  • VK_PIPELINE_CREATE_2_DISPATCH_BASE_BIT_KHR specifies that a compute pipeline can be used with vkCmdDispatchBase with a non-zero base workgroup.

  • VK_PIPELINE_CREATE_2_DEFER_COMPILE_BIT_NV specifies that a pipeline is created with all shaders in the deferred state. Before using the pipeline the application must call vkCompileDeferredNV exactly once on each shader in the pipeline before using the pipeline.

  • VK_PIPELINE_CREATE_2_CAPTURE_STATISTICS_BIT_KHR specifies that the shader compiler should capture statistics for the pipeline executables produced by the compile process which can later be retrieved by calling vkGetPipelineExecutableStatisticsKHR. Enabling this flag must not affect the final compiled pipeline but may disable pipeline caching or otherwise affect pipeline creation time.

  • VK_PIPELINE_CREATE_2_CAPTURE_INTERNAL_REPRESENTATIONS_BIT_KHR specifies that the shader compiler should capture the internal representations of pipeline executables produced by the compile process which can later be retrieved by calling vkGetPipelineExecutableInternalRepresentationsKHR. Enabling this flag must not affect the final compiled pipeline but may disable pipeline caching or otherwise affect pipeline creation time. When capturing IR from pipelines created with pipeline libraries, there is no guarantee that IR from libraries can be retrieved from the linked pipeline. Applications should retrieve IR from each library, and any linked pipelines, separately.

  • VK_PIPELINE_CREATE_2_LIBRARY_BIT_KHR specifies that the pipeline cannot be used directly, and instead defines a pipeline library that can be combined with other pipelines using the VkPipelineLibraryCreateInfoKHR structure. This is available in ray tracing and graphics pipelines.

  • VK_PIPELINE_CREATE_2_RAY_TRACING_NO_NULL_ANY_HIT_SHADERS_BIT_KHR specifies that an any-hit shader will always be present when an any-hit shader would be executed. A NULL any-hit shader is an any-hit shader which is effectively VK_SHADER_UNUSED_KHR, such as from a shader group consisting entirely of zeros.

  • VK_PIPELINE_CREATE_2_RAY_TRACING_NO_NULL_CLOSEST_HIT_SHADERS_BIT_KHR specifies that a closest hit shader will always be present when a closest hit shader would be executed. A NULL closest hit shader is a closest hit shader which is effectively VK_SHADER_UNUSED_KHR, such as from a shader group consisting entirely of zeros.

  • VK_PIPELINE_CREATE_2_RAY_TRACING_NO_NULL_MISS_SHADERS_BIT_KHR specifies that a miss shader will always be present when a miss shader would be executed. A NULL miss shader is a miss shader which is effectively VK_SHADER_UNUSED_KHR, such as from a shader group consisting entirely of zeros.

  • VK_PIPELINE_CREATE_2_RAY_TRACING_NO_NULL_INTERSECTION_SHADERS_BIT_KHR specifies that an intersection shader will always be present when an intersection shader would be executed. A NULL intersection shader is an intersection shader which is effectively VK_SHADER_UNUSED_KHR, such as from a shader group consisting entirely of zeros.

  • VK_PIPELINE_CREATE_2_RAY_TRACING_SKIP_TRIANGLES_BIT_KHR specifies that triangle primitives will be skipped during traversal using pipeline trace ray instructions.

  • VK_PIPELINE_CREATE_2_RAY_TRACING_SKIP_AABBS_BIT_KHR specifies that AABB primitives will be skipped during traversal using pipeline trace ray instructions.

  • VK_PIPELINE_CREATE_2_RAY_TRACING_SHADER_GROUP_HANDLE_CAPTURE_REPLAY_BIT_KHR specifies that the shader group handles can be saved and reused on a subsequent run (e.g. for trace capture and replay).

  • VK_PIPELINE_CREATE_2_INDIRECT_BINDABLE_BIT_NV specifies that the pipeline can be used in combination with Device-Generated Commands.

  • VK_PIPELINE_CREATE_2_INDIRECT_BINDABLE_BIT_EXT specifies that the pipeline can be used in a VkIndirectExecutionSetEXT.

  • VK_PIPELINE_CREATE_2_FAIL_ON_PIPELINE_COMPILE_REQUIRED_BIT_KHR specifies that pipeline creation will fail if a compile is required for creation of a valid VkPipeline object; VK_PIPELINE_COMPILE_REQUIRED will be returned by pipeline creation, and the VkPipeline will be set to VK_NULL_HANDLE.

  • When creating multiple pipelines, VK_PIPELINE_CREATE_2_EARLY_RETURN_ON_FAILURE_BIT_KHR specifies that control will be returned to the application if any individual pipeline returns a result which is not VK_SUCCESS rather than continuing to create additional pipelines.

  • VK_PIPELINE_CREATE_2_RAY_TRACING_ALLOW_MOTION_BIT_NV specifies that the pipeline is allowed to use OpTraceRayMotionNV.

  • VK_PIPELINE_CREATE_2_RENDERING_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR specifies that the pipeline will be used with a fragment shading rate attachment.

  • VK_PIPELINE_CREATE_2_RENDERING_FRAGMENT_DENSITY_MAP_ATTACHMENT_BIT_EXT specifies that the pipeline will be used with a fragment density map attachment.

  • VK_PIPELINE_CREATE_2_LINK_TIME_OPTIMIZATION_BIT_EXT specifies that pipeline libraries being linked into this library should have link time optimizations applied. If this bit is omitted, implementations should instead perform linking as rapidly as possible.

  • VK_PIPELINE_CREATE_2_RETAIN_LINK_TIME_OPTIMIZATION_INFO_BIT_EXT specifies that pipeline libraries should retain any information necessary to later perform an optimal link with VK_PIPELINE_CREATE_2_LINK_TIME_OPTIMIZATION_BIT_EXT.

  • VK_PIPELINE_CREATE_2_DESCRIPTOR_BUFFER_BIT_EXT specifies that a pipeline will be used with descriptor buffers, rather than descriptor sets.

  • VK_PIPELINE_CREATE_2_COLOR_ATTACHMENT_FEEDBACK_LOOP_BIT_EXT specifies that the pipeline may be used with an attachment feedback loop including color attachments.

  • VK_PIPELINE_CREATE_2_DEPTH_STENCIL_ATTACHMENT_FEEDBACK_LOOP_BIT_EXT specifies that the pipeline may be used with an attachment feedback loop including depth-stencil attachments.

  • VK_PIPELINE_CREATE_2_RAY_TRACING_OPACITY_MICROMAP_BIT_EXT specifies that the ray tracing pipeline can be used with acceleration structures which reference an opacity micromap array.

  • VK_PIPELINE_CREATE_2_RAY_TRACING_DISPLACEMENT_MICROMAP_BIT_NV specifies that the ray tracing pipeline can be used with acceleration structures which reference a displacement micromap array.

  • VK_PIPELINE_CREATE_2_NO_PROTECTED_ACCESS_BIT_EXT specifies that the pipeline must not be bound to a protected command buffer.

  • VK_PIPELINE_CREATE_2_PROTECTED_ACCESS_ONLY_BIT_EXT specifies that the pipeline must not be bound to an unprotected command buffer.

  • VK_PIPELINE_CREATE_2_CAPTURE_DATA_BIT_KHR specifies that VkPipelineBinaryKHR objects can be created from the pipeline. If VK_PIPELINE_CREATE_2_CAPTURE_DATA_BIT_KHR is used, implementations should not store pipeline data to an internal cache, if such a cache exists as stated by pipelineBinaryInternalCache. If pipelineBinaryPrefersInternalCache is VK_TRUE, applications should not use VK_PIPELINE_CREATE_2_CAPTURE_DATA_BIT_KHR.

  • VK_PIPELINE_CREATE_2_ENABLE_LEGACY_DITHERING_BIT_EXT specifies that the pipeline will be used in a render pass that is begun with VK_RENDERING_ENABLE_LEGACY_DITHERING_BIT_EXT.

It is valid to set both VK_PIPELINE_CREATE_2_ALLOW_DERIVATIVES_BIT_KHR and VK_PIPELINE_CREATE_2_DERIVATIVE_BIT_KHR. This allows a pipeline to be both a parent and possibly a child in a pipeline hierarchy. See Pipeline Derivatives for more information.

When an implementation is looking up a pipeline in a pipeline cache, if that pipeline is being created using linked libraries, implementations should always return an equivalent pipeline created with VK_PIPELINE_CREATE_2_LINK_TIME_OPTIMIZATION_BIT_EXT if available, whether or not that bit was specified.

Note

Using VK_PIPELINE_CREATE_2_LINK_TIME_OPTIMIZATION_BIT_EXT (or not) when linking pipeline libraries is intended as a performance tradeoff between host and device. If the bit is omitted, linking should be faster and produce a pipeline more rapidly, but performance of the pipeline on the target device may be reduced. If the bit is included, linking may be slower but should produce a pipeline with device performance comparable to a monolithically created pipeline. Using both options can allow latency-sensitive applications to generate a suboptimal but usable pipeline quickly, and then perform an optimal link in the background, substituting the result for the suboptimally linked pipeline as soon as it is available.

 
// Provided by VK_KHR_maintenance5
typedef VkFlags64 VkPipelineCreateFlags2KHR;

VkPipelineCreateFlags2KHR is a bitmask type for setting a mask of zero or more VkPipelineCreateFlagBits2KHR.

Bits which can be set in

specify how a pipeline is created, and are:

// Provided by VK_VERSION_1_0
typedef enum VkPipelineCreateFlagBits {
    VK_PIPELINE_CREATE_DISABLE_OPTIMIZATION_BIT = 0x00000001,
    VK_PIPELINE_CREATE_ALLOW_DERIVATIVES_BIT = 0x00000002,
    VK_PIPELINE_CREATE_DERIVATIVE_BIT = 0x00000004,
  // Provided by VK_VERSION_1_1
    VK_PIPELINE_CREATE_VIEW_INDEX_FROM_DEVICE_INDEX_BIT = 0x00000008,
  // Provided by VK_VERSION_1_1
    VK_PIPELINE_CREATE_DISPATCH_BASE_BIT = 0x00000010,
  // Provided by VK_VERSION_1_3
    VK_PIPELINE_CREATE_FAIL_ON_PIPELINE_COMPILE_REQUIRED_BIT = 0x00000100,
  // Provided by VK_VERSION_1_3
    VK_PIPELINE_CREATE_EARLY_RETURN_ON_FAILURE_BIT = 0x00000200,
  // Provided by VK_KHR_dynamic_rendering with VK_KHR_fragment_shading_rate
    VK_PIPELINE_CREATE_RENDERING_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR = 0x00200000,
  // Provided by VK_KHR_dynamic_rendering with VK_EXT_fragment_density_map
    VK_PIPELINE_CREATE_RENDERING_FRAGMENT_DENSITY_MAP_ATTACHMENT_BIT_EXT = 0x00400000,
  // Provided by VK_KHR_ray_tracing_pipeline
    VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_ANY_HIT_SHADERS_BIT_KHR = 0x00004000,
  // Provided by VK_KHR_ray_tracing_pipeline
    VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_CLOSEST_HIT_SHADERS_BIT_KHR = 0x00008000,
  // Provided by VK_KHR_ray_tracing_pipeline
    VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_MISS_SHADERS_BIT_KHR = 0x00010000,
  // Provided by VK_KHR_ray_tracing_pipeline
    VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_INTERSECTION_SHADERS_BIT_KHR = 0x00020000,
  // Provided by VK_KHR_ray_tracing_pipeline
    VK_PIPELINE_CREATE_RAY_TRACING_SKIP_TRIANGLES_BIT_KHR = 0x00001000,
  // Provided by VK_KHR_ray_tracing_pipeline
    VK_PIPELINE_CREATE_RAY_TRACING_SKIP_AABBS_BIT_KHR = 0x00002000,
  // Provided by VK_KHR_ray_tracing_pipeline
    VK_PIPELINE_CREATE_RAY_TRACING_SHADER_GROUP_HANDLE_CAPTURE_REPLAY_BIT_KHR = 0x00080000,
  // Provided by VK_NV_ray_tracing
    VK_PIPELINE_CREATE_DEFER_COMPILE_BIT_NV = 0x00000020,
  // Provided by VK_KHR_pipeline_executable_properties
    VK_PIPELINE_CREATE_CAPTURE_STATISTICS_BIT_KHR = 0x00000040,
  // Provided by VK_KHR_pipeline_executable_properties
    VK_PIPELINE_CREATE_CAPTURE_INTERNAL_REPRESENTATIONS_BIT_KHR = 0x00000080,
  // Provided by VK_NV_device_generated_commands
    VK_PIPELINE_CREATE_INDIRECT_BINDABLE_BIT_NV = 0x00040000,
  // Provided by VK_KHR_pipeline_library
    VK_PIPELINE_CREATE_LIBRARY_BIT_KHR = 0x00000800,
  // Provided by VK_EXT_descriptor_buffer
    VK_PIPELINE_CREATE_DESCRIPTOR_BUFFER_BIT_EXT = 0x20000000,
  // Provided by VK_EXT_graphics_pipeline_library
    VK_PIPELINE_CREATE_RETAIN_LINK_TIME_OPTIMIZATION_INFO_BIT_EXT = 0x00800000,
  // Provided by VK_EXT_graphics_pipeline_library
    VK_PIPELINE_CREATE_LINK_TIME_OPTIMIZATION_BIT_EXT = 0x00000400,
  // Provided by VK_NV_ray_tracing_motion_blur
    VK_PIPELINE_CREATE_RAY_TRACING_ALLOW_MOTION_BIT_NV = 0x00100000,
  // Provided by VK_EXT_attachment_feedback_loop_layout
    VK_PIPELINE_CREATE_COLOR_ATTACHMENT_FEEDBACK_LOOP_BIT_EXT = 0x02000000,
  // Provided by VK_EXT_attachment_feedback_loop_layout
    VK_PIPELINE_CREATE_DEPTH_STENCIL_ATTACHMENT_FEEDBACK_LOOP_BIT_EXT = 0x04000000,
  // Provided by VK_EXT_opacity_micromap
    VK_PIPELINE_CREATE_RAY_TRACING_OPACITY_MICROMAP_BIT_EXT = 0x01000000,
#ifdef VK_ENABLE_BETA_EXTENSIONS
  // Provided by VK_NV_displacement_micromap
    VK_PIPELINE_CREATE_RAY_TRACING_DISPLACEMENT_MICROMAP_BIT_NV = 0x10000000,
#endif
  // Provided by VK_EXT_pipeline_protected_access
    VK_PIPELINE_CREATE_NO_PROTECTED_ACCESS_BIT_EXT = 0x08000000,
  // Provided by VK_EXT_pipeline_protected_access
    VK_PIPELINE_CREATE_PROTECTED_ACCESS_ONLY_BIT_EXT = 0x40000000,
  // Provided by VK_VERSION_1_1
    VK_PIPELINE_CREATE_DISPATCH_BASE = VK_PIPELINE_CREATE_DISPATCH_BASE_BIT,
  // Provided by VK_KHR_dynamic_rendering with VK_KHR_fragment_shading_rate
  // VK_PIPELINE_RASTERIZATION_STATE_CREATE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR is a deprecated alias
    VK_PIPELINE_RASTERIZATION_STATE_CREATE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR = VK_PIPELINE_CREATE_RENDERING_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR,
  // Provided by VK_KHR_dynamic_rendering with VK_EXT_fragment_density_map
  // VK_PIPELINE_RASTERIZATION_STATE_CREATE_FRAGMENT_DENSITY_MAP_ATTACHMENT_BIT_EXT is a deprecated alias
    VK_PIPELINE_RASTERIZATION_STATE_CREATE_FRAGMENT_DENSITY_MAP_ATTACHMENT_BIT_EXT = VK_PIPELINE_CREATE_RENDERING_FRAGMENT_DENSITY_MAP_ATTACHMENT_BIT_EXT,
  // Provided by VK_KHR_device_group
    VK_PIPELINE_CREATE_VIEW_INDEX_FROM_DEVICE_INDEX_BIT_KHR = VK_PIPELINE_CREATE_VIEW_INDEX_FROM_DEVICE_INDEX_BIT,
  // Provided by VK_KHR_device_group
    VK_PIPELINE_CREATE_DISPATCH_BASE_KHR = VK_PIPELINE_CREATE_DISPATCH_BASE,
  // Provided by VK_EXT_pipeline_creation_cache_control
    VK_PIPELINE_CREATE_FAIL_ON_PIPELINE_COMPILE_REQUIRED_BIT_EXT = VK_PIPELINE_CREATE_FAIL_ON_PIPELINE_COMPILE_REQUIRED_BIT,
  // Provided by VK_EXT_pipeline_creation_cache_control
    VK_PIPELINE_CREATE_EARLY_RETURN_ON_FAILURE_BIT_EXT = VK_PIPELINE_CREATE_EARLY_RETURN_ON_FAILURE_BIT,
} VkPipelineCreateFlagBits;

  • VK_PIPELINE_CREATE_DISABLE_OPTIMIZATION_BIT specifies that the created pipeline will not be optimized. Using this flag may reduce the time taken to create the pipeline.

  • VK_PIPELINE_CREATE_ALLOW_DERIVATIVES_BIT specifies that the pipeline to be created is allowed to be the parent of a pipeline that will be created in a subsequent pipeline creation call.

  • VK_PIPELINE_CREATE_DERIVATIVE_BIT specifies that the pipeline to be created will be a child of a previously created parent pipeline.

  • VK_PIPELINE_CREATE_VIEW_INDEX_FROM_DEVICE_INDEX_BIT specifies that any shader input variables decorated as ViewIndex will be assigned values as if they were decorated as DeviceIndex.

  • VK_PIPELINE_CREATE_DISPATCH_BASE specifies that a compute pipeline can be used with vkCmdDispatchBase with a non-zero base workgroup.

  • VK_PIPELINE_CREATE_DEFER_COMPILE_BIT_NV specifies that a pipeline is created with all shaders in the deferred state. Before using the pipeline the application must call vkCompileDeferredNV exactly once on each shader in the pipeline before using the pipeline.

  • VK_PIPELINE_CREATE_CAPTURE_STATISTICS_BIT_KHR specifies that the shader compiler should capture statistics for the pipeline executables produced by the compile process which can later be retrieved by calling vkGetPipelineExecutableStatisticsKHR. Enabling this flag must not affect the final compiled pipeline but may disable pipeline caching or otherwise affect pipeline creation time.

  • VK_PIPELINE_CREATE_CAPTURE_INTERNAL_REPRESENTATIONS_BIT_KHR specifies that the shader compiler should capture the internal representations of pipeline executables produced by the compile process which can later be retrieved by calling vkGetPipelineExecutableInternalRepresentationsKHR. Enabling this flag must not affect the final compiled pipeline but may disable pipeline caching or otherwise affect pipeline creation time. When capturing IR from pipelines created with pipeline libraries, there is no guarantee that IR from libraries can be retrieved from the linked pipeline. Applications should retrieve IR from each library, and any linked pipelines, separately.

  • VK_PIPELINE_CREATE_LIBRARY_BIT_KHR specifies that the pipeline cannot be used directly, and instead defines a pipeline library that can be combined with other pipelines using the VkPipelineLibraryCreateInfoKHR structure. This is available in ray tracing and graphics pipelines.

  • VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_ANY_HIT_SHADERS_BIT_KHR specifies that an any-hit shader will always be present when an any-hit shader would be executed. A NULL any-hit shader is an any-hit shader which is effectively VK_SHADER_UNUSED_KHR, such as from a shader group consisting entirely of zeros.

  • VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_CLOSEST_HIT_SHADERS_BIT_KHR specifies that a closest hit shader will always be present when a closest hit shader would be executed. A NULL closest hit shader is a closest hit shader which is effectively VK_SHADER_UNUSED_KHR, such as from a shader group consisting entirely of zeros.

  • VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_MISS_SHADERS_BIT_KHR specifies that a miss shader will always be present when a miss shader would be executed. A NULL miss shader is a miss shader which is effectively VK_SHADER_UNUSED_KHR, such as from a shader group consisting entirely of zeros.

  • VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_INTERSECTION_SHADERS_BIT_KHR specifies that an intersection shader will always be present when an intersection shader would be executed. A NULL intersection shader is an intersection shader which is effectively VK_SHADER_UNUSED_KHR, such as from a shader group consisting entirely of zeros.

  • VK_PIPELINE_CREATE_RAY_TRACING_SKIP_TRIANGLES_BIT_KHR specifies that triangle primitives will be skipped during traversal using pipeline trace ray instructions.

  • VK_PIPELINE_CREATE_RAY_TRACING_SKIP_AABBS_BIT_KHR specifies that AABB primitives will be skipped during traversal using pipeline trace ray instructions.

  • VK_PIPELINE_CREATE_RAY_TRACING_SHADER_GROUP_HANDLE_CAPTURE_REPLAY_BIT_KHR specifies that the shader group handles can be saved and reused on a subsequent run (e.g. for trace capture and replay).

  • VK_PIPELINE_CREATE_INDIRECT_BINDABLE_BIT_NV specifies that the pipeline can be used in combination with Device-Generated Commands.

  • VK_PIPELINE_CREATE_FAIL_ON_PIPELINE_COMPILE_REQUIRED_BIT specifies that pipeline creation will fail if a compile is required for creation of a valid VkPipeline object; VK_PIPELINE_COMPILE_REQUIRED will be returned by pipeline creation, and the VkPipeline will be set to VK_NULL_HANDLE.

  • When creating multiple pipelines, VK_PIPELINE_CREATE_EARLY_RETURN_ON_FAILURE_BIT specifies that control will be returned to the application if any individual pipeline returns a result which is not VK_SUCCESS rather than continuing to create additional pipelines.

  • VK_PIPELINE_CREATE_RAY_TRACING_ALLOW_MOTION_BIT_NV specifies that the pipeline is allowed to use OpTraceRayMotionNV.

  • VK_PIPELINE_CREATE_RENDERING_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR specifies that the pipeline will be used with a fragment shading rate attachment and dynamic rendering.

  • VK_PIPELINE_CREATE_RENDERING_FRAGMENT_DENSITY_MAP_ATTACHMENT_BIT_EXT specifies that the pipeline will be used with a fragment density map attachment and dynamic rendering.

  • VK_PIPELINE_CREATE_LINK_TIME_OPTIMIZATION_BIT_EXT specifies that pipeline libraries being linked into this library should have link time optimizations applied. If this bit is omitted, implementations should instead perform linking as rapidly as possible.

  • VK_PIPELINE_CREATE_RETAIN_LINK_TIME_OPTIMIZATION_INFO_BIT_EXT specifies that pipeline libraries should retain any information necessary to later perform an optimal link with VK_PIPELINE_CREATE_LINK_TIME_OPTIMIZATION_BIT_EXT.

  • VK_PIPELINE_CREATE_DESCRIPTOR_BUFFER_BIT_EXT specifies that a pipeline will be used with descriptor buffers, rather than descriptor sets.

  • VK_PIPELINE_CREATE_COLOR_ATTACHMENT_FEEDBACK_LOOP_BIT_EXT specifies that the pipeline may be used with an attachment feedback loop including color attachments. It is ignored if VK_DYNAMIC_STATE_ATTACHMENT_FEEDBACK_LOOP_ENABLE_EXT is set in pDynamicStates.

  • VK_PIPELINE_CREATE_DEPTH_STENCIL_ATTACHMENT_FEEDBACK_LOOP_BIT_EXT specifies that the pipeline may be used with an attachment feedback loop including depth-stencil attachments. It is ignored if VK_DYNAMIC_STATE_ATTACHMENT_FEEDBACK_LOOP_ENABLE_EXT is set in pDynamicStates.

  • VK_PIPELINE_CREATE_RAY_TRACING_OPACITY_MICROMAP_BIT_EXT specifies that the ray tracing pipeline can be used with acceleration structures which reference an opacity micromap array.

  • VK_PIPELINE_CREATE_RAY_TRACING_DISPLACEMENT_MICROMAP_BIT_NV specifies that the ray tracing pipeline can be used with acceleration structures which reference a displacement micromap array.

  • VK_PIPELINE_CREATE_NO_PROTECTED_ACCESS_BIT_EXT specifies that the pipeline must not be bound to a protected command buffer.

  • VK_PIPELINE_CREATE_PROTECTED_ACCESS_ONLY_BIT_EXT specifies that the pipeline must not be bound to an unprotected command buffer.

It is valid to set both VK_PIPELINE_CREATE_ALLOW_DERIVATIVES_BIT and VK_PIPELINE_CREATE_DERIVATIVE_BIT. This allows a pipeline to be both a parent and possibly a child in a pipeline hierarchy. See Pipeline Derivatives for more information.

When an implementation is looking up a pipeline in a pipeline cache, if that pipeline is being created using linked libraries, implementations should always return an equivalent pipeline created with VK_PIPELINE_CREATE_LINK_TIME_OPTIMIZATION_BIT_EXT if available, whether or not that bit was specified.

Note

Using VK_PIPELINE_CREATE_LINK_TIME_OPTIMIZATION_BIT_EXT (or not) when linking pipeline libraries is intended as a performance tradeoff between host and device. If the bit is omitted, linking should be faster and produce a pipeline more rapidly, but performance of the pipeline on the target device may be reduced. If the bit is included, linking may be slower but should produce a pipeline with device performance comparable to a monolithically created pipeline. Using both options can allow latency-sensitive applications to generate a suboptimal but usable pipeline quickly, and then perform an optimal link in the background, substituting the result for the suboptimally linked pipeline as soon as it is available.

 
// Provided by VK_VERSION_1_0
typedef VkFlags VkPipelineCreateFlags;

VkPipelineCreateFlags is a bitmask type for setting a mask of zero or more VkPipelineCreateFlagBits.

The VkPipelineBinaryInfoKHR structure is defined as:

// Provided by VK_KHR_pipeline_binary
typedef struct VkPipelineBinaryInfoKHR {
    VkStructureType               sType;
    const void*                   pNext;
    uint32_t                      binaryCount;
    const VkPipelineBinaryKHR*    pPipelineBinaries;
} VkPipelineBinaryInfoKHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • binaryCount is the number of elements in the pPipelineBinaries array.

  • pPipelineBinaries is a pointer to an array of VkPipelineBinaryKHR handles.

If a VkPipelineBinaryInfoKHR structure with a binaryCount greater than 0 is included in the pNext chain of any Vk*PipelineCreateInfo structure when creating a pipeline, implementations must use the data in pPipelineBinaries instead of recalculating it. Any shader module identifiers or shader modules declared in VkPipelineShaderStageCreateInfo instances are ignored.

If this structure is not included in the pNext chain, it is equivalent to specifying this structure with a binaryCount of 0.

Valid Usage

  • VUID-VkPipelineBinaryInfoKHR-binaryCount-09603
    binaryCount and the order of the elements in pPipelineBinaries must exactly match that returned by vkCreatePipelineBinariesKHR for the matching Vk*PipelineCreateInfo structure and its pNext chain, ignoring the presence of the VkPipelineBinaryInfoKHR structure, the presence of the VK_PIPELINE_CREATE_2_CAPTURE_DATA_BIT_KHR flag, and absence of any shader module identifiers or shader modules, for the same global pipeline key, from either:

Valid Usage (Implicit)

  • VUID-VkPipelineBinaryInfoKHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_PIPELINE_BINARY_INFO_KHR

  • VUID-VkPipelineBinaryInfoKHR-pPipelineBinaries-parameter
    If binaryCount is not 0, pPipelineBinaries must be a valid pointer to an array of binaryCount valid VkPipelineBinaryKHR handles

The VkGraphicsPipelineLibraryCreateInfoEXT structure is defined as:

// Provided by VK_EXT_graphics_pipeline_library
typedef struct VkGraphicsPipelineLibraryCreateInfoEXT {
    VkStructureType                      sType;
    const void*                          pNext;
    VkGraphicsPipelineLibraryFlagsEXT    flags;
} VkGraphicsPipelineLibraryCreateInfoEXT;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • flags is a bitmask of VkGraphicsPipelineLibraryFlagBitsEXT specifying the subsets of the graphics pipeline that are being compiled.

If a VkGraphicsPipelineLibraryCreateInfoEXT structure is included in the pNext chain of VkGraphicsPipelineCreateInfo, it specifies the subsets of the graphics pipeline being created, excluding any subsets from linked pipeline libraries. If the pipeline is created with pipeline libraries, state from those libraries is aggregated with said subset.

If this structure is omitted, and either VkGraphicsPipelineCreateInfo::flags includes VK_PIPELINE_CREATE_LIBRARY_BIT_KHR or the VkGraphicsPipelineCreateInfo::pNext chain includes a VkPipelineLibraryCreateInfoKHR structure with a libraryCount greater than 0, it is as if flags is 0. Otherwise if this structure is omitted, it is as if flags includes all possible subsets of the graphics pipeline (i.e. a complete graphics pipeline).

Valid Usage (Implicit)

  • VUID-VkGraphicsPipelineLibraryCreateInfoEXT-sType-sType
    sType must be VK_STRUCTURE_TYPE_GRAPHICS_PIPELINE_LIBRARY_CREATE_INFO_EXT

  • VUID-VkGraphicsPipelineLibraryCreateInfoEXT-flags-parameter
    flags must be a valid combination of VkGraphicsPipelineLibraryFlagBitsEXT values

  • VUID-VkGraphicsPipelineLibraryCreateInfoEXT-flags-requiredbitmask
    flags must not be 0

// Provided by VK_EXT_graphics_pipeline_library
typedef VkFlags VkGraphicsPipelineLibraryFlagsEXT;

VkGraphicsPipelineLibraryFlagsEXT is a bitmask type for setting a mask of zero or more VkGraphicsPipelineLibraryFlagBitsEXT.

Possible values of the flags member of VkGraphicsPipelineLibraryCreateInfoEXT, specifying the subsets of a graphics pipeline to compile are:

// Provided by VK_EXT_graphics_pipeline_library
typedef enum VkGraphicsPipelineLibraryFlagBitsEXT {
    VK_GRAPHICS_PIPELINE_LIBRARY_VERTEX_INPUT_INTERFACE_BIT_EXT = 0x00000001,
    VK_GRAPHICS_PIPELINE_LIBRARY_PRE_RASTERIZATION_SHADERS_BIT_EXT = 0x00000002,
    VK_GRAPHICS_PIPELINE_LIBRARY_FRAGMENT_SHADER_BIT_EXT = 0x00000004,
    VK_GRAPHICS_PIPELINE_LIBRARY_FRAGMENT_OUTPUT_INTERFACE_BIT_EXT = 0x00000008,
} VkGraphicsPipelineLibraryFlagBitsEXT;

The VkPipelineDynamicStateCreateInfo structure is defined as:

// Provided by VK_VERSION_1_0
typedef struct VkPipelineDynamicStateCreateInfo {
    VkStructureType                      sType;
    const void*                          pNext;
    VkPipelineDynamicStateCreateFlags    flags;
    uint32_t                             dynamicStateCount;
    const VkDynamicState*                pDynamicStates;
} VkPipelineDynamicStateCreateInfo;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • flags is reserved for future use.

  • dynamicStateCount is the number of elements in the pDynamicStates array.

  • pDynamicStates is a pointer to an array of VkDynamicState values specifying which pieces of pipeline state will use the values from dynamic state commands rather than from pipeline state creation information.

Valid Usage

  • VUID-VkPipelineDynamicStateCreateInfo-pDynamicStates-01442
    Each element of pDynamicStates must be unique

Valid Usage (Implicit)

  • VUID-VkPipelineDynamicStateCreateInfo-sType-sType
    sType must be VK_STRUCTURE_TYPE_PIPELINE_DYNAMIC_STATE_CREATE_INFO

  • VUID-VkPipelineDynamicStateCreateInfo-pNext-pNext
    pNext must be NULL

  • VUID-VkPipelineDynamicStateCreateInfo-flags-zerobitmask
    flags must be 0

  • VUID-VkPipelineDynamicStateCreateInfo-pDynamicStates-parameter
    If dynamicStateCount is not 0, pDynamicStates must be a valid pointer to an array of dynamicStateCount valid VkDynamicState values

// Provided by VK_VERSION_1_0
typedef VkFlags VkPipelineDynamicStateCreateFlags;

VkPipelineDynamicStateCreateFlags is a bitmask type for setting a mask, but is currently reserved for future use.

The source of different pieces of dynamic state is specified by the VkPipelineDynamicStateCreateInfo::pDynamicStates property of the currently active pipeline, each of whose elements must be one of the values:

// Provided by VK_VERSION_1_0
typedef enum VkDynamicState {
    VK_DYNAMIC_STATE_VIEWPORT = 0,
    VK_DYNAMIC_STATE_SCISSOR = 1,
    VK_DYNAMIC_STATE_LINE_WIDTH = 2,
    VK_DYNAMIC_STATE_DEPTH_BIAS = 3,
    VK_DYNAMIC_STATE_BLEND_CONSTANTS = 4,
    VK_DYNAMIC_STATE_DEPTH_BOUNDS = 5,
    VK_DYNAMIC_STATE_STENCIL_COMPARE_MASK = 6,
    VK_DYNAMIC_STATE_STENCIL_WRITE_MASK = 7,
    VK_DYNAMIC_STATE_STENCIL_REFERENCE = 8,
  // Provided by VK_VERSION_1_3
    VK_DYNAMIC_STATE_CULL_MODE = 1000267000,
  // Provided by VK_VERSION_1_3
    VK_DYNAMIC_STATE_FRONT_FACE = 1000267001,
  // Provided by VK_VERSION_1_3
    VK_DYNAMIC_STATE_PRIMITIVE_TOPOLOGY = 1000267002,
  // Provided by VK_VERSION_1_3
    VK_DYNAMIC_STATE_VIEWPORT_WITH_COUNT = 1000267003,
  // Provided by VK_VERSION_1_3
    VK_DYNAMIC_STATE_SCISSOR_WITH_COUNT = 1000267004,
  // Provided by VK_VERSION_1_3
    VK_DYNAMIC_STATE_VERTEX_INPUT_BINDING_STRIDE = 1000267005,
  // Provided by VK_VERSION_1_3
    VK_DYNAMIC_STATE_DEPTH_TEST_ENABLE = 1000267006,
  // Provided by VK_VERSION_1_3
    VK_DYNAMIC_STATE_DEPTH_WRITE_ENABLE = 1000267007,
  // Provided by VK_VERSION_1_3
    VK_DYNAMIC_STATE_DEPTH_COMPARE_OP = 1000267008,
  // Provided by VK_VERSION_1_3
    VK_DYNAMIC_STATE_DEPTH_BOUNDS_TEST_ENABLE = 1000267009,
  // Provided by VK_VERSION_1_3
    VK_DYNAMIC_STATE_STENCIL_TEST_ENABLE = 1000267010,
  // Provided by VK_VERSION_1_3
    VK_DYNAMIC_STATE_STENCIL_OP = 1000267011,
  // Provided by VK_VERSION_1_3
    VK_DYNAMIC_STATE_RASTERIZER_DISCARD_ENABLE = 1000377001,
  // Provided by VK_VERSION_1_3
    VK_DYNAMIC_STATE_DEPTH_BIAS_ENABLE = 1000377002,
  // Provided by VK_VERSION_1_3
    VK_DYNAMIC_STATE_PRIMITIVE_RESTART_ENABLE = 1000377004,
  // Provided by VK_NV_clip_space_w_scaling
    VK_DYNAMIC_STATE_VIEWPORT_W_SCALING_NV = 1000087000,
  // Provided by VK_EXT_discard_rectangles
    VK_DYNAMIC_STATE_DISCARD_RECTANGLE_EXT = 1000099000,
  // Provided by VK_EXT_discard_rectangles
    VK_DYNAMIC_STATE_DISCARD_RECTANGLE_ENABLE_EXT = 1000099001,
  // Provided by VK_EXT_discard_rectangles
    VK_DYNAMIC_STATE_DISCARD_RECTANGLE_MODE_EXT = 1000099002,
  // Provided by VK_EXT_sample_locations
    VK_DYNAMIC_STATE_SAMPLE_LOCATIONS_EXT = 1000143000,
  // Provided by VK_KHR_ray_tracing_pipeline
    VK_DYNAMIC_STATE_RAY_TRACING_PIPELINE_STACK_SIZE_KHR = 1000347000,
  // Provided by VK_NV_shading_rate_image
    VK_DYNAMIC_STATE_VIEWPORT_SHADING_RATE_PALETTE_NV = 1000164004,
  // Provided by VK_NV_shading_rate_image
    VK_DYNAMIC_STATE_VIEWPORT_COARSE_SAMPLE_ORDER_NV = 1000164006,
  // Provided by VK_NV_scissor_exclusive
    VK_DYNAMIC_STATE_EXCLUSIVE_SCISSOR_ENABLE_NV = 1000205000,
  // Provided by VK_NV_scissor_exclusive
    VK_DYNAMIC_STATE_EXCLUSIVE_SCISSOR_NV = 1000205001,
  // Provided by VK_KHR_fragment_shading_rate
    VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR = 1000226000,
  // Provided by VK_EXT_vertex_input_dynamic_state
    VK_DYNAMIC_STATE_VERTEX_INPUT_EXT = 1000352000,
  // Provided by VK_EXT_extended_dynamic_state2
    VK_DYNAMIC_STATE_PATCH_CONTROL_POINTS_EXT = 1000377000,
  // Provided by VK_EXT_extended_dynamic_state2
    VK_DYNAMIC_STATE_LOGIC_OP_EXT = 1000377003,
  // Provided by VK_EXT_color_write_enable
    VK_DYNAMIC_STATE_COLOR_WRITE_ENABLE_EXT = 1000381000,
  // Provided by VK_EXT_extended_dynamic_state3
    VK_DYNAMIC_STATE_DEPTH_CLAMP_ENABLE_EXT = 1000455003,
  // Provided by VK_EXT_extended_dynamic_state3
    VK_DYNAMIC_STATE_POLYGON_MODE_EXT = 1000455004,
  // Provided by VK_EXT_extended_dynamic_state3
    VK_DYNAMIC_STATE_RASTERIZATION_SAMPLES_EXT = 1000455005,
  // Provided by VK_EXT_extended_dynamic_state3
    VK_DYNAMIC_STATE_SAMPLE_MASK_EXT = 1000455006,
  // Provided by VK_EXT_extended_dynamic_state3
    VK_DYNAMIC_STATE_ALPHA_TO_COVERAGE_ENABLE_EXT = 1000455007,
  // Provided by VK_EXT_extended_dynamic_state3
    VK_DYNAMIC_STATE_ALPHA_TO_ONE_ENABLE_EXT = 1000455008,
  // Provided by VK_EXT_extended_dynamic_state3
    VK_DYNAMIC_STATE_LOGIC_OP_ENABLE_EXT = 1000455009,
  // Provided by VK_EXT_extended_dynamic_state3
    VK_DYNAMIC_STATE_COLOR_BLEND_ENABLE_EXT = 1000455010,
  // Provided by VK_EXT_extended_dynamic_state3
    VK_DYNAMIC_STATE_COLOR_BLEND_EQUATION_EXT = 1000455011,
  // Provided by VK_EXT_extended_dynamic_state3
    VK_DYNAMIC_STATE_COLOR_WRITE_MASK_EXT = 1000455012,
  // Provided by VK_EXT_extended_dynamic_state3 with VK_KHR_maintenance2 or VK_VERSION_1_1
    VK_DYNAMIC_STATE_TESSELLATION_DOMAIN_ORIGIN_EXT = 1000455002,
  // Provided by VK_EXT_extended_dynamic_state3 with VK_EXT_transform_feedback
    VK_DYNAMIC_STATE_RASTERIZATION_STREAM_EXT = 1000455013,
  // Provided by VK_EXT_conservative_rasterization with VK_EXT_extended_dynamic_state3
    VK_DYNAMIC_STATE_CONSERVATIVE_RASTERIZATION_MODE_EXT = 1000455014,
  // Provided by VK_EXT_conservative_rasterization with VK_EXT_extended_dynamic_state3
    VK_DYNAMIC_STATE_EXTRA_PRIMITIVE_OVERESTIMATION_SIZE_EXT = 1000455015,
  // Provided by VK_EXT_depth_clip_enable with VK_EXT_extended_dynamic_state3
    VK_DYNAMIC_STATE_DEPTH_CLIP_ENABLE_EXT = 1000455016,
  // Provided by VK_EXT_extended_dynamic_state3 with VK_EXT_sample_locations
    VK_DYNAMIC_STATE_SAMPLE_LOCATIONS_ENABLE_EXT = 1000455017,
  // Provided by VK_EXT_blend_operation_advanced with VK_EXT_extended_dynamic_state3
    VK_DYNAMIC_STATE_COLOR_BLEND_ADVANCED_EXT = 1000455018,
  // Provided by VK_EXT_extended_dynamic_state3 with VK_EXT_provoking_vertex
    VK_DYNAMIC_STATE_PROVOKING_VERTEX_MODE_EXT = 1000455019,
  // Provided by VK_EXT_extended_dynamic_state3 with VK_EXT_line_rasterization
    VK_DYNAMIC_STATE_LINE_RASTERIZATION_MODE_EXT = 1000455020,
  // Provided by VK_EXT_extended_dynamic_state3 with VK_EXT_line_rasterization
    VK_DYNAMIC_STATE_LINE_STIPPLE_ENABLE_EXT = 1000455021,
  // Provided by VK_EXT_depth_clip_control with VK_EXT_extended_dynamic_state3
    VK_DYNAMIC_STATE_DEPTH_CLIP_NEGATIVE_ONE_TO_ONE_EXT = 1000455022,
  // Provided by VK_EXT_extended_dynamic_state3 with VK_NV_clip_space_w_scaling
    VK_DYNAMIC_STATE_VIEWPORT_W_SCALING_ENABLE_NV = 1000455023,
  // Provided by VK_EXT_extended_dynamic_state3 with VK_NV_viewport_swizzle
    VK_DYNAMIC_STATE_VIEWPORT_SWIZZLE_NV = 1000455024,
  // Provided by VK_EXT_extended_dynamic_state3 with VK_NV_fragment_coverage_to_color
    VK_DYNAMIC_STATE_COVERAGE_TO_COLOR_ENABLE_NV = 1000455025,
  // Provided by VK_EXT_extended_dynamic_state3 with VK_NV_fragment_coverage_to_color
    VK_DYNAMIC_STATE_COVERAGE_TO_COLOR_LOCATION_NV = 1000455026,
  // Provided by VK_EXT_extended_dynamic_state3 with VK_NV_framebuffer_mixed_samples
    VK_DYNAMIC_STATE_COVERAGE_MODULATION_MODE_NV = 1000455027,
  // Provided by VK_EXT_extended_dynamic_state3 with VK_NV_framebuffer_mixed_samples
    VK_DYNAMIC_STATE_COVERAGE_MODULATION_TABLE_ENABLE_NV = 1000455028,
  // Provided by VK_EXT_extended_dynamic_state3 with VK_NV_framebuffer_mixed_samples
    VK_DYNAMIC_STATE_COVERAGE_MODULATION_TABLE_NV = 1000455029,
  // Provided by VK_EXT_extended_dynamic_state3 with VK_NV_shading_rate_image
    VK_DYNAMIC_STATE_SHADING_RATE_IMAGE_ENABLE_NV = 1000455030,
  // Provided by VK_EXT_extended_dynamic_state3 with VK_NV_representative_fragment_test
    VK_DYNAMIC_STATE_REPRESENTATIVE_FRAGMENT_TEST_ENABLE_NV = 1000455031,
  // Provided by VK_EXT_extended_dynamic_state3 with VK_NV_coverage_reduction_mode
    VK_DYNAMIC_STATE_COVERAGE_REDUCTION_MODE_NV = 1000455032,
  // Provided by VK_EXT_attachment_feedback_loop_dynamic_state
    VK_DYNAMIC_STATE_ATTACHMENT_FEEDBACK_LOOP_ENABLE_EXT = 1000524000,
  // Provided by VK_KHR_line_rasterization
    VK_DYNAMIC_STATE_LINE_STIPPLE_KHR = 1000259000,
  // Provided by VK_EXT_depth_clamp_control
    VK_DYNAMIC_STATE_DEPTH_CLAMP_RANGE_EXT = 1000582000,
  // Provided by VK_EXT_line_rasterization
    VK_DYNAMIC_STATE_LINE_STIPPLE_EXT = VK_DYNAMIC_STATE_LINE_STIPPLE_KHR,
  // Provided by VK_EXT_extended_dynamic_state
    VK_DYNAMIC_STATE_CULL_MODE_EXT = VK_DYNAMIC_STATE_CULL_MODE,
  // Provided by VK_EXT_extended_dynamic_state
    VK_DYNAMIC_STATE_FRONT_FACE_EXT = VK_DYNAMIC_STATE_FRONT_FACE,
  // Provided by VK_EXT_extended_dynamic_state
    VK_DYNAMIC_STATE_PRIMITIVE_TOPOLOGY_EXT = VK_DYNAMIC_STATE_PRIMITIVE_TOPOLOGY,
  // Provided by VK_EXT_extended_dynamic_state
    VK_DYNAMIC_STATE_VIEWPORT_WITH_COUNT_EXT = VK_DYNAMIC_STATE_VIEWPORT_WITH_COUNT,
  // Provided by VK_EXT_extended_dynamic_state
    VK_DYNAMIC_STATE_SCISSOR_WITH_COUNT_EXT = VK_DYNAMIC_STATE_SCISSOR_WITH_COUNT,
  // Provided by VK_EXT_extended_dynamic_state
    VK_DYNAMIC_STATE_VERTEX_INPUT_BINDING_STRIDE_EXT = VK_DYNAMIC_STATE_VERTEX_INPUT_BINDING_STRIDE,
  // Provided by VK_EXT_extended_dynamic_state
    VK_DYNAMIC_STATE_DEPTH_TEST_ENABLE_EXT = VK_DYNAMIC_STATE_DEPTH_TEST_ENABLE,
  // Provided by VK_EXT_extended_dynamic_state
    VK_DYNAMIC_STATE_DEPTH_WRITE_ENABLE_EXT = VK_DYNAMIC_STATE_DEPTH_WRITE_ENABLE,
  // Provided by VK_EXT_extended_dynamic_state
    VK_DYNAMIC_STATE_DEPTH_COMPARE_OP_EXT = VK_DYNAMIC_STATE_DEPTH_COMPARE_OP,
  // Provided by VK_EXT_extended_dynamic_state
    VK_DYNAMIC_STATE_DEPTH_BOUNDS_TEST_ENABLE_EXT = VK_DYNAMIC_STATE_DEPTH_BOUNDS_TEST_ENABLE,
  // Provided by VK_EXT_extended_dynamic_state
    VK_DYNAMIC_STATE_STENCIL_TEST_ENABLE_EXT = VK_DYNAMIC_STATE_STENCIL_TEST_ENABLE,
  // Provided by VK_EXT_extended_dynamic_state
    VK_DYNAMIC_STATE_STENCIL_OP_EXT = VK_DYNAMIC_STATE_STENCIL_OP,
  // Provided by VK_EXT_extended_dynamic_state2
    VK_DYNAMIC_STATE_RASTERIZER_DISCARD_ENABLE_EXT = VK_DYNAMIC_STATE_RASTERIZER_DISCARD_ENABLE,
  // Provided by VK_EXT_extended_dynamic_state2
    VK_DYNAMIC_STATE_DEPTH_BIAS_ENABLE_EXT = VK_DYNAMIC_STATE_DEPTH_BIAS_ENABLE,
  // Provided by VK_EXT_extended_dynamic_state2
    VK_DYNAMIC_STATE_PRIMITIVE_RESTART_ENABLE_EXT = VK_DYNAMIC_STATE_PRIMITIVE_RESTART_ENABLE,
} VkDynamicState;

10.3.1. Valid Combinations of Stages for Graphics Pipelines

Primitive processing can be handled either on a per primitive basis by the vertex, tessellation, and geometry shader stages, or on a per mesh basis using task and mesh shader stages. If the pipeline includes a mesh shader stage, it uses the mesh pipeline, otherwise it uses the primitive pipeline.

If a task shader is omitted, the task shading stage is skipped.

If tessellation shader stages are omitted, the tessellation shading and fixed-function stages of the pipeline are skipped.

If a geometry shader is omitted, the geometry shading stage is skipped.

If a fragment shader is omitted, fragment color outputs have undefined values, and the fragment depth value is determined by Fragment Operations state. This can be useful for depth-only rendering.

Presence of a shader stage in a pipeline is indicated by including a valid VkPipelineShaderStageCreateInfo with module and pName selecting an entry point from a shader module, where that entry point is valid for the stage specified by stage.

Presence of some of the fixed-function stages in the pipeline is implicitly derived from enabled shaders and provided state. For example, the fixed-function tessellator is always present when the pipeline has valid Tessellation Control and Tessellation Evaluation shaders.

For example:

10.3.2. Graphics Pipeline Shader Groups

Graphics pipelines can contain multiple shader groups that can be bound individually. Each shader group behaves as if it was a pipeline using the shader group’s state. When the pipeline is bound by regular means, it behaves as if the state of group 0 is active, use vkCmdBindPipelineShaderGroupNV to bind an individual shader group.

The primary purpose of shader groups is allowing the device to bind different pipeline state using Device-Generated Commands.

The VkGraphicsPipelineShaderGroupsCreateInfoNV structure is defined as:

// Provided by VK_NV_device_generated_commands
typedef struct VkGraphicsPipelineShaderGroupsCreateInfoNV {
    VkStructureType                             sType;
    const void*                                 pNext;
    uint32_t                                    groupCount;
    const VkGraphicsShaderGroupCreateInfoNV*    pGroups;
    uint32_t                                    pipelineCount;
    const VkPipeline*                           pPipelines;
} VkGraphicsPipelineShaderGroupsCreateInfoNV;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • groupCount is the number of elements in the pGroups array.

  • pGroups is a pointer to an array of VkGraphicsShaderGroupCreateInfoNV structures specifying which state of the original VkGraphicsPipelineCreateInfo each shader group overrides.

  • pipelineCount is the number of elements in the pPipelines array.

  • pPipelines is a pointer to an array of graphics VkPipeline structures which are referenced within the created pipeline, including all their shader groups.

When referencing shader groups by index, groups defined in the referenced pipelines are treated as if they were defined as additional entries in pGroups. They are appended in the order they appear in the pPipelines array and in the pGroups array when those pipelines were defined.

The application must maintain the lifetime of all such referenced pipelines based on the pipelines that make use of them.

Valid Usage

  • VUID-VkGraphicsPipelineShaderGroupsCreateInfoNV-groupCount-02879
    groupCount must be at least 1 and as maximum VkPhysicalDeviceDeviceGeneratedCommandsPropertiesNV::maxGraphicsShaderGroupCount

  • VUID-VkGraphicsPipelineShaderGroupsCreateInfoNV-groupCount-02880
    The sum of groupCount including those groups added from referenced pPipelines must also be as maximum VkPhysicalDeviceDeviceGeneratedCommandsPropertiesNV::maxGraphicsShaderGroupCount

  • VUID-VkGraphicsPipelineShaderGroupsCreateInfoNV-pGroups-02881
    The state of the first element of pGroups must match its equivalent within the parent’s VkGraphicsPipelineCreateInfo

  • VUID-VkGraphicsPipelineShaderGroupsCreateInfoNV-pGroups-02882
    Each element of pGroups must in combination with the rest of the pipeline state yield a valid state configuration

  • VUID-VkGraphicsPipelineShaderGroupsCreateInfoNV-pGroups-02884
    All elements of pGroups must use the same shader stage combinations unless any mesh shader stage is used, then either combination of task and mesh or just mesh shader is valid

  • VUID-VkGraphicsPipelineShaderGroupsCreateInfoNV-pGroups-02885
    Mesh and regular primitive shading stages cannot be mixed across pGroups

  • VUID-VkGraphicsPipelineShaderGroupsCreateInfoNV-pPipelines-02886
    Each element of pPipelines must have been created with identical state to the pipeline currently created except the state that can be overridden by VkGraphicsShaderGroupCreateInfoNV

  • VUID-VkGraphicsPipelineShaderGroupsCreateInfoNV-deviceGeneratedCommands-02887
    The deviceGeneratedCommands feature must be enabled

Valid Usage (Implicit)

  • VUID-VkGraphicsPipelineShaderGroupsCreateInfoNV-sType-sType
    sType must be VK_STRUCTURE_TYPE_GRAPHICS_PIPELINE_SHADER_GROUPS_CREATE_INFO_NV

  • VUID-VkGraphicsPipelineShaderGroupsCreateInfoNV-pGroups-parameter
    If groupCount is not 0, pGroups must be a valid pointer to an array of groupCount valid VkGraphicsShaderGroupCreateInfoNV structures

  • VUID-VkGraphicsPipelineShaderGroupsCreateInfoNV-pPipelines-parameter
    If pipelineCount is not 0, pPipelines must be a valid pointer to an array of pipelineCount valid VkPipeline handles

The VkGraphicsShaderGroupCreateInfoNV structure provides the state overrides for each shader group. Each shader group behaves like a pipeline that was created from its state as well as the remaining parent’s state. It is defined as:

// Provided by VK_NV_device_generated_commands
typedef struct VkGraphicsShaderGroupCreateInfoNV {
    VkStructureType                                 sType;
    const void*                                     pNext;
    uint32_t                                        stageCount;
    const VkPipelineShaderStageCreateInfo*          pStages;
    const VkPipelineVertexInputStateCreateInfo*     pVertexInputState;
    const VkPipelineTessellationStateCreateInfo*    pTessellationState;
} VkGraphicsShaderGroupCreateInfoNV;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • stageCount is the number of entries in the pStages array.

  • pStages is a pointer to an array VkPipelineShaderStageCreateInfo structures specifying the set of the shader stages to be included in this shader group.

  • pVertexInputState is a pointer to a VkPipelineVertexInputStateCreateInfo structure.

  • pTessellationState is a pointer to a VkPipelineTessellationStateCreateInfo structure, and is ignored if the shader group does not include a tessellation control shader stage and tessellation evaluation shader stage.

Valid Usage

  • VUID-VkGraphicsShaderGroupCreateInfoNV-stageCount-02888
    For stageCount, the same restrictions as in VkGraphicsPipelineCreateInfo::stageCount apply

  • VUID-VkGraphicsShaderGroupCreateInfoNV-pStages-02889
    For pStages, the same restrictions as in VkGraphicsPipelineCreateInfo::pStages apply

  • VUID-VkGraphicsShaderGroupCreateInfoNV-pVertexInputState-02890
    For pVertexInputState, the same restrictions as in VkGraphicsPipelineCreateInfo::pVertexInputState apply

  • VUID-VkGraphicsShaderGroupCreateInfoNV-pTessellationState-02891
    For pTessellationState, the same restrictions as in VkGraphicsPipelineCreateInfo::pTessellationState apply

Valid Usage (Implicit)

  • VUID-VkGraphicsShaderGroupCreateInfoNV-sType-sType
    sType must be VK_STRUCTURE_TYPE_GRAPHICS_SHADER_GROUP_CREATE_INFO_NV

  • VUID-VkGraphicsShaderGroupCreateInfoNV-pNext-pNext
    pNext must be NULL

  • VUID-VkGraphicsShaderGroupCreateInfoNV-pStages-parameter
    pStages must be a valid pointer to an array of stageCount valid VkPipelineShaderStageCreateInfo structures

  • VUID-VkGraphicsShaderGroupCreateInfoNV-stageCount-arraylength
    stageCount must be greater than 0

10.4. Ray Tracing Pipelines

Ray tracing pipelines consist of multiple shader stages, fixed-function traversal stages, and a pipeline layout.

VK_SHADER_UNUSED_KHR is a special shader index used to indicate that a ray generation, miss, or callable shader member is not used.

#define VK_SHADER_UNUSED_KHR              (~0U)

or the equivalent

#define VK_SHADER_UNUSED_NV               VK_SHADER_UNUSED_KHR

To create ray tracing pipelines, call:

// Provided by VK_NV_ray_tracing
VkResult vkCreateRayTracingPipelinesNV(
    VkDevice                                    device,
    VkPipelineCache                             pipelineCache,
    uint32_t                                    createInfoCount,
    const VkRayTracingPipelineCreateInfoNV*     pCreateInfos,
    const VkAllocationCallbacks*                pAllocator,
    VkPipeline*                                 pPipelines);

  • device is the logical device that creates the ray tracing pipelines.

  • pipelineCache is either VK_NULL_HANDLE, indicating that pipeline caching is disabled, or the handle of a valid pipeline cache object, in which case use of that cache is enabled for the duration of the command.

  • createInfoCount is the length of the pCreateInfos and pPipelines arrays.

  • pCreateInfos is a pointer to an array of VkRayTracingPipelineCreateInfoNV structures.

  • pAllocator controls host memory allocation as described in the Memory Allocation chapter.

  • pPipelines is a pointer to an array in which the resulting ray tracing pipeline objects are returned.

Pipelines are created and returned as described for Multiple Pipeline Creation.

Valid Usage

  • VUID-vkCreateRayTracingPipelinesNV-device-09677
    device must support at least one queue family with the VK_QUEUE_COMPUTE_BIT capability

  • VUID-vkCreateRayTracingPipelinesNV-flags-03415
    If the flags member of any element of pCreateInfos contains the VK_PIPELINE_CREATE_DERIVATIVE_BIT flag, and the basePipelineIndex member of that same element is not -1, basePipelineIndex must be less than the index into pCreateInfos that corresponds to that element

  • VUID-vkCreateRayTracingPipelinesNV-flags-03416
    If the flags member of any element of pCreateInfos contains the VK_PIPELINE_CREATE_DERIVATIVE_BIT flag, the base pipeline must have been created with the VK_PIPELINE_CREATE_ALLOW_DERIVATIVES_BIT flag set

  • VUID-vkCreateRayTracingPipelinesNV-flags-03816
    flags must not contain the VK_PIPELINE_CREATE_DISPATCH_BASE flag

  • VUID-vkCreateRayTracingPipelinesNV-pipelineCache-02903
    If pipelineCache was created with VK_PIPELINE_CACHE_CREATE_EXTERNALLY_SYNCHRONIZED_BIT, host access to pipelineCache must be externally synchronized

  • VUID-vkCreateRayTracingPipelinesNV-pNext-09616
    If VkPipelineBinaryInfoKHR::binaryCount is not 0 for any element of pCreateInfos, pipelineCache must be VK_NULL_HANDLE

  • VUID-vkCreateRayTracingPipelinesNV-pNext-09617
    If a VkPipelineCreateFlags2CreateInfoKHR structure with the VK_PIPELINE_CREATE_2_CAPTURE_DATA_BIT_KHR flag set is included in the pNext chain of any element of pCreateInfos, pipelineCache must be VK_NULL_HANDLE

  • VUID-vkCreateRayTracingPipelinesNV-binaryCount-09620
    If VkPipelineBinaryInfoKHR::binaryCount is not 0 for any element of pCreateInfos, VK_PIPELINE_CREATION_FEEDBACK_APPLICATION_PIPELINE_CACHE_HIT_BIT must not be set in the flags of that element

  • VUID-vkCreateRayTracingPipelinesNV-binaryCount-09621
    If VkPipelineBinaryInfoKHR::binaryCount is not 0 for any element of pCreateInfos, VK_PIPELINE_CREATION_FEEDBACK_BASE_PIPELINE_ACCELERATION_BIT must not be set in the flags of that element

  • VUID-vkCreateRayTracingPipelinesNV-binaryCount-09622
    If VkPipelineBinaryInfoKHR::binaryCount is not 0 for any element of pCreateInfos, VK_PIPELINE_CREATE_FAIL_ON_PIPELINE_COMPILE_REQUIRED_BIT_EXT must not be set in the flags of that element

  • VUID-vkCreateRayTracingPipelinesNV-pNext-10150
    If a VkPipelineCreateFlags2CreateInfoKHR structure is included in the pNext chain of any element of pCreateInfos, VK_PIPELINE_CREATE_2_CAPTURE_DATA_BIT_KHR flag must not be set

Valid Usage (Implicit)

  • VUID-vkCreateRayTracingPipelinesNV-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkCreateRayTracingPipelinesNV-pipelineCache-parameter
    If pipelineCache is not VK_NULL_HANDLE, pipelineCache must be a valid VkPipelineCache handle

  • VUID-vkCreateRayTracingPipelinesNV-pCreateInfos-parameter
    pCreateInfos must be a valid pointer to an array of createInfoCount valid VkRayTracingPipelineCreateInfoNV structures

  • VUID-vkCreateRayTracingPipelinesNV-pAllocator-parameter
    If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure

  • VUID-vkCreateRayTracingPipelinesNV-pPipelines-parameter
    pPipelines must be a valid pointer to an array of createInfoCount VkPipeline handles

  • VUID-vkCreateRayTracingPipelinesNV-createInfoCount-arraylength
    createInfoCount must be greater than 0

  • VUID-vkCreateRayTracingPipelinesNV-pipelineCache-parent
    If pipelineCache is a valid handle, it must have been created, allocated, or retrieved from device

Return Codes
Success

  • VK_SUCCESS

  • VK_PIPELINE_COMPILE_REQUIRED_EXT

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

  • VK_ERROR_INVALID_SHADER_NV

To create ray tracing pipelines, call:

// Provided by VK_KHR_ray_tracing_pipeline
VkResult vkCreateRayTracingPipelinesKHR(
    VkDevice                                    device,
    VkDeferredOperationKHR                      deferredOperation,
    VkPipelineCache                             pipelineCache,
    uint32_t                                    createInfoCount,
    const VkRayTracingPipelineCreateInfoKHR*    pCreateInfos,
    const VkAllocationCallbacks*                pAllocator,
    VkPipeline*                                 pPipelines);

  • device is the logical device that creates the ray tracing pipelines.

  • deferredOperation is VK_NULL_HANDLE or the handle of a valid VkDeferredOperationKHR request deferral object for this command.

  • pipelineCache is either VK_NULL_HANDLE, indicating that pipeline caching is disabled, or the handle of a valid pipeline cache object, in which case use of that cache is enabled for the duration of the command.

  • createInfoCount is the length of the pCreateInfos and pPipelines arrays.

  • pCreateInfos is a pointer to an array of VkRayTracingPipelineCreateInfoKHR structures.

  • pAllocator controls host memory allocation as described in the Memory Allocation chapter.

  • pPipelines is a pointer to an array in which the resulting ray tracing pipeline objects are returned.

The VK_ERROR_INVALID_OPAQUE_CAPTURE_ADDRESS error is returned if the implementation is unable to reuse the shader group handles provided in VkRayTracingShaderGroupCreateInfoKHR::pShaderGroupCaptureReplayHandle when VkPhysicalDeviceRayTracingPipelineFeaturesKHR::rayTracingPipelineShaderGroupHandleCaptureReplay is enabled.

Pipelines are created and returned as described for Multiple Pipeline Creation.

Valid Usage

  • VUID-vkCreateRayTracingPipelinesKHR-device-09677
    device must support at least one queue family with the VK_QUEUE_COMPUTE_BIT capability

  • VUID-vkCreateRayTracingPipelinesKHR-flags-03415
    If the flags member of any element of pCreateInfos contains the VK_PIPELINE_CREATE_DERIVATIVE_BIT flag, and the basePipelineIndex member of that same element is not -1, basePipelineIndex must be less than the index into pCreateInfos that corresponds to that element

  • VUID-vkCreateRayTracingPipelinesKHR-flags-03416
    If the flags member of any element of pCreateInfos contains the VK_PIPELINE_CREATE_DERIVATIVE_BIT flag, the base pipeline must have been created with the VK_PIPELINE_CREATE_ALLOW_DERIVATIVES_BIT flag set

  • VUID-vkCreateRayTracingPipelinesKHR-flags-03816
    flags must not contain the VK_PIPELINE_CREATE_DISPATCH_BASE flag

  • VUID-vkCreateRayTracingPipelinesKHR-pipelineCache-02903
    If pipelineCache was created with VK_PIPELINE_CACHE_CREATE_EXTERNALLY_SYNCHRONIZED_BIT, host access to pipelineCache must be externally synchronized

  • VUID-vkCreateRayTracingPipelinesKHR-deferredOperation-03678
    Any previous deferred operation that was associated with deferredOperation must be complete

  • VUID-vkCreateRayTracingPipelinesKHR-pNext-09616
    If VkPipelineBinaryInfoKHR::binaryCount is not 0 for any element of pCreateInfos, pipelineCache must be VK_NULL_HANDLE

  • VUID-vkCreateRayTracingPipelinesKHR-pNext-09617
    If a VkPipelineCreateFlags2CreateInfoKHR structure with the VK_PIPELINE_CREATE_2_CAPTURE_DATA_BIT_KHR flag set is included in the pNext chain of any element of pCreateInfos, pipelineCache must be VK_NULL_HANDLE

  • VUID-vkCreateRayTracingPipelinesKHR-binaryCount-09620
    If VkPipelineBinaryInfoKHR::binaryCount is not 0 for any element of pCreateInfos, VK_PIPELINE_CREATION_FEEDBACK_APPLICATION_PIPELINE_CACHE_HIT_BIT must not be set in the flags of that element

  • VUID-vkCreateRayTracingPipelinesKHR-binaryCount-09621
    If VkPipelineBinaryInfoKHR::binaryCount is not 0 for any element of pCreateInfos, VK_PIPELINE_CREATION_FEEDBACK_BASE_PIPELINE_ACCELERATION_BIT must not be set in the flags of that element

  • VUID-vkCreateRayTracingPipelinesKHR-binaryCount-09622
    If VkPipelineBinaryInfoKHR::binaryCount is not 0 for any element of pCreateInfos, VK_PIPELINE_CREATE_FAIL_ON_PIPELINE_COMPILE_REQUIRED_BIT_EXT must not be set in the flags of that element

  • VUID-vkCreateRayTracingPipelinesKHR-rayTracingPipeline-03586
    The rayTracingPipeline feature must be enabled

  • VUID-vkCreateRayTracingPipelinesKHR-deferredOperation-03587
    If deferredOperation is not VK_NULL_HANDLE, the flags member of elements of pCreateInfos must not include VK_PIPELINE_CREATE_EARLY_RETURN_ON_FAILURE_BIT

Valid Usage (Implicit)

  • VUID-vkCreateRayTracingPipelinesKHR-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkCreateRayTracingPipelinesKHR-deferredOperation-parameter
    If deferredOperation is not VK_NULL_HANDLE, deferredOperation must be a valid VkDeferredOperationKHR handle

  • VUID-vkCreateRayTracingPipelinesKHR-pipelineCache-parameter
    If pipelineCache is not VK_NULL_HANDLE, pipelineCache must be a valid VkPipelineCache handle

  • VUID-vkCreateRayTracingPipelinesKHR-pCreateInfos-parameter
    pCreateInfos must be a valid pointer to an array of createInfoCount valid VkRayTracingPipelineCreateInfoKHR structures

  • VUID-vkCreateRayTracingPipelinesKHR-pAllocator-parameter
    If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure

  • VUID-vkCreateRayTracingPipelinesKHR-pPipelines-parameter
    pPipelines must be a valid pointer to an array of createInfoCount VkPipeline handles

  • VUID-vkCreateRayTracingPipelinesKHR-createInfoCount-arraylength
    createInfoCount must be greater than 0

  • VUID-vkCreateRayTracingPipelinesKHR-deferredOperation-parent
    If deferredOperation is a valid handle, it must have been created, allocated, or retrieved from device

  • VUID-vkCreateRayTracingPipelinesKHR-pipelineCache-parent
    If pipelineCache is a valid handle, it must have been created, allocated, or retrieved from device

Return Codes
Success

  • VK_SUCCESS

  • VK_OPERATION_DEFERRED_KHR

  • VK_OPERATION_NOT_DEFERRED_KHR

  • VK_PIPELINE_COMPILE_REQUIRED_EXT

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

  • VK_ERROR_INVALID_OPAQUE_CAPTURE_ADDRESS

The VkRayTracingPipelineCreateInfoNV structure is defined as:

// Provided by VK_NV_ray_tracing
typedef struct VkRayTracingPipelineCreateInfoNV {
    VkStructureType                               sType;
    const void*                                   pNext;
    VkPipelineCreateFlags                         flags;
    uint32_t                                      stageCount;
    const VkPipelineShaderStageCreateInfo*        pStages;
    uint32_t                                      groupCount;
    const VkRayTracingShaderGroupCreateInfoNV*    pGroups;
    uint32_t                                      maxRecursionDepth;
    VkPipelineLayout                              layout;
    VkPipeline                                    basePipelineHandle;
    int32_t                                       basePipelineIndex;
} VkRayTracingPipelineCreateInfoNV;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • flags is a bitmask of VkPipelineCreateFlagBits specifying how the pipeline will be generated.

  • stageCount is the number of entries in the pStages array.

  • pStages is a pointer to an array of VkPipelineShaderStageCreateInfo structures specifying the set of the shader stages to be included in the ray tracing pipeline.

  • groupCount is the number of entries in the pGroups array.

  • pGroups is a pointer to an array of VkRayTracingShaderGroupCreateInfoNV structures describing the set of the shader stages to be included in each shader group in the ray tracing pipeline.

  • maxRecursionDepth is the maximum recursion depth of shaders executed by this pipeline.

  • layout is the description of binding locations used by both the pipeline and descriptor sets used with the pipeline.

  • basePipelineHandle is a pipeline to derive from.

  • basePipelineIndex is an index into the pCreateInfos parameter to use as a pipeline to derive from.

The parameters basePipelineHandle and basePipelineIndex are described in more detail in Pipeline Derivatives.

If the pNext chain includes a VkPipelineCreateFlags2CreateInfoKHR structure, VkPipelineCreateFlags2CreateInfoKHR::flags from that structure is used instead of flags from this structure.

Valid Usage

  • VUID-VkRayTracingPipelineCreateInfoNV-None-09497
    If the pNext chain does not include a VkPipelineCreateFlags2CreateInfoKHR structure, flags must be a valid combination of VkPipelineCreateFlagBits values

  • VUID-VkRayTracingPipelineCreateInfoNV-flags-07984
    If flags contains the VK_PIPELINE_CREATE_DERIVATIVE_BIT flag, and basePipelineIndex is -1, basePipelineHandle must be a valid ray tracing VkPipeline handle

  • VUID-VkRayTracingPipelineCreateInfoNV-flags-07985
    If flags contains the VK_PIPELINE_CREATE_DERIVATIVE_BIT flag, and basePipelineHandle is VK_NULL_HANDLE, basePipelineIndex must be a valid index into the calling command’s pCreateInfos parameter

  • VUID-VkRayTracingPipelineCreateInfoNV-flags-07986
    If flags contains the VK_PIPELINE_CREATE_DERIVATIVE_BIT flag, basePipelineIndex must be -1 or basePipelineHandle must be VK_NULL_HANDLE

  • VUID-VkRayTracingPipelineCreateInfoNV-layout-07987
    If a push constant block is declared in a shader, a push constant range in layout must match the shader stage

  • VUID-VkRayTracingPipelineCreateInfoNV-layout-10069
    If a push constant block is declared in a shader, the block must be contained inside the push constant range in layout that matches the stage

  • VUID-VkRayTracingPipelineCreateInfoNV-layout-07988
    If a resource variables is declared in a shader, a descriptor slot in layout must match the shader stage

  • VUID-VkRayTracingPipelineCreateInfoNV-layout-07990
    If a resource variables is declared in a shader, and the descriptor type is not VK_DESCRIPTOR_TYPE_MUTABLE_EXT, a descriptor slot in layout must match the descriptor type

  • VUID-VkRayTracingPipelineCreateInfoNV-layout-07991
    If a resource variables is declared in a shader as an array, a descriptor slot in layout must match the descriptor count

  • VUID-VkRayTracingPipelineCreateInfoNV-pStages-03426
    The shader code for the entry points identified by pStages, and the rest of the state identified by this structure must adhere to the pipeline linking rules described in the Shader Interfaces chapter

  • VUID-VkRayTracingPipelineCreateInfoNV-layout-03428
    The number of resources in layout accessible to each shader stage that is used by the pipeline must be less than or equal to VkPhysicalDeviceLimits::maxPerStageResources

  • VUID-VkRayTracingPipelineCreateInfoNV-flags-02904
    flags must not include VK_PIPELINE_CREATE_INDIRECT_BINDABLE_BIT_NV

  • VUID-VkRayTracingPipelineCreateInfoNV-flags-11008
    flags must not include VK_PIPELINE_CREATE_2_INDIRECT_BINDABLE_BIT_EXT

  • VUID-VkRayTracingPipelineCreateInfoNV-pipelineCreationCacheControl-02905
    If the pipelineCreationCacheControl feature is not enabled, flags must not include VK_PIPELINE_CREATE_FAIL_ON_PIPELINE_COMPILE_REQUIRED_BIT or VK_PIPELINE_CREATE_EARLY_RETURN_ON_FAILURE_BIT

  • VUID-VkRayTracingPipelineCreateInfoNV-stage-06232
    The stage member of at least one element of pStages must be VK_SHADER_STAGE_RAYGEN_BIT_KHR

  • VUID-VkRayTracingPipelineCreateInfoNV-flags-03456
    flags must not include VK_PIPELINE_CREATE_LIBRARY_BIT_KHR

  • VUID-VkRayTracingPipelineCreateInfoNV-maxRecursionDepth-03457
    maxRecursionDepth must be less than or equal to VkPhysicalDeviceRayTracingPropertiesNV::maxRecursionDepth

  • VUID-VkRayTracingPipelineCreateInfoNV-flags-03458
    flags must not include VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_ANY_HIT_SHADERS_BIT_KHR

  • VUID-VkRayTracingPipelineCreateInfoNV-flags-03459
    flags must not include VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_CLOSEST_HIT_SHADERS_BIT_KHR

  • VUID-VkRayTracingPipelineCreateInfoNV-flags-03460
    flags must not include VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_MISS_SHADERS_BIT_KHR

  • VUID-VkRayTracingPipelineCreateInfoNV-flags-03461
    flags must not include VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_INTERSECTION_SHADERS_BIT_KHR

  • VUID-VkRayTracingPipelineCreateInfoNV-flags-03462
    flags must not include VK_PIPELINE_CREATE_RAY_TRACING_SKIP_AABBS_BIT_KHR

  • VUID-VkRayTracingPipelineCreateInfoNV-flags-03463
    flags must not include VK_PIPELINE_CREATE_RAY_TRACING_SKIP_TRIANGLES_BIT_KHR

  • VUID-VkRayTracingPipelineCreateInfoNV-flags-03588
    flags must not include VK_PIPELINE_CREATE_RAY_TRACING_SHADER_GROUP_HANDLE_CAPTURE_REPLAY_BIT_KHR

  • VUID-VkRayTracingPipelineCreateInfoNV-flags-04948
    flags must not include VK_PIPELINE_CREATE_RAY_TRACING_ALLOW_MOTION_BIT_NV

  • VUID-VkRayTracingPipelineCreateInfoNV-flags-02957
    flags must not include both VK_PIPELINE_CREATE_DEFER_COMPILE_BIT_NV and VK_PIPELINE_CREATE_FAIL_ON_PIPELINE_COMPILE_REQUIRED_BIT at the same time

  • VUID-VkRayTracingPipelineCreateInfoNV-pipelineStageCreationFeedbackCount-06651
    If VkPipelineCreationFeedbackCreateInfo::pipelineStageCreationFeedbackCount is not 0, it must be equal to stageCount

  • VUID-VkRayTracingPipelineCreateInfoNV-stage-06898
    The stage value in all pStages elements must be one of VK_SHADER_STAGE_RAYGEN_BIT_KHR, VK_SHADER_STAGE_ANY_HIT_BIT_KHR, VK_SHADER_STAGE_CLOSEST_HIT_BIT_KHR, VK_SHADER_STAGE_MISS_BIT_KHR, VK_SHADER_STAGE_INTERSECTION_BIT_KHR, or VK_SHADER_STAGE_CALLABLE_BIT_KHR

  • VUID-VkRayTracingPipelineCreateInfoNV-flags-07402
    flags must not include VK_PIPELINE_CREATE_RAY_TRACING_OPACITY_MICROMAP_BIT_EXT

  • VUID-VkRayTracingPipelineCreateInfoNV-flags-07998
    flags must not include VK_PIPELINE_CREATE_RAY_TRACING_DISPLACEMENT_MICROMAP_BIT_NV

Valid Usage (Implicit)

  • VUID-VkRayTracingPipelineCreateInfoNV-sType-sType
    sType must be VK_STRUCTURE_TYPE_RAY_TRACING_PIPELINE_CREATE_INFO_NV

  • VUID-VkRayTracingPipelineCreateInfoNV-pNext-pNext
    Each pNext member of any structure (including this one) in the pNext chain must be either NULL or a pointer to a valid instance of VkPipelineCreateFlags2CreateInfoKHR or VkPipelineCreationFeedbackCreateInfo

  • VUID-VkRayTracingPipelineCreateInfoNV-sType-unique
    The sType value of each struct in the pNext chain must be unique

  • VUID-VkRayTracingPipelineCreateInfoNV-pStages-parameter
    pStages must be a valid pointer to an array of stageCount valid VkPipelineShaderStageCreateInfo structures

  • VUID-VkRayTracingPipelineCreateInfoNV-pGroups-parameter
    pGroups must be a valid pointer to an array of groupCount valid VkRayTracingShaderGroupCreateInfoNV structures

  • VUID-VkRayTracingPipelineCreateInfoNV-layout-parameter
    layout must be a valid VkPipelineLayout handle

  • VUID-VkRayTracingPipelineCreateInfoNV-stageCount-arraylength
    stageCount must be greater than 0

  • VUID-VkRayTracingPipelineCreateInfoNV-groupCount-arraylength
    groupCount must be greater than 0

  • VUID-VkRayTracingPipelineCreateInfoNV-commonparent
    Both of basePipelineHandle, and layout that are valid handles of non-ignored parameters must have been created, allocated, or retrieved from the same VkDevice

The VkRayTracingPipelineCreateInfoKHR structure is defined as:

// Provided by VK_KHR_ray_tracing_pipeline
typedef struct VkRayTracingPipelineCreateInfoKHR {
    VkStructureType                                      sType;
    const void*                                          pNext;
    VkPipelineCreateFlags                                flags;
    uint32_t                                             stageCount;
    const VkPipelineShaderStageCreateInfo*               pStages;
    uint32_t                                             groupCount;
    const VkRayTracingShaderGroupCreateInfoKHR*          pGroups;
    uint32_t                                             maxPipelineRayRecursionDepth;
    const VkPipelineLibraryCreateInfoKHR*                pLibraryInfo;
    const VkRayTracingPipelineInterfaceCreateInfoKHR*    pLibraryInterface;
    const VkPipelineDynamicStateCreateInfo*              pDynamicState;
    VkPipelineLayout                                     layout;
    VkPipeline                                           basePipelineHandle;
    int32_t                                              basePipelineIndex;
} VkRayTracingPipelineCreateInfoKHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • flags is a bitmask of VkPipelineCreateFlagBits specifying how the pipeline will be generated.

  • stageCount is the number of entries in the pStages array.

  • pStages is a pointer to an array of stageCount VkPipelineShaderStageCreateInfo structures describing the set of the shader stages to be included in the ray tracing pipeline.

  • groupCount is the number of entries in the pGroups array.

  • pGroups is a pointer to an array of groupCount VkRayTracingShaderGroupCreateInfoKHR structures describing the set of the shader stages to be included in each shader group in the ray tracing pipeline.

  • maxPipelineRayRecursionDepth is the maximum recursion depth of shaders executed by this pipeline.

  • pLibraryInfo is a pointer to a VkPipelineLibraryCreateInfoKHR structure defining pipeline libraries to include.

  • pLibraryInterface is a pointer to a VkRayTracingPipelineInterfaceCreateInfoKHR structure defining additional information when using pipeline libraries.

  • pDynamicState is a pointer to a VkPipelineDynamicStateCreateInfo structure, and is used to indicate which properties of the pipeline state object are dynamic and can be changed independently of the pipeline state. This can be NULL, which means no state in the pipeline is considered dynamic.

  • layout is the description of binding locations used by both the pipeline and descriptor sets used with the pipeline.

  • basePipelineHandle is a pipeline to derive from.

  • basePipelineIndex is an index into the pCreateInfos parameter to use as a pipeline to derive from.

The parameters basePipelineHandle and basePipelineIndex are described in more detail in Pipeline Derivatives.

When VK_PIPELINE_CREATE_LIBRARY_BIT_KHR is specified, this pipeline defines a pipeline library which cannot be bound as a ray tracing pipeline directly. Instead, pipeline libraries define common shaders and shader groups which can be included in future pipeline creation.

If pipeline libraries are included in pLibraryInfo, shaders defined in those libraries are treated as if they were defined as additional entries in pStages, appended in the order they appear in the pLibraries array and in the pStages array when those libraries were defined.

When referencing shader groups in order to obtain a shader group handle, groups defined in those libraries are treated as if they were defined as additional entries in pGroups, appended in the order they appear in the pLibraries array and in the pGroups array when those libraries were defined. The shaders these groups reference are set when the pipeline library is created, referencing those specified in the pipeline library, not in the pipeline that includes it.

The default stack size for a pipeline if VK_DYNAMIC_STATE_RAY_TRACING_PIPELINE_STACK_SIZE_KHR is not provided is computed as described in Ray Tracing Pipeline Stack.

If the pNext chain includes a VkPipelineCreateFlags2CreateInfoKHR structure, VkPipelineCreateFlags2CreateInfoKHR::flags from that structure is used instead of flags from this structure.

Valid Usage

  • VUID-VkRayTracingPipelineCreateInfoKHR-None-09497
    If the pNext chain does not include a VkPipelineCreateFlags2CreateInfoKHR structure, flags must be a valid combination of VkPipelineCreateFlagBits values

  • VUID-VkRayTracingPipelineCreateInfoKHR-flags-07984
    If flags contains the VK_PIPELINE_CREATE_DERIVATIVE_BIT flag, and basePipelineIndex is -1, basePipelineHandle must be a valid ray tracing VkPipeline handle

  • VUID-VkRayTracingPipelineCreateInfoKHR-flags-07985
    If flags contains the VK_PIPELINE_CREATE_DERIVATIVE_BIT flag, and basePipelineHandle is VK_NULL_HANDLE, basePipelineIndex must be a valid index into the calling command’s pCreateInfos parameter

  • VUID-VkRayTracingPipelineCreateInfoKHR-flags-07986
    If flags contains the VK_PIPELINE_CREATE_DERIVATIVE_BIT flag, basePipelineIndex must be -1 or basePipelineHandle must be VK_NULL_HANDLE

  • VUID-VkRayTracingPipelineCreateInfoKHR-layout-07987
    If a push constant block is declared in a shader, a push constant range in layout must match the shader stage

  • VUID-VkRayTracingPipelineCreateInfoKHR-layout-10069
    If a push constant block is declared in a shader, the block must be contained inside the push constant range in layout that matches the stage

  • VUID-VkRayTracingPipelineCreateInfoKHR-layout-07988
    If a resource variables is declared in a shader, a descriptor slot in layout must match the shader stage

  • VUID-VkRayTracingPipelineCreateInfoKHR-layout-07990
    If a resource variables is declared in a shader, and the descriptor type is not VK_DESCRIPTOR_TYPE_MUTABLE_EXT, a descriptor slot in layout must match the descriptor type

  • VUID-VkRayTracingPipelineCreateInfoKHR-layout-07991
    If a resource variables is declared in a shader as an array, a descriptor slot in layout must match the descriptor count

  • VUID-VkRayTracingPipelineCreateInfoKHR-pStages-03426
    The shader code for the entry points identified by pStages, and the rest of the state identified by this structure must adhere to the pipeline linking rules described in the Shader Interfaces chapter

  • VUID-VkRayTracingPipelineCreateInfoKHR-layout-03428
    The number of resources in layout accessible to each shader stage that is used by the pipeline must be less than or equal to VkPhysicalDeviceLimits::maxPerStageResources

  • VUID-VkRayTracingPipelineCreateInfoKHR-flags-02904
    flags must not include VK_PIPELINE_CREATE_INDIRECT_BINDABLE_BIT_NV

  • VUID-VkRayTracingPipelineCreateInfoKHR-flags-11008
    flags must not include VK_PIPELINE_CREATE_2_INDIRECT_BINDABLE_BIT_EXT

  • VUID-VkRayTracingPipelineCreateInfoKHR-pipelineCreationCacheControl-02905
    If the pipelineCreationCacheControl feature is not enabled, flags must not include VK_PIPELINE_CREATE_FAIL_ON_PIPELINE_COMPILE_REQUIRED_BIT or VK_PIPELINE_CREATE_EARLY_RETURN_ON_FAILURE_BIT

  • VUID-VkRayTracingPipelineCreateInfoKHR-stage-03425
    If flags does not include VK_PIPELINE_CREATE_LIBRARY_BIT_KHR, the stage member of at least one element of pStages, including those implicitly added by pLibraryInfo, must be VK_SHADER_STAGE_RAYGEN_BIT_KHR

  • VUID-VkRayTracingPipelineCreateInfoKHR-maxPipelineRayRecursionDepth-03589
    maxPipelineRayRecursionDepth must be less than or equal to VkPhysicalDeviceRayTracingPipelinePropertiesKHR::maxRayRecursionDepth

  • VUID-VkRayTracingPipelineCreateInfoKHR-flags-03465
    If flags includes VK_PIPELINE_CREATE_LIBRARY_BIT_KHR, pLibraryInterface must not be NULL

  • VUID-VkRayTracingPipelineCreateInfoKHR-pLibraryInfo-03590
    If pLibraryInfo is not NULL and its libraryCount member is greater than 0, pLibraryInterface must not be NULL

  • VUID-VkRayTracingPipelineCreateInfoKHR-pLibraries-03591
    Each element of pLibraryInfo->pLibraries must have been created with the value of maxPipelineRayRecursionDepth equal to that in this pipeline

  • VUID-VkRayTracingPipelineCreateInfoKHR-pLibraryInfo-03592
    If pLibraryInfo is not NULL, each element of its pLibraries member must have been created with a layout that is compatible with the layout in this pipeline

  • VUID-VkRayTracingPipelineCreateInfoKHR-pLibraryInfo-03593
    If pLibraryInfo is not NULL, each element of its pLibraries member must have been created with values of the maxPipelineRayPayloadSize and maxPipelineRayHitAttributeSize members of pLibraryInterface equal to those in this pipeline

  • VUID-VkRayTracingPipelineCreateInfoKHR-flags-03594
    If flags includes VK_PIPELINE_CREATE_RAY_TRACING_SHADER_GROUP_HANDLE_CAPTURE_REPLAY_BIT_KHR, each element of pLibraryInfo->pLibraries must have been created with the VK_PIPELINE_CREATE_RAY_TRACING_SHADER_GROUP_HANDLE_CAPTURE_REPLAY_BIT_KHR bit set

  • VUID-VkRayTracingPipelineCreateInfoKHR-flags-04718
    If flags includes VK_PIPELINE_CREATE_RAY_TRACING_SKIP_AABBS_BIT_KHR, each element of pLibraryInfo->pLibraries must have been created with the VK_PIPELINE_CREATE_RAY_TRACING_SKIP_AABBS_BIT_KHR bit set

  • VUID-VkRayTracingPipelineCreateInfoKHR-flags-04719
    If flags includes VK_PIPELINE_CREATE_RAY_TRACING_SKIP_TRIANGLES_BIT_KHR, each element of pLibraryInfo->pLibraries must have been created with the VK_PIPELINE_CREATE_RAY_TRACING_SKIP_TRIANGLES_BIT_KHR bit set

  • VUID-VkRayTracingPipelineCreateInfoKHR-flags-04720
    If flags includes VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_ANY_HIT_SHADERS_BIT_KHR, each element of pLibraryInfo->pLibraries must have been created with the VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_ANY_HIT_SHADERS_BIT_KHR bit set

  • VUID-VkRayTracingPipelineCreateInfoKHR-flags-04721
    If flags includes VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_CLOSEST_HIT_SHADERS_BIT_KHR, each element of pLibraryInfo->pLibraries must have been created with the VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_CLOSEST_HIT_SHADERS_BIT_KHR bit set

  • VUID-VkRayTracingPipelineCreateInfoKHR-flags-04722
    If flags includes VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_INTERSECTION_SHADERS_BIT_KHR, each element of pLibraryInfo->pLibraries must have been created with the VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_INTERSECTION_SHADERS_BIT_KHR bit set

  • VUID-VkRayTracingPipelineCreateInfoKHR-flags-04723
    If flags includes VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_MISS_SHADERS_BIT_KHR, each element of pLibraryInfo->pLibraries must have been created with the VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_MISS_SHADERS_BIT_KHR bit set

  • VUID-VkRayTracingPipelineCreateInfoKHR-pLibraryInfo-03595
    If the VK_KHR_pipeline_library extension is not enabled, pLibraryInfo and pLibraryInterface must be NULL

  • VUID-VkRayTracingPipelineCreateInfoKHR-flags-03470
    If flags includes VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_ANY_HIT_SHADERS_BIT_KHR, for any element of pGroups with a type of VK_RAY_TRACING_SHADER_GROUP_TYPE_TRIANGLES_HIT_GROUP_KHR or VK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_KHR, the anyHitShader of that element must not be VK_SHADER_UNUSED_KHR

  • VUID-VkRayTracingPipelineCreateInfoKHR-flags-03471
    If flags includes VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_CLOSEST_HIT_SHADERS_BIT_KHR, for any element of pGroups with a type of VK_RAY_TRACING_SHADER_GROUP_TYPE_TRIANGLES_HIT_GROUP_KHR or VK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_KHR, the closestHitShader of that element must not be VK_SHADER_UNUSED_KHR

  • VUID-VkRayTracingPipelineCreateInfoKHR-rayTraversalPrimitiveCulling-03596
    If the rayTraversalPrimitiveCulling feature is not enabled, flags must not include VK_PIPELINE_CREATE_RAY_TRACING_SKIP_AABBS_BIT_KHR

  • VUID-VkRayTracingPipelineCreateInfoKHR-rayTraversalPrimitiveCulling-03597
    If the rayTraversalPrimitiveCulling feature is not enabled, flags must not include VK_PIPELINE_CREATE_RAY_TRACING_SKIP_TRIANGLES_BIT_KHR

  • VUID-VkRayTracingPipelineCreateInfoKHR-flags-06546
    flags must not include both VK_PIPELINE_CREATE_RAY_TRACING_SKIP_TRIANGLES_BIT_KHR and VK_PIPELINE_CREATE_RAY_TRACING_SKIP_AABBS_BIT_KHR

  • VUID-VkRayTracingPipelineCreateInfoKHR-flags-03598
    If flags includes VK_PIPELINE_CREATE_RAY_TRACING_SHADER_GROUP_HANDLE_CAPTURE_REPLAY_BIT_KHR, rayTracingPipelineShaderGroupHandleCaptureReplay must be enabled

  • VUID-VkRayTracingPipelineCreateInfoKHR-rayTracingPipelineShaderGroupHandleCaptureReplay-03599
    If VkPhysicalDeviceRayTracingPipelineFeaturesKHR::rayTracingPipelineShaderGroupHandleCaptureReplay is VK_TRUE and the pShaderGroupCaptureReplayHandle member of any element of pGroups is not NULL, flags must include VK_PIPELINE_CREATE_RAY_TRACING_SHADER_GROUP_HANDLE_CAPTURE_REPLAY_BIT_KHR

  • VUID-VkRayTracingPipelineCreateInfoKHR-pLibraryInfo-07999
    If pLibraryInfo is NULL or its libraryCount is 0, stageCount must not be 0

  • VUID-VkRayTracingPipelineCreateInfoKHR-flags-08700
    If flags does not include VK_PIPELINE_CREATE_LIBRARY_BIT_KHR and either pLibraryInfo is NULL or its libraryCount is 0, groupCount must not be 0

  • VUID-VkRayTracingPipelineCreateInfoKHR-pDynamicStates-03602
    Any element of the pDynamicStates member of pDynamicState must be VK_DYNAMIC_STATE_RAY_TRACING_PIPELINE_STACK_SIZE_KHR

  • VUID-VkRayTracingPipelineCreateInfoKHR-pipelineStageCreationFeedbackCount-06652
    If VkPipelineCreationFeedbackCreateInfo::pipelineStageCreationFeedbackCount is not 0, it must be equal to stageCount

  • VUID-VkRayTracingPipelineCreateInfoKHR-stage-06899
    The stage value in all pStages elements must be one of VK_SHADER_STAGE_RAYGEN_BIT_KHR, VK_SHADER_STAGE_ANY_HIT_BIT_KHR, VK_SHADER_STAGE_CLOSEST_HIT_BIT_KHR, VK_SHADER_STAGE_MISS_BIT_KHR, VK_SHADER_STAGE_INTERSECTION_BIT_KHR, or VK_SHADER_STAGE_CALLABLE_BIT_KHR

  • VUID-VkRayTracingPipelineCreateInfoKHR-flags-07403
    If flags includes VK_PIPELINE_CREATE_RAY_TRACING_OPACITY_MICROMAP_BIT_EXT, each element of pLibraryInfo->pLibraries must have been created with the VK_PIPELINE_CREATE_RAY_TRACING_OPACITY_MICROMAP_BIT_EXT bit set

  • VUID-VkRayTracingPipelineCreateInfoKHR-flags-08701
    If flags includes VK_PIPELINE_CREATE_RAY_TRACING_DISPLACEMENT_MICROMAP_BIT_NV, each element of pLibraryInfo->pLibraries must have been created with the VK_PIPELINE_CREATE_RAY_TRACING_DISPLACEMENT_MICROMAP_BIT_NV bit set

Valid Usage (Implicit)

  • VUID-VkRayTracingPipelineCreateInfoKHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_RAY_TRACING_PIPELINE_CREATE_INFO_KHR

  • VUID-VkRayTracingPipelineCreateInfoKHR-pNext-pNext
    Each pNext member of any structure (including this one) in the pNext chain must be either NULL or a pointer to a valid instance of VkPipelineBinaryInfoKHR, VkPipelineCreateFlags2CreateInfoKHR, VkPipelineCreationFeedbackCreateInfo, or VkPipelineRobustnessCreateInfoEXT

  • VUID-VkRayTracingPipelineCreateInfoKHR-sType-unique
    The sType value of each struct in the pNext chain must be unique

  • VUID-VkRayTracingPipelineCreateInfoKHR-pStages-parameter
    If stageCount is not 0, pStages must be a valid pointer to an array of stageCount valid VkPipelineShaderStageCreateInfo structures

  • VUID-VkRayTracingPipelineCreateInfoKHR-pGroups-parameter
    If groupCount is not 0, pGroups must be a valid pointer to an array of groupCount valid VkRayTracingShaderGroupCreateInfoKHR structures

  • VUID-VkRayTracingPipelineCreateInfoKHR-pLibraryInfo-parameter
    If pLibraryInfo is not NULL, pLibraryInfo must be a valid pointer to a valid VkPipelineLibraryCreateInfoKHR structure

  • VUID-VkRayTracingPipelineCreateInfoKHR-pLibraryInterface-parameter
    If pLibraryInterface is not NULL, pLibraryInterface must be a valid pointer to a valid VkRayTracingPipelineInterfaceCreateInfoKHR structure

  • VUID-VkRayTracingPipelineCreateInfoKHR-pDynamicState-parameter
    If pDynamicState is not NULL, pDynamicState must be a valid pointer to a valid VkPipelineDynamicStateCreateInfo structure

  • VUID-VkRayTracingPipelineCreateInfoKHR-layout-parameter
    layout must be a valid VkPipelineLayout handle

  • VUID-VkRayTracingPipelineCreateInfoKHR-commonparent
    Both of basePipelineHandle, and layout that are valid handles of non-ignored parameters must have been created, allocated, or retrieved from the same VkDevice

The VkRayTracingShaderGroupCreateInfoNV structure is defined as:

// Provided by VK_NV_ray_tracing
typedef struct VkRayTracingShaderGroupCreateInfoNV {
    VkStructureType                   sType;
    const void*                       pNext;
    VkRayTracingShaderGroupTypeKHR    type;
    uint32_t                          generalShader;
    uint32_t                          closestHitShader;
    uint32_t                          anyHitShader;
    uint32_t                          intersectionShader;
} VkRayTracingShaderGroupCreateInfoNV;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • type is the type of hit group specified in this structure.

  • generalShader is the index of the ray generation, miss, or callable shader from VkRayTracingPipelineCreateInfoNV::pStages in the group if the shader group has type of VK_RAY_TRACING_SHADER_GROUP_TYPE_GENERAL_NV, and VK_SHADER_UNUSED_NV otherwise.

  • closestHitShader is the optional index of the closest hit shader from VkRayTracingPipelineCreateInfoNV::pStages in the group if the shader group has type of VK_RAY_TRACING_SHADER_GROUP_TYPE_TRIANGLES_HIT_GROUP_NV or VK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_NV, and VK_SHADER_UNUSED_NV otherwise.

  • anyHitShader is the optional index of the any-hit shader from VkRayTracingPipelineCreateInfoNV::pStages in the group if the shader group has type of VK_RAY_TRACING_SHADER_GROUP_TYPE_TRIANGLES_HIT_GROUP_NV or VK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_NV, and VK_SHADER_UNUSED_NV otherwise.

  • intersectionShader is the index of the intersection shader from VkRayTracingPipelineCreateInfoNV::pStages in the group if the shader group has type of VK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_NV, and VK_SHADER_UNUSED_NV otherwise.

Valid Usage

  • VUID-VkRayTracingShaderGroupCreateInfoNV-type-02413
    If type is VK_RAY_TRACING_SHADER_GROUP_TYPE_GENERAL_NV then generalShader must be a valid index into VkRayTracingPipelineCreateInfoNV::pStages referring to a shader of VK_SHADER_STAGE_RAYGEN_BIT_NV, VK_SHADER_STAGE_MISS_BIT_NV, or VK_SHADER_STAGE_CALLABLE_BIT_NV

  • VUID-VkRayTracingShaderGroupCreateInfoNV-type-02414
    If type is VK_RAY_TRACING_SHADER_GROUP_TYPE_GENERAL_NV then closestHitShader, anyHitShader, and intersectionShader must be VK_SHADER_UNUSED_NV

  • VUID-VkRayTracingShaderGroupCreateInfoNV-type-02415
    If type is VK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_NV then intersectionShader must be a valid index into VkRayTracingPipelineCreateInfoNV::pStages referring to a shader of VK_SHADER_STAGE_INTERSECTION_BIT_NV

  • VUID-VkRayTracingShaderGroupCreateInfoNV-type-02416
    If type is VK_RAY_TRACING_SHADER_GROUP_TYPE_TRIANGLES_HIT_GROUP_NV then intersectionShader must be VK_SHADER_UNUSED_NV

  • VUID-VkRayTracingShaderGroupCreateInfoNV-closestHitShader-02417
    closestHitShader must be either VK_SHADER_UNUSED_NV or a valid index into VkRayTracingPipelineCreateInfoNV::pStages referring to a shader of VK_SHADER_STAGE_CLOSEST_HIT_BIT_NV

  • VUID-VkRayTracingShaderGroupCreateInfoNV-anyHitShader-02418
    anyHitShader must be either VK_SHADER_UNUSED_NV or a valid index into VkRayTracingPipelineCreateInfoNV::pStages referring to a shader of VK_SHADER_STAGE_ANY_HIT_BIT_NV

Valid Usage (Implicit)

  • VUID-VkRayTracingShaderGroupCreateInfoNV-sType-sType
    sType must be VK_STRUCTURE_TYPE_RAY_TRACING_SHADER_GROUP_CREATE_INFO_NV

  • VUID-VkRayTracingShaderGroupCreateInfoNV-pNext-pNext
    pNext must be NULL

  • VUID-VkRayTracingShaderGroupCreateInfoNV-type-parameter
    type must be a valid VkRayTracingShaderGroupTypeKHR value

The VkRayTracingShaderGroupCreateInfoKHR structure is defined as:

// Provided by VK_KHR_ray_tracing_pipeline
typedef struct VkRayTracingShaderGroupCreateInfoKHR {
    VkStructureType                   sType;
    const void*                       pNext;
    VkRayTracingShaderGroupTypeKHR    type;
    uint32_t                          generalShader;
    uint32_t                          closestHitShader;
    uint32_t                          anyHitShader;
    uint32_t                          intersectionShader;
    const void*                       pShaderGroupCaptureReplayHandle;
} VkRayTracingShaderGroupCreateInfoKHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • type is the type of hit group specified in this structure.

  • generalShader is the index of the ray generation, miss, or callable shader from VkRayTracingPipelineCreateInfoKHR::pStages in the group if the shader group has type of VK_RAY_TRACING_SHADER_GROUP_TYPE_GENERAL_KHR, and VK_SHADER_UNUSED_KHR otherwise.

  • closestHitShader is the optional index of the closest hit shader from VkRayTracingPipelineCreateInfoKHR::pStages in the group if the shader group has type of VK_RAY_TRACING_SHADER_GROUP_TYPE_TRIANGLES_HIT_GROUP_KHR or VK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_KHR, and VK_SHADER_UNUSED_KHR otherwise.

  • anyHitShader is the optional index of the any-hit shader from VkRayTracingPipelineCreateInfoKHR::pStages in the group if the shader group has type of VK_RAY_TRACING_SHADER_GROUP_TYPE_TRIANGLES_HIT_GROUP_KHR or VK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_KHR, and VK_SHADER_UNUSED_KHR otherwise.

  • intersectionShader is the index of the intersection shader from VkRayTracingPipelineCreateInfoKHR::pStages in the group if the shader group has type of VK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_KHR, and VK_SHADER_UNUSED_KHR otherwise.

  • pShaderGroupCaptureReplayHandle is NULL or a pointer to replay information for this shader group queried from vkGetRayTracingCaptureReplayShaderGroupHandlesKHR, as described in Ray Tracing Capture Replay. Ignored if VkPhysicalDeviceRayTracingPipelineFeaturesKHR::rayTracingPipelineShaderGroupHandleCaptureReplay is VK_FALSE.

If the pipeline is created with VK_PIPELINE_CREATE_LIBRARY_BIT_KHR and the pipelineLibraryGroupHandles feature is enabled, pShaderGroupCaptureReplayHandle is inherited by all pipelines which link against this pipeline and remains bitwise identical for any pipeline which references this pipeline library.

Valid Usage

  • VUID-VkRayTracingShaderGroupCreateInfoKHR-type-03474
    If type is VK_RAY_TRACING_SHADER_GROUP_TYPE_GENERAL_KHR then generalShader must be a valid index into VkRayTracingPipelineCreateInfoKHR::pStages referring to a shader of VK_SHADER_STAGE_RAYGEN_BIT_KHR, VK_SHADER_STAGE_MISS_BIT_KHR, or VK_SHADER_STAGE_CALLABLE_BIT_KHR

  • VUID-VkRayTracingShaderGroupCreateInfoKHR-type-03475
    If type is VK_RAY_TRACING_SHADER_GROUP_TYPE_GENERAL_KHR then closestHitShader, anyHitShader, and intersectionShader must be VK_SHADER_UNUSED_KHR

  • VUID-VkRayTracingShaderGroupCreateInfoKHR-type-03476
    If type is VK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_KHR then intersectionShader must be a valid index into VkRayTracingPipelineCreateInfoKHR::pStages referring to a shader of VK_SHADER_STAGE_INTERSECTION_BIT_KHR

  • VUID-VkRayTracingShaderGroupCreateInfoKHR-type-03477
    If type is VK_RAY_TRACING_SHADER_GROUP_TYPE_TRIANGLES_HIT_GROUP_KHR then intersectionShader must be VK_SHADER_UNUSED_KHR

  • VUID-VkRayTracingShaderGroupCreateInfoKHR-closestHitShader-03478
    closestHitShader must be either VK_SHADER_UNUSED_KHR or a valid index into VkRayTracingPipelineCreateInfoKHR::pStages referring to a shader of VK_SHADER_STAGE_CLOSEST_HIT_BIT_KHR

  • VUID-VkRayTracingShaderGroupCreateInfoKHR-anyHitShader-03479
    anyHitShader must be either VK_SHADER_UNUSED_KHR or a valid index into VkRayTracingPipelineCreateInfoKHR::pStages referring to a shader of VK_SHADER_STAGE_ANY_HIT_BIT_KHR

  • VUID-VkRayTracingShaderGroupCreateInfoKHR-rayTracingPipelineShaderGroupHandleCaptureReplayMixed-03603
    If VkPhysicalDeviceRayTracingPipelineFeaturesKHR::rayTracingPipelineShaderGroupHandleCaptureReplayMixed is VK_FALSE then pShaderGroupCaptureReplayHandle must not be provided if it has not been provided on a previous call to ray tracing pipeline creation

  • VUID-VkRayTracingShaderGroupCreateInfoKHR-rayTracingPipelineShaderGroupHandleCaptureReplayMixed-03604
    If VkPhysicalDeviceRayTracingPipelineFeaturesKHR::rayTracingPipelineShaderGroupHandleCaptureReplayMixed is VK_FALSE then the caller must guarantee that no ray tracing pipeline creation commands with pShaderGroupCaptureReplayHandle provided execute simultaneously with ray tracing pipeline creation commands without pShaderGroupCaptureReplayHandle provided

Valid Usage (Implicit)

  • VUID-VkRayTracingShaderGroupCreateInfoKHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_RAY_TRACING_SHADER_GROUP_CREATE_INFO_KHR

  • VUID-VkRayTracingShaderGroupCreateInfoKHR-pNext-pNext
    pNext must be NULL

  • VUID-VkRayTracingShaderGroupCreateInfoKHR-type-parameter
    type must be a valid VkRayTracingShaderGroupTypeKHR value

Possible values of type in VkRayTracingShaderGroupCreateInfoKHR are:

// Provided by VK_KHR_ray_tracing_pipeline
typedef enum VkRayTracingShaderGroupTypeKHR {
    VK_RAY_TRACING_SHADER_GROUP_TYPE_GENERAL_KHR = 0,
    VK_RAY_TRACING_SHADER_GROUP_TYPE_TRIANGLES_HIT_GROUP_KHR = 1,
    VK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_KHR = 2,
  // Provided by VK_NV_ray_tracing
    VK_RAY_TRACING_SHADER_GROUP_TYPE_GENERAL_NV = VK_RAY_TRACING_SHADER_GROUP_TYPE_GENERAL_KHR,
  // Provided by VK_NV_ray_tracing
    VK_RAY_TRACING_SHADER_GROUP_TYPE_TRIANGLES_HIT_GROUP_NV = VK_RAY_TRACING_SHADER_GROUP_TYPE_TRIANGLES_HIT_GROUP_KHR,
  // Provided by VK_NV_ray_tracing
    VK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_NV = VK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_KHR,
} VkRayTracingShaderGroupTypeKHR;

or the equivalent

// Provided by VK_NV_ray_tracing
typedef VkRayTracingShaderGroupTypeKHR VkRayTracingShaderGroupTypeNV;

  • VK_RAY_TRACING_SHADER_GROUP_TYPE_GENERAL_KHR indicates a shader group with a single VK_SHADER_STAGE_RAYGEN_BIT_KHR, VK_SHADER_STAGE_MISS_BIT_KHR, or VK_SHADER_STAGE_CALLABLE_BIT_KHR shader in it.

  • VK_RAY_TRACING_SHADER_GROUP_TYPE_TRIANGLES_HIT_GROUP_KHR specifies a shader group that only hits triangles and must not contain an intersection shader, only closest hit and any-hit shaders.

  • VK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_KHR specifies a shader group that only intersects with custom geometry and must contain an intersection shader and may contain closest hit and any-hit shaders.

Note

For current group types, the hit group type could be inferred from the presence or absence of the intersection shader, but we provide the type explicitly for future hit groups that do not have that property.

The VkRayTracingPipelineInterfaceCreateInfoKHR structure is defined as:

// Provided by VK_KHR_ray_tracing_pipeline
typedef struct VkRayTracingPipelineInterfaceCreateInfoKHR {
    VkStructureType    sType;
    const void*        pNext;
    uint32_t           maxPipelineRayPayloadSize;
    uint32_t           maxPipelineRayHitAttributeSize;
} VkRayTracingPipelineInterfaceCreateInfoKHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • maxPipelineRayPayloadSize is the maximum payload size in bytes used by any shader in the pipeline.

  • maxPipelineRayHitAttributeSize is the maximum attribute structure size in bytes used by any shader in the pipeline.

maxPipelineRayPayloadSize is calculated as the maximum number of bytes used by any block declared in the RayPayloadKHR or IncomingRayPayloadKHR storage classes. maxPipelineRayHitAttributeSize is calculated as the maximum number of bytes used by any block declared in the HitAttributeKHR storage class. As variables in these storage classes do not have explicit offsets, the size should be calculated as if each variable has a scalar alignment equal to the largest scalar alignment of any of the block’s members.

Note

There is no explicit upper limit for maxPipelineRayPayloadSize, but in practice it should be kept as small as possible. Similar to invocation local memory, it must be allocated for each shader invocation and for devices which support many simultaneous invocations, this storage can rapidly be exhausted, resulting in failure.
Valid Usage
Valid Usage (Implicit)

  • VUID-VkRayTracingPipelineInterfaceCreateInfoKHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_RAY_TRACING_PIPELINE_INTERFACE_CREATE_INFO_KHR

  • VUID-VkRayTracingPipelineInterfaceCreateInfoKHR-pNext-pNext
    pNext must be NULL

To query the opaque handles of shaders in the ray tracing pipeline, call:

// Provided by VK_KHR_ray_tracing_pipeline
VkResult vkGetRayTracingShaderGroupHandlesKHR(
    VkDevice                                    device,
    VkPipeline                                  pipeline,
    uint32_t                                    firstGroup,
    uint32_t                                    groupCount,
    size_t                                      dataSize,
    void*                                       pData);

or the equivalent command

// Provided by VK_NV_ray_tracing
VkResult vkGetRayTracingShaderGroupHandlesNV(
    VkDevice                                    device,
    VkPipeline                                  pipeline,
    uint32_t                                    firstGroup,
    uint32_t                                    groupCount,
    size_t                                      dataSize,
    void*                                       pData);

  • device is the logical device containing the ray tracing pipeline.

  • pipeline is the ray tracing pipeline object containing the shaders.

  • firstGroup is the index of the first group to retrieve a handle for from the VkRayTracingPipelineCreateInfoKHR::pGroups or VkRayTracingPipelineCreateInfoNV::pGroups array.

  • groupCount is the number of shader handles to retrieve.

  • dataSize is the size in bytes of the buffer pointed to by pData.

  • pData is a pointer to an application-allocated buffer where the results will be written.

On success, an array of groupCount shader handles will be written to pData, with each element being of size VkPhysicalDeviceRayTracingPipelinePropertiesKHR::shaderGroupHandleSize.

If pipeline was created with VK_PIPELINE_CREATE_LIBRARY_BIT_KHR and the pipelineLibraryGroupHandles feature is enabled applications can query group handles from that pipeline, even if the pipeline is a library and is never bound to a command buffer. These group handles remain bitwise identical for any pipeline which references the pipeline library. Group indices are assigned as-if the pipeline was created without VK_PIPELINE_CREATE_LIBRARY_BIT_KHR.

Valid Usage

  • VUID-vkGetRayTracingShaderGroupHandlesKHR-pipeline-04619
    pipeline must be a ray tracing pipeline

  • VUID-vkGetRayTracingShaderGroupHandlesKHR-firstGroup-04050
    firstGroup must be less than the number of shader groups in pipeline

  • VUID-vkGetRayTracingShaderGroupHandlesKHR-firstGroup-02419
    The sum of firstGroup and groupCount must be less than or equal to the number of shader groups in pipeline

  • VUID-vkGetRayTracingShaderGroupHandlesKHR-dataSize-02420
    dataSize must be at least VkPhysicalDeviceRayTracingPipelinePropertiesKHR::shaderGroupHandleSize × groupCount

  • VUID-vkGetRayTracingShaderGroupHandlesKHR-pipeline-07828
    If the pipelineLibraryGroupHandles feature is not enabled, pipeline must not have been created with VK_PIPELINE_CREATE_LIBRARY_BIT_KHR

Valid Usage (Implicit)

  • VUID-vkGetRayTracingShaderGroupHandlesKHR-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkGetRayTracingShaderGroupHandlesKHR-pipeline-parameter
    pipeline must be a valid VkPipeline handle

  • VUID-vkGetRayTracingShaderGroupHandlesKHR-pData-parameter
    pData must be a valid pointer to an array of dataSize bytes

  • VUID-vkGetRayTracingShaderGroupHandlesKHR-dataSize-arraylength
    dataSize must be greater than 0

  • VUID-vkGetRayTracingShaderGroupHandlesKHR-pipeline-parent
    pipeline must have been created, allocated, or retrieved from device

Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

To query the opaque capture data of shader groups in a ray tracing pipeline, call:

// Provided by VK_KHR_ray_tracing_pipeline
VkResult vkGetRayTracingCaptureReplayShaderGroupHandlesKHR(
    VkDevice                                    device,
    VkPipeline                                  pipeline,
    uint32_t                                    firstGroup,
    uint32_t                                    groupCount,
    size_t                                      dataSize,
    void*                                       pData);

  • device is the logical device containing the ray tracing pipeline.

  • pipeline is the ray tracing pipeline object containing the shaders.

  • firstGroup is the index of the first group to retrieve a handle for from the VkRayTracingPipelineCreateInfoKHR::pGroups array.

  • groupCount is the number of shader handles to retrieve.

  • dataSize is the size in bytes of the buffer pointed to by pData.

  • pData is a pointer to an application-allocated buffer where the results will be written.

On success, an array of groupCount shader handles will be written to pData, with each element being of size VkPhysicalDeviceRayTracingPipelinePropertiesKHR::shaderGroupHandleCaptureReplaySize.

Once queried, this opaque data can be provided at pipeline creation time (in a subsequent execution), using VkRayTracingShaderGroupCreateInfoKHR::pShaderGroupCaptureReplayHandle, as described in Ray Tracing Capture Replay.

If pipeline was created with VK_PIPELINE_CREATE_LIBRARY_BIT_KHR and the pipelineLibraryGroupHandles feature is enabled applications can query capture replay group handles from that pipeline. The capture replay handle remains bitwise identical for any pipeline which references the pipeline library. Group indices are assigned as-if the pipeline was created without VK_PIPELINE_CREATE_LIBRARY_BIT_KHR.

Valid Usage

  • VUID-vkGetRayTracingCaptureReplayShaderGroupHandlesKHR-pipeline-04620
    pipeline must be a ray tracing pipeline

  • VUID-vkGetRayTracingCaptureReplayShaderGroupHandlesKHR-firstGroup-04051
    firstGroup must be less than the number of shader groups in pipeline

  • VUID-vkGetRayTracingCaptureReplayShaderGroupHandlesKHR-firstGroup-03483
    The sum of firstGroup and groupCount must be less than or equal to the number of shader groups in pipeline

  • VUID-vkGetRayTracingCaptureReplayShaderGroupHandlesKHR-dataSize-03484
    dataSize must be at least VkPhysicalDeviceRayTracingPipelinePropertiesKHR::shaderGroupHandleCaptureReplaySize × groupCount

  • VUID-vkGetRayTracingCaptureReplayShaderGroupHandlesKHR-rayTracingPipelineShaderGroupHandleCaptureReplay-03606
    VkPhysicalDeviceRayTracingPipelineFeaturesKHR::rayTracingPipelineShaderGroupHandleCaptureReplay must be enabled to call this function

  • VUID-vkGetRayTracingCaptureReplayShaderGroupHandlesKHR-pipeline-03607
    pipeline must have been created with a flags that included VK_PIPELINE_CREATE_RAY_TRACING_SHADER_GROUP_HANDLE_CAPTURE_REPLAY_BIT_KHR

  • VUID-vkGetRayTracingCaptureReplayShaderGroupHandlesKHR-pipeline-07829
    If the pipelineLibraryGroupHandles feature is not enabled, pipeline must not have been created with VK_PIPELINE_CREATE_LIBRARY_BIT_KHR

Valid Usage (Implicit)

  • VUID-vkGetRayTracingCaptureReplayShaderGroupHandlesKHR-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkGetRayTracingCaptureReplayShaderGroupHandlesKHR-pipeline-parameter
    pipeline must be a valid VkPipeline handle

  • VUID-vkGetRayTracingCaptureReplayShaderGroupHandlesKHR-pData-parameter
    pData must be a valid pointer to an array of dataSize bytes

  • VUID-vkGetRayTracingCaptureReplayShaderGroupHandlesKHR-dataSize-arraylength
    dataSize must be greater than 0

  • VUID-vkGetRayTracingCaptureReplayShaderGroupHandlesKHR-pipeline-parent
    pipeline must have been created, allocated, or retrieved from device

Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

Ray tracing pipelines can contain more shaders than a graphics or compute pipeline, so to allow parallel compilation of shaders within a pipeline, an application can choose to defer compilation until a later point in time.

To compile a deferred shader in a pipeline call:

// Provided by VK_NV_ray_tracing
VkResult vkCompileDeferredNV(
    VkDevice                                    device,
    VkPipeline                                  pipeline,
    uint32_t                                    shader);

  • device is the logical device containing the ray tracing pipeline.

  • pipeline is the ray tracing pipeline object containing the shaders.

  • shader is the index of the shader to compile.

Valid Usage

  • VUID-vkCompileDeferredNV-pipeline-04621
    pipeline must be a ray tracing pipeline

  • VUID-vkCompileDeferredNV-pipeline-02237
    pipeline must have been created with VK_PIPELINE_CREATE_DEFER_COMPILE_BIT_NV

  • VUID-vkCompileDeferredNV-shader-02238
    shader must not have been called as a deferred compile before

Valid Usage (Implicit)

  • VUID-vkCompileDeferredNV-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkCompileDeferredNV-pipeline-parameter
    pipeline must be a valid VkPipeline handle

  • VUID-vkCompileDeferredNV-pipeline-parent
    pipeline must have been created, allocated, or retrieved from device

Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

To query the pipeline stack size of shaders in a shader group in the ray tracing pipeline, call:

// Provided by VK_KHR_ray_tracing_pipeline
VkDeviceSize vkGetRayTracingShaderGroupStackSizeKHR(
    VkDevice                                    device,
    VkPipeline                                  pipeline,
    uint32_t                                    group,
    VkShaderGroupShaderKHR                      groupShader);

  • device is the logical device containing the ray tracing pipeline.

  • pipeline is the ray tracing pipeline object containing the shaders groups.

  • group is the index of the shader group to query.

  • groupShader is the type of shader from the group to query.

The return value is the ray tracing pipeline stack size in bytes for the specified shader as called from the specified shader group.

Valid Usage

  • VUID-vkGetRayTracingShaderGroupStackSizeKHR-pipeline-04622
    pipeline must be a ray tracing pipeline

  • VUID-vkGetRayTracingShaderGroupStackSizeKHR-group-03608
    The value of group must be less than the number of shader groups in pipeline

  • VUID-vkGetRayTracingShaderGroupStackSizeKHR-groupShader-03609
    The shader identified by groupShader in group must not be VK_SHADER_UNUSED_KHR

Valid Usage (Implicit)

  • VUID-vkGetRayTracingShaderGroupStackSizeKHR-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkGetRayTracingShaderGroupStackSizeKHR-pipeline-parameter
    pipeline must be a valid VkPipeline handle

  • VUID-vkGetRayTracingShaderGroupStackSizeKHR-groupShader-parameter
    groupShader must be a valid VkShaderGroupShaderKHR value

  • VUID-vkGetRayTracingShaderGroupStackSizeKHR-pipeline-parent
    pipeline must have been created, allocated, or retrieved from device

Possible values of groupShader in vkGetRayTracingShaderGroupStackSizeKHR are:

// Provided by VK_KHR_ray_tracing_pipeline
typedef enum VkShaderGroupShaderKHR {
    VK_SHADER_GROUP_SHADER_GENERAL_KHR = 0,
    VK_SHADER_GROUP_SHADER_CLOSEST_HIT_KHR = 1,
    VK_SHADER_GROUP_SHADER_ANY_HIT_KHR = 2,
    VK_SHADER_GROUP_SHADER_INTERSECTION_KHR = 3,
} VkShaderGroupShaderKHR;

To dynamically set the stack size for a ray tracing pipeline, call:

// Provided by VK_KHR_ray_tracing_pipeline
void vkCmdSetRayTracingPipelineStackSizeKHR(
    VkCommandBuffer                             commandBuffer,
    uint32_t                                    pipelineStackSize);

  • commandBuffer is the command buffer into which the command will be recorded.

  • pipelineStackSize is the stack size to use for subsequent ray tracing trace commands.

This command sets the stack size for subsequent ray tracing commands when the ray tracing pipeline is created with VK_DYNAMIC_STATE_RAY_TRACING_PIPELINE_STACK_SIZE_KHR set in VkPipelineDynamicStateCreateInfo::pDynamicStates. Otherwise, the stack size is computed as described in Ray Tracing Pipeline Stack.

Valid Usage

  • VUID-vkCmdSetRayTracingPipelineStackSizeKHR-pipelineStackSize-03610
    pipelineStackSize must be large enough for any dynamic execution through the shaders in the ray tracing pipeline used by a subsequent trace call

Valid Usage (Implicit)

  • VUID-vkCmdSetRayTracingPipelineStackSizeKHR-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdSetRayTracingPipelineStackSizeKHR-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdSetRayTracingPipelineStackSizeKHR-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support compute operations

  • VUID-vkCmdSetRayTracingPipelineStackSizeKHR-renderpass
    This command must only be called outside of a render pass instance

  • VUID-vkCmdSetRayTracingPipelineStackSizeKHR-videocoding
    This command must only be called outside of a video coding scope

Host Synchronization

  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Video Coding Scope Supported Queue Types Command Type

Primary
Secondary

Outside

Outside

Compute

State

10.5. Pipeline Destruction

To destroy a pipeline, call:

// Provided by VK_VERSION_1_0
void vkDestroyPipeline(
    VkDevice                                    device,
    VkPipeline                                  pipeline,
    const VkAllocationCallbacks*                pAllocator);

  • device is the logical device that destroys the pipeline.

  • pipeline is the handle of the pipeline to destroy.

  • pAllocator controls host memory allocation as described in the Memory Allocation chapter.

Valid Usage

  • VUID-vkDestroyPipeline-pipeline-00765
    All submitted commands that refer to pipeline must have completed execution

  • VUID-vkDestroyPipeline-pipeline-00766
    If VkAllocationCallbacks were provided when pipeline was created, a compatible set of callbacks must be provided here

  • VUID-vkDestroyPipeline-pipeline-00767
    If no VkAllocationCallbacks were provided when pipeline was created, pAllocator must be NULL

Valid Usage (Implicit)

  • VUID-vkDestroyPipeline-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkDestroyPipeline-pipeline-parameter
    If pipeline is not VK_NULL_HANDLE, pipeline must be a valid VkPipeline handle

  • VUID-vkDestroyPipeline-pAllocator-parameter
    If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure

  • VUID-vkDestroyPipeline-pipeline-parent
    If pipeline is a valid handle, it must have been created, allocated, or retrieved from device

Host Synchronization

  • Host access to pipeline must be externally synchronized

10.6. Pipeline Derivatives

A pipeline derivative is a child pipeline created from a parent pipeline, where the child and parent are expected to have much commonality.

The goal of derivative pipelines is that they be cheaper to create using the parent as a starting point, and that it be more efficient (on either host or device) to switch/bind between children of the same parent.

A derivative pipeline is created by setting the VK_PIPELINE_CREATE_DERIVATIVE_BIT flag in the Vk*PipelineCreateInfo structure. If this is set, then exactly one of basePipelineHandle or basePipelineIndex members of the structure must have a valid handle/index, and specifies the parent pipeline. If basePipelineHandle is used, the parent pipeline must have already been created. If basePipelineIndex is used, then the parent is being created in the same command. VK_NULL_HANDLE acts as the invalid handle for basePipelineHandle, and -1 is the invalid index for basePipelineIndex. If basePipelineIndex is used, the base pipeline must appear earlier in the array. The base pipeline must have been created with the VK_PIPELINE_CREATE_ALLOW_DERIVATIVES_BIT flag set.

10.7. Pipeline Cache

Pipeline cache objects allow the result of pipeline construction to be reused between pipelines and between runs of an application. Reuse between pipelines is achieved by passing the same pipeline cache object when creating multiple related pipelines. Reuse across runs of an application is achieved by retrieving pipeline cache contents in one run of an application, saving the contents, and using them to preinitialize a pipeline cache on a subsequent run. The contents of the pipeline cache objects are managed by the implementation. Applications can manage the host memory consumed by a pipeline cache object and control the amount of data retrieved from a pipeline cache object.

Pipeline cache objects are represented by VkPipelineCache handles:

// Provided by VK_VERSION_1_0
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkPipelineCache)

10.7.1. Creating a Pipeline Cache

To create pipeline cache objects, call:

// Provided by VK_VERSION_1_0
VkResult vkCreatePipelineCache(
    VkDevice                                    device,
    const VkPipelineCacheCreateInfo*            pCreateInfo,
    const VkAllocationCallbacks*                pAllocator,
    VkPipelineCache*                            pPipelineCache);

  • device is the logical device that creates the pipeline cache object.

  • pCreateInfo is a pointer to a VkPipelineCacheCreateInfo structure containing initial parameters for the pipeline cache object.

  • pAllocator controls host memory allocation as described in the Memory Allocation chapter.

  • pPipelineCache is a pointer to a VkPipelineCache handle in which the resulting pipeline cache object is returned.

Note

Applications can track and manage the total host memory size of a pipeline cache object using the pAllocator. Applications can limit the amount of data retrieved from a pipeline cache object in vkGetPipelineCacheData. Implementations should not internally limit the total number of entries added to a pipeline cache object or the total host memory consumed.

Once created, a pipeline cache can be passed to the vkCreateGraphicsPipelines vkCreateRayTracingPipelinesKHR, vkCreateRayTracingPipelinesNV, and vkCreateComputePipelines commands. If the pipeline cache passed into these commands is not VK_NULL_HANDLE, the implementation will query it for possible reuse opportunities and update it with new content. The use of the pipeline cache object in these commands is internally synchronized, and the same pipeline cache object can be used in multiple threads simultaneously.

If flags of pCreateInfo includes VK_PIPELINE_CACHE_CREATE_EXTERNALLY_SYNCHRONIZED_BIT, all commands that modify the returned pipeline cache object must be externally synchronized.

Note

Implementations should make every effort to limit any critical sections to the actual accesses to the cache, which is expected to be significantly shorter than the duration of the vkCreate*Pipelines commands.
Valid Usage (Implicit)

  • VUID-vkCreatePipelineCache-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkCreatePipelineCache-pCreateInfo-parameter
    pCreateInfo must be a valid pointer to a valid VkPipelineCacheCreateInfo structure

  • VUID-vkCreatePipelineCache-pAllocator-parameter
    If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure

  • VUID-vkCreatePipelineCache-pPipelineCache-parameter
    pPipelineCache must be a valid pointer to a VkPipelineCache handle

Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

The VkPipelineCacheCreateInfo structure is defined as:

// Provided by VK_VERSION_1_0
typedef struct VkPipelineCacheCreateInfo {
    VkStructureType               sType;
    const void*                   pNext;
    VkPipelineCacheCreateFlags    flags;
    size_t                        initialDataSize;
    const void*                   pInitialData;
} VkPipelineCacheCreateInfo;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • flags is a bitmask of VkPipelineCacheCreateFlagBits specifying the behavior of the pipeline cache.

  • initialDataSize is the number of bytes in pInitialData. If initialDataSize is zero, the pipeline cache will initially be empty.

  • pInitialData is a pointer to previously retrieved pipeline cache data. If the pipeline cache data is incompatible (as defined below) with the device, the pipeline cache will be initially empty. If initialDataSize is zero, pInitialData is ignored.

Valid Usage

  • VUID-VkPipelineCacheCreateInfo-initialDataSize-00768
    If initialDataSize is not 0, it must be equal to the size of pInitialData, as returned by vkGetPipelineCacheData when pInitialData was originally retrieved

  • VUID-VkPipelineCacheCreateInfo-initialDataSize-00769
    If initialDataSize is not 0, pInitialData must have been retrieved from a previous call to vkGetPipelineCacheData

  • VUID-VkPipelineCacheCreateInfo-pipelineCreationCacheControl-02892
    If the pipelineCreationCacheControl feature is not enabled, flags must not include VK_PIPELINE_CACHE_CREATE_EXTERNALLY_SYNCHRONIZED_BIT

Valid Usage (Implicit)

  • VUID-VkPipelineCacheCreateInfo-sType-sType
    sType must be VK_STRUCTURE_TYPE_PIPELINE_CACHE_CREATE_INFO

  • VUID-VkPipelineCacheCreateInfo-pNext-pNext
    pNext must be NULL

  • VUID-VkPipelineCacheCreateInfo-flags-parameter
    flags must be a valid combination of VkPipelineCacheCreateFlagBits values

  • VUID-VkPipelineCacheCreateInfo-pInitialData-parameter
    If initialDataSize is not 0, pInitialData must be a valid pointer to an array of initialDataSize bytes

// Provided by VK_VERSION_1_0
typedef VkFlags VkPipelineCacheCreateFlags;

VkPipelineCacheCreateFlags is a bitmask type for setting a mask of zero or more VkPipelineCacheCreateFlagBits.

Bits which can be set in VkPipelineCacheCreateInfo::flags, specifying behavior of the pipeline cache, are:

// Provided by VK_EXT_pipeline_creation_cache_control
typedef enum VkPipelineCacheCreateFlagBits {
  // Provided by VK_VERSION_1_3
    VK_PIPELINE_CACHE_CREATE_EXTERNALLY_SYNCHRONIZED_BIT = 0x00000001,
  // Provided by VK_EXT_pipeline_creation_cache_control
    VK_PIPELINE_CACHE_CREATE_EXTERNALLY_SYNCHRONIZED_BIT_EXT = VK_PIPELINE_CACHE_CREATE_EXTERNALLY_SYNCHRONIZED_BIT,
} VkPipelineCacheCreateFlagBits;

  • VK_PIPELINE_CACHE_CREATE_EXTERNALLY_SYNCHRONIZED_BIT specifies that all commands that modify the created VkPipelineCache will be externally synchronized. When set, the implementation may skip any unnecessary processing needed to support simultaneous modification from multiple threads where allowed.

10.7.2. Merging Pipeline Caches

Pipeline cache objects can be merged using the command:

// Provided by VK_VERSION_1_0
VkResult vkMergePipelineCaches(
    VkDevice                                    device,
    VkPipelineCache                             dstCache,
    uint32_t                                    srcCacheCount,
    const VkPipelineCache*                      pSrcCaches);

  • device is the logical device that owns the pipeline cache objects.

  • dstCache is the handle of the pipeline cache to merge results into.

  • srcCacheCount is the length of the pSrcCaches array.

  • pSrcCaches is a pointer to an array of pipeline cache handles, which will be merged into dstCache. The previous contents of dstCache are included after the merge.

Note

The details of the merge operation are implementation-dependent, but implementations should merge the contents of the specified pipelines and prune duplicate entries.
Valid Usage

  • VUID-vkMergePipelineCaches-dstCache-00770
    dstCache must not appear in the list of source caches

Valid Usage (Implicit)

  • VUID-vkMergePipelineCaches-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkMergePipelineCaches-dstCache-parameter
    dstCache must be a valid VkPipelineCache handle

  • VUID-vkMergePipelineCaches-pSrcCaches-parameter
    pSrcCaches must be a valid pointer to an array of srcCacheCount valid VkPipelineCache handles

  • VUID-vkMergePipelineCaches-srcCacheCount-arraylength
    srcCacheCount must be greater than 0

  • VUID-vkMergePipelineCaches-dstCache-parent
    dstCache must have been created, allocated, or retrieved from device

  • VUID-vkMergePipelineCaches-pSrcCaches-parent
    Each element of pSrcCaches must have been created, allocated, or retrieved from device

Host Synchronization

  • Host access to dstCache must be externally synchronized

Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

10.7.3. Retrieving Pipeline Cache Data

Data can be retrieved from a pipeline cache object using the command:

// Provided by VK_VERSION_1_0
VkResult vkGetPipelineCacheData(
    VkDevice                                    device,
    VkPipelineCache                             pipelineCache,
    size_t*                                     pDataSize,
    void*                                       pData);

  • device is the logical device that owns the pipeline cache.

  • pipelineCache is the pipeline cache to retrieve data from.

  • pDataSize is a pointer to a size_t value related to the amount of data in the pipeline cache, as described below.

  • pData is either NULL or a pointer to a buffer.

If pData is NULL, then the maximum size of the data that can be retrieved from the pipeline cache, in bytes, is returned in pDataSize. Otherwise, pDataSize must point to a variable set by the application to the size of the buffer, in bytes, pointed to by pData, and on return the variable is overwritten with the amount of data actually written to pData. If pDataSize is less than the maximum size that can be retrieved by the pipeline cache, at most pDataSize bytes will be written to pData, and VK_INCOMPLETE will be returned instead of VK_SUCCESS, to indicate that not all of the pipeline cache was returned.

Any data written to pData is valid and can be provided as the pInitialData member of the VkPipelineCacheCreateInfo structure passed to vkCreatePipelineCache.

Two calls to vkGetPipelineCacheData with the same parameters must retrieve the same data unless a command that modifies the contents of the cache is called between them.

The initial bytes written to pData must be a header as described in the Pipeline Cache Header section.

If pDataSize is less than what is necessary to store this header, nothing will be written to pData and zero will be written to pDataSize.

Valid Usage (Implicit)

  • VUID-vkGetPipelineCacheData-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkGetPipelineCacheData-pipelineCache-parameter
    pipelineCache must be a valid VkPipelineCache handle

  • VUID-vkGetPipelineCacheData-pDataSize-parameter
    pDataSize must be a valid pointer to a size_t value

  • VUID-vkGetPipelineCacheData-pData-parameter
    If the value referenced by pDataSize is not 0, and pData is not NULL, pData must be a valid pointer to an array of pDataSize bytes

  • VUID-vkGetPipelineCacheData-pipelineCache-parent
    pipelineCache must have been created, allocated, or retrieved from device

Return Codes
Success

  • VK_SUCCESS

  • VK_INCOMPLETE

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

10.7.4. Pipeline Cache Header

Applications can store the data retrieved from the pipeline cache, and use these data, possibly in a future run of the application, to populate new pipeline cache objects. The results of pipeline compiles, however, may depend on the vendor ID, device ID, driver version, and other details of the device. To enable applications to detect when previously retrieved data is incompatible with the device, the pipeline cache data must begin with a valid pipeline cache header.

Note

Structures described in this section are not part of the Vulkan API and are only used to describe the representation of data elements in pipeline cache data. Accordingly, the valid usage clauses defined for structures defined in this section do not define valid usage conditions for APIs accepting pipeline cache data as input, as providing invalid pipeline cache data as input to any Vulkan API commands will result in the provided pipeline cache data being ignored.

Version one of the pipeline cache header is defined as:

// Provided by VK_VERSION_1_0
typedef struct VkPipelineCacheHeaderVersionOne {
    uint32_t                        headerSize;
    VkPipelineCacheHeaderVersion    headerVersion;
    uint32_t                        vendorID;
    uint32_t                        deviceID;
    uint8_t                         pipelineCacheUUID[VK_UUID_SIZE];
} VkPipelineCacheHeaderVersionOne;

  • headerSize is the length in bytes of the pipeline cache header.

  • headerVersion is a VkPipelineCacheHeaderVersion value specifying the version of the header. A consumer of the pipeline cache should use the cache version to interpret the remainder of the cache header.

  • vendorID is the VkPhysicalDeviceProperties::vendorID of the implementation.

  • deviceID is the VkPhysicalDeviceProperties::deviceID of the implementation.

  • pipelineCacheUUID is the VkPhysicalDeviceProperties::pipelineCacheUUID of the implementation.

Unlike most structures declared by the Vulkan API, all fields of this structure are written with the least significant byte first, regardless of host byte-order.

The C language specification does not define the packing of structure members. This layout assumes tight structure member packing, with members laid out in the order listed in the structure, and the intended size of the structure is 32 bytes. If a compiler produces code that diverges from that pattern, applications must employ another method to set values at the correct offsets.

Valid Usage

  • VUID-VkPipelineCacheHeaderVersionOne-headerSize-04967
    headerSize must be 32

  • VUID-VkPipelineCacheHeaderVersionOne-headerVersion-04968
    headerVersion must be VK_PIPELINE_CACHE_HEADER_VERSION_ONE

  • VUID-VkPipelineCacheHeaderVersionOne-headerSize-08990
    headerSize must not exceed the size of the pipeline cache

Valid Usage (Implicit)

Possible values of the headerVersion value of the pipeline cache header are:

// Provided by VK_VERSION_1_0
typedef enum VkPipelineCacheHeaderVersion {
    VK_PIPELINE_CACHE_HEADER_VERSION_ONE = 1,
} VkPipelineCacheHeaderVersion;

10.7.5. Destroying a Pipeline Cache

To destroy a pipeline cache, call:

// Provided by VK_VERSION_1_0
void vkDestroyPipelineCache(
    VkDevice                                    device,
    VkPipelineCache                             pipelineCache,
    const VkAllocationCallbacks*                pAllocator);

  • device is the logical device that destroys the pipeline cache object.

  • pipelineCache is the handle of the pipeline cache to destroy.

  • pAllocator controls host memory allocation as described in the Memory Allocation chapter.

Valid Usage

  • VUID-vkDestroyPipelineCache-pipelineCache-00771
    If VkAllocationCallbacks were provided when pipelineCache was created, a compatible set of callbacks must be provided here

  • VUID-vkDestroyPipelineCache-pipelineCache-00772
    If no VkAllocationCallbacks were provided when pipelineCache was created, pAllocator must be NULL

Valid Usage (Implicit)

  • VUID-vkDestroyPipelineCache-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkDestroyPipelineCache-pipelineCache-parameter
    If pipelineCache is not VK_NULL_HANDLE, pipelineCache must be a valid VkPipelineCache handle

  • VUID-vkDestroyPipelineCache-pAllocator-parameter
    If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure

  • VUID-vkDestroyPipelineCache-pipelineCache-parent
    If pipelineCache is a valid handle, it must have been created, allocated, or retrieved from device

Host Synchronization

  • Host access to pipelineCache must be externally synchronized

10.8. Pipeline Binaries

Pipeline binary objects allow the result of pipeline construction to be reused between pipelines and between runs of an application. Reuse is achieved by extracting pipeline binaries from a VkPipeline object, associating them with a corresponding VkPipelineBinaryKeyKHR and then adding a VkPipelineBinaryInfoKHR to the pNext chain of any Vk*PipelineCreateInfo when creating a pipeline. Pipeline binaries can be reused between runs by extracting VkPipelineBinaryDataKHR from VkPipelineBinaryKHR objects, saving the contents, and then using them to create a VkPipelineBinaryKHR object on subsequent runs.

When creating a pipeline that includes VkPipelineBinaryInfoKHR in the pNext chain, or has the VK_PIPELINE_CREATE_2_CAPTURE_DATA_BIT_KHR flag set, the use of VkPipelineCache objects is not allowed.

Pipeline binary objects are represented by VkPipelineBinaryKHR handles:

// Provided by VK_KHR_pipeline_binary
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkPipelineBinaryKHR)

10.8.1. Generating the Pipeline Key

To generate the key for a particular pipeline creation info, call:

// Provided by VK_KHR_pipeline_binary
VkResult vkGetPipelineKeyKHR(
    VkDevice                                    device,
    const VkPipelineCreateInfoKHR*              pPipelineCreateInfo,
    VkPipelineBinaryKeyKHR*                     pPipelineKey);

  • device is the logical device that creates the pipeline object.

  • pPipelineCreateInfo is NULL or a pointer to a VkPipelineCreateInfoKHR structure.

  • pPipelineKey is a pointer to a VkPipelineBinaryKeyKHR structure in which the resulting key is returned.

If pPipelineCreateInfo is NULL, then the implementation must return the global key that applies to all pipelines. If the key obtained in this way changes between saving and restoring data obtained from vkGetPipelineBinaryDataKHR in a different VkDevice, then the application must assume that the restored data is invalid and cannot be passed to vkCreatePipelineBinariesKHR. Otherwise the application can assume the data is still valid.

If pPipelineCreateInfo is not NULL, the key obtained functions as a method to compare two pipeline creation info structures. Implementations may not compare parts of a pipeline creation info which would not contribute to the final binary output. If a shader module identifier is used instead of a shader module, the pPipelineKey generated must be equal to the key generated when using the shader module from which the identifier was queried. If the content of two pPipelineKey are equal, pipelines created with the two pPipelineCreateInfo->pname:pNext create infos must produce the same VkPipelineBinaryKHR contents.

The pipeline key is distinct from pipeline binary key. Pipeline binary keys can only be obtained after compilation. The pipeline key is intended to optionally allow associating pipeline create info with multiple pipeline binary keys.

Valid Usage

  • VUID-vkGetPipelineKeyKHR-pNext-09605
    The pNext chain of pPipelineCreateInfo must not set VkPipelineBinaryInfoKHR::binaryCount to a value greater than 0

Valid Usage (Implicit)

  • VUID-vkGetPipelineKeyKHR-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkGetPipelineKeyKHR-pPipelineCreateInfo-parameter
    If pPipelineCreateInfo is not NULL, pPipelineCreateInfo must be a valid pointer to a valid VkPipelineCreateInfoKHR structure

  • VUID-vkGetPipelineKeyKHR-pPipelineKey-parameter
    pPipelineKey must be a valid pointer to a VkPipelineBinaryKeyKHR structure

Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

The VkPipelineCreateInfoKHR structure is defined as:

// Provided by VK_KHR_pipeline_binary
typedef struct VkPipelineCreateInfoKHR {
    VkStructureType    sType;
    void*              pNext;
} VkPipelineCreateInfoKHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is a pointer to a structure extending this structure.

Valid Usage
Valid Usage (Implicit)

  • VUID-VkPipelineCreateInfoKHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_PIPELINE_CREATE_INFO_KHR

The VkPipelineBinaryKeyKHR structure is defined as:

// Provided by VK_KHR_pipeline_binary
typedef struct VkPipelineBinaryKeyKHR {
    VkStructureType    sType;
    void*              pNext;
    uint32_t           keySize;
    uint8_t            key[VK_MAX_PIPELINE_BINARY_KEY_SIZE_KHR];
} VkPipelineBinaryKeyKHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • keySize is the size, in bytes, of valid data returned in key.

  • key is a buffer of opaque data specifying a pipeline binary key.

Any returned values beyond the first keySize bytes are undefined. Implementations must return a keySize greater than 0, and less-or-equal to VK_MAX_PIPELINE_BINARY_KEY_SIZE_KHR.

Two keys are considered equal if keySize is equal and the first keySize bytes of key compare equal.

Implementations may return a different keySize for different binaries.

Implementations should ensure that keySize is large enough to uniquely identify a pipeline binary.

Valid Usage (Implicit)

  • VUID-VkPipelineBinaryKeyKHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_PIPELINE_BINARY_KEY_KHR

  • VUID-VkPipelineBinaryKeyKHR-pNext-pNext
    pNext must be NULL

VK_MAX_PIPELINE_BINARY_KEY_SIZE_KHR is the length in bytes of a binary key, as returned in VkPipelineBinaryKeyKHR::keySize.

#define VK_MAX_PIPELINE_BINARY_KEY_SIZE_KHR 32U

10.8.2. Creating Pipeline Binaries

To create pipeline binary objects, call:

// Provided by VK_KHR_pipeline_binary
VkResult vkCreatePipelineBinariesKHR(
    VkDevice                                    device,
    const VkPipelineBinaryCreateInfoKHR*        pCreateInfo,
    const VkAllocationCallbacks*                pAllocator,
    VkPipelineBinaryHandlesInfoKHR*             pBinaries);

  • device is the logical device that creates the pipeline binary objects.

  • pCreateInfo is a pointer to a VkPipelineBinaryCreateInfoKHR structure that contains the data to create the pipeline binaries from.

  • pAllocator controls host memory allocation as described in the Memory Allocation chapter.

  • pBinaries is a pointer to a VkPipelineBinaryHandlesInfoKHR structure in which the resulting pipeline binaries are returned.

The implementation will attempt to create all pipeline binaries. If creation fails for any pipeline binary, then:

Valid Usage (Implicit)

  • VUID-vkCreatePipelineBinariesKHR-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkCreatePipelineBinariesKHR-pCreateInfo-parameter
    pCreateInfo must be a valid pointer to a valid VkPipelineBinaryCreateInfoKHR structure

  • VUID-vkCreatePipelineBinariesKHR-pAllocator-parameter
    If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure

  • VUID-vkCreatePipelineBinariesKHR-pBinaries-parameter
    pBinaries must be a valid pointer to a VkPipelineBinaryHandlesInfoKHR structure

Return Codes
Success

  • VK_SUCCESS

  • VK_INCOMPLETE

  • VK_PIPELINE_BINARY_MISSING_KHR

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

  • VK_ERROR_INITIALIZATION_FAILED

The VkPipelineBinaryHandlesInfoKHR structure is defined as:

// Provided by VK_KHR_pipeline_binary
typedef struct VkPipelineBinaryHandlesInfoKHR {
    VkStructureType         sType;
    const void*             pNext;
    uint32_t                pipelineBinaryCount;
    VkPipelineBinaryKHR*    pPipelineBinaries;
} VkPipelineBinaryHandlesInfoKHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • pipelineBinaryCount is the number of binaries associated with this pipeline or the number of entries in the pPipelineBinaries array.

  • pPipelineBinaries is NULL or a pointer to an array of VkPipelineBinaryKHR handles in which the resulting pipeline binaries are returned.

If pPipelineBinaries is NULL, the number of binaries that would be created is returned in pipelineBinaryCount. Otherwise, pipelineBinaryCount must be set to the number of entries in the pPipelineBinaries array, and on return from vkCreatePipelineBinariesKHR pipelineBinaryCount is overwritten with the number of handles actually written to pPipelineBinaries. If the value of pipelineBinaryCount is less than the number of binaries that would have been created, at most pipelineBinaryCount handles will be written to pPipelineBinaries and VK_INCOMPLETE will be returned instead of VK_SUCCESS, to indicate that pPipelineBinaries was not large enough to create all the binaries.

Valid Usage (Implicit)

  • VUID-VkPipelineBinaryHandlesInfoKHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_PIPELINE_BINARY_HANDLES_INFO_KHR

  • VUID-VkPipelineBinaryHandlesInfoKHR-pNext-pNext
    pNext must be NULL

  • VUID-VkPipelineBinaryHandlesInfoKHR-pPipelineBinaries-parameter
    If pipelineBinaryCount is not 0, and pPipelineBinaries is not NULL, pPipelineBinaries must be a valid pointer to an array of pipelineBinaryCount VkPipelineBinaryKHR handles

The VkPipelineBinaryCreateInfoKHR structure is defined as:

// Provided by VK_KHR_pipeline_binary
typedef struct VkPipelineBinaryCreateInfoKHR {
    VkStructureType                          sType;
    const void*                              pNext;
    const VkPipelineBinaryKeysAndDataKHR*    pKeysAndDataInfo;
    VkPipeline                               pipeline;
    const VkPipelineCreateInfoKHR*           pPipelineCreateInfo;
} VkPipelineBinaryCreateInfoKHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • pKeysAndDataInfo is NULL or a pointer to a VkPipelineBinaryKeysAndDataKHR structure that contains keys and data to create the pipeline binaries from.

  • pipeline is VK_NULL_HANDLE or a VkPipeline that contains data to create the pipeline binaries from.

  • pPipelineCreateInfo is NULL or a pointer to a VkPipelineCreateInfoKHR structure with the pipeline creation info. This is used to probe the implementation’s internal cache for pipeline binaries.

When pPipelineCreateInfo is not NULL, an implementation will attempt to retrieve pipeline binary data from an internal cache external to the application if pipelineBinaryInternalCache is VK_TRUE. Applications can use this to determine if a pipeline can be created without compilation. If the implementation fails to create a pipeline binary due to missing an internal cache entry, VK_PIPELINE_BINARY_MISSING_KHR is returned. If creation succeeds, the resulting binary can be used to create a pipeline. VK_PIPELINE_BINARY_MISSING_KHR may be returned for any reason in this situation, even if creating a pipeline binary with the same parameters that succeeded earlier.

If pipelineBinaryPrecompiledInternalCache is VK_TRUE, the implementation may be able to create pipeline binaries even when pPipelineCreateInfo has not been used to create binaries before by the application.

Note

On some platforms, internal pipeline caches may be pre-populated before running the application.
Valid Usage

  • VUID-VkPipelineBinaryCreateInfoKHR-pipeline-09607
    If pipeline is not VK_NULL_HANDLE, pipeline must have been created with VK_PIPELINE_CREATE_2_CAPTURE_DATA_BIT_KHR

  • VUID-VkPipelineBinaryCreateInfoKHR-pipeline-09608
    If pipeline is not VK_NULL_HANDLE, vkReleaseCapturedPipelineDataKHR must not have been called on pipeline prior to this command

  • VUID-VkPipelineBinaryCreateInfoKHR-pipelineBinaryInternalCache-09609
    If pipelineBinaryInternalCache is VK_FALSE pPipelineCreateInfo must be NULL

  • VUID-VkPipelineBinaryCreateInfoKHR-device-09610
    If device was created with VkDevicePipelineBinaryInternalCacheControlKHR::disableInternalCache set to VK_TRUE, pPipelineCreateInfo must be NULL

  • VUID-VkPipelineBinaryCreateInfoKHR-pKeysAndDataInfo-09619
    One and only one of pKeysAndDataInfo, pipeline, or pPipelineCreateInfo must be non-NULL

  • VUID-VkPipelineBinaryCreateInfoKHR-pPipelineCreateInfo-09606
    If pPipelineCreateInfo is not NULL, the pNext chain of pPipelineCreateInfo must not set VkPipelineBinaryInfoKHR::binaryCount to a value greater than 0

Valid Usage (Implicit)

  • VUID-VkPipelineBinaryCreateInfoKHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_PIPELINE_BINARY_CREATE_INFO_KHR

  • VUID-VkPipelineBinaryCreateInfoKHR-pNext-pNext
    pNext must be NULL

  • VUID-VkPipelineBinaryCreateInfoKHR-pKeysAndDataInfo-parameter
    If pKeysAndDataInfo is not NULL, pKeysAndDataInfo must be a valid pointer to a valid VkPipelineBinaryKeysAndDataKHR structure

  • VUID-VkPipelineBinaryCreateInfoKHR-pipeline-parameter
    If pipeline is not VK_NULL_HANDLE, pipeline must be a valid VkPipeline handle

  • VUID-VkPipelineBinaryCreateInfoKHR-pPipelineCreateInfo-parameter
    If pPipelineCreateInfo is not NULL, pPipelineCreateInfo must be a valid pointer to a valid VkPipelineCreateInfoKHR structure

The VkPipelineBinaryKeysAndDataKHR structure is defined as:

// Provided by VK_KHR_pipeline_binary
typedef struct VkPipelineBinaryKeysAndDataKHR {
    uint32_t                          binaryCount;
    const VkPipelineBinaryKeyKHR*     pPipelineBinaryKeys;
    const VkPipelineBinaryDataKHR*    pPipelineBinaryData;
} VkPipelineBinaryKeysAndDataKHR;

  • binaryCount is the size of the pPipelineBinaryKeys and pPipelineBinaryData arrays

  • pPipelineBinaryKeys is a pointer to an array of VkPipelineBinaryKeyKHR structures containing the pipeline binary keys

  • pPipelineBinaryData is a pointer to an array of VkPipelineBinaryDataKHR structures containing the pipeline binary data

Valid Usage (Implicit)

  • VUID-VkPipelineBinaryKeysAndDataKHR-pPipelineBinaryKeys-parameter
    pPipelineBinaryKeys must be a valid pointer to an array of binaryCount valid VkPipelineBinaryKeyKHR structures

  • VUID-VkPipelineBinaryKeysAndDataKHR-pPipelineBinaryData-parameter
    pPipelineBinaryData must be a valid pointer to an array of binaryCount valid VkPipelineBinaryDataKHR structures

  • VUID-VkPipelineBinaryKeysAndDataKHR-binaryCount-arraylength
    binaryCount must be greater than 0

The VkPipelineBinaryDataKHR structure is defined as:

// Provided by VK_KHR_pipeline_binary
typedef struct VkPipelineBinaryDataKHR {
    size_t    dataSize;
    void*     pData;
} VkPipelineBinaryDataKHR;

  • dataSize is the size of the pData buffer in bytes.

  • pData is a pointer to a buffer of size bytes that contains pipeline binary data obtained from vkGetPipelineBinaryDataKHR.

Valid Usage (Implicit)

  • VUID-VkPipelineBinaryDataKHR-pData-parameter
    pData must be a valid pointer to an array of dataSize bytes

  • VUID-VkPipelineBinaryDataKHR-dataSize-arraylength
    dataSize must be greater than 0

10.8.3. Retrieving Pipeline Binary Data

Data can be retrieved from a pipeline binary object using the command:

// Provided by VK_KHR_pipeline_binary
VkResult vkGetPipelineBinaryDataKHR(
    VkDevice                                    device,
    const VkPipelineBinaryDataInfoKHR*          pInfo,
    VkPipelineBinaryKeyKHR*                     pPipelineBinaryKey,
    size_t*                                     pPipelineBinaryDataSize,
    void*                                       pPipelineBinaryData);

  • device is the logical device that created the pipeline binary.

  • pInfo is a pointer to a VkPipelineBinaryDataInfoKHR structure which describes the pipeline binary to get data from.

  • pPipelineBinaryKey is a pointer to a VkPipelineBinaryKeyKHR structure where the key for this binary will be written.

  • pPipelineBinaryDataSize is a pointer to a size_t value related to the amount of data in the pipeline binary, as described below.

  • pPipelineBinaryData is either NULL or a pointer to a buffer.

If pPipelineBinaryData is NULL, then the size of the data, in bytes, that is required to store the binary is returned in pPipelineBinaryDataSize. Otherwise, pPipelineBinaryDataSize must contain the size of the buffer, in bytes, pointed to by pPipelineBinaryData, and on return pPipelineBinaryDataSize is overwritten with the size of the data, in bytes, that is required to store the binary. If pPipelineBinaryDataSize is less than the size that is required to store the binary, nothing is written to pPipelineBinaryData and VK_ERROR_NOT_ENOUGH_SPACE_KHR will be returned, instead of VK_SUCCESS.

If pipelineBinaryCompressedData is VK_FALSE, implementations should not return compressed pipeline binary data to the application.

Valid Usage (Implicit)

  • VUID-vkGetPipelineBinaryDataKHR-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkGetPipelineBinaryDataKHR-pInfo-parameter
    pInfo must be a valid pointer to a valid VkPipelineBinaryDataInfoKHR structure

  • VUID-vkGetPipelineBinaryDataKHR-pPipelineBinaryKey-parameter
    pPipelineBinaryKey must be a valid pointer to a VkPipelineBinaryKeyKHR structure

  • VUID-vkGetPipelineBinaryDataKHR-pPipelineBinaryDataSize-parameter
    pPipelineBinaryDataSize must be a valid pointer to a size_t value

  • VUID-vkGetPipelineBinaryDataKHR-pPipelineBinaryData-parameter
    If the value referenced by pPipelineBinaryDataSize is not 0, and pPipelineBinaryData is not NULL, pPipelineBinaryData must be a valid pointer to an array of pPipelineBinaryDataSize bytes

Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

  • VK_ERROR_NOT_ENOUGH_SPACE_KHR

The VkPipelineBinaryDataInfoKHR structure is defined as:

// Provided by VK_KHR_pipeline_binary
typedef struct VkPipelineBinaryDataInfoKHR {
    VkStructureType        sType;
    void*                  pNext;
    VkPipelineBinaryKHR    pipelineBinary;
} VkPipelineBinaryDataInfoKHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • pipelineBinary is the pipeline binary to get data from.

Valid Usage (Implicit)

  • VUID-VkPipelineBinaryDataInfoKHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_PIPELINE_BINARY_DATA_INFO_KHR

  • VUID-VkPipelineBinaryDataInfoKHR-pNext-pNext
    pNext must be NULL

  • VUID-VkPipelineBinaryDataInfoKHR-pipelineBinary-parameter
    pipelineBinary must be a valid VkPipelineBinaryKHR handle

10.8.4. Releasing Captured Pipeline Binary Data

To release pipeline resources captured with VK_PIPELINE_CREATE_2_CAPTURE_DATA_BIT_KHR, call:

// Provided by VK_KHR_pipeline_binary
VkResult vkReleaseCapturedPipelineDataKHR(
    VkDevice                                    device,
    const VkReleaseCapturedPipelineDataInfoKHR* pInfo,
    const VkAllocationCallbacks*                pAllocator);

  • device is the logical device that created the pipeline object.

  • pInfo is a pointer to a VkReleaseCapturedPipelineDataInfoKHR structure which describes the pipeline to release the data from.

  • pAllocator controls host memory allocation as described in the Memory Allocation chapter.

The implementation may free any resources captured as a result of creating the pipeline with VK_PIPELINE_CREATE_2_CAPTURE_DATA_BIT_KHR and put the pipeline into a state as if VK_PIPELINE_CREATE_2_CAPTURE_DATA_BIT_KHR had not been provided at pipeline creation time.

Note

Any resources captured as a result of creating the pipeline with VK_PIPELINE_CREATE_2_CAPTURE_DATA_BIT_KHR are implicitly freed by vkDestroyPipeline.
Valid Usage

  • VUID-vkReleaseCapturedPipelineDataKHR-pipeline-09611
    If VkAllocationCallbacks were provided when pipeline was created, a compatible set of callbacks must be provided in pAllocator

  • VUID-vkReleaseCapturedPipelineDataKHR-pipeline-09612
    If no VkAllocationCallbacks were provided when pipeline was created, pAllocator must be NULL

Valid Usage (Implicit)

  • VUID-vkReleaseCapturedPipelineDataKHR-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkReleaseCapturedPipelineDataKHR-pInfo-parameter
    pInfo must be a valid pointer to a valid VkReleaseCapturedPipelineDataInfoKHR structure

  • VUID-vkReleaseCapturedPipelineDataKHR-pAllocator-parameter
    If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure

Host Synchronization

  • Host access to pInfo->pipeline must be externally synchronized

Return Codes
Success

  • VK_SUCCESS

Failure

None

The VkReleaseCapturedPipelineDataInfoKHR structure is defined as:

// Provided by VK_KHR_pipeline_binary
typedef struct VkReleaseCapturedPipelineDataInfoKHR {
    VkStructureType    sType;
    void*              pNext;
    VkPipeline         pipeline;
} VkReleaseCapturedPipelineDataInfoKHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • pipeline the handle of the pipeline object to release the data from.

Valid Usage

  • VUID-VkReleaseCapturedPipelineDataInfoKHR-pipeline-09613
    pipeline must have been created with VK_PIPELINE_CREATE_2_CAPTURE_DATA_BIT_KHR

  • VUID-VkReleaseCapturedPipelineDataInfoKHR-pipeline-09618
    pipeline must not have been used in a previous call to vkReleaseCapturedPipelineDataKHR

Valid Usage (Implicit)

  • VUID-VkReleaseCapturedPipelineDataInfoKHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_RELEASE_CAPTURED_PIPELINE_DATA_INFO_KHR

  • VUID-VkReleaseCapturedPipelineDataInfoKHR-pNext-pNext
    pNext must be NULL

  • VUID-VkReleaseCapturedPipelineDataInfoKHR-pipeline-parameter
    pipeline must be a valid VkPipeline handle

10.8.5. Destroying Pipeline Binaries

To destroy a VkPipelineBinaryKHR, call:

// Provided by VK_KHR_pipeline_binary
void vkDestroyPipelineBinaryKHR(
    VkDevice                                    device,
    VkPipelineBinaryKHR                         pipelineBinary,
    const VkAllocationCallbacks*                pAllocator);

  • device is the logical device that created the pipeline binary object.

  • pipelineBinary is the handle of the pipeline binary object to destroy.

  • pAllocator controls host memory allocation as described in the Memory Allocation chapter.

Valid Usage

  • VUID-vkDestroyPipelineBinaryKHR-pipelineBinary-09614
    If VkAllocationCallbacks were provided when pipelineBinary was created, a compatible set of callbacks must be provided here.

  • VUID-vkDestroyPipelineBinaryKHR-pipelineBinary-09615
    If no VkAllocationCallbacks were provided when pipelineBinary was created, pAllocator must be NULL

Valid Usage (Implicit)

  • VUID-vkDestroyPipelineBinaryKHR-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkDestroyPipelineBinaryKHR-pipelineBinary-parameter
    If pipelineBinary is not VK_NULL_HANDLE, pipelineBinary must be a valid VkPipelineBinaryKHR handle

  • VUID-vkDestroyPipelineBinaryKHR-pAllocator-parameter
    If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure

  • VUID-vkDestroyPipelineBinaryKHR-pipelineBinary-parent
    If pipelineBinary is a valid handle, it must have been created, allocated, or retrieved from device

Host Synchronization

  • Host access to pipelineBinary must be externally synchronized

10.9. Specialization Constants

Specialization constants are a mechanism whereby constants in a SPIR-V module can have their constant value specified at the time the VkPipeline is created. This allows a SPIR-V module to have constants that can be modified while executing an application that uses the Vulkan API.

Note

Specialization constants are useful to allow a compute shader to have its local workgroup size changed at runtime by the user, for example.

Each VkPipelineShaderStageCreateInfo structure contains a pSpecializationInfo member, which can be NULL to indicate no specialization constants, or point to a VkSpecializationInfo structure.

The VkSpecializationInfo structure is defined as:

// Provided by VK_VERSION_1_0
typedef struct VkSpecializationInfo {
    uint32_t                           mapEntryCount;
    const VkSpecializationMapEntry*    pMapEntries;
    size_t                             dataSize;
    const void*                        pData;
} VkSpecializationInfo;

  • mapEntryCount is the number of entries in the pMapEntries array.

  • pMapEntries is a pointer to an array of VkSpecializationMapEntry structures, which map constant IDs to offsets in pData.

  • dataSize is the byte size of the pData buffer.

  • pData contains the actual constant values to specialize with.

Valid Usage

  • VUID-VkSpecializationInfo-offset-00773
    The offset member of each element of pMapEntries must be less than dataSize

  • VUID-VkSpecializationInfo-pMapEntries-00774
    The size member of each element of pMapEntries must be less than or equal to dataSize minus offset

  • VUID-VkSpecializationInfo-constantID-04911
    The constantID value of each element of pMapEntries must be unique within pMapEntries

Valid Usage (Implicit)

  • VUID-VkSpecializationInfo-pMapEntries-parameter
    If mapEntryCount is not 0, pMapEntries must be a valid pointer to an array of mapEntryCount valid VkSpecializationMapEntry structures

  • VUID-VkSpecializationInfo-pData-parameter
    If dataSize is not 0, pData must be a valid pointer to an array of dataSize bytes

The VkSpecializationMapEntry structure is defined as:

// Provided by VK_VERSION_1_0
typedef struct VkSpecializationMapEntry {
    uint32_t    constantID;
    uint32_t    offset;
    size_t      size;
} VkSpecializationMapEntry;

  • constantID is the ID of the specialization constant in SPIR-V.

  • offset is the byte offset of the specialization constant value within the supplied data buffer.

  • size is the byte size of the specialization constant value within the supplied data buffer.

If a constantID value is not a specialization constant ID used in the shader, that map entry does not affect the behavior of the pipeline.

Valid Usage

  • VUID-VkSpecializationMapEntry-constantID-00776
    For a constantID specialization constant declared in a shader, size must match the byte size of the constantID. If the specialization constant is of type boolean, size must be the byte size of VkBool32

In human readable SPIR-V:

OpDecorate %x SpecId 13 ; decorate .x component of WorkgroupSize with ID 13
OpDecorate %y SpecId 42 ; decorate .y component of WorkgroupSize with ID 42
OpDecorate %z SpecId 3  ; decorate .z component of WorkgroupSize with ID 3
OpDecorate %wgsize BuiltIn WorkgroupSize ; decorate WorkgroupSize onto constant
%i32 = OpTypeInt 32 0 ; declare an unsigned 32-bit type
%uvec3 = OpTypeVector %i32 3 ; declare a 3 element vector type of unsigned 32-bit
%x = OpSpecConstant %i32 1 ; declare the .x component of WorkgroupSize
%y = OpSpecConstant %i32 1 ; declare the .y component of WorkgroupSize
%z = OpSpecConstant %i32 1 ; declare the .z component of WorkgroupSize
%wgsize = OpSpecConstantComposite %uvec3 %x %y %z ; declare WorkgroupSize

From the above we have three specialization constants, one for each of the x, y & z elements of the WorkgroupSize vector.

Now to specialize the above via the specialization constants mechanism:

const VkSpecializationMapEntry entries[] =
{
    {
        .constantID = 13,
        .offset = 0 * sizeof(uint32_t),
        .size = sizeof(uint32_t)
    },
    {
        .constantID = 42,
        .offset = 1 * sizeof(uint32_t),
        .size = sizeof(uint32_t)
    },
    {
        .constantID = 3,
        .offset = 2 * sizeof(uint32_t),
        .size = sizeof(uint32_t)
    }
};

const uint32_t data[] = { 16, 8, 4 }; // our workgroup size is 16x8x4

const VkSpecializationInfo info =
{
    .mapEntryCount = 3,
    .pMapEntries  = entries,
    .dataSize = 3 * sizeof(uint32_t),
    .pData = data,
};

Then when calling vkCreateComputePipelines, and passing the VkSpecializationInfo we defined as the pSpecializationInfo parameter of VkPipelineShaderStageCreateInfo, we will create a compute pipeline with the runtime specified local workgroup size.

Another example would be that an application has a SPIR-V module that has some platform-dependent constants they wish to use.

In human readable SPIR-V:

OpDecorate %1 SpecId 0  ; decorate our signed 32-bit integer constant
OpDecorate %2 SpecId 12 ; decorate our 32-bit floating-point constant
%i32 = OpTypeInt 32 1   ; declare a signed 32-bit type
%float = OpTypeFloat 32 ; declare a 32-bit floating-point type
%1 = OpSpecConstant %i32 -1 ; some signed 32-bit integer constant
%2 = OpSpecConstant %float 0.5 ; some 32-bit floating-point constant

From the above we have two specialization constants, one is a signed 32-bit integer and the second is a 32-bit floating-point value.

Now to specialize the above via the specialization constants mechanism:

struct SpecializationData {
    int32_t data0;
    float data1;
};

const VkSpecializationMapEntry entries[] =
{
    {
        .constantID = 0,
        .offset = offsetof(SpecializationData, data0),
        .size = sizeof(SpecializationData::data0)
    },
    {
        .constantID = 12,
        .offset = offsetof(SpecializationData, data1),
        .size = sizeof(SpecializationData::data1)
    }
};

SpecializationData data;
data.data0 = -42;    // set the data for the 32-bit integer
data.data1 = 42.0f;  // set the data for the 32-bit floating-point

const VkSpecializationInfo info =
{
    .mapEntryCount = 2,
    .pMapEntries = entries,
    .dataSize = sizeof(data),
    .pdata = &data,
};

It is legal for a SPIR-V module with specializations to be compiled into a pipeline where no specialization information was provided. SPIR-V specialization constants contain default values such that if a specialization is not provided, the default value will be used. In the examples above, it would be valid for an application to only specialize some of the specialization constants within the SPIR-V module, and let the other constants use their default values encoded within the OpSpecConstant declarations.

10.10. Pipeline Libraries

A pipeline library is a special pipeline that was created using the VK_PIPELINE_CREATE_LIBRARY_BIT_KHR and cannot be bound, instead it defines a set of pipeline state which can be linked into other pipelines. For ray tracing pipelines this includes shaders and shader groups. For graphics pipelines this includes distinct library types defined by VkGraphicsPipelineLibraryFlagBitsEXT. The application must maintain the lifetime of a pipeline library based on the pipelines that link with it.

This linkage is achieved by using the following structure within the appropriate creation mechanisms:

The VkPipelineLibraryCreateInfoKHR structure is defined as:

// Provided by VK_KHR_pipeline_library
typedef struct VkPipelineLibraryCreateInfoKHR {
    VkStructureType      sType;
    const void*          pNext;
    uint32_t             libraryCount;
    const VkPipeline*    pLibraries;
} VkPipelineLibraryCreateInfoKHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • libraryCount is the number of pipeline libraries in pLibraries.

  • pLibraries is a pointer to an array of VkPipeline structures specifying pipeline libraries to use when creating a pipeline.

Valid Usage

  • VUID-VkPipelineLibraryCreateInfoKHR-pLibraries-03381
    Each element of pLibraries must have been created with VK_PIPELINE_CREATE_LIBRARY_BIT_KHR

  • VUID-VkPipelineLibraryCreateInfoKHR-pLibraries-06855
    If any library in pLibraries was created with a shader stage with VkPipelineShaderStageModuleIdentifierCreateInfoEXT and identifierSize not equal to 0, the pipeline must be created with the VK_PIPELINE_CREATE_FAIL_ON_PIPELINE_COMPILE_REQUIRED_BIT flag set

  • VUID-VkPipelineLibraryCreateInfoKHR-pLibraries-08096
    If any element of pLibraries was created with VK_PIPELINE_CREATE_DESCRIPTOR_BUFFER_BIT_EXT, all elements must have been created with VK_PIPELINE_CREATE_DESCRIPTOR_BUFFER_BIT_EXT

  • VUID-VkPipelineLibraryCreateInfoKHR-pipeline-07404
    If pipeline is being created with VK_PIPELINE_CREATE_NO_PROTECTED_ACCESS_BIT_EXT, every element of pLibraries must have been created with VK_PIPELINE_CREATE_NO_PROTECTED_ACCESS_BIT_EXT

  • VUID-VkPipelineLibraryCreateInfoKHR-pipeline-07405
    If pipeline is being created without VK_PIPELINE_CREATE_NO_PROTECTED_ACCESS_BIT_EXT, every element of pLibraries must have been created without VK_PIPELINE_CREATE_NO_PROTECTED_ACCESS_BIT_EXT

  • VUID-VkPipelineLibraryCreateInfoKHR-pipeline-07406
    If pipeline is being created with VK_PIPELINE_CREATE_PROTECTED_ACCESS_ONLY_BIT_EXT, every element of pLibraries must have been created with VK_PIPELINE_CREATE_PROTECTED_ACCESS_ONLY_BIT_EXT

  • VUID-VkPipelineLibraryCreateInfoKHR-pipeline-07407
    If pipeline is being created without VK_PIPELINE_CREATE_PROTECTED_ACCESS_ONLY_BIT_EXT, every element of pLibraries must have been created without VK_PIPELINE_CREATE_PROTECTED_ACCESS_ONLY_BIT_EXT

Valid Usage (Implicit)

  • VUID-VkPipelineLibraryCreateInfoKHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_PIPELINE_LIBRARY_CREATE_INFO_KHR

  • VUID-VkPipelineLibraryCreateInfoKHR-pLibraries-parameter
    If libraryCount is not 0, pLibraries must be a valid pointer to an array of libraryCount valid VkPipeline handles

Pipelines created with VK_PIPELINE_CREATE_LIBRARY_BIT_KHR libraries can depend on other pipeline libraries in VkPipelineLibraryCreateInfoKHR.

A pipeline library is considered in-use, as long as one of the linking pipelines is in-use. This applies recursively if a pipeline library includes other pipeline libraries.

10.11. Pipeline Binding

Once a pipeline has been created, it can be bound to the command buffer using the command:

// Provided by VK_VERSION_1_0
void vkCmdBindPipeline(
    VkCommandBuffer                             commandBuffer,
    VkPipelineBindPoint                         pipelineBindPoint,
    VkPipeline                                  pipeline);

  • commandBuffer is the command buffer that the pipeline will be bound to.

  • pipelineBindPoint is a VkPipelineBindPoint value specifying to which bind point the pipeline is bound. Binding one does not disturb the others.

  • pipeline is the pipeline to be bound.

Once bound, a pipeline binding affects subsequent commands that interact with the given pipeline type in the command buffer until a different pipeline of the same type is bound to the bind point, or until the pipeline bind point is disturbed by binding a shader object as described in Interaction with Pipelines. Commands that do not interact with the given pipeline type must not be affected by the pipeline state.

Valid Usage

  • VUID-vkCmdBindPipeline-pipelineBindPoint-00777
    If pipelineBindPoint is VK_PIPELINE_BIND_POINT_COMPUTE, the VkCommandPool that commandBuffer was allocated from must support compute operations

  • VUID-vkCmdBindPipeline-pipelineBindPoint-00778
    If pipelineBindPoint is VK_PIPELINE_BIND_POINT_GRAPHICS, the VkCommandPool that commandBuffer was allocated from must support graphics operations

  • VUID-vkCmdBindPipeline-pipelineBindPoint-00779
    If pipelineBindPoint is VK_PIPELINE_BIND_POINT_COMPUTE, pipeline must be a compute pipeline

  • VUID-vkCmdBindPipeline-pipelineBindPoint-00780
    If pipelineBindPoint is VK_PIPELINE_BIND_POINT_GRAPHICS, pipeline must be a graphics pipeline

  • VUID-vkCmdBindPipeline-pipeline-00781
    If the variableMultisampleRate feature is not supported, pipeline is a graphics pipeline, the current subpass uses no attachments, and this is not the first call to this function with a graphics pipeline after transitioning to the current subpass, then the sample count specified by this pipeline must match that set in the previous pipeline

  • VUID-vkCmdBindPipeline-variableSampleLocations-01525
    If VkPhysicalDeviceSampleLocationsPropertiesEXT::variableSampleLocations is VK_FALSE, and pipeline is a graphics pipeline created with a VkPipelineSampleLocationsStateCreateInfoEXT structure having its sampleLocationsEnable member set to VK_TRUE but without VK_DYNAMIC_STATE_SAMPLE_LOCATIONS_EXT enabled then the current render pass instance must have been begun by specifying a VkRenderPassSampleLocationsBeginInfoEXT structure whose pPostSubpassSampleLocations member contains an element with a subpassIndex matching the current subpass index and the sampleLocationsInfo member of that element must match the sampleLocationsInfo specified in VkPipelineSampleLocationsStateCreateInfoEXT when the pipeline was created

  • VUID-vkCmdBindPipeline-None-02323
    This command must not be recorded when transform feedback is active

  • VUID-vkCmdBindPipeline-pipelineBindPoint-02391
    If pipelineBindPoint is VK_PIPELINE_BIND_POINT_RAY_TRACING_KHR, the VkCommandPool that commandBuffer was allocated from must support compute operations

  • VUID-vkCmdBindPipeline-pipelineBindPoint-02392
    If pipelineBindPoint is VK_PIPELINE_BIND_POINT_RAY_TRACING_KHR, pipeline must be a ray tracing pipeline

  • VUID-vkCmdBindPipeline-pipelineBindPoint-06721
    If pipelineBindPoint is VK_PIPELINE_BIND_POINT_RAY_TRACING_KHR, commandBuffer must not be a protected command buffer

  • VUID-vkCmdBindPipeline-pipelineProtectedAccess-07408
    If the pipelineProtectedAccess feature is enabled, and commandBuffer is a protected command buffer, pipeline must have been created without VK_PIPELINE_CREATE_NO_PROTECTED_ACCESS_BIT_EXT

  • VUID-vkCmdBindPipeline-pipelineProtectedAccess-07409
    If the pipelineProtectedAccess feature is enabled, and commandBuffer is not a protected command buffer, pipeline must have been created without VK_PIPELINE_CREATE_PROTECTED_ACCESS_ONLY_BIT_EXT

  • VUID-vkCmdBindPipeline-pipeline-03382
    pipeline must not have been created with VK_PIPELINE_CREATE_LIBRARY_BIT_KHR set

  • VUID-vkCmdBindPipeline-commandBuffer-04808
    If commandBuffer is a secondary command buffer with VkCommandBufferInheritanceViewportScissorInfoNV::viewportScissor2D enabled and pipelineBindPoint is VK_PIPELINE_BIND_POINT_GRAPHICS, then the pipeline must have been created with VK_DYNAMIC_STATE_VIEWPORT_WITH_COUNT or VK_DYNAMIC_STATE_VIEWPORT, and VK_DYNAMIC_STATE_SCISSOR_WITH_COUNT or VK_DYNAMIC_STATE_SCISSOR enabled

  • VUID-vkCmdBindPipeline-commandBuffer-04809
    If commandBuffer is a secondary command buffer with VkCommandBufferInheritanceViewportScissorInfoNV::viewportScissor2D enabled and pipelineBindPoint is VK_PIPELINE_BIND_POINT_GRAPHICS and pipeline was created with VkPipelineDiscardRectangleStateCreateInfoEXT structure and its discardRectangleCount member is not 0, or the pipeline was created with VK_DYNAMIC_STATE_DISCARD_RECTANGLE_ENABLE_EXT enabled, then the pipeline must have been created with VK_DYNAMIC_STATE_DISCARD_RECTANGLE_EXT enabled

  • VUID-vkCmdBindPipeline-pipelineBindPoint-04881
    If pipelineBindPoint is VK_PIPELINE_BIND_POINT_GRAPHICS and the provokingVertexModePerPipeline limit is VK_FALSE, then pipeline’s VkPipelineRasterizationProvokingVertexStateCreateInfoEXT::provokingVertexMode must be the same as that of any other pipelines previously bound to this bind point within the current render pass instance, including any pipeline already bound when beginning the render pass instance

  • VUID-vkCmdBindPipeline-pipelineBindPoint-04949
    If pipelineBindPoint is VK_PIPELINE_BIND_POINT_SUBPASS_SHADING_HUAWEI, the VkCommandPool that commandBuffer was allocated from must support compute operations

  • VUID-vkCmdBindPipeline-pipelineBindPoint-04950
    If pipelineBindPoint is VK_PIPELINE_BIND_POINT_SUBPASS_SHADING_HUAWEI, pipeline must be a subpass shading pipeline

Valid Usage (Implicit)

  • VUID-vkCmdBindPipeline-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdBindPipeline-pipelineBindPoint-parameter
    pipelineBindPoint must be a valid VkPipelineBindPoint value

  • VUID-vkCmdBindPipeline-pipeline-parameter
    pipeline must be a valid VkPipeline handle

  • VUID-vkCmdBindPipeline-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdBindPipeline-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support graphics, or compute operations

  • VUID-vkCmdBindPipeline-videocoding
    This command must only be called outside of a video coding scope

  • VUID-vkCmdBindPipeline-commonparent
    Both of commandBuffer, and pipeline must have been created, allocated, or retrieved from the same VkDevice

Host Synchronization

  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Video Coding Scope Supported Queue Types Command Type

Primary
Secondary

Both

Outside

Graphics
Compute

State

Possible values of vkCmdBindPipeline::pipelineBindPoint, specifying the bind point of a pipeline object, are:

// Provided by VK_VERSION_1_0
typedef enum VkPipelineBindPoint {
    VK_PIPELINE_BIND_POINT_GRAPHICS = 0,
    VK_PIPELINE_BIND_POINT_COMPUTE = 1,
#ifdef VK_ENABLE_BETA_EXTENSIONS
  // Provided by VK_AMDX_shader_enqueue
    VK_PIPELINE_BIND_POINT_EXECUTION_GRAPH_AMDX = 1000134000,
#endif
  // Provided by VK_KHR_ray_tracing_pipeline
    VK_PIPELINE_BIND_POINT_RAY_TRACING_KHR = 1000165000,
  // Provided by VK_HUAWEI_subpass_shading
    VK_PIPELINE_BIND_POINT_SUBPASS_SHADING_HUAWEI = 1000369003,
  // Provided by VK_NV_ray_tracing
    VK_PIPELINE_BIND_POINT_RAY_TRACING_NV = VK_PIPELINE_BIND_POINT_RAY_TRACING_KHR,
} VkPipelineBindPoint;

  • VK_PIPELINE_BIND_POINT_COMPUTE specifies binding as a compute pipeline.

  • VK_PIPELINE_BIND_POINT_GRAPHICS specifies binding as a graphics pipeline.

  • VK_PIPELINE_BIND_POINT_RAY_TRACING_KHR specifies binding as a ray tracing pipeline.

  • VK_PIPELINE_BIND_POINT_SUBPASS_SHADING_HUAWEI specifies binding as a subpass shading pipeline.

  • VK_PIPELINE_BIND_POINT_EXECUTION_GRAPH_AMDX specifies binding as an execution graph pipeline.

For pipelines that were created with the support of multiple shader groups (see Graphics Pipeline Shader Groups), the regular vkCmdBindPipeline command will bind Shader Group 0. To explicitly bind a shader group use:

// Provided by VK_NV_device_generated_commands
void vkCmdBindPipelineShaderGroupNV(
    VkCommandBuffer                             commandBuffer,
    VkPipelineBindPoint                         pipelineBindPoint,
    VkPipeline                                  pipeline,
    uint32_t                                    groupIndex);

  • commandBuffer is the command buffer that the pipeline will be bound to.

  • pipelineBindPoint is a VkPipelineBindPoint value specifying the bind point to which the pipeline will be bound.

  • pipeline is the pipeline to be bound.

  • groupIndex is the shader group to be bound.

Valid Usage

  • VUID-vkCmdBindPipelineShaderGroupNV-groupIndex-02893
    groupIndex must be 0 or less than the effective VkGraphicsPipelineShaderGroupsCreateInfoNV::groupCount including the referenced pipelines

  • VUID-vkCmdBindPipelineShaderGroupNV-pipelineBindPoint-02894
    The pipelineBindPoint must be VK_PIPELINE_BIND_POINT_GRAPHICS

  • VUID-vkCmdBindPipelineShaderGroupNV-groupIndex-02895
    The same restrictions as vkCmdBindPipeline apply as if the bound pipeline was created only with the Shader Group from the groupIndex information

  • VUID-vkCmdBindPipelineShaderGroupNV-deviceGeneratedCommands-02896
    The deviceGeneratedCommands feature must be enabled

Valid Usage (Implicit)

  • VUID-vkCmdBindPipelineShaderGroupNV-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdBindPipelineShaderGroupNV-pipelineBindPoint-parameter
    pipelineBindPoint must be a valid VkPipelineBindPoint value

  • VUID-vkCmdBindPipelineShaderGroupNV-pipeline-parameter
    pipeline must be a valid VkPipeline handle

  • VUID-vkCmdBindPipelineShaderGroupNV-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdBindPipelineShaderGroupNV-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support graphics, or compute operations

  • VUID-vkCmdBindPipelineShaderGroupNV-videocoding
    This command must only be called outside of a video coding scope

  • VUID-vkCmdBindPipelineShaderGroupNV-commonparent
    Both of commandBuffer, and pipeline must have been created, allocated, or retrieved from the same VkDevice

Host Synchronization

  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Video Coding Scope Supported Queue Types Command Type

Primary
Secondary

Both

Outside

Graphics
Compute

State

10.11.1. Interaction With Shader Objects

If the shaderObject feature is enabled, applications can use both pipelines and shader objects at the same time. The interaction between pipelines and shader objects is described in Interaction with Pipelines.

10.12. Dynamic State

When a pipeline object is bound, any pipeline object state that is not specified as dynamic is applied to the command buffer state. Pipeline object state that is specified as dynamic is not applied to the command buffer state at this time.

Instead, dynamic state can be modified at any time and persists for the lifetime of the command buffer, or until modified by another dynamic state setting command, or made invalid by binding a pipeline in which that state is statically specified.

If the commandBufferInheritance feature is enabled, all valid state from the previously executed command buffer in the queue is inherited into the next command buffer executed in the same queue. This inherited state does not need to be set again before draw or dispatch commands.

When a pipeline object is bound, the following applies to each state parameter:

  • If the state is not specified as dynamic in the new pipeline object, then that command buffer state is overwritten by the state in the new pipeline object. Before any draw or dispatch call with this pipeline there must not have been any calls to any of the corresponding dynamic state setting commands after this pipeline was bound.

  • If the state is specified as dynamic in the new pipeline object, then that command buffer state is not disturbed. Before any draw or dispatch call with this pipeline there must have been at least one call to each of the corresponding dynamic state setting commands. The state-setting commands must be recorded after command buffer recording was begun, or after the last command binding a pipeline object with that state specified as static, whichever was the latter.

  • If the state is not included (corresponding pointer in VkGraphicsPipelineCreateInfo was NULL or was ignored) in the new pipeline object, then that command buffer state is not disturbed. For example, mesh shading pipelines do not include vertex input state and therefore do not disturb any such command buffer state.

Dynamic state that does not affect the result of operations can be left undefined.

Note

For example, if blending is disabled by the pipeline object state then the dynamic color blend constants do not need to be specified in the command buffer, even if this state is specified as dynamic in the pipeline object.
Note

Applications running on Vulkan implementations advertising an VkPhysicalDeviceDriverProperties::conformanceVersion less than 1.3.8.0 should be aware that rebinding the currently bound pipeline object may not reapply static state.

10.13. Pipeline Properties and Shader Information

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. To query the properties of these pipeline executables, call:

// Provided by VK_KHR_pipeline_executable_properties
VkResult vkGetPipelineExecutablePropertiesKHR(
    VkDevice                                    device,
    const VkPipelineInfoKHR*                    pPipelineInfo,
    uint32_t*                                   pExecutableCount,
    VkPipelineExecutablePropertiesKHR*          pProperties);

  • device is the device that created the pipeline.

  • pPipelineInfo describes the pipeline being queried.

  • pExecutableCount is a pointer to an integer related to the number of pipeline executables available or queried, as described below.

  • pProperties is either NULL or a pointer to an array of VkPipelineExecutablePropertiesKHR structures.

If pProperties is NULL, then the number of pipeline executables associated with the pipeline is returned in pExecutableCount. Otherwise, pExecutableCount must point to a variable set by the application to the number of elements in the pProperties array, and on return the variable is overwritten with the number of structures actually written to pProperties. If pExecutableCount is less than the number of pipeline executables associated with the pipeline, at most pExecutableCount structures will be written, and VK_INCOMPLETE will be returned instead of VK_SUCCESS, to indicate that not all the available properties were returned.

Valid Usage

  • VUID-vkGetPipelineExecutablePropertiesKHR-pipelineExecutableInfo-03270
    The pipelineExecutableInfo feature must be enabled

  • VUID-vkGetPipelineExecutablePropertiesKHR-pipeline-03271
    The pipeline member of pPipelineInfo must have been created with device

Valid Usage (Implicit)

  • VUID-vkGetPipelineExecutablePropertiesKHR-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkGetPipelineExecutablePropertiesKHR-pPipelineInfo-parameter
    pPipelineInfo must be a valid pointer to a valid VkPipelineInfoKHR structure

  • VUID-vkGetPipelineExecutablePropertiesKHR-pExecutableCount-parameter
    pExecutableCount must be a valid pointer to a uint32_t value

  • VUID-vkGetPipelineExecutablePropertiesKHR-pProperties-parameter
    If the value referenced by pExecutableCount is not 0, and pProperties is not NULL, pProperties must be a valid pointer to an array of pExecutableCount VkPipelineExecutablePropertiesKHR structures

Return Codes
Success

  • VK_SUCCESS

  • VK_INCOMPLETE

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

The VkPipelineExecutablePropertiesKHR structure is defined as:

// Provided by VK_KHR_pipeline_executable_properties
typedef struct VkPipelineExecutablePropertiesKHR {
    VkStructureType       sType;
    void*                 pNext;
    VkShaderStageFlags    stages;
    char                  name[VK_MAX_DESCRIPTION_SIZE];
    char                  description[VK_MAX_DESCRIPTION_SIZE];
    uint32_t              subgroupSize;
} VkPipelineExecutablePropertiesKHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • stages is a bitmask of zero or more VkShaderStageFlagBits indicating which shader stages (if any) were principally used as inputs to compile this pipeline executable.

  • name is an array of VK_MAX_DESCRIPTION_SIZE char containing a null-terminated UTF-8 string which is a short human readable name for this pipeline executable.

  • description is an array of VK_MAX_DESCRIPTION_SIZE char containing a null-terminated UTF-8 string which is a human readable description for this pipeline executable.

  • subgroupSize is the subgroup size with which this pipeline executable is dispatched.

Not all implementations have a 1:1 mapping between shader stages and pipeline executables and some implementations may reduce a given shader stage to fixed function hardware programming such that no pipeline executable is available. No guarantees are provided about the mapping between shader stages and pipeline executables and stages should be considered a best effort hint. Because the application cannot rely on the stages field to provide an exact description, name and description provide a human readable name and description which more accurately describes the given pipeline executable.

Valid Usage (Implicit)

  • VUID-VkPipelineExecutablePropertiesKHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_PIPELINE_EXECUTABLE_PROPERTIES_KHR

  • VUID-VkPipelineExecutablePropertiesKHR-pNext-pNext
    pNext must be NULL

To query the pipeline properties call:

// Provided by VK_EXT_pipeline_properties
VkResult vkGetPipelinePropertiesEXT(
    VkDevice                                    device,
    const VkPipelineInfoEXT*                    pPipelineInfo,
    VkBaseOutStructure*                         pPipelineProperties);

  • device is the logical device that created the pipeline.

  • pPipelineInfo is a pointer to a VkPipelineInfoEXT structure which describes the pipeline being queried.

  • pPipelineProperties is a pointer to a VkBaseOutStructure structure in which the pipeline properties will be written.

To query a pipeline’s pipelineIdentifier pass a VkPipelinePropertiesIdentifierEXT structure in pPipelineProperties. Each pipeline is associated with a pipelineIdentifier and the identifier is implementation specific.

Valid Usage

  • VUID-vkGetPipelinePropertiesEXT-pipeline-06738
    The pipeline member of pPipelineInfo must have been created with device

  • VUID-vkGetPipelinePropertiesEXT-pPipelineProperties-06739
    pPipelineProperties must be a valid pointer to a VkPipelinePropertiesIdentifierEXT structure

  • VUID-vkGetPipelinePropertiesEXT-None-06766
    The pipelinePropertiesIdentifier feature must be enabled

Valid Usage (Implicit)

  • VUID-vkGetPipelinePropertiesEXT-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkGetPipelinePropertiesEXT-pPipelineInfo-parameter
    pPipelineInfo must be a valid pointer to a valid VkPipelineInfoEXT structure

Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

The VkPipelinePropertiesIdentifierEXT structure is defined as:

// Provided by VK_EXT_pipeline_properties
typedef struct VkPipelinePropertiesIdentifierEXT {
    VkStructureType    sType;
    void*              pNext;
    uint8_t            pipelineIdentifier[VK_UUID_SIZE];
} VkPipelinePropertiesIdentifierEXT;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • pipelineIdentifier is an array of VK_UUID_SIZE uint8_t values into which the pipeline identifier will be written.

Valid Usage (Implicit)

  • VUID-VkPipelinePropertiesIdentifierEXT-sType-sType
    sType must be VK_STRUCTURE_TYPE_PIPELINE_PROPERTIES_IDENTIFIER_EXT

  • VUID-VkPipelinePropertiesIdentifierEXT-pNext-pNext
    pNext must be NULL

The VkPipelineInfoKHR structure is defined as:

// Provided by VK_KHR_pipeline_executable_properties
typedef struct VkPipelineInfoKHR {
    VkStructureType    sType;
    const void*        pNext;
    VkPipeline         pipeline;
} VkPipelineInfoKHR;

or the equivalent

// Provided by VK_EXT_pipeline_properties
typedef VkPipelineInfoKHR VkPipelineInfoEXT;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • pipeline is a VkPipeline handle.

Valid Usage (Implicit)

  • VUID-VkPipelineInfoKHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_PIPELINE_INFO_KHR

  • VUID-VkPipelineInfoKHR-pNext-pNext
    pNext must be NULL

  • VUID-VkPipelineInfoKHR-pipeline-parameter
    pipeline must be a valid VkPipeline handle

Each pipeline executable may have a set of statistics associated with it that are generated by the pipeline compilation process. These statistics may include things such as instruction counts, amount of spilling (if any), maximum number of simultaneous threads, or anything else which may aid developers in evaluating the expected performance of a shader. To query the compile time statistics associated with a pipeline executable, call:

// Provided by VK_KHR_pipeline_executable_properties
VkResult vkGetPipelineExecutableStatisticsKHR(
    VkDevice                                    device,
    const VkPipelineExecutableInfoKHR*          pExecutableInfo,
    uint32_t*                                   pStatisticCount,
    VkPipelineExecutableStatisticKHR*           pStatistics);

  • device is the device that created the pipeline.

  • pExecutableInfo describes the pipeline executable being queried.

  • pStatisticCount is a pointer to an integer related to the number of statistics available or queried, as described below.

  • pStatistics is either NULL or a pointer to an array of VkPipelineExecutableStatisticKHR structures.

If pStatistics is NULL, then the number of statistics associated with the pipeline executable is returned in pStatisticCount. Otherwise, pStatisticCount must point to a variable set by the application to the number of elements in the pStatistics array, and on return the variable is overwritten with the number of structures actually written to pStatistics. If pStatisticCount is less than the number of statistics associated with the pipeline executable, at most pStatisticCount structures will be written, and VK_INCOMPLETE will be returned instead of VK_SUCCESS, to indicate that not all the available statistics were returned.

Valid Usage

  • VUID-vkGetPipelineExecutableStatisticsKHR-pipelineExecutableInfo-03272
    The pipelineExecutableInfo feature must be enabled

  • VUID-vkGetPipelineExecutableStatisticsKHR-pipeline-03273
    The pipeline member of pExecutableInfo must have been created with device

  • VUID-vkGetPipelineExecutableStatisticsKHR-pipeline-03274
    The pipeline member of pExecutableInfo must have been created with VK_PIPELINE_CREATE_CAPTURE_STATISTICS_BIT_KHR

Valid Usage (Implicit)

  • VUID-vkGetPipelineExecutableStatisticsKHR-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkGetPipelineExecutableStatisticsKHR-pExecutableInfo-parameter
    pExecutableInfo must be a valid pointer to a valid VkPipelineExecutableInfoKHR structure

  • VUID-vkGetPipelineExecutableStatisticsKHR-pStatisticCount-parameter
    pStatisticCount must be a valid pointer to a uint32_t value

  • VUID-vkGetPipelineExecutableStatisticsKHR-pStatistics-parameter
    If the value referenced by pStatisticCount is not 0, and pStatistics is not NULL, pStatistics must be a valid pointer to an array of pStatisticCount VkPipelineExecutableStatisticKHR structures

Return Codes
Success

  • VK_SUCCESS

  • VK_INCOMPLETE

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

The VkPipelineExecutableInfoKHR structure is defined as:

// Provided by VK_KHR_pipeline_executable_properties
typedef struct VkPipelineExecutableInfoKHR {
    VkStructureType    sType;
    const void*        pNext;
    VkPipeline         pipeline;
    uint32_t           executableIndex;
} VkPipelineExecutableInfoKHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • pipeline is the pipeline to query.

  • executableIndex is the index of the pipeline executable to query in the array of executable properties returned by vkGetPipelineExecutablePropertiesKHR.

Valid Usage

  • VUID-VkPipelineExecutableInfoKHR-executableIndex-03275
    executableIndex must be less than the number of pipeline executables associated with pipeline as returned in the pExecutableCount parameter of vkGetPipelineExecutablePropertiesKHR

Valid Usage (Implicit)

  • VUID-VkPipelineExecutableInfoKHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_PIPELINE_EXECUTABLE_INFO_KHR

  • VUID-VkPipelineExecutableInfoKHR-pNext-pNext
    pNext must be NULL

  • VUID-VkPipelineExecutableInfoKHR-pipeline-parameter
    pipeline must be a valid VkPipeline handle

The VkPipelineExecutableStatisticKHR structure is defined as:

// Provided by VK_KHR_pipeline_executable_properties
typedef struct VkPipelineExecutableStatisticKHR {
    VkStructureType                           sType;
    void*                                     pNext;
    char                                      name[VK_MAX_DESCRIPTION_SIZE];
    char                                      description[VK_MAX_DESCRIPTION_SIZE];
    VkPipelineExecutableStatisticFormatKHR    format;
    VkPipelineExecutableStatisticValueKHR     value;
} VkPipelineExecutableStatisticKHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • name is an array of VK_MAX_DESCRIPTION_SIZE char containing a null-terminated UTF-8 string which is a short human readable name for this statistic.

  • description is an array of VK_MAX_DESCRIPTION_SIZE char containing a null-terminated UTF-8 string which is a human readable description for this statistic.

  • format is a VkPipelineExecutableStatisticFormatKHR value specifying the format of the data found in value.

  • value is the value of this statistic.

Valid Usage (Implicit)

  • VUID-VkPipelineExecutableStatisticKHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_PIPELINE_EXECUTABLE_STATISTIC_KHR

  • VUID-VkPipelineExecutableStatisticKHR-pNext-pNext
    pNext must be NULL

The VkPipelineExecutableStatisticFormatKHR enum is defined as:

// Provided by VK_KHR_pipeline_executable_properties
typedef enum VkPipelineExecutableStatisticFormatKHR {
    VK_PIPELINE_EXECUTABLE_STATISTIC_FORMAT_BOOL32_KHR = 0,
    VK_PIPELINE_EXECUTABLE_STATISTIC_FORMAT_INT64_KHR = 1,
    VK_PIPELINE_EXECUTABLE_STATISTIC_FORMAT_UINT64_KHR = 2,
    VK_PIPELINE_EXECUTABLE_STATISTIC_FORMAT_FLOAT64_KHR = 3,
} VkPipelineExecutableStatisticFormatKHR;

  • VK_PIPELINE_EXECUTABLE_STATISTIC_FORMAT_BOOL32_KHR specifies that the statistic is returned as a 32-bit boolean value which must be either VK_TRUE or VK_FALSE and should be read from the b32 field of VkPipelineExecutableStatisticValueKHR.

  • VK_PIPELINE_EXECUTABLE_STATISTIC_FORMAT_INT64_KHR specifies that the statistic is returned as a signed 64-bit integer and should be read from the i64 field of VkPipelineExecutableStatisticValueKHR.

  • VK_PIPELINE_EXECUTABLE_STATISTIC_FORMAT_UINT64_KHR specifies that the statistic is returned as an unsigned 64-bit integer and should be read from the u64 field of VkPipelineExecutableStatisticValueKHR.

  • VK_PIPELINE_EXECUTABLE_STATISTIC_FORMAT_FLOAT64_KHR specifies that the statistic is returned as a 64-bit floating-point value and should be read from the f64 field of VkPipelineExecutableStatisticValueKHR.

The VkPipelineExecutableStatisticValueKHR union is defined as:

// Provided by VK_KHR_pipeline_executable_properties
typedef union VkPipelineExecutableStatisticValueKHR {
    VkBool32    b32;
    int64_t     i64;
    uint64_t    u64;
    double      f64;
} VkPipelineExecutableStatisticValueKHR;

  • b32 is the 32-bit boolean value if the VkPipelineExecutableStatisticFormatKHR is VK_PIPELINE_EXECUTABLE_STATISTIC_FORMAT_BOOL32_KHR.

  • i64 is the signed 64-bit integer value if the VkPipelineExecutableStatisticFormatKHR is VK_PIPELINE_EXECUTABLE_STATISTIC_FORMAT_INT64_KHR.

  • u64 is the unsigned 64-bit integer value if the VkPipelineExecutableStatisticFormatKHR is VK_PIPELINE_EXECUTABLE_STATISTIC_FORMAT_UINT64_KHR.

  • f64 is the 64-bit floating-point value if the VkPipelineExecutableStatisticFormatKHR is VK_PIPELINE_EXECUTABLE_STATISTIC_FORMAT_FLOAT64_KHR.

Each pipeline executable may have one or more text or binary internal representations associated with it which are generated as part of the compile process. These may include the final shader assembly, a binary form of the compiled shader, or the shader compiler’s internal representation at any number of intermediate compile steps. To query the internal representations associated with a pipeline executable, call:

// Provided by VK_KHR_pipeline_executable_properties
VkResult vkGetPipelineExecutableInternalRepresentationsKHR(
    VkDevice                                    device,
    const VkPipelineExecutableInfoKHR*          pExecutableInfo,
    uint32_t*                                   pInternalRepresentationCount,
    VkPipelineExecutableInternalRepresentationKHR* pInternalRepresentations);

  • device is the device that created the pipeline.

  • pExecutableInfo describes the pipeline executable being queried.

  • pInternalRepresentationCount is a pointer to an integer related to the number of internal representations available or queried, as described below.

  • pInternalRepresentations is either NULL or a pointer to an array of VkPipelineExecutableInternalRepresentationKHR structures.

If pInternalRepresentations is NULL, then the number of internal representations associated with the pipeline executable is returned in pInternalRepresentationCount. Otherwise, pInternalRepresentationCount must point to a variable set by the application to the number of elements in the pInternalRepresentations array, and on return the variable is overwritten with the number of structures actually written to pInternalRepresentations. If pInternalRepresentationCount is less than the number of internal representations associated with the pipeline executable, at most pInternalRepresentationCount structures will be written, and VK_INCOMPLETE will be returned instead of VK_SUCCESS, to indicate that not all the available representations were returned.

While the details of the internal representations remain implementation-dependent, the implementation should order the internal representations in the order in which they occur in the compiled pipeline with the final shader assembly (if any) last.

Valid Usage

  • VUID-vkGetPipelineExecutableInternalRepresentationsKHR-pipelineExecutableInfo-03276
    The pipelineExecutableInfo feature must be enabled

  • VUID-vkGetPipelineExecutableInternalRepresentationsKHR-pipeline-03277
    The pipeline member of pExecutableInfo must have been created with device

  • VUID-vkGetPipelineExecutableInternalRepresentationsKHR-pipeline-03278
    The pipeline member of pExecutableInfo must have been created with VK_PIPELINE_CREATE_CAPTURE_INTERNAL_REPRESENTATIONS_BIT_KHR

Valid Usage (Implicit)

  • VUID-vkGetPipelineExecutableInternalRepresentationsKHR-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkGetPipelineExecutableInternalRepresentationsKHR-pExecutableInfo-parameter
    pExecutableInfo must be a valid pointer to a valid VkPipelineExecutableInfoKHR structure

  • VUID-vkGetPipelineExecutableInternalRepresentationsKHR-pInternalRepresentationCount-parameter
    pInternalRepresentationCount must be a valid pointer to a uint32_t value

  • VUID-vkGetPipelineExecutableInternalRepresentationsKHR-pInternalRepresentations-parameter
    If the value referenced by pInternalRepresentationCount is not 0, and pInternalRepresentations is not NULL, pInternalRepresentations must be a valid pointer to an array of pInternalRepresentationCount VkPipelineExecutableInternalRepresentationKHR structures

Return Codes
Success

  • VK_SUCCESS

  • VK_INCOMPLETE

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

The VkPipelineExecutableInternalRepresentationKHR structure is defined as:

// Provided by VK_KHR_pipeline_executable_properties
typedef struct VkPipelineExecutableInternalRepresentationKHR {
    VkStructureType    sType;
    void*              pNext;
    char               name[VK_MAX_DESCRIPTION_SIZE];
    char               description[VK_MAX_DESCRIPTION_SIZE];
    VkBool32           isText;
    size_t             dataSize;
    void*              pData;
} VkPipelineExecutableInternalRepresentationKHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • name is an array of VK_MAX_DESCRIPTION_SIZE char containing a null-terminated UTF-8 string which is a short human readable name for this internal representation.

  • description is an array of VK_MAX_DESCRIPTION_SIZE char containing a null-terminated UTF-8 string which is a human readable description for this internal representation.

  • isText specifies whether the returned data is text or opaque data. If isText is VK_TRUE then the data returned in pData is text and is guaranteed to be a null-terminated UTF-8 string.

  • dataSize is an integer related to the size, in bytes, of the internal representation’s data, as described below.

  • pData is either NULL or a pointer to a block of data into which the implementation will write the internal representation.

If pData is NULL, then the size, in bytes, of the internal representation data is returned in dataSize. Otherwise, dataSize must be the size of the buffer, in bytes, pointed to by pData and on return dataSize is overwritten with the number of bytes of data actually written to pData including any trailing null character. If dataSize is less than the size, in bytes, of the internal representation’s data, at most dataSize bytes of data will be written to pData, and VK_INCOMPLETE will be returned instead of VK_SUCCESS, to indicate that not all the available representation was returned.

If isText is VK_TRUE and pData is not NULL and dataSize is not zero, the last byte written to pData will be a null character.

Valid Usage (Implicit)

  • VUID-VkPipelineExecutableInternalRepresentationKHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_PIPELINE_EXECUTABLE_INTERNAL_REPRESENTATION_KHR

  • VUID-VkPipelineExecutableInternalRepresentationKHR-pNext-pNext
    pNext must be NULL

Information about a particular shader that has been compiled as part of a pipeline object can be extracted by calling:

// Provided by VK_AMD_shader_info
VkResult vkGetShaderInfoAMD(
    VkDevice                                    device,
    VkPipeline                                  pipeline,
    VkShaderStageFlagBits                       shaderStage,
    VkShaderInfoTypeAMD                         infoType,
    size_t*                                     pInfoSize,
    void*                                       pInfo);

  • device is the device that created pipeline.

  • pipeline is the target of the query.

  • shaderStage is a VkShaderStageFlagBits specifying the particular shader within the pipeline about which information is being queried.

  • infoType describes what kind of information is being queried.

  • pInfoSize is a pointer to a value related to the amount of data the query returns, as described below.

  • pInfo is either NULL or a pointer to a buffer.

If pInfo is NULL, then the maximum size of the information that can be retrieved about the shader, in bytes, is returned in pInfoSize. Otherwise, pInfoSize must point to a variable set by the application to the size of the buffer, in bytes, pointed to by pInfo, and on return the variable is overwritten with the amount of data actually written to pInfo. If pInfoSize is less than the maximum size that can be retrieved by the pipeline cache, then at most pInfoSize bytes will be written to pInfo, and VK_INCOMPLETE will be returned, instead of VK_SUCCESS, to indicate that not all required of the pipeline cache was returned.

Not all information is available for every shader and implementations may not support all kinds of information for any shader. When a certain type of information is unavailable, the function returns VK_ERROR_FEATURE_NOT_PRESENT.

If information is successfully and fully queried, the function will return VK_SUCCESS.

For infoType VK_SHADER_INFO_TYPE_STATISTICS_AMD, a VkShaderStatisticsInfoAMD structure will be written to the buffer pointed to by pInfo. This structure will be populated with statistics regarding the physical device resources used by that shader along with other miscellaneous information and is described in further detail below.

For infoType VK_SHADER_INFO_TYPE_DISASSEMBLY_AMD, pInfo is a pointer to a null-terminated UTF-8 string containing human-readable disassembly. The exact formatting and contents of the disassembly string are vendor-specific.

The formatting and contents of all other types of information, including infoType VK_SHADER_INFO_TYPE_BINARY_AMD, are left to the vendor and are not further specified by this extension.

Valid Usage (Implicit)

  • VUID-vkGetShaderInfoAMD-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkGetShaderInfoAMD-pipeline-parameter
    pipeline must be a valid VkPipeline handle

  • VUID-vkGetShaderInfoAMD-shaderStage-parameter
    shaderStage must be a valid VkShaderStageFlagBits value

  • VUID-vkGetShaderInfoAMD-infoType-parameter
    infoType must be a valid VkShaderInfoTypeAMD value

  • VUID-vkGetShaderInfoAMD-pInfoSize-parameter
    pInfoSize must be a valid pointer to a size_t value

  • VUID-vkGetShaderInfoAMD-pInfo-parameter
    If the value referenced by pInfoSize is not 0, and pInfo is not NULL, pInfo must be a valid pointer to an array of pInfoSize bytes

  • VUID-vkGetShaderInfoAMD-pipeline-parent
    pipeline must have been created, allocated, or retrieved from device

Return Codes
Success

  • VK_SUCCESS

  • VK_INCOMPLETE

Failure

  • VK_ERROR_FEATURE_NOT_PRESENT

  • VK_ERROR_OUT_OF_HOST_MEMORY

Possible values of vkGetShaderInfoAMD::infoType, specifying the information being queried from a shader, are:

// Provided by VK_AMD_shader_info
typedef enum VkShaderInfoTypeAMD {
    VK_SHADER_INFO_TYPE_STATISTICS_AMD = 0,
    VK_SHADER_INFO_TYPE_BINARY_AMD = 1,
    VK_SHADER_INFO_TYPE_DISASSEMBLY_AMD = 2,
} VkShaderInfoTypeAMD;

  • VK_SHADER_INFO_TYPE_STATISTICS_AMD specifies that device resources used by a shader will be queried.

  • VK_SHADER_INFO_TYPE_BINARY_AMD specifies that implementation-specific information will be queried.

  • VK_SHADER_INFO_TYPE_DISASSEMBLY_AMD specifies that human-readable disassembly of a shader.

The VkShaderStatisticsInfoAMD structure is defined as:

// Provided by VK_AMD_shader_info
typedef struct VkShaderStatisticsInfoAMD {
    VkShaderStageFlags          shaderStageMask;
    VkShaderResourceUsageAMD    resourceUsage;
    uint32_t                    numPhysicalVgprs;
    uint32_t                    numPhysicalSgprs;
    uint32_t                    numAvailableVgprs;
    uint32_t                    numAvailableSgprs;
    uint32_t                    computeWorkGroupSize[3];
} VkShaderStatisticsInfoAMD;

  • shaderStageMask are the combination of logical shader stages contained within this shader.

  • resourceUsage is a VkShaderResourceUsageAMD structure describing internal physical device resources used by this shader.

  • numPhysicalVgprs is the maximum number of vector instruction general-purpose registers (VGPRs) available to the physical device.

  • numPhysicalSgprs is the maximum number of scalar instruction general-purpose registers (SGPRs) available to the physical device.

  • numAvailableVgprs is the maximum limit of VGPRs made available to the shader compiler.

  • numAvailableSgprs is the maximum limit of SGPRs made available to the shader compiler.

  • computeWorkGroupSize is the local workgroup size of this shader in { X, Y, Z } dimensions.

Some implementations may merge multiple logical shader stages together in a single shader. In such cases, shaderStageMask will contain a bitmask of all of the stages that are active within that shader. Consequently, if specifying those stages as input to vkGetShaderInfoAMD, the same output information may be returned for all such shader stage queries.

The number of available VGPRs and SGPRs (numAvailableVgprs and numAvailableSgprs respectively) are the shader-addressable subset of physical registers that is given as a limit to the compiler for register assignment. These values may further be limited by implementations due to performance optimizations where register pressure is a bottleneck.

The VkShaderResourceUsageAMD structure is defined as:

// Provided by VK_AMD_shader_info
typedef struct VkShaderResourceUsageAMD {
    uint32_t    numUsedVgprs;
    uint32_t    numUsedSgprs;
    uint32_t    ldsSizePerLocalWorkGroup;
    size_t      ldsUsageSizeInBytes;
    size_t      scratchMemUsageInBytes;
} VkShaderResourceUsageAMD;

  • numUsedVgprs is the number of vector instruction general-purpose registers used by this shader.

  • numUsedSgprs is the number of scalar instruction general-purpose registers used by this shader.

  • ldsSizePerLocalWorkGroup is the maximum local data store size per work group in bytes.

  • ldsUsageSizeInBytes is the LDS usage size in bytes per work group by this shader.

  • scratchMemUsageInBytes is the scratch memory usage in bytes by this shader.

10.14. Pipeline Compiler Control

The compilation of a pipeline can be tuned by adding a VkPipelineCompilerControlCreateInfoAMD structure to the pNext chain of VkGraphicsPipelineCreateInfo or VkComputePipelineCreateInfo.

// Provided by VK_AMD_pipeline_compiler_control
typedef struct VkPipelineCompilerControlCreateInfoAMD {
    VkStructureType                      sType;
    const void*                          pNext;
    VkPipelineCompilerControlFlagsAMD    compilerControlFlags;
} VkPipelineCompilerControlCreateInfoAMD;
Valid Usage (Implicit)

  • VUID-VkPipelineCompilerControlCreateInfoAMD-sType-sType
    sType must be VK_STRUCTURE_TYPE_PIPELINE_COMPILER_CONTROL_CREATE_INFO_AMD

  • VUID-VkPipelineCompilerControlCreateInfoAMD-compilerControlFlags-zerobitmask
    compilerControlFlags must be 0

There are currently no available flags for this extension; flags will be added by future versions of this extension.

// Provided by VK_AMD_pipeline_compiler_control
typedef enum VkPipelineCompilerControlFlagBitsAMD {
} VkPipelineCompilerControlFlagBitsAMD;
// Provided by VK_AMD_pipeline_compiler_control
typedef VkFlags VkPipelineCompilerControlFlagsAMD;

VkPipelineCompilerControlFlagsAMD is a bitmask type for setting a mask of zero or more VkPipelineCompilerControlFlagBitsAMD.

10.15. Pipeline Creation Feedback

Feedback about the creation of a particular pipeline object can be obtained by adding a VkPipelineCreationFeedbackCreateInfo structure to the pNext chain of VkGraphicsPipelineCreateInfo, VkRayTracingPipelineCreateInfoKHR, VkRayTracingPipelineCreateInfoNV, or VkComputePipelineCreateInfo. The VkPipelineCreationFeedbackCreateInfo structure is defined as:

// Provided by VK_VERSION_1_3
typedef struct VkPipelineCreationFeedbackCreateInfo {
    VkStructureType                sType;
    const void*                    pNext;
    VkPipelineCreationFeedback*    pPipelineCreationFeedback;
    uint32_t                       pipelineStageCreationFeedbackCount;
    VkPipelineCreationFeedback*    pPipelineStageCreationFeedbacks;
} VkPipelineCreationFeedbackCreateInfo;

or the equivalent

// Provided by VK_EXT_pipeline_creation_feedback
typedef VkPipelineCreationFeedbackCreateInfo VkPipelineCreationFeedbackCreateInfoEXT;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • pPipelineCreationFeedback is a pointer to a VkPipelineCreationFeedback structure.

  • pipelineStageCreationFeedbackCount is the number of elements in pPipelineStageCreationFeedbacks.

  • pPipelineStageCreationFeedbacks is a pointer to an array of pipelineStageCreationFeedbackCount VkPipelineCreationFeedback structures.

An implementation should write pipeline creation feedback to pPipelineCreationFeedback and may write pipeline stage creation feedback to pPipelineStageCreationFeedbacks. An implementation must set or clear the VK_PIPELINE_CREATION_FEEDBACK_VALID_BIT in VkPipelineCreationFeedback::flags for pPipelineCreationFeedback and every element of pPipelineStageCreationFeedbacks.

Note

One common scenario for an implementation to skip per-stage feedback is when VK_PIPELINE_CREATION_FEEDBACK_APPLICATION_PIPELINE_CACHE_HIT_BIT is set in pPipelineCreationFeedback.

When chained to VkRayTracingPipelineCreateInfoKHR, VkRayTracingPipelineCreateInfoNV, or VkGraphicsPipelineCreateInfo, the i element of pPipelineStageCreationFeedbacks corresponds to the i element of VkRayTracingPipelineCreateInfoKHR::pStages, VkRayTracingPipelineCreateInfoNV::pStages, or VkGraphicsPipelineCreateInfo::pStages. When chained to VkComputePipelineCreateInfo, the first element of pPipelineStageCreationFeedbacks corresponds to VkComputePipelineCreateInfo::stage.

Valid Usage (Implicit)

  • VUID-VkPipelineCreationFeedbackCreateInfo-sType-sType
    sType must be VK_STRUCTURE_TYPE_PIPELINE_CREATION_FEEDBACK_CREATE_INFO

  • VUID-VkPipelineCreationFeedbackCreateInfo-pPipelineCreationFeedback-parameter
    pPipelineCreationFeedback must be a valid pointer to a VkPipelineCreationFeedback structure

  • VUID-VkPipelineCreationFeedbackCreateInfo-pPipelineStageCreationFeedbacks-parameter
    If pipelineStageCreationFeedbackCount is not 0, pPipelineStageCreationFeedbacks must be a valid pointer to an array of pipelineStageCreationFeedbackCount VkPipelineCreationFeedback structures

The VkPipelineCreationFeedback structure is defined as:

// Provided by VK_VERSION_1_3
typedef struct VkPipelineCreationFeedback {
    VkPipelineCreationFeedbackFlags    flags;
    uint64_t                           duration;
} VkPipelineCreationFeedback;

or the equivalent

// Provided by VK_EXT_pipeline_creation_feedback
typedef VkPipelineCreationFeedback VkPipelineCreationFeedbackEXT;

  • flags is a bitmask of VkPipelineCreationFeedbackFlagBits providing feedback about the creation of a pipeline or of a pipeline stage.

  • duration is the duration spent creating a pipeline or pipeline stage in nanoseconds.

If the VK_PIPELINE_CREATION_FEEDBACK_VALID_BIT is not set in flags, an implementation must not set any other bits in flags, and the values of all other VkPipelineCreationFeedback data members are undefined.

Possible values of the flags member of VkPipelineCreationFeedback are:

// Provided by VK_VERSION_1_3
typedef enum VkPipelineCreationFeedbackFlagBits {
    VK_PIPELINE_CREATION_FEEDBACK_VALID_BIT = 0x00000001,
    VK_PIPELINE_CREATION_FEEDBACK_APPLICATION_PIPELINE_CACHE_HIT_BIT = 0x00000002,
    VK_PIPELINE_CREATION_FEEDBACK_BASE_PIPELINE_ACCELERATION_BIT = 0x00000004,
    VK_PIPELINE_CREATION_FEEDBACK_VALID_BIT_EXT = VK_PIPELINE_CREATION_FEEDBACK_VALID_BIT,
    VK_PIPELINE_CREATION_FEEDBACK_APPLICATION_PIPELINE_CACHE_HIT_BIT_EXT = VK_PIPELINE_CREATION_FEEDBACK_APPLICATION_PIPELINE_CACHE_HIT_BIT,
    VK_PIPELINE_CREATION_FEEDBACK_BASE_PIPELINE_ACCELERATION_BIT_EXT = VK_PIPELINE_CREATION_FEEDBACK_BASE_PIPELINE_ACCELERATION_BIT,
} VkPipelineCreationFeedbackFlagBits;

or the equivalent

// Provided by VK_EXT_pipeline_creation_feedback
typedef VkPipelineCreationFeedbackFlagBits VkPipelineCreationFeedbackFlagBitsEXT;

  • VK_PIPELINE_CREATION_FEEDBACK_VALID_BIT indicates that the feedback information is valid.

  • VK_PIPELINE_CREATION_FEEDBACK_APPLICATION_PIPELINE_CACHE_HIT_BIT indicates that a readily usable pipeline or pipeline stage was found in the pipelineCache specified by the application in the pipeline creation command.

    An implementation should set the VK_PIPELINE_CREATION_FEEDBACK_APPLICATION_PIPELINE_CACHE_HIT_BIT bit if it was able to avoid the large majority of pipeline or pipeline stage creation work by using the pipelineCache parameter of vkCreateGraphicsPipelines, vkCreateRayTracingPipelinesKHR, vkCreateRayTracingPipelinesNV, or vkCreateComputePipelines. When an implementation sets this bit for the entire pipeline, it may leave it unset for any stage.

    Note

    Implementations are encouraged to provide a meaningful signal to applications using this bit. The intention is to communicate to the application that the pipeline or pipeline stage was created “as fast as it gets” using the pipeline cache provided by the application. If an implementation uses an internal cache, it is discouraged from setting this bit as the feedback would be unactionable.

  • VK_PIPELINE_CREATION_FEEDBACK_BASE_PIPELINE_ACCELERATION_BIT indicates that the base pipeline specified by the basePipelineHandle or basePipelineIndex member of the Vk*PipelineCreateInfo structure was used to accelerate the creation of the pipeline.

    An implementation should set the VK_PIPELINE_CREATION_FEEDBACK_BASE_PIPELINE_ACCELERATION_BIT bit if it was able to avoid a significant amount of work by using the base pipeline.

    Note

    While “significant amount of work” is subjective, implementations are encouraged to provide a meaningful signal to applications using this bit. For example, a 1% reduction in duration may not warrant setting this bit, while a 50% reduction would.

    		 
// Provided by VK_VERSION_1_3
typedef VkFlags VkPipelineCreationFeedbackFlags;

or the equivalent

// Provided by VK_EXT_pipeline_creation_feedback
typedef VkPipelineCreationFeedbackFlags VkPipelineCreationFeedbackFlagsEXT;

VkPipelineCreationFeedbackFlags is a bitmask type for providing zero or more VkPipelineCreationFeedbackFlagBits.

11. Memory Allocation

Vulkan memory is broken up into two categories, host memory and device memory.

11.1. Host Memory

Host memory is memory needed by the Vulkan implementation for non-device-visible storage.

Note

This memory may be used to store the implementation’s representation and state of Vulkan objects.

Vulkan provides applications the opportunity to perform host memory allocations on behalf of the Vulkan implementation. If this feature is not used, the implementation will perform its own memory allocations. Since most memory allocations are off the critical path, this is not meant as a performance feature. Rather, this can be useful for certain embedded systems, for debugging purposes (e.g. putting a guard page after all host allocations), or for memory allocation logging.

Allocators are provided by the application as a pointer to a VkAllocationCallbacks structure:

// Provided by VK_VERSION_1_0
typedef struct VkAllocationCallbacks {
    void*                                   pUserData;
    PFN_vkAllocationFunction                pfnAllocation;
    PFN_vkReallocationFunction              pfnReallocation;
    PFN_vkFreeFunction                      pfnFree;
    PFN_vkInternalAllocationNotification    pfnInternalAllocation;
    PFN_vkInternalFreeNotification          pfnInternalFree;
} VkAllocationCallbacks;

  • pUserData is a value to be interpreted by the implementation of the callbacks. When any of the callbacks in VkAllocationCallbacks are called, the Vulkan implementation will pass this value as the first parameter to the callback. This value can vary each time an allocator is passed into a command, even when the same object takes an allocator in multiple commands.

  • pfnAllocation is a PFN_vkAllocationFunction pointer to an application-defined memory allocation function.

  • pfnReallocation is a PFN_vkReallocationFunction pointer to an application-defined memory reallocation function.

  • pfnFree is a PFN_vkFreeFunction pointer to an application-defined memory free function.

  • pfnInternalAllocation is a PFN_vkInternalAllocationNotification pointer to an application-defined function that is called by the implementation when the implementation makes internal allocations.

  • pfnInternalFree is a PFN_vkInternalFreeNotification pointer to an application-defined function that is called by the implementation when the implementation frees internal allocations.

Valid Usage

  • VUID-VkAllocationCallbacks-pfnAllocation-00632
    pfnAllocation must be a valid pointer to a valid application-defined PFN_vkAllocationFunction

  • VUID-VkAllocationCallbacks-pfnReallocation-00633
    pfnReallocation must be a valid pointer to a valid application-defined PFN_vkReallocationFunction

  • VUID-VkAllocationCallbacks-pfnFree-00634
    pfnFree must be a valid pointer to a valid application-defined PFN_vkFreeFunction

  • VUID-VkAllocationCallbacks-pfnInternalAllocation-00635
    If either of pfnInternalAllocation or pfnInternalFree is not NULL, both must be valid callbacks

The type of pfnAllocation is:

// Provided by VK_VERSION_1_0
typedef void* (VKAPI_PTR *PFN_vkAllocationFunction)(
    void*                                       pUserData,
    size_t                                      size,
    size_t                                      alignment,
    VkSystemAllocationScope                     allocationScope);

  • pUserData is the value specified for VkAllocationCallbacks::pUserData in the allocator specified by the application.

  • size is the size in bytes of the requested allocation.

  • alignment is the requested alignment of the allocation in bytes and must be a power of two.

  • allocationScope is a VkSystemAllocationScope value specifying the allocation scope of the lifetime of the allocation, as described here.

If pfnAllocation is unable to allocate the requested memory, it must return NULL. If the allocation was successful, it must return a valid pointer to memory allocation containing at least size bytes, and with the pointer value being a multiple of alignment.

Note

Correct Vulkan operation cannot be assumed if the application does not follow these rules.

For example, pfnAllocation (or pfnReallocation) could cause termination of running Vulkan instance(s) on a failed allocation for debugging purposes, either directly or indirectly. In these circumstances, it cannot be assumed that any part of any affected VkInstance objects are going to operate correctly (even vkDestroyInstance), and the application must ensure it cleans up properly via other means (e.g. process termination).

If pfnAllocation returns NULL, and if the implementation is unable to continue correct processing of the current command without the requested allocation, it must treat this as a runtime error, and generate VK_ERROR_OUT_OF_HOST_MEMORY at the appropriate time for the command in which the condition was detected, as described in Return Codes.

If the implementation is able to continue correct processing of the current command without the requested allocation, then it may do so, and must not generate VK_ERROR_OUT_OF_HOST_MEMORY as a result of this failed allocation.

The type of pfnReallocation is:

// Provided by VK_VERSION_1_0
typedef void* (VKAPI_PTR *PFN_vkReallocationFunction)(
    void*                                       pUserData,
    void*                                       pOriginal,
    size_t                                      size,
    size_t                                      alignment,
    VkSystemAllocationScope                     allocationScope);

  • pUserData is the value specified for VkAllocationCallbacks::pUserData in the allocator specified by the application.

  • pOriginal must be either NULL or a pointer previously returned by pfnReallocation or pfnAllocation of a compatible allocator.

  • size is the size in bytes of the requested allocation.

  • alignment is the requested alignment of the allocation in bytes and must be a power of two.

  • allocationScope is a VkSystemAllocationScope value specifying the allocation scope of the lifetime of the allocation, as described here.

If the reallocation was successful, pfnReallocation must return an allocation with enough space for size bytes, and the contents of the original allocation from bytes zero to min(original size, new size) - 1 must be preserved in the returned allocation. If size is larger than the old size, the contents of the additional space are undefined. If satisfying these requirements involves creating a new allocation, then the old allocation should be freed.

If pOriginal is NULL, then pfnReallocation must behave equivalently to a call to PFN_vkAllocationFunction with the same parameter values (without pOriginal).

If size is zero, then pfnReallocation must behave equivalently to a call to PFN_vkFreeFunction with the same pUserData parameter value, and pMemory equal to pOriginal.

If pOriginal is non-NULL, the implementation must ensure that alignment is equal to the alignment used to originally allocate pOriginal.

If this function fails and pOriginal is non-NULL the application must not free the old allocation.

pfnReallocation must follow the same rules for return values as PFN_vkAllocationFunction.

The type of pfnFree is:

// Provided by VK_VERSION_1_0
typedef void (VKAPI_PTR *PFN_vkFreeFunction)(
    void*                                       pUserData,
    void*                                       pMemory);

  • pUserData is the value specified for VkAllocationCallbacks::pUserData in the allocator specified by the application.

  • pMemory is the allocation to be freed.

pMemory may be NULL, which the callback must handle safely. If pMemory is non-NULL, it must be a pointer previously allocated by pfnAllocation or pfnReallocation. The application should free this memory.

The type of pfnInternalAllocation is:

// Provided by VK_VERSION_1_0
typedef void (VKAPI_PTR *PFN_vkInternalAllocationNotification)(
    void*                                       pUserData,
    size_t                                      size,
    VkInternalAllocationType                    allocationType,
    VkSystemAllocationScope                     allocationScope);

  • pUserData is the value specified for VkAllocationCallbacks::pUserData in the allocator specified by the application.

  • size is the requested size of an allocation.

  • allocationType is a VkInternalAllocationType value specifying the requested type of an allocation.

  • allocationScope is a VkSystemAllocationScope value specifying the allocation scope of the lifetime of the allocation, as described here.

This is a purely informational callback.

The type of pfnInternalFree is:

// Provided by VK_VERSION_1_0
typedef void (VKAPI_PTR *PFN_vkInternalFreeNotification)(
    void*                                       pUserData,
    size_t                                      size,
    VkInternalAllocationType                    allocationType,
    VkSystemAllocationScope                     allocationScope);

  • pUserData is the value specified for VkAllocationCallbacks::pUserData in the allocator specified by the application.

  • size is the requested size of an allocation.

  • allocationType is a VkInternalAllocationType value specifying the requested type of an allocation.

  • allocationScope is a VkSystemAllocationScope value specifying the allocation scope of the lifetime of the allocation, as described here.

Each allocation has an allocation scope defining its lifetime and which object it is associated with. Possible values passed to the allocationScope parameter of the callback functions specified by VkAllocationCallbacks, indicating the allocation scope, are:

// Provided by VK_VERSION_1_0
typedef enum VkSystemAllocationScope {
    VK_SYSTEM_ALLOCATION_SCOPE_COMMAND = 0,
    VK_SYSTEM_ALLOCATION_SCOPE_OBJECT = 1,
    VK_SYSTEM_ALLOCATION_SCOPE_CACHE = 2,
    VK_SYSTEM_ALLOCATION_SCOPE_DEVICE = 3,
    VK_SYSTEM_ALLOCATION_SCOPE_INSTANCE = 4,
} VkSystemAllocationScope;

  • VK_SYSTEM_ALLOCATION_SCOPE_COMMAND specifies that the allocation is scoped to the duration of the Vulkan command.

  • VK_SYSTEM_ALLOCATION_SCOPE_OBJECT specifies that the allocation is scoped to the lifetime of the Vulkan object that is being created or used.

  • VK_SYSTEM_ALLOCATION_SCOPE_CACHE specifies that the allocation is scoped to the lifetime of a VkPipelineCache or VkValidationCacheEXT object.

  • VK_SYSTEM_ALLOCATION_SCOPE_DEVICE specifies that the allocation is scoped to the lifetime of the Vulkan device.

  • VK_SYSTEM_ALLOCATION_SCOPE_INSTANCE specifies that the allocation is scoped to the lifetime of the Vulkan instance.

Most Vulkan commands operate on a single object, or there is a sole object that is being created or manipulated. When an allocation uses an allocation scope of VK_SYSTEM_ALLOCATION_SCOPE_OBJECT or VK_SYSTEM_ALLOCATION_SCOPE_CACHE, the allocation is scoped to the object being created or manipulated.

When an implementation requires host memory, it will make callbacks to the application using the most specific allocator and allocation scope available:

  • If an allocation is scoped to the duration of a command, the allocator will use the VK_SYSTEM_ALLOCATION_SCOPE_COMMAND allocation scope. The most specific allocator available is used: if the object being created or manipulated has an allocator, that object’s allocator will be used, else if the parent VkDevice has an allocator it will be used, else if the parent VkInstance has an allocator it will be used. Else,

  • If an allocation is associated with a VkValidationCacheEXT or VkPipelineCache object, the allocator will use the VK_SYSTEM_ALLOCATION_SCOPE_CACHE allocation scope. The most specific allocator available is used (cache, else device, else instance). Else,

  • If an allocation is scoped to the lifetime of an object, that object is being created or manipulated by the command, and that object’s type is not VkDevice or VkInstance, the allocator will use an allocation scope of VK_SYSTEM_ALLOCATION_SCOPE_OBJECT. The most specific allocator available is used (object, else device, else instance). Else,

  • If an allocation is scoped to the lifetime of a device, the allocator will use an allocation scope of VK_SYSTEM_ALLOCATION_SCOPE_DEVICE. The most specific allocator available is used (device, else instance). Else,

  • If the allocation is scoped to the lifetime of an instance and the instance has an allocator, its allocator will be used with an allocation scope of VK_SYSTEM_ALLOCATION_SCOPE_INSTANCE.

  • Otherwise an implementation will allocate memory through an alternative mechanism that is unspecified.

Objects that are allocated from pools do not specify their own allocator. When an implementation requires host memory for such an object, that memory is sourced from the object’s parent pool’s allocator.

The application is not expected to handle allocating memory that is intended for execution by the host due to the complexities of differing security implementations across multiple platforms. The implementation will allocate such memory internally and invoke an application provided informational callback when these internal allocations are allocated and freed. Upon allocation of executable memory, pfnInternalAllocation will be called. Upon freeing executable memory, pfnInternalFree will be called. An implementation will only call an informational callback for executable memory allocations and frees.

The allocationType parameter to the pfnInternalAllocation and pfnInternalFree functions may be one of the following values:

// Provided by VK_VERSION_1_0
typedef enum VkInternalAllocationType {
    VK_INTERNAL_ALLOCATION_TYPE_EXECUTABLE = 0,
} VkInternalAllocationType;

  • VK_INTERNAL_ALLOCATION_TYPE_EXECUTABLE specifies that the allocation is intended for execution by the host.

An implementation must only make calls into an application-provided allocator during the execution of an API command. An implementation must only make calls into an application-provided allocator from the same thread that called the provoking API command. The implementation should not synchronize calls to any of the callbacks. If synchronization is needed, the callbacks must provide it themselves. The informational callbacks are subject to the same restrictions as the allocation callbacks.

If an implementation intends to make calls through a VkAllocationCallbacks structure between the time a vkCreate* command returns and the time a corresponding vkDestroy* command begins, that implementation must save a copy of the allocator before the vkCreate* command returns. The callback functions and any data structures they rely upon must remain valid for the lifetime of the object they are associated with.

If an allocator is provided to a vkCreate* command, a compatible allocator must be provided to the corresponding vkDestroy* command. Two VkAllocationCallbacks structures are compatible if memory allocated with pfnAllocation or pfnReallocation in each can be freed with pfnReallocation or pfnFree in the other. An allocator must not be provided to a vkDestroy* command if an allocator was not provided to the corresponding vkCreate* command.

If a non-NULL allocator is used, the pfnAllocation, pfnReallocation and pfnFree members must be non-NULL and point to valid implementations of the callbacks. An application can choose to not provide informational callbacks by setting both pfnInternalAllocation and pfnInternalFree to NULL. pfnInternalAllocation and pfnInternalFree must either both be NULL or both be non-NULL.

If pfnAllocation or pfnReallocation fail, the implementation may fail object creation and/or generate a VK_ERROR_OUT_OF_HOST_MEMORY error, as appropriate.

Allocation callbacks must not call any Vulkan commands.

The following sets of rules define when an implementation is permitted to call the allocator callbacks.

pfnAllocation or pfnReallocation may be called in the following situations:

  • Allocations scoped to a VkDevice or VkInstance may be allocated from any API command.

  • Allocations scoped to a command may be allocated from any API command.

  • Allocations scoped to a VkPipelineCache may only be allocated from:

    • vkCreatePipelineCache

    • vkMergePipelineCaches for dstCache

    • vkCreateGraphicsPipelines for pipelineCache

    • vkCreateComputePipelines for pipelineCache

  • Allocations scoped to a VkValidationCacheEXT may only be allocated from:

  • Allocations scoped to a VkDescriptorPool may only be allocated from:

    • any command that takes the pool as a direct argument

    • vkAllocateDescriptorSets for the descriptorPool member of its pAllocateInfo parameter

    • vkCreateDescriptorPool

  • Allocations scoped to a VkCommandPool may only be allocated from:

    • any command that takes the pool as a direct argument

    • vkCreateCommandPool

    • vkAllocateCommandBuffers for the commandPool member of its pAllocateInfo parameter

    • any vkCmd* command whose commandBuffer was allocated from that VkCommandPool

  • Allocations scoped to any other object may only be allocated in that object’s vkCreate* command.

pfnFree, or pfnReallocation with zero size, may be called in the following situations:

  • Allocations scoped to a VkDevice or VkInstance may be freed from any API command.

  • Allocations scoped to a command must be freed by any API command which allocates such memory.

  • Allocations scoped to a VkPipelineCache may be freed from vkDestroyPipelineCache.

  • Allocations scoped to a VkValidationCacheEXT may be freed from vkDestroyValidationCacheEXT.

  • Allocations scoped to a VkDescriptorPool may be freed from

    • any command that takes the pool as a direct argument

  • Allocations scoped to a VkCommandPool may be freed from:

    • any command that takes the pool as a direct argument

    • vkResetCommandBuffer whose commandBuffer was allocated from that VkCommandPool

  • Allocations scoped to any other object may be freed in that object’s vkDestroy* command.

  • Any command that allocates host memory may also free host memory of the same scope.

11.2. Device Memory

Device memory is memory that is visible to the device — for example the contents of the image or buffer objects, which can be natively used by the device.

11.2.1. Device Memory Properties

Memory properties of a physical device describe the memory heaps and memory types available.

To query memory properties, call:

// Provided by VK_VERSION_1_0
void vkGetPhysicalDeviceMemoryProperties(
    VkPhysicalDevice                            physicalDevice,
    VkPhysicalDeviceMemoryProperties*           pMemoryProperties);

  • physicalDevice is the handle to the device to query.

  • pMemoryProperties is a pointer to a VkPhysicalDeviceMemoryProperties structure in which the properties are returned.

Valid Usage (Implicit)

  • VUID-vkGetPhysicalDeviceMemoryProperties-physicalDevice-parameter
    physicalDevice must be a valid VkPhysicalDevice handle

  • VUID-vkGetPhysicalDeviceMemoryProperties-pMemoryProperties-parameter
    pMemoryProperties must be a valid pointer to a VkPhysicalDeviceMemoryProperties structure

The VkPhysicalDeviceMemoryProperties structure is defined as:

// Provided by VK_VERSION_1_0
typedef struct VkPhysicalDeviceMemoryProperties {
    uint32_t        memoryTypeCount;
    VkMemoryType    memoryTypes[VK_MAX_MEMORY_TYPES];
    uint32_t        memoryHeapCount;
    VkMemoryHeap    memoryHeaps[VK_MAX_MEMORY_HEAPS];
} VkPhysicalDeviceMemoryProperties;

  • memoryTypeCount is the number of valid elements in the memoryTypes array.

  • memoryTypes is an array of VK_MAX_MEMORY_TYPES VkMemoryType structures describing the memory types that can be used to access memory allocated from the heaps specified by memoryHeaps.

  • memoryHeapCount is the number of valid elements in the memoryHeaps array.

  • memoryHeaps is an array of VK_MAX_MEMORY_HEAPS VkMemoryHeap structures describing the memory heaps from which memory can be allocated.

The VkPhysicalDeviceMemoryProperties structure describes a number of memory heaps as well as a number of memory types that can be used to access memory allocated in those heaps. Each heap describes a memory resource of a particular size, and each memory type describes a set of memory properties (e.g. host cached vs. uncached) that can be used with a given memory heap. Allocations using a particular memory type will consume resources from the heap indicated by that memory type’s heap index. More than one memory type may share each heap, and the heaps and memory types provide a mechanism to advertise an accurate size of the physical memory resources while allowing the memory to be used with a variety of different properties.

The number of memory heaps is given by memoryHeapCount and is less than or equal to VK_MAX_MEMORY_HEAPS. Each heap is described by an element of the memoryHeaps array as a VkMemoryHeap structure. The number of memory types available across all memory heaps is given by memoryTypeCount and is less than or equal to VK_MAX_MEMORY_TYPES. Each memory type is described by an element of the memoryTypes array as a VkMemoryType structure.

At least one heap must include VK_MEMORY_HEAP_DEVICE_LOCAL_BIT in VkMemoryHeap::flags. If there are multiple heaps that all have similar performance characteristics, they may all include VK_MEMORY_HEAP_DEVICE_LOCAL_BIT. In a unified memory architecture (UMA) system there is often only a single memory heap which is considered to be equally “local” to the host and to the device, and such an implementation must advertise the heap as device-local.

Each memory type returned by vkGetPhysicalDeviceMemoryProperties must have its propertyFlags set to one of the following values:

  • 0

  • VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT |
    VK_MEMORY_PROPERTY_HOST_COHERENT_BIT

  • VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT |
    VK_MEMORY_PROPERTY_HOST_CACHED_BIT

  • VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT |
    VK_MEMORY_PROPERTY_HOST_CACHED_BIT |
    VK_MEMORY_PROPERTY_HOST_COHERENT_BIT

  • VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT

  • VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT |
    VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT |
    VK_MEMORY_PROPERTY_HOST_COHERENT_BIT

  • VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT |
    VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT |
    VK_MEMORY_PROPERTY_HOST_CACHED_BIT

  • VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT |
    VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT |
    VK_MEMORY_PROPERTY_HOST_CACHED_BIT |
    VK_MEMORY_PROPERTY_HOST_COHERENT_BIT

  • VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT |
    VK_MEMORY_PROPERTY_LAZILY_ALLOCATED_BIT

  • VK_MEMORY_PROPERTY_PROTECTED_BIT

  • VK_MEMORY_PROPERTY_PROTECTED_BIT | VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT

  • VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT |
    VK_MEMORY_PROPERTY_HOST_COHERENT_BIT |
    VK_MEMORY_PROPERTY_DEVICE_COHERENT_BIT_AMD

  • VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT |
    VK_MEMORY_PROPERTY_HOST_CACHED_BIT |
    VK_MEMORY_PROPERTY_HOST_COHERENT_BIT |
    VK_MEMORY_PROPERTY_DEVICE_COHERENT_BIT_AMD

  • VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT |
    VK_MEMORY_PROPERTY_DEVICE_COHERENT_BIT_AMD

  • VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT |
    VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT |
    VK_MEMORY_PROPERTY_HOST_COHERENT_BIT |
    VK_MEMORY_PROPERTY_DEVICE_COHERENT_BIT_AMD

  • VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT |
    VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT |
    VK_MEMORY_PROPERTY_HOST_CACHED_BIT |
    VK_MEMORY_PROPERTY_HOST_COHERENT_BIT |
    VK_MEMORY_PROPERTY_DEVICE_COHERENT_BIT_AMD

  • VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT |
    VK_MEMORY_PROPERTY_HOST_COHERENT_BIT |
    VK_MEMORY_PROPERTY_DEVICE_COHERENT_BIT_AMD |
    VK_MEMORY_PROPERTY_DEVICE_UNCACHED_BIT_AMD

  • VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT |
    VK_MEMORY_PROPERTY_HOST_CACHED_BIT |
    VK_MEMORY_PROPERTY_HOST_COHERENT_BIT |
    VK_MEMORY_PROPERTY_DEVICE_COHERENT_BIT_AMD |
    VK_MEMORY_PROPERTY_DEVICE_UNCACHED_BIT_AMD

  • VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT |
    VK_MEMORY_PROPERTY_DEVICE_COHERENT_BIT_AMD |
    VK_MEMORY_PROPERTY_DEVICE_UNCACHED_BIT_AMD

  • VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT |
    VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT |
    VK_MEMORY_PROPERTY_HOST_COHERENT_BIT |
    VK_MEMORY_PROPERTY_DEVICE_COHERENT_BIT_AMD |
    VK_MEMORY_PROPERTY_DEVICE_UNCACHED_BIT_AMD

  • VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT |
    VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT |
    VK_MEMORY_PROPERTY_HOST_CACHED_BIT |
    VK_MEMORY_PROPERTY_HOST_COHERENT_BIT |
    VK_MEMORY_PROPERTY_DEVICE_COHERENT_BIT_AMD |
    VK_MEMORY_PROPERTY_DEVICE_UNCACHED_BIT_AMD

  • VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT |
    VK_MEMORY_PROPERTY_RDMA_CAPABLE_BIT_NV

There must be at least one memory type with both the VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT and VK_MEMORY_PROPERTY_HOST_COHERENT_BIT bits set in its propertyFlags. There must be at least one memory type with the VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT bit set in its propertyFlags. If the deviceCoherentMemory feature is enabled, there must be at least one memory type with the VK_MEMORY_PROPERTY_DEVICE_COHERENT_BIT_AMD bit set in its propertyFlags.

For each pair of elements X and Y returned in memoryTypes, X must be placed at a lower index position than Y if:

  • the set of bit flags returned in the propertyFlags member of X is a strict subset of the set of bit flags returned in the propertyFlags member of Y; or

  • the propertyFlags members of X and Y are equal, and X belongs to a memory heap with greater performance (as determined in an implementation-specific manner) ; or

  • the propertyFlags members of Y includes VK_MEMORY_PROPERTY_DEVICE_COHERENT_BIT_AMD or VK_MEMORY_PROPERTY_DEVICE_UNCACHED_BIT_AMD and X does not

Note

There is no ordering requirement between X and Y elements for the case their propertyFlags members are not in a subset relation. That potentially allows more than one possible way to order the same set of memory types. Notice that the list of all allowed memory property flag combinations is written in a valid order. But if instead VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT was before VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT | VK_MEMORY_PROPERTY_HOST_COHERENT_BIT, the list would still be in a valid order.

There may be a performance penalty for using device coherent or uncached device memory types, and using these accidentally is undesirable. In order to avoid this, memory types with these properties always appear at the end of the list; but are subject to the same rules otherwise.

This ordering requirement enables applications to use a simple search loop to select the desired memory type along the lines of:

// Find a memory in `memoryTypeBitsRequirement` that includes all of `requiredProperties`
int32_t findProperties(const VkPhysicalDeviceMemoryProperties* pMemoryProperties,
                       uint32_t memoryTypeBitsRequirement,
                       VkMemoryPropertyFlags requiredProperties) {
    const uint32_t memoryCount = pMemoryProperties->memoryTypeCount;
    for (uint32_t memoryIndex = 0; memoryIndex < memoryCount; ++memoryIndex) {
        const uint32_t memoryTypeBits = (1 << memoryIndex);
        const bool isRequiredMemoryType = memoryTypeBitsRequirement & memoryTypeBits;

        const VkMemoryPropertyFlags properties =
            pMemoryProperties->memoryTypes[memoryIndex].propertyFlags;
        const bool hasRequiredProperties =
            (properties & requiredProperties) == requiredProperties;

        if (isRequiredMemoryType && hasRequiredProperties)
            return static_cast<int32_t>(memoryIndex);
    }

    // failed to find memory type
    return -1;
}

// Try to find an optimal memory type, or if it does not exist try fallback memory type
// `device` is the VkDevice
// `image` is the VkImage that requires memory to be bound
// `memoryProperties` properties as returned by vkGetPhysicalDeviceMemoryProperties
// `requiredProperties` are the property flags that must be present
// `optimalProperties` are the property flags that are preferred by the application
VkMemoryRequirements memoryRequirements;
vkGetImageMemoryRequirements(device, image, &memoryRequirements);
int32_t memoryType =
    findProperties(&memoryProperties, memoryRequirements.memoryTypeBits, optimalProperties);
if (memoryType == -1) // not found; try fallback properties
    memoryType =
        findProperties(&memoryProperties, memoryRequirements.memoryTypeBits, requiredProperties);

VK_MAX_MEMORY_TYPES is the length of an array of VkMemoryType structures describing memory types, as returned in VkPhysicalDeviceMemoryProperties::memoryTypes.

#define VK_MAX_MEMORY_TYPES               32U

VK_MAX_MEMORY_HEAPS is the length of an array of VkMemoryHeap structures describing memory heaps, as returned in VkPhysicalDeviceMemoryProperties::memoryHeaps.

#define VK_MAX_MEMORY_HEAPS               16U

To query memory properties, call:

// Provided by VK_VERSION_1_1
void vkGetPhysicalDeviceMemoryProperties2(
    VkPhysicalDevice                            physicalDevice,
    VkPhysicalDeviceMemoryProperties2*          pMemoryProperties);

or the equivalent command

// Provided by VK_KHR_get_physical_device_properties2
void vkGetPhysicalDeviceMemoryProperties2KHR(
    VkPhysicalDevice                            physicalDevice,
    VkPhysicalDeviceMemoryProperties2*          pMemoryProperties);

  • physicalDevice is the handle to the device to query.

  • pMemoryProperties is a pointer to a VkPhysicalDeviceMemoryProperties2 structure in which the properties are returned.

vkGetPhysicalDeviceMemoryProperties2 behaves similarly to vkGetPhysicalDeviceMemoryProperties, with the ability to return extended information in a pNext chain of output structures.

Valid Usage (Implicit)

  • VUID-vkGetPhysicalDeviceMemoryProperties2-physicalDevice-parameter
    physicalDevice must be a valid VkPhysicalDevice handle

  • VUID-vkGetPhysicalDeviceMemoryProperties2-pMemoryProperties-parameter
    pMemoryProperties must be a valid pointer to a VkPhysicalDeviceMemoryProperties2 structure

The VkPhysicalDeviceMemoryProperties2 structure is defined as:

// Provided by VK_VERSION_1_1
typedef struct VkPhysicalDeviceMemoryProperties2 {
    VkStructureType                     sType;
    void*                               pNext;
    VkPhysicalDeviceMemoryProperties    memoryProperties;
} VkPhysicalDeviceMemoryProperties2;

or the equivalent

// Provided by VK_KHR_get_physical_device_properties2
typedef VkPhysicalDeviceMemoryProperties2 VkPhysicalDeviceMemoryProperties2KHR;
Valid Usage (Implicit)

  • VUID-VkPhysicalDeviceMemoryProperties2-sType-sType
    sType must be VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MEMORY_PROPERTIES_2

  • VUID-VkPhysicalDeviceMemoryProperties2-pNext-pNext
    pNext must be NULL or a pointer to a valid instance of VkPhysicalDeviceMemoryBudgetPropertiesEXT

  • VUID-VkPhysicalDeviceMemoryProperties2-sType-unique
    The sType value of each struct in the pNext chain must be unique

The VkMemoryHeap structure is defined as:

// Provided by VK_VERSION_1_0
typedef struct VkMemoryHeap {
    VkDeviceSize         size;
    VkMemoryHeapFlags    flags;
} VkMemoryHeap;

  • size is the total memory size in bytes in the heap.

  • flags is a bitmask of VkMemoryHeapFlagBits specifying attribute flags for the heap.

Bits which may be set in VkMemoryHeap::flags, indicating attribute flags for the heap, are:

// Provided by VK_VERSION_1_0
typedef enum VkMemoryHeapFlagBits {
    VK_MEMORY_HEAP_DEVICE_LOCAL_BIT = 0x00000001,
  // Provided by VK_VERSION_1_1
    VK_MEMORY_HEAP_MULTI_INSTANCE_BIT = 0x00000002,
  // Provided by VK_KHR_device_group_creation
    VK_MEMORY_HEAP_MULTI_INSTANCE_BIT_KHR = VK_MEMORY_HEAP_MULTI_INSTANCE_BIT,
} VkMemoryHeapFlagBits;

  • VK_MEMORY_HEAP_DEVICE_LOCAL_BIT specifies that the heap corresponds to device-local memory. Device-local memory may have different performance characteristics than host-local memory, and may support different memory property flags.

  • VK_MEMORY_HEAP_MULTI_INSTANCE_BIT specifies that in a logical device representing more than one physical device, there is a per-physical device instance of the heap memory. By default, an allocation from such a heap will be replicated to each physical device’s instance of the heap.

// Provided by VK_VERSION_1_0
typedef VkFlags VkMemoryHeapFlags;

VkMemoryHeapFlags is a bitmask type for setting a mask of zero or more VkMemoryHeapFlagBits.

The VkMemoryType structure is defined as:

// Provided by VK_VERSION_1_0
typedef struct VkMemoryType {
    VkMemoryPropertyFlags    propertyFlags;
    uint32_t                 heapIndex;
} VkMemoryType;

Bits which may be set in VkMemoryType::propertyFlags, indicating properties of a memory type, are:

// Provided by VK_VERSION_1_0
typedef enum VkMemoryPropertyFlagBits {
    VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT = 0x00000001,
    VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT = 0x00000002,
    VK_MEMORY_PROPERTY_HOST_COHERENT_BIT = 0x00000004,
    VK_MEMORY_PROPERTY_HOST_CACHED_BIT = 0x00000008,
    VK_MEMORY_PROPERTY_LAZILY_ALLOCATED_BIT = 0x00000010,
  // Provided by VK_VERSION_1_1
    VK_MEMORY_PROPERTY_PROTECTED_BIT = 0x00000020,
  // Provided by VK_AMD_device_coherent_memory
    VK_MEMORY_PROPERTY_DEVICE_COHERENT_BIT_AMD = 0x00000040,
  // Provided by VK_AMD_device_coherent_memory
    VK_MEMORY_PROPERTY_DEVICE_UNCACHED_BIT_AMD = 0x00000080,
  // Provided by VK_NV_external_memory_rdma
    VK_MEMORY_PROPERTY_RDMA_CAPABLE_BIT_NV = 0x00000100,
} VkMemoryPropertyFlagBits;

  • VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT bit specifies that memory allocated with this type is the most efficient for device access. This property will be set if and only if the memory type belongs to a heap with the VK_MEMORY_HEAP_DEVICE_LOCAL_BIT set.

  • VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT bit specifies that memory allocated with this type can be mapped for host access using vkMapMemory.

  • VK_MEMORY_PROPERTY_HOST_COHERENT_BIT bit specifies that the host cache management commands vkFlushMappedMemoryRanges and vkInvalidateMappedMemoryRanges are not needed to flush host writes to the device or make device writes visible to the host, respectively.

  • VK_MEMORY_PROPERTY_HOST_CACHED_BIT bit specifies that memory allocated with this type is cached on the host. Host memory accesses to uncached memory are slower than to cached memory, however uncached memory is always host coherent.

  • VK_MEMORY_PROPERTY_LAZILY_ALLOCATED_BIT bit specifies that the memory type only allows device access to the memory. Memory types must not have both VK_MEMORY_PROPERTY_LAZILY_ALLOCATED_BIT and VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT set. Additionally, the object’s backing memory may be provided by the implementation lazily as specified in Lazily Allocated Memory.

  • VK_MEMORY_PROPERTY_PROTECTED_BIT bit specifies that the memory type only allows device access to the memory, and allows protected queue operations to access the memory. Memory types must not have VK_MEMORY_PROPERTY_PROTECTED_BIT set and any of VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT set, or VK_MEMORY_PROPERTY_HOST_COHERENT_BIT set, or VK_MEMORY_PROPERTY_HOST_CACHED_BIT set.

  • VK_MEMORY_PROPERTY_DEVICE_COHERENT_BIT_AMD bit specifies that device accesses to allocations of this memory type are automatically made available and visible.

  • VK_MEMORY_PROPERTY_DEVICE_UNCACHED_BIT_AMD bit specifies that memory allocated with this type is not cached on the device. Uncached device memory is always device coherent.

  • VK_MEMORY_PROPERTY_RDMA_CAPABLE_BIT_NV bit specifies that external devices can access this memory directly.

For any memory allocated with both the VK_MEMORY_PROPERTY_HOST_COHERENT_BIT and the VK_MEMORY_PROPERTY_DEVICE_COHERENT_BIT_AMD, host or device accesses also perform automatic memory domain transfer operations, such that writes are always automatically available and visible to both host and device memory domains.

Note

Device coherence is a useful property for certain debugging use cases (e.g. crash analysis, where performing separate coherence actions could mean values are not reported correctly). However, device coherent accesses may be slower than equivalent accesses without device coherence, particularly if they are also device uncached. For device uncached memory in particular, repeated accesses to the same or neighboring memory locations over a short time period (e.g. within a frame) may be slower than it would be for the equivalent cached memory type. As such, it is generally inadvisable to use device coherent or device uncached memory except when really needed.

 
// Provided by VK_VERSION_1_0
typedef VkFlags VkMemoryPropertyFlags;

VkMemoryPropertyFlags is a bitmask type for setting a mask of zero or more VkMemoryPropertyFlagBits.

If the VkPhysicalDeviceMemoryBudgetPropertiesEXT structure is included in the pNext chain of VkPhysicalDeviceMemoryProperties2, it is filled with the current memory budgets and usages.

The VkPhysicalDeviceMemoryBudgetPropertiesEXT structure is defined as:

// Provided by VK_EXT_memory_budget
typedef struct VkPhysicalDeviceMemoryBudgetPropertiesEXT {
    VkStructureType    sType;
    void*              pNext;
    VkDeviceSize       heapBudget[VK_MAX_MEMORY_HEAPS];
    VkDeviceSize       heapUsage[VK_MAX_MEMORY_HEAPS];
} VkPhysicalDeviceMemoryBudgetPropertiesEXT;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • heapBudget is an array of VK_MAX_MEMORY_HEAPS VkDeviceSize values in which memory budgets are returned, with one element for each memory heap. A heap’s budget is a rough estimate of how much memory the process can allocate from that heap before allocations may fail or cause performance degradation. The budget includes any currently allocated device memory.

  • heapUsage is an array of VK_MAX_MEMORY_HEAPS VkDeviceSize values in which memory usages are returned, with one element for each memory heap. A heap’s usage is an estimate of how much memory the process is currently using in that heap.

The values returned in this structure are not invariant. The heapBudget and heapUsage values must be zero for array elements greater than or equal to VkPhysicalDeviceMemoryProperties::memoryHeapCount. The heapBudget value must be non-zero for array elements less than VkPhysicalDeviceMemoryProperties::memoryHeapCount. The heapBudget value must be less than or equal to VkMemoryHeap::size for each heap.

Valid Usage (Implicit)

  • VUID-VkPhysicalDeviceMemoryBudgetPropertiesEXT-sType-sType
    sType must be VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MEMORY_BUDGET_PROPERTIES_EXT

11.2.2. Device Memory Objects

A Vulkan device operates on data in device memory via memory objects that are represented in the API by a VkDeviceMemory handle:

// Provided by VK_VERSION_1_0
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkDeviceMemory)

11.2.3. Device Memory Allocation

To allocate memory objects, call:

// Provided by VK_VERSION_1_0
VkResult vkAllocateMemory(
    VkDevice                                    device,
    const VkMemoryAllocateInfo*                 pAllocateInfo,
    const VkAllocationCallbacks*                pAllocator,
    VkDeviceMemory*                             pMemory);

  • device is the logical device that owns the memory.

  • pAllocateInfo is a pointer to a VkMemoryAllocateInfo structure describing parameters of the allocation. A successfully returned allocation must use the requested parameters — no substitution is permitted by the implementation.

  • pAllocator controls host memory allocation as described in the Memory Allocation chapter.

  • pMemory is a pointer to a VkDeviceMemory handle in which information about the allocated memory is returned.

Allocations returned by vkAllocateMemory are guaranteed to meet any alignment requirement of the implementation. For example, if an implementation requires 128 byte alignment for images and 64 byte alignment for buffers, the device memory returned through this mechanism would be 128-byte aligned. This ensures that applications can correctly suballocate objects of different types (with potentially different alignment requirements) in the same memory object.

When memory is allocated, its contents are undefined with the following constraint:

  • The contents of unprotected memory must not be a function of the contents of data protected memory objects, even if those memory objects were previously freed.

Note

The contents of memory allocated by one application should not be a function of data from protected memory objects of another application, even if those memory objects were previously freed.

The maximum number of valid memory allocations that can exist simultaneously within a VkDevice may be restricted by implementation- or platform-dependent limits. The maxMemoryAllocationCount feature describes the number of allocations that can exist simultaneously before encountering these internal limits.

Note

For historical reasons, if maxMemoryAllocationCount is exceeded, some implementations may return VK_ERROR_TOO_MANY_OBJECTS. Exceeding this limit will result in undefined behavior, and an application should not rely on the use of the returned error code in order to identify when the limit is reached.
Note

Many protected memory implementations involve complex hardware and system software support, and often have additional and much lower limits on the number of simultaneous protected memory allocations (from memory types with the VK_MEMORY_PROPERTY_PROTECTED_BIT property) than for non-protected memory allocations. These limits can be system-wide, and depend on a variety of factors outside of the Vulkan implementation, so they cannot be queried in Vulkan. Applications should use as few allocations as possible from such memory types by suballocating aggressively, and be prepared for allocation failure even when there is apparently plenty of capacity remaining in the memory heap. As a guideline, the Vulkan conformance test suite requires that at least 80 minimum-size allocations can exist concurrently when no other uses of protected memory are active in the system.

Some platforms may have a limit on the maximum size of a single allocation. For example, certain systems may fail to create allocations with a size greater than or equal to 4GB. Such a limit is implementation-dependent, and if such a failure occurs then the error VK_ERROR_OUT_OF_DEVICE_MEMORY must be returned. This limit is advertised in VkPhysicalDeviceMaintenance3Properties::maxMemoryAllocationSize.

The cumulative memory size allocated to a heap can be limited by the size of the specified heap. In such cases, allocated memory is tracked on a per-device and per-heap basis. Some platforms allow overallocation into other heaps. The overallocation behavior can be specified through the VK_AMD_memory_overallocation_behavior extension.

If the VkPhysicalDevicePageableDeviceLocalMemoryFeaturesEXT::pageableDeviceLocalMemory feature is enabled, memory allocations made from a heap that includes VK_MEMORY_HEAP_DEVICE_LOCAL_BIT in VkMemoryHeap::flags may be transparently moved to host-local memory allowing multiple applications to share device-local memory. If there is no space left in device-local memory when this new allocation is made, other allocations may be moved out transparently to make room. The operating system will determine which allocations to move to device-local memory or host-local memory based on platform-specific criteria. To help the operating system make good choices, the application should set the appropriate memory priority with VkMemoryPriorityAllocateInfoEXT and adjust it as necessary with vkSetDeviceMemoryPriorityEXT. Higher priority allocations will moved to device-local memory first.

Memory allocations made on heaps without the VK_MEMORY_HEAP_DEVICE_LOCAL_BIT property will not be transparently promoted to device-local memory by the operating system.

Valid Usage
Valid Usage (Implicit)

  • VUID-vkAllocateMemory-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkAllocateMemory-pAllocateInfo-parameter
    pAllocateInfo must be a valid pointer to a valid VkMemoryAllocateInfo structure

  • VUID-vkAllocateMemory-pAllocator-parameter
    If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure

  • VUID-vkAllocateMemory-pMemory-parameter
    pMemory must be a valid pointer to a VkDeviceMemory handle

Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

  • VK_ERROR_INVALID_EXTERNAL_HANDLE

  • VK_ERROR_INVALID_OPAQUE_CAPTURE_ADDRESS_KHR

The VkMemoryAllocateInfo structure is defined as:

// Provided by VK_VERSION_1_0
typedef struct VkMemoryAllocateInfo {
    VkStructureType    sType;
    const void*        pNext;
    VkDeviceSize       allocationSize;
    uint32_t           memoryTypeIndex;
} VkMemoryAllocateInfo;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • allocationSize is the size of the allocation in bytes.

  • memoryTypeIndex is an index identifying a memory type from the memoryTypes array of the VkPhysicalDeviceMemoryProperties structure.

The internal data of an allocated device memory object must include a reference to implementation-specific resources, referred to as the memory object’s payload. Applications can also import and export that internal data to and from device memory objects to share data between Vulkan instances and other compatible APIs. A VkMemoryAllocateInfo structure defines a memory import operation if its pNext chain includes one of the following structures:

If the parameters define an import operation and the external handle type is VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_BIT, VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_KMT_BIT, or VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_RESOURCE_BIT, allocationSize is ignored. The implementation must query the size of these allocations from the OS.

Whether device memory objects constructed via a memory import operation hold a reference to their payload depends on the properties of the handle type used to perform the import, as defined below for each valid handle type. Importing memory must not modify the content of the memory. Implementations must ensure that importing memory does not enable the importing Vulkan instance to access any memory or resources in other Vulkan instances other than that corresponding to the memory object imported. Implementations must also ensure accessing imported memory which has not been initialized does not allow the importing Vulkan instance to obtain data from the exporting Vulkan instance or vice-versa.

Note

How exported and imported memory is isolated is left to the implementation, but applications should be aware that such isolation may prevent implementations from placing multiple exportable memory objects in the same physical or virtual page. Hence, applications should avoid creating many small external memory objects whenever possible.

Importing memory must not increase overall heap usage within a system. However, it must affect the following per-process values:

When performing a memory import operation, it is the responsibility of the application to ensure the external handles and their associated payloads meet all valid usage requirements. However, implementations must perform sufficient validation of external handles and payloads to ensure that the operation results in a valid memory object which will not cause program termination, device loss, queue stalls, or corruption of other resources when used as allowed according to its allocation parameters. If the external handle provided does not meet these requirements, the implementation must fail the memory import operation with the error code VK_ERROR_INVALID_EXTERNAL_HANDLE. If the parameters define an export operation and the external handle type is VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID, implementations should not strictly follow memoryTypeIndex. Instead, they should modify the allocation internally to use the required memory type for the application’s given usage. This is because for an export operation, there is currently no way for the application to know the memory type index before allocating.

Valid Usage

  • VUID-VkMemoryAllocateInfo-allocationSize-07897
    If the parameters do not define an import or export operation, allocationSize must be greater than 0

  • VUID-VkMemoryAllocateInfo-None-06657
    The parameters must not define more than one import operation

  • VUID-VkMemoryAllocateInfo-allocationSize-07899
    If the parameters define an export operation and the handle type is not VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID , allocationSize must be greater than 0

  • VUID-VkMemoryAllocateInfo-buffer-06380
    If the parameters define an import operation from an VkBufferCollectionFUCHSIA, and VkMemoryDedicatedAllocateInfo::buffer is present and non-NULL, VkImportMemoryBufferCollectionFUCHSIA::collection and VkImportMemoryBufferCollectionFUCHSIA::index must match VkBufferCollectionBufferCreateInfoFUCHSIA::collection and VkBufferCollectionBufferCreateInfoFUCHSIA::index, respectively, of the VkBufferCollectionBufferCreateInfoFUCHSIA structure used to create the VkMemoryDedicatedAllocateInfo::buffer

  • VUID-VkMemoryAllocateInfo-image-06381
    If the parameters define an import operation from an VkBufferCollectionFUCHSIA, and VkMemoryDedicatedAllocateInfo::image is present and non-NULL, VkImportMemoryBufferCollectionFUCHSIA::collection and VkImportMemoryBufferCollectionFUCHSIA::index must match VkBufferCollectionImageCreateInfoFUCHSIA::collection and VkBufferCollectionImageCreateInfoFUCHSIA::index, respectively, of the VkBufferCollectionImageCreateInfoFUCHSIA structure used to create the VkMemoryDedicatedAllocateInfo::image

  • VUID-VkMemoryAllocateInfo-allocationSize-06382
    If the parameters define an import operation from an VkBufferCollectionFUCHSIA, allocationSize must match VkMemoryRequirements::size value retrieved by vkGetImageMemoryRequirements or vkGetBufferMemoryRequirements for image-based or buffer-based collections respectively

  • VUID-VkMemoryAllocateInfo-pNext-06383
    If the parameters define an import operation from an VkBufferCollectionFUCHSIA, the pNext chain must include a VkMemoryDedicatedAllocateInfo structure with either its image or buffer field set to a value other than VK_NULL_HANDLE

  • VUID-VkMemoryAllocateInfo-image-06384
    If the parameters define an import operation from an VkBufferCollectionFUCHSIA and VkMemoryDedicatedAllocateInfo::image is not VK_NULL_HANDLE, the image must be created with a VkBufferCollectionImageCreateInfoFUCHSIA structure chained to its VkImageCreateInfo::pNext pointer

  • VUID-VkMemoryAllocateInfo-buffer-06385
    If the parameters define an import operation from an VkBufferCollectionFUCHSIA and VkMemoryDedicatedAllocateInfo::buffer is not VK_NULL_HANDLE, the buffer must be created with a VkBufferCollectionBufferCreateInfoFUCHSIA structure chained to its VkBufferCreateInfo::pNext pointer

  • VUID-VkMemoryAllocateInfo-memoryTypeIndex-06386
    If the parameters define an import operation from an VkBufferCollectionFUCHSIA, memoryTypeIndex must be from VkBufferCollectionPropertiesFUCHSIA as retrieved by vkGetBufferCollectionPropertiesFUCHSIA

  • VUID-VkMemoryAllocateInfo-pNext-00639
    If the pNext chain includes a VkExportMemoryAllocateInfo structure, and any of the handle types specified in VkExportMemoryAllocateInfo::handleTypes require a dedicated allocation, as reported by vkGetPhysicalDeviceImageFormatProperties2 in VkExternalImageFormatProperties::externalMemoryProperties.externalMemoryFeatures, or by vkGetPhysicalDeviceExternalBufferProperties in VkExternalBufferProperties::externalMemoryProperties.externalMemoryFeatures, the pNext chain must include a VkMemoryDedicatedAllocateInfo or VkDedicatedAllocationMemoryAllocateInfoNV structure with either its image or buffer member set to a value other than VK_NULL_HANDLE

  • VUID-VkMemoryAllocateInfo-pNext-00640
    If the pNext chain includes a VkExportMemoryAllocateInfo structure, it must not include a VkExportMemoryAllocateInfoNV or VkExportMemoryWin32HandleInfoNV structure

  • VUID-VkMemoryAllocateInfo-pNext-00641
    If the pNext chain includes a VkImportMemoryWin32HandleInfoKHR structure, it must not include a VkImportMemoryWin32HandleInfoNV structure

  • VUID-VkMemoryAllocateInfo-allocationSize-01742
    If the parameters define an import operation, the external handle specified was created by the Vulkan API, and the external handle type is VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_FD_BIT, then the values of allocationSize and memoryTypeIndex must match those specified when the payload being imported was created

  • VUID-VkMemoryAllocateInfo-None-00643
    If the parameters define an import operation and the external handle specified was created by the Vulkan API, the device mask specified by VkMemoryAllocateFlagsInfo must match the mask specified when the payload being imported was allocated

  • VUID-VkMemoryAllocateInfo-None-00644
    If the parameters define an import operation and the external handle specified was created by the Vulkan API, the list of physical devices that comprise the logical device passed to vkAllocateMemory must match the list of physical devices that comprise the logical device on which the payload was originally allocated

  • VUID-VkMemoryAllocateInfo-memoryTypeIndex-00645
    If the parameters define an import operation and the external handle is an NT handle or a global share handle created outside of the Vulkan API, the value of memoryTypeIndex must be one of those returned by vkGetMemoryWin32HandlePropertiesKHR

  • VUID-VkMemoryAllocateInfo-allocationSize-01743
    If the parameters define an import operation, the external handle was created by the Vulkan API, and the external handle type is VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_BIT or VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_KMT_BIT, then the values of allocationSize and memoryTypeIndex must match those specified when the payload being imported was created

  • VUID-VkMemoryAllocateInfo-allocationSize-00647
    If the parameters define an import operation and the external handle type is VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_HEAP_BIT, allocationSize must match the size specified when creating the Direct3D 12 heap from which the payload was extracted

  • VUID-VkMemoryAllocateInfo-memoryTypeIndex-00648
    If the parameters define an import operation and the external handle is a POSIX file descriptor created outside of the Vulkan API, the value of memoryTypeIndex must be one of those returned by vkGetMemoryFdPropertiesKHR

  • VUID-VkMemoryAllocateInfo-memoryTypeIndex-01872
    If the protectedMemory feature is not enabled, the VkMemoryAllocateInfo::memoryTypeIndex must not indicate a memory type that reports VK_MEMORY_PROPERTY_PROTECTED_BIT

  • VUID-VkMemoryAllocateInfo-memoryTypeIndex-01744
    If the parameters define an import operation and the external handle is a host pointer, the value of memoryTypeIndex must be one of those returned by vkGetMemoryHostPointerPropertiesEXT

  • VUID-VkMemoryAllocateInfo-allocationSize-01745
    If the parameters define an import operation and the external handle is a host pointer, allocationSize must be an integer multiple of VkPhysicalDeviceExternalMemoryHostPropertiesEXT::minImportedHostPointerAlignment

  • VUID-VkMemoryAllocateInfo-pNext-02805
    If the parameters define an import operation and the external handle is a host pointer, the pNext chain must not include a VkDedicatedAllocationMemoryAllocateInfoNV structure with either its image or buffer field set to a value other than VK_NULL_HANDLE

  • VUID-VkMemoryAllocateInfo-pNext-02806
    If the parameters define an import operation and the external handle is a host pointer, the pNext chain must not include a VkMemoryDedicatedAllocateInfo structure with either its image or buffer field set to a value other than VK_NULL_HANDLE

  • VUID-VkMemoryAllocateInfo-allocationSize-02383
    If the parameters define an import operation and the external handle type is VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID, allocationSize must be the size returned by vkGetAndroidHardwareBufferPropertiesANDROID for the Android hardware buffer

  • VUID-VkMemoryAllocateInfo-pNext-02384
    If the parameters define an import operation and the external handle type is VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID, and the pNext chain does not include a VkMemoryDedicatedAllocateInfo structure or VkMemoryDedicatedAllocateInfo::image is VK_NULL_HANDLE, the Android hardware buffer must have a AHardwareBuffer_Desc::format of AHARDWAREBUFFER_FORMAT_BLOB and a AHardwareBuffer_Desc::usage that includes AHARDWAREBUFFER_USAGE_GPU_DATA_BUFFER

  • VUID-VkMemoryAllocateInfo-memoryTypeIndex-02385
    If the parameters define an import operation and the external handle type is VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID, memoryTypeIndex must be one of those returned by vkGetAndroidHardwareBufferPropertiesANDROID for the Android hardware buffer

  • VUID-VkMemoryAllocateInfo-pNext-01874
    If the parameters do not define an import operation, and the pNext chain includes a VkExportMemoryAllocateInfo structure with VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID included in its handleTypes member, and the pNext chain includes a VkMemoryDedicatedAllocateInfo structure with image not equal to VK_NULL_HANDLE, then allocationSize must be 0

  • VUID-VkMemoryAllocateInfo-pNext-07900
    If the parameters define an export operation, the handle type is VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID, and the pNext does not include a VkMemoryDedicatedAllocateInfo structure, allocationSize must be greater than 0

  • VUID-VkMemoryAllocateInfo-pNext-07901
    If the parameters define an export operation, the handle type is VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID, and the pNext chain includes a VkMemoryDedicatedAllocateInfo structure with buffer set to a valid VkBuffer object, allocationSize must be greater than 0

  • VUID-VkMemoryAllocateInfo-pNext-02386
    If the parameters define an import operation, the external handle is an Android hardware buffer, and the pNext chain includes a VkMemoryDedicatedAllocateInfo with image that is not VK_NULL_HANDLE, the Android hardware buffer’s AHardwareBuffer::usage must include at least one of AHARDWAREBUFFER_USAGE_GPU_FRAMEBUFFER, AHARDWAREBUFFER_USAGE_GPU_SAMPLED_IMAGE or AHARDWAREBUFFER_USAGE_GPU_DATA_BUFFER

  • VUID-VkMemoryAllocateInfo-pNext-02387
    If the parameters define an import operation, the external handle is an Android hardware buffer, and the pNext chain includes a VkMemoryDedicatedAllocateInfo with image that is not VK_NULL_HANDLE, the format of image must be VK_FORMAT_UNDEFINED or the format returned by vkGetAndroidHardwareBufferPropertiesANDROID in VkAndroidHardwareBufferFormatPropertiesANDROID::format for the Android hardware buffer

  • VUID-VkMemoryAllocateInfo-pNext-02388
    If the parameters define an import operation, the external handle is an Android hardware buffer, and the pNext chain includes a VkMemoryDedicatedAllocateInfo structure with image that is not VK_NULL_HANDLE, the width, height, and array layer dimensions of image and the Android hardware buffer’s AHardwareBuffer_Desc must be identical

  • VUID-VkMemoryAllocateInfo-pNext-02389
    If the parameters define an import operation, the external handle is an Android hardware buffer, and the pNext chain includes a VkMemoryDedicatedAllocateInfo structure with image that is not VK_NULL_HANDLE, and the Android hardware buffer’s AHardwareBuffer::usage includes AHARDWAREBUFFER_USAGE_GPU_MIPMAP_COMPLETE, the image must have a complete mipmap chain

  • VUID-VkMemoryAllocateInfo-pNext-02586
    If the parameters define an import operation, the external handle is an Android hardware buffer, and the pNext chain includes a VkMemoryDedicatedAllocateInfo structure with image that is not VK_NULL_HANDLE, and the Android hardware buffer’s AHardwareBuffer::usage does not include AHARDWAREBUFFER_USAGE_GPU_MIPMAP_COMPLETE, the image must have exactly one mipmap level

  • VUID-VkMemoryAllocateInfo-pNext-02390
    If the parameters define an import operation, the external handle is an Android hardware buffer, and the pNext chain includes a VkMemoryDedicatedAllocateInfo structure with image that is not VK_NULL_HANDLE, each bit set in the usage of image must be listed in AHardwareBuffer Usage Equivalence, and if there is a corresponding AHARDWAREBUFFER_USAGE bit listed that bit must be included in the Android hardware buffer’s AHardwareBuffer_Desc::usage

  • VUID-VkMemoryAllocateInfo-screenBufferImport-08941
    If the parameters define an import operation and the external handle type is VK_EXTERNAL_MEMORY_HANDLE_TYPE_SCREEN_BUFFER_BIT_QNX, VkPhysicalDeviceExternalMemoryScreenBufferFeaturesQNX::screenBufferImport must be enabled

  • VUID-VkMemoryAllocateInfo-allocationSize-08942
    If the parameters define an import operation and the external handle type is VK_EXTERNAL_MEMORY_HANDLE_TYPE_SCREEN_BUFFER_BIT_QNX, allocationSize must be the size returned by vkGetScreenBufferPropertiesQNX for the QNX Screen buffer

  • VUID-VkMemoryAllocateInfo-memoryTypeIndex-08943
    If the parameters define an import operation and the external handle type is VK_EXTERNAL_MEMORY_HANDLE_TYPE_SCREEN_BUFFER_BIT_QNX, memoryTypeIndex must be one of those returned by vkGetScreenBufferPropertiesQNX for the QNX Screen buffer

  • VUID-VkMemoryAllocateInfo-pNext-08944
    If the parameters define an import operation, the external handle is a QNX Screen buffer, and the pNext chain includes a VkMemoryDedicatedAllocateInfo with image that is not VK_NULL_HANDLE, the QNX Screen’s buffer must be a valid QNX Screen buffer

  • VUID-VkMemoryAllocateInfo-pNext-08945
    If the parameters define an import operation, the external handle is an QNX Screen buffer, and the pNext chain includes a VkMemoryDedicatedAllocateInfo with image that is not VK_NULL_HANDLE, the format of image must be VK_FORMAT_UNDEFINED or the format returned by vkGetScreenBufferPropertiesQNX in VkScreenBufferFormatPropertiesQNX::format for the QNX Screen buffer

  • VUID-VkMemoryAllocateInfo-pNext-08946
    If the parameters define an import operation, the external handle is a QNX Screen buffer, and the pNext chain includes a VkMemoryDedicatedAllocateInfo structure with image that is not VK_NULL_HANDLE, the width, height, and array layer dimensions of image and the QNX Screen buffer’s _screen_buffer must be identical

  • VUID-VkMemoryAllocateInfo-opaqueCaptureAddress-03329
    If VkMemoryOpaqueCaptureAddressAllocateInfo::opaqueCaptureAddress is not zero, VkMemoryAllocateFlagsInfo::flags must include VK_MEMORY_ALLOCATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT

  • VUID-VkMemoryAllocateInfo-flags-03330
    If VkMemoryAllocateFlagsInfo::flags includes VK_MEMORY_ALLOCATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT, the bufferDeviceAddressCaptureReplay feature must be enabled

  • VUID-VkMemoryAllocateInfo-flags-03331
    If VkMemoryAllocateFlagsInfo::flags includes VK_MEMORY_ALLOCATE_DEVICE_ADDRESS_BIT, the bufferDeviceAddress feature must be enabled

  • VUID-VkMemoryAllocateInfo-pNext-03332
    If the pNext chain includes a VkImportMemoryHostPointerInfoEXT structure, VkMemoryOpaqueCaptureAddressAllocateInfo::opaqueCaptureAddress must be zero

  • VUID-VkMemoryAllocateInfo-opaqueCaptureAddress-03333
    If the parameters define an import operation, VkMemoryOpaqueCaptureAddressAllocateInfo::opaqueCaptureAddress must be zero

  • VUID-VkMemoryAllocateInfo-None-04749
    If the parameters define an import operation and the external handle type is VK_EXTERNAL_MEMORY_HANDLE_TYPE_ZIRCON_VMO_BIT_FUCHSIA, the value of memoryTypeIndex must be an index identifying a memory type from the memoryTypeBits field of the VkMemoryZirconHandlePropertiesFUCHSIA structure populated by a call to vkGetMemoryZirconHandlePropertiesFUCHSIA

  • VUID-VkMemoryAllocateInfo-allocationSize-07902
    If the parameters define an import operation and the external handle type is VK_EXTERNAL_MEMORY_HANDLE_TYPE_ZIRCON_VMO_BIT_FUCHSIA, the value of allocationSize must be greater than 0

  • VUID-VkMemoryAllocateInfo-allocationSize-07903
    If the parameters define an import operation and the external handle type is VK_EXTERNAL_MEMORY_HANDLE_TYPE_ZIRCON_VMO_BIT_FUCHSIA, the value of allocationSize must be less than or equal to the size of the VMO as determined by zx_vmo_get_size(handle) where handle is the VMO handle to the imported external memory

  • VUID-VkMemoryAllocateInfo-pNext-06780
    If the pNext chain includes a VkExportMetalObjectCreateInfoEXT structure, its exportObjectType member must be VK_EXPORT_METAL_OBJECT_TYPE_METAL_BUFFER_BIT_EXT

Valid Usage (Implicit)

If the pNext chain includes a VkMemoryDedicatedAllocateInfo structure, then that structure includes a handle of the sole buffer or image resource that the memory can be bound to.

The VkMemoryDedicatedAllocateInfo structure is defined as:

// Provided by VK_VERSION_1_1
typedef struct VkMemoryDedicatedAllocateInfo {
    VkStructureType    sType;
    const void*        pNext;
    VkImage            image;
    VkBuffer           buffer;
} VkMemoryDedicatedAllocateInfo;

or the equivalent

// Provided by VK_KHR_dedicated_allocation
typedef VkMemoryDedicatedAllocateInfo VkMemoryDedicatedAllocateInfoKHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • image is VK_NULL_HANDLE or a handle of an image which this memory will be bound to.

  • buffer is VK_NULL_HANDLE or a handle of a buffer which this memory will be bound to.

Valid Usage

  • VUID-VkMemoryDedicatedAllocateInfo-image-01432
    At least one of image and buffer must be VK_NULL_HANDLE

  • VUID-VkMemoryDedicatedAllocateInfo-image-02964
    If image is not VK_NULL_HANDLE and the memory is not an imported Android Hardware Buffer or an imported QNX Screen buffer , VkMemoryAllocateInfo::allocationSize must equal the VkMemoryRequirements::size of the image

  • VUID-VkMemoryDedicatedAllocateInfo-image-01434
    If image is not VK_NULL_HANDLE, image must have been created without VK_IMAGE_CREATE_SPARSE_BINDING_BIT set in VkImageCreateInfo::flags

  • VUID-VkMemoryDedicatedAllocateInfo-buffer-02965
    If buffer is not VK_NULL_HANDLE and the memory is not an imported Android Hardware Buffer or an imported QNX Screen buffer , VkMemoryAllocateInfo::allocationSize must equal the VkMemoryRequirements::size of the buffer

  • VUID-VkMemoryDedicatedAllocateInfo-buffer-01436
    If buffer is not VK_NULL_HANDLE, buffer must have been created without VK_BUFFER_CREATE_SPARSE_BINDING_BIT set in VkBufferCreateInfo::flags

  • VUID-VkMemoryDedicatedAllocateInfo-image-01876
    If image is not VK_NULL_HANDLE and VkMemoryAllocateInfo defines a memory import operation with handle type VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_BIT, VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_KMT_BIT, VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_BIT, VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_KMT_BIT, VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_HEAP_BIT, or VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_RESOURCE_BIT, and the external handle was created by the Vulkan API, then the memory being imported must also be a dedicated image allocation and image must be identical to the image associated with the imported memory

  • VUID-VkMemoryDedicatedAllocateInfo-buffer-01877
    If buffer is not VK_NULL_HANDLE and VkMemoryAllocateInfo defines a memory import operation with handle type VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_BIT, VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_KMT_BIT, VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_BIT, VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_KMT_BIT, VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_HEAP_BIT, or VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_RESOURCE_BIT, and the external handle was created by the Vulkan API, then the memory being imported must also be a dedicated buffer allocation and buffer must be identical to the buffer associated with the imported memory

  • VUID-VkMemoryDedicatedAllocateInfo-image-01878
    If image is not VK_NULL_HANDLE and VkMemoryAllocateInfo defines a memory import operation with handle type VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_FD_BIT, the memory being imported must also be a dedicated image allocation and image must be identical to the image associated with the imported memory

  • VUID-VkMemoryDedicatedAllocateInfo-buffer-01879
    If buffer is not VK_NULL_HANDLE and VkMemoryAllocateInfo defines a memory import operation with handle type VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_FD_BIT, the memory being imported must also be a dedicated buffer allocation and buffer must be identical to the buffer associated with the imported memory

  • VUID-VkMemoryDedicatedAllocateInfo-image-01797
    If image is not VK_NULL_HANDLE, image must not have been created with VK_IMAGE_CREATE_DISJOINT_BIT set in VkImageCreateInfo::flags

  • VUID-VkMemoryDedicatedAllocateInfo-image-04751
    If image is not VK_NULL_HANDLE and VkMemoryAllocateInfo defines a memory import operation with handle type VK_EXTERNAL_MEMORY_HANDLE_TYPE_ZIRCON_VMO_BIT_FUCHSIA, the memory being imported must also be a dedicated image allocation and image must be identical to the image associated with the imported memory

  • VUID-VkMemoryDedicatedAllocateInfo-buffer-04752
    If buffer is not VK_NULL_HANDLE and VkMemoryAllocateInfo defines a memory import operation with handle type VK_EXTERNAL_MEMORY_HANDLE_TYPE_ZIRCON_VMO_BIT_FUCHSIA, the memory being imported must also be a dedicated buffer allocation and buffer must be identical to the buffer associated with the imported memory

Valid Usage (Implicit)

  • VUID-VkMemoryDedicatedAllocateInfo-sType-sType
    sType must be VK_STRUCTURE_TYPE_MEMORY_DEDICATED_ALLOCATE_INFO

  • VUID-VkMemoryDedicatedAllocateInfo-image-parameter
    If image is not VK_NULL_HANDLE, image must be a valid VkImage handle

  • VUID-VkMemoryDedicatedAllocateInfo-buffer-parameter
    If buffer is not VK_NULL_HANDLE, buffer must be a valid VkBuffer handle

  • VUID-VkMemoryDedicatedAllocateInfo-commonparent
    Both of buffer, and image that are valid handles of non-ignored parameters must have been created, allocated, or retrieved from the same VkDevice

If the pNext chain includes a VkDedicatedAllocationMemoryAllocateInfoNV structure, then that structure includes a handle of the sole buffer or image resource that the memory can be bound to.

The VkDedicatedAllocationMemoryAllocateInfoNV structure is defined as:

// Provided by VK_NV_dedicated_allocation
typedef struct VkDedicatedAllocationMemoryAllocateInfoNV {
    VkStructureType    sType;
    const void*        pNext;
    VkImage            image;
    VkBuffer           buffer;
} VkDedicatedAllocationMemoryAllocateInfoNV;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • image is VK_NULL_HANDLE or a handle of an image which this memory will be bound to.

  • buffer is VK_NULL_HANDLE or a handle of a buffer which this memory will be bound to.

Valid Usage

  • VUID-VkDedicatedAllocationMemoryAllocateInfoNV-image-00649
    At least one of image and buffer must be VK_NULL_HANDLE

  • VUID-VkDedicatedAllocationMemoryAllocateInfoNV-image-00650
    If image is not VK_NULL_HANDLE, the image must have been created with VkDedicatedAllocationImageCreateInfoNV::dedicatedAllocation equal to VK_TRUE

  • VUID-VkDedicatedAllocationMemoryAllocateInfoNV-buffer-00651
    If buffer is not VK_NULL_HANDLE, the buffer must have been created with VkDedicatedAllocationBufferCreateInfoNV::dedicatedAllocation equal to VK_TRUE

  • VUID-VkDedicatedAllocationMemoryAllocateInfoNV-image-00652
    If image is not VK_NULL_HANDLE, VkMemoryAllocateInfo::allocationSize must equal the VkMemoryRequirements::size of the image

  • VUID-VkDedicatedAllocationMemoryAllocateInfoNV-buffer-00653
    If buffer is not VK_NULL_HANDLE, VkMemoryAllocateInfo::allocationSize must equal the VkMemoryRequirements::size of the buffer

  • VUID-VkDedicatedAllocationMemoryAllocateInfoNV-image-00654
    If image is not VK_NULL_HANDLE and VkMemoryAllocateInfo defines a memory import operation, the memory being imported must also be a dedicated image allocation and image must be identical to the image associated with the imported memory

  • VUID-VkDedicatedAllocationMemoryAllocateInfoNV-buffer-00655
    If buffer is not VK_NULL_HANDLE and VkMemoryAllocateInfo defines a memory import operation, the memory being imported must also be a dedicated buffer allocation and buffer must be identical to the buffer associated with the imported memory

Valid Usage (Implicit)

  • VUID-VkDedicatedAllocationMemoryAllocateInfoNV-sType-sType
    sType must be VK_STRUCTURE_TYPE_DEDICATED_ALLOCATION_MEMORY_ALLOCATE_INFO_NV

  • VUID-VkDedicatedAllocationMemoryAllocateInfoNV-image-parameter
    If image is not VK_NULL_HANDLE, image must be a valid VkImage handle

  • VUID-VkDedicatedAllocationMemoryAllocateInfoNV-buffer-parameter
    If buffer is not VK_NULL_HANDLE, buffer must be a valid VkBuffer handle

  • VUID-VkDedicatedAllocationMemoryAllocateInfoNV-commonparent
    Both of buffer, and image that are valid handles of non-ignored parameters must have been created, allocated, or retrieved from the same VkDevice

If the pNext chain includes a VkMemoryPriorityAllocateInfoEXT structure, then that structure includes a priority for the memory.

The VkMemoryPriorityAllocateInfoEXT structure is defined as:

// Provided by VK_EXT_memory_priority
typedef struct VkMemoryPriorityAllocateInfoEXT {
    VkStructureType    sType;
    const void*        pNext;
    float              priority;
} VkMemoryPriorityAllocateInfoEXT;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • priority is a floating-point value between 0 and 1, indicating the priority of the allocation relative to other memory allocations. Larger values are higher priority. The granularity of the priorities is implementation-dependent.

Memory allocations with higher priority may be more likely to stay in device-local memory when the system is under memory pressure.

If this structure is not included, it is as if the priority value were 0.5.

Valid Usage

  • VUID-VkMemoryPriorityAllocateInfoEXT-priority-02602
    priority must be between 0 and 1, inclusive

Valid Usage (Implicit)

  • VUID-VkMemoryPriorityAllocateInfoEXT-sType-sType
    sType must be VK_STRUCTURE_TYPE_MEMORY_PRIORITY_ALLOCATE_INFO_EXT

To modify the priority of an existing memory allocation, call:

// Provided by VK_EXT_pageable_device_local_memory
void vkSetDeviceMemoryPriorityEXT(
    VkDevice                                    device,
    VkDeviceMemory                              memory,
    float                                       priority);

  • device is the logical device that owns the memory.

  • memory is the VkDeviceMemory object to which the new priority will be applied.

  • priority is a floating-point value between 0 and 1, indicating the priority of the allocation relative to other memory allocations. Larger values are higher priority. The granularity of the priorities is implementation-dependent.

Memory allocations with higher priority may be more likely to stay in device-local memory when the system is under memory pressure.

Valid Usage

  • VUID-vkSetDeviceMemoryPriorityEXT-priority-06258
    priority must be between 0 and 1, inclusive

Valid Usage (Implicit)

  • VUID-vkSetDeviceMemoryPriorityEXT-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkSetDeviceMemoryPriorityEXT-memory-parameter
    memory must be a valid VkDeviceMemory handle

  • VUID-vkSetDeviceMemoryPriorityEXT-memory-parent
    memory must have been created, allocated, or retrieved from device

When allocating memory whose payload may be exported to another process or Vulkan instance, add a VkExportMemoryAllocateInfo structure to the pNext chain of the VkMemoryAllocateInfo structure, specifying the handle types that may be exported.

The VkExportMemoryAllocateInfo structure is defined as:

// Provided by VK_VERSION_1_1
typedef struct VkExportMemoryAllocateInfo {
    VkStructureType                    sType;
    const void*                        pNext;
    VkExternalMemoryHandleTypeFlags    handleTypes;
} VkExportMemoryAllocateInfo;

or the equivalent

// Provided by VK_KHR_external_memory
typedef VkExportMemoryAllocateInfo VkExportMemoryAllocateInfoKHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • handleTypes is zero or a bitmask of VkExternalMemoryHandleTypeFlagBits specifying one or more memory handle types the application can export from the resulting allocation. The application can request multiple handle types for the same allocation.

Valid Usage
Valid Usage (Implicit)

  • VUID-VkExportMemoryAllocateInfo-sType-sType
    sType must be VK_STRUCTURE_TYPE_EXPORT_MEMORY_ALLOCATE_INFO

  • VUID-VkExportMemoryAllocateInfo-handleTypes-parameter
    handleTypes must be a valid combination of VkExternalMemoryHandleTypeFlagBits values

When allocating memory that may be exported to another process or Vulkan instance, add a VkExportMemoryAllocateInfoNV structure to the pNext chain of the VkMemoryAllocateInfo structure, specifying the handle types that may be exported.

The VkExportMemoryAllocateInfoNV structure is defined as:

// Provided by VK_NV_external_memory
typedef struct VkExportMemoryAllocateInfoNV {
    VkStructureType                      sType;
    const void*                          pNext;
    VkExternalMemoryHandleTypeFlagsNV    handleTypes;
} VkExportMemoryAllocateInfoNV;
Valid Usage (Implicit)

  • VUID-VkExportMemoryAllocateInfoNV-sType-sType
    sType must be VK_STRUCTURE_TYPE_EXPORT_MEMORY_ALLOCATE_INFO_NV

  • VUID-VkExportMemoryAllocateInfoNV-handleTypes-parameter
    handleTypes must be a valid combination of VkExternalMemoryHandleTypeFlagBitsNV values

11.2.4. Win32 External Memory

To specify additional attributes of NT handles exported from a memory object, add a VkExportMemoryWin32HandleInfoKHR structure to the pNext chain of the VkMemoryAllocateInfo structure. The VkExportMemoryWin32HandleInfoKHR structure is defined as:

// Provided by VK_KHR_external_memory_win32
typedef struct VkExportMemoryWin32HandleInfoKHR {
    VkStructureType               sType;
    const void*                   pNext;
    const SECURITY_ATTRIBUTES*    pAttributes;
    DWORD                         dwAccess;
    LPCWSTR                       name;
} VkExportMemoryWin32HandleInfoKHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • pAttributes is a pointer to a Windows SECURITY_ATTRIBUTES structure specifying security attributes of the handle.

  • dwAccess is a DWORD specifying access rights of the handle.

  • name is a null-terminated UTF-16 string to associate with the payload referenced by NT handles exported from the created memory.

If VkExportMemoryAllocateInfo is not included in the same pNext chain, this structure is ignored.

If VkExportMemoryAllocateInfo is included in the pNext chain of VkMemoryAllocateInfo with a Windows handleType, but either VkExportMemoryWin32HandleInfoKHR is not included in the pNext chain, or it is included but pAttributes is set to NULL, default security descriptor values will be used, and child processes created by the application will not inherit the handle, as described in the MSDN documentation for “Synchronization Object Security and Access Rights”1. Further, if the structure is not present, the access rights used depend on the handle type.

For handles of the following types:

  • VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_BIT

The implementation must ensure the access rights allow read and write access to the memory.

1

https://docs.microsoft.com/en-us/windows/win32/sync/synchronization-object-security-and-access-rights

Valid Usage

  • VUID-VkExportMemoryWin32HandleInfoKHR-handleTypes-00657
    If VkExportMemoryAllocateInfo::handleTypes does not include VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_BIT, a VkExportMemoryWin32HandleInfoKHR structure must not be included in the pNext chain of VkMemoryAllocateInfo

Valid Usage (Implicit)

  • VUID-VkExportMemoryWin32HandleInfoKHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_EXPORT_MEMORY_WIN32_HANDLE_INFO_KHR

  • VUID-VkExportMemoryWin32HandleInfoKHR-pAttributes-parameter
    If pAttributes is not NULL, pAttributes must be a valid pointer to a valid SECURITY_ATTRIBUTES value

To import memory from a Windows handle, add a VkImportMemoryWin32HandleInfoKHR structure to the pNext chain of the VkMemoryAllocateInfo structure.

The VkImportMemoryWin32HandleInfoKHR structure is defined as:

// Provided by VK_KHR_external_memory_win32
typedef struct VkImportMemoryWin32HandleInfoKHR {
    VkStructureType                       sType;
    const void*                           pNext;
    VkExternalMemoryHandleTypeFlagBits    handleType;
    HANDLE                                handle;
    LPCWSTR                               name;
} VkImportMemoryWin32HandleInfoKHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • handleType is a VkExternalMemoryHandleTypeFlagBits value specifying the type of handle or name.

  • handle is NULL or the external handle to import.

  • name is NULL or a null-terminated UTF-16 string naming the payload to import.

Importing memory object payloads from Windows handles does not transfer ownership of the handle to the Vulkan implementation. For handle types defined as NT handles, the application must release handle ownership using the CloseHandle system call when the handle is no longer needed. For handle types defined as NT handles, the imported memory object holds a reference to its payload.

Note

Non-NT handle import operations do not add a reference to their associated payload. If the original object owning the payload is destroyed, all resources and handles sharing that payload will become invalid.

Applications can import the same payload into multiple instances of Vulkan, into the same instance from which it was exported, and multiple times into a given Vulkan instance. In all cases, each import operation must create a distinct VkDeviceMemory object.

Valid Usage

  • VUID-VkImportMemoryWin32HandleInfoKHR-handleType-00658
    If handleType is not 0, it must be supported for import, as reported by VkExternalImageFormatProperties or VkExternalBufferProperties

  • VUID-VkImportMemoryWin32HandleInfoKHR-handle-00659
    The memory from which handle was exported, or the memory named by name must have been created on the same underlying physical device as device

  • VUID-VkImportMemoryWin32HandleInfoKHR-handleType-00660
    If handleType is not 0, it must be defined as an NT handle or a global share handle

  • VUID-VkImportMemoryWin32HandleInfoKHR-handleType-01439
    If handleType is not VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_BIT, VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_BIT, VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_HEAP_BIT, or VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_RESOURCE_BIT, name must be NULL

  • VUID-VkImportMemoryWin32HandleInfoKHR-handleType-01440
    If handleType is not 0 and handle is NULL, name must name a valid memory resource of the type specified by handleType

  • VUID-VkImportMemoryWin32HandleInfoKHR-handleType-00661
    If handleType is not 0 and name is NULL, handle must be a valid handle of the type specified by handleType

  • VUID-VkImportMemoryWin32HandleInfoKHR-handle-01441
    If handle is not NULL, name must be NULL

  • VUID-VkImportMemoryWin32HandleInfoKHR-handle-01518
    If handle is not NULL, it must obey any requirements listed for handleType in external memory handle types compatibility

  • VUID-VkImportMemoryWin32HandleInfoKHR-name-01519
    If name is not NULL, it must obey any requirements listed for handleType in external memory handle types compatibility

Valid Usage (Implicit)

  • VUID-VkImportMemoryWin32HandleInfoKHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_IMPORT_MEMORY_WIN32_HANDLE_INFO_KHR

  • VUID-VkImportMemoryWin32HandleInfoKHR-handleType-parameter
    If handleType is not 0, handleType must be a valid VkExternalMemoryHandleTypeFlagBits value

To export a Windows handle representing the payload of a Vulkan device memory object, call:

// Provided by VK_KHR_external_memory_win32
VkResult vkGetMemoryWin32HandleKHR(
    VkDevice                                    device,
    const VkMemoryGetWin32HandleInfoKHR*        pGetWin32HandleInfo,
    HANDLE*                                     pHandle);

  • device is the logical device that created the device memory being exported.

  • pGetWin32HandleInfo is a pointer to a VkMemoryGetWin32HandleInfoKHR structure containing parameters of the export operation.

  • pHandle will return the Windows handle representing the payload of the device memory object.

For handle types defined as NT handles, the handles returned by vkGetMemoryWin32HandleKHR are owned by the application and hold a reference to their payload. To avoid leaking resources, the application must release ownership of them using the CloseHandle system call when they are no longer needed.

Note

Non-NT handle types do not add a reference to their associated payload. If the original object owning the payload is destroyed, all resources and handles sharing that payload will become invalid.
Valid Usage (Implicit)

  • VUID-vkGetMemoryWin32HandleKHR-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkGetMemoryWin32HandleKHR-pGetWin32HandleInfo-parameter
    pGetWin32HandleInfo must be a valid pointer to a valid VkMemoryGetWin32HandleInfoKHR structure

  • VUID-vkGetMemoryWin32HandleKHR-pHandle-parameter
    pHandle must be a valid pointer to a HANDLE value

Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_TOO_MANY_OBJECTS

  • VK_ERROR_OUT_OF_HOST_MEMORY

The VkMemoryGetWin32HandleInfoKHR structure is defined as:

// Provided by VK_KHR_external_memory_win32
typedef struct VkMemoryGetWin32HandleInfoKHR {
    VkStructureType                       sType;
    const void*                           pNext;
    VkDeviceMemory                        memory;
    VkExternalMemoryHandleTypeFlagBits    handleType;
} VkMemoryGetWin32HandleInfoKHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • memory is the memory object from which the handle will be exported.

  • handleType is a VkExternalMemoryHandleTypeFlagBits value specifying the type of handle requested.

The properties of the handle returned depend on the value of handleType. See VkExternalMemoryHandleTypeFlagBits for a description of the properties of the defined external memory handle types.

Valid Usage

  • VUID-VkMemoryGetWin32HandleInfoKHR-handleType-00662
    handleType must have been included in VkExportMemoryAllocateInfo::handleTypes when memory was created

  • VUID-VkMemoryGetWin32HandleInfoKHR-handleType-00663
    If handleType is defined as an NT handle, vkGetMemoryWin32HandleKHR must be called no more than once for each valid unique combination of memory and handleType

  • VUID-VkMemoryGetWin32HandleInfoKHR-handleType-00664
    handleType must be defined as an NT handle or a global share handle

Valid Usage (Implicit)

  • VUID-VkMemoryGetWin32HandleInfoKHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_MEMORY_GET_WIN32_HANDLE_INFO_KHR

  • VUID-VkMemoryGetWin32HandleInfoKHR-pNext-pNext
    pNext must be NULL

  • VUID-VkMemoryGetWin32HandleInfoKHR-memory-parameter
    memory must be a valid VkDeviceMemory handle

  • VUID-VkMemoryGetWin32HandleInfoKHR-handleType-parameter
    handleType must be a valid VkExternalMemoryHandleTypeFlagBits value

Windows memory handles compatible with Vulkan may also be created by non-Vulkan APIs using methods beyond the scope of this specification. To determine the correct parameters to use when importing such handles, call:

// Provided by VK_KHR_external_memory_win32
VkResult vkGetMemoryWin32HandlePropertiesKHR(
    VkDevice                                    device,
    VkExternalMemoryHandleTypeFlagBits          handleType,
    HANDLE                                      handle,
    VkMemoryWin32HandlePropertiesKHR*           pMemoryWin32HandleProperties);

  • device is the logical device that will be importing handle.

  • handleType is a VkExternalMemoryHandleTypeFlagBits value specifying the type of the handle handle.

  • handle is the handle which will be imported.

  • pMemoryWin32HandleProperties is a pointer to a VkMemoryWin32HandlePropertiesKHR structure in which properties of handle are returned.

Valid Usage

  • VUID-vkGetMemoryWin32HandlePropertiesKHR-handle-00665
    handle must point to a valid Windows memory handle

  • VUID-vkGetMemoryWin32HandlePropertiesKHR-handleType-00666
    handleType must not be one of the handle types defined as opaque

Valid Usage (Implicit)

  • VUID-vkGetMemoryWin32HandlePropertiesKHR-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkGetMemoryWin32HandlePropertiesKHR-handleType-parameter
    handleType must be a valid VkExternalMemoryHandleTypeFlagBits value

  • VUID-vkGetMemoryWin32HandlePropertiesKHR-pMemoryWin32HandleProperties-parameter
    pMemoryWin32HandleProperties must be a valid pointer to a VkMemoryWin32HandlePropertiesKHR structure

Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_INVALID_EXTERNAL_HANDLE

The VkMemoryWin32HandlePropertiesKHR structure returned is defined as:

// Provided by VK_KHR_external_memory_win32
typedef struct VkMemoryWin32HandlePropertiesKHR {
    VkStructureType    sType;
    void*              pNext;
    uint32_t           memoryTypeBits;
} VkMemoryWin32HandlePropertiesKHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • memoryTypeBits is a bitmask containing one bit set for every memory type which the specified windows handle can be imported as.

Valid Usage (Implicit)

  • VUID-VkMemoryWin32HandlePropertiesKHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_MEMORY_WIN32_HANDLE_PROPERTIES_KHR

  • VUID-VkMemoryWin32HandlePropertiesKHR-pNext-pNext
    pNext must be NULL

When VkExportMemoryAllocateInfoNV::handleTypes includes VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_BIT_NV, add a VkExportMemoryWin32HandleInfoNV structure to the pNext chain of the VkExportMemoryAllocateInfoNV structure to specify security attributes and access rights for the memory object’s external handle.

The VkExportMemoryWin32HandleInfoNV structure is defined as:

// Provided by VK_NV_external_memory_win32
typedef struct VkExportMemoryWin32HandleInfoNV {
    VkStructureType               sType;
    const void*                   pNext;
    const SECURITY_ATTRIBUTES*    pAttributes;
    DWORD                         dwAccess;
} VkExportMemoryWin32HandleInfoNV;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • pAttributes is a pointer to a Windows SECURITY_ATTRIBUTES structure specifying security attributes of the handle.

  • dwAccess is a DWORD specifying access rights of the handle.

If this structure is not present, or if pAttributes is set to NULL, default security descriptor values will be used, and child processes created by the application will not inherit the handle, as described in the MSDN documentation for “Synchronization Object Security and Access Rights”1. Further, if the structure is not present, the access rights will be

DXGI_SHARED_RESOURCE_READ | DXGI_SHARED_RESOURCE_WRITE

1

https://docs.microsoft.com/en-us/windows/win32/sync/synchronization-object-security-and-access-rights

Valid Usage (Implicit)

  • VUID-VkExportMemoryWin32HandleInfoNV-sType-sType
    sType must be VK_STRUCTURE_TYPE_EXPORT_MEMORY_WIN32_HANDLE_INFO_NV

  • VUID-VkExportMemoryWin32HandleInfoNV-pAttributes-parameter
    If pAttributes is not NULL, pAttributes must be a valid pointer to a valid SECURITY_ATTRIBUTES value

To import memory created on the same physical device but outside of the current Vulkan instance, add a VkImportMemoryWin32HandleInfoNV structure to the pNext chain of the VkMemoryAllocateInfo structure, specifying a handle to and the type of the memory.

The VkImportMemoryWin32HandleInfoNV structure is defined as:

// Provided by VK_NV_external_memory_win32
typedef struct VkImportMemoryWin32HandleInfoNV {
    VkStructureType                      sType;
    const void*                          pNext;
    VkExternalMemoryHandleTypeFlagsNV    handleType;
    HANDLE                               handle;
} VkImportMemoryWin32HandleInfoNV;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • handleType is 0 or a VkExternalMemoryHandleTypeFlagBitsNV value specifying the type of memory handle in handle.

  • handle is a Windows HANDLE referring to the memory.

If handleType is 0, this structure is ignored by consumers of the VkMemoryAllocateInfo structure it is chained from.

Valid Usage

  • VUID-VkImportMemoryWin32HandleInfoNV-handleType-01327
    handleType must not have more than one bit set

  • VUID-VkImportMemoryWin32HandleInfoNV-handle-01328
    handle must be a valid handle to memory, obtained as specified by handleType

Valid Usage (Implicit)

  • VUID-VkImportMemoryWin32HandleInfoNV-sType-sType
    sType must be VK_STRUCTURE_TYPE_IMPORT_MEMORY_WIN32_HANDLE_INFO_NV

  • VUID-VkImportMemoryWin32HandleInfoNV-handleType-parameter
    handleType must be a valid combination of VkExternalMemoryHandleTypeFlagBitsNV values

Bits which can be set in handleType are:

Possible values of VkImportMemoryWin32HandleInfoNV::handleType, specifying the type of an external memory handle, are:

// Provided by VK_NV_external_memory_capabilities
typedef enum VkExternalMemoryHandleTypeFlagBitsNV {
    VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_BIT_NV = 0x00000001,
    VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_KMT_BIT_NV = 0x00000002,
    VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_IMAGE_BIT_NV = 0x00000004,
    VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_IMAGE_KMT_BIT_NV = 0x00000008,
} VkExternalMemoryHandleTypeFlagBitsNV;

  • VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_KMT_BIT_NV specifies a handle to memory returned by vkGetMemoryWin32HandleNV.

  • VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_BIT_NV specifies a handle to memory returned by vkGetMemoryWin32HandleNV, or one duplicated from such a handle using DuplicateHandle().

  • VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_IMAGE_BIT_NV specifies a valid NT handle to memory returned by IDXGIResource1::CreateSharedHandle, or a handle duplicated from such a handle using DuplicateHandle().

  • VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_IMAGE_KMT_BIT_NV specifies a handle to memory returned by IDXGIResource::GetSharedHandle().

// Provided by VK_NV_external_memory_capabilities
typedef VkFlags VkExternalMemoryHandleTypeFlagsNV;

VkExternalMemoryHandleTypeFlagsNV is a bitmask type for setting a mask of zero or more VkExternalMemoryHandleTypeFlagBitsNV.

To retrieve the handle corresponding to a device memory object created with VkExportMemoryAllocateInfoNV::handleTypes set to include VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_BIT_NV or VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_KMT_BIT_NV, call:

// Provided by VK_NV_external_memory_win32
VkResult vkGetMemoryWin32HandleNV(
    VkDevice                                    device,
    VkDeviceMemory                              memory,
    VkExternalMemoryHandleTypeFlagsNV           handleType,
    HANDLE*                                     pHandle);

  • device is the logical device that owns the memory.

  • memory is the VkDeviceMemory object.

  • handleType is a bitmask of VkExternalMemoryHandleTypeFlagBitsNV containing a single bit specifying the type of handle requested.

  • handle is a pointer to a Windows HANDLE in which the handle is returned.

Valid Usage

  • VUID-vkGetMemoryWin32HandleNV-handleType-01326
    handleType must be a flag specified in VkExportMemoryAllocateInfoNV::handleTypes when allocating memory

Valid Usage (Implicit)

  • VUID-vkGetMemoryWin32HandleNV-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkGetMemoryWin32HandleNV-memory-parameter
    memory must be a valid VkDeviceMemory handle

  • VUID-vkGetMemoryWin32HandleNV-handleType-parameter
    handleType must be a valid combination of VkExternalMemoryHandleTypeFlagBitsNV values

  • VUID-vkGetMemoryWin32HandleNV-handleType-requiredbitmask
    handleType must not be 0

  • VUID-vkGetMemoryWin32HandleNV-pHandle-parameter
    pHandle must be a valid pointer to a HANDLE value

  • VUID-vkGetMemoryWin32HandleNV-memory-parent
    memory must have been created, allocated, or retrieved from device

Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_TOO_MANY_OBJECTS

  • VK_ERROR_OUT_OF_HOST_MEMORY

11.2.5. File Descriptor External Memory

To import memory from a POSIX file descriptor handle, add a VkImportMemoryFdInfoKHR structure to the pNext chain of the VkMemoryAllocateInfo structure. The VkImportMemoryFdInfoKHR structure is defined as:

// Provided by VK_KHR_external_memory_fd
typedef struct VkImportMemoryFdInfoKHR {
    VkStructureType                       sType;
    const void*                           pNext;
    VkExternalMemoryHandleTypeFlagBits    handleType;
    int                                   fd;
} VkImportMemoryFdInfoKHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • handleType is a VkExternalMemoryHandleTypeFlagBits value specifying the handle type of fd.

  • fd is the external handle to import.

Importing memory from a file descriptor transfers ownership of the file descriptor from the application to the Vulkan implementation. The application must not perform any operations on the file descriptor after a successful import. The imported memory object holds a reference to its payload.

Applications can import the same payload into multiple instances of Vulkan, into the same instance from which it was exported, and multiple times into a given Vulkan instance. In all cases, each import operation must create a distinct VkDeviceMemory object.

Valid Usage

  • VUID-VkImportMemoryFdInfoKHR-handleType-00667
    If handleType is not 0, it must be supported for import, as reported by VkExternalImageFormatProperties or VkExternalBufferProperties

  • VUID-VkImportMemoryFdInfoKHR-fd-00668
    The memory from which fd was exported must have been created on the same underlying physical device as device

  • VUID-VkImportMemoryFdInfoKHR-handleType-00669
    If handleType is not 0, it must be VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_FD_BIT or VK_EXTERNAL_MEMORY_HANDLE_TYPE_DMA_BUF_BIT_EXT

  • VUID-VkImportMemoryFdInfoKHR-handleType-00670
    If handleType is not 0, fd must be a valid handle of the type specified by handleType

  • VUID-VkImportMemoryFdInfoKHR-fd-01746
    The memory represented by fd must have been created from a physical device and driver that is compatible with device and handleType, as described in External Memory Handle Types Compatibility

  • VUID-VkImportMemoryFdInfoKHR-fd-01520
    fd must obey any requirements listed for handleType in external memory handle types compatibility

Valid Usage (Implicit)

  • VUID-VkImportMemoryFdInfoKHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_IMPORT_MEMORY_FD_INFO_KHR

  • VUID-VkImportMemoryFdInfoKHR-handleType-parameter
    If handleType is not 0, handleType must be a valid VkExternalMemoryHandleTypeFlagBits value

To export a POSIX file descriptor referencing the payload of a Vulkan device memory object, call:

// Provided by VK_KHR_external_memory_fd
VkResult vkGetMemoryFdKHR(
    VkDevice                                    device,
    const VkMemoryGetFdInfoKHR*                 pGetFdInfo,
    int*                                        pFd);

  • device is the logical device that created the device memory being exported.

  • pGetFdInfo is a pointer to a VkMemoryGetFdInfoKHR structure containing parameters of the export operation.

  • pFd will return a file descriptor referencing the payload of the device memory object.

Each call to vkGetMemoryFdKHR must create a new file descriptor holding a reference to the memory object’s payload and transfer ownership of the file descriptor to the application. To avoid leaking resources, the application must release ownership of the file descriptor using the close system call when it is no longer needed, or by importing a Vulkan memory object from it. Where supported by the operating system, the implementation must set the file descriptor to be closed automatically when an execve system call is made.

Valid Usage (Implicit)

  • VUID-vkGetMemoryFdKHR-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkGetMemoryFdKHR-pGetFdInfo-parameter
    pGetFdInfo must be a valid pointer to a valid VkMemoryGetFdInfoKHR structure

  • VUID-vkGetMemoryFdKHR-pFd-parameter
    pFd must be a valid pointer to an int value

Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_TOO_MANY_OBJECTS

  • VK_ERROR_OUT_OF_HOST_MEMORY

The VkMemoryGetFdInfoKHR structure is defined as:

// Provided by VK_KHR_external_memory_fd
typedef struct VkMemoryGetFdInfoKHR {
    VkStructureType                       sType;
    const void*                           pNext;
    VkDeviceMemory                        memory;
    VkExternalMemoryHandleTypeFlagBits    handleType;
} VkMemoryGetFdInfoKHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • memory is the memory object from which the handle will be exported.

  • handleType is a VkExternalMemoryHandleTypeFlagBits value specifying the type of handle requested.

The properties of the file descriptor exported depend on the value of handleType. See VkExternalMemoryHandleTypeFlagBits for a description of the properties of the defined external memory handle types.

Note

The size of the exported file may be larger than the size requested by VkMemoryAllocateInfo::allocationSize. If handleType is VK_EXTERNAL_MEMORY_HANDLE_TYPE_DMA_BUF_BIT_EXT, then the application can query the file’s actual size with lseek.
Valid Usage

  • VUID-VkMemoryGetFdInfoKHR-handleType-00671
    handleType must have been included in VkExportMemoryAllocateInfo::handleTypes when memory was created

  • VUID-VkMemoryGetFdInfoKHR-handleType-00672
    handleType must be VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_FD_BIT or VK_EXTERNAL_MEMORY_HANDLE_TYPE_DMA_BUF_BIT_EXT

Valid Usage (Implicit)

  • VUID-VkMemoryGetFdInfoKHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_MEMORY_GET_FD_INFO_KHR

  • VUID-VkMemoryGetFdInfoKHR-pNext-pNext
    pNext must be NULL

  • VUID-VkMemoryGetFdInfoKHR-memory-parameter
    memory must be a valid VkDeviceMemory handle

  • VUID-VkMemoryGetFdInfoKHR-handleType-parameter
    handleType must be a valid VkExternalMemoryHandleTypeFlagBits value

POSIX file descriptor memory handles compatible with Vulkan may also be created by non-Vulkan APIs using methods beyond the scope of this specification. To determine the correct parameters to use when importing such handles, call:

// Provided by VK_KHR_external_memory_fd
VkResult vkGetMemoryFdPropertiesKHR(
    VkDevice                                    device,
    VkExternalMemoryHandleTypeFlagBits          handleType,
    int                                         fd,
    VkMemoryFdPropertiesKHR*                    pMemoryFdProperties);

  • device is the logical device that will be importing fd.

  • handleType is a VkExternalMemoryHandleTypeFlagBits value specifying the type of the handle fd.

  • fd is the handle which will be imported.

  • pMemoryFdProperties is a pointer to a VkMemoryFdPropertiesKHR structure in which the properties of the handle fd are returned.

Valid Usage

  • VUID-vkGetMemoryFdPropertiesKHR-fd-00673
    fd must point to a valid POSIX file descriptor memory handle

  • VUID-vkGetMemoryFdPropertiesKHR-handleType-00674
    handleType must not be VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_FD_BIT

Valid Usage (Implicit)

  • VUID-vkGetMemoryFdPropertiesKHR-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkGetMemoryFdPropertiesKHR-handleType-parameter
    handleType must be a valid VkExternalMemoryHandleTypeFlagBits value

  • VUID-vkGetMemoryFdPropertiesKHR-pMemoryFdProperties-parameter
    pMemoryFdProperties must be a valid pointer to a VkMemoryFdPropertiesKHR structure

Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_INVALID_EXTERNAL_HANDLE

The VkMemoryFdPropertiesKHR structure returned is defined as:

// Provided by VK_KHR_external_memory_fd
typedef struct VkMemoryFdPropertiesKHR {
    VkStructureType    sType;
    void*              pNext;
    uint32_t           memoryTypeBits;
} VkMemoryFdPropertiesKHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • memoryTypeBits is a bitmask containing one bit set for every memory type which the specified file descriptor can be imported as.

Valid Usage (Implicit)

  • VUID-VkMemoryFdPropertiesKHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_MEMORY_FD_PROPERTIES_KHR

  • VUID-VkMemoryFdPropertiesKHR-pNext-pNext
    pNext must be NULL

11.2.6. Host External Memory

To import memory from a host pointer, add a VkImportMemoryHostPointerInfoEXT structure to the pNext chain of the VkMemoryAllocateInfo structure. The VkImportMemoryHostPointerInfoEXT structure is defined as:

// Provided by VK_EXT_external_memory_host
typedef struct VkImportMemoryHostPointerInfoEXT {
    VkStructureType                       sType;
    const void*                           pNext;
    VkExternalMemoryHandleTypeFlagBits    handleType;
    void*                                 pHostPointer;
} VkImportMemoryHostPointerInfoEXT;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • handleType is a VkExternalMemoryHandleTypeFlagBits value specifying the handle type.

  • pHostPointer is the host pointer to import from.

Importing memory from a host pointer shares ownership of the memory between the host and the Vulkan implementation. The application can continue to access the memory through the host pointer but it is the application’s responsibility to synchronize device and non-device access to the payload as defined in Host Access to Device Memory Objects.

Applications can import the same payload into multiple instances of Vulkan and multiple times into a given Vulkan instance. However, implementations may fail to import the same payload multiple times into a given physical device due to platform constraints.

Importing memory from a particular host pointer may not be possible due to additional platform-specific restrictions beyond the scope of this specification in which case the implementation must fail the memory import operation with the error code VK_ERROR_INVALID_EXTERNAL_HANDLE_KHR.

Whether device memory objects imported from a host pointer hold a reference to their payload is undefined. As such, the application must ensure that the imported memory range remains valid and accessible for the lifetime of the imported memory object.

Implementations may support importing host pointers for memory types which are not host-visible. In this case, after a successful call to vkAllocateMemory, the memory range imported from pHostPointer must not be accessed by the application until the VkDeviceMemory has been destroyed. Memory contents for the host memory becomes undefined on import, and is left undefined after the VkDeviceMemory has been destroyed. Applications must also not access host memory which is mapped to the same physical memory as pHostPointer, but mapped to a different host pointer while the VkDeviceMemory handle is valid. Implementations running on general-purpose operating systems should not support importing host pointers for memory types which are not host-visible.

Note

Using host pointers to back non-host visible allocations is a platform-specific use case, and applications should not attempt to do this unless instructed by the platform.
Valid Usage

  • VUID-VkImportMemoryHostPointerInfoEXT-handleType-01747
    If handleType is not 0, it must be supported for import, as reported in VkExternalMemoryProperties

  • VUID-VkImportMemoryHostPointerInfoEXT-handleType-01748
    If handleType is not 0, it must be VK_EXTERNAL_MEMORY_HANDLE_TYPE_HOST_ALLOCATION_BIT_EXT or VK_EXTERNAL_MEMORY_HANDLE_TYPE_HOST_MAPPED_FOREIGN_MEMORY_BIT_EXT

  • VUID-VkImportMemoryHostPointerInfoEXT-pHostPointer-01749
    pHostPointer must be a pointer aligned to an integer multiple of VkPhysicalDeviceExternalMemoryHostPropertiesEXT::minImportedHostPointerAlignment

  • VUID-VkImportMemoryHostPointerInfoEXT-handleType-01750
    If handleType is VK_EXTERNAL_MEMORY_HANDLE_TYPE_HOST_ALLOCATION_BIT_EXT, pHostPointer must be a pointer to allocationSize number of bytes of host memory, where allocationSize is the member of the VkMemoryAllocateInfo structure this structure is chained to

  • VUID-VkImportMemoryHostPointerInfoEXT-handleType-01751
    If handleType is VK_EXTERNAL_MEMORY_HANDLE_TYPE_HOST_MAPPED_FOREIGN_MEMORY_BIT_EXT, pHostPointer must be a pointer to allocationSize number of bytes of host mapped foreign memory, where allocationSize is the member of the VkMemoryAllocateInfo structure this structure is chained to

Valid Usage (Implicit)

  • VUID-VkImportMemoryHostPointerInfoEXT-sType-sType
    sType must be VK_STRUCTURE_TYPE_IMPORT_MEMORY_HOST_POINTER_INFO_EXT

  • VUID-VkImportMemoryHostPointerInfoEXT-handleType-parameter
    handleType must be a valid VkExternalMemoryHandleTypeFlagBits value

  • VUID-VkImportMemoryHostPointerInfoEXT-pHostPointer-parameter
    pHostPointer must be a pointer value

To determine the correct parameters to use when importing host pointers, call:

// Provided by VK_EXT_external_memory_host
VkResult vkGetMemoryHostPointerPropertiesEXT(
    VkDevice                                    device,
    VkExternalMemoryHandleTypeFlagBits          handleType,
    const void*                                 pHostPointer,
    VkMemoryHostPointerPropertiesEXT*           pMemoryHostPointerProperties);

  • device is the logical device that will be importing pHostPointer.

  • handleType is a VkExternalMemoryHandleTypeFlagBits value specifying the type of the handle pHostPointer.

  • pHostPointer is the host pointer to import from.

  • pMemoryHostPointerProperties is a pointer to a VkMemoryHostPointerPropertiesEXT structure in which the host pointer properties are returned.

Valid Usage

  • VUID-vkGetMemoryHostPointerPropertiesEXT-handleType-01752
    handleType must be VK_EXTERNAL_MEMORY_HANDLE_TYPE_HOST_ALLOCATION_BIT_EXT or VK_EXTERNAL_MEMORY_HANDLE_TYPE_HOST_MAPPED_FOREIGN_MEMORY_BIT_EXT

  • VUID-vkGetMemoryHostPointerPropertiesEXT-pHostPointer-01753
    pHostPointer must be a pointer aligned to an integer multiple of VkPhysicalDeviceExternalMemoryHostPropertiesEXT::minImportedHostPointerAlignment

  • VUID-vkGetMemoryHostPointerPropertiesEXT-handleType-01754
    If handleType is VK_EXTERNAL_MEMORY_HANDLE_TYPE_HOST_ALLOCATION_BIT_EXT, pHostPointer must be a pointer to host memory

  • VUID-vkGetMemoryHostPointerPropertiesEXT-handleType-01755
    If handleType is VK_EXTERNAL_MEMORY_HANDLE_TYPE_HOST_MAPPED_FOREIGN_MEMORY_BIT_EXT, pHostPointer must be a pointer to host mapped foreign memory

Valid Usage (Implicit)

  • VUID-vkGetMemoryHostPointerPropertiesEXT-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkGetMemoryHostPointerPropertiesEXT-handleType-parameter
    handleType must be a valid VkExternalMemoryHandleTypeFlagBits value

  • VUID-vkGetMemoryHostPointerPropertiesEXT-pHostPointer-parameter
    pHostPointer must be a pointer value

  • VUID-vkGetMemoryHostPointerPropertiesEXT-pMemoryHostPointerProperties-parameter
    pMemoryHostPointerProperties must be a valid pointer to a VkMemoryHostPointerPropertiesEXT structure

Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_INVALID_EXTERNAL_HANDLE

The VkMemoryHostPointerPropertiesEXT structure is defined as:

// Provided by VK_EXT_external_memory_host
typedef struct VkMemoryHostPointerPropertiesEXT {
    VkStructureType    sType;
    void*              pNext;
    uint32_t           memoryTypeBits;
} VkMemoryHostPointerPropertiesEXT;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • memoryTypeBits is a bitmask containing one bit set for every memory type which the specified host pointer can be imported as.

The value returned by memoryTypeBits should only include bits that identify memory types which are host visible. Implementations may include bits that identify memory types which are not host visible. Behavior for imported pointers of such types is defined by VkImportMemoryHostPointerInfoEXT.

Valid Usage (Implicit)

  • VUID-VkMemoryHostPointerPropertiesEXT-sType-sType
    sType must be VK_STRUCTURE_TYPE_MEMORY_HOST_POINTER_PROPERTIES_EXT

  • VUID-VkMemoryHostPointerPropertiesEXT-pNext-pNext
    pNext must be NULL

11.2.7. Android Hardware Buffer External Memory

To import memory created outside of the current Vulkan instance from an Android hardware buffer, add a VkImportAndroidHardwareBufferInfoANDROID structure to the pNext chain of the VkMemoryAllocateInfo structure. The VkImportAndroidHardwareBufferInfoANDROID structure is defined as:

// Provided by VK_ANDROID_external_memory_android_hardware_buffer
typedef struct VkImportAndroidHardwareBufferInfoANDROID {
    VkStructureType            sType;
    const void*                pNext;
    struct AHardwareBuffer*    buffer;
} VkImportAndroidHardwareBufferInfoANDROID;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • buffer is the Android hardware buffer to import.

If the vkAllocateMemory command succeeds, the implementation must acquire a reference to the imported hardware buffer, which it must release when the device memory object is freed. If the command fails, the implementation must not retain a reference.

Valid Usage

  • VUID-VkImportAndroidHardwareBufferInfoANDROID-buffer-01880
    If buffer is not NULL, Android hardware buffers must be supported for import, as reported by VkExternalImageFormatProperties or VkExternalBufferProperties

  • VUID-VkImportAndroidHardwareBufferInfoANDROID-buffer-01881
    If buffer is not NULL, it must be a valid Android hardware buffer object with AHardwareBuffer_Desc::usage compatible with Vulkan as described in Android Hardware Buffers

Valid Usage (Implicit)

  • VUID-VkImportAndroidHardwareBufferInfoANDROID-sType-sType
    sType must be VK_STRUCTURE_TYPE_IMPORT_ANDROID_HARDWARE_BUFFER_INFO_ANDROID

  • VUID-VkImportAndroidHardwareBufferInfoANDROID-buffer-parameter
    buffer must be a valid pointer to an AHardwareBuffer value

To export an Android hardware buffer referencing the payload of a Vulkan device memory object, call:

// Provided by VK_ANDROID_external_memory_android_hardware_buffer
VkResult vkGetMemoryAndroidHardwareBufferANDROID(
    VkDevice                                    device,
    const VkMemoryGetAndroidHardwareBufferInfoANDROID* pInfo,
    struct AHardwareBuffer**                    pBuffer);

  • device is the logical device that created the device memory being exported.

  • pInfo is a pointer to a VkMemoryGetAndroidHardwareBufferInfoANDROID structure containing parameters of the export operation.

  • pBuffer will return an Android hardware buffer referencing the payload of the device memory object.

Each call to vkGetMemoryAndroidHardwareBufferANDROID must return an Android hardware buffer with a new reference acquired in addition to the reference held by the VkDeviceMemory. To avoid leaking resources, the application must release the reference by calling AHardwareBuffer_release when it is no longer needed. When called with the same handle in VkMemoryGetAndroidHardwareBufferInfoANDROID::memory, vkGetMemoryAndroidHardwareBufferANDROID must return the same Android hardware buffer object. If the device memory was created by importing an Android hardware buffer, vkGetMemoryAndroidHardwareBufferANDROID must return that same Android hardware buffer object.

Valid Usage (Implicit)

  • VUID-vkGetMemoryAndroidHardwareBufferANDROID-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkGetMemoryAndroidHardwareBufferANDROID-pInfo-parameter
    pInfo must be a valid pointer to a valid VkMemoryGetAndroidHardwareBufferInfoANDROID structure

  • VUID-vkGetMemoryAndroidHardwareBufferANDROID-pBuffer-parameter
    pBuffer must be a valid pointer to a valid pointer to an AHardwareBuffer value

Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_TOO_MANY_OBJECTS

  • VK_ERROR_OUT_OF_HOST_MEMORY

The VkMemoryGetAndroidHardwareBufferInfoANDROID structure is defined as:

// Provided by VK_ANDROID_external_memory_android_hardware_buffer
typedef struct VkMemoryGetAndroidHardwareBufferInfoANDROID {
    VkStructureType    sType;
    const void*        pNext;
    VkDeviceMemory     memory;
} VkMemoryGetAndroidHardwareBufferInfoANDROID;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • memory is the memory object from which the Android hardware buffer will be exported.

Valid Usage

  • VUID-VkMemoryGetAndroidHardwareBufferInfoANDROID-handleTypes-01882
    VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID must have been included in VkExportMemoryAllocateInfo::handleTypes when memory was created

  • VUID-VkMemoryGetAndroidHardwareBufferInfoANDROID-pNext-01883
    If the pNext chain of the VkMemoryAllocateInfo used to allocate memory included a VkMemoryDedicatedAllocateInfo with non-NULL image member, then that image must already be bound to memory

Valid Usage (Implicit)

  • VUID-VkMemoryGetAndroidHardwareBufferInfoANDROID-sType-sType
    sType must be VK_STRUCTURE_TYPE_MEMORY_GET_ANDROID_HARDWARE_BUFFER_INFO_ANDROID

  • VUID-VkMemoryGetAndroidHardwareBufferInfoANDROID-pNext-pNext
    pNext must be NULL

  • VUID-VkMemoryGetAndroidHardwareBufferInfoANDROID-memory-parameter
    memory must be a valid VkDeviceMemory handle

To determine the memory parameters to use when importing an Android hardware buffer, call:

// Provided by VK_ANDROID_external_memory_android_hardware_buffer
VkResult vkGetAndroidHardwareBufferPropertiesANDROID(
    VkDevice                                    device,
    const struct AHardwareBuffer*               buffer,
    VkAndroidHardwareBufferPropertiesANDROID*   pProperties);

  • device is the logical device that will be importing buffer.

  • buffer is the Android hardware buffer which will be imported.

  • pProperties is a pointer to a VkAndroidHardwareBufferPropertiesANDROID structure in which the properties of buffer are returned.

Valid Usage

  • VUID-vkGetAndroidHardwareBufferPropertiesANDROID-buffer-01884
    buffer must be a valid Android hardware buffer object with at least one of the AHARDWAREBUFFER_USAGE_GPU_* flags in its AHardwareBuffer_Desc::usage

Valid Usage (Implicit)

  • VUID-vkGetAndroidHardwareBufferPropertiesANDROID-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkGetAndroidHardwareBufferPropertiesANDROID-buffer-parameter
    buffer must be a valid pointer to a valid AHardwareBuffer value

  • VUID-vkGetAndroidHardwareBufferPropertiesANDROID-pProperties-parameter
    pProperties must be a valid pointer to a VkAndroidHardwareBufferPropertiesANDROID structure

Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_INVALID_EXTERNAL_HANDLE_KHR

The VkAndroidHardwareBufferPropertiesANDROID structure returned is defined as:

// Provided by VK_ANDROID_external_memory_android_hardware_buffer
typedef struct VkAndroidHardwareBufferPropertiesANDROID {
    VkStructureType    sType;
    void*              pNext;
    VkDeviceSize       allocationSize;
    uint32_t           memoryTypeBits;
} VkAndroidHardwareBufferPropertiesANDROID;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • allocationSize is the size of the external memory

  • memoryTypeBits is a bitmask containing one bit set for every memory type which the specified Android hardware buffer can be imported as.

Valid Usage (Implicit)

To obtain format properties of an Android hardware buffer, include a VkAndroidHardwareBufferFormatPropertiesANDROID structure in the pNext chain of the VkAndroidHardwareBufferPropertiesANDROID structure passed to vkGetAndroidHardwareBufferPropertiesANDROID. This structure is defined as:

// Provided by VK_ANDROID_external_memory_android_hardware_buffer
typedef struct VkAndroidHardwareBufferFormatPropertiesANDROID {
    VkStructureType                  sType;
    void*                            pNext;
    VkFormat                         format;
    uint64_t                         externalFormat;
    VkFormatFeatureFlags             formatFeatures;
    VkComponentMapping               samplerYcbcrConversionComponents;
    VkSamplerYcbcrModelConversion    suggestedYcbcrModel;
    VkSamplerYcbcrRange              suggestedYcbcrRange;
    VkChromaLocation                 suggestedXChromaOffset;
    VkChromaLocation                 suggestedYChromaOffset;
} VkAndroidHardwareBufferFormatPropertiesANDROID;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • format is the Vulkan format corresponding to the Android hardware buffer’s format, or VK_FORMAT_UNDEFINED if there is not an equivalent Vulkan format.

  • externalFormat is an implementation-defined external format identifier for use with VkExternalFormatANDROID. It must not be zero.

  • formatFeatures describes the capabilities of this external format when used with an image bound to memory imported from buffer.

  • samplerYcbcrConversionComponents is the component swizzle that should be used in VkSamplerYcbcrConversionCreateInfo.

  • suggestedYcbcrModel is a suggested color model to use in the VkSamplerYcbcrConversionCreateInfo.

  • suggestedYcbcrRange is a suggested numerical value range to use in VkSamplerYcbcrConversionCreateInfo.

  • suggestedXChromaOffset is a suggested X chroma offset to use in VkSamplerYcbcrConversionCreateInfo.

  • suggestedYChromaOffset is a suggested Y chroma offset to use in VkSamplerYcbcrConversionCreateInfo.

If the Android hardware buffer has one of the formats listed in the Format Equivalence table, then format must have the equivalent Vulkan format listed in the table. Otherwise, format may be VK_FORMAT_UNDEFINED, indicating the Android hardware buffer can only be used with an external format.

The formatFeatures member must include VK_FORMAT_FEATURE_SAMPLED_IMAGE_BIT and at least one of VK_FORMAT_FEATURE_MIDPOINT_CHROMA_SAMPLES_BIT or VK_FORMAT_FEATURE_COSITED_CHROMA_SAMPLES_BIT, and should include VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT and VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_LINEAR_FILTER_BIT.

Note

The formatFeatures member only indicates the features available when using an external-format image created from the Android hardware buffer. Images from Android hardware buffers with a format other than VK_FORMAT_UNDEFINED are subject to the format capabilities obtained from vkGetPhysicalDeviceFormatProperties2, and vkGetPhysicalDeviceImageFormatProperties2 with appropriate parameters. These sets of features are independent of each other, e.g. the external format will support sampler Y′CBCR conversion even if the non-external format does not, and rendering directly to the external format will not be supported even if the non-external format does support this.

Android hardware buffers with the same external format must have the same support for VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT, VK_FORMAT_FEATURE_MIDPOINT_CHROMA_SAMPLES_BIT, VK_FORMAT_FEATURE_COSITED_CHROMA_SAMPLES_BIT, VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_LINEAR_FILTER_BIT, VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_SEPARATE_RECONSTRUCTION_FILTER_BIT, and VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_CHROMA_RECONSTRUCTION_EXPLICIT_FORCEABLE_BIT. in formatFeatures. Other format features may differ between Android hardware buffers that have the same external format. This allows applications to use the same VkSamplerYcbcrConversion object (and samplers and pipelines created from them) for any Android hardware buffers that have the same external format.

If format is not VK_FORMAT_UNDEFINED, then the value of samplerYcbcrConversionComponents must be valid when used as the components member of VkSamplerYcbcrConversionCreateInfo with that format. If format is VK_FORMAT_UNDEFINED, all members of samplerYcbcrConversionComponents must be the identity swizzle.

Implementations may not always be able to determine the color model, numerical range, or chroma offsets of the image contents, so the values in VkAndroidHardwareBufferFormatPropertiesANDROID are only suggestions. Applications should treat these values as sensible defaults to use in the absence of more reliable information obtained through some other means. If the underlying physical device is also usable via OpenGL ES with the GL_OES_EGL_image_external extension, the implementation should suggest values that will produce similar sampled values as would be obtained by sampling the same external image via samplerExternalOES in OpenGL ES using equivalent sampler parameters.

Note

Since GL_OES_EGL_image_external does not require the same sampling and conversion calculations as Vulkan does, achieving identical results between APIs may not be possible on some implementations.
Valid Usage (Implicit)

  • VUID-VkAndroidHardwareBufferFormatPropertiesANDROID-sType-sType
    sType must be VK_STRUCTURE_TYPE_ANDROID_HARDWARE_BUFFER_FORMAT_PROPERTIES_ANDROID

The format properties of an Android hardware buffer can be obtained by including a VkAndroidHardwareBufferFormatProperties2ANDROID structure in the pNext chain of the VkAndroidHardwareBufferPropertiesANDROID structure passed to vkGetAndroidHardwareBufferPropertiesANDROID. This structure is defined as:

// Provided by VK_ANDROID_external_memory_android_hardware_buffer with VK_KHR_format_feature_flags2 or VK_VERSION_1_3
typedef struct VkAndroidHardwareBufferFormatProperties2ANDROID {
    VkStructureType                  sType;
    void*                            pNext;
    VkFormat                         format;
    uint64_t                         externalFormat;
    VkFormatFeatureFlags2            formatFeatures;
    VkComponentMapping               samplerYcbcrConversionComponents;
    VkSamplerYcbcrModelConversion    suggestedYcbcrModel;
    VkSamplerYcbcrRange              suggestedYcbcrRange;
    VkChromaLocation                 suggestedXChromaOffset;
    VkChromaLocation                 suggestedYChromaOffset;
} VkAndroidHardwareBufferFormatProperties2ANDROID;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • format is the Vulkan format corresponding to the Android hardware buffer’s format, or VK_FORMAT_UNDEFINED if there is not an equivalent Vulkan format.

  • externalFormat is an implementation-defined external format identifier for use with VkExternalFormatANDROID. It must not be zero.

  • formatFeatures describes the capabilities of this external format when used with an image bound to memory imported from buffer.

  • samplerYcbcrConversionComponents is the component swizzle that should be used in VkSamplerYcbcrConversionCreateInfo.

  • suggestedYcbcrModel is a suggested color model to use in the VkSamplerYcbcrConversionCreateInfo.

  • suggestedYcbcrRange is a suggested numerical value range to use in VkSamplerYcbcrConversionCreateInfo.

  • suggestedXChromaOffset is a suggested X chroma offset to use in VkSamplerYcbcrConversionCreateInfo.

  • suggestedYChromaOffset is a suggested Y chroma offset to use in VkSamplerYcbcrConversionCreateInfo.

The bits reported in formatFeatures must include the bits reported in the corresponding fields of VkAndroidHardwareBufferFormatPropertiesANDROID::formatFeatures.

Valid Usage (Implicit)

  • VUID-VkAndroidHardwareBufferFormatProperties2ANDROID-sType-sType
    sType must be VK_STRUCTURE_TYPE_ANDROID_HARDWARE_BUFFER_FORMAT_PROPERTIES_2_ANDROID

The VkAndroidHardwareBufferFormatResolvePropertiesANDROID structure is defined as:

// Provided by VK_ANDROID_external_format_resolve
typedef struct VkAndroidHardwareBufferFormatResolvePropertiesANDROID {
    VkStructureType    sType;
    void*              pNext;
    VkFormat           colorAttachmentFormat;
} VkAndroidHardwareBufferFormatResolvePropertiesANDROID;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • colorAttachmentFormat is a VkFormat specifying the format of color attachment images that must be used for color attachments when resolving to the specified external format. If the implementation supports external format resolves for the specified external format, this value will be set to a color format supporting the VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT in VkFormatProperties::optimalTilingFeatures as returned by vkGetPhysicalDeviceFormatProperties with format equal to colorAttachmentFormat If external format resolves are not supported, this value will be set to VK_FORMAT_UNDEFINED.

Any Android hardware buffer created with the GRALLOC_USAGE_HW_RENDER flag must be renderable in some way in Vulkan, either:

Valid Usage (Implicit)

  • VUID-VkAndroidHardwareBufferFormatResolvePropertiesANDROID-sType-sType
    sType must be VK_STRUCTURE_TYPE_ANDROID_HARDWARE_BUFFER_FORMAT_RESOLVE_PROPERTIES_ANDROID

11.2.8. Remote Device External Memory

To export an address representing the payload of a Vulkan device memory object accessible by remote devices, call:

// Provided by VK_NV_external_memory_rdma
VkResult vkGetMemoryRemoteAddressNV(
    VkDevice                                    device,
    const VkMemoryGetRemoteAddressInfoNV*       pMemoryGetRemoteAddressInfo,
    VkRemoteAddressNV*                          pAddress);

  • device is the logical device that created the device memory being exported.

  • pMemoryGetRemoteAddressInfo is a pointer to a VkMemoryGetRemoteAddressInfoNV structure containing parameters of the export operation.

  • pAddress is a pointer to a VkRemoteAddressNV value in which an address representing the payload of the device memory object is returned.

More communication may be required between the kernel-mode drivers of the devices involved. This information is out of scope of this documentation and should be requested from the vendors of the devices.

Valid Usage (Implicit)

  • VUID-vkGetMemoryRemoteAddressNV-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkGetMemoryRemoteAddressNV-pMemoryGetRemoteAddressInfo-parameter
    pMemoryGetRemoteAddressInfo must be a valid pointer to a valid VkMemoryGetRemoteAddressInfoNV structure

  • VUID-vkGetMemoryRemoteAddressNV-pAddress-parameter
    pAddress must be a valid pointer to a VkRemoteAddressNV value

Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_INVALID_EXTERNAL_HANDLE

The VkMemoryGetRemoteAddressInfoNV structure is defined as:

// Provided by VK_NV_external_memory_rdma
typedef struct VkMemoryGetRemoteAddressInfoNV {
    VkStructureType                       sType;
    const void*                           pNext;
    VkDeviceMemory                        memory;
    VkExternalMemoryHandleTypeFlagBits    handleType;
} VkMemoryGetRemoteAddressInfoNV;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • memory is the memory object from which the remote accessible address will be exported.

  • handleType is the type of handle requested.

Valid Usage

  • VUID-VkMemoryGetRemoteAddressInfoNV-handleType-04966
    handleType must have been included in VkExportMemoryAllocateInfo::handleTypes when memory was created

Valid Usage (Implicit)

  • VUID-VkMemoryGetRemoteAddressInfoNV-sType-sType
    sType must be VK_STRUCTURE_TYPE_MEMORY_GET_REMOTE_ADDRESS_INFO_NV

  • VUID-VkMemoryGetRemoteAddressInfoNV-pNext-pNext
    pNext must be NULL

  • VUID-VkMemoryGetRemoteAddressInfoNV-memory-parameter
    memory must be a valid VkDeviceMemory handle

  • VUID-VkMemoryGetRemoteAddressInfoNV-handleType-parameter
    handleType must be a valid VkExternalMemoryHandleTypeFlagBits value

VkRemoteAddressNV represents an address of a memory object accessible by remote devices, as returned in vkGetMemoryRemoteAddressNV::pAddress.

// Provided by VK_NV_external_memory_rdma
typedef void* VkRemoteAddressNV;

11.2.9. Fuchsia External Memory

On Fuchsia, when allocating memory that may be imported from another device, process or Vulkan instance, add a VkImportMemoryZirconHandleInfoFUCHSIA structure to the pNext chain of the VkMemoryAllocateInfo structure.

External memory on Fuchsia is imported and exported using VMO handles of type zx_handle_t. VMO handles to external memory are canonically obtained from Fuchsia’s Sysmem service or from syscalls such as zx_vmo_create(). VMO handles for import can also be obtained by exporting them from another Vulkan instance as described in exporting fuchsia device memory.

Importing VMO handles to the Vulkan instance transfers ownership of the handle to the instance from the application. The application must not perform any operations on the handle after successful import.

Applications can import the same underlying memory into multiple instances of Vulkan, into the same instance from which it was exported, and multiple times into a given Vulkan instance. In all cases, each import operation must create a distinct VkDeviceMemory object.

Importing Fuchsia External Memory

The VkImportMemoryZirconHandleInfoFUCHSIA structure is defined as:

// Provided by VK_FUCHSIA_external_memory
typedef struct VkImportMemoryZirconHandleInfoFUCHSIA {
    VkStructureType                       sType;
    const void*                           pNext;
    VkExternalMemoryHandleTypeFlagBits    handleType;
    zx_handle_t                           handle;
} VkImportMemoryZirconHandleInfoFUCHSIA;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • handleType is a VkExternalMemoryHandleTypeFlagBits value specifying the type of handle.

  • handle is a zx_handle_t (Zircon) handle to the external memory.

Valid Usage

  • VUID-VkImportMemoryZirconHandleInfoFUCHSIA-handleType-04771
    handleType must be VK_EXTERNAL_MEMORY_HANDLE_TYPE_ZIRCON_VMO_BIT_FUCHSIA

  • VUID-VkImportMemoryZirconHandleInfoFUCHSIA-handle-04772
    handle must be a valid VMO handle

Valid Usage (Implicit)

  • VUID-VkImportMemoryZirconHandleInfoFUCHSIA-sType-sType
    sType must be VK_STRUCTURE_TYPE_IMPORT_MEMORY_ZIRCON_HANDLE_INFO_FUCHSIA

  • VUID-VkImportMemoryZirconHandleInfoFUCHSIA-handleType-parameter
    If handleType is not 0, handleType must be a valid VkExternalMemoryHandleTypeFlagBits value

To obtain the memoryTypeIndex for the VkMemoryAllocateInfo structure, call vkGetMemoryZirconHandlePropertiesFUCHSIA:

// Provided by VK_FUCHSIA_external_memory
VkResult vkGetMemoryZirconHandlePropertiesFUCHSIA(
    VkDevice                                    device,
    VkExternalMemoryHandleTypeFlagBits          handleType,
    zx_handle_t                                 zirconHandle,
    VkMemoryZirconHandlePropertiesFUCHSIA*      pMemoryZirconHandleProperties);
Valid Usage

  • VUID-vkGetMemoryZirconHandlePropertiesFUCHSIA-handleType-04773
    handleType must be VK_EXTERNAL_MEMORY_HANDLE_TYPE_ZIRCON_VMO_BIT_FUCHSIA

  • VUID-vkGetMemoryZirconHandlePropertiesFUCHSIA-zirconHandle-04774
    zirconHandle must reference a valid VMO

Valid Usage (Implicit)

  • VUID-vkGetMemoryZirconHandlePropertiesFUCHSIA-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkGetMemoryZirconHandlePropertiesFUCHSIA-handleType-parameter
    handleType must be a valid VkExternalMemoryHandleTypeFlagBits value

  • VUID-vkGetMemoryZirconHandlePropertiesFUCHSIA-pMemoryZirconHandleProperties-parameter
    pMemoryZirconHandleProperties must be a valid pointer to a VkMemoryZirconHandlePropertiesFUCHSIA structure

Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_INVALID_EXTERNAL_HANDLE

The VkMemoryZirconHandlePropertiesFUCHSIA structure is defined as:

// Provided by VK_FUCHSIA_external_memory
typedef struct VkMemoryZirconHandlePropertiesFUCHSIA {
    VkStructureType    sType;
    void*              pNext;
    uint32_t           memoryTypeBits;
} VkMemoryZirconHandlePropertiesFUCHSIA;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • memoryTypeBits a bitmask containing one bit set for every memory type which the specified handle can be imported as.

Valid Usage (Implicit)

  • VUID-VkMemoryZirconHandlePropertiesFUCHSIA-sType-sType
    sType must be VK_STRUCTURE_TYPE_MEMORY_ZIRCON_HANDLE_PROPERTIES_FUCHSIA

  • VUID-VkMemoryZirconHandlePropertiesFUCHSIA-pNext-pNext
    pNext must be NULL

With pMemoryZirconHandleProperties now successfully populated by vkGetMemoryZirconHandlePropertiesFUCHSIA, assign the VkMemoryAllocateInfo memoryTypeIndex field to a memory type which has a bit set in the VkMemoryZirconHandlePropertiesFUCHSIA memoryTypeBits field.

Exporting Fuchsia Device Memory

Similar to importing, exporting a VMO handle from Vulkan transfers ownership of the handle from the Vulkan instance to the application. The application is responsible for closing the handle with zx_handle_close() when it is no longer in use.

To export device memory as a Zircon handle that can be used by another instance, device, or process, retrieve the handle to the VkDeviceMemory using the command:

// Provided by VK_FUCHSIA_external_memory
VkResult vkGetMemoryZirconHandleFUCHSIA(
    VkDevice                                    device,
    const VkMemoryGetZirconHandleInfoFUCHSIA*   pGetZirconHandleInfo,
    zx_handle_t*                                pZirconHandle);
Valid Usage (Implicit)

  • VUID-vkGetMemoryZirconHandleFUCHSIA-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkGetMemoryZirconHandleFUCHSIA-pGetZirconHandleInfo-parameter
    pGetZirconHandleInfo must be a valid pointer to a valid VkMemoryGetZirconHandleInfoFUCHSIA structure

  • VUID-vkGetMemoryZirconHandleFUCHSIA-pZirconHandle-parameter
    pZirconHandle must be a valid pointer to a zx_handle_t value

Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_TOO_MANY_OBJECTS

  • VK_ERROR_OUT_OF_HOST_MEMORY

VkMemoryGetZirconHandleInfoFUCHSIA is defined as:

// Provided by VK_FUCHSIA_external_memory
typedef struct VkMemoryGetZirconHandleInfoFUCHSIA {
    VkStructureType                       sType;
    const void*                           pNext;
    VkDeviceMemory                        memory;
    VkExternalMemoryHandleTypeFlagBits    handleType;
} VkMemoryGetZirconHandleInfoFUCHSIA;
Valid Usage

  • VUID-VkMemoryGetZirconHandleInfoFUCHSIA-handleType-04775
    handleType must be VK_EXTERNAL_MEMORY_HANDLE_TYPE_ZIRCON_VMO_BIT_FUCHSIA

  • VUID-VkMemoryGetZirconHandleInfoFUCHSIA-handleType-04776
    handleType must have been included in the handleTypes field of the VkExportMemoryAllocateInfo structure when the external memory was allocated

Valid Usage (Implicit)

  • VUID-VkMemoryGetZirconHandleInfoFUCHSIA-sType-sType
    sType must be VK_STRUCTURE_TYPE_MEMORY_GET_ZIRCON_HANDLE_INFO_FUCHSIA

  • VUID-VkMemoryGetZirconHandleInfoFUCHSIA-pNext-pNext
    pNext must be NULL

  • VUID-VkMemoryGetZirconHandleInfoFUCHSIA-memory-parameter
    memory must be a valid VkDeviceMemory handle

  • VUID-VkMemoryGetZirconHandleInfoFUCHSIA-handleType-parameter
    handleType must be a valid VkExternalMemoryHandleTypeFlagBits value

With the result pZirconHandle now obtained, the memory properties for the handle can be retrieved using vkGetMemoryZirconHandlePropertiesFUCHSIA as documented above substituting the dereferenced, retrieved pZirconHandle in for the zirconHandle argument.

11.2.10. Metal Objects

A Vulkan implementation that is layered on top of Metal on Apple device platform, and implements the VK_EXT_metal_objects extension, supports the ability to import and export the underlying Metal objects associated with specific Vulkan objects.

The underlying Metal objects associated with certain Vulkan objects can be exported from those Vulkan objects using the pNext chain of the VkExportMetalObjectsInfoEXT parameter of the vkExportMetalObjectsEXT command.

An VkDeviceMemory object can be allocated on an existing MTLBuffer object, by including the MTLBuffer object in a VkImportMetalBufferInfoEXT structure in the pNext chain of the VkMemoryAllocateInfo structure in the vkAllocateMemory command.

A new VkImage object can be created on an existing IOSurface object, or one or more existing Metal MTLTexture objects, by including those Metal objects in either VkImportMetalIOSurfaceInfoEXT or VkImportMetalTextureInfoEXT structures in the pNext chain of the VkImageCreateInfo structure in the vkCreateImage command.

To export Metal objects from Vulkan objects, the application must first indicate the intention to do so during the creation of the Vulkan object, by including one or more VkExportMetalObjectCreateInfoEXT structures in the pNext chain of the VkInstanceCreateInfo, VkMemoryAllocateInfo, VkImageCreateInfo, VkImageViewCreateInfo, VkBufferViewCreateInfo, VkSemaphoreCreateInfo, or VkEventCreateInfo, in the corresponding Vulkan object creation command.

The VkExportMetalObjectCreateInfoEXT structure is defined as:

// Provided by VK_EXT_metal_objects
typedef struct VkExportMetalObjectCreateInfoEXT {
    VkStructureType                       sType;
    const void*                           pNext;
    VkExportMetalObjectTypeFlagBitsEXT    exportObjectType;
} VkExportMetalObjectCreateInfoEXT;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • exportObjectType is a VkExportMetalObjectTypeFlagBitsEXT indicating the type of Metal object that the application may request to be exported from the Vulkan object.

Valid Usage (Implicit)

  • VUID-VkExportMetalObjectCreateInfoEXT-sType-sType
    sType must be VK_STRUCTURE_TYPE_EXPORT_METAL_OBJECT_CREATE_INFO_EXT

  • VUID-VkExportMetalObjectCreateInfoEXT-exportObjectType-parameter
    If exportObjectType is not 0, exportObjectType must be a valid VkExportMetalObjectTypeFlagBitsEXT value

Bits which indicate the types of Metal objects that may be exported from a corresponding Vulkan object are:

// Provided by VK_EXT_metal_objects
typedef enum VkExportMetalObjectTypeFlagBitsEXT {
    VK_EXPORT_METAL_OBJECT_TYPE_METAL_DEVICE_BIT_EXT = 0x00000001,
    VK_EXPORT_METAL_OBJECT_TYPE_METAL_COMMAND_QUEUE_BIT_EXT = 0x00000002,
    VK_EXPORT_METAL_OBJECT_TYPE_METAL_BUFFER_BIT_EXT = 0x00000004,
    VK_EXPORT_METAL_OBJECT_TYPE_METAL_TEXTURE_BIT_EXT = 0x00000008,
    VK_EXPORT_METAL_OBJECT_TYPE_METAL_IOSURFACE_BIT_EXT = 0x00000010,
    VK_EXPORT_METAL_OBJECT_TYPE_METAL_SHARED_EVENT_BIT_EXT = 0x00000020,
} VkExportMetalObjectTypeFlagBitsEXT;

  • VK_EXPORT_METAL_OBJECT_TYPE_METAL_DEVICE_BIT_EXT indicates a Metal MTLDevice may be exported.

  • VK_EXPORT_METAL_OBJECT_TYPE_METAL_COMMAND_QUEUE_BIT_EXT indicates a Metal MTLCommandQueue may be exported.

  • VK_EXPORT_METAL_OBJECT_TYPE_METAL_BUFFER_BIT_EXT indicates a Metal MTLBuffer may be exported.

  • VK_EXPORT_METAL_OBJECT_TYPE_METAL_TEXTURE_BIT_EXT indicates a Metal MTLTexture may be exported.

  • VK_EXPORT_METAL_OBJECT_TYPE_METAL_IOSURFACE_BIT_EXT indicates a Metal IOSurface may be exported.

  • VK_EXPORT_METAL_OBJECT_TYPE_METAL_SHARED_EVENT_BIT_EXT indicates a Metal MTLSharedEvent may be exported.

// Provided by VK_EXT_metal_objects
typedef VkFlags VkExportMetalObjectTypeFlagsEXT;

VkExportMetalObjectTypeFlagsEXT is a bitmask type for setting a mask of zero or more VkExportMetalObjectTypeFlagBitsEXT.

To export Metal objects that underlie Vulkan objects, call:

// Provided by VK_EXT_metal_objects
void vkExportMetalObjectsEXT(
    VkDevice                                    device,
    VkExportMetalObjectsInfoEXT*                pMetalObjectsInfo);

  • device is the device that created the Vulkan objects.

  • pMetalObjectsInfo is a pointer to a VkExportMetalObjectsInfoEXT structure whose pNext chain contains structures, each identifying a Vulkan object and providing a pointer through which the Metal object will be returned.

Valid Usage (Implicit)

  • VUID-vkExportMetalObjectsEXT-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkExportMetalObjectsEXT-pMetalObjectsInfo-parameter
    pMetalObjectsInfo must be a valid pointer to a VkExportMetalObjectsInfoEXT structure

The VkExportMetalObjectsInfoEXT structure is defined as:

// Provided by VK_EXT_metal_objects
typedef struct VkExportMetalObjectsInfoEXT {
    VkStructureType    sType;
    const void*        pNext;
} VkExportMetalObjectsInfoEXT;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

Valid Usage
Valid Usage (Implicit)

To export the Metal MTLDevice object underlying the VkPhysicalDevice associated with a VkDevice object, include a VkExportMetalDeviceInfoEXT structure in the pNext chain of the pMetalObjectsInfo parameter of a vkExportMetalObjectsEXT call.

The VkExportMetalDeviceInfoEXT structure is defined as:

// Provided by VK_EXT_metal_objects
typedef struct VkExportMetalDeviceInfoEXT {
    VkStructureType    sType;
    const void*        pNext;
    MTLDevice_id       mtlDevice;
} VkExportMetalDeviceInfoEXT;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • mtlDevice is the Metal id<MTLDevice> object underlying the VkPhysicalDevice associated with the VkDevice object identified in the call. The implementation will return the MTLDevice in this member, or it will return NULL if no MTLDevice could be found underlying the VkPhysicalDevice object.

Valid Usage (Implicit)

  • VUID-VkExportMetalDeviceInfoEXT-sType-sType
    sType must be VK_STRUCTURE_TYPE_EXPORT_METAL_DEVICE_INFO_EXT

The type id<MTLDevice> is defined in Apple’s Metal framework, but to remove an unnecessary compile time dependency, an incomplete type definition of MTLDevice_id is provided in the Vulkan headers:

// Provided by VK_EXT_metal_objects
#ifdef __OBJC__
@protocol MTLDevice;
typedef __unsafe_unretained id<MTLDevice> MTLDevice_id;
#else
typedef void* MTLDevice_id;
#endif

To export the Metal MTLCommandQueue object underlying a VkQueue object, include a VkExportMetalCommandQueueInfoEXT structure in the pNext chain of the pMetalObjectsInfo parameter of a vkExportMetalObjectsEXT call.

The VkExportMetalCommandQueueInfoEXT structure is defined as:

// Provided by VK_EXT_metal_objects
typedef struct VkExportMetalCommandQueueInfoEXT {
    VkStructureType       sType;
    const void*           pNext;
    VkQueue               queue;
    MTLCommandQueue_id    mtlCommandQueue;
} VkExportMetalCommandQueueInfoEXT;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • queue is a VkQueue.

  • mtlCommandQueue is the Metal id<MTLCommandQueue> object underlying the VkQueue object in queue. The implementation will return the MTLCommandQueue in this member, or it will return NULL if no MTLCommandQueue could be found underlying the VkQueue object.

Valid Usage (Implicit)

  • VUID-VkExportMetalCommandQueueInfoEXT-sType-sType
    sType must be VK_STRUCTURE_TYPE_EXPORT_METAL_COMMAND_QUEUE_INFO_EXT

  • VUID-VkExportMetalCommandQueueInfoEXT-queue-parameter
    queue must be a valid VkQueue handle

The type id<MTLCommandQueue> is defined in Apple’s Metal framework, but to remove an unnecessary compile time dependency, an incomplete type definition of MTLCommandQueue_id is provided in the Vulkan headers:

// Provided by VK_EXT_metal_objects
#ifdef __OBJC__
@protocol MTLCommandQueue;
typedef __unsafe_unretained id<MTLCommandQueue> MTLCommandQueue_id;
#else
typedef void* MTLCommandQueue_id;
#endif

To export the Metal MTLBuffer object underlying a VkDeviceMemory object, include a VkExportMetalBufferInfoEXT structure in the pNext chain of the pMetalObjectsInfo parameter of a vkExportMetalObjectsEXT call.

The VkExportMetalBufferInfoEXT structure is defined as:

// Provided by VK_EXT_metal_objects
typedef struct VkExportMetalBufferInfoEXT {
    VkStructureType    sType;
    const void*        pNext;
    VkDeviceMemory     memory;
    MTLBuffer_id       mtlBuffer;
} VkExportMetalBufferInfoEXT;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • memory is a VkDeviceMemory.

  • mtlBuffer is the Metal id<MTLBuffer> object underlying the VkDeviceMemory object in memory. The implementation will return the MTLBuffer in this member, or it will return NULL if no MTLBuffer could be found underlying the VkDeviceMemory object.

Valid Usage (Implicit)

  • VUID-VkExportMetalBufferInfoEXT-sType-sType
    sType must be VK_STRUCTURE_TYPE_EXPORT_METAL_BUFFER_INFO_EXT

  • VUID-VkExportMetalBufferInfoEXT-memory-parameter
    memory must be a valid VkDeviceMemory handle

To import a Metal MTLBuffer object to underlie a VkDeviceMemory object, include a VkImportMetalBufferInfoEXT structure in the pNext chain of the VkMemoryAllocateInfo structure in a vkAllocateMemory command.

The VkImportMetalBufferInfoEXT structure is defined as:

// Provided by VK_EXT_metal_objects
typedef struct VkImportMetalBufferInfoEXT {
    VkStructureType    sType;
    const void*        pNext;
    MTLBuffer_id       mtlBuffer;
} VkImportMetalBufferInfoEXT;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • mtlBuffer is the Metal id<MTLBuffer> object that is to underlie the VkDeviceMemory.

The application must ensure that the configuration of the id<MTLBuffer> object is compatible with the configuration of the VkDeviceMemory. Failure to do so results in undefined behavior.

Valid Usage (Implicit)

  • VUID-VkImportMetalBufferInfoEXT-sType-sType
    sType must be VK_STRUCTURE_TYPE_IMPORT_METAL_BUFFER_INFO_EXT

The type id<MTLBuffer> is defined in Apple’s Metal framework, but to remove an unnecessary compile time dependency, an incomplete type definition of MTLBuffer_id is provided in the Vulkan headers:

// Provided by VK_EXT_metal_objects
#ifdef __OBJC__
@protocol MTLBuffer;
typedef __unsafe_unretained id<MTLBuffer> MTLBuffer_id;
#else
typedef void* MTLBuffer_id;
#endif

To export a Metal MTLTexture object underlying a VkImage, VkImageView, or VkBufferView object, include a VkExportMetalTextureInfoEXT structure in the pNext chain of the pMetalObjectsInfo parameter of a vkExportMetalObjectsEXT call.

The VkExportMetalTextureInfoEXT structure is defined as:

// Provided by VK_EXT_metal_objects
typedef struct VkExportMetalTextureInfoEXT {
    VkStructureType          sType;
    const void*              pNext;
    VkImage                  image;
    VkImageView              imageView;
    VkBufferView             bufferView;
    VkImageAspectFlagBits    plane;
    MTLTexture_id            mtlTexture;
} VkExportMetalTextureInfoEXT;
Valid Usage (Implicit)

  • VUID-VkExportMetalTextureInfoEXT-sType-sType
    sType must be VK_STRUCTURE_TYPE_EXPORT_METAL_TEXTURE_INFO_EXT

  • VUID-VkExportMetalTextureInfoEXT-image-parameter
    If image is not VK_NULL_HANDLE, image must be a valid VkImage handle

  • VUID-VkExportMetalTextureInfoEXT-imageView-parameter
    If imageView is not VK_NULL_HANDLE, imageView must be a valid VkImageView handle

  • VUID-VkExportMetalTextureInfoEXT-bufferView-parameter
    If bufferView is not VK_NULL_HANDLE, bufferView must be a valid VkBufferView handle

  • VUID-VkExportMetalTextureInfoEXT-plane-parameter
    plane must be a valid VkImageAspectFlagBits value

  • VUID-VkExportMetalTextureInfoEXT-commonparent
    Each of bufferView, image, and imageView that are valid handles of non-ignored parameters must have been created, allocated, or retrieved from the same VkDevice

To import one or more existing Metal MTLTexture objects to underlie a VkImage object, include one or more VkImportMetalTextureInfoEXT structures in the pNext chain of the VkImageCreateInfo structure in a vkCreateImage command.

The VkImportMetalTextureInfoEXT structure is defined as:

// Provided by VK_EXT_metal_objects
typedef struct VkImportMetalTextureInfoEXT {
    VkStructureType          sType;
    const void*              pNext;
    VkImageAspectFlagBits    plane;
    MTLTexture_id            mtlTexture;
} VkImportMetalTextureInfoEXT;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • plane indicates the plane of the VkImage that the id<MTLTexture> object should be attached to.

  • mtlTexture is a the Metal id<MTLTexture> object that is to underlie the VkImage plane.

The pNext chain must include one VkImportMetalTextureInfoEXT structure for each plane in the VkImage. The application must ensure that the configuration of the Metal id<MTLTexture> objects are compatible with the configuration of the VkImage. Failure to do so results in undefined behavior.

Valid Usage (Implicit)

  • VUID-VkImportMetalTextureInfoEXT-sType-sType
    sType must be VK_STRUCTURE_TYPE_IMPORT_METAL_TEXTURE_INFO_EXT

  • VUID-VkImportMetalTextureInfoEXT-plane-parameter
    plane must be a valid VkImageAspectFlagBits value

The type id<MTLTexture> is defined in Apple’s Metal framework, but to remove an unnecessary compile time dependency, an incomplete type definition of MTLTexture_id is provided in the Vulkan headers:

// Provided by VK_EXT_metal_objects
#ifdef __OBJC__
@protocol MTLTexture;
typedef __unsafe_unretained id<MTLTexture> MTLTexture_id;
#else
typedef void* MTLTexture_id;
#endif

To export the Metal IOSurfaceRef object underlying a VkImage object, include a VkExportMetalIOSurfaceInfoEXT structure in the pNext chain of the pMetalObjectsInfo parameter of a vkExportMetalObjectsEXT call.

The VkExportMetalIOSurfaceInfoEXT structure is defined as:

// Provided by VK_EXT_metal_objects
typedef struct VkExportMetalIOSurfaceInfoEXT {
    VkStructureType    sType;
    const void*        pNext;
    VkImage            image;
    IOSurfaceRef       ioSurface;
} VkExportMetalIOSurfaceInfoEXT;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • image is a VkImage.

  • ioSurface is the Metal IOSurfaceRef object underlying the VkImage object in image. The implementation will return the IOSurfaceRef in this member, or it will return NULL if no IOSurfaceRef could be found underlying the VkImage object.

Valid Usage (Implicit)

  • VUID-VkExportMetalIOSurfaceInfoEXT-sType-sType
    sType must be VK_STRUCTURE_TYPE_EXPORT_METAL_IO_SURFACE_INFO_EXT

  • VUID-VkExportMetalIOSurfaceInfoEXT-image-parameter
    image must be a valid VkImage handle

To import, or create, a Metal IOSurfaceRef object to underlie a VkImage object, include a VkImportMetalIOSurfaceInfoEXT structure in the pNext chain of the VkImageCreateInfo structure in a vkCreateImage command.

The VkImportMetalIOSurfaceInfoEXT structure is defined as:

// Provided by VK_EXT_metal_objects
typedef struct VkImportMetalIOSurfaceInfoEXT {
    VkStructureType    sType;
    const void*        pNext;
    IOSurfaceRef       ioSurface;
} VkImportMetalIOSurfaceInfoEXT;

If ioSurface is not VK_NULL_HANDLE, it will be used to underlie the VkImage. If ioSurface is VK_NULL_HANDLE, the implementation will create a new IOSurface to underlie the VkImage.

If provided, the application must ensure that the configuration of the IOSurfaceRef object is compatible with the configuration of the VkImage. Failure to do so results in undefined behavior.

Valid Usage (Implicit)

  • VUID-VkImportMetalIOSurfaceInfoEXT-sType-sType
    sType must be VK_STRUCTURE_TYPE_IMPORT_METAL_IO_SURFACE_INFO_EXT

The type IOSurfaceRef is defined in Apple’s CoreGraphics framework, but to remove an unnecessary compile time dependency, an incomplete type definition of IOSurfaceRef is provided in the Vulkan headers:

// Provided by VK_EXT_metal_objects
typedef struct __IOSurface* IOSurfaceRef;

To export the Metal MTLSharedEvent object underlying a VkSemaphore or VkEvent object, include a VkExportMetalSharedEventInfoEXT structure in the pNext chain of the pMetalObjectsInfo parameter of a vkExportMetalObjectsEXT call.

The VkExportMetalSharedEventInfoEXT structure is defined as:

// Provided by VK_EXT_metal_objects
typedef struct VkExportMetalSharedEventInfoEXT {
    VkStructureType      sType;
    const void*          pNext;
    VkSemaphore          semaphore;
    VkEvent              event;
    MTLSharedEvent_id    mtlSharedEvent;
} VkExportMetalSharedEventInfoEXT;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • semaphore is VK_NULL_HANDLE or a VkSemaphore.

  • event is VK_NULL_HANDLE or a VkEvent.

  • mtlSharedEvent is the Metal id<MTLSharedEvent> object underlying the VkSemaphore or VkEvent object in semaphore or event, respectively. The implementation will return the MTLSharedEvent in this member, or it will return NULL if no MTLSharedEvent could be found underlying the VkSemaphore or VkEvent object.

Valid Usage (Implicit)

  • VUID-VkExportMetalSharedEventInfoEXT-sType-sType
    sType must be VK_STRUCTURE_TYPE_EXPORT_METAL_SHARED_EVENT_INFO_EXT

  • VUID-VkExportMetalSharedEventInfoEXT-semaphore-parameter
    If semaphore is not VK_NULL_HANDLE, semaphore must be a valid VkSemaphore handle

  • VUID-VkExportMetalSharedEventInfoEXT-event-parameter
    If event is not VK_NULL_HANDLE, event must be a valid VkEvent handle

  • VUID-VkExportMetalSharedEventInfoEXT-commonparent
    Both of event, and semaphore that are valid handles of non-ignored parameters must have been created, allocated, or retrieved from the same VkDevice

To import a Metal id<MTLSharedEvent> object to underlie a VkSemaphore or VkEvent object, include a VkImportMetalSharedEventInfoEXT structure in the pNext chain of the VkSemaphoreCreateInfo or VkEventCreateInfo structure in a vkCreateSemaphore or vkCreateEvent command, respectively.

The VkImportMetalSharedEventInfoEXT structure is defined as:

// Provided by VK_EXT_metal_objects
typedef struct VkImportMetalSharedEventInfoEXT {
    VkStructureType      sType;
    const void*          pNext;
    MTLSharedEvent_id    mtlSharedEvent;
} VkImportMetalSharedEventInfoEXT;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • mtlSharedEvent is the Metal id<MTLSharedEvent> object that is to underlie the VkSemaphore or VkEvent.

If the pNext chain of the VkSemaphoreCreateInfo structure includes both VkImportMetalSharedEventInfoEXT and VkSemaphoreTypeCreateInfo, the signaledValue property of the imported id<MTLSharedEvent> object will be set to initialValue of VkSemaphoreTypeCreateInfo.

Valid Usage (Implicit)

  • VUID-VkImportMetalSharedEventInfoEXT-sType-sType
    sType must be VK_STRUCTURE_TYPE_IMPORT_METAL_SHARED_EVENT_INFO_EXT

The type id<MTLSharedEvent> is defined in Apple’s Metal framework, but to remove an unnecessary compile time dependency, an incomplete type definition of MTLSharedEvent_id is provided in the Vulkan headers:

// Provided by VK_EXT_metal_objects
#ifdef __OBJC__
@protocol MTLSharedEvent;
typedef __unsafe_unretained id<MTLSharedEvent> MTLSharedEvent_id;
#else
typedef void* MTLSharedEvent_id;
#endif

11.2.11. QNX Screen Buffer External Memory

To import memory created outside of the current Vulkan instance from a QNX Screen buffer, add a VkImportScreenBufferInfoQNX structure to the pNext chain of the VkMemoryAllocateInfo structure. The VkImportScreenBufferInfoQNX structure is defined as:

// Provided by VK_QNX_external_memory_screen_buffer
typedef struct VkImportScreenBufferInfoQNX {
    VkStructureType           sType;
    const void*               pNext;
    struct _screen_buffer*    buffer;
} VkImportScreenBufferInfoQNX;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • buffer is a pointer to a struct _screen_buffer, the QNX Screen buffer to import

The implementation may not acquire a reference to the imported Screen buffer. Therefore, the application must ensure that the object referred to by buffer stays valid as long as the device memory to which it is imported is being used.

Valid Usage
Valid Usage (Implicit)

  • VUID-VkImportScreenBufferInfoQNX-sType-sType
    sType must be VK_STRUCTURE_TYPE_IMPORT_SCREEN_BUFFER_INFO_QNX

To determine the memory parameters to use when importing a QNX Screen buffer, call:

// Provided by VK_QNX_external_memory_screen_buffer
VkResult vkGetScreenBufferPropertiesQNX(
    VkDevice                                    device,
    const struct _screen_buffer*                buffer,
    VkScreenBufferPropertiesQNX*                pProperties);

  • device is the logical device that will be importing buffer.

  • buffer is the QNX Screen buffer which will be imported.

  • pProperties is a pointer to a VkScreenBufferPropertiesQNX structure in which the properties of buffer are returned.

Valid Usage
Valid Usage (Implicit)

  • VUID-vkGetScreenBufferPropertiesQNX-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkGetScreenBufferPropertiesQNX-buffer-parameter
    buffer must be a valid pointer to a valid _screen_buffer value

  • VUID-vkGetScreenBufferPropertiesQNX-pProperties-parameter
    pProperties must be a valid pointer to a VkScreenBufferPropertiesQNX structure

Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_INVALID_EXTERNAL_HANDLE_KHR

The VkScreenBufferPropertiesQNX structure returned is defined as:

// Provided by VK_QNX_external_memory_screen_buffer
typedef struct VkScreenBufferPropertiesQNX {
    VkStructureType    sType;
    void*              pNext;
    VkDeviceSize       allocationSize;
    uint32_t           memoryTypeBits;
} VkScreenBufferPropertiesQNX;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • allocationSize is the size of the external memory.

  • memoryTypeBits is a bitmask containing one bit set for every memory type which the specified Screen buffer can be imported as.

Valid Usage (Implicit)

  • VUID-VkScreenBufferPropertiesQNX-sType-sType
    sType must be VK_STRUCTURE_TYPE_SCREEN_BUFFER_PROPERTIES_QNX

  • VUID-VkScreenBufferPropertiesQNX-pNext-pNext
    pNext must be NULL or a pointer to a valid instance of VkScreenBufferFormatPropertiesQNX

  • VUID-VkScreenBufferPropertiesQNX-sType-unique
    The sType value of each struct in the pNext chain must be unique

To obtain format properties of a QNX Screen buffer, include a VkScreenBufferFormatPropertiesQNX structure in the pNext chain of the VkScreenBufferPropertiesQNX structure passed to vkGetScreenBufferPropertiesQNX. This structure is defined as:

// Provided by VK_QNX_external_memory_screen_buffer
typedef struct VkScreenBufferFormatPropertiesQNX {
    VkStructureType                  sType;
    void*                            pNext;
    VkFormat                         format;
    uint64_t                         externalFormat;
    uint64_t                         screenUsage;
    VkFormatFeatureFlags             formatFeatures;
    VkComponentMapping               samplerYcbcrConversionComponents;
    VkSamplerYcbcrModelConversion    suggestedYcbcrModel;
    VkSamplerYcbcrRange              suggestedYcbcrRange;
    VkChromaLocation                 suggestedXChromaOffset;
    VkChromaLocation                 suggestedYChromaOffset;
} VkScreenBufferFormatPropertiesQNX;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • format is the Vulkan format corresponding to the Screen buffer’s format or VK_FORMAT_UNDEFINED if there is not an equivalent Vulkan format.

  • externalFormat is an implementation-defined external format identifier for use with VkExternalFormatQNX. It must not be zero.

  • screenUsage is an implementation-defined external usage identifier for the QNX Screen buffer.

  • formatFeatures describes the capabilities of this external format when used with an image bound to memory imported from buffer.

  • samplerYcbcrConversionComponents is the component swizzle that should be used in VkSamplerYcbcrConversionCreateInfo.

  • suggestedYcbcrModel is a suggested color model to use in the VkSamplerYcbcrConversionCreateInfo.

  • suggestedYcbcrRange is a suggested numerical value range to use in VkSamplerYcbcrConversionCreateInfo.

  • suggestedXChromaOffset is a suggested X chroma offset to use in VkSamplerYcbcrConversionCreateInfo.

  • suggestedYChromaOffset is a suggested Y chroma offset to use in VkSamplerYcbcrConversionCreateInfo.

If the QNX Screen buffer has one of the formats listed in the QNX Screen Format Equivalence table, then format must have the equivalent Vulkan format listed in the table. Otherwise, format may be VK_FORMAT_UNDEFINED, indicating the QNX Screen buffer can only be used with an external format. The formatFeatures member must include VK_FORMAT_FEATURE_SAMPLED_IMAGE_BIT and should include VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT and VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_LINEAR_FILTER_BIT.

Valid Usage (Implicit)

  • VUID-VkScreenBufferFormatPropertiesQNX-sType-sType
    sType must be VK_STRUCTURE_TYPE_SCREEN_BUFFER_FORMAT_PROPERTIES_QNX

11.2.12. Device Group Memory Allocations

If the pNext chain of VkMemoryAllocateInfo includes a VkMemoryAllocateFlagsInfo structure, then that structure includes flags and a device mask controlling how many instances of the memory will be allocated.

The VkMemoryAllocateFlagsInfo structure is defined as:

// Provided by VK_VERSION_1_1
typedef struct VkMemoryAllocateFlagsInfo {
    VkStructureType          sType;
    const void*              pNext;
    VkMemoryAllocateFlags    flags;
    uint32_t                 deviceMask;
} VkMemoryAllocateFlagsInfo;

or the equivalent

// Provided by VK_KHR_device_group
typedef VkMemoryAllocateFlagsInfo VkMemoryAllocateFlagsInfoKHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • flags is a bitmask of VkMemoryAllocateFlagBits controlling the allocation.

  • deviceMask is a mask of physical devices in the logical device, indicating that memory must be allocated on each device in the mask, if VK_MEMORY_ALLOCATE_DEVICE_MASK_BIT is set in flags.

If VK_MEMORY_ALLOCATE_DEVICE_MASK_BIT is not set, the number of instances allocated depends on whether VK_MEMORY_HEAP_MULTI_INSTANCE_BIT is set in the memory heap. If VK_MEMORY_HEAP_MULTI_INSTANCE_BIT is set, then memory is allocated for every physical device in the logical device (as if deviceMask has bits set for all device indices). If VK_MEMORY_HEAP_MULTI_INSTANCE_BIT is not set, then a single instance of memory is allocated (as if deviceMask is set to one).

On some implementations, allocations from a multi-instance heap may consume memory on all physical devices even if the deviceMask excludes some devices. If VkPhysicalDeviceGroupProperties::subsetAllocation is VK_TRUE, then memory is only consumed for the devices in the device mask.

Note

In practice, most allocations on a multi-instance heap will be allocated across all physical devices. Unicast allocation support is an optional optimization for a minority of allocations.
Valid Usage

  • VUID-VkMemoryAllocateFlagsInfo-deviceMask-00675
    If VK_MEMORY_ALLOCATE_DEVICE_MASK_BIT is set, deviceMask must be a valid device mask

  • VUID-VkMemoryAllocateFlagsInfo-deviceMask-00676
    If VK_MEMORY_ALLOCATE_DEVICE_MASK_BIT is set, deviceMask must not be zero

Valid Usage (Implicit)

  • VUID-VkMemoryAllocateFlagsInfo-sType-sType
    sType must be VK_STRUCTURE_TYPE_MEMORY_ALLOCATE_FLAGS_INFO

  • VUID-VkMemoryAllocateFlagsInfo-flags-parameter
    flags must be a valid combination of VkMemoryAllocateFlagBits values

Bits which can be set in VkMemoryAllocateFlagsInfo::flags, controlling device memory allocation, are:

// Provided by VK_VERSION_1_1
typedef enum VkMemoryAllocateFlagBits {
    VK_MEMORY_ALLOCATE_DEVICE_MASK_BIT = 0x00000001,
  // Provided by VK_VERSION_1_2
    VK_MEMORY_ALLOCATE_DEVICE_ADDRESS_BIT = 0x00000002,
  // Provided by VK_VERSION_1_2
    VK_MEMORY_ALLOCATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT = 0x00000004,
  // Provided by VK_KHR_device_group
    VK_MEMORY_ALLOCATE_DEVICE_MASK_BIT_KHR = VK_MEMORY_ALLOCATE_DEVICE_MASK_BIT,
  // Provided by VK_KHR_buffer_device_address
    VK_MEMORY_ALLOCATE_DEVICE_ADDRESS_BIT_KHR = VK_MEMORY_ALLOCATE_DEVICE_ADDRESS_BIT,
  // Provided by VK_KHR_buffer_device_address
    VK_MEMORY_ALLOCATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT_KHR = VK_MEMORY_ALLOCATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT,
} VkMemoryAllocateFlagBits;

or the equivalent

// Provided by VK_KHR_device_group
typedef VkMemoryAllocateFlagBits VkMemoryAllocateFlagBitsKHR;

  • VK_MEMORY_ALLOCATE_DEVICE_MASK_BIT specifies that memory will be allocated for the devices in VkMemoryAllocateFlagsInfo::deviceMask.

  • VK_MEMORY_ALLOCATE_DEVICE_ADDRESS_BIT specifies that the memory can be attached to a buffer object created with the VK_BUFFER_USAGE_SHADER_DEVICE_ADDRESS_BIT bit set in usage, and that the memory handle can be used to retrieve an opaque address via vkGetDeviceMemoryOpaqueCaptureAddress.

  • VK_MEMORY_ALLOCATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT specifies that the memory’s address can be saved and reused on a subsequent run (e.g. for trace capture and replay), see VkBufferOpaqueCaptureAddressCreateInfo for more detail.

// Provided by VK_VERSION_1_1
typedef VkFlags VkMemoryAllocateFlags;

or the equivalent

// Provided by VK_KHR_device_group
typedef VkMemoryAllocateFlags VkMemoryAllocateFlagsKHR;

VkMemoryAllocateFlags is a bitmask type for setting a mask of zero or more VkMemoryAllocateFlagBits.

11.2.13. Opaque Capture Address Allocation

To request a specific device address for a memory allocation, add a VkMemoryOpaqueCaptureAddressAllocateInfo structure to the pNext chain of the VkMemoryAllocateInfo structure. The VkMemoryOpaqueCaptureAddressAllocateInfo structure is defined as:

// Provided by VK_VERSION_1_2
typedef struct VkMemoryOpaqueCaptureAddressAllocateInfo {
    VkStructureType    sType;
    const void*        pNext;
    uint64_t           opaqueCaptureAddress;
} VkMemoryOpaqueCaptureAddressAllocateInfo;

or the equivalent

// Provided by VK_KHR_buffer_device_address
typedef VkMemoryOpaqueCaptureAddressAllocateInfo VkMemoryOpaqueCaptureAddressAllocateInfoKHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • opaqueCaptureAddress is the opaque capture address requested for the memory allocation.

If opaqueCaptureAddress is zero, no specific address is requested.

If opaqueCaptureAddress is not zero, it should be an address retrieved from vkGetDeviceMemoryOpaqueCaptureAddress on an identically created memory allocation on the same implementation.

Note

In most cases, it is expected that a non-zero opaqueAddress is an address retrieved from vkGetDeviceMemoryOpaqueCaptureAddress on an identically created memory allocation. If this is not the case, it is likely that VK_ERROR_INVALID_OPAQUE_CAPTURE_ADDRESS errors will occur.

This is, however, not a strict requirement because trace capture/replay tools may need to adjust memory allocation parameters for imported memory.

If this structure is not present, it is as if opaqueCaptureAddress is zero.

Valid Usage (Implicit)

  • VUID-VkMemoryOpaqueCaptureAddressAllocateInfo-sType-sType
    sType must be VK_STRUCTURE_TYPE_MEMORY_OPAQUE_CAPTURE_ADDRESS_ALLOCATE_INFO

11.2.14. Freeing Device Memory

To free a memory object, call:

// Provided by VK_VERSION_1_0
void vkFreeMemory(
    VkDevice                                    device,
    VkDeviceMemory                              memory,
    const VkAllocationCallbacks*                pAllocator);

  • device is the logical device that owns the memory.

  • memory is the VkDeviceMemory object to be freed.

  • pAllocator controls host memory allocation as described in the Memory Allocation chapter.

Before freeing a memory object, an application must ensure the memory object is no longer in use by the device — for example by command buffers in the pending state. Memory can be freed whilst still bound to resources, but those resources must not be used afterwards. Freeing a memory object releases the reference it held, if any, to its payload. If there are still any bound images or buffers, the memory object’s payload may not be immediately released by the implementation, but must be released by the time all bound images and buffers have been destroyed. Once all references to a payload are released, it is returned to the heap from which it was allocated.

How memory objects are bound to Images and Buffers is described in detail in the Resource Memory Association section.

If a memory object is mapped at the time it is freed, it is implicitly unmapped.

Note

As described below, host writes are not implicitly flushed when the memory object is unmapped, but the implementation must guarantee that writes that have not been flushed do not affect any other memory.
Valid Usage

  • VUID-vkFreeMemory-memory-00677
    All submitted commands that refer to memory (via images or buffers) must have completed execution

Valid Usage (Implicit)

  • VUID-vkFreeMemory-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkFreeMemory-memory-parameter
    If memory is not VK_NULL_HANDLE, memory must be a valid VkDeviceMemory handle

  • VUID-vkFreeMemory-pAllocator-parameter
    If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure

  • VUID-vkFreeMemory-memory-parent
    If memory is a valid handle, it must have been created, allocated, or retrieved from device

Host Synchronization

  • Host access to memory must be externally synchronized

11.2.15. Host Access to Device Memory Objects

Memory objects created with vkAllocateMemory are not directly host accessible.

Memory objects created with the memory property VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT are considered mappable. Memory objects must be mappable in order to be successfully mapped on the host.

To retrieve a host virtual address pointer to a region of a mappable memory object, call:

// Provided by VK_VERSION_1_0
VkResult vkMapMemory(
    VkDevice                                    device,
    VkDeviceMemory                              memory,
    VkDeviceSize                                offset,
    VkDeviceSize                                size,
    VkMemoryMapFlags                            flags,
    void**                                      ppData);

  • device is the logical device that owns the memory.

  • memory is the VkDeviceMemory object to be mapped.

  • offset is a zero-based byte offset from the beginning of the memory object.

  • size is the size of the memory range to map, or VK_WHOLE_SIZE to map from offset to the end of the allocation.

  • flags is a bitmask of VkMemoryMapFlagBits specifying additional parameters of the memory map operation.

  • ppData is a pointer to a void* variable in which a host-accessible pointer to the beginning of the mapped range is returned. This pointer minus offset must be aligned to at least VkPhysicalDeviceLimits::minMemoryMapAlignment.

After a successful call to vkMapMemory the memory object memory is considered to be currently host mapped.

Note

It is an application error to call vkMapMemory on a memory object that is already host mapped.
Note

vkMapMemory will fail if the implementation is unable to allocate an appropriately sized contiguous virtual address range, e.g. due to virtual address space fragmentation or platform limits. In such cases, vkMapMemory must return VK_ERROR_MEMORY_MAP_FAILED. The application can improve the likelihood of success by reducing the size of the mapped range and/or removing unneeded mappings using vkUnmapMemory.

vkMapMemory does not check whether the device memory is currently in use before returning the host-accessible pointer. The application must guarantee that any previously submitted command that writes to this range has completed before the host reads from or writes to that range, and that any previously submitted command that reads from that range has completed before the host writes to that region (see here for details on fulfilling such a guarantee). If the device memory was allocated without the VK_MEMORY_PROPERTY_HOST_COHERENT_BIT set, these guarantees must be made for an extended range: the application must round down the start of the range to the nearest multiple of VkPhysicalDeviceLimits::nonCoherentAtomSize, and round the end of the range up to the nearest multiple of VkPhysicalDeviceLimits::nonCoherentAtomSize.

While a range of device memory is host mapped, the application is responsible for synchronizing both device and host access to that memory range.

Note

It is important for the application developer to become meticulously familiar with all of the mechanisms described in the chapter on Synchronization and Cache Control as they are crucial to maintaining memory access ordering.

Calling vkMapMemory is equivalent to calling vkMapMemory2KHR with an empty pNext chain.

Valid Usage

  • VUID-vkMapMemory-memory-00678
    memory must not be currently host mapped

  • VUID-vkMapMemory-offset-00679
    offset must be less than the size of memory

  • VUID-vkMapMemory-size-00680
    If size is not equal to VK_WHOLE_SIZE, size must be greater than 0

  • VUID-vkMapMemory-size-00681
    If size is not equal to VK_WHOLE_SIZE, size must be less than or equal to the size of the memory minus offset

  • VUID-vkMapMemory-memory-00682
    memory must have been created with a memory type that reports VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT

  • VUID-vkMapMemory-memory-00683
    memory must not have been allocated with multiple instances

  • VUID-vkMapMemory-flags-09568
    VK_MEMORY_MAP_PLACED_BIT_EXT must not be set in flags

Valid Usage (Implicit)

  • VUID-vkMapMemory-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkMapMemory-memory-parameter
    memory must be a valid VkDeviceMemory handle

  • VUID-vkMapMemory-flags-parameter
    flags must be a valid combination of VkMemoryMapFlagBits values

  • VUID-vkMapMemory-ppData-parameter
    ppData must be a valid pointer to a pointer value

  • VUID-vkMapMemory-memory-parent
    memory must have been created, allocated, or retrieved from device

Host Synchronization

  • Host access to memory must be externally synchronized

Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

  • VK_ERROR_MEMORY_MAP_FAILED

Bits which can be set in vkMapMemory::flags and VkMemoryMapInfoKHR::flags, specifying additional properties of a memory map, are:

// Provided by VK_VERSION_1_0
typedef enum VkMemoryMapFlagBits {
  // Provided by VK_EXT_map_memory_placed
    VK_MEMORY_MAP_PLACED_BIT_EXT = 0x00000001,
} VkMemoryMapFlagBits;

  • VK_MEMORY_MAP_PLACED_BIT_EXT requests that the implementation place the memory map at the virtual address specified by the application via VkMemoryMapPlacedInfoEXT::pPlacedAddress, replacing any existing mapping at that address. This flag must not be used with vkMapMemory as there is no way to specify the placement address.

// Provided by VK_VERSION_1_0
typedef VkFlags VkMemoryMapFlags;

VkMemoryMapFlags is a bitmask type for setting a mask of zero or more VkMemoryMapFlagBits.

Alternatively, to retrieve a host virtual address pointer to a region of a mappable memory object, call:

// Provided by VK_KHR_map_memory2
VkResult vkMapMemory2KHR(
    VkDevice                                    device,
    const VkMemoryMapInfoKHR*                   pMemoryMapInfo,
    void**                                      ppData);

  • device is the logical device that owns the memory.

  • pMemoryMapInfo is a pointer to a VkMemoryMapInfoKHR structure describing parameters of the map.

  • ppData is a pointer to a void * variable in which is returned a host-accessible pointer to the beginning of the mapped range. This pointer minus VkMemoryMapInfoKHR::offset must be aligned to at least VkPhysicalDeviceLimits::minMemoryMapAlignment.

This function behaves identically to vkMapMemory except that it gets its parameters via an extensible structure pointer rather than directly as function arguments.

Valid Usage (Implicit)

  • VUID-vkMapMemory2KHR-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkMapMemory2KHR-pMemoryMapInfo-parameter
    pMemoryMapInfo must be a valid pointer to a valid VkMemoryMapInfoKHR structure

  • VUID-vkMapMemory2KHR-ppData-parameter
    ppData must be a valid pointer to a pointer value

Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

  • VK_ERROR_MEMORY_MAP_FAILED

The VkMemoryMapInfoKHR structure is defined as:

// Provided by VK_KHR_map_memory2
typedef struct VkMemoryMapInfoKHR {
    VkStructureType     sType;
    const void*         pNext;
    VkMemoryMapFlags    flags;
    VkDeviceMemory      memory;
    VkDeviceSize        offset;
    VkDeviceSize        size;
} VkMemoryMapInfoKHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • flags is a bitmask of VkMemoryMapFlagBits specifying additional parameters of the memory map operation.

  • memory is the VkDeviceMemory object to be mapped.

  • offset is a zero-based byte offset from the beginning of the memory object.

  • size is the size of the memory range to map, or VK_WHOLE_SIZE to map from offset to the end of the allocation.

Valid Usage

  • VUID-VkMemoryMapInfoKHR-memory-07958
    memory must not be currently host mapped

  • VUID-VkMemoryMapInfoKHR-offset-07959
    offset must be less than the size of memory

  • VUID-VkMemoryMapInfoKHR-size-07960
    If size is not equal to VK_WHOLE_SIZE, size must be greater than 0

  • VUID-VkMemoryMapInfoKHR-size-07961
    If size is not equal to VK_WHOLE_SIZE, size must be less than or equal to the size of the memory minus offset

  • VUID-VkMemoryMapInfoKHR-memory-07962
    memory must have been created with a memory type that reports VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT

  • VUID-VkMemoryMapInfoKHR-memory-07963
    memory must not have been allocated with multiple instances

  • VUID-VkMemoryMapInfoKHR-flags-09569
    If VK_MEMORY_MAP_PLACED_BIT_EXT is set in flags, the memoryMapPlaced feature must be enabled

  • VUID-VkMemoryMapInfoKHR-flags-09570
    If VK_MEMORY_MAP_PLACED_BIT_EXT is set in flags, the pNext chain must include a VkMemoryMapPlacedInfoEXT structure and VkMemoryMapPlacedInfoEXT::pPlacedAddress must not be NULL

  • VUID-VkMemoryMapInfoKHR-flags-09571
    If VK_MEMORY_MAP_PLACED_BIT_EXT is set in flags and the memoryMapRangePlaced feature is not enabled, offset must be zero

  • VUID-VkMemoryMapInfoKHR-flags-09572
    If VK_MEMORY_MAP_PLACED_BIT_EXT is set in flags and the memoryMapRangePlaced feature is not enabled, size must be VK_WHOLE_SIZE or VkMemoryAllocateInfo::allocationSize

  • VUID-VkMemoryMapInfoKHR-flags-09573
    If VK_MEMORY_MAP_PLACED_BIT_EXT is set in flags and the memoryMapRangePlaced feature is enabled, offset must be aligned to an integer multiple of VkPhysicalDeviceMapMemoryPlacedPropertiesEXT::minPlacedMemoryMapAlignment

  • VUID-VkMemoryMapInfoKHR-flags-09574
    If VK_MEMORY_MAP_PLACED_BIT_EXT is set in flags and size is not VK_WHOLE_SIZE, size must be aligned to an integer multiple of VkPhysicalDeviceMapMemoryPlacedPropertiesEXT::minPlacedMemoryMapAlignment

  • VUID-VkMemoryMapInfoKHR-flags-09651
    If VK_MEMORY_MAP_PLACED_BIT_EXT is set in flags and size is VK_WHOLE_SIZE, VkMemoryAllocateInfo::allocationSize must be aligned to an integer multiple of VkPhysicalDeviceMapMemoryPlacedPropertiesEXT::minPlacedMemoryMapAlignment

  • VUID-VkMemoryMapInfoKHR-flags-09575
    If VK_MEMORY_MAP_PLACED_BIT_EXT is set in flags, the memory object must not have been imported from a handle type of VK_EXTERNAL_MEMORY_HANDLE_TYPE_HOST_ALLOCATION_BIT_EXT or VK_EXTERNAL_MEMORY_HANDLE_TYPE_HOST_MAPPED_FOREIGN_MEMORY_BIT_EXT

Valid Usage (Implicit)

  • VUID-VkMemoryMapInfoKHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_MEMORY_MAP_INFO_KHR

  • VUID-VkMemoryMapInfoKHR-pNext-pNext
    pNext must be NULL or a pointer to a valid instance of VkMemoryMapPlacedInfoEXT

  • VUID-VkMemoryMapInfoKHR-sType-unique
    The sType value of each struct in the pNext chain must be unique

  • VUID-VkMemoryMapInfoKHR-flags-parameter
    flags must be a valid combination of VkMemoryMapFlagBits values

  • VUID-VkMemoryMapInfoKHR-memory-parameter
    memory must be a valid VkDeviceMemory handle

Host Synchronization

  • Host access to memory must be externally synchronized

If VK_MEMORY_MAP_PLACED_BIT_EXT is set in VkMemoryMapInfoKHR::flags and the pNext chain of VkMemoryMapInfoKHR includes a VkMemoryMapPlacedInfoEXT structure, then that structure specifies the placement address of the memory map. The implementation will place the memory map at the specified address, replacing any existing maps in the specified memory range. Replacing memory maps in this way does not implicitly unmap Vulkan memory objects. Instead, the application must ensure no other Vulkan memory objects are mapped anywhere in the specified virtual address range. If successful, ppData will be set to the same value as VkMemoryMapPlacedInfoEXT::pPlacedAddress and vkMapMemory2KHR will return VK_SUCCESS. If it cannot place the map at the requested address for any reason, the memory object is left unmapped and vkMapMemory2KHR will return VK_ERROR_MEMORY_MAP_FAILED.

The VkMemoryMapPlacedInfoEXT structure is defined as:

// Provided by VK_EXT_map_memory_placed
typedef struct VkMemoryMapPlacedInfoEXT {
    VkStructureType    sType;
    const void*        pNext;
    void*              pPlacedAddress;
} VkMemoryMapPlacedInfoEXT;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • pPlacedAddress is the virtual address at which to place the address. If VkMemoryMapInfoKHR::flags does not contain VK_MEMORY_MAP_PLACED_BIT_EXT, this value is ignored.

Valid Usage

  • VUID-VkMemoryMapPlacedInfoEXT-flags-09576
    If VkMemoryMapInfoKHR::flags contains VK_MEMORY_MAP_PLACED_BIT_EXT, pPlacedAddress must not be NULL

  • VUID-VkMemoryMapPlacedInfoEXT-pPlacedAddress-09577
    pPlacedAddress must be aligned to an integer multiple of VkPhysicalDeviceMapMemoryPlacedPropertiesEXT::minPlacedMemoryMapAlignment

  • VUID-VkMemoryMapPlacedInfoEXT-pPlacedAddress-09578
    The address range specified by pPlacedAddress and VkMemoryMapInfoKHR::size must not overlap any existing Vulkan memory object mapping

Valid Usage (Implicit)

  • VUID-VkMemoryMapPlacedInfoEXT-sType-sType
    sType must be VK_STRUCTURE_TYPE_MEMORY_MAP_PLACED_INFO_EXT

Two commands are provided to enable applications to work with non-coherent memory allocations: vkFlushMappedMemoryRanges and vkInvalidateMappedMemoryRanges.

Note

If the memory object was created with the VK_MEMORY_PROPERTY_HOST_COHERENT_BIT set, vkFlushMappedMemoryRanges and vkInvalidateMappedMemoryRanges are unnecessary and may have a performance cost. However, availability and visibility operations still need to be managed on the device. See the description of host access types for more information.
Note

While memory objects imported from a handle type of VK_EXTERNAL_MEMORY_HANDLE_TYPE_HOST_ALLOCATION_BIT_EXT or VK_EXTERNAL_MEMORY_HANDLE_TYPE_HOST_MAPPED_FOREIGN_MEMORY_BIT_EXT are inherently mapped to host address space, they are not considered to be host mapped device memory unless they are explicitly host mapped using vkMapMemory. That means flushing or invalidating host caches with respect to host accesses performed on such memory through the original host pointer specified at import time is the responsibility of the application and must be performed with appropriate synchronization primitives provided by the platform which are outside the scope of Vulkan. vkFlushMappedMemoryRanges and vkInvalidateMappedMemoryRanges, however, can still be used on such memory objects to synchronize host accesses performed through the host pointer of the host mapped device memory range returned by vkMapMemory.

After a successful call to vkMapMemory or vkMapMemory2KHR the memory object memory is considered to be currently host mapped.

To flush ranges of non-coherent memory from the host caches, call:

// Provided by VK_VERSION_1_0
VkResult vkFlushMappedMemoryRanges(
    VkDevice                                    device,
    uint32_t                                    memoryRangeCount,
    const VkMappedMemoryRange*                  pMemoryRanges);

  • device is the logical device that owns the memory ranges.

  • memoryRangeCount is the length of the pMemoryRanges array.

  • pMemoryRanges is a pointer to an array of VkMappedMemoryRange structures describing the memory ranges to flush.

vkFlushMappedMemoryRanges guarantees that host writes to the memory ranges described by pMemoryRanges are made available to the host memory domain, such that they can be made available to the device memory domain via memory domain operations using the VK_ACCESS_HOST_WRITE_BIT access type.

Within each range described by pMemoryRanges, each set of nonCoherentAtomSize bytes in that range is flushed if any byte in that set has been written by the host since it was first host mapped, or the last time it was flushed. If pMemoryRanges includes sets of nonCoherentAtomSize bytes where no bytes have been written by the host, those bytes must not be flushed.

Unmapping non-coherent memory does not implicitly flush the host mapped memory, and host writes that have not been flushed may not ever be visible to the device. However, implementations must ensure that writes that have not been flushed do not become visible to any other memory.

Note

The above guarantee avoids a potential memory corruption in scenarios where host writes to a mapped memory object have not been flushed before the memory is unmapped (or freed), and the virtual address range is subsequently reused for a different mapping (or memory allocation).
Valid Usage (Implicit)

  • VUID-vkFlushMappedMemoryRanges-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkFlushMappedMemoryRanges-pMemoryRanges-parameter
    pMemoryRanges must be a valid pointer to an array of memoryRangeCount valid VkMappedMemoryRange structures

  • VUID-vkFlushMappedMemoryRanges-memoryRangeCount-arraylength
    memoryRangeCount must be greater than 0

Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

To invalidate ranges of non-coherent memory from the host caches, call:

// Provided by VK_VERSION_1_0
VkResult vkInvalidateMappedMemoryRanges(
    VkDevice                                    device,
    uint32_t                                    memoryRangeCount,
    const VkMappedMemoryRange*                  pMemoryRanges);

  • device is the logical device that owns the memory ranges.

  • memoryRangeCount is the length of the pMemoryRanges array.

  • pMemoryRanges is a pointer to an array of VkMappedMemoryRange structures describing the memory ranges to invalidate.

vkInvalidateMappedMemoryRanges guarantees that device writes to the memory ranges described by pMemoryRanges, which have been made available to the host memory domain using the VK_ACCESS_HOST_WRITE_BIT and VK_ACCESS_HOST_READ_BIT access types, are made visible to the host. If a range of non-coherent memory is written by the host and then invalidated without first being flushed, its contents are undefined.

Within each range described by pMemoryRanges, each set of nonCoherentAtomSize bytes in that range is invalidated if any byte in that set has been written by the device since it was first host mapped, or the last time it was invalidated.

Note

Mapping non-coherent memory does not implicitly invalidate that memory.
Valid Usage (Implicit)

  • VUID-vkInvalidateMappedMemoryRanges-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkInvalidateMappedMemoryRanges-pMemoryRanges-parameter
    pMemoryRanges must be a valid pointer to an array of memoryRangeCount valid VkMappedMemoryRange structures

  • VUID-vkInvalidateMappedMemoryRanges-memoryRangeCount-arraylength
    memoryRangeCount must be greater than 0

Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

The VkMappedMemoryRange structure is defined as:

// Provided by VK_VERSION_1_0
typedef struct VkMappedMemoryRange {
    VkStructureType    sType;
    const void*        pNext;
    VkDeviceMemory     memory;
    VkDeviceSize       offset;
    VkDeviceSize       size;
} VkMappedMemoryRange;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • memory is the memory object to which this range belongs.

  • offset is the zero-based byte offset from the beginning of the memory object.

  • size is either the size of range, or VK_WHOLE_SIZE to affect the range from offset to the end of the current mapping of the allocation.

Valid Usage

  • VUID-VkMappedMemoryRange-memory-00684
    memory must be currently host mapped

  • VUID-VkMappedMemoryRange-size-00685
    If size is not equal to VK_WHOLE_SIZE, offset and size must specify a range contained within the currently mapped range of memory

  • VUID-VkMappedMemoryRange-size-00686
    If size is equal to VK_WHOLE_SIZE, offset must be within the currently mapped range of memory

  • VUID-VkMappedMemoryRange-offset-00687
    offset must be a multiple of VkPhysicalDeviceLimits::nonCoherentAtomSize

  • VUID-VkMappedMemoryRange-size-01389
    If size is equal to VK_WHOLE_SIZE, the end of the current mapping of memory must either be a multiple of VkPhysicalDeviceLimits::nonCoherentAtomSize bytes from the beginning of the memory object, or be equal to the end of the memory object

  • VUID-VkMappedMemoryRange-size-01390
    If size is not equal to VK_WHOLE_SIZE, size must either be a multiple of VkPhysicalDeviceLimits::nonCoherentAtomSize, or offset plus size must equal the size of memory

Valid Usage (Implicit)

  • VUID-VkMappedMemoryRange-sType-sType
    sType must be VK_STRUCTURE_TYPE_MAPPED_MEMORY_RANGE

  • VUID-VkMappedMemoryRange-pNext-pNext
    pNext must be NULL

  • VUID-VkMappedMemoryRange-memory-parameter
    memory must be a valid VkDeviceMemory handle

To unmap a memory object once host access to it is no longer needed by the application, call:

// Provided by VK_VERSION_1_0
void vkUnmapMemory(
    VkDevice                                    device,
    VkDeviceMemory                              memory);

  • device is the logical device that owns the memory.

  • memory is the memory object to be unmapped.

Calling vkUnmapMemory is equivalent to calling vkUnmapMemory2KHR with an empty pNext chain and the flags parameter set to zero.

Valid Usage

  • VUID-vkUnmapMemory-memory-00689
    memory must be currently host mapped

Valid Usage (Implicit)

  • VUID-vkUnmapMemory-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkUnmapMemory-memory-parameter
    memory must be a valid VkDeviceMemory handle

  • VUID-vkUnmapMemory-memory-parent
    memory must have been created, allocated, or retrieved from device

Host Synchronization

  • Host access to memory must be externally synchronized

Alternatively, to unmap a memory object once host access to it is no longer needed by the application, call:

// Provided by VK_KHR_map_memory2
VkResult vkUnmapMemory2KHR(
    VkDevice                                    device,
    const VkMemoryUnmapInfoKHR*                 pMemoryUnmapInfo);

  • device is the logical device that owns the memory.

  • pMemoryUnmapInfo is a pointer to a VkMemoryUnmapInfoKHR structure describing parameters of the unmap.

This function behaves identically to vkUnmapMemory except that it gets its parameters via an extensible structure pointer rather than directly as function arguments.

Valid Usage (Implicit)

  • VUID-vkUnmapMemory2KHR-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkUnmapMemory2KHR-pMemoryUnmapInfo-parameter
    pMemoryUnmapInfo must be a valid pointer to a valid VkMemoryUnmapInfoKHR structure

Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_MEMORY_MAP_FAILED

The VkMemoryUnmapInfoKHR structure is defined as:

// Provided by VK_KHR_map_memory2
typedef struct VkMemoryUnmapInfoKHR {
    VkStructureType          sType;
    const void*              pNext;
    VkMemoryUnmapFlagsKHR    flags;
    VkDeviceMemory           memory;
} VkMemoryUnmapInfoKHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • flags is a bitmask of VkMemoryUnmapFlagBitsKHR specifying additional parameters of the memory map operation.

  • memory is the VkDeviceMemory object to be unmapped.

Valid Usage

  • VUID-VkMemoryUnmapInfoKHR-memory-07964
    memory must be currently host mapped

  • VUID-VkMemoryUnmapInfoKHR-flags-09579
    If VK_MEMORY_UNMAP_RESERVE_BIT_EXT is set in flags, the memoryUnmapReserve must be enabled

  • VUID-VkMemoryUnmapInfoKHR-flags-09580
    If VK_MEMORY_UNMAP_RESERVE_BIT_EXT is set in flags, the memory object must not have been imported from a handle type of VK_EXTERNAL_MEMORY_HANDLE_TYPE_HOST_ALLOCATION_BIT_EXT or VK_EXTERNAL_MEMORY_HANDLE_TYPE_HOST_MAPPED_FOREIGN_MEMORY_BIT_EXT

Valid Usage (Implicit)

  • VUID-VkMemoryUnmapInfoKHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_MEMORY_UNMAP_INFO_KHR

  • VUID-VkMemoryUnmapInfoKHR-pNext-pNext
    pNext must be NULL

  • VUID-VkMemoryUnmapInfoKHR-flags-parameter
    flags must be a valid combination of VkMemoryUnmapFlagBitsKHR values

  • VUID-VkMemoryUnmapInfoKHR-memory-parameter
    memory must be a valid VkDeviceMemory handle

Host Synchronization

  • Host access to memory must be externally synchronized

Bits which can be set in VkMemoryUnmapInfoKHR::flags, specifying additional properties of a memory unmap, are:

// Provided by VK_KHR_map_memory2
typedef enum VkMemoryUnmapFlagBitsKHR {
  // Provided by VK_EXT_map_memory_placed
    VK_MEMORY_UNMAP_RESERVE_BIT_EXT = 0x00000001,
} VkMemoryUnmapFlagBitsKHR;

  • VK_MEMORY_UNMAP_RESERVE_BIT_EXT requests that virtual address range currently occupied by the memory map remain reserved after the vkUnmapMemory2KHR call completes. Future system memory map operations or calls to vkMapMemory or vkMapMemory2KHR will not return addresses in that range unless the range has since been unreserved by the application or the mapping is explicitly placed in that range by calling vkMapMemory2KHR with VK_MEMORY_MAP_PLACED_BIT_EXT, or doing the system memory map equivalent. When VK_MEMORY_UNMAP_RESERVE_BIT_EXT is set, the memory unmap operation may fail, in which case the memory object will remain host mapped and vkUnmapMemory2KHR will return VK_ERROR_MEMORY_MAP_FAILED.

// Provided by VK_KHR_map_memory2
typedef VkFlags VkMemoryUnmapFlagsKHR;

VkMemoryUnmapFlagsKHR is a bitmask type for setting a mask of zero or more VkMemoryUnmapFlagBitsKHR.

11.2.16. Lazily Allocated Memory

If the memory object is allocated from a heap with the VK_MEMORY_PROPERTY_LAZILY_ALLOCATED_BIT bit set, that object’s backing memory may be provided by the implementation lazily. The actual committed size of the memory may initially be as small as zero (or as large as the requested size), and monotonically increases as additional memory is needed.

A memory type with this flag set is only allowed to be bound to a VkImage whose usage flags include VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT.

Note

Using lazily allocated memory objects for framebuffer attachments that are not needed once a render pass instance has completed may allow some implementations to never allocate memory for such attachments.

To determine the amount of lazily-allocated memory that is currently committed for a memory object, call:

// Provided by VK_VERSION_1_0
void vkGetDeviceMemoryCommitment(
    VkDevice                                    device,
    VkDeviceMemory                              memory,
    VkDeviceSize*                               pCommittedMemoryInBytes);

  • device is the logical device that owns the memory.

  • memory is the memory object being queried.

  • pCommittedMemoryInBytes is a pointer to a VkDeviceSize value in which the number of bytes currently committed is returned, on success.

The implementation may update the commitment at any time, and the value returned by this query may be out of date.

The implementation guarantees to allocate any committed memory from the heapIndex indicated by the memory type that the memory object was created with.

Valid Usage

  • VUID-vkGetDeviceMemoryCommitment-memory-00690
    memory must have been created with a memory type that reports VK_MEMORY_PROPERTY_LAZILY_ALLOCATED_BIT

Valid Usage (Implicit)

  • VUID-vkGetDeviceMemoryCommitment-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkGetDeviceMemoryCommitment-memory-parameter
    memory must be a valid VkDeviceMemory handle

  • VUID-vkGetDeviceMemoryCommitment-pCommittedMemoryInBytes-parameter
    pCommittedMemoryInBytes must be a valid pointer to a VkDeviceSize value

  • VUID-vkGetDeviceMemoryCommitment-memory-parent
    memory must have been created, allocated, or retrieved from device

11.2.17. Protected Memory

Protected memory divides device memory into protected device memory and unprotected device memory.

Protected memory adds the following concepts:

  • Memory:

    • Unprotected device memory, which can be visible to the device and can be visible to the host

    • Protected device memory, which can be visible to the device but must not be visible to the host

  • Resources:

    • Unprotected images and unprotected buffers, to which unprotected memory can be bound

    • Protected images and protected buffers, to which protected memory can be bound

  • Command buffers:

    • Unprotected command buffers, which can be submitted to a device queue to execute unprotected queue operations

    • Protected command buffers, which can be submitted to a protected-capable device queue to execute protected queue operations

  • Device queues:

    • Unprotected device queues, to which unprotected command buffers can be submitted

    • Protected-capable device queues, to which unprotected command buffers or protected command buffers can be submitted

  • Queue submissions

    • Unprotected queue submissions, through which unprotected command buffers can be submitted

    • Protected queue submissions, through which protected command buffers can be submitted

  • Queue operations

    • Unprotected queue operations

    • Protected queue operations

Note

When the protectedMemory feature is enabled, all pipelines may be recorded in either protected or unprotected command buffers (or both), which may incur an extra cost on some implementations. This can be mitigated by enabling the pipelineProtectedAccess feature, in which case pipelines created with VK_PIPELINE_CREATE_PROTECTED_ACCESS_ONLY_BIT_EXT may only be recorded in protected command buffers, and pipelines created with VK_PIPELINE_CREATE_NO_PROTECTED_ACCESS_BIT_EXT may only be recorded in unprotected command buffers.
Protected Memory Access Rules