Vulkan Logo

1. Preamble

Copyright 2014-2023 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. 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.2. 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.3. 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.4. 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-I/ .

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/master/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. State setting commands update the current state of the command buffer. Some commands that perform actions (e.g. draw/dispatch) do so based on the current state set cumulatively since the start of the command buffer. The work involved in performing action commands is often allowed to overlap or to be reordered, but doing so must not alter the state to be used by each action command. In general, action commands are those commands that alter framebuffer attachments, read/write buffer or image memory, or write to query pools.

Synchronization commands introduce explicit execution and memory dependencies between two sets of action commands, where the second set of commands depends on the first set of commands. These dependencies enforce both that the execution of certain pipeline stages in the later set occurs after the execution of certain stages in the source set, and that the effects of memory accesses performed by certain pipeline stages occur in order and are visible to each other. When not enforced by an explicit dependency or implicit ordering guarantees, action commands may overlap execution or execute out of order, and may not see the side effects of each other’s memory accesses.

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

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

  • 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 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.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 a user 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 Vulkan client applications in the system. 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 labelled “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 labelled “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.

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:

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

  • Run time 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_present_timing
    VK_ERROR_PRESENT_TIMING_QUEUE_FULL_EXT = -1000208000,
  // 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,
#ifdef VK_ENABLE_BETA_EXTENSIONS
  // Provided by VK_KHR_video_encode_queue
    VK_ERROR_INVALID_VIDEO_STD_PARAMETERS_KHR = -1000299000,
#endif
  // Provided by VK_EXT_image_compression_control
    VK_ERROR_COMPRESSION_EXHAUSTED_EXT = -1000338000,
  // Provided by VK_EXT_shader_object
    VK_ERROR_INCOMPATIBLE_SHADER_BINARY_EXT = 1000482000,
  // 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,
} 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.

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

editing-note

(Jon, Bug 14966) This is a rat’s nest of complexity, both in terms of describing/enumerating places such computation may take place (other than “not shader code”) and in how implementations may do it. We have consciously deferred the resolution of this issue to post-1.0, and in the meantime, the following language inherited from the OpenGL Specification is inserted as a placeholder. Hopefully it can be tightened up considerably.

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. 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.11.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.11.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.11.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.11.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,
#ifdef VK_ENABLE_BETA_EXTENSIONS
  // Provided by VK_EXT_video_encode_h264
    VK_STRUCTURE_TYPE_VIDEO_ENCODE_H264_CAPABILITIES_EXT = 1000038000,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
  // Provided by VK_EXT_video_encode_h264
    VK_STRUCTURE_TYPE_VIDEO_ENCODE_H264_SESSION_PARAMETERS_CREATE_INFO_EXT = 1000038001,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
  // Provided by VK_EXT_video_encode_h264
    VK_STRUCTURE_TYPE_VIDEO_ENCODE_H264_SESSION_PARAMETERS_ADD_INFO_EXT = 1000038002,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
  // Provided by VK_EXT_video_encode_h264
    VK_STRUCTURE_TYPE_VIDEO_ENCODE_H264_PICTURE_INFO_EXT = 1000038003,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
  // Provided by VK_EXT_video_encode_h264
    VK_STRUCTURE_TYPE_VIDEO_ENCODE_H264_DPB_SLOT_INFO_EXT = 1000038004,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
  // Provided by VK_EXT_video_encode_h264
    VK_STRUCTURE_TYPE_VIDEO_ENCODE_H264_NALU_SLICE_INFO_EXT = 1000038005,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
  // Provided by VK_EXT_video_encode_h264
    VK_STRUCTURE_TYPE_VIDEO_ENCODE_H264_GOP_REMAINING_FRAME_INFO_EXT = 1000038006,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
  // Provided by VK_EXT_video_encode_h264
    VK_STRUCTURE_TYPE_VIDEO_ENCODE_H264_PROFILE_INFO_EXT = 1000038007,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
  // Provided by VK_EXT_video_encode_h264
    VK_STRUCTURE_TYPE_VIDEO_ENCODE_H264_RATE_CONTROL_INFO_EXT = 1000038008,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
  // Provided by VK_EXT_video_encode_h264
    VK_STRUCTURE_TYPE_VIDEO_ENCODE_H264_RATE_CONTROL_LAYER_INFO_EXT = 1000038009,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
  // Provided by VK_EXT_video_encode_h264
    VK_STRUCTURE_TYPE_VIDEO_ENCODE_H264_SESSION_CREATE_INFO_EXT = 1000038010,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
  // Provided by VK_EXT_video_encode_h264
    VK_STRUCTURE_TYPE_VIDEO_ENCODE_H264_QUALITY_LEVEL_PROPERTIES_EXT = 1000038011,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
  // Provided by VK_EXT_video_encode_h264
    VK_STRUCTURE_TYPE_VIDEO_ENCODE_H264_SESSION_PARAMETERS_GET_INFO_EXT = 1000038012,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
  // Provided by VK_EXT_video_encode_h264
    VK_STRUCTURE_TYPE_VIDEO_ENCODE_H264_SESSION_PARAMETERS_FEEDBACK_INFO_EXT = 1000038013,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
  // Provided by VK_EXT_video_encode_h265
    VK_STRUCTURE_TYPE_VIDEO_ENCODE_H265_CAPABILITIES_EXT = 1000039000,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
  // Provided by VK_EXT_video_encode_h265
    VK_STRUCTURE_TYPE_VIDEO_ENCODE_H265_SESSION_PARAMETERS_CREATE_INFO_EXT = 1000039001,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
  // Provided by VK_EXT_video_encode_h265
    VK_STRUCTURE_TYPE_VIDEO_ENCODE_H265_SESSION_PARAMETERS_ADD_INFO_EXT = 1000039002,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
  // Provided by VK_EXT_video_encode_h265
    VK_STRUCTURE_TYPE_VIDEO_ENCODE_H265_PICTURE_INFO_EXT = 1000039003,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
  // Provided by VK_EXT_video_encode_h265
    VK_STRUCTURE_TYPE_VIDEO_ENCODE_H265_DPB_SLOT_INFO_EXT = 1000039004,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
  // Provided by VK_EXT_video_encode_h265
    VK_STRUCTURE_TYPE_VIDEO_ENCODE_H265_NALU_SLICE_SEGMENT_INFO_EXT = 1000039005,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
  // Provided by VK_EXT_video_encode_h265
    VK_STRUCTURE_TYPE_VIDEO_ENCODE_H265_GOP_REMAINING_FRAME_INFO_EXT = 1000039006,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
  // Provided by VK_EXT_video_encode_h265
    VK_STRUCTURE_TYPE_VIDEO_ENCODE_H265_PROFILE_INFO_EXT = 1000039007,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
  // Provided by VK_EXT_video_encode_h265
    VK_STRUCTURE_TYPE_VIDEO_ENCODE_H265_RATE_CONTROL_INFO_EXT = 1000039009,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
  // Provided by VK_EXT_video_encode_h265
    VK_STRUCTURE_TYPE_VIDEO_ENCODE_H265_RATE_CONTROL_LAYER_INFO_EXT = 1000039010,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
  // Provided by VK_EXT_video_encode_h265
    VK_STRUCTURE_TYPE_VIDEO_ENCODE_H265_SESSION_CREATE_INFO_EXT = 1000039011,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
  // Provided by VK_EXT_video_encode_h265
    VK_STRUCTURE_TYPE_VIDEO_ENCODE_H265_QUALITY_LEVEL_PROPERTIES_EXT = 1000039012,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
  // Provided by VK_EXT_video_encode_h265
    VK_STRUCTURE_TYPE_VIDEO_ENCODE_H265_SESSION_PARAMETERS_GET_INFO_EXT = 1000039013,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
  // Provided by VK_EXT_video_encode_h265
    VK_STRUCTURE_TYPE_VIDEO_ENCODE_H265_SESSION_PARAMETERS_FEEDBACK_INFO_EXT = 1000039014,
#endif
  // 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_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_KHR_format_feature_flags2 with VK_ANDROID_external_memory_android_hardware_buffer
    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_KHR_format_feature_flags2 with VK_EXT_image_drm_format_modifier
    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_EXT_calibrated_timestamps
    VK_STRUCTURE_TYPE_CALIBRATED_TIMESTAMP_INFO_EXT = 1000184000,
  // 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_EXT_vertex_attribute_divisor
    VK_STRUCTURE_TYPE_PIPELINE_VERTEX_INPUT_DIVISOR_STATE_CREATE_INFO_EXT = 1000190001,
  // Provided by VK_EXT_vertex_attribute_divisor
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VERTEX_ATTRIBUTE_DIVISOR_FEATURES_EXT = 1000190002,
  // Provided by VK_GGP_frame_token
    VK_STRUCTURE_TYPE_PRESENT_FRAME_TOKEN_GGP = 1000191000,
  // Provided by VK_NV_compute_shader_derivatives
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_COMPUTE_SHADER_DERIVATIVES_FEATURES_NV = 1000201000,
  // 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_EXT_present_timing
    VK_STRUCTURE_TYPE_SWAPCHAIN_TIMING_PROPERTIES_EXT = 1000208000,
  // Provided by VK_EXT_present_timing
    VK_STRUCTURE_TYPE_SWAPCHAIN_TIME_DOMAIN_PROPERTIES_EXT = 1000208001,
  // Provided by VK_EXT_present_timing
    VK_STRUCTURE_TYPE_SWAPCHAIN_PRESENT_TIMING_CREATE_INFO_EXT = 1000208002,
  // Provided by VK_EXT_present_timing
    VK_STRUCTURE_TYPE_SWAPCHAIN_TIMING_INFO_EXT = 1000208003,
  // Provided by VK_EXT_present_timing
    VK_STRUCTURE_TYPE_PRESENT_TIMES_INFO_EXT = 1000208004,
  // Provided by VK_EXT_present_timing
    VK_STRUCTURE_TYPE_PAST_PRESENTATION_TIMING_EXT = 1000208005,
  // Provided by VK_EXT_present_timing
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PRESENT_TIMING_FEATURES_EXT = 1000208006,
  // Provided by VK_EXT_present_timing
    VK_STRUCTURE_TYPE_PRESENT_TIMING_SURFACE_CAPABILITIES_EXT = 1000208007,
  // Provided by VK_EXT_present_timing
    VK_STRUCTURE_TYPE_SWAPCHAIN_CALIBRATED_TIMESTAMP_INFO_EXT = 1000208008,
  // 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_EXT_shader_image_atomic_int64
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_IMAGE_ATOMIC_INT64_FEATURES_EXT = 1000234000,
  // 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_line_rasterization
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_LINE_RASTERIZATION_FEATURES_EXT = 1000259000,
  // Provided by VK_EXT_line_rasterization
    VK_STRUCTURE_TYPE_PIPELINE_RASTERIZATION_LINE_STATE_CREATE_INFO_EXT = 1000259001,
  // Provided by VK_EXT_line_rasterization
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_LINE_RASTERIZATION_PROPERTIES_EXT = 1000259002,
  // Provided by VK_EXT_shader_atomic_float
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_ATOMIC_FLOAT_FEATURES_EXT = 1000260000,
  // Provided by VK_EXT_index_type_uint8
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_INDEX_TYPE_UINT8_FEATURES_EXT = 1000265000,
  // 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_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,
#ifdef VK_ENABLE_BETA_EXTENSIONS
  // Provided by VK_KHR_video_encode_queue
    VK_STRUCTURE_TYPE_VIDEO_ENCODE_INFO_KHR = 1000299000,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
  // Provided by VK_KHR_video_encode_queue
    VK_STRUCTURE_TYPE_VIDEO_ENCODE_RATE_CONTROL_INFO_KHR = 1000299001,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
  // Provided by VK_KHR_video_encode_queue
    VK_STRUCTURE_TYPE_VIDEO_ENCODE_RATE_CONTROL_LAYER_INFO_KHR = 1000299002,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
  // Provided by VK_KHR_video_encode_queue
    VK_STRUCTURE_TYPE_VIDEO_ENCODE_CAPABILITIES_KHR = 1000299003,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
  // Provided by VK_KHR_video_encode_queue
    VK_STRUCTURE_TYPE_VIDEO_ENCODE_USAGE_INFO_KHR = 1000299004,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
  // Provided by VK_KHR_video_encode_queue
    VK_STRUCTURE_TYPE_QUERY_POOL_VIDEO_ENCODE_FEEDBACK_CREATE_INFO_KHR = 1000299005,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
  // Provided by VK_KHR_video_encode_queue
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VIDEO_ENCODE_QUALITY_LEVEL_INFO_KHR = 1000299006,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
  // Provided by VK_KHR_video_encode_queue
    VK_STRUCTURE_TYPE_VIDEO_ENCODE_QUALITY_LEVEL_PROPERTIES_KHR = 1000299007,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
  // Provided by VK_KHR_video_encode_queue
    VK_STRUCTURE_TYPE_VIDEO_ENCODE_QUALITY_LEVEL_INFO_KHR = 1000299008,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
  // Provided by VK_KHR_video_encode_queue
    VK_STRUCTURE_TYPE_VIDEO_ENCODE_SESSION_PARAMETERS_GET_INFO_KHR = 1000299009,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
  // Provided by VK_KHR_video_encode_queue
    VK_STRUCTURE_TYPE_VIDEO_ENCODE_SESSION_PARAMETERS_FEEDBACK_INFO_KHR = 1000299010,
#endif
  // 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_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_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_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_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_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_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_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_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_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_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_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_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_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_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_NV_descriptor_pool_overallocation
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DESCRIPTOR_POOL_OVERALLOCATION_FEATURES_NV = 1000546000,
  // 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 = 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 = 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_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_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 = 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_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_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.12. 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 with the command:

// 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 with the command:

// 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. Core commands beyond that version which are supported by 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 the physical-device version is 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 behaviour 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
    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

  • 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 is disabled. 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, the shader validation and GPU-assisted validation features are also disabled.

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

The VkDirectDriverLoadingListLUNARG structure is defined as:

// Provided by VK_LUNARG_direct_driver_loading
typedef struct VkDirectDriverLoadingListLUNARG {
    VkStructureType                           sType;
    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 user 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_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.

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 version of the Vulkan conformance test this driver is conformant against (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 nonuniform indexing. If this is VK_FALSE, then a single dynamic instance of an instruction that nonuniformly 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 nonuniform indexing. If this is VK_FALSE, then a single dynamic instance of an instruction that nonuniformly 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 nonuniform indexing. If this is VK_FALSE, then a single dynamic instance of an instruction that nonuniformly 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 nonuniform indexing. If this is VK_FALSE, then a single dynamic instance of an instruction that nonuniformly 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 nonuniform indexing. If this is VK_FALSE, then a single dynamic instance of an instruction that nonuniformly 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 version of the Vulkan conformance test this driver is conformant against (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,
  // 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

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 user 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,
#ifdef VK_ENABLE_BETA_EXTENSIONS
  // Provided by VK_KHR_video_encode_queue
    VK_QUEUE_VIDEO_ENCODE_BIT_KHR = 0x00000040,
#endif
  // 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 definition of VkQueueFamilyGlobalPriorityPropertiesKHR is:

// 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_EXT VkQueueGlobalPriorityEXT 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

  • VUID-VkQueueFamilyGlobalPriorityPropertiesKHR-priorities-parameter
    Each element of priorities must be a valid VkQueueGlobalPriorityKHR value

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 user 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 = VK_PERFORMANCE_COUNTER_SCOPE_COMMAND_BUFFER_KHR,
    VK_QUERY_SCOPE_RENDER_PASS_KHR = VK_PERFORMANCE_COUNTER_SCOPE_RENDER_PASS_KHR,
    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 = VK_PERFORMANCE_COUNTER_DESCRIPTION_PERFORMANCE_IMPACTING_BIT_KHR,
    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 user 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;
    uint32_t                           enabledLayerCount;
    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

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

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.

editing-note

TODO (piman) - I do not think we are very clear about what “in-use by the device” means.

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

Valid Usage (Implicit)

  • VUID-VkDeviceQueueCreateInfo-sType-sType
    sType must be VK_STRUCTURE_TYPE_DEVICE_QUEUE_CREATE_INFO

  • VUID-VkDeviceQueueCreateInfo-pNext-pNext
    pNext must be NULL or a pointer to a valid instance of VkDeviceQueueGlobalPriorityCreateInfoKHR

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

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.

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 behaviour 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 a queue 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 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 an 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 Transfer Acquire Operation, there must exist a previously submitted Queue Family 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, 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

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

  • VUID-VkCommandBufferSubmitInfo-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

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 Transfer Acquire Operation, there must exist a previously submitted Queue Family 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 an 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)

  • VUID-VkSubmitInfo-sType-sType
    sType must be VK_STRUCTURE_TYPE_SUBMIT_INFO

  • VUID-VkSubmitInfo-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 VkAmigoProfilingSubmitInfoSEC, VkD3D12FenceSubmitInfoKHR, VkDeviceGroupSubmitInfo, VkFrameBoundaryEXT, VkPerformanceQuerySubmitInfoKHR, VkProtectedSubmitInfo, VkTimelineSemaphoreSubmitInfo, VkWin32KeyedMutexAcquireReleaseInfoKHR, or VkWin32KeyedMutexAcquireReleaseInfoNV

  • VUID-VkSubmitInfo-sType-unique
    The sType value of each struct in the pNext chain must be unique

  • VUID-VkSubmitInfo-pWaitSemaphores-parameter
    If waitSemaphoreCount is not 0, pWaitSemaphores must be a valid pointer to an array of waitSemaphoreCount valid VkSemaphore handles

  • VUID-VkSubmitInfo-pWaitDstStageMask-parameter
    If waitSemaphoreCount is not 0, pWaitDstStageMask must be a valid pointer to an array of waitSemaphoreCount valid combinations of VkPipelineStageFlagBits values

  • VUID-VkSubmitInfo-pCommandBuffers-parameter
    If commandBufferCount is not 0, pCommandBuffers must be a valid pointer to an array of commandBufferCount valid VkCommandBuffer handles

  • VUID-VkSubmitInfo-pSignalSemaphores-parameter
    If signalSemaphoreCount is not 0, pSignalSemaphores must be a valid pointer to an array of signalSemaphoreCount valid VkSemaphore handles

  • VUID-VkSubmitInfo-commonparent
    Each of the elements of pCommandBuffers, the elements of pSignalSemaphores, and the elements of pWaitSemaphores that are valid handles of non-ignored parameters must have been created, allocated, or retrieved from the same VkDevice

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

A secondary command buffer must not be directly submitted to a queue. Instead, secondary command buffers are recorded to execute as part of a primary command buffer with the command:

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

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-06018
    If vkCmdExecuteCommands is being called within a render pass instance begun with vkCmdBeginRenderPass, its contents parameter must have been set to VK_SUBPASS_CONTENTS_SECONDARY_COMMAND_BUFFERS

  • 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

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-bufferlevel
    commandBuffer must be a primary VkCommandBuffer

  • 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

Both

Outside

Transfer
Graphics
Compute

Indirection

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

Render passes provide a useful synchronization framework for most 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:

editing-note

The many places pipeline stage flags are used are not currently listed here.

 
// 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;
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_KHR_video_encode_queue
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_VIDEO_ENCODE_BIT_KHR = 0x08000000ULL;
#endif
// 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_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;
// 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
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.

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

    • 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_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,
} 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.

  • 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_2_ACCELERATION_STRUCTURE_COPY_BIT_KHR specifies the execution of 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_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 app 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_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_NV

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;
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_KHR_video_encode_queue
static const VkAccessFlagBits2 VK_ACCESS_2_VIDEO_ENCODE_READ_BIT_KHR = 0x2000000000ULL;
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_KHR_video_encode_queue
static const VkAccessFlagBits2 VK_ACCESS_2_VIDEO_ENCODE_WRITE_BIT_KHR = 0x4000000000ULL;
#endif
// 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_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 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 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_BINDING_TABLE_READ_BIT_KHR

  • 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. Such access occurs in the VK_PIPELINE_STAGE_2_COLOR_ATTACHMENT_OUTPUT_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. 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_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_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 a 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,
} 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 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. Such access occurs in the VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_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. Such access occurs in the VK_PIPELINE_STAGE_EARLY_FRAGMENT_TESTS_BIT or VK_PIPELINE_STAGE_LATE_FRAGMENT_TESTS_BIT pipeline stages.

  • 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_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 a 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_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_SHADER_BINDING_TABLE_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_SUBPASS_SHADER_BIT_HUAWEI, VK_PIPELINE_STAGE_2_CLUSTER_CULLING_SHADER_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 were recorded to a command buffer on the host, from first to last:

    • For commands recorded outside a render pass, this includes all other commands recorded outside a render pass, including vkCmdBeginRenderPass and vkCmdEndRenderPass commands; it does not directly include commands inside a render pass.

    • For commands recorded inside a render pass, this includes all other commands recorded inside the same subpass, including the vkCmdBeginRenderPass and vkCmdEndRenderPass commands that delimit the same render pass instance; it does not include commands recorded to other subpasses. 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 client 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 (if any) 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-01137
    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 all semaphore signal operations that operate on semaphores waited on in the same batch, and that happen-before the wait completes.

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, the act of waiting for a binary semaphore also unsignals that semaphore. 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
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

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-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 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
    commandBuffer’s current device mask 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 either include only pipeline stages valid for the queue family that was used to create the command pool that commandBuffer was allocated from, or include only VK_PIPELINE_STAGE_2_HOST_BIT

  • 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 operations within the same subpass .

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 or depth/stencil attachment

  • 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 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-shaderTileImageColorReadAccess-08718
    If vkCmdPipelineBarrier2 is called within a render pass instance the render pass must not have been started with vkCmdBeginRendering

  • VUID-vkCmdPipelineBarrier2-synchronization2-03848
    The synchronization2 feature must be enabled

  • VUID-vkCmdPipelineBarrier2-srcStageMask-03849
    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-vkCmdPipelineBarrier2-dstStageMask-03850
    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-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 an 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 or depth/stencil attachment

  • 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 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-shaderTileImageColorReadAccess-08718
    If vkCmdPipelineBarrier is called within a render pass instance the render pass must not have been started with vkCmdBeginRendering

  • 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

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, VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_COPY_BIT_KHR, or 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, VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_COPY_BIT_KHR, or 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 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 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 and access scopes do not synchronize operations on that queue. 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 and access scopes do not synchronize operations on that queue.

A queue family 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, VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_COPY_BIT_KHR, or 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, VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_COPY_BIT_KHR, or 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 access scope includes no access, as if dstAccessMask was 0.

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 access scope includes no access, as if srcAccessMask was 0.

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 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 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 and access scopes do not synchronize operations on that queue. 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 and access scopes do not synchronize operations on that queue.

A queue family 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 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, VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_COPY_BIT_KHR, or 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, VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_COPY_BIT_KHR, or 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-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-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-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-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-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 access scope includes no access, as if dstAccessMask was 0.

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 access scope includes no access, as if srcAccessMask was 0.

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

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, and happens-before operations specified in the second synchronization scope of the calling command.

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-after operations in the first synchronization scope of the calling command, and happens-before the visibility operation.

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.

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.

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_EXT_calibrated_timestamps
VkResult vkGetCalibratedTimestampsEXT(
    VkDevice                                    device,
    uint32_t                                    timestampCount,
    const VkCalibratedTimestampInfoEXT*         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 VkCalibratedTimestampInfoEXT 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 vkGetCalibratedTimestampsEXT 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 (Implicit)

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

  • VUID-vkGetCalibratedTimestampsEXT-pTimestampInfos-parameter
    pTimestampInfos must be a valid pointer to an array of timestampCount valid VkCalibratedTimestampInfoEXT structures

  • VUID-vkGetCalibratedTimestampsEXT-pTimestamps-parameter
    pTimestamps must be a valid pointer to an array of timestampCount uint64_t values

  • VUID-vkGetCalibratedTimestampsEXT-pMaxDeviation-parameter
    pMaxDeviation must be a valid pointer to a uint64_t value

  • VUID-vkGetCalibratedTimestampsEXT-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 VkCalibratedTimestampInfoEXT structure is defined as:

// Provided by VK_EXT_calibrated_timestamps
typedef struct VkCalibratedTimestampInfoEXT {
    VkStructureType    sType;
    const void*        pNext;
    VkTimeDomainEXT    timeDomain;
} VkCalibratedTimestampInfoEXT;

  • sType is a VkStructureType value identifying this structure.

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

  • timeDomain is a VkTimeDomainEXT value specifying the time domain from which the calibrated timestamp value should be returned.

Valid Usage
Valid Usage (Implicit)

  • VUID-VkCalibratedTimestampInfoEXT-sType-sType
    sType must be VK_STRUCTURE_TYPE_CALIBRATED_TIMESTAMP_INFO_EXT

  • VUID-VkCalibratedTimestampInfoEXT-pNext-pNext
    pNext must be NULL or a pointer to a valid instance of VkSwapchainCalibratedTimestampInfoEXT

  • VUID-VkCalibratedTimestampInfoEXT-sType-unique
    The sType value of each struct in the pNext chain must be unique

  • VUID-VkCalibratedTimestampInfoEXT-timeDomain-parameter
    timeDomain must be a valid VkTimeDomainEXT value

The set of supported time domains consists of:

// Provided by VK_EXT_calibrated_timestamps
typedef enum VkTimeDomainEXT {
    VK_TIME_DOMAIN_DEVICE_EXT = 0,
    VK_TIME_DOMAIN_CLOCK_MONOTONIC_EXT = 1,
    VK_TIME_DOMAIN_CLOCK_MONOTONIC_RAW_EXT = 2,
    VK_TIME_DOMAIN_QUERY_PERFORMANCE_COUNTER_EXT = 3,
  // Provided by VK_EXT_present_timing
    VK_TIME_DOMAIN_SWAPCHAIN_LOCAL_EXT = 1000208000,
} VkTimeDomainEXT;

  • VK_TIME_DOMAIN_DEVICE_EXT 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_SWAPCHAIN_LOCAL_EXT specifies a time domain unique to a particular swapchain. Timestamp values in this time domain are in units of nanosecond and are comparable only with other values from the same swapchain.

  • VK_TIME_DOMAIN_CLOCK_MONOTONIC_EXT 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_EXT_calibrated_timestamps will use the same time domain for all its VkQueue so that timestamp values reported for VK_TIME_DOMAIN_DEVICE_EXT 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_EXT 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_EXT 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;

The VkSwapchainCalibratedTimestampInfoEXT structure is defined as:

// Provided by VK_EXT_present_timing
typedef struct VkSwapchainCalibratedTimestampInfoEXT {
    VkStructureType    sType;
    const void*        pNext;
    VkSwapchainKHR     swapchain;
} VkSwapchainCalibratedTimestampInfoEXT;

  • sType is the type of this structure.

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

  • swapchain is the swapchain to retrieve the VK_TIME_DOMAIN_SWAPCHAIN_LOCAL_EXT timestamp from.

Valid Usage (Implicit)

  • VUID-VkSwapchainCalibratedTimestampInfoEXT-sType-sType
    sType must be VK_STRUCTURE_TYPE_SWAPCHAIN_CALIBRATED_TIMESTAMP_INFO_EXT

  • VUID-VkSwapchainCalibratedTimestampInfoEXT-swapchain-parameter
    swapchain must be a valid VkSwapchainKHR handle

Host Synchronization

  • Host access to swapchain must be externally synchronized

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, pRenderingInfo->flags must not include VK_RENDERING_CONTENTS_SECONDARY_COMMAND_BUFFERS_BIT

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_KHR_dynamic_rendering with VK_QCOM_tile_properties
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, 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
    If none of the VK_AMD_mixed_attachment_samples extension, the VK_NV_framebuffer_mixed_samples extension, or the multisampledRenderToSingleSampled feature are enabled, imageView members of pDepthAttachment, pStencilAttachment, and elements of pColorAttachments that are not VK_NULL_HANDLE must have been created with the same sampleCount

  • 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-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-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-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-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-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-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 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-06120
    If 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-06121
    If 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-06122
    If 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

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_VERSION_1_3 with VK_EXT_legacy_dithering, VK_KHR_dynamic_rendering with VK_EXT_legacy_dithering
    VK_RENDERING_ENABLE_LEGACY_DITHERING_BIT_EXT = 0x00000008,
    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,
} 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.

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

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 multisampled data written to imageView will be resolved.

  • resolveImageView is an image view used to write resolved multisample 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, 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.

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.

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
    If imageView is not VK_NULL_HANDLE, resolveMode is not VK_RESOLVE_MODE_NONE, and the pNext chain of VkRenderingInfo does not includes a VkMultisampledRenderToSingleSampledInfoEXT structure with the multisampledRenderToSingleSampledEnable field equal to VK_TRUE, imageView must not have a sample count of VK_SAMPLE_COUNT_1_BIT

  • VUID-VkRenderingAttachmentInfo-imageView-06862
    If imageView is not VK_NULL_HANDLE, resolveMode is not VK_RESOLVE_MODE_NONE, and the pNext chain of VkRenderingInfo does not includes a VkMultisampledRenderToSingleSampledInfoEXT structure with the multisampledRenderToSingleSampledEnable field equal to VK_TRUE, resolveImageView must not be VK_NULL_HANDLE

  • 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

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, layout 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 VK_KHR_multiview 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 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

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 (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-06698
    format must not be VK_FORMAT_UNDEFINED

  • 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 bit value that is set in imageCreateSampleCounts (as defined in Image Creation Limits) for the given format

  • 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-06868
    If neither the VK_AMD_mixed_attachment_samples extension nor the VK_NV_framebuffer_mixed_samples extension is enabled, 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-pColorAttachments-01506
    If the VK_AMD_mixed_attachment_samples extension 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 neither the VK_AMD_mixed_attachment_samples nor the VK_NV_framebuffer_mixed_samples extensions are enabled, and if pDepthStencilAttachment is not VK_ATTACHMENT_UNUSED and any attachments in pColorAttachments are not VK_ATTACHMENT_UNUSED, they must have the same sample count

  • 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

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.

editing-note

The following two alleged implicit dependencies are practically no-ops, as the operations they describe are already guaranteed by semaphores and submission order (so they are almost entirely no-ops on their own). The only reason they exist is because it simplifies reasoning about where automatic layout transitions happen. Further rewrites of this chapter could potentially remove the need for these.

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

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

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.

Valid Usage

  • VUID-VkAttachmentDescription2-format-06698
    format must not be VK_FORMAT_UNDEFINED

  • 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 bit value that is set in imageCreateSampleCounts (as defined in Image Creation Limits) for the given format

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

Valid Usage (Implicit)

  • VUID-VkAttachmentDescription2-sType-sType
    sType must be VK_STRUCTURE_TYPE_ATTACHMENT_DESCRIPTION_2

  • VUID-VkAttachmentDescription2-pNext-pNext
    pNext must be NULL or a pointer to a valid instance of VkAttachmentDescriptionStencilLayout

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

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-03065
    If 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-pResolveAttachments-03066
    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-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-pResolveAttachments-03068
    Each element of pResolveAttachments must have the same VkFormat as its corresponding color attachment

  • VUID-VkSubpassDescription2-multisampledRenderToSingleSampled-06869
    If none of the VK_AMD_mixed_attachment_samples extension, the VK_NV_framebuffer_mixed_samples extension, or the multisampledRenderToSingleSampled feature are 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 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-02899
    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-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-pColorAttachments-03070
    If the VK_AMD_mixed_attachment_samples extension 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
    If none of the VK_AMD_mixed_attachment_samples extension, the VK_NV_framebuffer_mixed_samples extension, or the multisampledRenderToSingleSampled feature are enabled, all attachments in pDepthStencilAttachment or pColorAttachments that are not VK_ATTACHMENT_UNUSED must have the same sample count

  • 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

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

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-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 bit 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
    If renderPass was specified with non-zero view masks, each element of pAttachments that is referenced by fragmentDensityMapAttachment must have a layerCount equal to 1 or greater than the index of the most significant bit set in any of those view masks

  • VUID-VkFramebufferCreateInfo-renderPass-02747
    If renderPass was specified with all view masks equal to zero, each element of pAttachments that is referenced by fragmentDensityMapAttachment must have a layerCount equal to 1

  • 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-renderPass-08921
    If renderPass was specified with non-zero view masks, each element of pAttachments that is used as a fragment shading rate attachment must have a layerCount equal to 1 or greater than the index of the most significant bit set in any of those view masks

  • VUID-VkFramebufferCreateInfo-flags-04539
    If 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 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 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 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, 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-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

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

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, 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_EXT_load_store_op_none
    VK_ATTACHMENT_LOAD_OP_NONE_EXT = 1000400000,
} 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_EXT 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 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_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 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_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.

When no resolve mode is specified, VK_RESOLVE_MODE_AVERAGE_BIT is used.

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

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

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 (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,
} 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.

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 <features-multiview-per-view-render-areas,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 least one greater than the most significant bit set in any 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 fragmentDensityMapOffsets 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 set to 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 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.

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

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

9.4. 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.4.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 are terminated when all non-helper invocations in the same derivative group either terminate or become helper invocations via OpDemoteToHelperInvocationEXT or OpKill.

A shader stage for a given command completes execution when all invocations for that stage have terminated.

9.5. 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.6. 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.7. 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.7.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.8. 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.8.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.9. 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.9.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.10. 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.10.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.11. 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 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-04873
    The extendedDynamicState2PatchControlPoints feature must be enabled

  • 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.11.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.12. 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.12.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.13. 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.13.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.14. 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.15. 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.16. Ray Generation Shaders

A ray generation shader is similar to a compute shader. Its main purpose is to execute ray tracing queries using OpTraceRayKHR instructions and process the results.

9.16.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.17. 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.17.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.18. 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.18.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.19. 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 OpTraceRayKHR to recursively trace rays.

9.19.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.20. Miss Shaders

Miss shaders can access the ray payload and can trace new rays through the OpTraceRayKHR instruction, but cannot access attributes since they are not associated with an intersection.

9.20.1. Miss Shader Execution

A miss shader is executed instead of a closest hit shader if no intersection was found during traversal.

9.21. Callable Shaders

Callable shaders can access a callable payload that works similarly to ray payloads to do subroutine work.

9.21.1. Callable Shader Execution

A callable shader is executed by calling OpExecuteCallableKHR from an allowed shader stage.

9.22. 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.23. 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.24. 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.24.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.24.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.24.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.24.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.24.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.24.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.24.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.24.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

In shaders, there are two kinds of uniformity that are of primary interest to applications: uniform within an invocation group (a.k.a. dynamically uniform), and uniform within a subgroup scope.

While one could make the assumption that being uniform in invocation group implies being uniform in subgroup scope, it is not necessarily the case for shader stages without defined workgroups.

For shader stages with defined workgroups however, the relationship between invocation group and subgroup scope is well defined as a subgroup is a subset of the workgroup, and the workgroup is the invocation group. If a value is uniform in invocation group, it is by definition also uniform in subgroup scope. This is important if writing code like:

uniform texture2D Textures[];
uint dynamicallyUniformValue = gl_WorkGroupID.x;
vec4 value = texelFetch(Textures[dynamicallyUniformValue], coord, 0);

// subgroupUniformValue is guaranteed to be uniform within the subgroup.
// This value also happens to be dynamically uniform.
vec4 subgroupUniformValue = subgroupBroadcastFirst(dynamicallyUniformValue);

In shader stages without defined workgroups, this gets complicated. Due to scoping rules, there is no guarantee that a subgroup is a subset of the invocation group, which in turn defines the scope for dynamically uniform. In graphics, the invocation group is a single draw command, except for multi-draw situations, and indirect draws with drawCount > 1, where there are multiple invocation groups, one per DrawIndex.

// Assume SubgroupSize = 8, where 3 draws are packed together.
// Two subgroups were generated.
uniform texture2D Textures[];

// DrawIndex builtin is dynamically uniform
uint dynamicallyUniformValue = gl_DrawID;
//              | gl_DrawID = 0 | gl_DrawID = 1 | }
// Subgroup 0: { 0, 0, 0, 0,      1, 1, 1, 1 }
//              | DrawID = 2 | DrawID = 1 | }
// Subgroup 1: { 2, 2, 2, 2,      1, 1, 1, 1 }

uint notActuallyDynamicallyUniformAnymore =
    subgroupBroadcastFirst(dynamicallyUniformValue);
//              | gl_DrawID = 0 | gl_DrawID = 1 | }
// Subgroup 0: { 0, 0, 0, 0,      0, 0, 0, 0 }
//              | gl_DrawID = 2 | gl_DrawID = 1 | }
// Subgroup 1: { 2, 2, 2, 2,      2, 2, 2, 2 }

// Bug. gl_DrawID = 1's invocation group observes both index 0 and 2.
vec4 value = texelFetch(Textures[notActuallyDynamicallyUniformAnymore],
                        coord, 0);

Another problematic scenario is when a shader attempts to help the compiler notice that a value is uniform in subgroup scope to potentially improve performance.

layout(location = 0) flat in dynamicallyUniformIndex;
// Vertex shader might have emitted a value that depends only on gl_DrawID,
// making it dynamically uniform.
// Give knowledge to compiler that the flat input is dynamically uniform,
// as this is not a guarantee otherwise.

uint uniformIndex = subgroupBroadcastFirst(dynamicallyUniformIndex);
// Hazard: If different draw commands are packed into one subgroup, the uniformIndex is wrong.

DrawData d = UBO.perDrawData[uniformIndex];

For implementations where subgroups are packed across draws, the implementation must make sure to handle descriptor indexing correctly. From the specification’s point of view, a dynamically uniform index does not require NonUniform decoration, and such an implementation will likely either promote descriptor indexing into NonUniform on its own, or handle non-uniformity implicitly.

9.24.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 compute shader, if the DerivativeGroupQuadsNV 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 compute shader, if the DerivativeGroupLinearNV 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 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.24.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 neighbouring 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.24.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.25. 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.25.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.25.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.25.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.25.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.25.5. Shuffle Group Operations

The shuffle group operations allow invocations to read values from other invocations within a group.

9.25.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.25.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. 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 quad group 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.

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.27. 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 is equivalent to the quad scope instance for a compute shader invocation, or the primitive scope instance for a fragment shader invocation.

Derivatives are calculated assuming that P is piecewise linear and continuous within the derivative group. All dynamic instances of explicit derivative instructions (OpDPdx*, OpDPdy*, and OpFwidth*) must be executed in control flow that is uniform within a derivative group. For other derivative operations, results are undefined if a dynamic instance is executed in control flow that is not uniform within the derivative group.

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

For group operations other than derivative and quad group operations, helper invocations may be treated as inactive even if they would be considered otherwise active.

Helper invocations may become permanently inactive if all invocations in a quad scope instance become helper invocations.

9.29. 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_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 user 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 VkCooperativeMatrixPropertiesNV structure describes a single supported combination of types for a matrix multiply/add operation ( OpCooperativeMatrixMulAddNV ). The multiply can be described in terms of the following variables and types (in SPIR-V pseudocode):

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

  • VUID-VkCooperativeMatrixPropertiesNV-AType-parameter
    AType must be a valid VkComponentTypeNV value

  • VUID-VkCooperativeMatrixPropertiesNV-BType-parameter
    BType must be a valid VkComponentTypeNV value

  • VUID-VkCooperativeMatrixPropertiesNV-CType-parameter
    CType must be a valid VkComponentTypeNV value

  • VUID-VkCooperativeMatrixPropertiesNV-DType-parameter
    DType must be a valid VkComponentTypeNV value

  • VUID-VkCooperativeMatrixPropertiesNV-scope-parameter
    scope must be a valid VkScopeNV value

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

  • VK_COMPONENT_TYPE_SINT16_KHR corresponds to SPIR-V OpTypeInt 16 1.

  • VK_COMPONENT_TYPE_SINT32_KHR corresponds to SPIR-V OpTypeInt 32 1.

  • VK_COMPONENT_TYPE_SINT64_KHR corresponds to SPIR-V OpTypeInt 64 1.

  • VK_COMPONENT_TYPE_UINT8_KHR corresponds to SPIR-V OpTypeInt 8 0.

  • VK_COMPONENT_TYPE_UINT16_KHR corresponds to SPIR-V OpTypeInt 16 0.

  • VK_COMPONENT_TYPE_UINT32_KHR corresponds to SPIR-V OpTypeInt 32 0.

  • VK_COMPONENT_TYPE_UINT64_KHR corresponds to SPIR-V OpTypeInt 64 0.

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

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.

No state, including dynamic state, is inherited from one command buffer to another.

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

    editing-note

    TODO (Jon) - Should we say something like “the i’th element of the pPipelines array is created based on the corresponding element of the pCreateInfos array”? Also for vkCreateGraphicsPipelines below.
Valid Usage

  • 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

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.

Valid Usage

  • 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 both the shader stage and range

  • 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-02874
    flags must not include VK_PIPELINE_CREATE_INDIRECT_BINDABLE_BIT_NV

  • 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-flags-03364
    flags must not include VK_PIPELINE_CREATE_LIBRARY_BIT_KHR

  • 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

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 any variables in its interface that are declared with the ClipDistance or 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-00712
    If 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-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-00718
    If stage is VK_SHADER_STAGE_FRAGMENT_BIT, the identified entry point must not include any output variables in its interface decorated with CullDistance

  • 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-stage-06844
    If a shader module identifier is specified for this stage, a VkShaderModuleCreateInfo structure must not be present in the pNext chain

  • 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

  • VUID-VkPipelineShaderStageCreateInfo-stage-06846
    If a shader module identifier is not specified for this stage, and the graphicsPipelineLibrary feature is not enabled, module must be a valid VkShaderModule

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

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

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

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 a VkExtent2D structure

  • VUID-vkGetDeviceSubpassShadingMaxWorkgroupSizeHUAWEI-renderpass-parent
    renderpass 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

  • 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 behaviour 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 behaviour 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 behaviour of out of bounds accesses made to vertex input attributes

  • images describes the behaviour 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

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

Valid Usage

  • 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

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.

Valid Usage

  • 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 both the shader stage and range

  • 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-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-stage-02096
    If the pipeline requires pre-rasterization shader state the stage member of one element of pStages must be either VK_SHADER_STAGE_VERTEX_BIT or VK_SHADER_STAGE_MESH_BIT_EXT

  • 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

  • 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

  • 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

  • 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, and the pipeline is being created with fragment output interface state, and the pColorBlendState pointer is not NULL, 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 either the VK_EXT_extended_dynamic_state3 extension is not enabled, or either the VK_DYNAMIC_STATE_VIEWPORT_WITH_COUNT or VK_DYNAMIC_STATE_SCISSOR_WITH_COUNT dynamic states are 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-pViewportState-04892
    If the pipeline requires pre-rasterization shader state, and the graphics pipeline state was created with the VK_DYNAMIC_STATE_RASTERIZER_DISCARD_ENABLE dynamic state enabled, pViewportState 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 is 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 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-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 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-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, and 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-06049
    If renderPass is not VK_NULL_HANDLE, the pipeline is being created with pre-rasterization shader state, and subpass viewMask is not 0, all of the shaders in the pipeline must not write to the Layer built-in output

  • 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-07717
    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 ViewMask 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 the VK_EXT_extended_dynamic_state3 extension is not enabled, or either VK_DYNAMIC_STATE_PRIMITIVE_RESTART_ENABLE, or VK_DYNAMIC_STATE_PRIMITIVE_TOPOLOGY dynamic states are not set, or dynamicPrimitiveTopologyUnrestricted is VK_FALSE, 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 VkPipelineRasterizationLineStateCreateInfoEXT structure included in the pNext chain of pRasterizationState is VK_LINE_RASTERIZATION_MODE_BRESENHAM_EXT or VK_LINE_RASTERIZATION_MODE_RECTANGULAR_SMOOTH_EXT, 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 VkPipelineRasterizationLineStateCreateInfoEXT is VK_TRUE, and no element of the pDynamicStates member of pDynamicState is VK_DYNAMIC_STATE_LINE_STIPPLE_EXT, then the lineStippleFactor member of VkPipelineRasterizationLineStateCreateInfoEXT 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-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-renderPass-06575
    If the pipeline requires pre-rasterization shader state, fragment shader state, or fragment output interface state, renderPass must be VK_NULL_HANDLE or a valid render pass object

  • 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 VkPipelineRenderingCreateInfo::colorAttachmentCount is not equal to 0, 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 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-07718
    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 write to the Layer built-in output

  • 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-07719
    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 ViewIndex 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 pipeline requires fragment shader state and renderPass is VK_NULL_HANDLE, fragment shaders in pStages must not include the InputAttachment capability

  • 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 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-flags-06483
    If 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-flags-06484
    If 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 subpass must have been created with VK_SUBPASS_DESCRIPTION_RASTERIZATION_ORDER_ATTACHMENT_COLOR_ACCESS_BIT_EXT

  • VUID-VkGraphicsPipelineCreateInfo-flags-06485
    If the pipeline requires fragment shader state 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-flags-06486
    If the pipeline requires fragment shader state 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-pRasterizationState-09039
    If 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 are 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-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 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-06604
    If the pipeline requires pre-rasterization shader state or fragment 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-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, 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 be VK_NULL_HANDLE

  • VUID-VkGraphicsPipelineCreateInfo-flags-06680
    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 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-pMultisampleState-06629
    If the pipeline requires fragment shader state pMultisampleState must be NULL or a valid pointer to a valid VkPipelineMultisampleStateCreateInfo structure

  • VUID-VkGraphicsPipelineCreateInfo-renderpass-06631
    If the pipeline requires fragment shader state and renderpass is not VK_NULL_HANDLE, then pMultisampleState must not be NULL

  • 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, then pMultisampleState must not be NULL

  • 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->sampleShading 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->sampleShading is VK_TRUE, and an element of VkPipelineLibraryCreateInfoKHR::pLibraries was created with VK_GRAPHICS_PIPELINE_LIBRARY_FRAGMENT_SHADER_BIT_EXT, the pMultisampleState used to create that library must be identically defined pMultisampleState

  • 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-09041
    If VkGraphicsPipelineLibraryCreateInfoEXT::flags includes VK_GRAPHICS_PIPELINE_LIBRARY_PRE_RASTERIZATION_SHADERS_BIT_EXT, 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 are 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-pRasterizationState-09042
    If pRasterizationState is not NULL it must be a valid pointer to a valid VkPipelineRasterizationStateCreateInfo structure

  • 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, 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-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-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-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 bit 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 pre-rasterization shader 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-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

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.

Valid Usage (Implicit)

  • VUID-VkPipelineRenderingCreateInfo-sType-sType
    sType must be VK_STRUCTURE_TYPE_PIPELINE_RENDERING_CREATE_INFO

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

  • VK_PIPELINE_CREATE_RAY_TRACING_SKIP_AABBS_BIT_KHR specifies that AABB primitives will be skipped during traversal using OpTraceRayKHR.

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

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

  • VK_PIPELINE_CREATE_RAY_TRACING_OPACITY_MICROMAP_BIT_EXT specifies that the pipeline can be used with acceleration structures which reference an opacity 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 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_line_rasterization
    VK_DYNAMIC_STATE_LINE_STIPPLE_EXT = 1000259000,
  // 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_TESSELLATION_DOMAIN_ORIGIN_EXT = 1000455002,
  // 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
    VK_DYNAMIC_STATE_RASTERIZATION_STREAM_EXT = 1000455013,
  // Provided by VK_EXT_extended_dynamic_state3
    VK_DYNAMIC_STATE_CONSERVATIVE_RASTERIZATION_MODE_EXT = 1000455014,
  // Provided by VK_EXT_extended_dynamic_state3
    VK_DYNAMIC_STATE_EXTRA_PRIMITIVE_OVERESTIMATION_SIZE_EXT = 1000455015,
  // Provided by VK_EXT_extended_dynamic_state3
    VK_DYNAMIC_STATE_DEPTH_CLIP_ENABLE_EXT = 1000455016,
  // Provided by VK_EXT_extended_dynamic_state3
    VK_DYNAMIC_STATE_SAMPLE_LOCATIONS_ENABLE_EXT = 1000455017,
  // Provided by VK_EXT_extended_dynamic_state3
    VK_DYNAMIC_STATE_COLOR_BLEND_ADVANCED_EXT = 1000455018,
  // Provided by VK_EXT_extended_dynamic_state3
    VK_DYNAMIC_STATE_PROVOKING_VERTEX_MODE_EXT = 1000455019,
  // Provided by VK_EXT_extended_dynamic_state3
    VK_DYNAMIC_STATE_LINE_RASTERIZATION_MODE_EXT = 1000455020,
  // Provided by VK_EXT_extended_dynamic_state3
    VK_DYNAMIC_STATE_LINE_STIPPLE_ENABLE_EXT = 1000455021,
  // Provided by 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_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.2.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.2.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.3. 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.

Valid Usage

  • 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

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.

Valid Usage

  • 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-03677
    If deferredOperation is not VK_NULL_HANDLE, it must be a valid VkDeferredOperationKHR object

  • VUID-vkCreateRayTracingPipelinesKHR-deferredOperation-03678
    Any previous deferred operation that was associated with deferredOperation must be complete

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

Valid Usage

  • 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 both the shader stage and range

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

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-flags-parameter
    flags must be a valid combination of VkPipelineCreateFlagBits values

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

Valid Usage

  • 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 both the shader stage and range

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

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 VkPipelineCreateFlags2CreateInfoKHR, VkPipelineCreationFeedbackCreateInfo, or VkPipelineRobustnessCreateInfoEXT

  • VUID-VkRayTracingPipelineCreateInfoKHR-sType-unique
    The sType value of each struct in the pNext chain must be unique

  • VUID-VkRayTracingPipelineCreateInfoKHR-flags-parameter
    flags must be a valid combination of VkPipelineCreateFlagBits values

  • 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 a user-allocated buffer where the results will be written.

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 a user-allocated buffer where the results will be written.

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.4. 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.5. Multiple Pipeline Creation

Multiple pipelines can be created simultaneously by passing an array of VkGraphicsPipelineCreateInfo, VkRayTracingPipelineCreateInfoKHR, VkRayTracingPipelineCreateInfoNV, or VkComputePipelineCreateInfo structures into the vkCreateGraphicsPipelines, vkCreateRayTracingPipelinesKHR, vkCreateRayTracingPipelinesNV, and vkCreateComputePipelines commands, respectively. Applications can group together similar pipelines to be created in a single call, and implementations are encouraged to look for reuse opportunities within a group-create.

When an application attempts to create many pipelines in a single command, it is possible that some subset may fail creation. In that case, the corresponding entries in the pPipelines output array will be filled with VK_NULL_HANDLE values. If any pipeline fails creation despite valid arguments (for example, due to out of memory errors), the VkResult code returned by vkCreate*Pipelines 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 had VK_PIPELINE_CREATE_EARLY_RETURN_ON_FAILURE_BIT set, pipelines at an index in the pPipelines array greater than or equal to that of the failing pipeline must be set to VK_NULL_HANDLE.

If multiple pipelines fail to be created, the VkResult must be the return value of any of the pipelines which did not return VK_SUCCESS.

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 user 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 enum 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. 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.9. 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.10. 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. 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

  • VUID-vkCmdBindPipeline-pipelineBindPoint-06653
    If pipelineBindPoint is VK_PIPELINE_BIND_POINT_GRAPHICS, pipeline must have been created without VK_PIPELINE_CREATE_LIBRARY_BIT_KHR

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.

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. 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 another pipeline bind with that state specified as static.

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.

10.12. 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 user 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 user 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 user 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 user 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 UTF-8 null-terminated 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.13. 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.14. 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 user-defined PFN_vkAllocationFunction

  • VUID-VkAllocationCallbacks-pfnReallocation-00633
    pfnReallocation must be a valid pointer to a valid user-defined PFN_vkReallocationFunction

  • VUID-VkAllocationCallbacks-pfnFree-00634
    pfnFree must be a valid pointer to a valid user-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 neighbouring 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 client to know the memory type index before allocating.

Valid Usage

  • VUID-VkMemoryAllocateInfo-None-06657
    The parameters must not define more than one import operation

  • VUID-VkMemoryAllocateInfo-allocationSize-07897
    If the parameters do not define an import or export operation, allocationSize must be greater than 0

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

editing-note

(Jon) If additional (non-Win32) bits are added to the possible memory types, this type should move to the VK_NV_external_memory_capabilities section, and each bit would then be protected by ifdefs for the extension it is defined by.

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

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 must only include bits that identify memory types which are host visible.

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)

  • VUID-VkAndroidHardwareBufferPropertiesANDROID-sType-sType
    sType must be VK_STRUCTURE_TYPE_ANDROID_HARDWARE_BUFFER_PROPERTIES_ANDROID

  • VUID-VkAndroidHardwareBufferPropertiesANDROID-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 VkAndroidHardwareBufferFormatProperties2ANDROID or VkAndroidHardwareBufferFormatPropertiesANDROID

  • VUID-VkAndroidHardwareBufferPropertiesANDROID-sType-unique
    The sType value of each struct in the pNext chain must be unique

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 writing to non-external format images is possible but writing to external format images is not.

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_KHR_format_feature_flags2 with VK_ANDROID_external_memory_android_hardware_buffer
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

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, the handle to the VkDeviceMemory must be retrieved using vkGetMemoryZirconHandleFUCHSIA:

// 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 app 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 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 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 app 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 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 app 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 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 app 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 id<MTLSharedEvent> MTLSharedEvent_id;
#else
typedef void* MTLSharedEvent_id;
#endif

11.2.11. 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.12. 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.13. 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.14. 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 reserved for future use.

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

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-zerobitmask
    flags must be 0

  • 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

// Provided by VK_VERSION_1_0
typedef VkFlags VkMemoryMapFlags;

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

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

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

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

If VkPhysicalDeviceProtectedMemoryProperties::protectedNoFault is VK_FALSE, applications must not perform any of the following operations:

  • Write to unprotected memory within protected queue operations.

  • Access protected memory within protected queue operations other than in framebuffer-space pipeline stages, the compute shader stage, or the transfer stage.

  • Perform a query within protected queue operations.

If VkPhysicalDeviceProtectedMemoryProperties::protectedNoFault is VK_TRUE, these operations are valid, but reads will return undefined values, and writes will either be dropped or store undefined values.

Additionally, indirect operations must not be performed within protected queue operations.

Whether these operations are valid or not, or if any other invalid usage is performed, the implementation must guarantee that:

  • Protected device memory must never be visible to the host.

  • Values written to unprotected device memory must not be a function of values from protected memory.

11.2.17. External Memory Handle Types

Android Hardware Buffer

Android’s NDK defines AHardwareBuffer objects, which represent device memory that is shareable across processes and that can be accessed by a variety of media APIs and the hardware used to implement them. These Android hardware buffer objects may be imported into VkDeviceMemory objects for access via Vulkan, or exported from Vulkan. An VkImage or VkBuffer can be bound to the imported or exported VkDeviceMemory object if it is created with VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID.

To remove an unnecessary compile time dependency, an incomplete type definition of AHardwareBuffer is provided in the Vulkan headers:

// Provided by VK_ANDROID_external_memory_android_hardware_buffer
struct AHardwareBuffer;

The actual AHardwareBuffer type is defined in Android NDK headers.

Note

The NDK format, usage, and size/dimensions of an AHardwareBuffer object can be obtained with the AHardwareBuffer_describe function. While Android hardware buffers can be imported to or exported from Vulkan without using that function, valid usage and implementation behavior is defined in terms of the AHardwareBuffer_Desc properties it returns.

Android hardware buffer objects are reference-counted using Android NDK functions outside of the scope of this specification. A VkDeviceMemory imported from an Android hardware buffer or that can be exported to an Android hardware buffer must acquire a reference to its AHardwareBuffer object, and must release this reference when the device memory is freed. During the host execution of a Vulkan command that has an Android hardware buffer as a parameter (including indirect parameters via pNext chains), the application must not decrement the Android hardware buffer’s reference count to zero.

Android hardware buffers can be mapped and unmapped for CPU access using the NDK functions. These lock and unlock APIs are considered to acquire and release ownership of the Android hardware buffer, and applications must follow the rules described in External Resource Sharing to transfer ownership between the Vulkan instance and these native APIs.

Android hardware buffers can be shared with external APIs and Vulkan instances on the same device, and also with foreign devices. When transferring ownership of the Android hardware buffer, the external and foreign special queue families described in Queue Family Ownership Transfer are not identical. All APIs which produce or consume Android hardware buffers are considered to use foreign devices, except OpenGL ES contexts and Vulkan logical devices that have matching device and driver UUIDs. Implementations may treat a transfer to or from the foreign queue family as if it were a transfer to or from the external queue family when the Android hardware buffer’s usage only permits it to be used on the same physical device.

Android Hardware Buffer Optimal Usages

Vulkan buffer and image usage flags do not correspond exactly to Android hardware buffer usage flags. When allocating Android hardware buffers with non-Vulkan APIs, if any AHARDWAREBUFFER_USAGE_GPU_* usage bits are included, by default the allocator must allocate the memory in such a way that it supports Vulkan usages and creation flags in the usage equivalence table which do not have Android hardware buffer equivalents.

An VkAndroidHardwareBufferUsageANDROID structure can be included in the pNext chain of a VkImageFormatProperties2 structure passed to vkGetPhysicalDeviceImageFormatProperties2 to obtain optimal Android hardware buffer usage flags for specific Vulkan resource creation parameters. Some usage flags returned by these commands are required based on the input parameters, but additional vendor-specific usage flags (AHARDWAREBUFFER_USAGE_VENDOR_*) may also be returned. Any Android hardware buffer allocated with these vendor-specific usage flags and imported to Vulkan must only be bound to resources created with parameters that are a subset of the parameters used to obtain the Android hardware buffer usage, since the memory may have been allocated in a way incompatible with other parameters. If an Android hardware buffer is successfully allocated with additional non-vendor-specific usage flags in addition to the recommended usage, it must support being used in the same ways as an Android hardware buffer allocated with only the recommended usage, and also in ways indicated by the additional usage.

Android Hardware Buffer External Formats

Android hardware buffers may represent images using implementation-specific formats, layouts, color models, etc., which do not have Vulkan equivalents. Such external formats are commonly used by external image sources such as video decoders or cameras. Vulkan can import Android hardware buffers that have external formats, but since the image contents are in an undiscoverable and possibly proprietary representation, images with external formats must only be used as sampled images, must only be sampled with a sampler that has Y′CBCR conversion enabled, and must have optimal tiling.

Images that will be backed by an Android hardware buffer can use an external format by setting VkImageCreateInfo::format to VK_FORMAT_UNDEFINED and including a VkExternalFormatANDROID structure in the pNext chain. Images can be created with an external format even if the Android hardware buffer has a format which has an equivalent Vulkan format to enable consistent handling of images from sources that might use either category of format. However, all images created with an external format are subject to the valid usage requirements associated with external formats, even if the Android hardware buffer’s format has a Vulkan equivalent. The external format of an Android hardware buffer can be obtained by passing a VkAndroidHardwareBufferFormatPropertiesANDROID structure to vkGetAndroidHardwareBufferPropertiesANDROID.

Android Hardware Buffer Image Resources

Android hardware buffers have intrinsic width, height, format, and usage properties, so Vulkan images bound to memory imported from an Android hardware buffer must use dedicated allocations: VkMemoryDedicatedRequirements::requiresDedicatedAllocation must be VK_TRUE for images created with VkExternalMemoryImageCreateInfo::handleTypes that includes VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID. When creating an image that will be bound to an imported Android hardware buffer, the image creation parameters must be equivalent to the AHardwareBuffer properties as described by the valid usage of VkMemoryAllocateInfo. Similarly, device memory allocated for a dedicated image must not be exported to an Android hardware buffer until it has been bound to that image, and the implementation must return an Android hardware buffer with properties derived from the image:

  • The width and height members of AHardwareBuffer_Desc must be the same as the width and height members of VkImageCreateInfo::extent, respectively.

  • The layers member of AHardwareBuffer_Desc must be the same as the arrayLayers member of VkImageCreateInfo.

  • The format member of AHardwareBuffer_Desc must be equivalent to VkImageCreateInfo::format as defined by AHardwareBuffer Format Equivalence.

  • The usage member of AHardwareBuffer_Desc must include bits corresponding to bits included in VkImageCreateInfo::usage and VkImageCreateInfo::flags where such a correspondence exists according to AHardwareBuffer Usage Equivalence. It may also include additional usage bits, including vendor-specific usages. Presence of vendor usage bits may make the Android hardware buffer only usable in ways indicated by the image creation parameters, even when used outside Vulkan, in a similar way that allocating the Android hardware buffer with usage returned in VkAndroidHardwareBufferUsageANDROID does.

Implementations may support fewer combinations of image creation parameters for images with Android hardware buffer external handle type than for non-external images. Support for a given set of parameters can be determined by passing VkExternalImageFormatProperties to vkGetPhysicalDeviceImageFormatProperties2 with handleType set to VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID. Any Android hardware buffer successfully allocated outside Vulkan with usage that includes AHARDWAREBUFFER_USAGE_GPU_* must be supported when using equivalent Vulkan image parameters. If a given choice of image parameters are supported for import, they can also be used to create an image and memory that will be exported to an Android hardware buffer.

Table 13. AHardwareBuffer Format Equivalence
AHardwareBuffer Format Vulkan Format

AHARDWAREBUFFER_FORMAT_R8G8B8A8_UNORM

VK_FORMAT_R8G8B8A8_UNORM

AHARDWAREBUFFER_FORMAT_R8G8B8X8_UNORM 1

VK_FORMAT_R8G8B8A8_UNORM

AHARDWAREBUFFER_FORMAT_R8G8B8_UNORM

VK_FORMAT_R8G8B8_UNORM

AHARDWAREBUFFER_FORMAT_R5G6B5_UNORM

VK_FORMAT_R5G6B5_UNORM_PACK16

AHARDWAREBUFFER_FORMAT_R16G16B16A16_FLOAT

VK_FORMAT_R16G16B16A16_SFLOAT

AHARDWAREBUFFER_FORMAT_R10G10B10A2_UNORM

VK_FORMAT_A2B10G10R10_UNORM_PACK32

AHARDWAREBUFFER_FORMAT_D16_UNORM

VK_FORMAT_D16_UNORM

AHARDWAREBUFFER_FORMAT_D24_UNORM

VK_FORMAT_X8_D24_UNORM_PACK32

AHARDWAREBUFFER_FORMAT_D24_UNORM_S8_UINT

VK_FORMAT_D24_UNORM_S8_UINT

AHARDWAREBUFFER_FORMAT_D32_FLOAT

VK_FORMAT_D32_SFLOAT

AHARDWAREBUFFER_FORMAT_D32_FLOAT_S8_UINT

VK_FORMAT_D32_SFLOAT_S8_UINT

AHARDWAREBUFFER_FORMAT_S8_UINT

VK_FORMAT_S8_UINT
Table 14. AHardwareBuffer Usage Equivalence
AHardwareBuffer Usage Vulkan Usage or Creation Flag

None

VK_IMAGE_USAGE_TRANSFER_SRC_BIT

None

VK_IMAGE_USAGE_TRANSFER_DST_BIT

AHARDWAREBUFFER_USAGE_GPU_SAMPLED_IMAGE

VK_IMAGE_USAGE_SAMPLED_BIT

AHARDWAREBUFFER_USAGE_GPU_SAMPLED_IMAGE

VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT

AHARDWAREBUFFER_USAGE_GPU_FRAMEBUFFER 3

VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT

AHARDWAREBUFFER_USAGE_GPU_FRAMEBUFFER 3

VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT

AHARDWAREBUFFER_USAGE_GPU_CUBE_MAP

VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT

AHARDWAREBUFFER_USAGE_GPU_MIPMAP_COMPLETE

None 2

AHARDWAREBUFFER_USAGE_PROTECTED_CONTENT

VK_IMAGE_CREATE_PROTECTED_BIT

None

VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT

None

VK_IMAGE_CREATE_EXTENDED_USAGE_BIT

AHARDWAREBUFFER_USAGE_GPU_DATA_BUFFER 4

VK_IMAGE_USAGE_STORAGE_BIT
1

Vulkan does not differentiate between AHARDWAREBUFFER_FORMAT_R8G8B8A8_UNORM and AHARDWAREBUFFER_FORMAT_R8G8B8X8_UNORM: they both behave as VK_FORMAT_R8G8B8A8_UNORM. After an external entity writes to a AHARDWAREBUFFER_FORMAT_R8G8B8X8_UNORM Android hardware buffer, the values read by Vulkan from the X/A component are undefined. To emulate the traditional behavior of the X component during sampling or blending, applications should use VK_COMPONENT_SWIZZLE_ONE in image view component mappings and VK_BLEND_FACTOR_ONE in color blend factors. There is no way to avoid copying these undefined values when copying from such an image to another image or buffer.

2

The AHARDWAREBUFFER_USAGE_GPU_MIPMAP_COMPLETE flag does not correspond to a Vulkan image usage or creation flag. Instead, its presence indicates that the Android hardware buffer contains a complete mipmap chain, and its absence indicates that the Android hardware buffer contains only a single mip level.

3

Only image usages valid for the format are valid. It would be invalid to take a Android Hardware Buffer with a format of AHARDWAREBUFFER_FORMAT_R8G8B8A8_UNORM that has a AHARDWAREBUFFER_USAGE_GPU_FRAMEBUFFER usage and try to create an image with VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT.

4

In combination with a hardware buffer format other than BLOB.

Note

When using VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT with Android hardware buffer images, applications should use VkImageFormatListCreateInfo to inform the implementation which view formats will be used with the image. For some common sets of format, this allows some implementations to provide significantly better performance when accessing the image via Vulkan.
Android Hardware Buffer Buffer Resources

Android hardware buffers with a format of AHARDWAREBUFFER_FORMAT_BLOB and usage that includes AHARDWAREBUFFER_USAGE_GPU_DATA_BUFFER can be used as the backing store for VkBuffer objects. Such Android hardware buffers have a size in bytes specified by their width; height and layers are both 1.

Unlike images, buffer resources backed by Android hardware buffers do not require dedicated allocations.

Exported AHardwareBuffer objects that do not have dedicated images must have a format of AHARDWAREBUFFER_FORMAT_BLOB, usage must include AHARDWAREBUFFER_USAGE_GPU_DATA_BUFFER, width must equal the device memory allocation size, and height and layers must be 1.

11.2.18. Peer Memory Features

Peer memory is memory that is allocated for a given physical device and then bound to a resource and accessed by a different physical device, in a logical device that represents multiple physical devices. Some ways of reading and writing peer memory may not be supported by a device.

To determine how peer memory can be accessed, call:

// Provided by VK_VERSION_1_1
void vkGetDeviceGroupPeerMemoryFeatures(
    VkDevice                                    device,
    uint32_t                                    heapIndex,
    uint32_t                                    localDeviceIndex,
    uint32_t                                    remoteDeviceIndex,
    VkPeerMemoryFeatureFlags*                   pPeerMemoryFeatures);

or the equivalent command

// Provided by VK_KHR_device_group
void vkGetDeviceGroupPeerMemoryFeaturesKHR(
    VkDevice                                    device,
    uint32_t                                    heapIndex,
    uint32_t                                    localDeviceIndex,
    uint32_t                                    remoteDeviceIndex,
    VkPeerMemoryFeatureFlags*                   pPeerMemoryFeatures);

  • device is the logical device that owns the memory.

  • heapIndex is the index of the memory heap from which the memory is allocated.

  • localDeviceIndex is the device index of the physical device that performs the memory access.

  • remoteDeviceIndex is the device index of the physical device that the memory is allocated for.

  • pPeerMemoryFeatures is a pointer to a VkPeerMemoryFeatureFlags bitmask indicating which types of memory accesses are supported for the combination of heap, local, and remote devices.

Valid Usage

  • VUID-vkGetDeviceGroupPeerMemoryFeatures-heapIndex-00691
    heapIndex must be less than memoryHeapCount

  • VUID-vkGetDeviceGroupPeerMemoryFeatures-localDeviceIndex-00692
    localDeviceIndex must be a valid device index

  • VUID-vkGetDeviceGroupPeerMemoryFeatures-remoteDeviceIndex-00693
    remoteDeviceIndex must be a valid device index

  • VUID-vkGetDeviceGroupPeerMemoryFeatures-localDeviceIndex-00694
    localDeviceIndex must not equal remoteDeviceIndex

Valid Usage (Implicit)

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

  • VUID-vkGetDeviceGroupPeerMemoryFeatures-pPeerMemoryFeatures-parameter
    pPeerMemoryFeatures must be a valid pointer to a VkPeerMemoryFeatureFlags value

Bits which may be set in vkGetDeviceGroupPeerMemoryFeatures::pPeerMemoryFeatures, indicating supported peer memory features, are:

// Provided by VK_VERSION_1_1
typedef enum VkPeerMemoryFeatureFlagBits {
    VK_PEER_MEMORY_FEATURE_COPY_SRC_BIT = 0x00000001,
    VK_PEER_MEMORY_FEATURE_COPY_DST_BIT = 0x00000002,
    VK_PEER_MEMORY_FEATURE_GENERIC_SRC_BIT = 0x00000004,
    VK_PEER_MEMORY_FEATURE_GENERIC_DST_BIT = 0x00000008,
  // Provided by VK_KHR_device_group
    VK_PEER_MEMORY_FEATURE_COPY_SRC_BIT_KHR = VK_PEER_MEMORY_FEATURE_COPY_SRC_BIT,
  // Provided by VK_KHR_device_group
    VK_PEER_MEMORY_FEATURE_COPY_DST_BIT_KHR = VK_PEER_MEMORY_FEATURE_COPY_DST_BIT,
  // Provided by VK_KHR_device_group
    VK_PEER_MEMORY_FEATURE_GENERIC_SRC_BIT_KHR = VK_PEER_MEMORY_FEATURE_GENERIC_SRC_BIT,
  // Provided by VK_KHR_device_group
    VK_PEER_MEMORY_FEATURE_GENERIC_DST_BIT_KHR = VK_PEER_MEMORY_FEATURE_GENERIC_DST_BIT,
} VkPeerMemoryFeatureFlagBits;

or the equivalent

// Provided by VK_KHR_device_group
typedef VkPeerMemoryFeatureFlagBits VkPeerMemoryFeatureFlagBitsKHR;

  • VK_PEER_MEMORY_FEATURE_COPY_SRC_BIT specifies that the memory can be accessed as the source of any vkCmdCopy* command.

  • VK_PEER_MEMORY_FEATURE_COPY_DST_BIT specifies that the memory can be accessed as the destination of any vkCmdCopy* command.

  • VK_PEER_MEMORY_FEATURE_GENERIC_SRC_BIT specifies that the memory can be read as any memory access type.

  • VK_PEER_MEMORY_FEATURE_GENERIC_DST_BIT specifies that the memory can be written as any memory access type. Shader atomics are considered to be writes.

Note

The peer memory features of a memory heap also apply to any accesses that may be performed during image layout transitions.

VK_PEER_MEMORY_FEATURE_COPY_DST_BIT must be supported for all host local heaps and for at least one device-local memory heap.

If a device does not support a peer memory feature, it is still valid to use a resource that includes both local and peer memory bindings with the corresponding access type as long as only the local bindings are actually accessed. For example, an application doing split-frame rendering would use framebuffer attachments that include both local and peer memory bindings, but would scissor the rendering to only update local memory.

// Provided by VK_VERSION_1_1
typedef VkFlags VkPeerMemoryFeatureFlags;

or the equivalent

// Provided by VK_KHR_device_group
typedef VkPeerMemoryFeatureFlags VkPeerMemoryFeatureFlagsKHR;

VkPeerMemoryFeatureFlags is a bitmask type for setting a mask of zero or more VkPeerMemoryFeatureFlagBits.

11.2.19. Opaque Capture Address Query

To query a 64-bit opaque capture address value from a memory object, call:

// Provided by VK_VERSION_1_2
uint64_t vkGetDeviceMemoryOpaqueCaptureAddress(
    VkDevice                                    device,
    const VkDeviceMemoryOpaqueCaptureAddressInfo* pInfo);

or the equivalent command

// Provided by VK_KHR_buffer_device_address
uint64_t vkGetDeviceMemoryOpaqueCaptureAddressKHR(
    VkDevice                                    device,
    const VkDeviceMemoryOpaqueCaptureAddressInfo* pInfo);

  • device is the logical device that the memory object was allocated on.

  • pInfo is a pointer to a VkDeviceMemoryOpaqueCaptureAddressInfo structure specifying the memory object to retrieve an address for.

The 64-bit return value is an opaque address representing the start of pInfo->memory.

If the memory object was allocated with a non-zero value of VkMemoryOpaqueCaptureAddressAllocateInfo::opaqueCaptureAddress, the return value must be the same address.

Note

The expected usage for these opaque addresses is only for trace capture/replay tools to store these addresses in a trace and subsequently specify them during replay.
Valid Usage

  • VUID-vkGetDeviceMemoryOpaqueCaptureAddress-None-03334
    The bufferDeviceAddress feature must be enabled

  • VUID-vkGetDeviceMemoryOpaqueCaptureAddress-device-03335
    If device was created with multiple physical devices, then the bufferDeviceAddressMultiDevice feature must be enabled

Valid Usage (Implicit)

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

  • VUID-vkGetDeviceMemoryOpaqueCaptureAddress-pInfo-parameter
    pInfo must be a valid pointer to a valid VkDeviceMemoryOpaqueCaptureAddressInfo structure

The VkDeviceMemoryOpaqueCaptureAddressInfo structure is defined as:

// Provided by VK_VERSION_1_2
typedef struct VkDeviceMemoryOpaqueCaptureAddressInfo {
    VkStructureType    sType;
    const void*        pNext;
    VkDeviceMemory     memory;
} VkDeviceMemoryOpaqueCaptureAddressInfo;

or the equivalent

// Provided by VK_KHR_buffer_device_address
typedef VkDeviceMemoryOpaqueCaptureAddressInfo VkDeviceMemoryOpaqueCaptureAddressInfoKHR;

  • sType is a VkStructureType value identifying this structure.

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

  • memory specifies the memory whose address is being queried.

Valid Usage

  • VUID-VkDeviceMemoryOpaqueCaptureAddressInfo-memory-03336
    memory must have been allocated with VK_MEMORY_ALLOCATE_DEVICE_ADDRESS_BIT

Valid Usage (Implicit)

  • VUID-VkDeviceMemoryOpaqueCaptureAddressInfo-sType-sType
    sType must be VK_STRUCTURE_TYPE_DEVICE_MEMORY_OPAQUE_CAPTURE_ADDRESS_INFO

  • VUID-VkDeviceMemoryOpaqueCaptureAddressInfo-pNext-pNext
    pNext must be NULL

  • VUID-VkDeviceMemoryOpaqueCaptureAddressInfo-memory-parameter
    memory must be a valid VkDeviceMemory handle

12. Resource Creation

Vulkan supports two primary resource types: buffers and images. Resources are views of memory with associated formatting and dimensionality. Buffers provide access to raw arrays of bytes, whereas images can be multidimensional and may have associated metadata.

Other resource types, such as acceleration structures and micromaps use buffers as the backing store for opaque data structures.

12.1. Buffers

Buffers represent linear arrays of data which are used for various purposes by binding them to a graphics or compute pipeline via descriptor sets or certain commands, or by directly specifying them as parameters to certain commands.

Buffers are represented by VkBuffer handles:

// Provided by VK_VERSION_1_0
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkBuffer)

To create buffers, call:

// Provided by VK_VERSION_1_0
VkResult vkCreateBuffer(
    VkDevice                                    device,
    const VkBufferCreateInfo*                   pCreateInfo,
    const VkAllocationCallbacks*                pAllocator,
    VkBuffer*                                   pBuffer);

  • device is the logical device that creates the buffer object.

  • pCreateInfo is a pointer to a VkBufferCreateInfo structure containing parameters affecting creation of the buffer.

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

  • pBuffer is a pointer to a VkBuffer handle in which the resulting buffer object is returned.

Valid Usage

  • VUID-vkCreateBuffer-flags-00911
    If the flags member of pCreateInfo includes VK_BUFFER_CREATE_SPARSE_BINDING_BIT, creating this VkBuffer must not cause the total required sparse memory for all currently valid sparse resources on the device to exceed VkPhysicalDeviceLimits::sparseAddressSpaceSize

Valid Usage (Implicit)

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

  • VUID-vkCreateBuffer-pCreateInfo-parameter
    pCreateInfo must be a valid pointer to a valid VkBufferCreateInfo structure

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

  • VUID-vkCreateBuffer-pBuffer-parameter
    pBuffer must be a valid pointer to a VkBuffer handle

Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

  • VK_ERROR_INVALID_OPAQUE_CAPTURE_ADDRESS_KHR

The VkBufferCreateInfo structure is defined as:

// Provided by VK_VERSION_1_0
typedef struct VkBufferCreateInfo {
    VkStructureType        sType;
    const void*            pNext;
    VkBufferCreateFlags    flags;
    VkDeviceSize           size;
    VkBufferUsageFlags     usage;
    VkSharingMode          sharingMode;
    uint32_t               queueFamilyIndexCount;
    const uint32_t*        pQueueFamilyIndices;
} VkBufferCreateInfo;

  • 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 VkBufferCreateFlagBits specifying additional parameters of the buffer.

  • size is the size in bytes of the buffer to be created.

  • usage is a bitmask of VkBufferUsageFlagBits specifying allowed usages of the buffer.

  • sharingMode is a VkSharingMode value specifying the sharing mode of the buffer when it will be accessed by multiple queue families.

  • queueFamilyIndexCount is the number of entries in the pQueueFamilyIndices array.

  • pQueueFamilyIndices is a pointer to an array of queue families that will access this buffer. It is ignored if sharingMode is not VK_SHARING_MODE_CONCURRENT.

Valid Usage

  • VUID-VkBufferCreateInfo-size-00912
    size must be greater than 0

  • VUID-VkBufferCreateInfo-sharingMode-00913
    If sharingMode is VK_SHARING_MODE_CONCURRENT, pQueueFamilyIndices must be a valid pointer to an array of queueFamilyIndexCount uint32_t values

  • VUID-VkBufferCreateInfo-sharingMode-00914
    If sharingMode is VK_SHARING_MODE_CONCURRENT, queueFamilyIndexCount must be greater than 1

  • VUID-VkBufferCreateInfo-sharingMode-01419
    If sharingMode is VK_SHARING_MODE_CONCURRENT, each element of pQueueFamilyIndices must be unique and must be less than pQueueFamilyPropertyCount returned by either vkGetPhysicalDeviceQueueFamilyProperties or vkGetPhysicalDeviceQueueFamilyProperties2 for the physicalDevice that was used to create device

  • VUID-VkBufferCreateInfo-flags-00915
    If the sparseBinding feature is not enabled, flags must not contain VK_BUFFER_CREATE_SPARSE_BINDING_BIT

  • VUID-VkBufferCreateInfo-flags-00916
    If the sparseResidencyBuffer feature is not enabled, flags must not contain VK_BUFFER_CREATE_SPARSE_RESIDENCY_BIT

  • VUID-VkBufferCreateInfo-flags-00917
    If the sparseResidencyAliased feature is not enabled, flags must not contain VK_BUFFER_CREATE_SPARSE_ALIASED_BIT

  • VUID-VkBufferCreateInfo-flags-00918
    If flags contains VK_BUFFER_CREATE_SPARSE_RESIDENCY_BIT or VK_BUFFER_CREATE_SPARSE_ALIASED_BIT, it must also contain VK_BUFFER_CREATE_SPARSE_BINDING_BIT

  • VUID-VkBufferCreateInfo-pNext-00920
    If the pNext chain includes a VkExternalMemoryBufferCreateInfo structure, its handleTypes member must only contain bits that are also in VkExternalBufferProperties::externalMemoryProperties.compatibleHandleTypes, as returned by vkGetPhysicalDeviceExternalBufferProperties with pExternalBufferInfo->handleType equal to any one of the handle types specified in VkExternalMemoryBufferCreateInfo::handleTypes

  • VUID-VkBufferCreateInfo-flags-01887
    If the protectedMemory feature is not enabled, flags must not contain VK_BUFFER_CREATE_PROTECTED_BIT

  • VUID-VkBufferCreateInfo-None-01888
    If any of the bits VK_BUFFER_CREATE_SPARSE_BINDING_BIT, VK_BUFFER_CREATE_SPARSE_RESIDENCY_BIT, or VK_BUFFER_CREATE_SPARSE_ALIASED_BIT are set, VK_BUFFER_CREATE_PROTECTED_BIT must not also be set

  • VUID-VkBufferCreateInfo-pNext-01571
    If the pNext chain includes a VkDedicatedAllocationBufferCreateInfoNV structure, and the dedicatedAllocation member of the chained structure is VK_TRUE, then flags must not include VK_BUFFER_CREATE_SPARSE_BINDING_BIT, VK_BUFFER_CREATE_SPARSE_RESIDENCY_BIT, or VK_BUFFER_CREATE_SPARSE_ALIASED_BIT

  • VUID-VkBufferCreateInfo-deviceAddress-02604
    If VkBufferDeviceAddressCreateInfoEXT::deviceAddress is not zero, flags must include VK_BUFFER_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT

  • VUID-VkBufferCreateInfo-opaqueCaptureAddress-03337
    If VkBufferOpaqueCaptureAddressCreateInfo::opaqueCaptureAddress is not zero, flags must include VK_BUFFER_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT

  • VUID-VkBufferCreateInfo-flags-03338
    If flags includes VK_BUFFER_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT, the bufferDeviceAddressCaptureReplay or bufferDeviceAddressCaptureReplayEXT feature must be enabled

  • VUID-VkBufferCreateInfo-usage-04813
    If usage includes VK_BUFFER_USAGE_VIDEO_DECODE_SRC_BIT_KHR or VK_BUFFER_USAGE_VIDEO_DECODE_DST_BIT_KHR, then the pNext chain must include a VkVideoProfileListInfoKHR structure with profileCount greater than 0 and pProfiles including at least one VkVideoProfileInfoKHR structure with a videoCodecOperation member specifying a decode operation

  • VUID-VkBufferCreateInfo-usage-04814
    If usage includes VK_BUFFER_USAGE_VIDEO_ENCODE_SRC_BIT_KHR or VK_BUFFER_USAGE_VIDEO_ENCODE_DST_BIT_KHR, then the pNext chain must include a VkVideoProfileListInfoKHR structure with profileCount greater than 0 and pProfiles including at least one VkVideoProfileInfoKHR structure with a videoCodecOperation member specifying an encode operation

  • VUID-VkBufferCreateInfo-size-06409
    size must be less than or equal to VkPhysicalDeviceMaintenance4Properties::maxBufferSize

  • VUID-VkBufferCreateInfo-usage-08097
    If usage includes VK_BUFFER_USAGE_SAMPLER_DESCRIPTOR_BUFFER_BIT_EXT, creating this VkBuffer must not cause the total required space for all currently valid buffers using this flag on the device to exceed VkPhysicalDeviceDescriptorBufferPropertiesEXT::samplerDescriptorBufferAddressSpaceSize or VkPhysicalDeviceDescriptorBufferPropertiesEXT::descriptorBufferAddressSpaceSize

  • VUID-VkBufferCreateInfo-usage-08098
    If usage includes VK_BUFFER_USAGE_RESOURCE_DESCRIPTOR_BUFFER_BIT_EXT, creating this VkBuffer must not cause the total required space for all currently valid buffers using this flag on the device to exceed VkPhysicalDeviceDescriptorBufferPropertiesEXT::resourceDescriptorBufferAddressSpaceSize or VkPhysicalDeviceDescriptorBufferPropertiesEXT::descriptorBufferAddressSpaceSize

  • VUID-VkBufferCreateInfo-flags-08099
    If flags includes VK_BUFFER_CREATE_DESCRIPTOR_BUFFER_CAPTURE_REPLAY_BIT_EXT, the descriptorBufferCaptureReplay feature must be enabled

  • VUID-VkBufferCreateInfo-pNext-08100
    If the pNext chain includes a VkOpaqueCaptureDescriptorDataCreateInfoEXT structure, flags must contain VK_BUFFER_CREATE_DESCRIPTOR_BUFFER_CAPTURE_REPLAY_BIT_EXT

  • VUID-VkBufferCreateInfo-usage-08101
    If usage includes VK_BUFFER_USAGE_PUSH_DESCRIPTORS_DESCRIPTOR_BUFFER_BIT_EXT, the descriptorBufferPushDescriptors feature must be enabled

  • VUID-VkBufferCreateInfo-usage-08102
    If usage includes VK_BUFFER_USAGE_PUSH_DESCRIPTORS_DESCRIPTOR_BUFFER_BIT_EXT VkPhysicalDeviceDescriptorBufferPropertiesEXT::bufferlessPushDescriptors must be VK_FALSE

  • VUID-VkBufferCreateInfo-usage-08103
    If usage includes VK_BUFFER_USAGE_PUSH_DESCRIPTORS_DESCRIPTOR_BUFFER_BIT_EXT, usage must contain at least one of VK_BUFFER_USAGE_RESOURCE_DESCRIPTOR_BUFFER_BIT_EXT or VK_BUFFER_USAGE_SAMPLER_DESCRIPTOR_BUFFER_BIT_EXT

  • VUID-VkBufferCreateInfo-None-09205
    usage must be a valid combination of VkBufferUsageFlagBits values

  • VUID-VkBufferCreateInfo-None-09206
    usage must not be 0

Valid Usage (Implicit)

Bits which can be set in VkBufferCreateInfo::usage, specifying usage behavior of a buffer, are:

// Provided by VK_VERSION_1_0
typedef enum VkBufferUsageFlagBits {
    VK_BUFFER_USAGE_TRANSFER_SRC_BIT = 0x00000001,
    VK_BUFFER_USAGE_TRANSFER_DST_BIT = 0x00000002,
    VK_BUFFER_USAGE_UNIFORM_TEXEL_BUFFER_BIT = 0x00000004,
    VK_BUFFER_USAGE_STORAGE_TEXEL_BUFFER_BIT = 0x00000008,
    VK_BUFFER_USAGE_UNIFORM_BUFFER_BIT = 0x00000010,
    VK_BUFFER_USAGE_STORAGE_BUFFER_BIT = 0x00000020,
    VK_BUFFER_USAGE_INDEX_BUFFER_BIT = 0x00000040,
    VK_BUFFER_USAGE_VERTEX_BUFFER_BIT = 0x00000080,
    VK_BUFFER_USAGE_INDIRECT_BUFFER_BIT = 0x00000100,
  // Provided by VK_VERSION_1_2
    VK_BUFFER_USAGE_SHADER_DEVICE_ADDRESS_BIT = 0x00020000,
  // Provided by VK_KHR_video_decode_queue
    VK_BUFFER_USAGE_VIDEO_DECODE_SRC_BIT_KHR = 0x00002000,
  // Provided by VK_KHR_video_decode_queue
    VK_BUFFER_USAGE_VIDEO_DECODE_DST_BIT_KHR = 0x00004000,
  // Provided by VK_EXT_transform_feedback
    VK_BUFFER_USAGE_TRANSFORM_FEEDBACK_BUFFER_BIT_EXT = 0x00000800,
  // Provided by VK_EXT_transform_feedback
    VK_BUFFER_USAGE_TRANSFORM_FEEDBACK_COUNTER_BUFFER_BIT_EXT = 0x00001000,
  // Provided by VK_EXT_conditional_rendering
    VK_BUFFER_USAGE_CONDITIONAL_RENDERING_BIT_EXT = 0x00000200,
#ifdef VK_ENABLE_BETA_EXTENSIONS
  // Provided by VK_AMDX_shader_enqueue
    VK_BUFFER_USAGE_EXECUTION_GRAPH_SCRATCH_BIT_AMDX = 0x02000000,
#endif
  // Provided by VK_KHR_acceleration_structure
    VK_BUFFER_USAGE_ACCELERATION_STRUCTURE_BUILD_INPUT_READ_ONLY_BIT_KHR = 0x00080000,
  // Provided by VK_KHR_acceleration_structure
    VK_BUFFER_USAGE_ACCELERATION_STRUCTURE_STORAGE_BIT_KHR = 0x00100000,
  // Provided by VK_KHR_ray_tracing_pipeline
    VK_BUFFER_USAGE_SHADER_BINDING_TABLE_BIT_KHR = 0x00000400,
#ifdef VK_ENABLE_BETA_EXTENSIONS
  // Provided by VK_KHR_video_encode_queue
    VK_BUFFER_USAGE_VIDEO_ENCODE_DST_BIT_KHR = 0x00008000,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
  // Provided by VK_KHR_video_encode_queue
    VK_BUFFER_USAGE_VIDEO_ENCODE_SRC_BIT_KHR = 0x00010000,
#endif
  // Provided by VK_EXT_descriptor_buffer
    VK_BUFFER_USAGE_SAMPLER_DESCRIPTOR_BUFFER_BIT_EXT = 0x00200000,
  // Provided by VK_EXT_descriptor_buffer
    VK_BUFFER_USAGE_RESOURCE_DESCRIPTOR_BUFFER_BIT_EXT = 0x00400000,
  // Provided by VK_EXT_descriptor_buffer
    VK_BUFFER_USAGE_PUSH_DESCRIPTORS_DESCRIPTOR_BUFFER_BIT_EXT = 0x04000000,
  // Provided by VK_EXT_opacity_micromap
    VK_BUFFER_USAGE_MICROMAP_BUILD_INPUT_READ_ONLY_BIT_EXT = 0x00800000,
  // Provided by VK_EXT_opacity_micromap
    VK_BUFFER_USAGE_MICROMAP_STORAGE_BIT_EXT = 0x01000000,
  // Provided by VK_NV_ray_tracing
    VK_BUFFER_USAGE_RAY_TRACING_BIT_NV = VK_BUFFER_USAGE_SHADER_BINDING_TABLE_BIT_KHR,
  // Provided by VK_EXT_buffer_device_address
    VK_BUFFER_USAGE_SHADER_DEVICE_ADDRESS_BIT_EXT = VK_BUFFER_USAGE_SHADER_DEVICE_ADDRESS_BIT,
  // Provided by VK_KHR_buffer_device_address
    VK_BUFFER_USAGE_SHADER_DEVICE_ADDRESS_BIT_KHR = VK_BUFFER_USAGE_SHADER_DEVICE_ADDRESS_BIT,
} VkBufferUsageFlagBits;

  • VK_BUFFER_USAGE_TRANSFER_SRC_BIT specifies that the buffer can be used as the source of a transfer command (see the definition of VK_PIPELINE_STAGE_TRANSFER_BIT).

  • VK_BUFFER_USAGE_TRANSFER_DST_BIT specifies that the buffer can be used as the destination of a transfer command.

  • VK_BUFFER_USAGE_UNIFORM_TEXEL_BUFFER_BIT specifies that the buffer can be used to create a VkBufferView suitable for occupying a VkDescriptorSet slot of type VK_DESCRIPTOR_TYPE_UNIFORM_TEXEL_BUFFER.

  • VK_BUFFER_USAGE_STORAGE_TEXEL_BUFFER_BIT specifies that the buffer can be used to create a VkBufferView suitable for occupying a VkDescriptorSet slot of type VK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER.

  • VK_BUFFER_USAGE_UNIFORM_BUFFER_BIT specifies that the buffer can be used in a VkDescriptorBufferInfo suitable for occupying a VkDescriptorSet slot either of type VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER or VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC.

  • VK_BUFFER_USAGE_STORAGE_BUFFER_BIT specifies that the buffer can be used in a VkDescriptorBufferInfo suitable for occupying a VkDescriptorSet slot either of type VK_DESCRIPTOR_TYPE_STORAGE_BUFFER or VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC.

  • VK_BUFFER_USAGE_INDEX_BUFFER_BIT specifies that the buffer is suitable for passing as the buffer parameter to vkCmdBindIndexBuffer.

  • VK_BUFFER_USAGE_VERTEX_BUFFER_BIT specifies that the buffer is suitable for passing as an element of the pBuffers array to vkCmdBindVertexBuffers.

  • VK_BUFFER_USAGE_INDIRECT_BUFFER_BIT specifies that the buffer is suitable for passing as the buffer parameter to vkCmdDrawIndirect, vkCmdDrawIndexedIndirect, vkCmdDrawMeshTasksIndirectNV, vkCmdDrawMeshTasksIndirectCountNV, vkCmdDrawMeshTasksIndirectEXT, vkCmdDrawMeshTasksIndirectCountEXT, vkCmdDrawClusterIndirectHUAWEI, or vkCmdDispatchIndirect. It is also suitable for passing as the buffer member of VkIndirectCommandsStreamNV, or sequencesCountBuffer or sequencesIndexBuffer or preprocessedBuffer member of VkGeneratedCommandsInfoNV

  • VK_BUFFER_USAGE_CONDITIONAL_RENDERING_BIT_EXT specifies that the buffer is suitable for passing as the buffer parameter to vkCmdBeginConditionalRenderingEXT.

  • VK_BUFFER_USAGE_TRANSFORM_FEEDBACK_BUFFER_BIT_EXT specifies that the buffer is suitable for using for binding as a transform feedback buffer with vkCmdBindTransformFeedbackBuffersEXT.

  • VK_BUFFER_USAGE_TRANSFORM_FEEDBACK_COUNTER_BUFFER_BIT_EXT specifies that the buffer is suitable for using as a counter buffer with vkCmdBeginTransformFeedbackEXT and vkCmdEndTransformFeedbackEXT.

  • VK_BUFFER_USAGE_SAMPLER_DESCRIPTOR_BUFFER_BIT_EXT specifies that the buffer is suitable to contain sampler and combined image sampler descriptors when bound as a descriptor buffer. Buffers containing combined image sampler descriptors must also specify VK_BUFFER_USAGE_RESOURCE_DESCRIPTOR_BUFFER_BIT_EXT.

  • VK_BUFFER_USAGE_RESOURCE_DESCRIPTOR_BUFFER_BIT_EXT specifies that the buffer is suitable to contain resource descriptors when bound as a descriptor buffer.

  • VK_BUFFER_USAGE_PUSH_DESCRIPTORS_DESCRIPTOR_BUFFER_BIT_EXT specifies that the buffer, when bound, can be used by the implementation to support push descriptors when using descriptor buffers.

  • VK_BUFFER_USAGE_RAY_TRACING_BIT_NV specifies that the buffer is suitable for use in vkCmdTraceRaysNV.

  • VK_BUFFER_USAGE_SHADER_BINDING_TABLE_BIT_KHR specifies that the buffer is suitable for use as a Shader Binding Table.

  • VK_BUFFER_USAGE_ACCELERATION_STRUCTURE_BUILD_INPUT_READ_ONLY_BIT_KHR specifies that the buffer is suitable for use as a read-only input to an acceleration structure build.

  • VK_BUFFER_USAGE_ACCELERATION_STRUCTURE_STORAGE_BIT_KHR specifies that the buffer is suitable for storage space for a VkAccelerationStructureKHR.

  • VK_BUFFER_USAGE_SHADER_DEVICE_ADDRESS_BIT specifies that the buffer can be used to retrieve a buffer device address via vkGetBufferDeviceAddress and use that address to access the buffer’s memory from a shader.

  • VK_BUFFER_USAGE_VIDEO_DECODE_SRC_BIT_KHR specifies that the buffer can be used as the source video bitstream buffer in a video decode operation.

  • VK_BUFFER_USAGE_VIDEO_DECODE_DST_BIT_KHR is reserved for future use.

  • VK_BUFFER_USAGE_VIDEO_ENCODE_DST_BIT_KHR specifies that the buffer can be used as the destination video bitstream buffer in a video encode operation.

  • VK_BUFFER_USAGE_VIDEO_ENCODE_SRC_BIT_KHR is reserved for future use.

// Provided by VK_VERSION_1_0
typedef VkFlags VkBufferUsageFlags;

VkBufferUsageFlags is a bitmask type for setting a mask of zero or more VkBufferUsageFlagBits.

Bits which can be set in VkBufferCreateInfo::flags, specifying additional parameters of a buffer, are:

// Provided by VK_VERSION_1_0
typedef enum VkBufferCreateFlagBits {
    VK_BUFFER_CREATE_SPARSE_BINDING_BIT = 0x00000001,
    VK_BUFFER_CREATE_SPARSE_RESIDENCY_BIT = 0x00000002,
    VK_BUFFER_CREATE_SPARSE_ALIASED_BIT = 0x00000004,
  // Provided by VK_VERSION_1_1
    VK_BUFFER_CREATE_PROTECTED_BIT = 0x00000008,
  // Provided by VK_VERSION_1_2
    VK_BUFFER_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT = 0x00000010,
  // Provided by VK_EXT_descriptor_buffer
    VK_BUFFER_CREATE_DESCRIPTOR_BUFFER_CAPTURE_REPLAY_BIT_EXT = 0x00000020,
  // Provided by VK_EXT_buffer_device_address
    VK_BUFFER_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT_EXT = VK_BUFFER_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT,
  // Provided by VK_KHR_buffer_device_address
    VK_BUFFER_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT_KHR = VK_BUFFER_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT,
} VkBufferCreateFlagBits;

  • VK_BUFFER_CREATE_SPARSE_BINDING_BIT specifies that the buffer will be backed using sparse memory binding.

  • VK_BUFFER_CREATE_SPARSE_RESIDENCY_BIT specifies that the buffer can be partially backed using sparse memory binding. Buffers created with this flag must also be created with the VK_BUFFER_CREATE_SPARSE_BINDING_BIT flag.

  • VK_BUFFER_CREATE_SPARSE_ALIASED_BIT specifies that the buffer will be backed using sparse memory binding with memory ranges that might also simultaneously be backing another buffer (or another portion of the same buffer). Buffers created with this flag must also be created with the VK_BUFFER_CREATE_SPARSE_BINDING_BIT flag.

  • VK_BUFFER_CREATE_PROTECTED_BIT specifies that the buffer is a protected buffer.

  • VK_BUFFER_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT specifies that the buffer’s address can be saved and reused on a subsequent run (e.g. for trace capture and replay), see VkBufferOpaqueCaptureAddressCreateInfo for more detail.

  • VK_BUFFER_CREATE_DESCRIPTOR_BUFFER_CAPTURE_REPLAY_BIT_EXT specifies that the buffer can be used with descriptor buffers when capturing and replaying (e.g. for trace capture and replay), see VkOpaqueCaptureDescriptorDataCreateInfoEXT for more detail.

See Sparse Resource Features and Physical Device Features for details of the sparse memory features supported on a device.

// Provided by VK_VERSION_1_0
typedef VkFlags VkBufferCreateFlags;

VkBufferCreateFlags is a bitmask type for setting a mask of zero or more VkBufferCreateFlagBits.

If the pNext chain includes a VkDedicatedAllocationBufferCreateInfoNV structure, then that structure includes an enable controlling whether the buffer will have a dedicated memory allocation bound to it.

The VkDedicatedAllocationBufferCreateInfoNV structure is defined as:

// Provided by VK_NV_dedicated_allocation
typedef struct VkDedicatedAllocationBufferCreateInfoNV {
    VkStructureType    sType;
    const void*        pNext;
    VkBool32           dedicatedAllocation;
} VkDedicatedAllocationBufferCreateInfoNV;

  • sType is a VkStructureType value identifying this structure.

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

  • dedicatedAllocation specifies whether the buffer will have a dedicated allocation bound to it.

Valid Usage (Implicit)

  • VUID-VkDedicatedAllocationBufferCreateInfoNV-sType-sType
    sType must be VK_STRUCTURE_TYPE_DEDICATED_ALLOCATION_BUFFER_CREATE_INFO_NV

To define a set of external memory handle types that may be used as backing store for a buffer, add a VkExternalMemoryBufferCreateInfo structure to the pNext chain of the VkBufferCreateInfo structure. The VkExternalMemoryBufferCreateInfo structure is defined as:

// Provided by VK_VERSION_1_1
typedef struct VkExternalMemoryBufferCreateInfo {
    VkStructureType                    sType;
    const void*                        pNext;
    VkExternalMemoryHandleTypeFlags    handleTypes;
} VkExternalMemoryBufferCreateInfo;

or the equivalent

// Provided by VK_KHR_external_memory
typedef VkExternalMemoryBufferCreateInfo VkExternalMemoryBufferCreateInfoKHR;
Note

A VkExternalMemoryBufferCreateInfo structure with a non-zero handleTypes field must be included in the creation parameters for a buffer that will be bound to memory that is either exported or imported.

  • 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 external memory handle types.

Valid Usage (Implicit)

  • VUID-VkExternalMemoryBufferCreateInfo-sType-sType
    sType must be VK_STRUCTURE_TYPE_EXTERNAL_MEMORY_BUFFER_CREATE_INFO

  • VUID-VkExternalMemoryBufferCreateInfo-handleTypes-parameter
    handleTypes must be a valid combination of VkExternalMemoryHandleTypeFlagBits values

To request a specific device address for a buffer, add a VkBufferOpaqueCaptureAddressCreateInfo structure to the pNext chain of the VkBufferCreateInfo structure. The VkBufferOpaqueCaptureAddressCreateInfo structure is defined as:

// Provided by VK_VERSION_1_2
typedef struct VkBufferOpaqueCaptureAddressCreateInfo {
    VkStructureType    sType;
    const void*        pNext;
    uint64_t           opaqueCaptureAddress;
} VkBufferOpaqueCaptureAddressCreateInfo;

or the equivalent

// Provided by VK_KHR_buffer_device_address
typedef VkBufferOpaqueCaptureAddressCreateInfo VkBufferOpaqueCaptureAddressCreateInfoKHR;

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

If opaqueCaptureAddress is zero, no specific address is requested.

If opaqueCaptureAddress is not zero, then it should be an address retrieved from vkGetBufferOpaqueCaptureAddress for an identically created buffer on the same implementation.

If this structure is not present, it is as if opaqueCaptureAddress is zero.

Apps should avoid creating buffers with app-provided addresses and implementation-provided addresses in the same process, to reduce the likelihood of VK_ERROR_INVALID_OPAQUE_CAPTURE_ADDRESS errors.

Note

The expected usage for this is that a trace capture/replay tool will add the VK_BUFFER_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT flag to all buffers that use VK_BUFFER_USAGE_SHADER_DEVICE_ADDRESS_BIT, and during capture will save the queried opaque device addresses in the trace. During replay, the buffers will be created specifying the original address so any address values stored in the trace data will remain valid.

Implementations are expected to separate such buffers in the GPU address space so normal allocations will avoid using these addresses. Apps/tools should avoid mixing app-provided and implementation-provided addresses for buffers created with VK_BUFFER_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT, to avoid address space allocation conflicts.
Valid Usage (Implicit)

  • VUID-VkBufferOpaqueCaptureAddressCreateInfo-sType-sType
    sType must be VK_STRUCTURE_TYPE_BUFFER_OPAQUE_CAPTURE_ADDRESS_CREATE_INFO

Alternatively, to request a specific device address for a buffer, add a VkBufferDeviceAddressCreateInfoEXT structure to the pNext chain of the VkBufferCreateInfo structure. The VkBufferDeviceAddressCreateInfoEXT structure is defined as:

// Provided by VK_EXT_buffer_device_address
typedef struct VkBufferDeviceAddressCreateInfoEXT {
    VkStructureType    sType;
    const void*        pNext;
    VkDeviceAddress    deviceAddress;
} VkBufferDeviceAddressCreateInfoEXT;

  • sType is a VkStructureType value identifying this structure.

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

  • deviceAddress is the device address requested for the buffer.

If deviceAddress is zero, no specific address is requested.

If deviceAddress is not zero, then it must be an address retrieved from an identically created buffer on the same implementation. The buffer must also be bound to an identically created VkDeviceMemory object.

If this structure is not present, it is as if deviceAddress is zero.

Apps should avoid creating buffers with app-provided addresses and implementation-provided addresses in the same process, to reduce the likelihood of VK_ERROR_INVALID_DEVICE_ADDRESS_EXT errors.

Valid Usage (Implicit)

  • VUID-VkBufferDeviceAddressCreateInfoEXT-sType-sType
    sType must be VK_STRUCTURE_TYPE_BUFFER_DEVICE_ADDRESS_CREATE_INFO_EXT

The VkBufferCollectionBufferCreateInfoFUCHSIA structure is defined as:

// Provided by VK_FUCHSIA_buffer_collection
typedef struct VkBufferCollectionBufferCreateInfoFUCHSIA {
    VkStructureType              sType;
    const void*                  pNext;
    VkBufferCollectionFUCHSIA    collection;
    uint32_t                     index;
} VkBufferCollectionBufferCreateInfoFUCHSIA;

  • sType is a VkStructureType value identifying this structure.

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

  • collection is the VkBufferCollectionFUCHSIA handle

  • index is the index of the buffer in the buffer collection from which the memory will be imported

Valid Usage
Valid Usage (Implicit)

  • VUID-VkBufferCollectionBufferCreateInfoFUCHSIA-sType-sType
    sType must be VK_STRUCTURE_TYPE_BUFFER_COLLECTION_BUFFER_CREATE_INFO_FUCHSIA

  • VUID-VkBufferCollectionBufferCreateInfoFUCHSIA-collection-parameter
    collection must be a valid VkBufferCollectionFUCHSIA handle

To destroy a buffer, call:

// Provided by VK_VERSION_1_0
void vkDestroyBuffer(
    VkDevice                                    device,
    VkBuffer                                    buffer,
    const VkAllocationCallbacks*                pAllocator);

  • device is the logical device that destroys the buffer.

  • buffer is the buffer to destroy.

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

Valid Usage

  • VUID-vkDestroyBuffer-buffer-00922
    All submitted commands that refer to buffer, either directly or via a VkBufferView, must have completed execution

  • VUID-vkDestroyBuffer-buffer-00923
    If VkAllocationCallbacks were provided when buffer was created, a compatible set of callbacks must be provided here

  • VUID-vkDestroyBuffer-buffer-00924
    If no VkAllocationCallbacks were provided when buffer was created, pAllocator must be NULL

Valid Usage (Implicit)

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

  • VUID-vkDestroyBuffer-buffer-parameter
    If buffer is not VK_NULL_HANDLE, buffer must be a valid VkBuffer handle

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

  • VUID-vkDestroyBuffer-buffer-parent
    If buffer is a valid handle, it must have been created, allocated, or retrieved from device

Host Synchronization

  • Host access to buffer must be externally synchronized

12.2. Buffer Views

A buffer view represents a contiguous range of a buffer and a specific format to be used to interpret the data. Buffer views are used to enable shaders to access buffer contents using image operations. In order to create a valid buffer view, the buffer must have been created with at least one of the following usage flags:

  • VK_BUFFER_USAGE_UNIFORM_TEXEL_BUFFER_BIT

  • VK_BUFFER_USAGE_STORAGE_TEXEL_BUFFER_BIT

Buffer views are represented by VkBufferView handles:

// Provided by VK_VERSION_1_0
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkBufferView)

To create a buffer view, call:

// Provided by VK_VERSION_1_0
VkResult vkCreateBufferView(
    VkDevice                                    device,
    const VkBufferViewCreateInfo*               pCreateInfo,
    const VkAllocationCallbacks*                pAllocator,
    VkBufferView*                               pView);

  • device is the logical device that creates the buffer view.

  • pCreateInfo is a pointer to a VkBufferViewCreateInfo structure containing parameters to be used to create the buffer view.

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

  • pView is a pointer to a VkBufferView handle in which the resulting buffer view object is returned.

Valid Usage (Implicit)

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

  • VUID-vkCreateBufferView-pCreateInfo-parameter
    pCreateInfo must be a valid pointer to a valid VkBufferViewCreateInfo structure

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

  • VUID-vkCreateBufferView-pView-parameter
    pView must be a valid pointer to a VkBufferView handle

Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

The VkBufferViewCreateInfo structure is defined as:

// Provided by VK_VERSION_1_0
typedef struct VkBufferViewCreateInfo {
    VkStructureType            sType;
    const void*                pNext;
    VkBufferViewCreateFlags    flags;
    VkBuffer                   buffer;
    VkFormat                   format;
    VkDeviceSize               offset;
    VkDeviceSize               range;
} VkBufferViewCreateInfo;

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

  • buffer is a VkBuffer on which the view will be created.

  • format is a VkFormat describing the format of the data elements in the buffer.

  • offset is an offset in bytes from the base address of the buffer. Accesses to the buffer view from shaders use addressing that is relative to this starting offset.

  • range is a size in bytes of the buffer view. If range is equal to VK_WHOLE_SIZE, the range from offset to the end of the buffer is used. If VK_WHOLE_SIZE is used and the remaining size of the buffer is not a multiple of the texel block size of format, the nearest smaller multiple is used.

The buffer view has a buffer view usage identifying which descriptor types can be created from it. This usage is equal to the VkBufferCreateInfo::usage value used to create buffer.

Valid Usage

  • VUID-VkBufferViewCreateInfo-offset-00925
    offset must be less than the size of buffer

  • VUID-VkBufferViewCreateInfo-range-00928
    If range is not equal to VK_WHOLE_SIZE, range must be greater than 0

  • VUID-VkBufferViewCreateInfo-range-00929
    If range is not equal to VK_WHOLE_SIZE, range must be an integer multiple of the texel block size of format

  • VUID-VkBufferViewCreateInfo-range-00930
    If range is not equal to VK_WHOLE_SIZE, the number of texel buffer elements given by (⌊range / (texel block size)⌋ × (texels per block)) where texel block size and texels per block are as defined in the Compatible Formats table for format, must be less than or equal to VkPhysicalDeviceLimits::maxTexelBufferElements

  • VUID-VkBufferViewCreateInfo-offset-00931
    If range is not equal to VK_WHOLE_SIZE, the sum of offset and range must be less than or equal to the size of buffer

  • VUID-VkBufferViewCreateInfo-range-04059
    If range is equal to VK_WHOLE_SIZE, the number of texel buffer elements given by (⌊(size - offset) / (texel block size)⌋ × (texels per block)) where size is the size of buffer, and texel block size and texels per block are as defined in the Compatible Formats table for format, must be less than or equal to VkPhysicalDeviceLimits::maxTexelBufferElements

  • VUID-VkBufferViewCreateInfo-buffer-00932
    buffer must have been created with a usage value containing at least one of VK_BUFFER_USAGE_UNIFORM_TEXEL_BUFFER_BIT or VK_BUFFER_USAGE_STORAGE_TEXEL_BUFFER_BIT

  • VUID-VkBufferViewCreateInfo-format-08778
    If the buffer view usage contains VK_BUFFER_USAGE_UNIFORM_TEXEL_BUFFER_BIT, then format features of format must contain VK_FORMAT_FEATURE_UNIFORM_TEXEL_BUFFER_BIT

  • VUID-VkBufferViewCreateInfo-format-08779
    If the buffer view usage contains VK_BUFFER_USAGE_STORAGE_TEXEL_BUFFER_BIT, then format features of format must contain VK_FORMAT_FEATURE_STORAGE_TEXEL_BUFFER_BIT

  • VUID-VkBufferViewCreateInfo-buffer-00935
    If buffer is non-sparse then it must be bound completely and contiguously to a single VkDeviceMemory object

  • VUID-VkBufferViewCreateInfo-offset-02749
    If the texelBufferAlignment feature is not enabled, offset must be a multiple of VkPhysicalDeviceLimits::minTexelBufferOffsetAlignment

  • VUID-VkBufferViewCreateInfo-buffer-02750
    If the texelBufferAlignment feature is enabled and if buffer was created with usage containing VK_BUFFER_USAGE_STORAGE_TEXEL_BUFFER_BIT, offset must be a multiple of the lesser of VkPhysicalDeviceTexelBufferAlignmentProperties::storageTexelBufferOffsetAlignmentBytes or, if VkPhysicalDeviceTexelBufferAlignmentProperties::storageTexelBufferOffsetSingleTexelAlignment is VK_TRUE, the size of a texel of the requested format. If the size of a texel is a multiple of three bytes, then the size of a single component of format is used instead

  • VUID-VkBufferViewCreateInfo-buffer-02751
    If the texelBufferAlignment feature is enabled and if buffer was created with usage containing VK_BUFFER_USAGE_UNIFORM_TEXEL_BUFFER_BIT, offset must be a multiple of the lesser of VkPhysicalDeviceTexelBufferAlignmentProperties::uniformTexelBufferOffsetAlignmentBytes or, if VkPhysicalDeviceTexelBufferAlignmentProperties::uniformTexelBufferOffsetSingleTexelAlignment is VK_TRUE, the size of a texel of the requested format. If the size of a texel is a multiple of three bytes, then the size of a single component of format is used instead

  • VUID-VkBufferViewCreateInfo-pNext-06782
    If the pNext chain includes a VkExportMetalObjectCreateInfoEXT structure, its exportObjectType member must be VK_EXPORT_METAL_OBJECT_TYPE_METAL_TEXTURE_BIT_EXT

Valid Usage (Implicit)

  • VUID-VkBufferViewCreateInfo-sType-sType
    sType must be VK_STRUCTURE_TYPE_BUFFER_VIEW_CREATE_INFO

  • VUID-VkBufferViewCreateInfo-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 VkBufferUsageFlags2CreateInfoKHR or VkExportMetalObjectCreateInfoEXT

  • VUID-VkBufferViewCreateInfo-sType-unique
    The sType value of each struct in the pNext chain must be unique, with the exception of structures of type VkExportMetalObjectCreateInfoEXT

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

  • VUID-VkBufferViewCreateInfo-buffer-parameter
    buffer must be a valid VkBuffer handle

  • VUID-VkBufferViewCreateInfo-format-parameter
    format must be a valid VkFormat value

// Provided by VK_VERSION_1_0
typedef VkFlags VkBufferViewCreateFlags;

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

To destroy a buffer view, call:

// Provided by VK_VERSION_1_0
void vkDestroyBufferView(
    VkDevice                                    device,
    VkBufferView                                bufferView,
    const VkAllocationCallbacks*                pAllocator);

  • device is the logical device that destroys the buffer view.

  • bufferView is the buffer view to destroy.

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

Valid Usage

  • VUID-vkDestroyBufferView-bufferView-00936
    All submitted commands that refer to bufferView must have completed execution

  • VUID-vkDestroyBufferView-bufferView-00937
    If VkAllocationCallbacks were provided when bufferView was created, a compatible set of callbacks must be provided here

  • VUID-vkDestroyBufferView-bufferView-00938
    If no VkAllocationCallbacks were provided when bufferView was created, pAllocator must be NULL

Valid Usage (Implicit)

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

  • VUID-vkDestroyBufferView-bufferView-parameter
    If bufferView is not VK_NULL_HANDLE, bufferView must be a valid VkBufferView handle

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

  • VUID-vkDestroyBufferView-bufferView-parent
    If bufferView is a valid handle, it must have been created, allocated, or retrieved from device

Host Synchronization

  • Host access to bufferView must be externally synchronized

12.2.1. Buffer View Format Features

Valid uses of a VkBufferView may depend on the buffer view’s format features, defined below. Such constraints are documented in the affected valid usage statement.

12.3. Images

Images represent multidimensional - up to 3 - arrays of data which can be used for various purposes (e.g. attachments, textures), by binding them to a graphics or compute pipeline via descriptor sets, or by directly specifying them as parameters to certain commands.

Images are represented by VkImage handles:

// Provided by VK_VERSION_1_0
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkImage)

To create images, call:

// Provided by VK_VERSION_1_0
VkResult vkCreateImage(
    VkDevice                                    device,
    const VkImageCreateInfo*                    pCreateInfo,
    const VkAllocationCallbacks*                pAllocator,
    VkImage*                                    pImage);

  • device is the logical device that creates the image.

  • pCreateInfo is a pointer to a VkImageCreateInfo structure containing parameters to be used to create the image.

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

  • pImage is a pointer to a VkImage handle in which the resulting image object is returned.

Valid Usage

  • VUID-vkCreateImage-flags-00939
    If the flags member of pCreateInfo includes VK_IMAGE_CREATE_SPARSE_BINDING_BIT, creating this VkImage must not cause the total required sparse memory for all currently valid sparse resources on the device to exceed VkPhysicalDeviceLimits::sparseAddressSpaceSize

Valid Usage (Implicit)

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

  • VUID-vkCreateImage-pCreateInfo-parameter
    pCreateInfo must be a valid pointer to a valid VkImageCreateInfo structure

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

  • VUID-vkCreateImage-pImage-parameter
    pImage must be a valid pointer to a VkImage handle

Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

  • VK_ERROR_COMPRESSION_EXHAUSTED_EXT

  • VK_ERROR_INVALID_OPAQUE_CAPTURE_ADDRESS_KHR

The VkImageCreateInfo structure is defined as:

// Provided by VK_VERSION_1_0
typedef struct VkImageCreateInfo {
    VkStructureType          sType;
    const void*              pNext;
    VkImageCreateFlags       flags;
    VkImageType              imageType;
    VkFormat                 format;
    VkExtent3D               extent;
    uint32_t                 mipLevels;
    uint32_t                 arrayLayers;
    VkSampleCountFlagBits    samples;
    VkImageTiling            tiling;
    VkImageUsageFlags        usage;
    VkSharingMode            sharingMode;
    uint32_t                 queueFamilyIndexCount;
    const uint32_t*          pQueueFamilyIndices;
    VkImageLayout            initialLayout;
} VkImageCreateInfo;

  • 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 describing additional parameters of the image.

  • imageType is a VkImageType value specifying the basic dimensionality of the image. Layers in array textures do not count as a dimension for the purposes of the image type.

  • format is a VkFormat describing the format and type of the texel blocks that will be contained in the image.

  • extent is a VkExtent3D describing the number of data elements in each dimension of the base level.

  • mipLevels describes the number of levels of detail available for minified sampling of the image.

  • arrayLayers is the number of layers in the image.

  • samples is a VkSampleCountFlagBits value specifying the number of samples per texel.

  • tiling is a VkImageTiling value specifying the tiling arrangement of the texel blocks in memory.

  • usage is a bitmask of VkImageUsageFlagBits describing the intended usage of the image.

  • sharingMode is a VkSharingMode value specifying the sharing mode of the image when it will be accessed by multiple queue families.

  • queueFamilyIndexCount is the number of entries in the pQueueFamilyIndices array.

  • pQueueFamilyIndices is a pointer to an array of queue families that will access this image. It is ignored if sharingMode is not VK_SHARING_MODE_CONCURRENT.

  • initialLayout is a VkImageLayout value specifying the initial VkImageLayout of all image subresources of the image. See Image Layouts.

Images created with tiling equal to VK_IMAGE_TILING_LINEAR have further restrictions on their limits and capabilities compared to images created with tiling equal to VK_IMAGE_TILING_OPTIMAL. Creation of images with tiling VK_IMAGE_TILING_LINEAR may not be supported unless other parameters meet all of the constraints:

  • imageType is VK_IMAGE_TYPE_2D

  • format is not a depth/stencil format

  • mipLevels is 1

  • arrayLayers is 1

  • samples is VK_SAMPLE_COUNT_1_BIT

  • usage only includes VK_IMAGE_USAGE_TRANSFER_SRC_BIT and/or VK_IMAGE_USAGE_TRANSFER_DST_BIT

Images created with one of the formats that require a sampler Y′CBCR conversion, have further restrictions on their limits and capabilities compared to images created with other formats. Creation of images with a format requiring Y′CBCR conversion may not be supported unless other parameters meet all of the constraints:

Implementations may support additional limits and capabilities beyond those listed above.

To determine the set of valid usage bits for a given format, call vkGetPhysicalDeviceFormatProperties.

If the size of the resultant image would exceed maxResourceSize, then vkCreateImage must fail and return VK_ERROR_OUT_OF_DEVICE_MEMORY. This failure may occur even when all image creation parameters satisfy their valid usage requirements.

Note

For images created without VK_IMAGE_CREATE_EXTENDED_USAGE_BIT a usage bit is valid if it is supported for the format the image is created with.

For images created with VK_IMAGE_CREATE_EXTENDED_USAGE_BIT a usage bit is valid if it is supported for at least one of the formats a VkImageView created from the image can have (see Image Views for more detail).
Image Creation Limits

Valid values for some image creation parameters are limited by a numerical upper bound or by inclusion in a bitset. For example, VkImageCreateInfo::arrayLayers is limited by imageCreateMaxArrayLayers, defined below; and VkImageCreateInfo::samples is limited by imageCreateSampleCounts, also defined below.

Several limiting values are defined below, as well as assisting values from which the limiting values are derived. The limiting values are referenced by the relevant valid usage statements of VkImageCreateInfo.

Valid Usage

  • VUID-VkImageCreateInfo-imageCreateMaxMipLevels-02251
    Each of the following values (as described in Image Creation Limits) must not be undefined : imageCreateMaxMipLevels, imageCreateMaxArrayLayers, imageCreateMaxExtent, and imageCreateSampleCounts

  • VUID-VkImageCreateInfo-sharingMode-00941
    If sharingMode is VK_SHARING_MODE_CONCURRENT, pQueueFamilyIndices must be a valid pointer to an array of queueFamilyIndexCount uint32_t values

  • VUID-VkImageCreateInfo-sharingMode-00942
    If sharingMode is VK_SHARING_MODE_CONCURRENT, queueFamilyIndexCount must be greater than 1

  • VUID-VkImageCreateInfo-sharingMode-01420
    If sharingMode is VK_SHARING_MODE_CONCURRENT, each element of pQueueFamilyIndices must be unique and must be less than pQueueFamilyPropertyCount returned by either vkGetPhysicalDeviceQueueFamilyProperties or vkGetPhysicalDeviceQueueFamilyProperties2 for the physicalDevice that was used to create device

  • VUID-VkImageCreateInfo-pNext-01974
    If the pNext chain includes a VkExternalFormatANDROID structure, and its externalFormat member is non-zero the format must be VK_FORMAT_UNDEFINED

  • VUID-VkImageCreateInfo-pNext-01975
    If the pNext chain does not include a VkExternalFormatANDROID structure, or does and its externalFormat member is 0, the format must not be VK_FORMAT_UNDEFINED

  • VUID-VkImageCreateInfo-extent-00944
    extent.width must be greater than 0

  • VUID-VkImageCreateInfo-extent-00945
    extent.height must be greater than 0

  • VUID-VkImageCreateInfo-extent-00946
    extent.depth must be greater than 0

  • VUID-VkImageCreateInfo-mipLevels-00947
    mipLevels must be greater than 0

  • VUID-VkImageCreateInfo-arrayLayers-00948
    arrayLayers must be greater than 0

  • VUID-VkImageCreateInfo-flags-00949
    If flags contains VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT, imageType must be VK_IMAGE_TYPE_2D

  • VUID-VkImageCreateInfo-flags-08865
    If flags contains VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT, extent.width and extent.height must be equal

  • VUID-VkImageCreateInfo-flags-08866
    If flags contains VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT, arrayLayers must be greater than or equal to 6

  • VUID-VkImageCreateInfo-flags-02557
    If flags contains VK_IMAGE_USAGE_FRAGMENT_DENSITY_MAP_BIT_EXT, imageType must be VK_IMAGE_TYPE_2D

  • VUID-VkImageCreateInfo-flags-00950
    If flags contains VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT, imageType must be VK_IMAGE_TYPE_3D

  • VUID-VkImageCreateInfo-flags-07755
    If flags contains VK_IMAGE_CREATE_2D_VIEW_COMPATIBLE_BIT_EXT, imageType must be VK_IMAGE_TYPE_3D

  • VUID-VkImageCreateInfo-extent-02252
    extent.width must be less than or equal to imageCreateMaxExtent.width (as defined in Image Creation Limits)

  • VUID-VkImageCreateInfo-extent-02253
    extent.height must be less than or equal to imageCreateMaxExtent.height (as defined in Image Creation Limits)

  • VUID-VkImageCreateInfo-extent-02254
    extent.depth must be less than or equal to imageCreateMaxExtent.depth (as defined in Image Creation Limits)

  • VUID-VkImageCreateInfo-imageType-00956
    If imageType is VK_IMAGE_TYPE_1D, both extent.height and extent.depth must be 1

  • VUID-VkImageCreateInfo-imageType-00957
    If imageType is VK_IMAGE_TYPE_2D, extent.depth must be 1

  • VUID-VkImageCreateInfo-mipLevels-00958
    mipLevels must be less than or equal to the number of levels in the complete mipmap chain based on extent.width, extent.height, and extent.depth

  • VUID-VkImageCreateInfo-mipLevels-02255
    mipLevels must be less than or equal to imageCreateMaxMipLevels (as defined in Image Creation Limits)

  • VUID-VkImageCreateInfo-arrayLayers-02256
    arrayLayers must be less than or equal to imageCreateMaxArrayLayers (as defined in Image Creation Limits)

  • VUID-VkImageCreateInfo-imageType-00961
    If imageType is VK_IMAGE_TYPE_3D, arrayLayers must be 1

  • VUID-VkImageCreateInfo-samples-02257
    If samples is not VK_SAMPLE_COUNT_1_BIT, then imageType must be VK_IMAGE_TYPE_2D, flags must not contain VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT, mipLevels must be equal to 1, and imageCreateMaybeLinear (as defined in Image Creation Limits) must be VK_FALSE,

  • VUID-VkImageCreateInfo-samples-02558
    If samples is not VK_SAMPLE_COUNT_1_BIT, usage must not contain VK_IMAGE_USAGE_FRAGMENT_DENSITY_MAP_BIT_EXT

  • VUID-VkImageCreateInfo-usage-00963
    If usage includes VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT, then bits other than VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT, VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT, and VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT must not be set

  • VUID-VkImageCreateInfo-usage-00964
    If usage includes VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT, VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT, VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT, or VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT, extent.width must be less than or equal to VkPhysicalDeviceLimits::maxFramebufferWidth

  • VUID-VkImageCreateInfo-usage-00965
    If usage includes VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT, VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT, VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT, or VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT, extent.height must be less than or equal to VkPhysicalDeviceLimits::maxFramebufferHeight

  • VUID-VkImageCreateInfo-fragmentDensityMapOffset-06514
    If the fragmentDensityMapOffset feature is not enabled and usage includes VK_IMAGE_USAGE_FRAGMENT_DENSITY_MAP_BIT_EXT, extent.width must be less than or equal to

  • VUID-VkImageCreateInfo-fragmentDensityMapOffset-06515
    If the fragmentDensityMapOffset feature is not enabled and usage includes VK_IMAGE_USAGE_FRAGMENT_DENSITY_MAP_BIT_EXT, extent.height must be less than or equal to

  • VUID-VkImageCreateInfo-usage-00966
    If usage includes VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT, usage must also contain at least one of VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT, VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT, or VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT

  • VUID-VkImageCreateInfo-samples-02258
    samples must be a bit value that is set in imageCreateSampleCounts (as defined in Image Creation Limits)

  • VUID-VkImageCreateInfo-usage-00968
    If the shaderStorageImageMultisample feature is not enabled, and usage contains VK_IMAGE_USAGE_STORAGE_BIT, samples must be VK_SAMPLE_COUNT_1_BIT

  • VUID-VkImageCreateInfo-flags-00969
    If the sparseBinding feature is not enabled, flags must not contain VK_IMAGE_CREATE_SPARSE_BINDING_BIT

  • VUID-VkImageCreateInfo-flags-01924
    If the sparseResidencyAliased feature is not enabled, flags must not contain VK_IMAGE_CREATE_SPARSE_ALIASED_BIT

  • VUID-VkImageCreateInfo-tiling-04121
    If tiling is VK_IMAGE_TILING_LINEAR, flags must not contain VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT

  • VUID-VkImageCreateInfo-imageType-00970
    If imageType is VK_IMAGE_TYPE_1D, flags must not contain VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT

  • VUID-VkImageCreateInfo-imageType-00971
    If the sparseResidencyImage2D feature is not enabled, and imageType is VK_IMAGE_TYPE_2D, flags must not contain VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT

  • VUID-VkImageCreateInfo-imageType-00972
    If the sparseResidencyImage3D feature is not enabled, and imageType is VK_IMAGE_TYPE_3D, flags must not contain VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT

  • VUID-VkImageCreateInfo-imageType-00973
    If the sparseResidency2Samples feature is not enabled, imageType is VK_IMAGE_TYPE_2D, and samples is VK_SAMPLE_COUNT_2_BIT, flags must not contain VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT

  • VUID-VkImageCreateInfo-imageType-00974
    If the sparseResidency4Samples feature is not enabled, imageType is VK_IMAGE_TYPE_2D, and samples is VK_SAMPLE_COUNT_4_BIT, flags must not contain VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT

  • VUID-VkImageCreateInfo-imageType-00975
    If the sparseResidency8Samples feature is not enabled, imageType is VK_IMAGE_TYPE_2D, and samples is VK_SAMPLE_COUNT_8_BIT, flags must not contain VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT

  • VUID-VkImageCreateInfo-imageType-00976
    If the sparseResidency16Samples feature is not enabled, imageType is VK_IMAGE_TYPE_2D, and samples is VK_SAMPLE_COUNT_16_BIT, flags must not contain VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT

  • VUID-VkImageCreateInfo-flags-00987
    If flags contains VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT or VK_IMAGE_CREATE_SPARSE_ALIASED_BIT, it must also contain VK_IMAGE_CREATE_SPARSE_BINDING_BIT

  • VUID-VkImageCreateInfo-None-01925
    If any of the bits VK_IMAGE_CREATE_SPARSE_BINDING_BIT, VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT, or VK_IMAGE_CREATE_SPARSE_ALIASED_BIT are set, VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT must not also be set

  • VUID-VkImageCreateInfo-flags-01890
    If the protectedMemory feature is not enabled, flags must not contain VK_IMAGE_CREATE_PROTECTED_BIT

  • VUID-VkImageCreateInfo-None-01891
    If any of the bits VK_IMAGE_CREATE_SPARSE_BINDING_BIT, VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT, or VK_IMAGE_CREATE_SPARSE_ALIASED_BIT are set, VK_IMAGE_CREATE_PROTECTED_BIT must not also be set

  • VUID-VkImageCreateInfo-pNext-00988
    If the pNext chain includes a VkExternalMemoryImageCreateInfoNV structure, it must not contain a VkExternalMemoryImageCreateInfo structure

  • VUID-VkImageCreateInfo-pNext-00990
    If the pNext chain includes a VkExternalMemoryImageCreateInfo structure, its handleTypes member must only contain bits that are also in VkExternalImageFormatProperties::externalMemoryProperties.compatibleHandleTypes, as returned by vkGetPhysicalDeviceImageFormatProperties2 with format, imageType, tiling, usage, and flags equal to those in this structure, and with a VkPhysicalDeviceExternalImageFormatInfo structure included in the pNext chain, with a handleType equal to any one of the handle types specified in VkExternalMemoryImageCreateInfo::handleTypes

  • VUID-VkImageCreateInfo-pNext-00991
    If the pNext chain includes a VkExternalMemoryImageCreateInfoNV structure, its handleTypes member must only contain bits that are also in VkExternalImageFormatPropertiesNV::externalMemoryProperties.compatibleHandleTypes, as returned by vkGetPhysicalDeviceExternalImageFormatPropertiesNV with format, imageType, tiling, usage, and flags equal to those in this structure, and with externalHandleType equal to any one of the handle types specified in VkExternalMemoryImageCreateInfoNV::handleTypes

  • VUID-VkImageCreateInfo-physicalDeviceCount-01421
    If the logical device was created with VkDeviceGroupDeviceCreateInfo::physicalDeviceCount equal to 1, flags must not contain VK_IMAGE_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT

  • VUID-VkImageCreateInfo-flags-02259
    If flags contains VK_IMAGE_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT, then mipLevels must be one, arrayLayers must be one, imageType must be VK_IMAGE_TYPE_2D. and imageCreateMaybeLinear (as defined in Image Creation Limits) must be VK_FALSE

  • VUID-VkImageCreateInfo-flags-01572
    If flags contains VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT, then format must be a compressed image format

  • VUID-VkImageCreateInfo-flags-01573
    If flags contains VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT, then flags must also contain VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT

  • VUID-VkImageCreateInfo-initialLayout-00993
    initialLayout must be VK_IMAGE_LAYOUT_UNDEFINED or VK_IMAGE_LAYOUT_PREINITIALIZED

  • VUID-VkImageCreateInfo-pNext-01443
    If the pNext chain includes a VkExternalMemoryImageCreateInfo or VkExternalMemoryImageCreateInfoNV structure whose handleTypes member is not 0, initialLayout must be VK_IMAGE_LAYOUT_UNDEFINED

  • VUID-VkImageCreateInfo-format-06410
    If the image format is one of the formats that require a sampler Y′CBCR conversion, mipLevels must be 1

  • VUID-VkImageCreateInfo-format-06411
    If the image format is one of the formats that require a sampler Y′CBCR conversion, samples must be VK_SAMPLE_COUNT_1_BIT

  • VUID-VkImageCreateInfo-format-06412
    If the image format is one of the formats that require a sampler Y′CBCR conversion, imageType must be VK_IMAGE_TYPE_2D

  • VUID-VkImageCreateInfo-imageCreateFormatFeatures-02260
    If format is a multi-planar format, and if imageCreateFormatFeatures (as defined in Image Creation Limits) does not contain VK_FORMAT_FEATURE_DISJOINT_BIT, then flags must not contain VK_IMAGE_CREATE_DISJOINT_BIT

  • VUID-VkImageCreateInfo-format-01577
    If format is not a multi-planar format, and flags does not include VK_IMAGE_CREATE_ALIAS_BIT, flags must not contain VK_IMAGE_CREATE_DISJOINT_BIT

  • VUID-VkImageCreateInfo-format-04712
    If format has a _422 or _420 suffix, width must be a multiple of 2

  • VUID-VkImageCreateInfo-format-04713
    If format has a _420 suffix, height must be a multiple of 2

  • VUID-VkImageCreateInfo-tiling-02261
    If tiling is VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, then the pNext chain must include exactly one of VkImageDrmFormatModifierListCreateInfoEXT or VkImageDrmFormatModifierExplicitCreateInfoEXT structures

  • VUID-VkImageCreateInfo-pNext-02262
    If the pNext chain includes a VkImageDrmFormatModifierListCreateInfoEXT or VkImageDrmFormatModifierExplicitCreateInfoEXT structure, then tiling must be VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT

  • VUID-VkImageCreateInfo-tiling-02353
    If tiling is VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT and flags contains VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT, then the pNext chain must include a VkImageFormatListCreateInfo structure with non-zero viewFormatCount

  • VUID-VkImageCreateInfo-flags-01533
    If flags contains VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT format must be a depth or depth/stencil format

  • VUID-VkImageCreateInfo-pNext-02393
    If the pNext chain includes a VkExternalMemoryImageCreateInfo structure whose handleTypes member includes VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID, imageType must be VK_IMAGE_TYPE_2D

  • VUID-VkImageCreateInfo-pNext-02394
    If the pNext chain includes a VkExternalMemoryImageCreateInfo structure whose handleTypes member includes VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID, mipLevels must either be 1 or equal to the number of levels in the complete mipmap chain based on extent.width, extent.height, and extent.depth

  • VUID-VkImageCreateInfo-pNext-02396
    If the pNext chain includes a VkExternalFormatANDROID structure whose externalFormat member is not 0, flags must not include VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT

  • VUID-VkImageCreateInfo-pNext-02397
    If the pNext chain includes a VkExternalFormatANDROID structure whose externalFormat member is not 0, usage must not include any usages except VK_IMAGE_USAGE_SAMPLED_BIT

  • VUID-VkImageCreateInfo-pNext-02398
    If the pNext chain includes a VkExternalFormatANDROID structure whose externalFormat member is not 0, tiling must be VK_IMAGE_TILING_OPTIMAL

  • VUID-VkImageCreateInfo-format-02795
    If format is a depth-stencil format, usage includes VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT, and the pNext chain includes a VkImageStencilUsageCreateInfo structure, then its VkImageStencilUsageCreateInfo::stencilUsage member must also include VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT

  • VUID-VkImageCreateInfo-format-02796
    If format is a depth-stencil format, usage does not include VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT, and the pNext chain includes a VkImageStencilUsageCreateInfo structure, then its VkImageStencilUsageCreateInfo::stencilUsage member must also not include VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT

  • VUID-VkImageCreateInfo-format-02797
    If format is a depth-stencil format, usage includes VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT, and the pNext chain includes a VkImageStencilUsageCreateInfo structure, then its VkImageStencilUsageCreateInfo::stencilUsage member must also include VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT

  • VUID-VkImageCreateInfo-format-02798
    If format is a depth-stencil format, usage does not include VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT, and the pNext chain includes a VkImageStencilUsageCreateInfo structure, then its VkImageStencilUsageCreateInfo::stencilUsage member must also not include VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT

  • VUID-VkImageCreateInfo-Format-02536
    If Format is a depth-stencil format and the pNext chain includes a VkImageStencilUsageCreateInfo structure with its stencilUsage member including VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT, extent.width must be less than or equal to VkPhysicalDeviceLimits::maxFramebufferWidth

  • VUID-VkImageCreateInfo-format-02537
    If format is a depth-stencil format and the pNext chain includes a VkImageStencilUsageCreateInfo structure with its stencilUsage member including VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT, extent.height must be less than or equal to VkPhysicalDeviceLimits::maxFramebufferHeight

  • VUID-VkImageCreateInfo-format-02538
    If the shaderStorageImageMultisample feature is not enabled, format is a depth-stencil format and the pNext chain includes a VkImageStencilUsageCreateInfo structure with its stencilUsage including VK_IMAGE_USAGE_STORAGE_BIT, samples must be VK_SAMPLE_COUNT_1_BIT

  • VUID-VkImageCreateInfo-flags-02050
    If flags contains VK_IMAGE_CREATE_CORNER_SAMPLED_BIT_NV, imageType must be VK_IMAGE_TYPE_2D or VK_IMAGE_TYPE_3D

  • VUID-VkImageCreateInfo-flags-02051
    If flags contains VK_IMAGE_CREATE_CORNER_SAMPLED_BIT_NV, it must not contain VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT and the format must not be a depth/stencil format

  • VUID-VkImageCreateInfo-flags-02052
    If flags contains VK_IMAGE_CREATE_CORNER_SAMPLED_BIT_NV and imageType is VK_IMAGE_TYPE_2D, extent.width and extent.height must be greater than 1

  • VUID-VkImageCreateInfo-flags-02053
    If flags contains VK_IMAGE_CREATE_CORNER_SAMPLED_BIT_NV and imageType is VK_IMAGE_TYPE_3D, extent.width, extent.height, and extent.depth must be greater than 1

  • VUID-VkImageCreateInfo-imageType-02082
    If usage includes VK_IMAGE_USAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR, imageType must be VK_IMAGE_TYPE_2D

  • VUID-VkImageCreateInfo-samples-02083
    If usage includes VK_IMAGE_USAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR, samples must be VK_SAMPLE_COUNT_1_BIT

  • VUID-VkImageCreateInfo-shadingRateImage-07727
    If the shadingRateImage feature is enabled and usage includes VK_IMAGE_USAGE_SHADING_RATE_IMAGE_BIT_NV, tiling must be VK_IMAGE_TILING_OPTIMAL

  • VUID-VkImageCreateInfo-flags-02565
    If flags contains VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT, tiling must be VK_IMAGE_TILING_OPTIMAL

  • VUID-VkImageCreateInfo-flags-02566
    If flags contains VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT, imageType must be VK_IMAGE_TYPE_2D

  • VUID-VkImageCreateInfo-flags-02567
    If flags contains VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT, flags must not contain VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT

  • VUID-VkImageCreateInfo-flags-02568
    If flags contains VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT, mipLevels must be 1

  • VUID-VkImageCreateInfo-usage-04992
    If usage includes VK_IMAGE_USAGE_INVOCATION_MASK_BIT_HUAWEI, tiling must be VK_IMAGE_TILING_LINEAR

  • VUID-VkImageCreateInfo-imageView2DOn3DImage-04459
    If the VK_KHR_portability_subset extension is enabled, and VkPhysicalDevicePortabilitySubsetFeaturesKHR::imageView2DOn3DImage is VK_FALSE, flags must not contain VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT

  • VUID-VkImageCreateInfo-multisampleArrayImage-04460
    If the VK_KHR_portability_subset extension is enabled, and VkPhysicalDevicePortabilitySubsetFeaturesKHR::multisampleArrayImage is VK_FALSE, and samples is not VK_SAMPLE_COUNT_1_BIT, then arrayLayers must be 1

  • VUID-VkImageCreateInfo-pNext-06722
    If a VkImageFormatListCreateInfo structure was included in the pNext chain and VkImageFormatListCreateInfo::viewFormatCount is not zero, then each format in VkImageFormatListCreateInfo::pViewFormats must either be compatible with the format as described in the compatibility table or, if flags contains VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT, be an uncompressed format that is size-compatible with format

  • VUID-VkImageCreateInfo-flags-04738
    If flags does not contain VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT and the pNext chain includes a VkImageFormatListCreateInfo structure, then VkImageFormatListCreateInfo::viewFormatCount must be 0 or 1

  • VUID-VkImageCreateInfo-usage-04815
    If usage includes VK_IMAGE_USAGE_VIDEO_DECODE_SRC_BIT_KHR, VK_IMAGE_USAGE_VIDEO_DECODE_DST_BIT_KHR, or VK_IMAGE_USAGE_VIDEO_DECODE_DPB_BIT_KHR, then the pNext chain must include a VkVideoProfileListInfoKHR structure with profileCount greater than 0 and pProfiles including at least one VkVideoProfileInfoKHR structure with a videoCodecOperation member specifying a decode operation

  • VUID-VkImageCreateInfo-usage-04816
    If usage includes VK_IMAGE_USAGE_VIDEO_ENCODE_SRC_BIT_KHR, VK_IMAGE_USAGE_VIDEO_ENCODE_DST_BIT_KHR, or VK_IMAGE_USAGE_VIDEO_ENCODE_DPB_BIT_KHR, then the pNext chain must include a VkVideoProfileListInfoKHR structure with profileCount greater than 0 and pProfiles including at least one VkVideoProfileInfoKHR structure with a videoCodecOperation member specifying an encode operation

  • VUID-VkImageCreateInfo-pNext-06811
    If the pNext chain includes a VkVideoProfileListInfoKHR structure with profileCount greater than 0, then supportedVideoFormat must be VK_TRUE

  • VUID-VkImageCreateInfo-pNext-06390
    If the VkImage is to be used to import memory from a VkBufferCollectionFUCHSIA, a VkBufferCollectionImageCreateInfoFUCHSIA structure must be chained to pNext

  • VUID-VkImageCreateInfo-multisampledRenderToSingleSampled-06882
    If the multisampledRenderToSingleSampled feature is not enabled, flags must not contain VK_IMAGE_CREATE_MULTISAMPLED_RENDER_TO_SINGLE_SAMPLED_BIT_EXT

  • VUID-VkImageCreateInfo-flags-06883
    If flags contains VK_IMAGE_CREATE_MULTISAMPLED_RENDER_TO_SINGLE_SAMPLED_BIT_EXT, samples must be VK_SAMPLE_COUNT_1_BIT

  • VUID-VkImageCreateInfo-pNext-06743
    If the pNext chain includes a VkImageCompressionControlEXT structure, format is a multi-planar format, and VkImageCompressionControlEXT::flags includes VK_IMAGE_COMPRESSION_FIXED_RATE_EXPLICIT_EXT, then VkImageCompressionControlEXT::compressionControlPlaneCount must be equal to the number of planes in format

  • VUID-VkImageCreateInfo-pNext-06744
    If the pNext chain includes a VkImageCompressionControlEXT structure, format is not a multi-planar format, and VkImageCompressionControlEXT::flags includes VK_IMAGE_COMPRESSION_FIXED_RATE_EXPLICIT_EXT, then VkImageCompressionControlEXT::compressionControlPlaneCount must be 1

  • VUID-VkImageCreateInfo-pNext-06746
    If the pNext chain includes a VkImageCompressionControlEXT structure, it must not contain a VkImageDrmFormatModifierExplicitCreateInfoEXT structure

  • VUID-VkImageCreateInfo-flags-08104
    If flags includes VK_IMAGE_CREATE_DESCRIPTOR_BUFFER_CAPTURE_REPLAY_BIT_EXT, the descriptorBufferCaptureReplay feature must be enabled

  • VUID-VkImageCreateInfo-pNext-08105
    If the pNext chain includes a VkOpaqueCaptureDescriptorDataCreateInfoEXT structure, flags must contain VK_IMAGE_CREATE_DESCRIPTOR_BUFFER_CAPTURE_REPLAY_BIT_EXT

  • VUID-VkImageCreateInfo-pNext-06783
    If the pNext chain includes a VkExportMetalObjectCreateInfoEXT structure, its exportObjectType member must be either VK_EXPORT_METAL_OBJECT_TYPE_METAL_TEXTURE_BIT_EXT or VK_EXPORT_METAL_OBJECT_TYPE_METAL_IOSURFACE_BIT_EXT

  • VUID-VkImageCreateInfo-pNext-06784
    If the pNext chain includes a VkImportMetalTextureInfoEXT structure its plane member must be VK_IMAGE_ASPECT_PLANE_0_BIT, VK_IMAGE_ASPECT_PLANE_1_BIT, or VK_IMAGE_ASPECT_PLANE_2_BIT

  • VUID-VkImageCreateInfo-pNext-06785
    If the pNext chain includes a VkImportMetalTextureInfoEXT structure and the image does not have a multi-planar format, then VkImportMetalTextureInfoEXT::plane must be VK_IMAGE_ASPECT_PLANE_0_BIT

  • VUID-VkImageCreateInfo-pNext-06786
    If the pNext chain includes a VkImportMetalTextureInfoEXT structure and the image has a multi-planar format with only two planes, then VkImportMetalTextureInfoEXT::plane must not be VK_IMAGE_ASPECT_PLANE_2_BIT

Valid Usage (Implicit)

The VkBufferCollectionImageCreateInfoFUCHSIA structure is defined as:

// Provided by VK_FUCHSIA_buffer_collection
typedef struct VkBufferCollectionImageCreateInfoFUCHSIA {
    VkStructureType              sType;
    const void*                  pNext;
    VkBufferCollectionFUCHSIA    collection;
    uint32_t                     index;
} VkBufferCollectionImageCreateInfoFUCHSIA;

  • sType is a VkStructureType value identifying this structure.

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

  • collection is the VkBufferCollectionFUCHSIA handle

  • index is the index of the buffer in the buffer collection from which the memory will be imported

Valid Usage
Valid Usage (Implicit)

  • VUID-VkBufferCollectionImageCreateInfoFUCHSIA-sType-sType
    sType must be VK_STRUCTURE_TYPE_BUFFER_COLLECTION_IMAGE_CREATE_INFO_FUCHSIA

  • VUID-VkBufferCollectionImageCreateInfoFUCHSIA-collection-parameter
    collection must be a valid VkBufferCollectionFUCHSIA handle

The VkImageStencilUsageCreateInfo structure is defined as:

// Provided by VK_VERSION_1_2
typedef struct VkImageStencilUsageCreateInfo {
    VkStructureType      sType;
    const void*          pNext;
    VkImageUsageFlags    stencilUsage;
} VkImageStencilUsageCreateInfo;

or the equivalent

// Provided by VK_EXT_separate_stencil_usage
typedef VkImageStencilUsageCreateInfo VkImageStencilUsageCreateInfoEXT;

  • sType is a VkStructureType value identifying this structure.

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

  • stencilUsage is a bitmask of VkImageUsageFlagBits describing the intended usage of the stencil aspect of the image.

If the pNext chain of VkImageCreateInfo includes a VkImageStencilUsageCreateInfo structure, then that structure includes the usage flags specific to the stencil aspect of the image for an image with a depth-stencil format.

This structure specifies image usages which only apply to the stencil aspect of a depth/stencil format image. When this structure is included in the pNext chain of VkImageCreateInfo, the stencil aspect of the image must only be used as specified by stencilUsage. When this structure is not included in the pNext chain of VkImageCreateInfo, the stencil aspect of an image must only be used as specified by VkImageCreateInfo::usage. Use of other aspects of an image are unaffected by this structure.

This structure can also be included in the pNext chain of VkPhysicalDeviceImageFormatInfo2 to query additional capabilities specific to image creation parameter combinations including a separate set of usage flags for the stencil aspect of the image using vkGetPhysicalDeviceImageFormatProperties2. When this structure is not included in the pNext chain of VkPhysicalDeviceImageFormatInfo2 then the implicit value of stencilUsage matches that of VkPhysicalDeviceImageFormatInfo2::usage.

Valid Usage

  • VUID-VkImageStencilUsageCreateInfo-stencilUsage-02539
    If stencilUsage includes VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT, it must not include bits other than VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT or VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT

Valid Usage (Implicit)

  • VUID-VkImageStencilUsageCreateInfo-sType-sType
    sType must be VK_STRUCTURE_TYPE_IMAGE_STENCIL_USAGE_CREATE_INFO

  • VUID-VkImageStencilUsageCreateInfo-stencilUsage-parameter
    stencilUsage must be a valid combination of VkImageUsageFlagBits values

  • VUID-VkImageStencilUsageCreateInfo-stencilUsage-requiredbitmask
    stencilUsage must not be 0

If the pNext chain includes a VkDedicatedAllocationImageCreateInfoNV structure, then that structure includes an enable controlling whether the image will have a dedicated memory allocation bound to it.

The VkDedicatedAllocationImageCreateInfoNV structure is defined as:

// Provided by VK_NV_dedicated_allocation
typedef struct VkDedicatedAllocationImageCreateInfoNV {
    VkStructureType    sType;
    const void*        pNext;
    VkBool32           dedicatedAllocation;
} VkDedicatedAllocationImageCreateInfoNV;

  • sType is a VkStructureType value identifying this structure.

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

  • dedicatedAllocation specifies whether the image will have a dedicated allocation bound to it.

Note

Using a dedicated allocation for color and depth/stencil attachments or other large images may improve performance on some devices.
Valid Usage

  • VUID-VkDedicatedAllocationImageCreateInfoNV-dedicatedAllocation-00994
    If dedicatedAllocation is VK_TRUE, VkImageCreateInfo::flags must not include VK_IMAGE_CREATE_SPARSE_BINDING_BIT, VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT, or VK_IMAGE_CREATE_SPARSE_ALIASED_BIT

Valid Usage (Implicit)

  • VUID-VkDedicatedAllocationImageCreateInfoNV-sType-sType
    sType must be VK_STRUCTURE_TYPE_DEDICATED_ALLOCATION_IMAGE_CREATE_INFO_NV

To define a set of external memory handle types that may be used as backing store for an image, add a VkExternalMemoryImageCreateInfo structure to the pNext chain of the VkImageCreateInfo structure. The VkExternalMemoryImageCreateInfo structure is defined as:

// Provided by VK_VERSION_1_1
typedef struct VkExternalMemoryImageCreateInfo {
    VkStructureType                    sType;
    const void*                        pNext;
    VkExternalMemoryHandleTypeFlags    handleTypes;
} VkExternalMemoryImageCreateInfo;

or the equivalent

// Provided by VK_KHR_external_memory
typedef VkExternalMemoryImageCreateInfo VkExternalMemoryImageCreateInfoKHR;
Note

A VkExternalMemoryImageCreateInfo structure with a non-zero handleTypes field must be included in the creation parameters for an image that will be bound to memory that is either exported or imported.

  • 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 external memory handle types.

Valid Usage (Implicit)

  • VUID-VkExternalMemoryImageCreateInfo-sType-sType
    sType must be VK_STRUCTURE_TYPE_EXTERNAL_MEMORY_IMAGE_CREATE_INFO

  • VUID-VkExternalMemoryImageCreateInfo-handleTypes-parameter
    handleTypes must be a valid combination of VkExternalMemoryHandleTypeFlagBits values

If the pNext chain includes a VkExternalMemoryImageCreateInfoNV structure, then that structure defines a set of external memory handle types that may be used as backing store for the image.

The VkExternalMemoryImageCreateInfoNV structure is defined as:

// Provided by VK_NV_external_memory
typedef struct VkExternalMemoryImageCreateInfoNV {
    VkStructureType                      sType;
    const void*                          pNext;
    VkExternalMemoryHandleTypeFlagsNV    handleTypes;
} VkExternalMemoryImageCreateInfoNV;

  • 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 VkExternalMemoryHandleTypeFlagBitsNV specifying one or more external memory handle types.

Valid Usage (Implicit)

  • VUID-VkExternalMemoryImageCreateInfoNV-sType-sType
    sType must be VK_STRUCTURE_TYPE_EXTERNAL_MEMORY_IMAGE_CREATE_INFO_NV

  • VUID-VkExternalMemoryImageCreateInfoNV-handleTypes-parameter
    handleTypes must be a valid combination of VkExternalMemoryHandleTypeFlagBitsNV values

To create an image with an external format, add a VkExternalFormatANDROID structure in the pNext chain of VkImageCreateInfo. VkExternalFormatANDROID is defined as:

// Provided by VK_ANDROID_external_memory_android_hardware_buffer
typedef struct VkExternalFormatANDROID {
    VkStructureType    sType;
    void*              pNext;
    uint64_t           externalFormat;
} VkExternalFormatANDROID;

  • sType is a VkStructureType value identifying this structure.

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

  • externalFormat is an implementation-defined identifier for the external format

If externalFormat is zero, the effect is as if the VkExternalFormatANDROID structure was not present. Otherwise, the image will have the specified external format.

Valid Usage
Valid Usage (Implicit)

  • VUID-VkExternalFormatANDROID-sType-sType
    sType must be VK_STRUCTURE_TYPE_EXTERNAL_FORMAT_ANDROID

If the pNext chain of VkImageCreateInfo includes a VkImageSwapchainCreateInfoKHR structure, then that structure includes a swapchain handle indicating that the image will be bound to memory from that swapchain.

The VkImageSwapchainCreateInfoKHR structure is defined as:

// Provided by VK_VERSION_1_1 with VK_KHR_swapchain, VK_KHR_device_group with VK_KHR_swapchain
typedef struct VkImageSwapchainCreateInfoKHR {
    VkStructureType    sType;
    const void*        pNext;
    VkSwapchainKHR     swapchain;
} VkImageSwapchainCreateInfoKHR;

  • sType is a VkStructureType value identifying this structure.

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

  • swapchain is VK_NULL_HANDLE or a handle of a swapchain that the image will be bound to.

Valid Usage
Valid Usage (Implicit)

  • VUID-VkImageSwapchainCreateInfoKHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_IMAGE_SWAPCHAIN_CREATE_INFO_KHR

  • VUID-VkImageSwapchainCreateInfoKHR-swapchain-parameter
    If swapchain is not VK_NULL_HANDLE, swapchain must be a valid VkSwapchainKHR handle

If the pNext chain of VkImageCreateInfo includes a VkImageFormatListCreateInfo structure, then that structure contains a list of all formats that can be used when creating views of this image.

The VkImageFormatListCreateInfo structure is defined as:

// Provided by VK_VERSION_1_2
typedef struct VkImageFormatListCreateInfo {
    VkStructureType    sType;
    const void*        pNext;
    uint32_t           viewFormatCount;
    const VkFormat*    pViewFormats;
} VkImageFormatListCreateInfo;

or the equivalent

// Provided by VK_KHR_image_format_list
typedef VkImageFormatListCreateInfo VkImageFormatListCreateInfoKHR;

  • sType is a VkStructureType value identifying this structure.

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

  • viewFormatCount is the number of entries in the pViewFormats array.

  • pViewFormats is a pointer to an array of VkFormat values specifying all formats which can be used when creating views of this image.

If viewFormatCount is zero, pViewFormats is ignored and the image is created as if the VkImageFormatListCreateInfo structure were not included in the pNext chain of VkImageCreateInfo.

Valid Usage (Implicit)

  • VUID-VkImageFormatListCreateInfo-sType-sType
    sType must be VK_STRUCTURE_TYPE_IMAGE_FORMAT_LIST_CREATE_INFO

  • VUID-VkImageFormatListCreateInfo-pViewFormats-parameter
    If viewFormatCount is not 0, pViewFormats must be a valid pointer to an array of viewFormatCount valid VkFormat values

If the pNext chain of VkImageCreateInfo includes a VkImageDrmFormatModifierListCreateInfoEXT structure, then the image will be created with one of the Linux DRM format modifiers listed in the structure. The choice of modifier is implementation-dependent.

The VkImageDrmFormatModifierListCreateInfoEXT structure is defined as:

// Provided by VK_EXT_image_drm_format_modifier
typedef struct VkImageDrmFormatModifierListCreateInfoEXT {
    VkStructureType    sType;
    const void*        pNext;
    uint32_t           drmFormatModifierCount;
    const uint64_t*    pDrmFormatModifiers;
} VkImageDrmFormatModifierListCreateInfoEXT;

  • sType is a VkStructureType value identifying this structure.

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

  • drmFormatModifierCount is the length of the pDrmFormatModifiers array.

  • pDrmFormatModifiers is a pointer to an array of Linux DRM format modifiers.

Valid Usage
Valid Usage (Implicit)

  • VUID-VkImageDrmFormatModifierListCreateInfoEXT-sType-sType
    sType must be VK_STRUCTURE_TYPE_IMAGE_DRM_FORMAT_MODIFIER_LIST_CREATE_INFO_EXT

  • VUID-VkImageDrmFormatModifierListCreateInfoEXT-pDrmFormatModifiers-parameter
    pDrmFormatModifiers must be a valid pointer to an array of drmFormatModifierCount uint64_t values

  • VUID-VkImageDrmFormatModifierListCreateInfoEXT-drmFormatModifierCount-arraylength
    drmFormatModifierCount must be greater than 0

If the pNext chain of VkImageCreateInfo includes a VkImageDrmFormatModifierExplicitCreateInfoEXT structure, then the image will be created with the Linux DRM format modifier and memory layout defined by the structure.

The VkImageDrmFormatModifierExplicitCreateInfoEXT structure is defined as:

// Provided by VK_EXT_image_drm_format_modifier
typedef struct VkImageDrmFormatModifierExplicitCreateInfoEXT {
    VkStructureType               sType;
    const void*                   pNext;
    uint64_t                      drmFormatModifier;
    uint32_t                      drmFormatModifierPlaneCount;
    const VkSubresourceLayout*    pPlaneLayouts;
} VkImageDrmFormatModifierExplicitCreateInfoEXT;

  • sType is a VkStructureType value identifying this structure.

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

  • drmFormatModifier is the Linux DRM format modifier with which the image will be created.

  • drmFormatModifierPlaneCount is the number of memory planes in the image (as reported by VkDrmFormatModifierPropertiesEXT) as well as the length of the pPlaneLayouts array.

  • pPlaneLayouts is a pointer to an array of VkSubresourceLayout structures describing the image’s memory planes.

The ith member of pPlaneLayouts describes the layout of the image’s ith memory plane (that is, VK_IMAGE_ASPECT_MEMORY_PLANE_i_BIT_EXT). In each element of pPlaneLayouts, the implementation must ignore size. The implementation calculates the size of each plane, which the application can query with vkGetImageSubresourceLayout.

When creating an image with VkImageDrmFormatModifierExplicitCreateInfoEXT, it is the application’s responsibility to satisfy all valid usage requirements. However, the implementation must validate that the provided pPlaneLayouts, when combined with the provided drmFormatModifier and other creation parameters in VkImageCreateInfo and its pNext chain, produce a valid image. (This validation is necessarily implementation-dependent and outside the scope of Vulkan, and therefore not described by valid usage requirements). If this validation fails, then vkCreateImage returns VK_ERROR_INVALID_DRM_FORMAT_MODIFIER_PLANE_LAYOUT_EXT.

Valid Usage
Valid Usage (Implicit)

  • VUID-VkImageDrmFormatModifierExplicitCreateInfoEXT-sType-sType
    sType must be VK_STRUCTURE_TYPE_IMAGE_DRM_FORMAT_MODIFIER_EXPLICIT_CREATE_INFO_EXT

  • VUID-VkImageDrmFormatModifierExplicitCreateInfoEXT-pPlaneLayouts-parameter
    pPlaneLayouts must be a valid pointer to an array of drmFormatModifierPlaneCount VkSubresourceLayout structures

  • VUID-VkImageDrmFormatModifierExplicitCreateInfoEXT-drmFormatModifierPlaneCount-arraylength
    drmFormatModifierPlaneCount must be greater than 0

If the pNext list of VkImageCreateInfo includes a VkImageCompressionControlEXT structure, then that structure describes compression controls for this image.

The VkImageCompressionControlEXT structure is defined as:

// Provided by VK_EXT_image_compression_control
typedef struct VkImageCompressionControlEXT {
    VkStructureType                         sType;
    const void*                             pNext;
    VkImageCompressionFlagsEXT              flags;
    uint32_t                                compressionControlPlaneCount;
    VkImageCompressionFixedRateFlagsEXT*    pFixedRateFlags;
} VkImageCompressionControlEXT;

  • 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 VkImageCompressionFlagBitsEXT describing compression controls for the image.

  • compressionControlPlaneCount is the number of entries in the pFixedRateFlags array.

  • pFixedRateFlags is NULL or a pointer to an array of VkImageCompressionFixedRateFlagsEXT bitfields describing allowed fixed-rate compression rates of each image plane. It is ignored if flags does not include VK_IMAGE_COMPRESSION_FIXED_RATE_EXPLICIT_EXT.

If enabled, fixed-rate compression is done in an implementation-defined manner and may be applied at block granularity. In that case, a write to an individual texel may modify the value of other texels in the same block.

Valid Usage

  • VUID-VkImageCompressionControlEXT-flags-06747
    flags must be one of VK_IMAGE_COMPRESSION_DEFAULT_EXT, VK_IMAGE_COMPRESSION_FIXED_RATE_DEFAULT_EXT, VK_IMAGE_COMPRESSION_FIXED_RATE_EXPLICIT_EXT, or VK_IMAGE_COMPRESSION_DISABLED_EXT

  • VUID-VkImageCompressionControlEXT-flags-06748
    If flags includes VK_IMAGE_COMPRESSION_FIXED_RATE_EXPLICIT_EXT, pFixedRateFlags must not be NULL

Valid Usage (Implicit)

  • VUID-VkImageCompressionControlEXT-sType-sType
    sType must be VK_STRUCTURE_TYPE_IMAGE_COMPRESSION_CONTROL_EXT

Note

Some combinations of compression properties may not be supported. For example, some implementations may not support different fixed-rate compression rates per plane of a multi-planar format and will not be able to enable fixed-rate compression for any plane if the requested rates differ.

Possible values of VkImageCompressionControlEXT::flags, specifying compression controls for an image, are:

// Provided by VK_EXT_image_compression_control
typedef enum VkImageCompressionFlagBitsEXT {
    VK_IMAGE_COMPRESSION_DEFAULT_EXT = 0,
    VK_IMAGE_COMPRESSION_FIXED_RATE_DEFAULT_EXT = 0x00000001,
    VK_IMAGE_COMPRESSION_FIXED_RATE_EXPLICIT_EXT = 0x00000002,
    VK_IMAGE_COMPRESSION_DISABLED_EXT = 0x00000004,
} VkImageCompressionFlagBitsEXT;

  • VK_IMAGE_COMPRESSION_DEFAULT_EXT specifies that the default image compression setting is used. Implementations must not apply fixed-rate compression.

  • VK_IMAGE_COMPRESSION_FIXED_RATE_DEFAULT_EXT specifies that the implementation may choose any supported fixed-rate compression setting in an implementation-defined manner based on the properties of the image.

  • VK_IMAGE_COMPRESSION_FIXED_RATE_EXPLICIT_EXT specifies that fixed-rate compression may be used and that the allowed compression rates are specified by VkImageCompressionControlEXT::pFixedRateFlags.

  • VK_IMAGE_COMPRESSION_DISABLED_EXT specifies that all lossless and fixed-rate compression should be disabled.

If VkImageCompressionControlEXT::flags is VK_IMAGE_COMPRESSION_FIXED_RATE_EXPLICIT_EXT, then the ith member of the pFixedRateFlags array specifies the allowed compression rates for the image’s ith plane.

Note

If VK_IMAGE_COMPRESSION_DISABLED_EXT is included in VkImageCompressionControlEXT::flags, both lossless and fixed-rate compression will be disabled. This is likely to have a negative impact on performance and is only intended to be used for debugging purposes.

 
// Provided by VK_EXT_image_compression_control
typedef VkFlags VkImageCompressionFlagsEXT;

VkImageCompressionFlagsEXT is a bitmask type for setting a mask of zero or more VkImageCompressionFlagBitsEXT.

// Provided by VK_EXT_image_compression_control
typedef VkFlags VkImageCompressionFixedRateFlagsEXT;

VkImageCompressionFixedRateFlagsEXT is a bitmask type for setting a mask of zero or more VkImageCompressionFixedRateFlagBitsEXT.

Bits which can be set in VkImageCompressionControlEXT::pFixedRateFlags, specifying allowed compression rates for an image plane, are:

// Provided by VK_EXT_image_compression_control
typedef enum VkImageCompressionFixedRateFlagBitsEXT {
    VK_IMAGE_COMPRESSION_FIXED_RATE_NONE_EXT = 0,
    VK_IMAGE_COMPRESSION_FIXED_RATE_1BPC_BIT_EXT = 0x00000001,
    VK_IMAGE_COMPRESSION_FIXED_RATE_2BPC_BIT_EXT = 0x00000002,
    VK_IMAGE_COMPRESSION_FIXED_RATE_3BPC_BIT_EXT = 0x00000004,
    VK_IMAGE_COMPRESSION_FIXED_RATE_4BPC_BIT_EXT = 0x00000008,
    VK_IMAGE_COMPRESSION_FIXED_RATE_5BPC_BIT_EXT = 0x00000010,
    VK_IMAGE_COMPRESSION_FIXED_RATE_6BPC_BIT_EXT = 0x00000020,
    VK_IMAGE_COMPRESSION_FIXED_RATE_7BPC_BIT_EXT = 0x00000040,
    VK_IMAGE_COMPRESSION_FIXED_RATE_8BPC_BIT_EXT = 0x00000080,
    VK_IMAGE_COMPRESSION_FIXED_RATE_9BPC_BIT_EXT = 0x00000100,
    VK_IMAGE_COMPRESSION_FIXED_RATE_10BPC_BIT_EXT = 0x00000200,
    VK_IMAGE_COMPRESSION_FIXED_RATE_11BPC_BIT_EXT = 0x00000400,
    VK_IMAGE_COMPRESSION_FIXED_RATE_12BPC_BIT_EXT = 0x00000800,
    VK_IMAGE_COMPRESSION_FIXED_RATE_13BPC_BIT_EXT = 0x00001000,
    VK_IMAGE_COMPRESSION_FIXED_RATE_14BPC_BIT_EXT = 0x00002000,
    VK_IMAGE_COMPRESSION_FIXED_RATE_15BPC_BIT_EXT = 0x00004000,
    VK_IMAGE_COMPRESSION_FIXED_RATE_16BPC_BIT_EXT = 0x00008000,
    VK_IMAGE_COMPRESSION_FIXED_RATE_17BPC_BIT_EXT = 0x00010000,
    VK_IMAGE_COMPRESSION_FIXED_RATE_18BPC_BIT_EXT = 0x00020000,
    VK_IMAGE_COMPRESSION_FIXED_RATE_19BPC_BIT_EXT = 0x00040000,
    VK_IMAGE_COMPRESSION_FIXED_RATE_20BPC_BIT_EXT = 0x00080000,
    VK_IMAGE_COMPRESSION_FIXED_RATE_21BPC_BIT_EXT = 0x00100000,
    VK_IMAGE_COMPRESSION_FIXED_RATE_22BPC_BIT_EXT = 0x00200000,
    VK_IMAGE_COMPRESSION_FIXED_RATE_23BPC_BIT_EXT = 0x00400000,
    VK_IMAGE_COMPRESSION_FIXED_RATE_24BPC_BIT_EXT = 0x00800000,
} VkImageCompressionFixedRateFlagBitsEXT;

  • VK_IMAGE_COMPRESSION_FIXED_RATE_NONE_EXT specifies that fixed-rate compression must not be used.

  • VK_IMAGE_COMPRESSION_FIXED_RATE_1BPC_BIT_EXT specifies that fixed-rate compression with a bitrate of [1,2) bits per component may be used.

  • VK_IMAGE_COMPRESSION_FIXED_RATE_2BPC_BIT_EXT specifies that fixed-rate compression with a bitrate of [2,3) bits per component may be used.

  • VK_IMAGE_COMPRESSION_FIXED_RATE_3BPC_BIT_EXT specifies that fixed-rate compression with a bitrate of [3,4) bits per component may be used.

  • VK_IMAGE_COMPRESSION_FIXED_RATE_4BPC_BIT_EXT specifies that fixed-rate compression with a bitrate of [4,5) bits per component may be used.

  • VK_IMAGE_COMPRESSION_FIXED_RATE_5BPC_BIT_EXT specifies that fixed-rate compression with a bitrate of [5,6) bits per component may be used.

  • VK_IMAGE_COMPRESSION_FIXED_RATE_6BPC_BIT_EXT specifies that fixed-rate compression with a bitrate of [6,7) bits per component may be used.

  • VK_IMAGE_COMPRESSION_FIXED_RATE_7BPC_BIT_EXT specifies that fixed-rate compression with a bitrate of [7,8) bits per component may be used.

  • VK_IMAGE_COMPRESSION_FIXED_RATE_8BPC_BIT_EXT specifies that fixed-rate compression with a bitrate of [8,9) bits per component may be used.

  • VK_IMAGE_COMPRESSION_FIXED_RATE_9BPC_BIT_EXT specifies that fixed-rate compression with a bitrate of [9,10) bits per component may be used.

  • VK_IMAGE_COMPRESSION_FIXED_RATE_10BPC_BIT_EXT specifies that fixed-rate compression with a bitrate of [10,11) bits per component may be used.

  • VK_IMAGE_COMPRESSION_FIXED_RATE_11BPC_BIT_EXT specifies that fixed-rate compression with a bitrate of [11,12) bits per component may be used.

  • VK_IMAGE_COMPRESSION_FIXED_RATE_12BPC_BIT_EXT specifies that fixed-rate compression with a bitrate of at least 12 bits per component may be used.

If the format has a different bit rate for different components, VkImageCompressionControlEXT::pFixedRateFlags describes the rate of the component with the largest number of bits assigned to it, scaled pro rata. For example, to request that a VK_FORMAT_A2R10G10B10_UNORM_PACK32 format be stored at a rate of 8 bits per pixel, use VK_IMAGE_COMPRESSION_FIXED_RATE_2BPC_BIT_EXT (10 bits for the largest component, stored at quarter the original size, 2.5 bits, rounded down).

If flags includes VK_IMAGE_COMPRESSION_FIXED_RATE_EXPLICIT_EXT, and multiple bits are set in VkImageCompressionControlEXT::pFixedRateFlags for a plane, implementations should apply the lowest allowed bitrate that is supported.

Note

The choice of “bits per component” terminology was chosen so that the same compression rate describes the same degree of compression applied to formats that differ only in the number of components. For example, VK_FORMAT_R8G8_UNORM compressed to half its original size is a rate of 4 bits per component, 8 bits per pixel. VK_FORMAT_R8G8B8A8_UNORM compressed to half its original size is 4 bits per component, 16 bits per pixel. Both of these cases can be requested with VK_IMAGE_COMPRESSION_FIXED_RATE_4BPC_BIT_EXT.

To query the compression properties of an image, add a VkImageCompressionPropertiesEXT structure to the pNext chain of the VkSubresourceLayout2EXT structure in a call to vkGetImageSubresourceLayout2EXT.

To determine the compression rates that are supported for a given image format, add a VkImageCompressionPropertiesEXT structure to the pNext chain of the VkImageFormatProperties2 structure in a call to vkGetPhysicalDeviceImageFormatProperties2.

Note

Since fixed-rate compression is disabled by default, the VkImageCompressionPropertiesEXT structure passed to vkGetPhysicalDeviceImageFormatProperties2 will not indicate any fixed-rate compression support unless a VkImageCompressionControlEXT structure is also included in the pNext chain of the VkPhysicalDeviceImageFormatInfo2 structure passed to the same command.

The VkImageCompressionPropertiesEXT structure is defined as:

// Provided by VK_EXT_image_compression_control
typedef struct VkImageCompressionPropertiesEXT {
    VkStructureType                        sType;
    void*                                  pNext;
    VkImageCompressionFlagsEXT             imageCompressionFlags;
    VkImageCompressionFixedRateFlagsEXT    imageCompressionFixedRateFlags;
} VkImageCompressionPropertiesEXT;

  • sType is a VkStructureType value identifying this structure.

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

  • imageCompressionFlags returns a value describing the compression controls that apply to the image. The value will be either VK_IMAGE_COMPRESSION_DEFAULT_EXT to indicate no fixed-rate compression, VK_IMAGE_COMPRESSION_FIXED_RATE_EXPLICIT_EXT to indicate fixed-rate compression, or VK_IMAGE_COMPRESSION_DISABLED_EXT to indicate no compression.

  • imageCompressionFixedRateFlags returns a VkImageCompressionFixedRateFlagsEXT value describing the compression rates that apply to the specified aspect of the image.

Valid Usage (Implicit)

  • VUID-VkImageCompressionPropertiesEXT-sType-sType
    sType must be VK_STRUCTURE_TYPE_IMAGE_COMPRESSION_PROPERTIES_EXT

Bits which can be set in

specify intended usage of an image, and are:

// Provided by VK_VERSION_1_0
typedef enum VkImageUsageFlagBits {
    VK_IMAGE_USAGE_TRANSFER_SRC_BIT = 0x00000001,
    VK_IMAGE_USAGE_TRANSFER_DST_BIT = 0x00000002,
    VK_IMAGE_USAGE_SAMPLED_BIT = 0x00000004,
    VK_IMAGE_USAGE_STORAGE_BIT = 0x00000008,
    VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT = 0x00000010,
    VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT = 0x00000020,
    VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT = 0x00000040,
    VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT = 0x00000080,
  // Provided by VK_KHR_video_decode_queue
    VK_IMAGE_USAGE_VIDEO_DECODE_DST_BIT_KHR = 0x00000400,
  // Provided by VK_KHR_video_decode_queue
    VK_IMAGE_USAGE_VIDEO_DECODE_SRC_BIT_KHR = 0x00000800,
  // Provided by VK_KHR_video_decode_queue
    VK_IMAGE_USAGE_VIDEO_DECODE_DPB_BIT_KHR = 0x00001000,
  // Provided by VK_EXT_fragment_density_map
    VK_IMAGE_USAGE_FRAGMENT_DENSITY_MAP_BIT_EXT = 0x00000200,
  // Provided by VK_KHR_fragment_shading_rate
    VK_IMAGE_USAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR = 0x00000100,
  // Provided by VK_EXT_host_image_copy
    VK_IMAGE_USAGE_HOST_TRANSFER_BIT_EXT = 0x00400000,
#ifdef VK_ENABLE_BETA_EXTENSIONS
  // Provided by VK_KHR_video_encode_queue
    VK_IMAGE_USAGE_VIDEO_ENCODE_DST_BIT_KHR = 0x00002000,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
  // Provided by VK_KHR_video_encode_queue
    VK_IMAGE_USAGE_VIDEO_ENCODE_SRC_BIT_KHR = 0x00004000,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
  // Provided by VK_KHR_video_encode_queue
    VK_IMAGE_USAGE_VIDEO_ENCODE_DPB_BIT_KHR = 0x00008000,
#endif
  // Provided by VK_EXT_attachment_feedback_loop_layout
    VK_IMAGE_USAGE_ATTACHMENT_FEEDBACK_LOOP_BIT_EXT = 0x00080000,
  // Provided by VK_HUAWEI_invocation_mask
    VK_IMAGE_USAGE_INVOCATION_MASK_BIT_HUAWEI = 0x00040000,
  // Provided by VK_QCOM_image_processing
    VK_IMAGE_USAGE_SAMPLE_WEIGHT_BIT_QCOM = 0x00100000,
  // Provided by VK_QCOM_image_processing
    VK_IMAGE_USAGE_SAMPLE_BLOCK_MATCH_BIT_QCOM = 0x00200000,
  // Provided by VK_NV_shading_rate_image
    VK_IMAGE_USAGE_SHADING_RATE_IMAGE_BIT_NV = VK_IMAGE_USAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR,
} VkImageUsageFlagBits;

  • VK_IMAGE_USAGE_TRANSFER_SRC_BIT specifies that the image can be used as the source of a transfer command.

  • VK_IMAGE_USAGE_TRANSFER_DST_BIT specifies that the image can be used as the destination of a transfer command.

  • VK_IMAGE_USAGE_SAMPLED_BIT specifies that the image can be used to create a VkImageView suitable for occupying a VkDescriptorSet slot either of type VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE or VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, and be sampled by a shader.

  • VK_IMAGE_USAGE_STORAGE_BIT specifies that the image can be used to create a VkImageView suitable for occupying a VkDescriptorSet slot of type VK_DESCRIPTOR_TYPE_STORAGE_IMAGE.

  • VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT specifies that the image can be used to create a VkImageView suitable for use as a color or resolve attachment in a VkFramebuffer.

  • VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT specifies that the image can be used to create a VkImageView suitable for use as a depth/stencil or depth/stencil resolve attachment in a VkFramebuffer.

  • VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT specifies that implementations may support using memory allocations with the VK_MEMORY_PROPERTY_LAZILY_ALLOCATED_BIT to back an image with this usage. This bit can be set for any image that can be used to create a VkImageView suitable for use as a color, resolve, depth/stencil, or input attachment.

  • VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT specifies that the image can be used to create a VkImageView suitable for occupying VkDescriptorSet slot of type VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT; be read from a shader as an input attachment; and be used as an input attachment in a framebuffer.

  • VK_IMAGE_USAGE_FRAGMENT_DENSITY_MAP_BIT_EXT specifies that the image can be used to create a VkImageView suitable for use as a fragment density map image.

  • VK_IMAGE_USAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR specifies that the image can be used to create a VkImageView suitable for use as a fragment shading rate attachment or shading rate image

  • VK_IMAGE_USAGE_VIDEO_DECODE_DST_BIT_KHR specifies that the image can be used as a decode output picture in a video decode operation.

  • VK_IMAGE_USAGE_VIDEO_DECODE_SRC_BIT_KHR is reserved for future use.

  • VK_IMAGE_USAGE_VIDEO_DECODE_DPB_BIT_KHR specifies that the image can be used as an output reconstructed picture or an input reference picture in a video decode operation.

  • VK_IMAGE_USAGE_VIDEO_ENCODE_DST_BIT_KHR is reserved for future use.

  • VK_IMAGE_USAGE_VIDEO_ENCODE_SRC_BIT_KHR specifies that the image can be used as an encode input picture in a video encode operation.

  • VK_IMAGE_USAGE_VIDEO_ENCODE_DPB_BIT_KHR specifies that the image can be used as an output reconstructed picture or an input reference picture in a video encode operation.

  • VK_IMAGE_USAGE_ATTACHMENT_FEEDBACK_LOOP_BIT_EXT specifies that the image can be transitioned to the VK_IMAGE_LAYOUT_ATTACHMENT_FEEDBACK_LOOP_OPTIMAL_EXT layout to be used as a color or depth/stencil attachment in a VkFramebuffer and/or as a read-only input resource in a shader (sampled image, combined image sampler or input attachment) in the same render pass.

// Provided by VK_VERSION_1_0
typedef VkFlags VkImageUsageFlags;

VkImageUsageFlags is a bitmask type for setting a mask of zero or more VkImageUsageFlagBits.

When creating a VkImageView one of the following VkImageUsageFlagBits must be set:

  • VK_IMAGE_USAGE_SAMPLED_BIT

  • VK_IMAGE_USAGE_STORAGE_BIT

  • VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT

  • VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT

  • VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT

  • VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT

  • VK_IMAGE_USAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR

  • VK_IMAGE_USAGE_FRAGMENT_DENSITY_MAP_BIT_EXT

  • VK_IMAGE_USAGE_VIDEO_DECODE_DST_BIT_KHR

  • VK_IMAGE_USAGE_VIDEO_DECODE_DPB_BIT_KHR

  • VK_IMAGE_USAGE_VIDEO_ENCODE_SRC_BIT_KHR

  • VK_IMAGE_USAGE_VIDEO_ENCODE_DPB_BIT_KHR

  • VK_IMAGE_USAGE_SAMPLE_WEIGHT_BIT_QCOM

  • VK_IMAGE_USAGE_SAMPLE_BLOCK_MATCH_BIT_QCOM

Bits which can be set in VkImageCreateInfo::flags, specifying additional parameters of an image, are:

// Provided by VK_VERSION_1_0
typedef enum VkImageCreateFlagBits {
    VK_IMAGE_CREATE_SPARSE_BINDING_BIT = 0x00000001,
    VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT = 0x00000002,
    VK_IMAGE_CREATE_SPARSE_ALIASED_BIT = 0x00000004,
    VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT = 0x00000008,
    VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT = 0x00000010,
  // Provided by VK_VERSION_1_1
    VK_IMAGE_CREATE_ALIAS_BIT = 0x00000400,
  // Provided by VK_VERSION_1_1
    VK_IMAGE_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT = 0x00000040,
  // Provided by VK_VERSION_1_1
    VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT = 0x00000020,
  // Provided by VK_VERSION_1_1
    VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT = 0x00000080,
  // Provided by VK_VERSION_1_1
    VK_IMAGE_CREATE_EXTENDED_USAGE_BIT = 0x00000100,
  // Provided by VK_VERSION_1_1
    VK_IMAGE_CREATE_PROTECTED_BIT = 0x00000800,
  // Provided by VK_VERSION_1_1
    VK_IMAGE_CREATE_DISJOINT_BIT = 0x00000200,
  // Provided by VK_NV_corner_sampled_image
    VK_IMAGE_CREATE_CORNER_SAMPLED_BIT_NV = 0x00002000,
  // Provided by VK_EXT_sample_locations
    VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT = 0x00001000,
  // Provided by VK_EXT_fragment_density_map
    VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT = 0x00004000,
  // Provided by VK_EXT_descriptor_buffer
    VK_IMAGE_CREATE_DESCRIPTOR_BUFFER_CAPTURE_REPLAY_BIT_EXT = 0x00010000,
  // Provided by VK_EXT_multisampled_render_to_single_sampled
    VK_IMAGE_CREATE_MULTISAMPLED_RENDER_TO_SINGLE_SAMPLED_BIT_EXT = 0x00040000,
  // Provided by VK_EXT_image_2d_view_of_3d
    VK_IMAGE_CREATE_2D_VIEW_COMPATIBLE_BIT_EXT = 0x00020000,
  // Provided by VK_QCOM_fragment_density_map_offset
    VK_IMAGE_CREATE_FRAGMENT_DENSITY_MAP_OFFSET_BIT_QCOM = 0x00008000,
  // Provided by VK_KHR_bind_memory2 with VK_KHR_device_group
    VK_IMAGE_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT_KHR = VK_IMAGE_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT,
  // Provided by VK_KHR_maintenance1
    VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT_KHR = VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT,
  // Provided by VK_KHR_maintenance2
    VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT_KHR = VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT,
  // Provided by VK_KHR_maintenance2
    VK_IMAGE_CREATE_EXTENDED_USAGE_BIT_KHR = VK_IMAGE_CREATE_EXTENDED_USAGE_BIT,
  // Provided by VK_KHR_sampler_ycbcr_conversion
    VK_IMAGE_CREATE_DISJOINT_BIT_KHR = VK_IMAGE_CREATE_DISJOINT_BIT,
  // Provided by VK_KHR_bind_memory2
    VK_IMAGE_CREATE_ALIAS_BIT_KHR = VK_IMAGE_CREATE_ALIAS_BIT,
} VkImageCreateFlagBits;

  • VK_IMAGE_CREATE_SPARSE_BINDING_BIT specifies that the image will be backed using sparse memory binding.

  • VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT specifies that the image can be partially backed using sparse memory binding. Images created with this flag must also be created with the VK_IMAGE_CREATE_SPARSE_BINDING_BIT flag.

  • VK_IMAGE_CREATE_SPARSE_ALIASED_BIT specifies that the image will be backed using sparse memory binding with memory ranges that might also simultaneously be backing another image (or another portion of the same image). Images created with this flag must also be created with the VK_IMAGE_CREATE_SPARSE_BINDING_BIT flag.

  • VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT specifies that the image can be used to create a VkImageView with a different format from the image. For multi-planar formats, VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT specifies that a VkImageView can be created of a plane of the image.

  • VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT specifies that the image can be used to create a VkImageView of type VK_IMAGE_VIEW_TYPE_CUBE or VK_IMAGE_VIEW_TYPE_CUBE_ARRAY.

  • VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT specifies that the image can be used to create a VkImageView of type VK_IMAGE_VIEW_TYPE_2D or VK_IMAGE_VIEW_TYPE_2D_ARRAY.

  • VK_IMAGE_CREATE_2D_VIEW_COMPATIBLE_BIT_EXT specifies that the image can be used to create a VkImageView of type VK_IMAGE_VIEW_TYPE_2D.

  • VK_IMAGE_CREATE_PROTECTED_BIT specifies that the image is a protected image.

  • VK_IMAGE_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT specifies that the image can be used with a non-zero value of the splitInstanceBindRegionCount member of a VkBindImageMemoryDeviceGroupInfo structure passed into vkBindImageMemory2. This flag also has the effect of making the image use the standard sparse image block dimensions.

  • VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT specifies that the image having a compressed format can be used to create a VkImageView with an uncompressed format where each texel in the image view corresponds to a compressed texel block of the image.

  • VK_IMAGE_CREATE_EXTENDED_USAGE_BIT specifies that the image can be created with usage flags that are not supported for the format the image is created with but are supported for at least one format a VkImageView created from the image can have.

  • VK_IMAGE_CREATE_DISJOINT_BIT specifies that an image with a multi-planar format must have each plane separately bound to memory, rather than having a single memory binding for the whole image; the presence of this bit distinguishes a disjoint image from an image without this bit set.

  • VK_IMAGE_CREATE_ALIAS_BIT specifies that two images created with the same creation parameters and aliased to the same memory can interpret the contents of the memory consistently with each other, subject to the rules described in the Memory Aliasing section. This flag further specifies that each plane of a disjoint image can share an in-memory non-linear representation with single-plane images, and that a single-plane image can share an in-memory non-linear representation with a plane of a multi-planar disjoint image, according to the rules in Compatible formats of planes of multi-planar formats. If the pNext chain includes a VkExternalMemoryImageCreateInfo or VkExternalMemoryImageCreateInfoNV structure whose handleTypes member is not 0, it is as if VK_IMAGE_CREATE_ALIAS_BIT is set.

  • VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT specifies that an image with a depth or depth/stencil format can be used with custom sample locations when used as a depth/stencil attachment.

  • VK_IMAGE_CREATE_CORNER_SAMPLED_BIT_NV specifies that the image is a corner-sampled image.

  • VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT specifies that an image can be in a subsampled format which may be more optimal when written as an attachment by a render pass that has a fragment density map attachment. Accessing a subsampled image has additional considerations:

    • Image data read as an image sampler will have undefined values if the sampler was not created with flags containing VK_SAMPLER_CREATE_SUBSAMPLED_BIT_EXT or was not sampled through the use of a combined image sampler with an immutable sampler in VkDescriptorSetLayoutBinding.

    • Image data read with an input attachment will have undefined values if the contents were not written as an attachment in an earlier subpass of the same render pass.

    • Image data read as an image sampler in the fragment shader will be additionally be read by the device during VK_PIPELINE_STAGE_VERTEX_SHADER_BIT if VkPhysicalDeviceFragmentDensityMap2PropertiesEXT::subsampledCoarseReconstructionEarlyAccess is VK_TRUE and the sampler was created with flags containing VK_SAMPLER_CREATE_SUBSAMPLED_COARSE_RECONSTRUCTION_BIT_EXT.

    • Image data read with load operations are resampled to the fragment density of the render pass if VkPhysicalDeviceFragmentDensityMap2PropertiesEXT::subsampledLoads is VK_TRUE. Otherwise, values of image data are undefined.

    • Image contents outside of the render area take on undefined values if the image is stored as a render pass attachment.

  • VK_IMAGE_CREATE_FRAGMENT_DENSITY_MAP_OFFSET_BIT_QCOM specifies that an image can be used in a render pass with non-zero fragment density map offsets. In a render pass with non-zero offsets, fragment density map attachments, input attachments, color attachments, depth/stencil attachment, resolve attachments, and preserve attachments must be created with VK_IMAGE_CREATE_FRAGMENT_DENSITY_MAP_OFFSET_BIT_QCOM.

  • VK_IMAGE_CREATE_DESCRIPTOR_BUFFER_CAPTURE_REPLAY_BIT_EXT specifies that the image can be used with descriptor buffers when capturing and replaying (e.g. for trace capture and replay), see VkOpaqueCaptureDescriptorDataCreateInfoEXT for more detail.

  • VK_IMAGE_CREATE_MULTISAMPLED_RENDER_TO_SINGLE_SAMPLED_BIT_EXT specifies that an image can be used with multisampled rendering as a single-sampled framebuffer attachment

See Sparse Resource Features and Sparse Physical Device Features for more details.

// Provided by VK_VERSION_1_0
typedef VkFlags VkImageCreateFlags;

VkImageCreateFlags is a bitmask type for setting a mask of zero or more VkImageCreateFlagBits.

Possible values of VkImageCreateInfo::imageType, specifying the basic dimensionality of an image, are:

// Provided by VK_VERSION_1_0
typedef enum VkImageType {
    VK_IMAGE_TYPE_1D = 0,
    VK_IMAGE_TYPE_2D = 1,
    VK_IMAGE_TYPE_3D = 2,
} VkImageType;

  • VK_IMAGE_TYPE_1D specifies a one-dimensional image.

  • VK_IMAGE_TYPE_2D specifies a two-dimensional image.

  • VK_IMAGE_TYPE_3D specifies a three-dimensional image.

Possible values of VkImageCreateInfo::tiling, specifying the tiling arrangement of texel blocks in an image, are:

// Provided by VK_VERSION_1_0
typedef enum VkImageTiling {
    VK_IMAGE_TILING_OPTIMAL = 0,
    VK_IMAGE_TILING_LINEAR = 1,
  // Provided by VK_EXT_image_drm_format_modifier
    VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT = 1000158000,
} VkImageTiling;

To query the memory layout of an image subresource, call:

// Provided by VK_VERSION_1_0
void vkGetImageSubresourceLayout(
    VkDevice                                    device,
    VkImage                                     image,
    const VkImageSubresource*                   pSubresource,
    VkSubresourceLayout*                        pLayout);

  • device is the logical device that owns the image.

  • image is the image whose layout is being queried.

  • pSubresource is a pointer to a VkImageSubresource structure selecting a specific image subresource from the image.

  • pLayout is a pointer to a VkSubresourceLayout structure in which the layout is returned.

If the image is linear, then the returned layout is valid for host access.

If the image’s tiling is VK_IMAGE_TILING_LINEAR and its format is a multi-planar format, then vkGetImageSubresourceLayout describes one format plane of the image. If the image’s tiling is VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, then vkGetImageSubresourceLayout describes one memory plane of the image. If the image’s tiling is VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT and the image is non-linear, then the returned layout has an implementation-dependent meaning; the vendor of the image’s DRM format modifier may provide documentation that explains how to interpret the returned layout.

vkGetImageSubresourceLayout is invariant for the lifetime of a single image. However, the subresource layout of images in Android hardware buffer or QNX Screen buffer external memory is not known until the image has been bound to memory, so applications must not call vkGetImageSubresourceLayout for such an image before it has been bound.

Valid Usage

  • VUID-vkGetImageSubresourceLayout-image-07790
    image must have been created with tiling equal to VK_IMAGE_TILING_LINEAR or VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT

  • VUID-vkGetImageSubresourceLayout-aspectMask-00997
    The aspectMask member of pSubresource must only have a single bit set

  • VUID-vkGetImageSubresourceLayout-mipLevel-01716
    The mipLevel member of pSubresource must be less than the mipLevels specified in VkImageCreateInfo when image was created

  • VUID-vkGetImageSubresourceLayout-arrayLayer-01717
    The arrayLayer member of pSubresource must be less than the arrayLayers specified in VkImageCreateInfo when image was created

  • VUID-vkGetImageSubresourceLayout-format-08886
    If format of the image is a color format, tiling of the image is VK_IMAGE_TILING_LINEAR or VK_IMAGE_TILING_OPTIMAL, and does not have a multi-planar image format, the aspectMask member of pSubresource must be VK_IMAGE_ASPECT_COLOR_BIT

  • VUID-vkGetImageSubresourceLayout-format-04462
    If format of the image has a depth component, the aspectMask member of pSubresource must contain VK_IMAGE_ASPECT_DEPTH_BIT

  • VUID-vkGetImageSubresourceLayout-format-04463
    If format of the image has a stencil component, the aspectMask member of pSubresource must contain VK_IMAGE_ASPECT_STENCIL_BIT

  • VUID-vkGetImageSubresourceLayout-format-04464
    If format of the image does not contain a stencil or depth component, the aspectMask member of pSubresource must not contain VK_IMAGE_ASPECT_DEPTH_BIT or VK_IMAGE_ASPECT_STENCIL_BIT

  • VUID-vkGetImageSubresourceLayout-tiling-08717
    If the tiling of the image is VK_IMAGE_TILING_LINEAR and has a multi-planar image format, then the aspectMask member of pSubresource must be a single valid multi-planar aspect mask bit

  • VUID-vkGetImageSubresourceLayout-image-01895
    If image was created with the VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID external memory handle type, then image must be bound to memory

  • VUID-vkGetImageSubresourceLayout-tiling-02271
    If the tiling of the image is VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, then the aspectMask member of pSubresource must be VK_IMAGE_ASPECT_MEMORY_PLANE_i_BIT_EXT and the index i must be less than the VkDrmFormatModifierPropertiesEXT::drmFormatModifierPlaneCount associated with the image’s format and VkImageDrmFormatModifierPropertiesEXT::drmFormatModifier

Valid Usage (Implicit)

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

  • VUID-vkGetImageSubresourceLayout-image-parameter
    image must be a valid VkImage handle

  • VUID-vkGetImageSubresourceLayout-pSubresource-parameter
    pSubresource must be a valid pointer to a valid VkImageSubresource structure

  • VUID-vkGetImageSubresourceLayout-pLayout-parameter
    pLayout must be a valid pointer to a VkSubresourceLayout structure

  • VUID-vkGetImageSubresourceLayout-image-parent
    image must have been created, allocated, or retrieved from device

The VkImageSubresource structure is defined as:

// Provided by VK_VERSION_1_0
typedef struct VkImageSubresource {
    VkImageAspectFlags    aspectMask;
    uint32_t              mipLevel;
    uint32_t              arrayLayer;
} VkImageSubresource;

  • aspectMask is a VkImageAspectFlags value selecting the image aspect.

  • mipLevel selects the mipmap level.

  • arrayLayer selects the array layer.

Valid Usage (Implicit)

  • VUID-VkImageSubresource-aspectMask-parameter
    aspectMask must be a valid combination of VkImageAspectFlagBits values

  • VUID-VkImageSubresource-aspectMask-requiredbitmask
    aspectMask must not be 0

Information about the layout of the image subresource is returned in a VkSubresourceLayout structure:

// Provided by VK_VERSION_1_0
typedef struct VkSubresourceLayout {
    VkDeviceSize    offset;
    VkDeviceSize    size;
    VkDeviceSize    rowPitch;
    VkDeviceSize    arrayPitch;
    VkDeviceSize    depthPitch;
} VkSubresourceLayout;

  • offset is the byte offset from the start of the image or the plane where the image subresource begins.

  • size is the size in bytes of the image subresource. size includes any extra memory that is required based on rowPitch.

  • rowPitch describes the number of bytes between each row of texels in an image.

  • arrayPitch describes the number of bytes between each array layer of an image.

  • depthPitch describes the number of bytes between each slice of 3D image.

If the image is linear, then rowPitch, arrayPitch and depthPitch describe the layout of the image subresource in linear memory. For uncompressed formats, rowPitch is the number of bytes between texels with the same x coordinate in adjacent rows (y coordinates differ by one). arrayPitch is the number of bytes between texels with the same x and y coordinate in adjacent array layers of the image (array layer values differ by one). depthPitch is the number of bytes between texels with the same x and y coordinate in adjacent slices of a 3D image (z coordinates differ by one). Expressed as an addressing formula, the starting byte of a texel in the image subresource has address:

// (x,y,z,layer) are in texel coordinates
address(x,y,z,layer) = layer*arrayPitch + z*depthPitch + y*rowPitch + x*elementSize + offset

For compressed formats, the rowPitch is the number of bytes between compressed texel blocks in adjacent rows. arrayPitch is the number of bytes between compressed texel blocks in adjacent array layers. depthPitch is the number of bytes between compressed texel blocks in adjacent slices of a 3D image.

// (x,y,z,layer) are in compressed texel block coordinates
address(x,y,z,layer) = layer*arrayPitch + z*depthPitch + y*rowPitch + x*compressedTexelBlockByteSize + offset;

The value of arrayPitch is undefined for images that were not created as arrays. depthPitch is defined only for 3D images.

If the image has a single-plane color format and its tiling is VK_IMAGE_TILING_LINEAR , then the aspectMask member of VkImageSubresource must be VK_IMAGE_ASPECT_COLOR_BIT.

If the image has a depth/stencil format and its tiling is VK_IMAGE_TILING_LINEAR , then aspectMask must be either VK_IMAGE_ASPECT_DEPTH_BIT or VK_IMAGE_ASPECT_STENCIL_BIT. On implementations that store depth and stencil aspects separately, querying each of these image subresource layouts will return a different offset and size representing the region of memory used for that aspect. On implementations that store depth and stencil aspects interleaved, the same offset and size are returned and represent the interleaved memory allocation.

If the image has a multi-planar format and its tiling is VK_IMAGE_TILING_LINEAR , then the aspectMask member of VkImageSubresource must be VK_IMAGE_ASPECT_PLANE_0_BIT, VK_IMAGE_ASPECT_PLANE_1_BIT, or (for 3-plane formats only) VK_IMAGE_ASPECT_PLANE_2_BIT. Querying each of these image subresource layouts will return a different offset and size representing the region of memory used for that plane. If the image is disjoint, then the offset is relative to the base address of the plane. If the image is non-disjoint, then the offset is relative to the base address of the image.

If the image’s tiling is VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, then the aspectMask member of VkImageSubresource must be one of VK_IMAGE_ASPECT_MEMORY_PLANE_i_BIT_EXT, where the maximum allowed plane index i is defined by the VkDrmFormatModifierPropertiesEXT::drmFormatModifierPlaneCount associated with the image’s VkImageCreateInfo::format and modifier. The memory range used by the subresource is described by offset and size. If the image is disjoint, then the offset is relative to the base address of the memory plane. If the image is non-disjoint, then the offset is relative to the base address of the image. If the image is non-linear, then rowPitch, arrayPitch, and depthPitch have an implementation-dependent meaning.

To query the memory layout of an image subresource, call:

// Provided by VK_EXT_host_image_copy, VK_EXT_image_compression_control
void vkGetImageSubresourceLayout2EXT(
    VkDevice                                    device,
    VkImage                                     image,
    const VkImageSubresource2KHR*               pSubresource,
    VkSubresourceLayout2KHR*                    pLayout);

  • device is the logical device that owns the image.

  • image is the image whose layout is being queried.

  • pSubresource is a pointer to a VkImageSubresource2KHR structure selecting a specific image for the image subresource.

  • pLayout is a pointer to a VkSubresourceLayout2KHR structure in which the layout is returned.

vkGetImageSubresourceLayout2KHR behaves similarly to vkGetImageSubresourceLayout, with the ability to specify extended inputs via chained input structures, and to return extended information via chained output structures.

It is legal to call vkGetImageSubresourceLayout2KHR with a image created with tiling equal to VK_IMAGE_TILING_OPTIMAL, but the members of VkSubresourceLayout2KHR::subresourceLayout will have undefined values in this case.

Note

Structures chained from VkImageSubresource2KHR::pNext will also be updated when tiling is equal to VK_IMAGE_TILING_OPTIMAL.
Valid Usage

  • VUID-vkGetImageSubresourceLayout2KHR-aspectMask-00997
    The aspectMask member of pSubresource must only have a single bit set

  • VUID-vkGetImageSubresourceLayout2KHR-mipLevel-01716
    The mipLevel member of pSubresource must be less than the mipLevels specified in VkImageCreateInfo when image was created

  • VUID-vkGetImageSubresourceLayout2KHR-arrayLayer-01717
    The arrayLayer member of pSubresource must be less than the arrayLayers specified in VkImageCreateInfo when image was created

  • VUID-vkGetImageSubresourceLayout2KHR-format-08886
    If format of the image is a color format, tiling of the image is VK_IMAGE_TILING_LINEAR or VK_IMAGE_TILING_OPTIMAL, and does not have a multi-planar image format, the aspectMask member of pSubresource must be VK_IMAGE_ASPECT_COLOR_BIT

  • VUID-vkGetImageSubresourceLayout2KHR-format-04462
    If format of the image has a depth component, the aspectMask member of pSubresource must contain VK_IMAGE_ASPECT_DEPTH_BIT

  • VUID-vkGetImageSubresourceLayout2KHR-format-04463
    If format of the image has a stencil component, the aspectMask member of pSubresource must contain VK_IMAGE_ASPECT_STENCIL_BIT

  • VUID-vkGetImageSubresourceLayout2KHR-format-04464
    If format of the image does not contain a stencil or depth component, the aspectMask member of pSubresource must not contain VK_IMAGE_ASPECT_DEPTH_BIT or VK_IMAGE_ASPECT_STENCIL_BIT

  • VUID-vkGetImageSubresourceLayout2KHR-tiling-08717
    If the tiling of the image is VK_IMAGE_TILING_LINEAR and has a multi-planar image format, then the aspectMask member of pSubresource must be a single valid multi-planar aspect mask bit

  • VUID-vkGetImageSubresourceLayout2KHR-image-01895
    If image was created with the VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID external memory handle type, then image must be bound to memory

  • VUID-vkGetImageSubresourceLayout2KHR-tiling-02271
    If the tiling of the image is VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, then the aspectMask member of pSubresource must be VK_IMAGE_ASPECT_MEMORY_PLANE_i_BIT_EXT and the index i must be less than the VkDrmFormatModifierPropertiesEXT::drmFormatModifierPlaneCount associated with the image’s format and VkImageDrmFormatModifierPropertiesEXT::drmFormatModifier

Valid Usage (Implicit)

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

  • VUID-vkGetImageSubresourceLayout2KHR-image-parameter
    image must be a valid VkImage handle

  • VUID-vkGetImageSubresourceLayout2KHR-pSubresource-parameter
    pSubresource must be a valid pointer to a valid VkImageSubresource2KHR structure

  • VUID-vkGetImageSubresourceLayout2KHR-pLayout-parameter
    pLayout must be a valid pointer to a VkSubresourceLayout2KHR structure

  • VUID-vkGetImageSubresourceLayout2KHR-image-parent
    image must have been created, allocated, or retrieved from device

The VkImageSubresource2KHR structure is defined as:

// Provided by VK_KHR_maintenance5
typedef struct VkImageSubresource2KHR {
    VkStructureType       sType;
    void*                 pNext;
    VkImageSubresource    imageSubresource;
} VkImageSubresource2KHR;
// Provided by VK_EXT_host_image_copy, VK_EXT_image_compression_control
typedef VkImageSubresource2KHR VkImageSubresource2EXT;

  • sType is a VkStructureType value identifying this structure.

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

  • imageSubresource is a VkImageSubresource structure.

Valid Usage (Implicit)

  • VUID-VkImageSubresource2KHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_IMAGE_SUBRESOURCE_2_KHR

  • VUID-VkImageSubresource2KHR-pNext-pNext
    pNext must be NULL

  • VUID-VkImageSubresource2KHR-imageSubresource-parameter
    imageSubresource must be a valid VkImageSubresource structure

Information about the layout of the image subresource is returned in a VkSubresourceLayout2KHR structure:

Information about the layout of the image subresource is returned in a VkSubresourceLayout2EXT structure:

// Provided by VK_EXT_host_image_copy, VK_EXT_image_compression_control
typedef VkSubresourceLayout2KHR VkSubresourceLayout2EXT;

  • sType is a VkStructureType value identifying this structure.

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

  • subresourceLayout is a VkSubresourceLayout structure.

Valid Usage (Implicit)

  • VUID-VkSubresourceLayout2KHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_SUBRESOURCE_LAYOUT_2_KHR

  • VUID-VkSubresourceLayout2KHR-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 VkImageCompressionPropertiesEXT or VkSubresourceHostMemcpySizeEXT

  • VUID-VkSubresourceLayout2KHR-sType-unique
    The sType value of each struct in the pNext chain must be unique

If an image was created with VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, then the image has a Linux DRM format modifier. To query the modifier, call:

// Provided by VK_EXT_image_drm_format_modifier
VkResult vkGetImageDrmFormatModifierPropertiesEXT(
    VkDevice                                    device,
    VkImage                                     image,
    VkImageDrmFormatModifierPropertiesEXT*      pProperties);

  • device is the logical device that owns the image.

  • image is the queried image.

  • pProperties is a pointer to a VkImageDrmFormatModifierPropertiesEXT structure in which properties of the image’s DRM format modifier are returned.

Valid Usage

  • VUID-vkGetImageDrmFormatModifierPropertiesEXT-image-02272
    image must have been created with tiling equal to VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT

Valid Usage (Implicit)

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

  • VUID-vkGetImageDrmFormatModifierPropertiesEXT-image-parameter
    image must be a valid VkImage handle

  • VUID-vkGetImageDrmFormatModifierPropertiesEXT-pProperties-parameter
    pProperties must be a valid pointer to a VkImageDrmFormatModifierPropertiesEXT structure

  • VUID-vkGetImageDrmFormatModifierPropertiesEXT-image-parent
    image must have been created, allocated, or retrieved from device

Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

The VkImageDrmFormatModifierPropertiesEXT structure is defined as:

// Provided by VK_EXT_image_drm_format_modifier
typedef struct VkImageDrmFormatModifierPropertiesEXT {
    VkStructureType    sType;
    void*              pNext;
    uint64_t           drmFormatModifier;
} VkImageDrmFormatModifierPropertiesEXT;

If the image was created with VkImageDrmFormatModifierListCreateInfoEXT, then the returned drmFormatModifier must belong to the list of modifiers provided at time of image creation in VkImageDrmFormatModifierListCreateInfoEXT::pDrmFormatModifiers. If the image was created with VkImageDrmFormatModifierExplicitCreateInfoEXT, then the returned drmFormatModifier must be the modifier provided at time of image creation in VkImageDrmFormatModifierExplicitCreateInfoEXT::drmFormatModifier.

Valid Usage (Implicit)

  • VUID-VkImageDrmFormatModifierPropertiesEXT-sType-sType
    sType must be VK_STRUCTURE_TYPE_IMAGE_DRM_FORMAT_MODIFIER_PROPERTIES_EXT

  • VUID-VkImageDrmFormatModifierPropertiesEXT-pNext-pNext
    pNext must be NULL

To destroy an image, call:

// Provided by VK_VERSION_1_0
void vkDestroyImage(
    VkDevice                                    device,
    VkImage                                     image,
    const VkAllocationCallbacks*                pAllocator);

  • device is the logical device that destroys the image.

  • image is the image to destroy.

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

Valid Usage

  • VUID-vkDestroyImage-image-01000
    All submitted commands that refer to image, either directly or via a VkImageView, must have completed execution

  • VUID-vkDestroyImage-image-01001
    If VkAllocationCallbacks were provided when image was created, a compatible set of callbacks must be provided here

  • VUID-vkDestroyImage-image-01002
    If no VkAllocationCallbacks were provided when image was created, pAllocator must be NULL

  • VUID-vkDestroyImage-image-04882
    image must not have been acquired from vkGetSwapchainImagesKHR

Valid Usage (Implicit)

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

  • VUID-vkDestroyImage-image-parameter
    If image is not VK_NULL_HANDLE, image must be a valid VkImage handle

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

  • VUID-vkDestroyImage-image-parent
    If image is a valid handle, it must have been created, allocated, or retrieved from device

Host Synchronization

  • Host access to image must be externally synchronized

12.3.1. Image Format Features

Valid uses of a VkImage may depend on the image’s format features, defined below. Such constraints are documented in the affected valid usage statement.

12.3.2. Corner-Sampled Images

A corner-sampled image is an image where unnormalized texel coordinates are centered on integer values rather than half-integer values.

A corner-sampled image has a number of differences compared to conventional texture image:

Corner-sampling is only supported for 2D and 3D images. When sampling a corner-sampled image, the sampler addressing mode must be VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE. Corner-sampled images are not supported as cube maps or depth/stencil images.

12.3.3. Image Mip Level Sizing

A complete mipmap chain is the full set of mip levels, from the largest mip level provided, down to the minimum mip level size.

Conventional Images

For conventional images, the dimensions of each successive mip level, n+1, are:

widthn+1 = max(⌊widthn/2⌋, 1)

heightn+1 = max(⌊heightn/2⌋, 1)

depthn+1 = max(⌊depthn/2⌋, 1)

where widthn, heightn, and depthn are the dimensions of the next larger mip level, n.

The minimum mip level size is:

  • 1 for one-dimensional images,

  • 1x1 for two-dimensional images, and

  • 1x1x1 for three-dimensional images.

The number of levels in a complete mipmap chain is:

⌊log2(max(width0, height0, depth0))⌋ + 1

where width0, height0, and depth0 are the dimensions of the largest (most detailed) mip level, 0.

Corner-Sampled Images

For corner-sampled images, the dimensions of each successive mip level, n+1, are:

widthn+1 = max(⌈widthn/2⌉, 2)

heightn+1 = max(⌈heightn/2⌉, 2)

depthn+1 = max(⌈depthn/2⌉, 2)

where widthn, heightn, and depthn are the dimensions of the next larger mip level, n.

The minimum mip level size is:

  • 2x2 for two-dimensional images, and

  • 2x2x2 for three-dimensional images.

The number of levels in a complete mipmap chain is:

⌈log2(max(width0, height0, depth0))⌉

where width0, height0, and depth0 are the dimensions of the largest (most detailed) mip level, 0.

12.4. Image Layouts

Images are stored in implementation-dependent opaque layouts in memory. Each layout has limitations on what kinds of operations are supported for image subresources using the layout. At any given time, the data representing an image subresource in memory exists in a particular layout which is determined by the most recent layout transition that was performed on that image subresource. Applications have control over which layout each image subresource uses, and can transition an image subresource from one layout to another. Transitions can happen with an image memory barrier, included as part of a vkCmdPipelineBarrier or a vkCmdWaitEvents command buffer command (see Image Memory Barriers), or as part of a subpass dependency within a render pass (see VkSubpassDependency).

Image layout is per-image subresource. Separate image subresources of the same image can be in different layouts at the same time, with the exception that depth and stencil aspects of a given image subresource can only be in different layouts if the separateDepthStencilLayouts feature is enabled.

Note

Each layout may offer optimal performance for a specific usage of image memory. For example, an image with a layout of VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL may provide optimal performance for use as a color attachment, but be unsupported for use in transfer commands. Applications can transition an image subresource from one layout to another in order to achieve optimal performance when the image subresource is used for multiple kinds of operations. After initialization, applications need not use any layout other than the general layout, though this may produce suboptimal performance on some implementations.

Upon creation, all image subresources of an image are initially in the same layout, where that layout is selected by the VkImageCreateInfo::initialLayout member. The initialLayout must be either VK_IMAGE_LAYOUT_UNDEFINED or VK_IMAGE_LAYOUT_PREINITIALIZED. If it is VK_IMAGE_LAYOUT_PREINITIALIZED, then the image data can be preinitialized by the host while using this layout, and the transition away from this layout will preserve that data. If it is VK_IMAGE_LAYOUT_UNDEFINED, then the contents of the data are considered to be undefined, and the transition away from this layout is not guaranteed to preserve that data. For either of these initial layouts, any image subresources must be transitioned to another layout before they are accessed by the device.

Host access to image memory is only well-defined for linear images and for image subresources of those images which are currently in either the VK_IMAGE_LAYOUT_PREINITIALIZED or VK_IMAGE_LAYOUT_GENERAL layout. Calling vkGetImageSubresourceLayout for a linear image returns a subresource layout mapping that is valid for either of those image layouts.

The set of image layouts consists of:

// Provided by VK_VERSION_1_0
typedef enum VkImageLayout {
    VK_IMAGE_LAYOUT_UNDEFINED = 0,
    VK_IMAGE_LAYOUT_GENERAL = 1,
    VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL = 2,
    VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL = 3,
    VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL = 4,
    VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL = 5,
    VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL = 6,
    VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL = 7,
    VK_IMAGE_LAYOUT_PREINITIALIZED = 8,
  // Provided by VK_VERSION_1_1
    VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL = 1000117000,
  // Provided by VK_VERSION_1_1
    VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL = 1000117001,
  // Provided by VK_VERSION_1_2
    VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL = 1000241000,
  // Provided by VK_VERSION_1_2
    VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL = 1000241001,
  // Provided by VK_VERSION_1_2
    VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL = 1000241002,
  // Provided by VK_VERSION_1_2
    VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL = 1000241003,
  // Provided by VK_VERSION_1_3
    VK_IMAGE_LAYOUT_READ_ONLY_OPTIMAL = 1000314000,
  // Provided by VK_VERSION_1_3
    VK_IMAGE_LAYOUT_ATTACHMENT_OPTIMAL = 1000314001,
  // Provided by VK_KHR_swapchain
    VK_IMAGE_LAYOUT_PRESENT_SRC_KHR = 1000001002,
  // Provided by VK_KHR_video_decode_queue
    VK_IMAGE_LAYOUT_VIDEO_DECODE_DST_KHR = 1000024000,
  // Provided by VK_KHR_video_decode_queue
    VK_IMAGE_LAYOUT_VIDEO_DECODE_SRC_KHR = 1000024001,
  // Provided by VK_KHR_video_decode_queue
    VK_IMAGE_LAYOUT_VIDEO_DECODE_DPB_KHR = 1000024002,
  // Provided by VK_KHR_shared_presentable_image
    VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR = 1000111000,
  // Provided by VK_EXT_fragment_density_map
    VK_IMAGE_LAYOUT_FRAGMENT_DENSITY_MAP_OPTIMAL_EXT = 1000218000,
  // Provided by VK_KHR_fragment_shading_rate
    VK_IMAGE_LAYOUT_FRAGMENT_SHADING_RATE_ATTACHMENT_OPTIMAL_KHR = 1000164003,
#ifdef VK_ENABLE_BETA_EXTENSIONS
  // Provided by VK_KHR_video_encode_queue
    VK_IMAGE_LAYOUT_VIDEO_ENCODE_DST_KHR = 1000299000,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
  // Provided by VK_KHR_video_encode_queue
    VK_IMAGE_LAYOUT_VIDEO_ENCODE_SRC_KHR = 1000299001,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
  // Provided by VK_KHR_video_encode_queue
    VK_IMAGE_LAYOUT_VIDEO_ENCODE_DPB_KHR = 1000299002,
#endif
  // Provided by VK_EXT_attachment_feedback_loop_layout
    VK_IMAGE_LAYOUT_ATTACHMENT_FEEDBACK_LOOP_OPTIMAL_EXT = 1000339000,
  // Provided by VK_KHR_maintenance2
    VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL_KHR = VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL,
  // Provided by VK_KHR_maintenance2
    VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL_KHR = VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL,
  // Provided by VK_NV_shading_rate_image
    VK_IMAGE_LAYOUT_SHADING_RATE_OPTIMAL_NV = VK_IMAGE_LAYOUT_FRAGMENT_SHADING_RATE_ATTACHMENT_OPTIMAL_KHR,
  // Provided by VK_KHR_separate_depth_stencil_layouts
    VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL_KHR = VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL,
  // Provided by VK_KHR_separate_depth_stencil_layouts
    VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL_KHR = VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL,
  // Provided by VK_KHR_separate_depth_stencil_layouts
    VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL_KHR = VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL,
  // Provided by VK_KHR_separate_depth_stencil_layouts
    VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL_KHR = VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL,
  // Provided by VK_KHR_synchronization2
    VK_IMAGE_LAYOUT_READ_ONLY_OPTIMAL_KHR = VK_IMAGE_LAYOUT_READ_ONLY_OPTIMAL,
  // Provided by VK_KHR_synchronization2
    VK_IMAGE_LAYOUT_ATTACHMENT_OPTIMAL_KHR = VK_IMAGE_LAYOUT_ATTACHMENT_OPTIMAL,
} VkImageLayout;

The type(s) of device access supported by each layout are:

  • VK_IMAGE_LAYOUT_UNDEFINED specifies that the layout is unknown. Image memory cannot be transitioned into this layout. This layout can be used as the initialLayout member of VkImageCreateInfo. This layout can be used in place of the current image layout in a layout transition, but doing so will cause the contents of the image’s memory to be undefined.

  • VK_IMAGE_LAYOUT_PREINITIALIZED specifies that an image’s memory is in a defined layout and can be populated by data, but that it has not yet been initialized by the driver. Image memory cannot be transitioned into this layout. This layout can be used as the initialLayout member of VkImageCreateInfo. This layout is intended to be used as the initial layout for an image whose contents are written by the host, and hence the data can be written to memory immediately, without first executing a layout transition. Currently, VK_IMAGE_LAYOUT_PREINITIALIZED is only useful with linear images because there is not a standard layout defined for VK_IMAGE_TILING_OPTIMAL images.

  • VK_IMAGE_LAYOUT_GENERAL supports all types of device access.

  • VK_IMAGE_LAYOUT_ATTACHMENT_OPTIMAL specifies a layout that must only be used with attachment accesses in the graphics pipeline.

  • VK_IMAGE_LAYOUT_READ_ONLY_OPTIMAL specifies a layout allowing read only access as an attachment, or in shaders as a sampled image, combined image/sampler, or input attachment.

  • VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL must only be used as a color or resolve attachment in a VkFramebuffer. This layout is valid only for image subresources of images created with the VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT usage bit enabled.

  • VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL specifies a layout for both the depth and stencil aspects of a depth/stencil format image allowing read and write access as a depth/stencil attachment. It is equivalent to VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL and VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL.

  • VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL specifies a layout for both the depth and stencil aspects of a depth/stencil format image allowing read only access as a depth/stencil attachment or in shaders as a sampled image, combined image/sampler, or input attachment. It is equivalent to VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL and VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL.

  • VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL specifies a layout for depth/stencil format images allowing read and write access to the stencil aspect as a stencil attachment, and read only access to the depth aspect as a depth attachment or in shaders as a sampled image, combined image/sampler, or input attachment. It is equivalent to VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL and VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL.

  • VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL specifies a layout for depth/stencil format images allowing read and write access to the depth aspect as a depth attachment, and read only access to the stencil aspect as a stencil attachment or in shaders as a sampled image, combined image/sampler, or input attachment. It is equivalent to VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL and VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL.

  • VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL specifies a layout for the depth aspect of a depth/stencil format image allowing read and write access as a depth attachment.

  • VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL specifies a layout for the depth aspect of a depth/stencil format image allowing read-only access as a depth attachment or in shaders as a sampled image, combined image/sampler, or input attachment.

  • VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL specifies a layout for the stencil aspect of a depth/stencil format image allowing read and write access as a stencil attachment.

  • VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL specifies a layout for the stencil aspect of a depth/stencil format image allowing read-only access as a stencil attachment or in shaders as a sampled image, combined image/sampler, or input attachment.

  • VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL specifies a layout allowing read-only access in a shader as a sampled image, combined image/sampler, or input attachment. This layout is valid only for image subresources of images created with the VK_IMAGE_USAGE_SAMPLED_BIT or VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT usage bits enabled.

  • VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL must only be used as a source image of a transfer command (see the definition of VK_PIPELINE_STAGE_TRANSFER_BIT). This layout is valid only for image subresources of images created with the VK_IMAGE_USAGE_TRANSFER_SRC_BIT usage bit enabled.

  • VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL must only be used as a destination image of a transfer command. This layout is valid only for image subresources of images created with the VK_IMAGE_USAGE_TRANSFER_DST_BIT usage bit enabled.

  • VK_IMAGE_LAYOUT_PRESENT_SRC_KHR must only be used for presenting a presentable image for display.

  • VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR is valid only for shared presentable images, and must be used for any usage the image supports.

  • VK_IMAGE_LAYOUT_FRAGMENT_SHADING_RATE_ATTACHMENT_OPTIMAL_KHR must only be used as a fragment shading rate attachment or shading rate image. This layout is valid only for image subresources of images created with the VK_IMAGE_USAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR usage bit enabled.

  • VK_IMAGE_LAYOUT_FRAGMENT_DENSITY_MAP_OPTIMAL_EXT must only be used as a fragment density map attachment in a VkRenderPass. This layout is valid only for image subresources of images created with the VK_IMAGE_USAGE_FRAGMENT_DENSITY_MAP_BIT_EXT usage bit enabled.

  • VK_IMAGE_LAYOUT_VIDEO_DECODE_DST_KHR must only be used as a decode output picture in a video decode operation. This layout is valid only for image subresources of images created with the VK_IMAGE_USAGE_VIDEO_DECODE_DST_BIT_KHR usage bit enabled.

  • VK_IMAGE_LAYOUT_VIDEO_DECODE_SRC_KHR is reserved for future use.

  • VK_IMAGE_LAYOUT_VIDEO_DECODE_DPB_KHR must only be used as an output reconstructed picture or an input reference picture in a video decode operation. This layout is valid only for image subresources of images created with the VK_IMAGE_USAGE_VIDEO_DECODE_DPB_BIT_KHR usage bit enabled.

  • VK_IMAGE_LAYOUT_VIDEO_ENCODE_DST_KHR is reserved for future use.

  • VK_IMAGE_LAYOUT_VIDEO_ENCODE_SRC_KHR must only be used as an encode input picture in a video encode operation. This layout is valid only for image subresources of images created with the VK_IMAGE_USAGE_VIDEO_ENCODE_SRC_BIT_KHR usage bit enabled.

  • VK_IMAGE_LAYOUT_VIDEO_ENCODE_DPB_KHR must only be used as an output reconstructed picture or an input reference picture in a video encode operation. This layout is valid only for image subresources of images created with the VK_IMAGE_USAGE_VIDEO_ENCODE_DPB_BIT_KHR usage bit enabled.

  • VK_IMAGE_LAYOUT_ATTACHMENT_FEEDBACK_LOOP_OPTIMAL_EXT must only be used as either a color attachment or depth/stencil attachment in a VkFramebuffer and/or read-only access in a shader as a sampled image, combined image/sampler, or input attachment. This layout is valid only for image subresources of images created with the VK_IMAGE_USAGE_ATTACHMENT_FEEDBACK_LOOP_BIT_EXT usage bit enabled and 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 enabled.

The layout of each image subresource is not a state of the image subresource itself, but is rather a property of how the data in memory is organized, and thus for each mechanism of accessing an image in the API the application must specify a parameter or structure member that indicates which image layout the image subresource(s) are considered to be in when the image will be accessed. For transfer commands, this is a parameter to the command (see Clear Commands and Copy Commands). For use as a framebuffer attachment, this is a member in the substructures of the VkRenderPassCreateInfo (see Render Pass). For use in a descriptor set, this is a member in the VkDescriptorImageInfo structure (see Descriptor Set Updates).

12.4.1. Image Layout Matching Rules

At the time that any command buffer command accessing an image executes on any queue, the layouts of the image subresources that are accessed must all match exactly the layout specified via the API controlling those accesses, except in case of accesses to an image with a depth/stencil format performed through descriptors referring to only a single aspect of the image, where the following relaxed matching rules apply:

  • Descriptors referring just to the depth aspect of a depth/stencil image only need to match in the image layout of the depth aspect, thus VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL and VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL are considered to match.

  • Descriptors referring just to the stencil aspect of a depth/stencil image only need to match in the image layout of the stencil aspect, thus VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL and VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL are considered to match.

When performing a layout transition on an image subresource, the old layout value must either equal the current layout of the image subresource (at the time the transition executes), or else be VK_IMAGE_LAYOUT_UNDEFINED (implying that the contents of the image subresource need not be preserved). The new layout used in a transition must not be VK_IMAGE_LAYOUT_UNDEFINED or VK_IMAGE_LAYOUT_PREINITIALIZED.

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 applications must provide the same sample locations that were last used to render to the given image subresource whenever a layout transition of the image subresource happens, otherwise the contents of the depth aspect of the image subresource become undefined.

In addition, depth reads from a depth/stencil attachment referring to an image subresource range of a depth/stencil image created with VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT using different sample locations than what have been last used to perform depth writes to the image subresources of the same image subresource range return undefined values.

Similarly, depth writes to a depth/stencil attachment referring to an image subresource range of a depth/stencil image created with VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT using different sample locations than what have been last used to perform depth writes to the image subresources of the same image subresource range make the contents of the depth aspect of those image subresources undefined.

12.5. Image Views

Image objects are not directly accessed by pipeline shaders for reading or writing image data. Instead, image views representing contiguous ranges of the image subresources and containing additional metadata are used for that purpose. Views must be created on images of compatible types, and must represent a valid subset of image subresources.

Image views are represented by VkImageView handles:

// Provided by VK_VERSION_1_0
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkImageView)

VK_REMAINING_ARRAY_LAYERS is a special constant value used for image views to indicate that all remaining array layers in an image after the base layer should be included in the view.

#define VK_REMAINING_ARRAY_LAYERS         (~0U)

VK_REMAINING_MIP_LEVELS is a special constant value used for image views to indicate that all remaining mipmap levels in an image after the base level should be included in the view.

#define VK_REMAINING_MIP_LEVELS           (~0U)

The types of image views that can be created are:

// Provided by VK_VERSION_1_0
typedef enum VkImageViewType {
    VK_IMAGE_VIEW_TYPE_1D = 0,
    VK_IMAGE_VIEW_TYPE_2D = 1,
    VK_IMAGE_VIEW_TYPE_3D = 2,
    VK_IMAGE_VIEW_TYPE_CUBE = 3,
    VK_IMAGE_VIEW_TYPE_1D_ARRAY = 4,
    VK_IMAGE_VIEW_TYPE_2D_ARRAY = 5,
    VK_IMAGE_VIEW_TYPE_CUBE_ARRAY = 6,
} VkImageViewType;

To create an image view, call:

// Provided by VK_VERSION_1_0
VkResult vkCreateImageView(
    VkDevice                                    device,
    const VkImageViewCreateInfo*                pCreateInfo,
    const VkAllocationCallbacks*                pAllocator,
    VkImageView*                                pView);

  • device is the logical device that creates the image view.

  • pCreateInfo is a pointer to a VkImageViewCreateInfo structure containing parameters to be used to create the image view.

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

  • pView is a pointer to a VkImageView handle in which the resulting image view object is returned.

Valid Usage
Valid Usage (Implicit)

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

  • VUID-vkCreateImageView-pCreateInfo-parameter
    pCreateInfo must be a valid pointer to a valid VkImageViewCreateInfo structure

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

  • VUID-vkCreateImageView-pView-parameter
    pView must be a valid pointer to a VkImageView handle

Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

  • VK_ERROR_INVALID_OPAQUE_CAPTURE_ADDRESS_KHR

The VkImageViewCreateInfo structure is defined as:

// Provided by VK_VERSION_1_0
typedef struct VkImageViewCreateInfo {
    VkStructureType            sType;
    const void*                pNext;
    VkImageViewCreateFlags     flags;
    VkImage                    image;
    VkImageViewType            viewType;
    VkFormat                   format;
    VkComponentMapping         components;
    VkImageSubresourceRange    subresourceRange;
} VkImageViewCreateInfo;

  • 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 VkImageViewCreateFlagBits specifying additional parameters of the image view.

  • image is a VkImage on which the view will be created.

  • viewType is a VkImageViewType value specifying the type of the image view.

  • format is a VkFormat specifying the format and type used to interpret texel blocks of the image.

  • components is a VkComponentMapping structure specifying a remapping of color components (or of depth or stencil components after they have been converted into color components).

  • subresourceRange is a VkImageSubresourceRange structure selecting the set of mipmap levels and array layers to be accessible to the view.

Some of the image creation parameters are inherited by the view. In particular, image view creation inherits the implicit parameter usage specifying the allowed usages of the image view that, by default, takes the value of the corresponding usage parameter specified in VkImageCreateInfo at image creation time. The implicit usage can be overridden by adding a VkImageViewUsageCreateInfo structure to the pNext chain, but the view usage must be a subset of the image usage. If image has a depth-stencil format and was created with a VkImageStencilUsageCreateInfo structure included in the pNext chain of VkImageCreateInfo, the usage is calculated based on the subresource.aspectMask provided:

If image is a 3D image, its Z range can be restricted to a subset by adding a VkImageViewSlicedCreateInfoEXT to the pNext chain.

If image was created with the VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT flag, and if the format of the image is not multi-planar, format can be different from the image’s format, but if image was created without the VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT flag and they are not equal they must be compatible. Image format compatibility is defined in the Format Compatibility Classes section. Views of compatible formats will have the same mapping between texel coordinates and memory locations irrespective of the format, with only the interpretation of the bit pattern changing.

If image was created with a multi-planar format, and the image view’s aspectMask is one of VK_IMAGE_ASPECT_PLANE_0_BIT, VK_IMAGE_ASPECT_PLANE_1_BIT or VK_IMAGE_ASPECT_PLANE_2_BIT, the view’s aspect mask is considered to be equivalent to VK_IMAGE_ASPECT_COLOR_BIT when used as a framebuffer attachment.

Note

Values intended to be used with one view format may not be exactly preserved when written or read through a different format. For example, an integer value that happens to have the bit pattern of a floating point denorm or NaN may be flushed or canonicalized when written or read through a view with a floating point format. Similarly, a value written through a signed normalized format that has a bit pattern exactly equal to -2b may be changed to -2b + 1 as described in Conversion from Normalized Fixed-Point to Floating-Point.

If image was created with the VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT flag, format must be compatible with the image’s format as described above; or must be an uncompressed format, in which case it must be size-compatible with the image’s format. In this case, the resulting image view’s texel dimensions equal the dimensions of the selected mip level divided by the compressed texel block size and rounded up.

The VkComponentMapping components member describes a remapping from components of the image to components of the vector returned by shader image instructions. This remapping must be the identity swizzle for storage image descriptors, input attachment descriptors, framebuffer attachments, and any VkImageView used with a combined image sampler that enables sampler Y′CBCR conversion.

If the image view is to be used with a sampler which supports sampler Y′CBCR conversion, an identically defined object of type VkSamplerYcbcrConversion to that used to create the sampler must be passed to vkCreateImageView in a VkSamplerYcbcrConversionInfo included in the pNext chain of VkImageViewCreateInfo. Conversely, if a VkSamplerYcbcrConversion object is passed to vkCreateImageView, an identically defined VkSamplerYcbcrConversion object must be used when sampling the image.

If the image has a multi-planar format, subresourceRange.aspectMask is VK_IMAGE_ASPECT_COLOR_BIT, and usage includes VK_IMAGE_USAGE_SAMPLED_BIT, then the format must be identical to the image format and the sampler to be used with the image view must enable sampler Y′CBCR conversion.

When such an image is used in a video coding operation, the sampler Y′CBCR conversion has no effect.

If image was created with the VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT and the image has a multi-planar format, and if subresourceRange.aspectMask is VK_IMAGE_ASPECT_PLANE_0_BIT, VK_IMAGE_ASPECT_PLANE_1_BIT, or VK_IMAGE_ASPECT_PLANE_2_BIT, format must be compatible with the corresponding plane of the image, and the sampler to be used with the image view must not enable sampler Y′CBCR conversion. The width and height of the single-plane image view must be derived from the multi-planar image’s dimensions in the manner listed for plane compatibility for the plane.

Any view of an image plane will have the same mapping between texel coordinates and memory locations as used by the components of the color aspect, subject to the formulae relating texel coordinates to lower-resolution planes as described in Chroma Reconstruction. That is, if an R or B plane has a reduced resolution relative to the G plane of the multi-planar image, the image view operates using the (uplane, vplane) unnormalized coordinates of the reduced-resolution plane, and these coordinates access the same memory locations as the (ucolor, vcolor) unnormalized coordinates of the color aspect for which chroma reconstruction operations operate on the same (uplane, vplane) or (iplane, jplane) coordinates.

Table 15. Image type and image view type compatibility requirements
Image View Type Compatible Image Types

VK_IMAGE_VIEW_TYPE_1D

VK_IMAGE_TYPE_1D

VK_IMAGE_VIEW_TYPE_1D_ARRAY

VK_IMAGE_TYPE_1D

VK_IMAGE_VIEW_TYPE_2D

VK_IMAGE_TYPE_2D , VK_IMAGE_TYPE_3D

VK_IMAGE_VIEW_TYPE_2D_ARRAY

VK_IMAGE_TYPE_2D , VK_IMAGE_TYPE_3D

VK_IMAGE_VIEW_TYPE_CUBE

VK_IMAGE_TYPE_2D

VK_IMAGE_VIEW_TYPE_CUBE_ARRAY

VK_IMAGE_TYPE_2D

VK_IMAGE_VIEW_TYPE_3D

VK_IMAGE_TYPE_3D
Valid Usage

  • VUID-VkImageViewCreateInfo-image-01003
    If image was not created with VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT then viewType must not be VK_IMAGE_VIEW_TYPE_CUBE or VK_IMAGE_VIEW_TYPE_CUBE_ARRAY

  • VUID-VkImageViewCreateInfo-viewType-01004
    If the imageCubeArray feature is not enabled, viewType must not be VK_IMAGE_VIEW_TYPE_CUBE_ARRAY

  • VUID-VkImageViewCreateInfo-image-06723
    If image was created with VK_IMAGE_TYPE_3D but without VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT set then viewType must not be VK_IMAGE_VIEW_TYPE_2D_ARRAY

  • VUID-VkImageViewCreateInfo-image-06728
    If image was created with VK_IMAGE_TYPE_3D but without VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT or VK_IMAGE_CREATE_2D_VIEW_COMPATIBLE_BIT_EXT set, then viewType must not be VK_IMAGE_VIEW_TYPE_2D

  • VUID-VkImageViewCreateInfo-image-04970
    If image was created with VK_IMAGE_TYPE_3D and viewType is VK_IMAGE_VIEW_TYPE_2D or VK_IMAGE_VIEW_TYPE_2D_ARRAY then subresourceRange.levelCount must be 1

  • VUID-VkImageViewCreateInfo-image-04971
    If image was created with VK_IMAGE_TYPE_3D and viewType is VK_IMAGE_VIEW_TYPE_2D or VK_IMAGE_VIEW_TYPE_2D_ARRAY then VkImageCreateInfo::flags must not contain any of VK_IMAGE_CREATE_SPARSE_BINDING_BIT, VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT, and VK_IMAGE_CREATE_SPARSE_ALIASED_BIT

  • VUID-VkImageViewCreateInfo-image-04972
    If image was created with a samples value not equal to VK_SAMPLE_COUNT_1_BIT then viewType must be either VK_IMAGE_VIEW_TYPE_2D or VK_IMAGE_VIEW_TYPE_2D_ARRAY

  • VUID-VkImageViewCreateInfo-image-04441
    image must have been created with a usage value containing at least one of the usages defined in the valid image usage list for image views

  • VUID-VkImageViewCreateInfo-None-02273
    The format features of the resultant image view must contain at least one bit

  • VUID-VkImageViewCreateInfo-usage-02274
    If usage contains VK_IMAGE_USAGE_SAMPLED_BIT, then the format features of the resultant image view must contain VK_FORMAT_FEATURE_SAMPLED_IMAGE_BIT

  • VUID-VkImageViewCreateInfo-usage-02275
    If usage contains VK_IMAGE_USAGE_STORAGE_BIT, then the image view’s format features must contain VK_FORMAT_FEATURE_STORAGE_IMAGE_BIT

  • VUID-VkImageViewCreateInfo-usage-08931
    If usage contains VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT, then the image view’s format features must contain VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT or VK_FORMAT_FEATURE_2_LINEAR_COLOR_ATTACHMENT_BIT_NV

  • VUID-VkImageViewCreateInfo-usage-02277
    If usage contains VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT, then the image view’s format features must contain VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT

  • VUID-VkImageViewCreateInfo-usage-08932
    If usage contains VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT, then the image view’s format features must contain at least one of VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT, VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT or, VK_FORMAT_FEATURE_2_LINEAR_COLOR_ATTACHMENT_BIT_NV

  • VUID-VkImageViewCreateInfo-subresourceRange-01478
    subresourceRange.baseMipLevel must be less than the mipLevels specified in VkImageCreateInfo when image was created

  • VUID-VkImageViewCreateInfo-subresourceRange-01718
    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-VkImageViewCreateInfo-image-02571
    If image was created with usage containing VK_IMAGE_USAGE_FRAGMENT_DENSITY_MAP_BIT_EXT, subresourceRange.levelCount must be 1

  • VUID-VkImageViewCreateInfo-image-06724
    If image is not a 3D image created with VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT or VK_IMAGE_CREATE_2D_VIEW_COMPATIBLE_BIT_EXT set, or viewType is not VK_IMAGE_VIEW_TYPE_2D or VK_IMAGE_VIEW_TYPE_2D_ARRAY, subresourceRange.baseArrayLayer must be less than the arrayLayers specified in VkImageCreateInfo when image was created

  • VUID-VkImageViewCreateInfo-subresourceRange-06725
    If subresourceRange.layerCount is not VK_REMAINING_ARRAY_LAYERS, image is not a 3D image created with VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT or VK_IMAGE_CREATE_2D_VIEW_COMPATIBLE_BIT_EXT set, or viewType is not VK_IMAGE_VIEW_TYPE_2D or VK_IMAGE_VIEW_TYPE_2D_ARRAY, subresourceRange.layerCount must be non-zero and subresourceRange.baseArrayLayer + subresourceRange.layerCount must be less than or equal to the arrayLayers specified in VkImageCreateInfo when image was created

  • VUID-VkImageViewCreateInfo-image-02724
    If image is a 3D image created with VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT set, and viewType is VK_IMAGE_VIEW_TYPE_2D or VK_IMAGE_VIEW_TYPE_2D_ARRAY, subresourceRange.baseArrayLayer must be less than the depth computed from baseMipLevel and extent.depth specified in VkImageCreateInfo when image was created, according to the formula defined in Image Mip Level Sizing

  • VUID-VkImageViewCreateInfo-subresourceRange-02725
    If subresourceRange.layerCount is not VK_REMAINING_ARRAY_LAYERS, image is a 3D image created with VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT set, and viewType is VK_IMAGE_VIEW_TYPE_2D or VK_IMAGE_VIEW_TYPE_2D_ARRAY, subresourceRange.layerCount must be non-zero and subresourceRange.baseArrayLayer + subresourceRange.layerCount must be less than or equal to the depth computed from baseMipLevel and extent.depth specified in VkImageCreateInfo when image was created, according to the formula defined in Image Mip Level Sizing

  • VUID-VkImageViewCreateInfo-image-01761
    If image was created with the VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT flag, but without the VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT flag, and if the format of the image is not a multi-planar format, format must be compatible with the format used to create image, as defined in Format Compatibility Classes

  • VUID-VkImageViewCreateInfo-image-01583
    If image was created with the VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT flag, format must be compatible with, or must be an uncompressed format that is size-compatible with, the format used to create image

  • VUID-VkImageViewCreateInfo-image-07072
    If image was created with the VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT flag and format is a non-compressed format, the levelCount and layerCount members of subresourceRange must both be 1

  • VUID-VkImageViewCreateInfo-pNext-01585
    If a VkImageFormatListCreateInfo structure was included in the pNext chain of the VkImageCreateInfo structure used when creating image and VkImageFormatListCreateInfo::viewFormatCount is not zero then format must be one of the formats in VkImageFormatListCreateInfo::pViewFormats

  • VUID-VkImageViewCreateInfo-image-01586
    If image was created with the VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT flag, if the format of the image is a multi-planar format, and if subresourceRange.aspectMask is one of the multi-planar aspect mask bits, then format must be compatible with the VkFormat for the plane of the image format indicated by subresourceRange.aspectMask, as defined in Compatible formats of planes of multi-planar formats

  • VUID-VkImageViewCreateInfo-subresourceRange-07818
    subresourceRange.aspectMask must only have at most 1 valid multi-planar aspect mask bit

  • VUID-VkImageViewCreateInfo-image-01762
    If image was not created with the VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT flag, or if the format of the image is a multi-planar format and if subresourceRange.aspectMask is VK_IMAGE_ASPECT_COLOR_BIT, format must be identical to the format used to create image

  • VUID-VkImageViewCreateInfo-format-06415
    If the image view requires a sampler Y′CBCR conversion and usage contains VK_IMAGE_USAGE_SAMPLED_BIT, then the pNext chain must include a VkSamplerYcbcrConversionInfo structure with a conversion value other than VK_NULL_HANDLE

  • VUID-VkImageViewCreateInfo-format-04714
    If format has a _422 or _420 suffix then image must have been created with a width that is a multiple of 2

  • VUID-VkImageViewCreateInfo-format-04715
    If format has a _420 suffix then image must have been created with a height that is a multiple of 2

  • VUID-VkImageViewCreateInfo-pNext-01970
    If the pNext chain includes a VkSamplerYcbcrConversionInfo structure with a conversion value other than VK_NULL_HANDLE, all members of components must have the identity swizzle

  • VUID-VkImageViewCreateInfo-pNext-06658
    If the pNext chain includes a VkSamplerYcbcrConversionInfo structure with a conversion value other than VK_NULL_HANDLE, format must be the same used in VkSamplerYcbcrConversionCreateInfo::format

  • VUID-VkImageViewCreateInfo-image-01020
    If image is non-sparse then it must be bound completely and contiguously to a single VkDeviceMemory object

  • VUID-VkImageViewCreateInfo-subResourceRange-01021
    viewType must be compatible with the type of image as shown in the view type compatibility table

  • VUID-VkImageViewCreateInfo-image-02399
    If image has an Android external format, format must be VK_FORMAT_UNDEFINED

  • VUID-VkImageViewCreateInfo-image-02400
    If image has an Android external format, the pNext chain must include a VkSamplerYcbcrConversionInfo structure with a conversion object created with the same external format as image

  • VUID-VkImageViewCreateInfo-image-02401
    If image has an Android external format, all members of components must be the identity swizzle

  • VUID-VkImageViewCreateInfo-image-02086
    If image was created with usage containing VK_IMAGE_USAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR, viewType must be VK_IMAGE_VIEW_TYPE_2D or VK_IMAGE_VIEW_TYPE_2D_ARRAY

  • VUID-VkImageViewCreateInfo-image-02087
    If the shadingRateImage feature is enabled, and If image was created with usage containing VK_IMAGE_USAGE_SHADING_RATE_IMAGE_BIT_NV, format must be VK_FORMAT_R8_UINT

  • VUID-VkImageViewCreateInfo-usage-04550
    If the attachmentFragmentShadingRate feature is enabled, and the usage for the image view includes VK_IMAGE_USAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR, then the image view’s format features must contain VK_FORMAT_FEATURE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR

  • VUID-VkImageViewCreateInfo-usage-04551
    If the attachmentFragmentShadingRate feature is enabled, the usage for the image view includes VK_IMAGE_USAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR, and layeredShadingRateAttachments is VK_FALSE, subresourceRange.layerCount must be 1

  • VUID-VkImageViewCreateInfo-flags-02572
    If the fragmentDensityMapDynamic feature is not enabled, flags must not contain VK_IMAGE_VIEW_CREATE_FRAGMENT_DENSITY_MAP_DYNAMIC_BIT_EXT

  • VUID-VkImageViewCreateInfo-flags-03567
    If the fragmentDensityMapDeferred feature is not enabled, flags must not contain VK_IMAGE_VIEW_CREATE_FRAGMENT_DENSITY_MAP_DEFERRED_BIT_EXT

  • VUID-VkImageViewCreateInfo-flags-03568
    If flags contains VK_IMAGE_VIEW_CREATE_FRAGMENT_DENSITY_MAP_DEFERRED_BIT_EXT, flags must not contain VK_IMAGE_VIEW_CREATE_FRAGMENT_DENSITY_MAP_DYNAMIC_BIT_EXT

  • VUID-VkImageViewCreateInfo-image-03569
    If image was created with flags containing VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT and usage containing VK_IMAGE_USAGE_SAMPLED_BIT, subresourceRange.layerCount must be less than or equal to VkPhysicalDeviceFragmentDensityMap2PropertiesEXT::maxSubsampledArrayLayers

  • VUID-VkImageViewCreateInfo-invocationMask-04993
    If the invocationMask feature is enabled, and if image was created with usage containing VK_IMAGE_USAGE_INVOCATION_MASK_BIT_HUAWEI, format must be VK_FORMAT_R8_UINT

  • VUID-VkImageViewCreateInfo-flags-04116
    If flags does not contain VK_IMAGE_VIEW_CREATE_FRAGMENT_DENSITY_MAP_DYNAMIC_BIT_EXT and image was created with usage containing VK_IMAGE_USAGE_FRAGMENT_DENSITY_MAP_BIT_EXT, its flags must not contain any of VK_IMAGE_CREATE_PROTECTED_BIT, VK_IMAGE_CREATE_SPARSE_BINDING_BIT, VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT, or VK_IMAGE_CREATE_SPARSE_ALIASED_BIT

  • VUID-VkImageViewCreateInfo-pNext-02662
    If the pNext chain includes a VkImageViewUsageCreateInfo structure, and image was not created with a VkImageStencilUsageCreateInfo structure included in the pNext chain of VkImageCreateInfo, its usage member must not include any bits that were not set in the usage member of the VkImageCreateInfo structure used to create image

  • VUID-VkImageViewCreateInfo-pNext-02663
    If the pNext chain includes a VkImageViewUsageCreateInfo structure, image was created with a VkImageStencilUsageCreateInfo structure included in the pNext chain of VkImageCreateInfo, and subresourceRange.aspectMask includes VK_IMAGE_ASPECT_STENCIL_BIT, the usage member of the VkImageViewUsageCreateInfo structure must not include any bits that were not set in the usage member of the VkImageStencilUsageCreateInfo structure used to create image

  • VUID-VkImageViewCreateInfo-pNext-02664
    If the pNext chain includes a VkImageViewUsageCreateInfo structure, image was created with a VkImageStencilUsageCreateInfo structure included in the pNext chain of VkImageCreateInfo, and subresourceRange.aspectMask includes bits other than VK_IMAGE_ASPECT_STENCIL_BIT, the usage member of the VkImageViewUsageCreateInfo structure must not include any bits that were not set in the usage member of the VkImageCreateInfo structure used to create image

  • VUID-VkImageViewCreateInfo-imageViewType-04973
    If viewType is VK_IMAGE_VIEW_TYPE_1D, VK_IMAGE_VIEW_TYPE_2D, or VK_IMAGE_VIEW_TYPE_3D; and subresourceRange.layerCount is not VK_REMAINING_ARRAY_LAYERS, then subresourceRange.layerCount must be 1

  • VUID-VkImageViewCreateInfo-imageViewType-04974
    If viewType is VK_IMAGE_VIEW_TYPE_1D, VK_IMAGE_VIEW_TYPE_2D, or VK_IMAGE_VIEW_TYPE_3D; and subresourceRange.layerCount is VK_REMAINING_ARRAY_LAYERS, then the remaining number of layers must be 1

  • VUID-VkImageViewCreateInfo-viewType-02960
    If viewType is VK_IMAGE_VIEW_TYPE_CUBE and subresourceRange.layerCount is not VK_REMAINING_ARRAY_LAYERS, subresourceRange.layerCount must be 6

  • VUID-VkImageViewCreateInfo-viewType-02961
    If viewType is VK_IMAGE_VIEW_TYPE_CUBE_ARRAY and subresourceRange.layerCount is not VK_REMAINING_ARRAY_LAYERS, subresourceRange.layerCount must be a multiple of 6

  • VUID-VkImageViewCreateInfo-viewType-02962
    If viewType is VK_IMAGE_VIEW_TYPE_CUBE and subresourceRange.layerCount is VK_REMAINING_ARRAY_LAYERS, the remaining number of layers must be 6

  • VUID-VkImageViewCreateInfo-viewType-02963
    If viewType is VK_IMAGE_VIEW_TYPE_CUBE_ARRAY and subresourceRange.layerCount is VK_REMAINING_ARRAY_LAYERS, the remaining number of layers must be a multiple of 6

  • VUID-VkImageViewCreateInfo-imageViewFormatSwizzle-04465
    If the VK_KHR_portability_subset extension is enabled, and VkPhysicalDevicePortabilitySubsetFeaturesKHR::imageViewFormatSwizzle is VK_FALSE, all elements of components must have the identity swizzle

  • VUID-VkImageViewCreateInfo-imageViewFormatReinterpretation-04466
    If the VK_KHR_portability_subset extension is enabled, and VkPhysicalDevicePortabilitySubsetFeaturesKHR::imageViewFormatReinterpretation is VK_FALSE, the VkFormat in format must not contain a different number of components, or a different number of bits in each component, than the format of the VkImage in image

  • VUID-VkImageViewCreateInfo-image-04817
    If image was created with usage containing VK_IMAGE_USAGE_VIDEO_DECODE_DST_BIT_KHR, VK_IMAGE_USAGE_VIDEO_DECODE_SRC_BIT_KHR, or VK_IMAGE_USAGE_VIDEO_DECODE_DPB_BIT_KHR, then the viewType must be VK_IMAGE_VIEW_TYPE_2D or VK_IMAGE_VIEW_TYPE_2D_ARRAY

  • VUID-VkImageViewCreateInfo-image-04818
    If image was created with usage containing VK_IMAGE_USAGE_VIDEO_ENCODE_DST_BIT_KHR, VK_IMAGE_USAGE_VIDEO_ENCODE_SRC_BIT_KHR, or VK_IMAGE_USAGE_VIDEO_ENCODE_DPB_BIT_KHR, then the viewType must be VK_IMAGE_VIEW_TYPE_2D or VK_IMAGE_VIEW_TYPE_2D_ARRAY

  • VUID-VkImageViewCreateInfo-flags-08106
    If flags includes VK_IMAGE_VIEW_CREATE_DESCRIPTOR_BUFFER_CAPTURE_REPLAY_BIT_EXT, the descriptorBufferCaptureReplay feature must be enabled

  • VUID-VkImageViewCreateInfo-pNext-08107
    If the pNext chain includes a VkOpaqueCaptureDescriptorDataCreateInfoEXT structure, flags must contain VK_IMAGE_VIEW_CREATE_DESCRIPTOR_BUFFER_CAPTURE_REPLAY_BIT_EXT

  • VUID-VkImageViewCreateInfo-pNext-06787
    If the pNext chain includes a VkExportMetalObjectCreateInfoEXT structure, its exportObjectType member must be VK_EXPORT_METAL_OBJECT_TYPE_METAL_TEXTURE_BIT_EXT

  • VUID-VkImageViewCreateInfo-pNext-06944
    If the pNext chain includes VkImageViewSampleWeightCreateInfoQCOM structure, then textureSampleWeighted feature must be enabled

  • VUID-VkImageViewCreateInfo-pNext-06945
    If the pNext chain includes VkImageViewSampleWeightCreateInfoQCOM structure, then image must have been created with usage containing VK_IMAGE_USAGE_SAMPLE_WEIGHT_BIT_QCOM

  • VUID-VkImageViewCreateInfo-pNext-06946
    If the pNext chain includes VkImageViewSampleWeightCreateInfoQCOM structure, then components must be VK_COMPONENT_SWIZZLE_IDENTITY for all components

  • VUID-VkImageViewCreateInfo-pNext-06947
    If the pNext chain includes VkImageViewSampleWeightCreateInfoQCOM structure, then subresourceRange.aspectMask must be VK_IMAGE_ASPECT_COLOR_BIT

  • VUID-VkImageViewCreateInfo-pNext-06948
    If the pNext chain includes VkImageViewSampleWeightCreateInfoQCOM structure, then subresourceRange.levelCount must be 1

  • VUID-VkImageViewCreateInfo-pNext-06949
    If the pNext chain includes VkImageViewSampleWeightCreateInfoQCOM structure, then viewType must be VK_IMAGE_VIEW_TYPE_1D_ARRAY or VK_IMAGE_VIEW_TYPE_2D_ARRAY

  • VUID-VkImageViewCreateInfo-pNext-06950
    If the pNext chain includes VkImageViewSampleWeightCreateInfoQCOM structure and if viewType is VK_IMAGE_VIEW_TYPE_1D_ARRAY, then image must have been created with imageType VK_IMAGE_TYPE_1D

  • VUID-VkImageViewCreateInfo-pNext-06951
    If the pNext chain includes VkImageViewSampleWeightCreateInfoQCOM structure and viewType is VK_IMAGE_VIEW_TYPE_1D_ARRAY, then subresourceRange.layerCount must be equal to 2

  • VUID-VkImageViewCreateInfo-pNext-06952
    If the pNext chain includes VkImageViewSampleWeightCreateInfoQCOM structure and viewType is VK_IMAGE_VIEW_TYPE_1D_ARRAY, then image must have been created with width equal to or greater than

  • VUID-VkImageViewCreateInfo-pNext-06953
    If the pNext chain includes VkImageViewSampleWeightCreateInfoQCOM structure and if viewType is VK_IMAGE_VIEW_TYPE_2D_ARRAY, then image must have been created with imageType VK_IMAGE_TYPE_2D

  • VUID-VkImageViewCreateInfo-pNext-06954
    If the pNext chain includes VkImageViewSampleWeightCreateInfoQCOM structure and viewType is VK_IMAGE_VIEW_TYPE_2D_ARRAY, then subresourceRange.layerCount must be equal or greater than numPhases

  • VUID-VkImageViewCreateInfo-pNext-06955
    If the pNext chain includes VkImageViewSampleWeightCreateInfoQCOM structure and viewType is VK_IMAGE_VIEW_TYPE_2D_ARRAY, then image must have been created with width equal to or greater than filterSize.width

  • VUID-VkImageViewCreateInfo-pNext-06956
    If the pNext chain includes VkImageViewSampleWeightCreateInfoQCOM structure and viewType is VK_IMAGE_VIEW_TYPE_2D_ARRAY, then image must have been created with height equal to or greater than filterSize.height

  • VUID-VkImageViewCreateInfo-pNext-06957
    If the pNext chain includes VkImageViewSampleWeightCreateInfoQCOM structure then VkImageViewSampleWeightCreateInfoQCOM::filterSize.height must be less than or equal to VkPhysicalDeviceImageProcessingPropertiesQCOM::maxWeightFilterDimension.height

Valid Usage (Implicit)

Bits which can be set in VkImageViewCreateInfo::flags, specifying additional parameters of an image view, are:

// Provided by VK_VERSION_1_0
typedef enum VkImageViewCreateFlagBits {
  // Provided by VK_EXT_fragment_density_map
    VK_IMAGE_VIEW_CREATE_FRAGMENT_DENSITY_MAP_DYNAMIC_BIT_EXT = 0x00000001,
  // Provided by VK_EXT_descriptor_buffer
    VK_IMAGE_VIEW_CREATE_DESCRIPTOR_BUFFER_CAPTURE_REPLAY_BIT_EXT = 0x00000004,
  // Provided by VK_EXT_fragment_density_map2
    VK_IMAGE_VIEW_CREATE_FRAGMENT_DENSITY_MAP_DEFERRED_BIT_EXT = 0x00000002,
} VkImageViewCreateFlagBits;

  • VK_IMAGE_VIEW_CREATE_FRAGMENT_DENSITY_MAP_DYNAMIC_BIT_EXT specifies that the fragment density map will be read by 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 for the primary command buffer that the render pass is recorded into

  • VK_IMAGE_VIEW_CREATE_DESCRIPTOR_BUFFER_CAPTURE_REPLAY_BIT_EXT specifies that the image view can be used with descriptor buffers when capturing and replaying (e.g. for trace capture and replay), see VkOpaqueCaptureDescriptorDataCreateInfoEXT for more detail.

// Provided by VK_VERSION_1_0
typedef VkFlags VkImageViewCreateFlags;

VkImageViewCreateFlags is a bitmask type for setting a mask of zero or more VkImageViewCreateFlagBits.

The set of usages for the created image view can be restricted compared to the parent image’s usage flags by adding a VkImageViewUsageCreateInfo structure to the pNext chain of VkImageViewCreateInfo.

The VkImageViewUsageCreateInfo structure is defined as:

// Provided by VK_VERSION_1_1
typedef struct VkImageViewUsageCreateInfo {
    VkStructureType      sType;
    const void*          pNext;
    VkImageUsageFlags    usage;
} VkImageViewUsageCreateInfo;

or the equivalent

// Provided by VK_KHR_maintenance2
typedef VkImageViewUsageCreateInfo VkImageViewUsageCreateInfoKHR;

  • sType is a VkStructureType value identifying this structure.

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

  • usage is a bitmask of VkImageUsageFlagBits specifying allowed usages of the image view.

When this structure is chained to VkImageViewCreateInfo the usage field overrides the implicit usage parameter inherited from image creation time and its value is used instead for the purposes of determining the valid usage conditions of VkImageViewCreateInfo.

Valid Usage (Implicit)

  • VUID-VkImageViewUsageCreateInfo-sType-sType
    sType must be VK_STRUCTURE_TYPE_IMAGE_VIEW_USAGE_CREATE_INFO

  • VUID-VkImageViewUsageCreateInfo-usage-parameter
    usage must be a valid combination of VkImageUsageFlagBits values

  • VUID-VkImageViewUsageCreateInfo-usage-requiredbitmask
    usage must not be 0

The range of 3D slices for the created image view can be restricted to a subset of the parent image’s Z range by adding a VkImageViewSlicedCreateInfoEXT structure to the pNext chain of VkImageViewCreateInfo.

The VkImageViewSlicedCreateInfoEXT structure is defined as:

// Provided by VK_EXT_image_sliced_view_of_3d
typedef struct VkImageViewSlicedCreateInfoEXT {
    VkStructureType    sType;
    const void*        pNext;
    uint32_t           sliceOffset;
    uint32_t           sliceCount;
} VkImageViewSlicedCreateInfoEXT;

  • sType is a VkStructureType value identifying this structure.

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

  • sliceOffset is the Z-offset for the first 3D slice accessible to the image view.

  • sliceCount is the number of 3D slices accessible to the image view.

When this structure is chained to VkImageViewCreateInfo the sliceOffset field is treated as a Z-offset for the sliced view and sliceCount specifies the range. Shader accesses using a Z coordinate of 0 will access the depth slice corresponding to sliceOffset in the image, and in a shader, the maximum in-bounds Z coordinate for the view is sliceCount - 1.

A sliced 3D view must only be used with a single mip level. The slice coordinates are integer coordinates within the subresourceRange.baseMipLevel used to create the image view.

The effective view depth is equal to extent.depth used to create the image for this view adjusted by subresourceRange.baseMipLevel as specified in Image Mip Level Sizing.

Shader access to this image view is only affected by VkImageViewSlicedCreateInfoEXT if it uses a descriptor of type VK_DESCRIPTOR_TYPE_STORAGE_IMAGE. For access using any other descriptor type, the contents of VkImageViewSlicedCreateInfoEXT are ignored; instead, sliceOffset is treated as being equal to 0, and sliceCount is treated as being equal to VK_REMAINING_3D_SLICES_EXT.

Valid Usage

  • VUID-VkImageViewSlicedCreateInfoEXT-sliceOffset-07867
    sliceOffset must be less than the effective view depth as specified in Image Mip Level Sizing

  • VUID-VkImageViewSlicedCreateInfoEXT-sliceCount-07868
    If sliceCount is not VK_REMAINING_3D_SLICES_EXT, it must be be non-zero and sliceOffset + sliceCount must be less than or equal to the effective view depth as specified in Image Mip Level Sizing

  • VUID-VkImageViewSlicedCreateInfoEXT-image-07869
    image must have been created with imageType equal to VK_IMAGE_TYPE_3D

  • VUID-VkImageViewSlicedCreateInfoEXT-viewType-07909
    viewType must be VK_IMAGE_VIEW_TYPE_3D

  • VUID-VkImageViewSlicedCreateInfoEXT-None-07870
    The image view must reference exactly 1 mip level

  • VUID-VkImageViewSlicedCreateInfoEXT-None-07871
    The imageSlicedViewOf3D feature must be enabled on the device

Valid Usage (Implicit)

  • VUID-VkImageViewSlicedCreateInfoEXT-sType-sType
    sType must be VK_STRUCTURE_TYPE_IMAGE_VIEW_SLICED_CREATE_INFO_EXT

VK_REMAINING_3D_SLICES_EXT is a special constant value used for VkImageViewSlicedCreateInfoEXT::sliceCount to indicate that all remaining 3D slices in an image after the first slice offset specified should be included in the view.

#define VK_REMAINING_3D_SLICES_EXT        (~0U)

The VkImageSubresourceRange structure is defined as:

// Provided by VK_VERSION_1_0
typedef struct VkImageSubresourceRange {
    VkImageAspectFlags    aspectMask;
    uint32_t              baseMipLevel;
    uint32_t              levelCount;
    uint32_t              baseArrayLayer;
    uint32_t              layerCount;
} VkImageSubresourceRange;

  • aspectMask is a bitmask of VkImageAspectFlagBits specifying which aspect(s) of the image are included in the view.

  • baseMipLevel is the first mipmap level accessible to the view.

  • levelCount is the number of mipmap levels (starting from baseMipLevel) accessible to the view.

  • baseArrayLayer is the first array layer accessible to the view.

  • layerCount is the number of array layers (starting from baseArrayLayer) accessible to the view.

The number of mipmap levels and array layers must be a subset of the image subresources in the image. If an application wants to use all mip levels or layers in an image after the baseMipLevel or baseArrayLayer, it can set levelCount and layerCount to the special values VK_REMAINING_MIP_LEVELS and VK_REMAINING_ARRAY_LAYERS without knowing the exact number of mip levels or layers.

For cube and cube array image views, the layers of the image view starting at baseArrayLayer correspond to faces in the order +X, -X, +Y, -Y, +Z, -Z. For cube arrays, each set of six sequential layers is a single cube, so the number of cube maps in a cube map array view is layerCount / 6, and image array layer (baseArrayLayer + i) is face index (i mod 6) of cube i / 6. If the number of layers in the view, whether set explicitly in layerCount or implied by VK_REMAINING_ARRAY_LAYERS, is not a multiple of 6, the last cube map in the array must not be accessed.

aspectMask must be only VK_IMAGE_ASPECT_COLOR_BIT, VK_IMAGE_ASPECT_DEPTH_BIT or VK_IMAGE_ASPECT_STENCIL_BIT if format is a color, depth-only or stencil-only format, respectively, except if format is a multi-planar format. If using a depth/stencil format with both depth and stencil components, aspectMask must include at least one of VK_IMAGE_ASPECT_DEPTH_BIT and VK_IMAGE_ASPECT_STENCIL_BIT, and can include both.

When the VkImageSubresourceRange structure is used to select a subset of the slices of a 3D image’s mip level in order to create a 2D or 2D array image view of a 3D image created with VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT, baseArrayLayer and layerCount specify the first slice index and the number of slices to include in the created image view. Such an image view can be used as a framebuffer attachment that refers only to the specified range of slices of the selected mip level. However, any layout transitions performed on such an attachment view during a render pass instance still apply to the entire subresource referenced which includes all the slices of the selected mip level.

When using an image view of a depth/stencil image to populate a descriptor set (e.g. for sampling in the shader, or for use as an input attachment), the aspectMask must only include one bit, which selects whether the image view is used for depth reads (i.e. using a floating-point sampler or input attachment in the shader) or stencil reads (i.e. using an unsigned integer sampler or input attachment in the shader). When an image view of a depth/stencil image is used as a depth/stencil framebuffer attachment, the aspectMask is ignored and both depth and stencil image subresources are used.

When creating a VkImageView, if sampler Y′CBCR conversion is enabled in the sampler, the aspectMask of a subresourceRange used by the VkImageView must be VK_IMAGE_ASPECT_COLOR_BIT.

When creating a VkImageView, if sampler Y′CBCR conversion is not enabled in the sampler and the image format is multi-planar, the image must have been created with VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT, and the aspectMask of the VkImageView’s subresourceRange must be VK_IMAGE_ASPECT_PLANE_0_BIT, VK_IMAGE_ASPECT_PLANE_1_BIT or VK_IMAGE_ASPECT_PLANE_2_BIT.

Valid Usage

  • VUID-VkImageSubresourceRange-levelCount-01720
    If levelCount is not VK_REMAINING_MIP_LEVELS, it must be greater than 0

  • VUID-VkImageSubresourceRange-layerCount-01721
    If layerCount is not VK_REMAINING_ARRAY_LAYERS, it must be greater than 0

  • VUID-VkImageSubresourceRange-aspectMask-01670
    If aspectMask includes VK_IMAGE_ASPECT_COLOR_BIT, then it must not include any of VK_IMAGE_ASPECT_PLANE_0_BIT, VK_IMAGE_ASPECT_PLANE_1_BIT, or VK_IMAGE_ASPECT_PLANE_2_BIT

  • VUID-VkImageSubresourceRange-aspectMask-02278
    aspectMask must not include VK_IMAGE_ASPECT_MEMORY_PLANE_i_BIT_EXT for any index i

Valid Usage (Implicit)

  • VUID-VkImageSubresourceRange-aspectMask-parameter
    aspectMask must be a valid combination of VkImageAspectFlagBits values

  • VUID-VkImageSubresourceRange-aspectMask-requiredbitmask
    aspectMask must not be 0

Bits which can be set in an aspect mask to specify aspects of an image for purposes such as identifying a subresource, are:

// Provided by VK_VERSION_1_0
typedef enum VkImageAspectFlagBits {
    VK_IMAGE_ASPECT_COLOR_BIT = 0x00000001,
    VK_IMAGE_ASPECT_DEPTH_BIT = 0x00000002,
    VK_IMAGE_ASPECT_STENCIL_BIT = 0x00000004,
    VK_IMAGE_ASPECT_METADATA_BIT = 0x00000008,
  // Provided by VK_VERSION_1_1
    VK_IMAGE_ASPECT_PLANE_0_BIT = 0x00000010,
  // Provided by VK_VERSION_1_1
    VK_IMAGE_ASPECT_PLANE_1_BIT = 0x00000020,
  // Provided by VK_VERSION_1_1
    VK_IMAGE_ASPECT_PLANE_2_BIT = 0x00000040,
  // Provided by VK_VERSION_1_3
    VK_IMAGE_ASPECT_NONE = 0,
  // Provided by VK_EXT_image_drm_format_modifier
    VK_IMAGE_ASPECT_MEMORY_PLANE_0_BIT_EXT = 0x00000080,
  // Provided by VK_EXT_image_drm_format_modifier
    VK_IMAGE_ASPECT_MEMORY_PLANE_1_BIT_EXT = 0x00000100,
  // Provided by VK_EXT_image_drm_format_modifier
    VK_IMAGE_ASPECT_MEMORY_PLANE_2_BIT_EXT = 0x00000200,
  // Provided by VK_EXT_image_drm_format_modifier
    VK_IMAGE_ASPECT_MEMORY_PLANE_3_BIT_EXT = 0x00000400,
  // Provided by VK_KHR_sampler_ycbcr_conversion
    VK_IMAGE_ASPECT_PLANE_0_BIT_KHR = VK_IMAGE_ASPECT_PLANE_0_BIT,
  // Provided by VK_KHR_sampler_ycbcr_conversion
    VK_IMAGE_ASPECT_PLANE_1_BIT_KHR = VK_IMAGE_ASPECT_PLANE_1_BIT,
  // Provided by VK_KHR_sampler_ycbcr_conversion
    VK_IMAGE_ASPECT_PLANE_2_BIT_KHR = VK_IMAGE_ASPECT_PLANE_2_BIT,
  // Provided by VK_KHR_maintenance4
    VK_IMAGE_ASPECT_NONE_KHR = VK_IMAGE_ASPECT_NONE,
} VkImageAspectFlagBits;

  • VK_IMAGE_ASPECT_NONE specifies no image aspect, or the image aspect is not applicable.

  • VK_IMAGE_ASPECT_COLOR_BIT specifies the color aspect.

  • VK_IMAGE_ASPECT_DEPTH_BIT specifies the depth aspect.

  • VK_IMAGE_ASPECT_STENCIL_BIT specifies the stencil aspect.

  • VK_IMAGE_ASPECT_METADATA_BIT specifies the metadata aspect used for sparse resource operations.

  • VK_IMAGE_ASPECT_PLANE_0_BIT specifies plane 0 of a multi-planar image format.

  • VK_IMAGE_ASPECT_PLANE_1_BIT specifies plane 1 of a multi-planar image format.

  • VK_IMAGE_ASPECT_PLANE_2_BIT specifies plane 2 of a multi-planar image format.

  • VK_IMAGE_ASPECT_MEMORY_PLANE_0_BIT_EXT specifies memory plane 0.

  • VK_IMAGE_ASPECT_MEMORY_PLANE_1_BIT_EXT specifies memory plane 1.

  • VK_IMAGE_ASPECT_MEMORY_PLANE_2_BIT_EXT specifies memory plane 2.

  • VK_IMAGE_ASPECT_MEMORY_PLANE_3_BIT_EXT specifies memory plane 3.

// Provided by VK_VERSION_1_0
typedef VkFlags VkImageAspectFlags;

VkImageAspectFlags is a bitmask type for setting a mask of zero or more VkImageAspectFlagBits.

The VkComponentMapping structure is defined as:

// Provided by VK_VERSION_1_0
typedef struct VkComponentMapping {
    VkComponentSwizzle    r;
    VkComponentSwizzle    g;
    VkComponentSwizzle    b;
    VkComponentSwizzle    a;
} VkComponentMapping;

  • r is a VkComponentSwizzle specifying the component value placed in the R component of the output vector.

  • g is a VkComponentSwizzle specifying the component value placed in the G component of the output vector.

  • b is a VkComponentSwizzle specifying the component value placed in the B component of the output vector.

  • a is a VkComponentSwizzle specifying the component value placed in the A component of the output vector.

Valid Usage (Implicit)

Possible values of the members of VkComponentMapping, specifying the component values placed in each component of the output vector, are:

// Provided by VK_VERSION_1_0
typedef enum VkComponentSwizzle {
    VK_COMPONENT_SWIZZLE_IDENTITY = 0,
    VK_COMPONENT_SWIZZLE_ZERO = 1,
    VK_COMPONENT_SWIZZLE_ONE = 2,
    VK_COMPONENT_SWIZZLE_R = 3,
    VK_COMPONENT_SWIZZLE_G = 4,
    VK_COMPONENT_SWIZZLE_B = 5,
    VK_COMPONENT_SWIZZLE_A = 6,
} VkComponentSwizzle;

  • VK_COMPONENT_SWIZZLE_IDENTITY specifies that the component is set to the identity swizzle.

  • VK_COMPONENT_SWIZZLE_ZERO specifies that the component is set to zero.

  • VK_COMPONENT_SWIZZLE_ONE specifies that the component is set to either 1 or 1.0, depending on whether the type of the image view format is integer or floating-point respectively, as determined by the Format Definition section for each VkFormat.

  • VK_COMPONENT_SWIZZLE_R specifies that the component is set to the value of the R component of the image.

  • VK_COMPONENT_SWIZZLE_G specifies that the component is set to the value of the G component of the image.

  • VK_COMPONENT_SWIZZLE_B specifies that the component is set to the value of the B component of the image.

  • VK_COMPONENT_SWIZZLE_A specifies that the component is set to the value of the A component of the image.

Setting the identity swizzle on a component is equivalent to setting the identity mapping on that component. That is:

Table 16. Component Mappings Equivalent To VK_COMPONENT_SWIZZLE_IDENTITY
Component Identity Mapping

components.r

VK_COMPONENT_SWIZZLE_R

components.g

VK_COMPONENT_SWIZZLE_G

components.b

VK_COMPONENT_SWIZZLE_B

components.a

VK_COMPONENT_SWIZZLE_A

If the pNext chain includes a VkImageViewASTCDecodeModeEXT structure, then that structure includes a parameter specifying the decode mode for image views using ASTC compressed formats.

The VkImageViewASTCDecodeModeEXT structure is defined as:

// Provided by VK_EXT_astc_decode_mode
typedef struct VkImageViewASTCDecodeModeEXT {
    VkStructureType    sType;
    const void*        pNext;
    VkFormat           decodeMode;
} VkImageViewASTCDecodeModeEXT;

  • sType is a VkStructureType value identifying this structure.

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

  • decodeMode is the intermediate format used to decode ASTC compressed formats.

Valid Usage

  • VUID-VkImageViewASTCDecodeModeEXT-decodeMode-02230
    decodeMode must be one of VK_FORMAT_R16G16B16A16_SFLOAT, VK_FORMAT_R8G8B8A8_UNORM, or VK_FORMAT_E5B9G9R9_UFLOAT_PACK32

  • VUID-VkImageViewASTCDecodeModeEXT-decodeMode-02231
    If the decodeModeSharedExponent feature is not enabled, decodeMode must not be VK_FORMAT_E5B9G9R9_UFLOAT_PACK32

  • VUID-VkImageViewASTCDecodeModeEXT-decodeMode-02232
    If decodeMode is VK_FORMAT_R8G8B8A8_UNORM the image view must not include blocks using any of the ASTC HDR modes

  • VUID-VkImageViewASTCDecodeModeEXT-format-04084
    format of the image view must be one of the ASTC Compressed Image Formats

If format uses sRGB encoding then the decodeMode has no effect.

Valid Usage (Implicit)

  • VUID-VkImageViewASTCDecodeModeEXT-sType-sType
    sType must be VK_STRUCTURE_TYPE_IMAGE_VIEW_ASTC_DECODE_MODE_EXT

  • VUID-VkImageViewASTCDecodeModeEXT-decodeMode-parameter
    decodeMode must be a valid VkFormat value

If the pNext chain includes a VkImageViewSampleWeightCreateInfoQCOM structure, then that structure includes a parameter specifying the parameters for weight image views used in weight image sampling.

The VkImageViewSampleWeightCreateInfoQCOM structure is defined as:

// Provided by VK_QCOM_image_processing
typedef struct VkImageViewSampleWeightCreateInfoQCOM {
    VkStructureType    sType;
    const void*        pNext;
    VkOffset2D         filterCenter;
    VkExtent2D         filterSize;
    uint32_t           numPhases;
} VkImageViewSampleWeightCreateInfoQCOM;

  • sType is a VkStructureType value identifying this structure.

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

  • filterCenter is a VkOffset2D describing the location of the weight filter origin.

  • filterSize is a VkExtent2D specifying weight filter dimensions.

  • numPhases is number of sub-pixel filter phases.

The filterCenter specifies the origin or center of the filter kernel, as described in Weight Sampling Operation. The numPhases describes the number of sub-pixel filter phases as described in Weight Sampling Phases.

Valid Usage
Valid Usage (Implicit)

  • VUID-VkImageViewSampleWeightCreateInfoQCOM-sType-sType
    sType must be VK_STRUCTURE_TYPE_IMAGE_VIEW_SAMPLE_WEIGHT_CREATE_INFO_QCOM

To destroy an image view, call:

// Provided by VK_VERSION_1_0
void vkDestroyImageView(
    VkDevice                                    device,
    VkImageView                                 imageView,
    const VkAllocationCallbacks*                pAllocator);

  • device is the logical device that destroys the image view.

  • imageView is the image view to destroy.

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

Valid Usage

  • VUID-vkDestroyImageView-imageView-01026
    All submitted commands that refer to imageView must have completed execution

  • VUID-vkDestroyImageView-imageView-01027
    If VkAllocationCallbacks were provided when imageView was created, a compatible set of callbacks must be provided here

  • VUID-vkDestroyImageView-imageView-01028
    If no VkAllocationCallbacks were provided when imageView was created, pAllocator must be NULL

Valid Usage (Implicit)

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

  • VUID-vkDestroyImageView-imageView-parameter
    If imageView is not VK_NULL_HANDLE, imageView must be a valid VkImageView handle

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

  • VUID-vkDestroyImageView-imageView-parent
    If imageView is a valid handle, it must have been created, allocated, or retrieved from device

Host Synchronization

  • Host access to imageView must be externally synchronized

To get the handle for an image view, call:

// Provided by VK_NVX_image_view_handle
uint32_t vkGetImageViewHandleNVX(
    VkDevice                                    device,
    const VkImageViewHandleInfoNVX*             pInfo);

  • device is the logical device that owns the image view.

  • pInfo describes the image view to query and type of handle.

Valid Usage (Implicit)

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

  • VUID-vkGetImageViewHandleNVX-pInfo-parameter
    pInfo must be a valid pointer to a valid VkImageViewHandleInfoNVX structure

The VkImageViewHandleInfoNVX structure is defined as:

// Provided by VK_NVX_image_view_handle
typedef struct VkImageViewHandleInfoNVX {
    VkStructureType     sType;
    const void*         pNext;
    VkImageView         imageView;
    VkDescriptorType    descriptorType;
    VkSampler           sampler;
} VkImageViewHandleInfoNVX;

  • 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 to query.

  • descriptorType is the type of descriptor for which to query a handle.

  • sampler is the sampler to combine with the image view when generating the handle.

Valid Usage

  • VUID-VkImageViewHandleInfoNVX-descriptorType-02654
    descriptorType must be VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE, VK_DESCRIPTOR_TYPE_STORAGE_IMAGE, or VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER

  • VUID-VkImageViewHandleInfoNVX-sampler-02655
    sampler must be a valid VkSampler if descriptorType is VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER

  • VUID-VkImageViewHandleInfoNVX-imageView-02656
    If descriptorType is VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE or VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, the image that imageView was created from must have been created with the VK_IMAGE_USAGE_SAMPLED_BIT usage bit set

  • VUID-VkImageViewHandleInfoNVX-imageView-02657
    If descriptorType is VK_DESCRIPTOR_TYPE_STORAGE_IMAGE, the image that imageView was created from must have been created with the VK_IMAGE_USAGE_STORAGE_BIT usage bit set

Valid Usage (Implicit)

  • VUID-VkImageViewHandleInfoNVX-sType-sType
    sType must be VK_STRUCTURE_TYPE_IMAGE_VIEW_HANDLE_INFO_NVX

  • VUID-VkImageViewHandleInfoNVX-pNext-pNext
    pNext must be NULL

  • VUID-VkImageViewHandleInfoNVX-imageView-parameter
    imageView must be a valid VkImageView handle

  • VUID-VkImageViewHandleInfoNVX-descriptorType-parameter
    descriptorType must be a valid VkDescriptorType value

  • VUID-VkImageViewHandleInfoNVX-sampler-parameter
    If sampler is not VK_NULL_HANDLE, sampler must be a valid VkSampler handle

  • VUID-VkImageViewHandleInfoNVX-commonparent
    Both of imageView, and sampler that are valid handles of non-ignored parameters must have been created, allocated, or retrieved from the same VkDevice

To get the device address for an image view, call:

// Provided by VK_NVX_image_view_handle
VkResult vkGetImageViewAddressNVX(
    VkDevice                                    device,
    VkImageView                                 imageView,
    VkImageViewAddressPropertiesNVX*            pProperties);

  • device is the logical device that owns the image view.

  • imageView is a handle to the image view.

  • pProperties contains the device address and size when the call returns.

Valid Usage (Implicit)

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

  • VUID-vkGetImageViewAddressNVX-imageView-parameter
    imageView must be a valid VkImageView handle

  • VUID-vkGetImageViewAddressNVX-pProperties-parameter
    pProperties must be a valid pointer to a VkImageViewAddressPropertiesNVX structure

  • VUID-vkGetImageViewAddressNVX-imageView-parent
    imageView must have been created, allocated, or retrieved from device

Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_UNKNOWN

The VkImageViewAddressPropertiesNVX structure is defined as:

// Provided by VK_NVX_image_view_handle
typedef struct VkImageViewAddressPropertiesNVX {
    VkStructureType    sType;
    void*              pNext;
    VkDeviceAddress    deviceAddress;
    VkDeviceSize       size;
} VkImageViewAddressPropertiesNVX;

  • sType is a VkStructureType value identifying this structure.

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

  • deviceAddress is the device address of the image view.

  • size is the size in bytes of the image view device memory.

Valid Usage (Implicit)

  • VUID-VkImageViewAddressPropertiesNVX-sType-sType
    sType must be VK_STRUCTURE_TYPE_IMAGE_VIEW_ADDRESS_PROPERTIES_NVX

  • VUID-VkImageViewAddressPropertiesNVX-pNext-pNext
    pNext must be NULL

12.5.1. Image View Format Features

Valid uses of a VkImageView may depend on the image view’s format features, defined below. Such constraints are documented in the affected valid usage statement.

The VkImageViewMinLodCreateInfoEXT structure is defined as:

// Provided by VK_EXT_image_view_min_lod
typedef struct VkImageViewMinLodCreateInfoEXT {
    VkStructureType    sType;
    const void*        pNext;
    float              minLod;
} VkImageViewMinLodCreateInfoEXT;

  • sType is a VkStructureType value identifying this structure.

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

  • minLod is the value to clamp the minimum LOD accessible by this VkImageView.

If the pNext chain includes a VkImageViewMinLodCreateInfoEXT structure, then that structure includes a parameter specifying a value to clamp the minimum LOD value during Image Level(s) Selection, Texel Gathering and Integer Texel Coordinate Operations.

If the image view contains VkImageViewMinLodCreateInfoEXT and it is used as part of a sampling operation:

minLodFloatimageView = minLod

otherwise:

minLodFloatimageView = 0.0

An integer variant of this parameter is also defined for sampling operations which access integer mipmap levels:

minLodIntegerimageView = ⌊minLodFloatimageView⌋

Valid Usage

  • VUID-VkImageViewMinLodCreateInfoEXT-minLod-06455
    If the minLod feature is not enabled, minLod must be 0.0

  • VUID-VkImageViewMinLodCreateInfoEXT-minLod-06456
    minLod must be less or equal to the index of the last mipmap level accessible to the view

Valid Usage (Implicit)

  • VUID-VkImageViewMinLodCreateInfoEXT-sType-sType
    sType must be VK_STRUCTURE_TYPE_IMAGE_VIEW_MIN_LOD_CREATE_INFO_EXT

12.6. Acceleration Structures

Acceleration structures are opaque data structures that are built by the implementation to more efficiently perform spatial queries on the provided geometric data. For this extension, an acceleration structure is either a top-level acceleration structure containing a set of bottom-level acceleration structures or a bottom-level acceleration structure containing either a set of axis-aligned bounding boxes for custom geometry or a set of triangles.

Each instance in the top-level acceleration structure contains a reference to a bottom-level acceleration structure as well as an instance transform plus information required to index into the shader bindings. The top-level acceleration structure is what is bound to the acceleration descriptor, for example to trace inside the shader in the ray tracing pipeline.

Acceleration structures are represented by VkAccelerationStructureKHR handles:

// Provided by VK_KHR_acceleration_structure
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkAccelerationStructureKHR)

Acceleration structures for the VK_NV_ray_tracing extension are represented by the similar VkAccelerationStructureNV handles:

// Provided by VK_NV_ray_tracing
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkAccelerationStructureNV)

To create acceleration structures, call:

// Provided by VK_NV_ray_tracing
VkResult vkCreateAccelerationStructureNV(
    VkDevice                                    device,
    const VkAccelerationStructureCreateInfoNV*  pCreateInfo,
    const VkAllocationCallbacks*                pAllocator,
    VkAccelerationStructureNV*                  pAccelerationStructure);

  • device is the logical device that creates the buffer object.

  • pCreateInfo is a pointer to a VkAccelerationStructureCreateInfoNV structure containing parameters affecting creation of the acceleration structure.

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

  • pAccelerationStructure is a pointer to a VkAccelerationStructureNV handle in which the resulting acceleration structure object is returned.

Similarly to other objects in Vulkan, the acceleration structure creation merely creates an object with a specific “shape” as specified by the information in VkAccelerationStructureInfoNV and compactedSize in pCreateInfo.

Once memory has been bound to the acceleration structure using vkBindAccelerationStructureMemoryNV, that memory is populated by calls to vkCmdBuildAccelerationStructureNV and vkCmdCopyAccelerationStructureNV.

Acceleration structure creation uses the count and type information from the geometries, but does not use the data references in the structures.

Valid Usage (Implicit)

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

  • VUID-vkCreateAccelerationStructureNV-pCreateInfo-parameter
    pCreateInfo must be a valid pointer to a valid VkAccelerationStructureCreateInfoNV structure

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

  • VUID-vkCreateAccelerationStructureNV-pAccelerationStructure-parameter
    pAccelerationStructure must be a valid pointer to a VkAccelerationStructureNV handle

Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

The VkAccelerationStructureCreateInfoNV structure is defined as:

// Provided by VK_NV_ray_tracing
typedef struct VkAccelerationStructureCreateInfoNV {
    VkStructureType                  sType;
    const void*                      pNext;
    VkDeviceSize                     compactedSize;
    VkAccelerationStructureInfoNV    info;
} VkAccelerationStructureCreateInfoNV;
Valid Usage

  • VUID-VkAccelerationStructureCreateInfoNV-compactedSize-02421
    If compactedSize is not 0 then both info.geometryCount and info.instanceCount must be 0

Valid Usage (Implicit)

  • VUID-VkAccelerationStructureCreateInfoNV-sType-sType
    sType must be VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_CREATE_INFO_NV

  • VUID-VkAccelerationStructureCreateInfoNV-pNext-pNext
    pNext must be NULL or a pointer to a valid instance of VkOpaqueCaptureDescriptorDataCreateInfoEXT

  • VUID-VkAccelerationStructureCreateInfoNV-sType-unique
    The sType value of each struct in the pNext chain must be unique

  • VUID-VkAccelerationStructureCreateInfoNV-info-parameter
    info must be a valid VkAccelerationStructureInfoNV structure

The VkAccelerationStructureInfoNV structure is defined as:

// Provided by VK_NV_ray_tracing
typedef struct VkAccelerationStructureInfoNV {
    VkStructureType                        sType;
    const void*                            pNext;
    VkAccelerationStructureTypeNV          type;
    VkBuildAccelerationStructureFlagsNV    flags;
    uint32_t                               instanceCount;
    uint32_t                               geometryCount;
    const VkGeometryNV*                    pGeometries;
} VkAccelerationStructureInfoNV;

  • sType is a VkStructureType value identifying this structure.

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

  • type is a VkAccelerationStructureTypeNV value specifying the type of acceleration structure that will be created.

  • flags is a bitmask of VkBuildAccelerationStructureFlagBitsNV specifying additional parameters of the acceleration structure.

  • instanceCount specifies the number of instances that will be in the new acceleration structure.

  • geometryCount specifies the number of geometries that will be in the new acceleration structure.

  • pGeometries is a pointer to an array of geometryCount VkGeometryNV structures containing the scene data being passed into the acceleration structure.

VkAccelerationStructureInfoNV contains information that is used both for acceleration structure creation with vkCreateAccelerationStructureNV and in combination with the actual geometric data to build the acceleration structure with vkCmdBuildAccelerationStructureNV.

Valid Usage

  • VUID-VkAccelerationStructureInfoNV-geometryCount-02422
    geometryCount must be less than or equal to VkPhysicalDeviceRayTracingPropertiesNV::maxGeometryCount

  • VUID-VkAccelerationStructureInfoNV-instanceCount-02423
    instanceCount must be less than or equal to VkPhysicalDeviceRayTracingPropertiesNV::maxInstanceCount

  • VUID-VkAccelerationStructureInfoNV-maxTriangleCount-02424
    The total number of triangles in all geometries must be less than or equal to VkPhysicalDeviceRayTracingPropertiesNV::maxTriangleCount

  • VUID-VkAccelerationStructureInfoNV-type-02425
    If type is VK_ACCELERATION_STRUCTURE_TYPE_TOP_LEVEL_NV then geometryCount must be 0

  • VUID-VkAccelerationStructureInfoNV-type-02426
    If type is VK_ACCELERATION_STRUCTURE_TYPE_BOTTOM_LEVEL_NV then instanceCount must be 0

  • VUID-VkAccelerationStructureInfoNV-type-02786
    If type is VK_ACCELERATION_STRUCTURE_TYPE_BOTTOM_LEVEL_NV then the geometryType member of each geometry in pGeometries must be the same

  • VUID-VkAccelerationStructureInfoNV-type-04623
    type must not be VK_ACCELERATION_STRUCTURE_TYPE_GENERIC_KHR

  • VUID-VkAccelerationStructureInfoNV-flags-02592
    If flags has the