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 theVkDevice
object they are retrieved from is destroyed. -
Destroying a pool object implicitly frees all objects allocated from that pool. Specifically, destroying
VkCommandPool
frees allVkCommandBuffer
objects that were allocated from it, and destroyingVkDescriptorPool
frees allVkDescriptorSet
objects that were allocated from it. -
VkDevice
objects can be destroyed when allVkQueue
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 theVkInstance
object they are retrieved from is destroyed. -
VkInstance
objects can be destroyed once allVkDevice
objects created from any of itsVkPhysicalDevice
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.
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.
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.
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:
-
it was added by a core version that is supported (as reported by vkEnumerateInstanceVersion) and the value of VkApplicationInfo::
apiVersion
is greater than or equal to the version that added it; or -
it was added by an instance extension that was enabled for the instance.
-
-
If the enumerant is used in a function that has a VkPhysicalDevice object as its first parameter and either:
-
it was added by a core version that is supported by that device (as reported by VkPhysicalDeviceProperties::
apiVersion
); -
it was added by an instance extension that was enabled for the instance; or
-
it was added by a device extension that is supported by that device.
-
-
If the enumerant is used in a function that has any other dispatchable object as its first parameter and either:
-
it was added by a core version that is supported for the device (as reported by VkPhysicalDeviceProperties::
apiVersion
); or -
it was added by a device extension that was enabled for the device.
-
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 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 |
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 |
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
isNULL
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
isNULL
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;
-
VK_SUCCESS
Command successfully completed -
VK_NOT_READY
A fence or query has not yet completed -
VK_TIMEOUT
A wait operation has not completed in the specified time -
VK_EVENT_SET
An event is signaled -
VK_EVENT_RESET
An event is unsignaled -
VK_INCOMPLETE
A return array was too small for the result -
VK_SUBOPTIMAL_KHR
A swapchain no longer matches the surface properties exactly, but can still be used to present to the surface successfully. -
VK_THREAD_IDLE_KHR
A deferred operation is not complete but there is currently no work for this thread to do at the time of this call. -
VK_THREAD_DONE_KHR
A deferred operation is not complete but there is no work remaining to assign to additional threads. -
VK_OPERATION_DEFERRED_KHR
A deferred operation was requested and at least some of the work was deferred. -
VK_OPERATION_NOT_DEFERRED_KHR
A deferred operation was requested and no operations were deferred. -
VK_PIPELINE_COMPILE_REQUIRED
A requested pipeline creation would have required compilation, but the application requested compilation to not be performed.
-
VK_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 toVK_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 viaVK_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 withVK_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, |
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
|
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
|
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, orNULL
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.
instance |
pName |
return value |
---|---|---|
*1 |
|
undefined |
invalid non- |
*1 |
undefined |
|
global command2 |
fp |
|
fp5 |
|
instance |
fp |
|
instance |
core dispatchable command |
fp3 |
instance |
enabled instance extension dispatchable command for |
fp3 |
instance |
available device extension4 dispatchable command for |
fp3 |
any other case, not covered above |
|
- 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 ofinstance
, 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 aNULL
instance pointer.
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
.
device |
pName |
return value |
---|---|---|
|
*1 |
undefined |
invalid device |
*1 |
undefined |
device |
|
undefined |
device |
requested core version2 device-level dispatchable command3 |
fp4 |
device |
enabled extension device-level dispatchable command3 |
fp4 |
any other case, not covered above |
|
- 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 returnNULL
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 ofdevice
e.g. VkDevice, VkQueue, or VkCommandBuffer.
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 auint32_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 |
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.
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
isNULL
or a pointer to a structure extending this structure. -
flags
is a bitmask of VkInstanceCreateFlagBits indicating the behavior of the instance. -
pApplicationInfo
isNULL
or a pointer to aVkApplicationInfo
structure. If notNULL
, 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 ofenabledLayerCount
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 ofenabledExtensionCount
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. |
// 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
isNULL
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.
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
isNULL
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.
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 processdebugPrintfEXT
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 |
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
isNULL
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 ofdriverCount
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.
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;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
flags
is reserved for future use. -
pfnGetInstanceProcAddr
is a PFN_vkGetInstanceProcAddrLUNARG pointer to the driver vkGetInstanceProcAddr function.
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 |
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
isNULL
or a pointer to a structure extending this structure. -
pApplicationName
isNULL
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
isNULL
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 inapiVersion
is ignored when creating an instance object. The variant version of the instance must match that requested inapiVersion
.
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
|
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 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
If we modify the above example so that the application sets |
Note
Providing a |
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.
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 eitherNULL
or a pointer to an array ofVkPhysicalDevice
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.
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.
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 ofVK_MAX_PHYSICAL_DEVICE_NAME_SIZE
char
containing a null-terminated UTF-8 string which is the name of the device. -
pipelineCacheUUID
is an array ofVK_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 |
Note
The encoding of |
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 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.
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;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
properties
is a VkPhysicalDeviceProperties structure describing properties of the physical device. This structure is written with the same values as if it were written by vkGetPhysicalDeviceProperties.
The pNext
chain of this structure is used to extend the structure with
properties defined by extensions.
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
isNULL
or a pointer to a structure extending this structure.
-
deviceUUID
is an array ofVK_UUID_SIZE
uint8_t
values representing a universally unique identifier for the device. -
driverUUID
is an array ofVK_UUID_SIZE
uint8_t
values representing a universally unique identifier for the driver build in use by the device. -
deviceLUID
is an array ofVK_LUID_SIZE
uint8_t
values representing a locally unique identifier for the device. -
deviceNodeMask
is auint32_t
bitfield identifying the node within a linked device adapter corresponding to the device. -
deviceLUIDValid
is a boolean value that will beVK_TRUE
ifdeviceLUID
contains a valid LUID anddeviceNodeMask
contains a valid node mask, andVK_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 supportVK_QUEUE_GRAPHICS_BIT
orVK_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 theVK_SHADER_STAGE_COMPUTE_BIT
bit set if any of the physical device’s queues supportVK_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 theVK_SUBGROUP_FEATURE_BASIC_BIT
bit set if any of the physical device’s queues supportVK_QUEUE_GRAPHICS_BIT
orVK_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 isVK_TRUE
, such writes will be discarded or have undefined values written, reads and queries will return undefined values. If this limit isVK_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.
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
isNULL
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 ofVK_MAX_DRIVER_NAME_SIZE
char
containing a null-terminated UTF-8 string which is the name of the driver. -
driverInfo
is an array ofVK_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 theSignedZeroInfNanPreserve
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 theSignedZeroInfNanPreserve
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 theSignedZeroInfNanPreserve
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 theDenormPreserve
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 theDenormPreserve
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 theDenormPreserve
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 theDenormFlushToZero
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 theDenormFlushToZero
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 theDenormFlushToZero
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 theRoundingModeRTE
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 theRoundingModeRTE
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 theRoundingModeRTE
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 theRoundingModeRTZ
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 theRoundingModeRTZ
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 theRoundingModeRTZ
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 theVK_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 isVK_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 isVK_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 isVK_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 isVK_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 isVK_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 whetherrobustBufferAccess
can be enabled on a device simultaneously withdescriptorBindingUniformBufferUpdateAfterBind
,descriptorBindingStorageBufferUpdateAfterBind
,descriptorBindingUniformTexelBufferUpdateAfterBind
, and/ordescriptorBindingStorageTexelBufferUpdateAfterBind
. If this isVK_FALSE
, then eitherrobustBufferAccess
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 tomaxPerStageDescriptorSamplers
but counts descriptors from descriptor sets created with or without theVK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT
bit set. -
maxPerStageDescriptorUpdateAfterBindUniformBuffers
is similar tomaxPerStageDescriptorUniformBuffers
but counts descriptors from descriptor sets created with or without theVK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT
bit set. -
maxPerStageDescriptorUpdateAfterBindStorageBuffers
is similar tomaxPerStageDescriptorStorageBuffers
but counts descriptors from descriptor sets created with or without theVK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT
bit set. -
maxPerStageDescriptorUpdateAfterBindSampledImages
is similar tomaxPerStageDescriptorSampledImages
but counts descriptors from descriptor sets created with or without theVK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT
bit set. -
maxPerStageDescriptorUpdateAfterBindStorageImages
is similar tomaxPerStageDescriptorStorageImages
but counts descriptors from descriptor sets created with or without theVK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT
bit set. -
maxPerStageDescriptorUpdateAfterBindInputAttachments
is similar tomaxPerStageDescriptorInputAttachments
but counts descriptors from descriptor sets created with or without theVK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT
bit set. -
maxPerStageUpdateAfterBindResources
is similar tomaxPerStageResources
but counts descriptors from descriptor sets created with or without theVK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT
bit set. -
maxDescriptorSetUpdateAfterBindSamplers
is similar tomaxDescriptorSetSamplers
but counts descriptors from descriptor sets created with or without theVK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT
bit set. -
maxDescriptorSetUpdateAfterBindUniformBuffers
is similar tomaxDescriptorSetUniformBuffers
but counts descriptors from descriptor sets created with or without theVK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT
bit set. -
maxDescriptorSetUpdateAfterBindUniformBuffersDynamic
is similar tomaxDescriptorSetUniformBuffersDynamic
but counts descriptors from descriptor sets created with or without theVK_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 theVK_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 withVK_DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BIT
. -
maxDescriptorSetUpdateAfterBindStorageBuffers
is similar tomaxDescriptorSetStorageBuffers
but counts descriptors from descriptor sets created with or without theVK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT
bit set. -
maxDescriptorSetUpdateAfterBindStorageBuffersDynamic
is similar tomaxDescriptorSetStorageBuffersDynamic
but counts descriptors from descriptor sets created with or without theVK_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 theVK_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 withVK_DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BIT
. -
maxDescriptorSetUpdateAfterBindSampledImages
is similar tomaxDescriptorSetSampledImages
but counts descriptors from descriptor sets created with or without theVK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT
bit set. -
maxDescriptorSetUpdateAfterBindStorageImages
is similar tomaxDescriptorSetStorageImages
but counts descriptors from descriptor sets created with or without theVK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT
bit set. -
maxDescriptorSetUpdateAfterBindInputAttachments
is similar tomaxDescriptorSetInputAttachments
but counts descriptors from descriptor sets created with or without theVK_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
isVK_TRUE
if the implementation supports setting the depth and stencil resolve modes to different values when one of those modes isVK_RESOLVE_MODE_NONE
. Otherwise the implementation only supports setting both modes to the same value. -
independentResolve
isVK_TRUE
if the implementation supports all combinations of the supported depth and stencil resolve modes, including setting either depth or stencil resolve mode toVK_RESOLVE_MODE_NONE
. An implementation that supportsindependentResolve
must also supportindependentResolveNone
. -
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.
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
isNULL
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 supportVK_QUEUE_GRAPHICS_BIT
orVK_QUEUE_COMPUTE_BIT
.minSubgroupSize
is a power-of-two.minSubgroupSize
is less than or equal tomaxSubgroupSize
.minSubgroupSize
is less than or equal tosubgroupSize
. -
maxSubgroupSize
is the maximum subgroup size supported by this device.maxSubgroupSize
is at least one if any of the physical device’s queues supportVK_QUEUE_GRAPHICS_BIT
orVK_QUEUE_COMPUTE_BIT
.maxSubgroupSize
is a power-of-two.maxSubgroupSize
is greater than or equal tominSubgroupSize
.maxSubgroupSize
is greater than or equal tosubgroupSize
. -
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 ofVK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK
count against this limit. Only descriptor bindings in descriptor set layouts created without theVK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT
bit set count against this limit. -
maxPerStageDescriptorUpdateAfterBindInlineUniformBlocks
is similar tomaxPerStageDescriptorInlineUniformBlocks
but counts descriptor bindings from descriptor sets created with or without theVK_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 ofVK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK
count against this limit. Only descriptor bindings in descriptor set layouts created without theVK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT
bit set count against this limit. -
maxDescriptorSetUpdateAfterBindInlineUniformBlocks
is similar tomaxDescriptorSetInlineUniformBlocks
but counts descriptor bindings from descriptor sets created with or without theVK_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 ofVK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK
count against this limit. -
integerDotProduct8BitUnsignedAccelerated
is a boolean that will beVK_TRUE
if the support for 8-bit unsigned dot product operations using theOpUDotKHR
SPIR-V instruction is accelerated as defined below. -
integerDotProduct8BitSignedAccelerated
is a boolean that will beVK_TRUE
if the support for 8-bit signed dot product operations using theOpSDotKHR
SPIR-V instruction is accelerated as defined below. -
integerDotProduct8BitMixedSignednessAccelerated
is a boolean that will beVK_TRUE
if the support for 8-bit mixed signedness dot product operations using theOpSUDotKHR
SPIR-V instruction is accelerated as defined below. -
integerDotProduct4x8BitPackedUnsignedAccelerated
is a boolean that will beVK_TRUE
if the support for 8-bit unsigned dot product operations from operands packed into 32-bit integers using theOpUDotKHR
SPIR-V instruction is accelerated as defined below. -
integerDotProduct4x8BitPackedSignedAccelerated
is a boolean that will beVK_TRUE
if the support for 8-bit signed dot product operations from operands packed into 32-bit integers using theOpSDotKHR
SPIR-V instruction is accelerated as defined below. -
integerDotProduct4x8BitPackedMixedSignednessAccelerated
is a boolean that will beVK_TRUE
if the support for 8-bit mixed signedness dot product operations from operands packed into 32-bit integers using theOpSUDotKHR
SPIR-V instruction is accelerated as defined below. -
integerDotProduct16BitUnsignedAccelerated
is a boolean that will beVK_TRUE
if the support for 16-bit unsigned dot product operations using theOpUDotKHR
SPIR-V instruction is accelerated as defined below. -
integerDotProduct16BitSignedAccelerated
is a boolean that will beVK_TRUE
if the support for 16-bit signed dot product operations using theOpSDotKHR
SPIR-V instruction is accelerated as defined below. -
integerDotProduct16BitMixedSignednessAccelerated
is a boolean that will beVK_TRUE
if the support for 16-bit mixed signedness dot product operations using theOpSUDotKHR
SPIR-V instruction is accelerated as defined below. -
integerDotProduct32BitUnsignedAccelerated
is a boolean that will beVK_TRUE
if the support for 32-bit unsigned dot product operations using theOpUDotKHR
SPIR-V instruction is accelerated as defined below. -
integerDotProduct32BitSignedAccelerated
is a boolean that will beVK_TRUE
if the support for 32-bit signed dot product operations using theOpSDotKHR
SPIR-V instruction is accelerated as defined below. -
integerDotProduct32BitMixedSignednessAccelerated
is a boolean that will beVK_TRUE
if the support for 32-bit mixed signedness dot product operations using theOpSUDotKHR
SPIR-V instruction is accelerated as defined below. -
integerDotProduct64BitUnsignedAccelerated
is a boolean that will beVK_TRUE
if the support for 64-bit unsigned dot product operations using theOpUDotKHR
SPIR-V instruction is accelerated as defined below. -
integerDotProduct64BitSignedAccelerated
is a boolean that will beVK_TRUE
if the support for 64-bit signed dot product operations using theOpSDotKHR
SPIR-V instruction is accelerated as defined below. -
integerDotProduct64BitMixedSignednessAccelerated
is a boolean that will beVK_TRUE
if the support for 64-bit mixed signedness dot product operations using theOpSUDotKHR
SPIR-V instruction is accelerated as defined below. -
integerDotProductAccumulatingSaturating8BitUnsignedAccelerated
is a boolean that will beVK_TRUE
if the support for 8-bit unsigned accumulating saturating dot product operations using theOpUDotAccSatKHR
SPIR-V instruction is accelerated as defined below. -
integerDotProductAccumulatingSaturating8BitSignedAccelerated
is a boolean that will beVK_TRUE
if the support for 8-bit signed accumulating saturating dot product operations using theOpSDotAccSatKHR
SPIR-V instruction is accelerated as defined below. -
integerDotProductAccumulatingSaturating8BitMixedSignednessAccelerated
is a boolean that will beVK_TRUE
if the support for 8-bit mixed signedness accumulating saturating dot product operations using theOpSUDotAccSatKHR
SPIR-V instruction is accelerated as defined below. -
integerDotProductAccumulatingSaturating4x8BitPackedUnsignedAccelerated
is a boolean that will beVK_TRUE
if the support for 8-bit unsigned accumulating saturating dot product operations from operands packed into 32-bit integers using theOpUDotAccSatKHR
SPIR-V instruction is accelerated as defined below. -
integerDotProductAccumulatingSaturating4x8BitPackedSignedAccelerated
is a boolean that will beVK_TRUE
if the support for 8-bit signed accumulating saturating dot product operations from operands packed into 32-bit integers using theOpSDotAccSatKHR
SPIR-V instruction is accelerated as defined below. -
integerDotProductAccumulatingSaturating4x8BitPackedMixedSignednessAccelerated
is a boolean that will beVK_TRUE
if the support for 8-bit mixed signedness accumulating saturating dot product operations from operands packed into 32-bit integers using theOpSUDotAccSatKHR
SPIR-V instruction is accelerated as defined below. -
integerDotProductAccumulatingSaturating16BitUnsignedAccelerated
is a boolean that will beVK_TRUE
if the support for 16-bit unsigned accumulating saturating dot product operations using theOpUDotAccSatKHR
SPIR-V instruction is accelerated as defined below. -
integerDotProductAccumulatingSaturating16BitSignedAccelerated
is a boolean that will beVK_TRUE
if the support for 16-bit signed accumulating saturating dot product operations using theOpSDotAccSatKHR
SPIR-V instruction is accelerated as defined below. -
integerDotProductAccumulatingSaturating16BitMixedSignednessAccelerated
is a boolean that will beVK_TRUE
if the support for 16-bit mixed signedness accumulating saturating dot product operations using theOpSUDotAccSatKHR
SPIR-V instruction is accelerated as defined below. -
integerDotProductAccumulatingSaturating32BitUnsignedAccelerated
is a boolean that will beVK_TRUE
if the support for 32-bit unsigned accumulating saturating dot product operations using theOpUDotAccSatKHR
SPIR-V instruction is accelerated as defined below. -
integerDotProductAccumulatingSaturating32BitSignedAccelerated
is a boolean that will beVK_TRUE
if the support for 32-bit signed accumulating saturating dot product operations using theOpSDotAccSatKHR
SPIR-V instruction is accelerated as defined below. -
integerDotProductAccumulatingSaturating32BitMixedSignednessAccelerated
is a boolean that will beVK_TRUE
if the support for 32-bit mixed signedness accumulating saturating dot product operations using theOpSUDotAccSatKHR
SPIR-V instruction is accelerated as defined below. -
integerDotProductAccumulatingSaturating64BitUnsignedAccelerated
is a boolean that will beVK_TRUE
if the support for 64-bit unsigned accumulating saturating dot product operations using theOpUDotAccSatKHR
SPIR-V instruction is accelerated as defined below. -
integerDotProductAccumulatingSaturating64BitSignedAccelerated
is a boolean that will beVK_TRUE
if the support for 64-bit signed accumulating saturating dot product operations using theOpSDotAccSatKHR
SPIR-V instruction is accelerated as defined below. -
integerDotProductAccumulatingSaturating64BitMixedSignednessAccelerated
is a boolean that will beVK_TRUE
if the support for 64-bit mixed signedness accumulating saturating dot product operations using theOpSUDotAccSatKHR
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 sizeVkBuffer
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.
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
isNULL
or a pointer to a structure extending this structure.
-
deviceUUID
is an array ofVK_UUID_SIZE
uint8_t
values representing a universally unique identifier for the device. -
driverUUID
is an array ofVK_UUID_SIZE
uint8_t
values representing a universally unique identifier for the driver build in use by the device. -
deviceLUID
is an array ofVK_LUID_SIZE
uint8_t
values representing a locally unique identifier for the device. -
deviceNodeMask
is auint32_t
bitfield identifying the node within a linked device adapter corresponding to the device. -
deviceLUIDValid
is a boolean value that will beVK_TRUE
ifdeviceLUID
contains a valid LUID anddeviceNodeMask
contains a valid node mask, andVK_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:: Implementations should return Khronos' conformance testing is unable to guarantee that A combination of values unique to the vendor, the driver, and the hardware
environment can be used to provide a
|
Note
While VkPhysicalDeviceIDProperties:: |
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
isNULL
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 ofVK_MAX_DRIVER_NAME_SIZE
char
containing a null-terminated UTF-8 string which is the name of the driver. -
driverInfo
is an array ofVK_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.
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 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
isNULL
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.
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
isNULL
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.
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
isNULL
or a pointer to a structure extending this structure.
-
integerDotProduct8BitUnsignedAccelerated
is a boolean that will beVK_TRUE
if the support for 8-bit unsigned dot product operations using theOpUDotKHR
SPIR-V instruction is accelerated as defined below. -
integerDotProduct8BitSignedAccelerated
is a boolean that will beVK_TRUE
if the support for 8-bit signed dot product operations using theOpSDotKHR
SPIR-V instruction is accelerated as defined below. -
integerDotProduct8BitMixedSignednessAccelerated
is a boolean that will beVK_TRUE
if the support for 8-bit mixed signedness dot product operations using theOpSUDotKHR
SPIR-V instruction is accelerated as defined below. -
integerDotProduct4x8BitPackedUnsignedAccelerated
is a boolean that will beVK_TRUE
if the support for 8-bit unsigned dot product operations from operands packed into 32-bit integers using theOpUDotKHR
SPIR-V instruction is accelerated as defined below. -
integerDotProduct4x8BitPackedSignedAccelerated
is a boolean that will beVK_TRUE
if the support for 8-bit signed dot product operations from operands packed into 32-bit integers using theOpSDotKHR
SPIR-V instruction is accelerated as defined below. -
integerDotProduct4x8BitPackedMixedSignednessAccelerated
is a boolean that will beVK_TRUE
if the support for 8-bit mixed signedness dot product operations from operands packed into 32-bit integers using theOpSUDotKHR
SPIR-V instruction is accelerated as defined below. -
integerDotProduct16BitUnsignedAccelerated
is a boolean that will beVK_TRUE
if the support for 16-bit unsigned dot product operations using theOpUDotKHR
SPIR-V instruction is accelerated as defined below. -
integerDotProduct16BitSignedAccelerated
is a boolean that will beVK_TRUE
if the support for 16-bit signed dot product operations using theOpSDotKHR
SPIR-V instruction is accelerated as defined below. -
integerDotProduct16BitMixedSignednessAccelerated
is a boolean that will beVK_TRUE
if the support for 16-bit mixed signedness dot product operations using theOpSUDotKHR
SPIR-V instruction is accelerated as defined below. -
integerDotProduct32BitUnsignedAccelerated
is a boolean that will beVK_TRUE
if the support for 32-bit unsigned dot product operations using theOpUDotKHR
SPIR-V instruction is accelerated as defined below. -
integerDotProduct32BitSignedAccelerated
is a boolean that will beVK_TRUE
if the support for 32-bit signed dot product operations using theOpSDotKHR
SPIR-V instruction is accelerated as defined below. -
integerDotProduct32BitMixedSignednessAccelerated
is a boolean that will beVK_TRUE
if the support for 32-bit mixed signedness dot product operations using theOpSUDotKHR
SPIR-V instruction is accelerated as defined below. -
integerDotProduct64BitUnsignedAccelerated
is a boolean that will beVK_TRUE
if the support for 64-bit unsigned dot product operations using theOpUDotKHR
SPIR-V instruction is accelerated as defined below. -
integerDotProduct64BitSignedAccelerated
is a boolean that will beVK_TRUE
if the support for 64-bit signed dot product operations using theOpSDotKHR
SPIR-V instruction is accelerated as defined below. -
integerDotProduct64BitMixedSignednessAccelerated
is a boolean that will beVK_TRUE
if the support for 64-bit mixed signedness dot product operations using theOpSUDotKHR
SPIR-V instruction is accelerated as defined below. -
integerDotProductAccumulatingSaturating8BitUnsignedAccelerated
is a boolean that will beVK_TRUE
if the support for 8-bit unsigned accumulating saturating dot product operations using theOpUDotAccSatKHR
SPIR-V instruction is accelerated as defined below. -
integerDotProductAccumulatingSaturating8BitSignedAccelerated
is a boolean that will beVK_TRUE
if the support for 8-bit signed accumulating saturating dot product operations using theOpSDotAccSatKHR
SPIR-V instruction is accelerated as defined below. -
integerDotProductAccumulatingSaturating8BitMixedSignednessAccelerated
is a boolean that will beVK_TRUE
if the support for 8-bit mixed signedness accumulating saturating dot product operations using theOpSUDotAccSatKHR
SPIR-V instruction is accelerated as defined below. -
integerDotProductAccumulatingSaturating4x8BitPackedUnsignedAccelerated
is a boolean that will beVK_TRUE
if the support for 8-bit unsigned accumulating saturating dot product operations from operands packed into 32-bit integers using theOpUDotAccSatKHR
SPIR-V instruction is accelerated as defined below. -
integerDotProductAccumulatingSaturating4x8BitPackedSignedAccelerated
is a boolean that will beVK_TRUE
if the support for 8-bit signed accumulating saturating dot product operations from operands packed into 32-bit integers using theOpSDotAccSatKHR
SPIR-V instruction is accelerated as defined below. -
integerDotProductAccumulatingSaturating4x8BitPackedMixedSignednessAccelerated
is a boolean that will beVK_TRUE
if the support for 8-bit mixed signedness accumulating saturating dot product operations from operands packed into 32-bit integers using theOpSUDotAccSatKHR
SPIR-V instruction is accelerated as defined below. -
integerDotProductAccumulatingSaturating16BitUnsignedAccelerated
is a boolean that will beVK_TRUE
if the support for 16-bit unsigned accumulating saturating dot product operations using theOpUDotAccSatKHR
SPIR-V instruction is accelerated as defined below. -
integerDotProductAccumulatingSaturating16BitSignedAccelerated
is a boolean that will beVK_TRUE
if the support for 16-bit signed accumulating saturating dot product operations using theOpSDotAccSatKHR
SPIR-V instruction is accelerated as defined below. -
integerDotProductAccumulatingSaturating16BitMixedSignednessAccelerated
is a boolean that will beVK_TRUE
if the support for 16-bit mixed signedness accumulating saturating dot product operations using theOpSUDotAccSatKHR
SPIR-V instruction is accelerated as defined below. -
integerDotProductAccumulatingSaturating32BitUnsignedAccelerated
is a boolean that will beVK_TRUE
if the support for 32-bit unsigned accumulating saturating dot product operations using theOpUDotAccSatKHR
SPIR-V instruction is accelerated as defined below. -
integerDotProductAccumulatingSaturating32BitSignedAccelerated
is a boolean that will beVK_TRUE
if the support for 32-bit signed accumulating saturating dot product operations using theOpSDotAccSatKHR
SPIR-V instruction is accelerated as defined below. -
integerDotProductAccumulatingSaturating32BitMixedSignednessAccelerated
is a boolean that will beVK_TRUE
if the support for 32-bit mixed signedness accumulating saturating dot product operations using theOpSUDotAccSatKHR
SPIR-V instruction is accelerated as defined below. -
integerDotProductAccumulatingSaturating64BitUnsignedAccelerated
is a boolean that will beVK_TRUE
if the support for 64-bit unsigned accumulating saturating dot product operations using theOpUDotAccSatKHR
SPIR-V instruction is accelerated as defined below. -
integerDotProductAccumulatingSaturating64BitSignedAccelerated
is a boolean that will beVK_TRUE
if the support for 64-bit signed accumulating saturating dot product operations using theOpSDotAccSatKHR
SPIR-V instruction is accelerated as defined below. -
integerDotProductAccumulatingSaturating64BitMixedSignednessAccelerated
is a boolean that will beVK_TRUE
if the support for 64-bit mixed signedness accumulating saturating dot product operations using theOpSUDotAccSatKHR
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. |
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;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
maxWeightFilterPhases
is the maximum value that can be specified for VkImageViewSampleWeightCreateInfoQCOM::numPhases
. in weight image sampling operations. -
maxWeightFilterDimension
is a VkExtent2D describing the largest dimensions (width
andheight
) that can be specified for VkImageViewSampleWeightCreateInfoQCOM::filterSize
. -
maxBlockMatchRegion
is a VkExtent2D describing the largest dimensions (width
andheight
) that can be specified forblockSize
in block matching operations. -
maxBoxFilterBlockSize
is a VkExtent2D describing the maximum dimensions (width
andheight
) that can be specified forblocksize
in box filter sampling operations.
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.
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 eitherNULL
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.
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
, andz
members of a VkOffset3D parameter must always be zero. -
The
width
,height
, anddepth
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
, andz
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 elsex
+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 elsey
+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 elsez
+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 theVK_DEVICE_QUEUE_CREATE_PROTECTED_BIT
bit. (see Protected Memory). If the physical device supports theprotectedMemory
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
|
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 eitherNULL
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.
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;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
queueFamilyProperties
is a VkQueueFamilyProperties structure which is populated with the same values as in vkGetPhysicalDeviceQueueFamilyProperties.
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
isNULL
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 ofVK_MAX_GLOBAL_PRIORITY_SIZE_EXT
VkQueueGlobalPriorityEXT enums representing all supported global queue priorities in this queue family. The firstpriorityCount
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 |
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
isNULL
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.
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
isNULL
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.
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
isNULL
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.
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
isNULL
or a pointer to a structure extending this structure. -
queryResultStatusSupport
reportsVK_TRUE
if query typeVK_QUERY_TYPE_RESULT_STATUS_ONLY_KHR
and use ofVK_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.
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 eitherNULL
or a pointer to an array of VkPerformanceCounterKHR structures. -
pCounterDescriptions
is eitherNULL
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.
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
isNULL
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 sizeVK_UUID_SIZE
, containing 8-bit values that represent a universally unique identifier for the counter of the physical device.
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
isNULL
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 sizeVK_MAX_DESCRIPTION_SIZE
, containing a null-terminated UTF-8 string specifying the name of the counter. -
category
is an array of sizeVK_MAX_DESCRIPTION_SIZE
, containing a null-terminated UTF-8 string specifying the category of the counter. -
description
is an array of sizeVK_MAX_DESCRIPTION_SIZE
, containing a null-terminated UTF-8 string specifying the description of the counter.
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
|
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 eitherNULL
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.
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
isNULL
or a pointer to a structure extending this structure. -
physicalDeviceCount
is the number of physical devices in the group. -
physicalDevices
is an array ofVK_MAX_DEVICE_GROUP_SIZE
VkPhysicalDevice handles representing all physical devices in the group. The firstphysicalDeviceCount
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 thedeviceMask
member of the VkMemoryAllocateFlagsInfo. If this isVK_FALSE
, then all device memory allocations are made across all physical devices in the group. IfphysicalDeviceCount
is1
, thensubsetAllocation
must beVK_FALSE
.
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 tovkEnumeratePhysicalDevices
(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
.
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
isNULL
or a pointer to a structure extending this structure. -
flags
is reserved for future use. -
queueCreateInfoCount
is the unsigned integer size of thepQueueCreateInfos
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 ofenabledExtensionCount
null-terminated UTF-8 strings containing the names of extensions to enable for the created device. See the Extensions section for further details. -
pEnabledFeatures
isNULL
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.
// 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
isNULL
or a pointer to a structure extending this structure. -
physicalDeviceCount
is the number of elements in thepPhysicalDevices
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.
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
isNULL
or a pointer to a structure extending this structure. -
overallocationBehavior
is the desired overallocation behavior.
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
isNULL
or a pointer to a structure extending this structure. -
flags
is a bitmask of VkDeviceDiagnosticsConfigFlagBitsNV specifying additional parameters for configuring diagnostic tools.
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
isNULL
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. |
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);
-
pCallbackData
contains all the callback related data in the VkDeviceMemoryReportCallbackDataEXT structure. -
pUserData
is the user data provided when the VkDeviceDeviceMemoryReportCreateInfoEXT was created.
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
isNULL
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 thisVkDeviceMemoryReportCallbackDataEXT
structure. -
memoryObjectId
is the unique id for the underlying memory object as described below. -
size
is the size of the memory object in bytes. Iftype
isVK_DEVICE_MEMORY_REPORT_EVENT_TYPE_ALLOCATE_EXT
,VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_IMPORT_EXT
orVK_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. Iftype
isVK_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
orVK_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. Iftype
isVK_DEVICE_MEMORY_REPORT_EVENT_TYPE_ALLOCATE_EXT
,VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_FREE_EXT
,VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_IMPORT_EXT
orVK_DEVICE_MEMORY_REPORT_EVENT_TYPE_UNIMPORT_EXT
,objectHandle
is a valid Vulkan handle of the type associated withobjectType
as defined in theVkObjectType
and Vulkan Handle Relationship table. Otherwise,objectHandle
is undefined. -
heapIndex
describes which memory heap this device memory allocation is made from. Iftype
isVK_DEVICE_MEMORY_REPORT_EVENT_TYPE_ALLOCATE_EXT
orVK_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.
Note
This structure should only be considered valid during the lifetime of the triggered callback. For |
// 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
isNULL
or a pointer to a structure extending this structure. -
privateDataSlotRequestCount
is the amount of slots to reserve.
5.2.2. Device Use
The following is a high-level list of VkDevice
uses along with
references on where to find more information:
-
Creation of queues. See the Queues section below for further details.
-
Creation and tracking of various synchronization constructs. See Synchronization and Cache Control for further details.
-
Allocating, freeing, and managing memory. See Memory Allocation and Resource Creation for further details.
-
Creation and destruction of command buffers and command buffer pools. See Command Buffers for further details.
-
Creation, destruction, and management of graphics state. See Pipelines and Resource Descriptors, among others, for further details.
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
|
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
isNULL
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 thepQueueFamilyProperties
array that was returned byvkGetPhysicalDeviceQueueFamilyProperties
. -
queueCount
is an unsigned integer specifying the number of queues to create in the queue family indicated byqueueFamilyIndex
, and with the behavior specified byflags
. -
pQueuePriorities
is a pointer to an array ofqueueCount
normalized floating point values, specifying priorities of work that will be submitted to each created queue. See Queue Priority for more information.
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
isNULL
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
.
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.
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.
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
isNULL
or a pointer to a structure extending this structure. ThepNext
chain ofVkDeviceQueueInfo2
can be used to provide additional device queue parameters tovkGetDeviceQueue2
. -
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 For such divergent implementations, the maximum value of Such implementations will return 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
|
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:
-
Zero or more semaphores to wait on before execution of the rest of the batch.
-
If present, these describe a semaphore wait operation.
-
-
Zero or more work items to execute.
-
If present, these describe a queue operation matching the work described.
-
-
Zero or more semaphores to signal upon completion of the work items.
-
If present, these describe a semaphore signal operation.
-
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.
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.
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.
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
isNULL
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.
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, thenvkResetCommandBuffer
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. |
// 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.
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.
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 thecommandBufferCount
member ofpAllocateInfo
. 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 |
When command buffers are first allocated, they are in the initial state.
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
isNULL
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.
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);
-
commandBuffer
is the command buffer to reset. The command buffer can be in any state other than pending, and is moved into the initial state. -
flags
is a bitmask of VkCommandBufferResetFlagBits controlling the reset operation.
Any primary command buffer that is in the recording or executable state and has commandBuffer
recorded into
it, becomes invalid.
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 thepCommandBuffers
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.
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.
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
isNULL
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 aVkCommandBufferInheritanceInfo
structure, used ifcommandBuffer
is a secondary command buffer. If this is a primary command buffer, then this value is ignored.
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
isNULL
or a pointer to a structure extending this structure. -
renderPass
is a VkRenderPass object defining which render passes theVkCommandBuffer
will be compatible with and can be executed within. -
subpass
is the index of the subpass within the render pass instance that theVkCommandBuffer
will be executed within. -
framebuffer
can refer to the VkFramebuffer object that theVkCommandBuffer
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.NoteSpecifying 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 isVK_TRUE
, then this command buffer can be executed whether the primary command buffer has an occlusion query active or not. If this isVK_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 theVK_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 theVK_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.
Note
On some implementations, not using the
|
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
isNULL
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 isVK_TRUE
, then this command buffer can be executed whether the primary command buffer has active conditional rendering or not. If this isVK_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
.
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
isNULL
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.
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
isNULL
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. WhenviewportScissor2D
isVK_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 ofpViewportDepths
, 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 |
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
isNULL
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.
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
isNULL
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.
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
|
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 |
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 thepSubmits
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. Iffence
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.
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
isNULL
or a pointer to a structure extending this structure. -
flags
is a bitmask of VkSubmitFlagBits. -
waitSemaphoreInfoCount
is the number of elements inpWaitSemaphoreInfos
. -
pWaitSemaphoreInfos
is a pointer to an array of VkSemaphoreSubmitInfo structures defining semaphore wait operations. -
commandBufferInfoCount
is the number of elements inpCommandBufferInfos
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 inpSignalSemaphoreInfos
. -
pSignalSemaphoreInfos
is a pointer to an array of VkSemaphoreSubmitInfo describing semaphore signal operations.
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
isNULL
or a pointer to a structure extending this structure. -
semaphore
is a VkSemaphore affected by this operation. -
value
is either the value used to signalsemaphore
or the value waited on bysemaphore
, ifsemaphore
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.
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
isNULL
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. AdeviceMask
of0
is equivalent to setting all bits corresponding to valid devices in the group to1
.
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 thepSubmits
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. Iffence
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.
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
isNULL
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 inpCommandBuffers
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.
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
isNULL
or a pointer to a structure extending this structure. -
waitSemaphoreValueCount
is the number of semaphore wait values specified inpWaitSemaphoreValues
. -
pWaitSemaphoreValues
is a pointer to an array ofwaitSemaphoreValueCount
values for the corresponding semaphores in VkSubmitInfo::pWaitSemaphores
to wait for. -
signalSemaphoreValueCount
is the number of semaphore signal values specified inpSignalSemaphoreValues
. -
pSignalSemaphoreValues
is a pointer to an arraysignalSemaphoreValueCount
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.
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
isNULL
or a pointer to a structure extending this structure. -
waitSemaphoreValuesCount
is the number of semaphore wait values specified inpWaitSemaphoreValues
. -
pWaitSemaphoreValues
is a pointer to an array ofwaitSemaphoreValuesCount
values for the corresponding semaphores in VkSubmitInfo::pWaitSemaphores
to wait for. -
signalSemaphoreValuesCount
is the number of semaphore signal values specified inpSignalSemaphoreValues
. -
pSignalSemaphoreValues
is a pointer to an array ofsignalSemaphoreValuesCount
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
|
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
isNULL
or a pointer to a structure extending this structure. -
acquireCount
is the number of entries in thepAcquireSyncs
,pAcquireKeys
, andpAcquireTimeouts
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 inpAcquireSyncs
. -
pAcquireTimeouts
is a pointer to an array of timeout values, in millisecond units, for each acquire specified inpAcquireKeys
. -
releaseCount
is the number of entries in thepReleaseSyncs
andpReleaseKeys
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 inpReleaseSyncs
.
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 thepAcquireSyncs
,pAcquireKeys
, andpAcquireTimeoutMilliseconds
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 inpAcquireSyncs
. -
pAcquireTimeoutMilliseconds
is a pointer to an array of timeout values, in millisecond units, for each acquire specified inpAcquireKeys
. -
releaseCount
is the number of entries in thepReleaseSyncs
andpReleaseKeys
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 inpReleaseSyncs
.
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. IfprotectedSubmit
isVK_TRUE
, the batch is protected. IfprotectedSubmit
isVK_FALSE
, the batch is unprotected. If theVkSubmitInfo
::pNext
chain does not include this structure, the batch is unprotected.
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
isNULL
or a pointer to a structure extending this structure. -
waitSemaphoreCount
is the number of elements in thepWaitSemaphoreDeviceIndices
array. -
pWaitSemaphoreDeviceIndices
is a pointer to an array ofwaitSemaphoreCount
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 thepCommandBufferDeviceMasks
array. -
pCommandBufferDeviceMasks
is a pointer to an array ofcommandBufferCount
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 thepSignalSemaphoreDeviceIndices
array. -
pSignalSemaphoreDeviceIndices
is a pointer to an array ofsignalSemaphoreCount
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.
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
isNULL
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.
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 thepCommandBuffers
array. -
pCommandBuffers
is a pointer to an array ofcommandBufferCount
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.
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
isNULL
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.
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.
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 If the contents of an attachment are not needed after a render pass
completes, then applications should use
|
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 toVK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT
with VkAccessFlags2 set to0
when specified in the second synchronization scope, but equivalent toVK_PIPELINE_STAGE_2_NONE
in the first scope. -
VK_PIPELINE_STAGE_2_BOTTOM_OF_PIPE_BIT
is equivalent toVK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT
with VkAccessFlags2 set to0
when specified in the first synchronization scope, but equivalent toVK_PIPELINE_STAGE_2_NONE
in the second scope.
Note
The |
Note
The |
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 whereVkDrawIndirect*
/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:-
All copy commands, including vkCmdCopyQueryPoolResults
-
All clear commands, with the exception of vkCmdClearAttachments
-
-
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 toVK_PIPELINE_STAGE_ALL_COMMANDS_BIT
with VkAccessFlags set to0
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 toVK_PIPELINE_STAGE_ALL_COMMANDS_BIT
with VkAccessFlags set to0
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.
Pipeline stage flag | Required queue capability flag |
---|---|
|
None required |
|
None required |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
None required |
|
None required |
|
|
|
None required |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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 allREAD
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 allWRITE
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 theVK_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 theVK_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 theVK_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 theVK_PIPELINE_STAGE_2_SUBPASS_SHADER_BIT_HUAWEI
orVK_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 toVK_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 theVK_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 theVK_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 theVK_PIPELINE_STAGE_2_EARLY_FRAGMENT_TESTS_BIT
orVK_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 theVK_PIPELINE_STAGE_2_EARLY_FRAGMENT_TESTS_BIT
orVK_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 theVK_PIPELINE_STAGE_2_COPY_BIT
,VK_PIPELINE_STAGE_2_BLIT_BIT
, orVK_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 theVK_PIPELINE_STAGE_2_COPY_BIT
,VK_PIPELINE_STAGE_2_BLIT_BIT
,VK_PIPELINE_STAGE_2_CLEAR_BIT
, orVK_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 theVK_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 theVK_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 theVK_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 theVK_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 theVK_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 theVK_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 theVK_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 theVK_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 theVK_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 theVK_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 theVK_PIPELINE_STAGE_2_RAY_TRACING_SHADER_BIT_KHR
pipeline stage orVK_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 theVK_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 theVK_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 theVK_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 theVK_PIPELINE_STAGE_2_SHADING_RATE_IMAGE_BIT_NV
pipeline stage. It is equivalent toVK_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 theVK_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 theVK_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 theVK_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 theVK_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 theVK_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 theVK_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 theVK_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 theVK_PIPELINE_STAGE_2_MICROMAP_BUILD_BIT_EXT
andVK_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, |
Note
The |
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 allREAD
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 allWRITE
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 theVK_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 theVK_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 theVK_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 theVK_PIPELINE_STAGE_2_SUBPASS_SHADER_BIT_HUAWEI
orVK_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 theVK_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 theVK_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 theVK_PIPELINE_STAGE_EARLY_FRAGMENT_TESTS_BIT
orVK_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 theVK_PIPELINE_STAGE_EARLY_FRAGMENT_TESTS_BIT
orVK_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 theVK_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 theVK_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 theVK_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 theVK_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 theVK_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 theVK_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 whenvkCmdBeginTransformFeedbackEXT
executes. Such access occurs in theVK_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 whenvkCmdEndTransformFeedbackEXT
executes. Such access occurs in theVK_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 theVK_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 theVK_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 theVK_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 theVK_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 theVK_PIPELINE_STAGE_RAY_TRACING_SHADER_BIT_KHR
pipeline stage orVK_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 theVK_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 theVK_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 theVK_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 theVK_PIPELINE_STAGE_SHADING_RATE_IMAGE_BIT_NV
pipeline stage. It is equivalent toVK_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.
Access flag | Supported pipeline stages |
---|---|
|
Any |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Any |
|
Any |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
// 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
|
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:
-
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.
-
The order in which VkSubmitInfo structures are specified in the
pSubmits
parameter of vkQueueSubmit, or in which VkSubmitInfo2 structures are specified in thepSubmits
parameter of vkQueueSubmit2, from lowest index to highest. -
The order in which command buffers are specified in the
pCommandBuffers
member of VkSubmitInfo or VkSubmitInfo2 from lowest index to highest. -
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:
-
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.
-
The order in which VkSubmitInfo structures are specified in the
pSubmits
parameter of vkQueueSubmit, or in which VkSubmitInfo2 structures are specified in thepSubmits
parameter of vkQueueSubmit2, from lowest index to highest. -
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 |
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.
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
isNULL
or a pointer to a structure extending this structure. -
flags
is a bitmask of VkFenceCreateFlagBits specifying the initial state and behavior of the fence.
// 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
isNULL
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.
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
isNULL
or a pointer to a structure extending this structure. -
pAttributes
is a pointer to a WindowsSECURITY_ATTRIBUTES
structure specifying security attributes of the handle. -
dwAccess
is aDWORD
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
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.
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
isNULL
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.
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 |
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.
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
isNULL
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.
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.
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:
Status | Meaning |
---|---|
|
The fence specified by |
|
The fence specified by |
|
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
.
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.
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 offenceCount
fence handles. -
waitAll
is the condition that must be satisfied to successfully unblock the wait. IfwaitAll
isVK_TRUE
, then the condition is that all fences inpFences
are signaled. Otherwise, the condition is that at least one fence inpFences
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 |
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.
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
isNULL
or a pointer to a structure extending this structure. -
device
is a VkDeviceEventTypeEXT value specifying when the fence will be signaled.
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 withdisplay
-
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.
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
isNULL
or a pointer to a structure extending this structure. -
displayEvent
is a VkDisplayEventTypeEXT specifying when the fence will be signaled.
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
|
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.
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
isNULL
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 ofhandle
. -
handle
isNULL
or the external handle to import. -
name
isNULL
or a null-terminated UTF-16 string naming the underlying synchronization primitive to import.
The handle types supported by handleType
are:
Handle Type | Transference | Permanence Supported |
---|---|---|
|
Reference |
Temporary,Permanent |
|
Reference |
Temporary,Permanent |
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.
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
isNULL
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 offd
. -
fd
is the external handle to import.
The handle types supported by handleType
are:
Handle Type | Transference | Permanence Supported |
---|---|---|
|
Reference |
Temporary,Permanent |
|
Copy |
Temporary |
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 |
Bits which can be set in
-
VkImportFenceFdInfoKHR::
flags
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 ofhandleType
.
// 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.
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
isNULL
or a pointer to a structure extending this structure. -
flags
is reserved for future use.
// 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
isNULL
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 ifsemaphoreType
isVK_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
.
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 theinitialValue
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
isNULL
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.
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
isNULL
or a pointer to a structure extending this structure. -
pAttributes
is a pointer to a WindowsSECURITY_ATTRIBUTES
structure specifying security attributes of the handle. -
dwAccess
is aDWORD
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
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.
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
isNULL
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.
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
isNULL
or a pointer to a structure extending this structure. -
pQueriedLowLatencyData
is used for NVIDIA Reflex Support.
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 |
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.
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
isNULL
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.
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.
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
isNULL
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.
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.
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 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
Alternatively, 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
|
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. |
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
.
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
isNULL
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 ofsemaphoreCount
semaphore handles to wait on. -
pValues
is a pointer to an array ofsemaphoreCount
timeline semaphore values.
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 inVkSemaphoreWaitInfo
::pSemaphores
has reached the value specified by the corresponding element ofVkSemaphoreWaitInfo
::pValues
. IfVK_SEMAPHORE_WAIT_ANY_BIT
is not set, the semaphore wait condition is that all of the semaphores inVkSemaphoreWaitInfo
::pSemaphores
have reached the value specified by the corresponding element ofVkSemaphoreWaitInfo
::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.
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
isNULL
or a pointer to a structure extending this structure. -
semaphore
is the handle of the semaphore to signal. -
value
is the value to signal.
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
|
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.
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
isNULL
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 ofhandle
. -
handle
isNULL
or the external handle to import. -
name
isNULL
or a null-terminated UTF-16 string naming the underlying synchronization primitive to import.
The handle types supported by handleType
are:
Handle Type | Transference | Permanence Supported |
---|---|---|
|
Reference |
Temporary,Permanent |
|
Reference |
Temporary,Permanent |
|
Reference |
Temporary,Permanent |
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.
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
isNULL
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 offd
. -
fd
is the external handle to import.
The handle types supported by handleType
are:
Handle Type | Transference | Permanence Supported |
---|---|---|
|
Reference |
Temporary,Permanent |
|
Copy |
Temporary |
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 |
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.
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
isNULL
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 ofzirconHandle
. -
zirconHandle
is the external handle to import.
The handle types supported by handleType
are:
Handle Type | Transference | Permanence Supported |
---|---|---|
|
Reference |
Temporary,Permanent |
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 ofhandleType
.
// 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.
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
isNULL
or a pointer to a structure extending this structure. -
flags
is a bitmask of VkEventCreateFlagBits defining additional creation parameters.
// 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.
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:
Status | Meaning |
---|---|
|
The event specified by |
|
The event specified by |
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.
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. |
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.
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.
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
isNULL
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 thepMemoryBarriers
array. -
pMemoryBarriers
is a pointer to an array of VkMemoryBarrier2 structures defining memory dependencies between any memory accesses. -
bufferMemoryBarrierCount
is the length of thepBufferMemoryBarriers
array. -
pBufferMemoryBarriers
is a pointer to an array of VkBufferMemoryBarrier2 structures defining memory dependencies between buffer ranges. -
imageMemoryBarrierCount
is the length of thepImageMemoryBarriers
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.
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.
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.
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 theevent
is unsignaled.
vkCmdResetEvent
behaves identically to vkCmdResetEvent2.
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 thepEvents
array. -
pEvents
is a pointer to an array ofeventCount
events to wait on. -
pDependencyInfos
is a pointer to an array ofeventCount
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 ofpDependencyInfos
at index i ; or -
The event was created without
VK_EVENT_CREATE_DEVICE_ONLY_BIT
, and the first synchronization scope defined by the element ofpDependencyInfos
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 |
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 thepEvents
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 thepMemoryBarriers
array. -
pMemoryBarriers
is a pointer to an array of VkMemoryBarrier structures. -
bufferMemoryBarrierCount
is the length of thepBufferMemoryBarriers
array. -
pBufferMemoryBarriers
is a pointer to an array of VkBufferMemoryBarrier structures. -
imageMemoryBarrierCount
is the length of thepImageMemoryBarriers
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.
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
.
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 thepMemoryBarriers
array. -
pMemoryBarriers
is a pointer to an array of VkMemoryBarrier structures. -
bufferMemoryBarrierCount
is the length of thepBufferMemoryBarriers
array. -
pBufferMemoryBarriers
is a pointer to an array of VkBufferMemoryBarrier structures. -
imageMemoryBarrierCount
is the length of thepImageMemoryBarriers
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.
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 theVK_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;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
srcStageMask
is a VkPipelineStageFlags2 mask of pipeline stages to be included in the first synchronization scope. -
srcAccessMask
is a VkAccessFlags2 mask of access flags to be included in the first access scope. -
dstStageMask
is a VkPipelineStageFlags2 mask of pipeline stages to be included in the second synchronization scope. -
dstAccessMask
is a VkAccessFlags2 mask of access flags to be included in the second access scope.
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
.
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;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
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.
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
.
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;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
srcStageMask
is a VkPipelineStageFlags2 mask of pipeline stages to be included in the first synchronization scope. -
srcAccessMask
is a VkAccessFlags2 mask of access flags to be included in the first access scope. -
dstStageMask
is a VkPipelineStageFlags2 mask of pipeline stages to be included in the second synchronization scope. -
dstAccessMask
is a VkAccessFlags2 mask of access flags to be included in the second access scope. -
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 forbuffer
; 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 forbuffer
, orVK_WHOLE_SIZE
to use the range fromoffset
to the end of the buffer.
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.
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
isNULL
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 forbuffer
; 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 forbuffer
, orVK_WHOLE_SIZE
to use the range fromoffset
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 |
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
.
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;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
srcStageMask
is a VkPipelineStageFlags2 mask of pipeline stages to be included in the first synchronization scope. -
srcAccessMask
is a VkAccessFlags2 mask of access flags to be included in the first access scope. -
dstStageMask
is a VkPipelineStageFlags2 mask of pipeline stages to be included in the second synchronization scope. -
dstAccessMask
is a VkAccessFlags2 mask of access flags to be included in the second access scope. -
oldLayout
is the old layout in an image layout transition. -
newLayout
is the new layout in an image layout transition. -
srcQueueFamilyIndex
is the source queue family for a queue family ownership transfer. -
dstQueueFamilyIndex
is the destination queue family for a queue family ownership transfer. -
image
is a handle to the image affected by this barrier. -
subresourceRange
describes the image subresource range withinimage
that is affected by this barrier.
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
.
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;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
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. -
oldLayout
is the old layout in an image layout transition. -
newLayout
is the new layout in an image layout transition. -
srcQueueFamilyIndex
is the source queue family for a queue family ownership transfer. -
dstQueueFamilyIndex
is the destination queue family for a queue family ownership transfer. -
image
is a handle to the image affected by this barrier. -
subresourceRange
describes the image subresource range withinimage
that is affected by this barrier.
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 |
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
.
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
|
A queue family ownership transfer consists of two distinct parts:
-
Release exclusive ownership from the source queue family
-
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
.
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
.
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 |
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 oftimestampCount
VkCalibratedTimestampInfoEXT structures, describing the time domains the calibrated timestamps should be captured from. -
pTimestamps
is a pointer to an array oftimestampCount
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
|
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.
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
isNULL
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.
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 thetimestampPeriod
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 |
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
isNULL
or a pointer to a structure extending this structure. -
swapchain
is the swapchain to retrieve theVK_TIME_DOMAIN_SWAPCHAIN_LOCAL_EXT
timestamp from.
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.
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
isNULL
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 whenviewMask
is0
. -
viewMask
is the view mask indicating the indices of attachment layers that will be rendered when it is not0
. -
colorAttachmentCount
is the number of elements inpColorAttachments
. -
pColorAttachments
is a pointer to an array ofcolorAttachmentCount
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.
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
isNULL
or a pointer to a structure extending this structure. -
imageView
is the image view that will be used for rendering. -
imageLayout
is the layout thatimageView
will be in during rendering. -
resolveMode
is a VkResolveModeFlagBits value defining how multisampled data written toimageView
will be resolved. -
resolveImageView
is an image view used to write resolved multisample data at the end of rendering. -
resolveImageLayout
is the layout thatresolveImageView
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 clearimageView
whenloadOp
isVK_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.
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
isNULL
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 thatimageView
will be in during rendering. -
shadingRateAttachmentTexelSize
specifies the number of pixels corresponding to each texel inimageView
.
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.
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
isNULL
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 thatimageView
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.
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.
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
isNULL
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 |
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.
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.
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
isNULL
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 ofattachmentCount
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 ofsubpassCount
VkSubpassDescription structures describing each subpass. -
dependencyCount
is the number of memory dependencies between pairs of subpasses. -
pDependencies
is a pointer to an array ofdependencyCount
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. |
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
isNULL
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 ofsubpassCount
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. IfsubpassCount
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 ofdependencyCount
view offsets, one for each dependency. IfdependencyCount
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 ofcorrelationMaskCount
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.
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
isNULL
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.
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
isNULL
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 duringVK_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
.
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 |
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 |
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
isNULL
or a pointer to a structure extending this structure. -
aspectReferenceCount
is the number of elements in thepAspectReferences
array. -
pAspectReferences
is a pointer to an array ofaspectReferenceCount
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.
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 thepSubpasses
array of the parentVkRenderPassCreateInfo
structure. -
inputAttachmentIndex
is an index into thepInputAttachments
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]
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 ofcolorAttachmentCount
VkAttachmentReference structures defining the color attachments for this subpass and their layouts. -
pResolveAttachments
isNULL
or a pointer to an array ofcolorAttachmentCount
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 ofpreserveAttachmentCount
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.
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 withVK_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 withVK_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 withVK_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
, orVK_ATTACHMENT_UNUSED
to signify that this attachment is not used. -
layout
is a VkImageLayout value specifying the layout the attachment uses during the subpass.
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;
-
srcSubpass
is the subpass index of the first subpass in the dependency, orVK_SUBPASS_EXTERNAL
. -
dstSubpass
is the subpass index of the second subpass in the dependency, orVK_SUBPASS_EXTERNAL
. -
srcStageMask
is a bitmask of VkPipelineStageFlagBits specifying the source stage mask. -
dstStageMask
is a bitmask of VkPipelineStageFlagBits specifying the destination stage mask -
srcAccessMask
is a bitmask of VkAccessFlagBits specifying a source access mask. -
dstAccessMask
is a bitmask of VkAccessFlagBits specifying a destination access mask. -
dependencyFlags
is a bitmask of VkDependencyFlagBits.
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 For attachments however, subpass dependencies work more like a
VkImageMemoryBarrier defined similarly to the VkMemoryBarrier
above, the queue family indices set to
|
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.
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
isNULL
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 ofattachmentCount
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 ofsubpassCount
VkSubpassDescription2 structures describing each subpass. -
dependencyCount
is the number of dependencies between pairs of subpasses. -
pDependencies
is a pointer to an array ofdependencyCount
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.
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
isNULL
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.
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
isNULL
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.
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
isNULL
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 ofcolorAttachmentCount
VkAttachmentReference2 structures defining the color attachments for this subpass and their layouts. -
pResolveAttachments
isNULL
or a pointer to an array ofcolorAttachmentCount
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 ofpreserveAttachmentCount
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.
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
isNULL
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
isNULL
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.
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
isNULL
or a pointer to a structure extending this structure. -
pFragmentShadingRateAttachment
isNULL
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 inpFragmentShadingRateAttachment
.
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.
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
isNULL
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.
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 toVK_ATTACHMENT_LOAD_OP_LOAD
, samples of the implicit image are initialized by replicating the value from the corresponding pixel in the attachment. -
If
storeOp
orstencilStoreOp
is equal toVK_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
isNULL
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
, orVK_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.
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
isNULL
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.
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;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
srcSubpass
is the subpass index of the first subpass in the dependency, orVK_SUBPASS_EXTERNAL
. -
dstSubpass
is the subpass index of the second subpass in the dependency, orVK_SUBPASS_EXTERNAL
. -
srcStageMask
is a bitmask of VkPipelineStageFlagBits specifying the source stage mask. -
dstStageMask
is a bitmask of VkPipelineStageFlagBits specifying the destination stage mask -
srcAccessMask
is a bitmask of VkAccessFlagBits specifying a source access mask. -
dstAccessMask
is a bitmask of VkAccessFlagBits specifying a destination access mask. -
dependencyFlags
is a bitmask of VkDependencyFlagBits. -
viewOffset
controls which views in the source subpass the views in the destination subpass depend on.
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.
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.
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.
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
isNULL
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. Ifflags
includesVK_FRAMEBUFFER_CREATE_IMAGELESS_BIT
, this parameter is ignored. -
width
,height
andlayers
define the dimensions of the framebuffer. If the render pass uses multiview, thenlayers
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
.
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
isNULL
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.
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
isNULL
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 thepViewFormats
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.
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.
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 |
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 typeVK_ACCESS_DEPTH_STENCIL_ATTACHMENT_READ_BIT
. For attachments with a color format, this uses the access typeVK_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 typeVK_ACCESS_DEPTH_STENCIL_ATTACHMENT_WRITE_BIT
. For attachments with a color format, this uses the access typeVK_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 typeVK_ACCESS_DEPTH_STENCIL_ATTACHMENT_WRITE_BIT
. For attachments with a color format, this uses the access typeVK_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 |
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 typeVK_ACCESS_DEPTH_STENCIL_ATTACHMENT_WRITE_BIT
. For attachments with a color format, this uses the access typeVK_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 typeVK_ACCESS_DEPTH_STENCIL_ATTACHMENT_WRITE_BIT
. For attachments with a color format, this uses the access typeVK_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 toVK_ATTACHMENT_STORE_OP_DONT_CARE
and with matching access semantics.
Note
|
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.
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.
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
isNULL
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 inpClearValues
. -
pClearValues
is a pointer to an array ofclearValueCount
VkClearValue structures containing clear values for each attachment, if the attachment uses aloadOp
value ofVK_ATTACHMENT_LOAD_OP_CLEAR
or if the attachment has a depth/stencil format and uses astencilLoadOp
value ofVK_ATTACHMENT_LOAD_OP_CLEAR
. The array is indexed by attachment number. Only elements corresponding to cleared attachments are used. Other elements ofpClearValues
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. |
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
isNULL
or a pointer to a structure extending this structure. -
attachmentInitialSampleLocationsCount
is the number of elements in thepAttachmentInitialSampleLocations
array. -
pAttachmentInitialSampleLocations
is a pointer to an array ofattachmentInitialSampleLocationsCount
VkAttachmentSampleLocationsEXT structures specifying the attachment indices and their corresponding sample location state. Each element ofpAttachmentInitialSampleLocations
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 thepPostSubpassSampleLocations
array. -
pPostSubpassSampleLocations
is a pointer to an array ofpostSubpassSampleLocationsCount
VkSubpassSampleLocationsEXT structures specifying the subpass indices and their corresponding sample location state. Each element ofpPostSubpassSampleLocations
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
isVK_FALSE
, each element ofpPostSubpassSampleLocations
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. IfvariableSampleLocations
isVK_TRUE
, the sample locations used for rasterization do not depend onpPostSubpassSampleLocations
.
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.
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 insubpassIndex
.
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.
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
isNULL
or a pointer to a structure extending this structure. -
transform
is a VkSurfaceTransformFlagBitsKHR value describing the transform to be applied to rasterization.
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
isNULL
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.
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
isNULL
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 thepDeviceRenderAreas
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.
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
isNULL
or a pointer to a structure extending this structure. -
attachmentCount
is the number of attachments. -
pAttachments
is a pointer to an array ofVkImageView
handles, each of which will be used as the corresponding attachment in the render pass instance.
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
isNULL
or a pointer to a structure extending this structure. -
perViewRenderAreaCount
is the number of elements in thepPerViewRenderAreas
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.
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 inrenderArea
is a multiple of thewidth
member of the returned VkExtent2D (the horizontal granularity). -
the
offset.y
member inrenderArea
is a multiple of theheight
member of the returned VkExtent2D (the vertical granularity). -
either the
extent.width
member inrenderArea
is a multiple of the horizontal granularity oroffset.x
+extent.width
is equal to thewidth
of theframebuffer
in the VkRenderPassBeginInfo. -
either the
extent.height
member inrenderArea
is a multiple of the vertical granularity oroffset.y
+extent.height
is equal to theheight
of theframebuffer
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.
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.
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.
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.
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.
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
isNULL
or a pointer to a structure extending this structure.
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
isNULL
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.
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
isNULL
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.
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;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
pRenderPassFeedback
is a pointer to a VkRenderPassCreationFeedbackInfoEXT structure in which feedback is returned.
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;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
pSubpassFeedback
is a pointer to a VkRenderPassSubpassFeedbackInfoEXT structure in which feedback is returned.
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 aVkSubpassMergeStatusEXT
value specifying information about whether the subpass is merged with previous subpass and the reason why it is not merged. -
description
is an array ofVK_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.
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
isNULL
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 bypCode
. -
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 bypCode
.
// 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
isNULL
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).
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.
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.
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);
-
device
is the logical device that can create a VkShaderModule frompCreateInfo
. -
pCreateInfo
is a pointer to a VkShaderModuleCreateInfo structure. -
pIdentifier
is a pointer to the returned VkShaderModuleIdentifierEXT.
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.
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
isNULL
or a pointer to a structure extending this structure. -
identifierSize
is the size, in bytes, of valid data returned inidentifier
. -
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.
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 |
---|---|---|
|
|
all drawing commands |
|
|
|
|
|
|
|
|
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 |
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.
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.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.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.21. Callable Shaders
Callable shaders can access a callable payload that works similarly to ray payloads to do subroutine work.
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 |
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:
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
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.
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 |
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
orSampleInterlockUnorderedEXT
execution modes are used, only invocations with identical framebuffer locations (x,y,layer,sample) are included. -
If the
PixelInterlockOrderedEXT
orPixelInterlockUnorderedEXT
execution modes are used, fragments with different sample ids are also included. -
If the
ShadingRateInterlockOrderedEXT
orShadingRateInterlockUnorderedEXT
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:
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 |
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 |
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 eitherNULL
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.
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
isNULL
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
.
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-VDevice
scope. -
VK_SCOPE_WORKGROUP_KHR
corresponds to SPIR-VWorkgroup
scope. -
VK_SCOPE_SUBGROUP_KHR
corresponds to SPIR-VSubgroup
scope. -
VK_SCOPE_QUEUE_FAMILY_KHR
corresponds to SPIR-VQueueFamily
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-VOpTypeFloat
16. -
VK_COMPONENT_TYPE_FLOAT32_KHR
corresponds to SPIR-VOpTypeFloat
32. -
VK_COMPONENT_TYPE_FLOAT64_KHR
corresponds to SPIR-VOpTypeFloat
64. -
VK_COMPONENT_TYPE_SINT8_KHR
corresponds to SPIR-VOpTypeInt
8 1. -
VK_COMPONENT_TYPE_SINT16_KHR
corresponds to SPIR-VOpTypeInt
16 1. -
VK_COMPONENT_TYPE_SINT32_KHR
corresponds to SPIR-VOpTypeInt
32 1. -
VK_COMPONENT_TYPE_SINT64_KHR
corresponds to SPIR-VOpTypeInt
64 1. -
VK_COMPONENT_TYPE_UINT8_KHR
corresponds to SPIR-VOpTypeInt
8 0. -
VK_COMPONENT_TYPE_UINT16_KHR
corresponds to SPIR-VOpTypeInt
16 0. -
VK_COMPONENT_TYPE_UINT32_KHR
corresponds to SPIR-VOpTypeInt
32 0. -
VK_COMPONENT_TYPE_UINT64_KHR
corresponds to SPIR-VOpTypeInt
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 |
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 |
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
isNULL
or a pointer to a structure extending this structure. -
flags
is reserved for future use. -
initialDataSize
is the number of bytes inpInitialData
. IfinitialDataSize
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. IfinitialDataSize
is zero,pInitialData
is ignored.
// 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 thepSrcCaches
array. -
pSrcCaches
is a pointer to an array of validation cache handles, which will be merged intodstCache
. The previous contents ofdstCache
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. |
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 eitherNULL
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:
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 |
|
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
.
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.
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.
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 thepCreateInfos
andpPipelines
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-noteTODO (Jon) - Should we say something like “the i’th element of the
pPipelines
array is created based on the corresponding element of thepCreateInfos
array”? Also for vkCreateGraphicsPipelines below.
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
isNULL
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 thepCreateInfos
parameter to use as a pipeline to derive from.
The parameters basePipelineHandle
and basePipelineIndex
are
described in more detail in Pipeline
Derivatives.
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
isNULL
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, orNULL
.
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.
// 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 theSubgroupSize
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 |
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
|
// 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
isNULL
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.
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
isNULL
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.
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.
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
isNULL
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 byVkPipelineRobustnessCreateInfoEXT
applies to all accesses through this pipeline -
VkPipelineShaderStageCreateInfo
:
The robustness behavior described byVkPipelineRobustnessCreateInfoEXT
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
.
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 therobustBufferAccess
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 therobustBufferAccess2
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 therobustImageAccess
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 therobustImageAccess2
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
isNULL
or a pointer to a structure extending this structure. -
identifierSize
is the size, in bytes, of the buffer pointed to bypIdentifier
. -
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.
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 thepCreateInfos
andpPipelines
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.
Note
An implicit cache may be provided by the implementation or a layer.
For this reason, it is still valid to set
|
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
isNULL
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 thepStages
array. -
pStages
is a pointer to an array ofstageCount
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 beNULL
if the pipeline is created with theVK_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 theVK_EXT_extended_dynamic_state3
extension is enabled, it can beNULL
if the pipeline is created with bothVK_DYNAMIC_STATE_PRIMITIVE_RESTART_ENABLE
, andVK_DYNAMIC_STATE_PRIMITIVE_TOPOLOGY
dynamic states set anddynamicPrimitiveTopologyUnrestricted
isVK_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 beNULL
if the pipeline is created with theVK_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 theVK_EXT_extended_dynamic_state3
extension is enabled, it can beNULL
if the pipeline is created with bothVK_DYNAMIC_STATE_VIEWPORT_WITH_COUNT
, andVK_DYNAMIC_STATE_SCISSOR_WITH_COUNT
dynamic states set. -
pRasterizationState
is a pointer to a VkPipelineRasterizationStateCreateInfo structure defining rasterization state. If theVK_EXT_extended_dynamic_state3
extension is enabled, it can beNULL
if the pipeline is created with all ofVK_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
, andVK_DYNAMIC_STATE_LINE_WIDTH
dynamic states set. -
pMultisampleState
is a pointer to a VkPipelineMultisampleStateCreateInfo structure defining multisample state used when rasterization is enabled. If theVK_EXT_extended_dynamic_state3
extension is enabled, it can beNULL
if the pipeline is created with all ofVK_DYNAMIC_STATE_RASTERIZATION_SAMPLES_EXT
,VK_DYNAMIC_STATE_SAMPLE_MASK_EXT
, andVK_DYNAMIC_STATE_ALPHA_TO_COVERAGE_ENABLE_EXT
dynamic states set, and either alphaToOne is disabled on the device orVK_DYNAMIC_STATE_ALPHA_TO_ONE_ENABLE_EXT
is set, in which case VkPipelineMultisampleStateCreateInfo::sampleShadingEnable
is assumed to beVK_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 theVK_EXT_extended_dynamic_state3
extension is enabled, it can beNULL
if the pipeline is created with all ofVK_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
, andVK_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 theVK_EXT_extended_dynamic_state3
extension is enabled, it can beNULL
if the pipeline is created with all ofVK_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
, andVK_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 beNULL
, 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 thepCreateInfos
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 |
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 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 is defined by:
-
VkPipelineShaderStageCreateInfo entries for:
-
Vertex shaders
-
Tessellation control shaders
-
Tessellation evaluation shaders
-
Geometry shaders
-
Task shaders
-
Mesh shaders
-
-
Within the VkPipelineLayout, all descriptor sets with pre-rasterization shader bindings if
VK_PIPELINE_LAYOUT_CREATE_INDEPENDENT_SETS_BIT_EXT
was specified.-
If
VK_PIPELINE_LAYOUT_CREATE_INDEPENDENT_SETS_BIT_EXT
was not specified, the full pipeline layout must be specified.
-
-
VkRenderPass and
subpass
parameter -
The
viewMask
parameter of VkPipelineRenderingCreateInfo (formats are ignored)
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 is defined by:
-
A VkPipelineShaderStageCreateInfo entry for the fragment shader
-
Within the VkPipelineLayout, all descriptor sets with fragment shader bindings if
VK_PIPELINE_LAYOUT_CREATE_INDEPENDENT_SETS_BIT_EXT
was specified.-
If
VK_PIPELINE_LAYOUT_CREATE_INDEPENDENT_SETS_BIT_EXT
was not specified, the full pipeline layout must be specified.
-
-
VkPipelineMultisampleStateCreateInfo if sample shading is enabled or
renderpass
is not VK_NULL_HANDLE -
VkRenderPass and
subpass
parameter -
The
viewMask
parameter of VkPipelineRenderingCreateInfo (formats are ignored) -
Inclusion/omission of the
VK_PIPELINE_RASTERIZATION_STATE_CREATE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR
flag -
Inclusion/omission of the
VK_PIPELINE_RASTERIZATION_STATE_CREATE_FRAGMENT_DENSITY_MAP_ATTACHMENT_BIT_EXT
flag
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 is defined by:
-
VkRenderPass and
subpass
parameter -
Inclusion/omission of the
VK_PIPELINE_CREATE_COLOR_ATTACHMENT_FEEDBACK_LOOP_BIT_EXT
andVK_PIPELINE_CREATE_DEPTH_STENCIL_ATTACHMENT_FEEDBACK_LOOP_BIT_EXT
flags
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 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.
A complete graphics pipeline always includes pre-rasterization shader state, with other subsets included depending on that state as specified in the above sections.
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.
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
isNULL
or a pointer to a structure extending this structure. -
viewMask
is the viewMask used for rendering. -
colorAttachmentCount
is the number of entries inpColorAttachmentFormats
-
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.
Bits which can be set in
-
VkGraphicsPipelineCreateInfo::
flags
-
VkComputePipelineCreateInfo::
flags
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 asViewIndex
will be assigned values as if they were decorated asDeviceIndex
. -
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 effectivelyVK_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 effectivelyVK_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 effectivelyVK_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 effectivelyVK_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 usingOpTraceRayKHR
. -
VK_PIPELINE_CREATE_RAY_TRACING_SKIP_AABBS_BIT_KHR
specifies that AABB primitives will be skipped during traversal usingOpTraceRayKHR
. -
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 notVK_SUCCESS
rather than continuing to create additional pipelines. -
VK_PIPELINE_CREATE_RAY_TRACING_ALLOW_MOTION_BIT_NV
specifies that the pipeline is allowed to useOpTraceRayMotionNV
. -
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 withVK_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 |
// 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
isNULL
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).
// 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;
-
VK_GRAPHICS_PIPELINE_LIBRARY_VERTEX_INPUT_INTERFACE_BIT_EXT
specifies that a pipeline will include vertex input interface state. -
VK_GRAPHICS_PIPELINE_LIBRARY_PRE_RASTERIZATION_SHADERS_BIT_EXT
specifies that a pipeline will include pre-rasterization shader state. -
VK_GRAPHICS_PIPELINE_LIBRARY_FRAGMENT_SHADER_BIT_EXT
specifies that a pipeline will include fragment shader state. -
VK_GRAPHICS_PIPELINE_LIBRARY_FRAGMENT_OUTPUT_INTERFACE_BIT_EXT
specifies that a pipeline will include fragment output interface state.
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
isNULL
or a pointer to a structure extending this structure. -
flags
is reserved for future use. -
dynamicStateCount
is the number of elements in thepDynamicStates
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.
// 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;
-
VK_DYNAMIC_STATE_VIEWPORT
specifies that thepViewports
state in VkPipelineViewportStateCreateInfo will be ignored and must be set dynamically with vkCmdSetViewport before any drawing commands. The number of viewports used by a pipeline is still specified by theviewportCount
member of VkPipelineViewportStateCreateInfo. -
VK_DYNAMIC_STATE_SCISSOR
specifies that thepScissors
state in VkPipelineViewportStateCreateInfo will be ignored and must be set dynamically with vkCmdSetScissor before any drawing commands. The number of scissor rectangles used by a pipeline is still specified by thescissorCount
member of VkPipelineViewportStateCreateInfo. -
VK_DYNAMIC_STATE_LINE_WIDTH
specifies that thelineWidth
state in VkPipelineRasterizationStateCreateInfo will be ignored and must be set dynamically with vkCmdSetLineWidth before any drawing commands that generate line primitives for the rasterizer. -
VK_DYNAMIC_STATE_DEPTH_BIAS
specifies that thedepthBiasConstantFactor
,depthBiasClamp
anddepthBiasSlopeFactor
states in VkPipelineRasterizationStateCreateInfo will be ignored and must be set dynamically with vkCmdSetDepthBias before any draws are performed with depth bias enabled. -
VK_DYNAMIC_STATE_BLEND_CONSTANTS
specifies that theblendConstants
state in VkPipelineColorBlendStateCreateInfo will be ignored and must be set dynamically with vkCmdSetBlendConstants before any draws are performed with a pipeline state withVkPipelineColorBlendAttachmentState
memberblendEnable
set toVK_TRUE
and any of the blend functions using a constant blend color. -
VK_DYNAMIC_STATE_DEPTH_BOUNDS
specifies that theminDepthBounds
andmaxDepthBounds
states of VkPipelineDepthStencilStateCreateInfo will be ignored and must be set dynamically with vkCmdSetDepthBounds before any draws are performed with a pipeline state with VkPipelineDepthStencilStateCreateInfo memberdepthBoundsTestEnable
set toVK_TRUE
. -
VK_DYNAMIC_STATE_STENCIL_COMPARE_MASK
specifies that thecompareMask
state in VkPipelineDepthStencilStateCreateInfo for bothfront
andback
will be ignored and must be set dynamically with vkCmdSetStencilCompareMask before any draws are performed with a pipeline state with VkPipelineDepthStencilStateCreateInfo memberstencilTestEnable
set toVK_TRUE
-
VK_DYNAMIC_STATE_STENCIL_WRITE_MASK
specifies that thewriteMask
state in VkPipelineDepthStencilStateCreateInfo for bothfront
andback
will be ignored and must be set dynamically with vkCmdSetStencilWriteMask before any draws are performed with a pipeline state with VkPipelineDepthStencilStateCreateInfo memberstencilTestEnable
set toVK_TRUE
-
VK_DYNAMIC_STATE_STENCIL_REFERENCE
specifies that thereference
state in VkPipelineDepthStencilStateCreateInfo for bothfront
andback
will be ignored and must be set dynamically with vkCmdSetStencilReference before any draws are performed with a pipeline state with VkPipelineDepthStencilStateCreateInfo memberstencilTestEnable
set toVK_TRUE
-
VK_DYNAMIC_STATE_VIEWPORT_W_SCALING_NV
specifies that thepViewportWScalings
state in VkPipelineViewportWScalingStateCreateInfoNV will be ignored and must be set dynamically with vkCmdSetViewportWScalingNV before any draws are performed with a pipeline state with VkPipelineViewportWScalingStateCreateInfoNV memberviewportScalingEnable
set toVK_TRUE
-
VK_DYNAMIC_STATE_DISCARD_RECTANGLE_EXT
specifies that thepDiscardRectangles
state in VkPipelineDiscardRectangleStateCreateInfoEXT will be ignored and must be set dynamically with vkCmdSetDiscardRectangleEXT before any draw or clear commands. -
VK_DYNAMIC_STATE_DISCARD_RECTANGLE_ENABLE_EXT
specifies that the presence of the VkPipelineDiscardRectangleStateCreateInfoEXT structure in the VkGraphicsPipelineCreateInfo chain with adiscardRectangleCount
greater than zero does not implicitly enable discard rectangles and they must be enabled dynamically with vkCmdSetDiscardRectangleEnableEXT before any draw commands. This is available on implementations that support at leastspecVersion
2
of theVK_EXT_discard_rectangles
extension. -
VK_DYNAMIC_STATE_DISCARD_RECTANGLE_MODE_EXT
specifies that thediscardRectangleMode
state in VkPipelineDiscardRectangleStateCreateInfoEXT will be ignored and must be set dynamically with vkCmdSetDiscardRectangleModeEXT before any draw commands. This is available on implementations that support at leastspecVersion
2
of theVK_EXT_discard_rectangles
extension. -
VK_DYNAMIC_STATE_SAMPLE_LOCATIONS_EXT
specifies that thesampleLocationsInfo
state in VkPipelineSampleLocationsStateCreateInfoEXT will be ignored and must be set dynamically with vkCmdSetSampleLocationsEXT before any draw or clear commands. Enabling custom sample locations is still indicated by thesampleLocationsEnable
member of VkPipelineSampleLocationsStateCreateInfoEXT. -
VK_DYNAMIC_STATE_EXCLUSIVE_SCISSOR_NV
specifies that thepExclusiveScissors
state in VkPipelineViewportExclusiveScissorStateCreateInfoNV will be ignored and must be set dynamically with vkCmdSetExclusiveScissorNV before any drawing commands. -
VK_DYNAMIC_STATE_EXCLUSIVE_SCISSOR_ENABLE_NV
specifies that the the exclusive scissors must be explicitly enabled with vkCmdSetExclusiveScissorEnableNV and theexclusiveScissorCount
value in VkPipelineViewportExclusiveScissorStateCreateInfoNV will not implicitly enable them. This is available on implementations that support at leastspecVersion
2
of theVK_NV_scissor_exclusive
extension. -
VK_DYNAMIC_STATE_VIEWPORT_SHADING_RATE_PALETTE_NV
specifies that thepShadingRatePalettes
state in VkPipelineViewportShadingRateImageStateCreateInfoNV will be ignored and must be set dynamically with vkCmdSetViewportShadingRatePaletteNV before any drawing commands. -
VK_DYNAMIC_STATE_VIEWPORT_COARSE_SAMPLE_ORDER_NV
specifies that the coarse sample order state in VkPipelineViewportCoarseSampleOrderStateCreateInfoNV will be ignored and must be set dynamically with vkCmdSetCoarseSampleOrderNV before any drawing commands. -
VK_DYNAMIC_STATE_LINE_STIPPLE_EXT
specifies that thelineStippleFactor
andlineStipplePattern
state in VkPipelineRasterizationLineStateCreateInfoEXT will be ignored and must be set dynamically with vkCmdSetLineStippleEXT before any draws are performed with a pipeline state with VkPipelineRasterizationLineStateCreateInfoEXT memberstippledLineEnable
set toVK_TRUE
. -
VK_DYNAMIC_STATE_CULL_MODE
specifies that thecullMode
state in VkPipelineRasterizationStateCreateInfo will be ignored and must be set dynamically with vkCmdSetCullMode before any drawing commands. -
VK_DYNAMIC_STATE_FRONT_FACE
specifies that thefrontFace
state in VkPipelineRasterizationStateCreateInfo will be ignored and must be set dynamically with vkCmdSetFrontFace before any drawing commands. -
VK_DYNAMIC_STATE_PRIMITIVE_TOPOLOGY
specifies that thetopology
state in VkPipelineInputAssemblyStateCreateInfo only specifies the topology class, and the specific topology order and adjacency must be set dynamically with vkCmdSetPrimitiveTopology before any drawing commands. -
VK_DYNAMIC_STATE_VIEWPORT_WITH_COUNT
specifies that theviewportCount
andpViewports
state in VkPipelineViewportStateCreateInfo will be ignored and must be set dynamically with vkCmdSetViewportWithCount before any draw call. -
VK_DYNAMIC_STATE_SCISSOR_WITH_COUNT
specifies that thescissorCount
andpScissors
state in VkPipelineViewportStateCreateInfo will be ignored and must be set dynamically with vkCmdSetScissorWithCount before any draw call. -
VK_DYNAMIC_STATE_VERTEX_INPUT_BINDING_STRIDE
specifies that thestride
state in VkVertexInputBindingDescription will be ignored and must be set dynamically with vkCmdBindVertexBuffers2 before any draw call. -
VK_DYNAMIC_STATE_DEPTH_TEST_ENABLE
specifies that thedepthTestEnable
state in VkPipelineDepthStencilStateCreateInfo will be ignored and must be set dynamically with vkCmdSetDepthTestEnable before any draw call. -
VK_DYNAMIC_STATE_DEPTH_WRITE_ENABLE
specifies that thedepthWriteEnable
state in VkPipelineDepthStencilStateCreateInfo will be ignored and must be set dynamically with vkCmdSetDepthWriteEnable before any draw call. -
VK_DYNAMIC_STATE_DEPTH_COMPARE_OP
specifies that thedepthCompareOp
state in VkPipelineDepthStencilStateCreateInfo will be ignored and must be set dynamically with vkCmdSetDepthCompareOp before any draw call. -
VK_DYNAMIC_STATE_DEPTH_BOUNDS_TEST_ENABLE
specifies that thedepthBoundsTestEnable
state in VkPipelineDepthStencilStateCreateInfo will be ignored and must be set dynamically with vkCmdSetDepthBoundsTestEnable before any draw call. -
VK_DYNAMIC_STATE_STENCIL_TEST_ENABLE
specifies that thestencilTestEnable
state in VkPipelineDepthStencilStateCreateInfo will be ignored and must be set dynamically with vkCmdSetStencilTestEnable before any draw call. -
VK_DYNAMIC_STATE_STENCIL_OP
specifies that thefailOp
,passOp
,depthFailOp
, andcompareOp
states inVkPipelineDepthStencilStateCreateInfo
for bothfront
andback
will be ignored and must be set dynamically with vkCmdSetStencilOp before any draws are performed with a pipeline state withVkPipelineDepthStencilStateCreateInfo
memberstencilTestEnable
set toVK_TRUE
-
VK_DYNAMIC_STATE_PATCH_CONTROL_POINTS_EXT
specifies that thepatchControlPoints
state in VkPipelineTessellationStateCreateInfo will be ignored and must be set dynamically with vkCmdSetPatchControlPointsEXT before any drawing commands. -
VK_DYNAMIC_STATE_RASTERIZER_DISCARD_ENABLE
specifies that therasterizerDiscardEnable
state in VkPipelineRasterizationStateCreateInfo will be ignored and must be set dynamically with vkCmdSetRasterizerDiscardEnable before any drawing commands. -
VK_DYNAMIC_STATE_DEPTH_BIAS_ENABLE
specifies that thedepthBiasEnable
state in VkPipelineRasterizationStateCreateInfo will be ignored and must be set dynamically with vkCmdSetDepthBiasEnable before any drawing commands. -
VK_DYNAMIC_STATE_LOGIC_OP_EXT
specifies that thelogicOp
state in VkPipelineColorBlendStateCreateInfo will be ignored and must be set dynamically with vkCmdSetLogicOpEXT before any drawing commands. -
VK_DYNAMIC_STATE_PRIMITIVE_RESTART_ENABLE
specifies that theprimitiveRestartEnable
state in VkPipelineInputAssemblyStateCreateInfo will be ignored and must be set dynamically with vkCmdSetPrimitiveRestartEnable before any drawing commands. -
VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR
specifies that state in VkPipelineFragmentShadingRateStateCreateInfoKHR and VkPipelineFragmentShadingRateEnumStateCreateInfoNV will be ignored and must be set dynamically with vkCmdSetFragmentShadingRateKHR or vkCmdSetFragmentShadingRateEnumNV before any drawing commands. -
VK_DYNAMIC_STATE_RAY_TRACING_PIPELINE_STACK_SIZE_KHR
specifies that the default stack size computation for the pipeline will be ignored and must be set dynamically with vkCmdSetRayTracingPipelineStackSizeKHR before any ray tracing calls are performed. -
VK_DYNAMIC_STATE_VERTEX_INPUT_EXT
specifies that thepVertexInputState
state will be ignored and must be set dynamically with vkCmdSetVertexInputEXT before any drawing commands -
VK_DYNAMIC_STATE_COLOR_WRITE_ENABLE_EXT
specifies that thepColorWriteEnables
state in VkPipelineColorWriteCreateInfoEXT will be ignored and must be set dynamically with vkCmdSetColorWriteEnableEXT before any draw call. -
VK_DYNAMIC_STATE_TESSELLATION_DOMAIN_ORIGIN_EXT
specifies that thedomainOrigin
state in VkPipelineTessellationDomainOriginStateCreateInfo will be ignored and must be set dynamically with vkCmdSetTessellationDomainOriginEXT before any draw call. -
VK_DYNAMIC_STATE_DEPTH_CLAMP_ENABLE_EXT
specifies that thedepthClampEnable
state in VkPipelineRasterizationStateCreateInfo will be ignored and must be set dynamically with vkCmdSetDepthClampEnableEXT before any draw call. -
VK_DYNAMIC_STATE_POLYGON_MODE_EXT
specifies that thepolygonMode
state in VkPipelineRasterizationStateCreateInfo will be ignored and must be set dynamically with vkCmdSetPolygonModeEXT before any draw call. -
VK_DYNAMIC_STATE_RASTERIZATION_SAMPLES_EXT
specifies that therasterizationSamples
state in VkPipelineMultisampleStateCreateInfo will be ignored and must be set dynamically with vkCmdSetRasterizationSamplesEXT before any draw call. -
VK_DYNAMIC_STATE_SAMPLE_MASK_EXT
specifies that thepSampleMask
state in VkPipelineMultisampleStateCreateInfo will be ignored and must be set dynamically with vkCmdSetSampleMaskEXT before any draw call. -
VK_DYNAMIC_STATE_ALPHA_TO_COVERAGE_ENABLE_EXT
specifies that thealphaToCoverageEnable
state in VkPipelineMultisampleStateCreateInfo will be ignored and must be set dynamically with vkCmdSetAlphaToCoverageEnableEXT before any draw call. -
VK_DYNAMIC_STATE_ALPHA_TO_ONE_ENABLE_EXT
specifies that thealphaToOneEnable
state in VkPipelineMultisampleStateCreateInfo will be ignored and must be set dynamically with vkCmdSetAlphaToOneEnableEXT before any draw call. -
VK_DYNAMIC_STATE_LOGIC_OP_ENABLE_EXT
specifies that thelogicOpEnable
state in VkPipelineColorBlendStateCreateInfo will be ignored and must be set dynamically with vkCmdSetLogicOpEnableEXT before any draw call. -
VK_DYNAMIC_STATE_COLOR_BLEND_ENABLE_EXT
specifies that theblendEnable
state in VkPipelineColorBlendAttachmentState will be ignored and must be set dynamically with vkCmdSetColorBlendEnableEXT before any draw call. -
VK_DYNAMIC_STATE_COLOR_BLEND_EQUATION_EXT
specifies that thesrcColorBlendFactor
,dstColorBlendFactor
,colorBlendOp
,srcAlphaBlendFactor
,dstAlphaBlendFactor
, andalphaBlendOp
states in VkPipelineColorBlendAttachmentState will be ignored and must be set dynamically with vkCmdSetColorBlendEquationEXT before any draw call. -
VK_DYNAMIC_STATE_COLOR_WRITE_MASK_EXT
specifies that thecolorWriteMask
state in VkPipelineColorBlendAttachmentState will be ignored and must be set dynamically with vkCmdSetColorWriteMaskEXT before any draw call. -
VK_DYNAMIC_STATE_RASTERIZATION_STREAM_EXT
specifies that therasterizationStream
state in VkPipelineRasterizationStateStreamCreateInfoEXT will be ignored and must be set dynamically with vkCmdSetRasterizationStreamEXT before any draw call. -
VK_DYNAMIC_STATE_CONSERVATIVE_RASTERIZATION_MODE_EXT
specifies that theconservativeRasterizationMode
state in VkPipelineRasterizationConservativeStateCreateInfoEXT will be ignored and must be set dynamically with vkCmdSetConservativeRasterizationModeEXT before any draw call. -
VK_DYNAMIC_STATE_EXTRA_PRIMITIVE_OVERESTIMATION_SIZE_EXT
specifies that theextraPrimitiveOverestimationSize
state in VkPipelineRasterizationConservativeStateCreateInfoEXT will be ignored and must be set dynamically with vkCmdSetExtraPrimitiveOverestimationSizeEXT before any draw call. -
VK_DYNAMIC_STATE_DEPTH_CLIP_ENABLE_EXT
specifies that thedepthClipEnable
state in VkPipelineRasterizationDepthClipStateCreateInfoEXT will be ignored and must be set dynamically with vkCmdSetDepthClipEnableEXT before any draw call. -
VK_DYNAMIC_STATE_SAMPLE_LOCATIONS_ENABLE_EXT
specifies that thesampleLocationsEnable
state in VkPipelineSampleLocationsStateCreateInfoEXT will be ignored and must be set dynamically with vkCmdSetSampleLocationsEnableEXT before any draw call. -
VK_DYNAMIC_STATE_COLOR_BLEND_ADVANCED_EXT
specifies that thecolorBlendOp
state in VkPipelineColorBlendAttachmentState, andsrcPremultiplied
,dstPremultiplied
, andblendOverlap
states in VkPipelineColorBlendAdvancedStateCreateInfoEXT will be ignored and must be set dynamically with vkCmdSetColorBlendAdvancedEXT before any draw call. -
VK_DYNAMIC_STATE_PROVOKING_VERTEX_MODE_EXT
specifies that theprovokingVertexMode
state in VkPipelineRasterizationProvokingVertexStateCreateInfoEXT will be ignored and must be set dynamically with vkCmdSetProvokingVertexModeEXT before any draw call. -
VK_DYNAMIC_STATE_LINE_RASTERIZATION_MODE_EXT
specifies that thelineRasterizationMode
state in VkPipelineRasterizationLineStateCreateInfoEXT will be ignored and must be set dynamically with vkCmdSetLineRasterizationModeEXT before any draw call. -
VK_DYNAMIC_STATE_LINE_STIPPLE_ENABLE_EXT
specifies that thestippledLineEnable
state in VkPipelineRasterizationLineStateCreateInfoEXT will be ignored and must be set dynamically with vkCmdSetLineStippleEnableEXT before any draw call. -
VK_DYNAMIC_STATE_DEPTH_CLIP_NEGATIVE_ONE_TO_ONE_EXT
specifies that thenegativeOneToOne
state in VkPipelineViewportDepthClipControlCreateInfoEXT will be ignored and must be set dynamically with vkCmdSetDepthClipNegativeOneToOneEXT before any draw call. -
VK_DYNAMIC_STATE_VIEWPORT_W_SCALING_ENABLE_NV
specifies that theviewportWScalingEnable
state in VkPipelineViewportWScalingStateCreateInfoNV will be ignored and must be set dynamically with vkCmdSetViewportWScalingEnableNV before any draw call. -
VK_DYNAMIC_STATE_VIEWPORT_SWIZZLE_NV
specifies that theviewportCount
, andpViewportSwizzles
states in VkPipelineViewportSwizzleStateCreateInfoNV will be ignored and must be set dynamically with vkCmdSetViewportSwizzleNV before any draw call. -
VK_DYNAMIC_STATE_COVERAGE_TO_COLOR_ENABLE_NV
specifies that thecoverageToColorEnable
state in VkPipelineCoverageToColorStateCreateInfoNV will be ignored and must be set dynamically with vkCmdSetCoverageToColorEnableNV before any draw call. -
VK_DYNAMIC_STATE_COVERAGE_TO_COLOR_LOCATION_NV
specifies that thecoverageToColorLocation
state in VkPipelineCoverageToColorStateCreateInfoNV will be ignored and must be set dynamically with vkCmdSetCoverageToColorLocationNV before any draw call. -
VK_DYNAMIC_STATE_COVERAGE_MODULATION_MODE_NV
specifies that thecoverageModulationMode
state in VkPipelineCoverageModulationStateCreateInfoNV will be ignored and must be set dynamically with vkCmdSetCoverageModulationModeNV before any draw call. -
VK_DYNAMIC_STATE_COVERAGE_MODULATION_TABLE_ENABLE_NV
specifies that thecoverageModulationTableEnable
state in VkPipelineCoverageModulationStateCreateInfoNV will be ignored and must be set dynamically with vkCmdSetCoverageModulationTableEnableNV before any draw call. -
VK_DYNAMIC_STATE_COVERAGE_MODULATION_TABLE_NV
specifies that thecoverageModulationTableCount
, andpCoverageModulationTable
states in VkPipelineCoverageModulationStateCreateInfoNV will be ignored and must be set dynamically with vkCmdSetCoverageModulationTableNV before any draw call. -
VK_DYNAMIC_STATE_SHADING_RATE_IMAGE_ENABLE_NV
specifies that theshadingRateImageEnable
state in VkPipelineViewportShadingRateImageStateCreateInfoNV will be ignored and must be set dynamically with vkCmdSetShadingRateImageEnableNV before any draw call. -
VK_DYNAMIC_STATE_REPRESENTATIVE_FRAGMENT_TEST_ENABLE_NV
specifies that therepresentativeFragmentTestEnable
state in VkPipelineRepresentativeFragmentTestStateCreateInfoNV will be ignored and must be set dynamically with vkCmdSetRepresentativeFragmentTestEnableNV before any draw call. -
VK_DYNAMIC_STATE_COVERAGE_REDUCTION_MODE_NV
specifies that thecoverageReductionMode
state in VkPipelineCoverageReductionStateCreateInfoNV will be ignored and must be set dynamically with vkCmdSetCoverageReductionModeNV before any draw call.
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.
-
Depth/stencil-only rendering in a subpass with no color attachments
-
Active Pipeline Shader Stages
-
Vertex Shader
-
-
Required: Fixed-Function Pipeline Stages
-
-
Color-only rendering in a subpass with no depth/stencil attachment
-
Active Pipeline Shader Stages
-
Vertex Shader
-
Fragment Shader
-
-
Required: Fixed-Function Pipeline Stages
-
-
Rendering pipeline with tessellation and geometry shaders
-
Active Pipeline Shader Stages
-
Vertex Shader
-
Tessellation Control Shader
-
Tessellation Evaluation Shader
-
Geometry Shader
-
Fragment Shader
-
-
Required: Fixed-Function Pipeline Stages
-
-
Rendering pipeline with task and mesh shaders
-
Active Pipeline Shader Stages
-
Task Shader
-
Mesh Shader
-
Fragment Shader
-
-
Required: Fixed-Function Pipeline Stages
-
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
isNULL
or a pointer to a structure extending this structure. -
groupCount
is the number of elements in thepGroups
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 thepPipelines
array. -
pPipelines
is a pointer to an array of graphicsVkPipeline
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.
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
isNULL
or a pointer to a structure extending this structure. -
stageCount
is the number of entries in thepStages
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.
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 thepCreateInfos
andpPipelines
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.
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 thepCreateInfos
andpPipelines
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.
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
isNULL
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 thepStages
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 thepGroups
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 thepCreateInfos
parameter to use as a pipeline to derive from.
The parameters basePipelineHandle
and basePipelineIndex
are
described in more detail in Pipeline
Derivatives.
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
isNULL
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 thepStages
array. -
pStages
is a pointer to an array ofstageCount
VkPipelineShaderStageCreateInfo structures describing the set of the shader stages to be included in the ray tracing pipeline. -
groupCount
is the number of entries in thepGroups
array. -
pGroups
is a pointer to an array ofgroupCount
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 beNULL
, 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 thepCreateInfos
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.
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
isNULL
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 hastype
ofVK_RAY_TRACING_SHADER_GROUP_TYPE_GENERAL_NV
, andVK_SHADER_UNUSED_NV
otherwise. -
closestHitShader
is the optional index of the closest hit shader from VkRayTracingPipelineCreateInfoNV::pStages
in the group if the shader group hastype
ofVK_RAY_TRACING_SHADER_GROUP_TYPE_TRIANGLES_HIT_GROUP_NV
orVK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_NV
, andVK_SHADER_UNUSED_NV
otherwise. -
anyHitShader
is the optional index of the any-hit shader from VkRayTracingPipelineCreateInfoNV::pStages
in the group if the shader group hastype
ofVK_RAY_TRACING_SHADER_GROUP_TYPE_TRIANGLES_HIT_GROUP_NV
orVK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_NV
, andVK_SHADER_UNUSED_NV
otherwise. -
intersectionShader
is the index of the intersection shader from VkRayTracingPipelineCreateInfoNV::pStages
in the group if the shader group hastype
ofVK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_NV
, andVK_SHADER_UNUSED_NV
otherwise.
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
isNULL
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 hastype
ofVK_RAY_TRACING_SHADER_GROUP_TYPE_GENERAL_KHR
, andVK_SHADER_UNUSED_KHR
otherwise. -
closestHitShader
is the optional index of the closest hit shader from VkRayTracingPipelineCreateInfoKHR::pStages
in the group if the shader group hastype
ofVK_RAY_TRACING_SHADER_GROUP_TYPE_TRIANGLES_HIT_GROUP_KHR
orVK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_KHR
, andVK_SHADER_UNUSED_KHR
otherwise. -
anyHitShader
is the optional index of the any-hit shader from VkRayTracingPipelineCreateInfoKHR::pStages
in the group if the shader group hastype
ofVK_RAY_TRACING_SHADER_GROUP_TYPE_TRIANGLES_HIT_GROUP_KHR
orVK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_KHR
, andVK_SHADER_UNUSED_KHR
otherwise. -
intersectionShader
is the index of the intersection shader from VkRayTracingPipelineCreateInfoKHR::pStages
in the group if the shader group hastype
ofVK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_KHR
, andVK_SHADER_UNUSED_KHR
otherwise. -
pShaderGroupCaptureReplayHandle
isNULL
or a pointer to replay information for this shader group queried from vkGetRayTracingCaptureReplayShaderGroupHandlesKHR, as described in Ray Tracing Capture Replay. Ignored if VkPhysicalDeviceRayTracingPipelineFeaturesKHR::rayTracingPipelineShaderGroupHandleCaptureReplay
isVK_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.
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 singleVK_SHADER_STAGE_RAYGEN_BIT_KHR
,VK_SHADER_STAGE_MISS_BIT_KHR
, orVK_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
isNULL
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 |
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 bypData
. -
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
.
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 bypData
. -
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
.
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.
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.
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;
-
VK_SHADER_GROUP_SHADER_GENERAL_KHR
uses the shader specified in the group with VkRayTracingShaderGroupCreateInfoKHR::generalShader
-
VK_SHADER_GROUP_SHADER_CLOSEST_HIT_KHR
uses the shader specified in the group with VkRayTracingShaderGroupCreateInfoKHR::closestHitShader
-
VK_SHADER_GROUP_SHADER_ANY_HIT_KHR
uses the shader specified in the group with VkRayTracingShaderGroupCreateInfoKHR::anyHitShader
-
VK_SHADER_GROUP_SHADER_INTERSECTION_KHR
uses the shader specified in the group with VkRayTracingShaderGroupCreateInfoKHR::intersectionShader
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.
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.
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 |
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 |
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
isNULL
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 inpInitialData
. IfinitialDataSize
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. IfinitialDataSize
is zero,pInitialData
is ignored.
// 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 thepSrcCaches
array. -
pSrcCaches
is a pointer to an array of pipeline cache handles, which will be merged intodstCache
. The previous contents ofdstCache
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. |
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 asize_t
value related to the amount of data in the pipeline cache, as described below. -
pData
is eitherNULL
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
.
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 theVkPhysicalDeviceProperties
::vendorID
of the implementation. -
deviceID
is theVkPhysicalDeviceProperties
::deviceID
of the implementation. -
pipelineCacheUUID
is theVkPhysicalDeviceProperties
::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.
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;
-
VK_PIPELINE_CACHE_HEADER_VERSION_ONE
specifies version one of the pipeline cache, described by VkPipelineCacheHeaderVersionOne.
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.
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 thepMapEntries
array. -
pMapEntries
is a pointer to an array ofVkSpecializationMapEntry
structures, which map constant IDs to offsets inpData
. -
dataSize
is the byte size of thepData
buffer. -
pData
contains the actual constant values to specialize with.
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.
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
isNULL
or a pointer to a structure extending this structure. -
libraryCount
is the number of pipeline libraries inpLibraries
. -
pLibraries
is a pointer to an array of VkPipeline structures specifying pipeline libraries to use when creating a pipeline.
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.
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.
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 eitherNULL
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.
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
isNULL
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 ofVK_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 ofVK_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.
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.
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
isNULL
or a pointer to a structure extending this structure. -
pipelineIdentifier
is an array ofVK_UUID_SIZE
uint8_t
values into which the pipeline identifier will be written.
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
isNULL
or a pointer to a structure extending this structure. -
pipeline
is aVkPipeline
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 eitherNULL
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.
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
isNULL
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.
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
isNULL
or a pointer to a structure extending this structure. -
name
is an array ofVK_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 ofVK_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 invalue
. -
value
is the value of this statistic.
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 eitherVK_TRUE
orVK_FALSE
and should be read from theb32
field ofVkPipelineExecutableStatisticValueKHR
. -
VK_PIPELINE_EXECUTABLE_STATISTIC_FORMAT_INT64_KHR
specifies that the statistic is returned as a signed 64-bit integer and should be read from thei64
field ofVkPipelineExecutableStatisticValueKHR
. -
VK_PIPELINE_EXECUTABLE_STATISTIC_FORMAT_UINT64_KHR
specifies that the statistic is returned as an unsigned 64-bit integer and should be read from theu64
field ofVkPipelineExecutableStatisticValueKHR
. -
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 thef64
field ofVkPipelineExecutableStatisticValueKHR
.
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 theVkPipelineExecutableStatisticFormatKHR
isVK_PIPELINE_EXECUTABLE_STATISTIC_FORMAT_BOOL32_KHR
. -
i64
is the signed 64-bit integer value if theVkPipelineExecutableStatisticFormatKHR
isVK_PIPELINE_EXECUTABLE_STATISTIC_FORMAT_INT64_KHR
. -
u64
is the unsigned 64-bit integer value if theVkPipelineExecutableStatisticFormatKHR
isVK_PIPELINE_EXECUTABLE_STATISTIC_FORMAT_UINT64_KHR
. -
f64
is the 64-bit floating-point value if theVkPipelineExecutableStatisticFormatKHR
isVK_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 eitherNULL
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.
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
isNULL
or a pointer to a structure extending this structure. -
name
is an array ofVK_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 ofVK_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. IfisText
isVK_TRUE
then the data returned inpData
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 eitherNULL
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.
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 createdpipeline
. -
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 eitherNULL
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.
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;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
compilerControlFlags
is a bitmask of VkPipelineCompilerControlFlagBitsAMD affecting how the pipeline will be compiled.
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
isNULL
or a pointer to a structure extending this structure. -
pPipelineCreationFeedback
is a pointer to a VkPipelineCreationFeedback structure. -
pipelineStageCreationFeedbackCount
is the number of elements inpPipelineStageCreationFeedbacks
. -
pPipelineStageCreationFeedbacks
is a pointer to an array ofpipelineStageCreationFeedbackCount
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
|
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
.
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 thepipelineCache
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 thepipelineCache
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.NoteImplementations 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 thebasePipelineHandle
orbasePipelineIndex
member of theVk*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.NoteWhile “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 inVkAllocationCallbacks
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.
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, |
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 eitherNULL
or a pointer previously returned bypfnReallocation
orpfnAllocation
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 aVkPipelineCache
orVkValidationCacheEXT
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 parentVkDevice
has an allocator it will be used, else if the parentVkInstance
has an allocator it will be used. Else, -
If an allocation is associated with a
VkValidationCacheEXT
orVkPipelineCache
object, the allocator will use theVK_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
orVkInstance
, the allocator will use an allocation scope ofVK_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
orVkInstance
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
fordstCache
-
vkCreateGraphicsPipelines
forpipelineCache
-
vkCreateComputePipelines
forpipelineCache
-
-
Allocations scoped to a
VkValidationCacheEXT
may only be allocated from:-
vkCreateValidationCacheEXT
-
vkMergeValidationCachesEXT
fordstCache
-
vkCreateShaderModule
forvalidationCache
in VkShaderModuleValidationCacheCreateInfoEXT
-
-
Allocations scoped to a
VkDescriptorPool
may only be allocated from:-
any command that takes the pool as a direct argument
-
vkAllocateDescriptorSets
for thedescriptorPool
member of itspAllocateInfo
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 thecommandPool
member of itspAllocateInfo
parameter -
any
vkCmd*
command whosecommandBuffer
was allocated from thatVkCommandPool
-
-
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
orVkInstance
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 fromvkDestroyPipelineCache
. -
Allocations scoped to a
VkValidationCacheEXT
may be freed fromvkDestroyValidationCacheEXT
. -
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
whosecommandBuffer
was allocated from thatVkCommandPool
-
-
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.
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 thememoryTypes
array. -
memoryTypes
is an array ofVK_MAX_MEMORY_TYPES
VkMemoryType structures describing the memory types that can be used to access memory allocated from the heaps specified bymemoryHeaps
. -
memoryHeapCount
is the number of valid elements in thememoryHeaps
array. -
memoryHeaps
is an array ofVK_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 thepropertyFlags
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 includesVK_MEMORY_PROPERTY_DEVICE_COHERENT_BIT_AMD
orVK_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 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.
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;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
memoryProperties
is a VkPhysicalDeviceMemoryProperties structure which is populated with the same values as in vkGetPhysicalDeviceMemoryProperties.
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;
-
heapIndex
describes which memory heap this memory type corresponds to, and must be less thanmemoryHeapCount
from the VkPhysicalDeviceMemoryProperties structure. -
propertyFlags
is a bitmask of VkMemoryPropertyFlagBits of properties for this memory type.
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 theVK_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 bothVK_MEMORY_PROPERTY_LAZILY_ALLOCATED_BIT
andVK_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 haveVK_MEMORY_PROPERTY_PROTECTED_BIT
set and any ofVK_MEMORY_PROPERTY_HOST_VISIBLE_BIT
set, orVK_MEMORY_PROPERTY_HOST_COHERENT_BIT
set, orVK_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
isNULL
or a pointer to a structure extending this structure. -
heapBudget
is an array ofVK_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 ofVK_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.
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 |
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 |
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.
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
isNULL
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 thememoryTypes
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:
-
VkImportMemoryWin32HandleInfoKHR with a non-zero
handleType
value -
VkImportMemoryFdInfoKHR with a non-zero
handleType
value -
VkImportMemoryHostPointerInfoEXT with a non-zero
handleType
value -
VkImportAndroidHardwareBufferInfoANDROID with a non-
NULL
buffer
value -
VkImportMemoryZirconHandleInfoFUCHSIA with a non-zero
handleType
value
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:
-
VkPhysicalDeviceMaintenance3Properties::
maxMemoryAllocationCount
-
VkPhysicalDeviceMemoryBudgetPropertiesEXT::
heapUsage
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.
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
isNULL
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.
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
isNULL
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.
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
isNULL
or a pointer to a structure extending this structure. -
priority
is a floating-point value between0
and1
, 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
.
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 between0
and1
, 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.
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
isNULL
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.
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;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
handleTypes
is a bitmask of VkExternalMemoryHandleTypeFlagBitsNV specifying one or more memory handle types that may be exported. Multiple handle types may be requested for the same allocation as long as they are compatible, as reported by vkGetPhysicalDeviceExternalImageFormatPropertiesNV.
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
isNULL
or a pointer to a structure extending this structure. -
pAttributes
is a pointer to a WindowsSECURITY_ATTRIBUTES
structure specifying security attributes of the handle. -
dwAccess
is aDWORD
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.
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
isNULL
or a pointer to a structure extending this structure. -
handleType
is a VkExternalMemoryHandleTypeFlagBits value specifying the type ofhandle
orname
. -
handle
isNULL
or the external handle to import. -
name
isNULL
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.
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. |
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
isNULL
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.
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 importinghandle
. -
handleType
is a VkExternalMemoryHandleTypeFlagBits value specifying the type of the handlehandle
. -
handle
is the handle which will be imported. -
pMemoryWin32HandleProperties
is a pointer to a VkMemoryWin32HandlePropertiesKHR structure in which properties ofhandle
are returned.
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
isNULL
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.
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
isNULL
or a pointer to a structure extending this structure. -
pAttributes
is a pointer to a WindowsSECURITY_ATTRIBUTES
structure specifying security attributes of the handle. -
dwAccess
is aDWORD
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
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
isNULL
or a pointer to a structure extending this structure. -
handleType
is0
or a VkExternalMemoryHandleTypeFlagBitsNV value specifying the type of memory handle inhandle
. -
handle
is a WindowsHANDLE
referring to the memory.
If handleType
is 0
, this structure is ignored by consumers of the
VkMemoryAllocateInfo structure it is chained from.
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 usingDuplicateHandle()
. -
VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_IMAGE_BIT_NV
specifies a valid NT handle to memory returned byIDXGIResource1::CreateSharedHandle
, or a handle duplicated from such a handle usingDuplicateHandle()
. -
VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_IMAGE_KMT_BIT_NV
specifies a handle to memory returned byIDXGIResource::GetSharedHandle()
.
editing-note
(Jon) If additional (non-Win32) bits are added to the possible memory types,
this type should move to the |
// 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 WindowsHANDLE
in which the handle is returned.
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
isNULL
or a pointer to a structure extending this structure. -
handleType
is a VkExternalMemoryHandleTypeFlagBits value specifying the handle type offd
. -
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.
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.
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
isNULL
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:: |
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 importingfd
. -
handleType
is a VkExternalMemoryHandleTypeFlagBits value specifying the type of the handlefd
. -
fd
is the handle which will be imported. -
pMemoryFdProperties
is a pointer to a VkMemoryFdPropertiesKHR structure in which the properties of the handlefd
are returned.
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
isNULL
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.
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
isNULL
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.
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 importingpHostPointer
. -
handleType
is a VkExternalMemoryHandleTypeFlagBits value specifying the type of the handlepHostPointer
. -
pHostPointer
is the host pointer to import from. -
pMemoryHostPointerProperties
is a pointer to a VkMemoryHostPointerPropertiesEXT structure in which the host pointer properties are returned.
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
isNULL
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.
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
isNULL
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.
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.
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
isNULL
or a pointer to a structure extending this structure. -
memory
is the memory object from which the Android hardware buffer will be exported.
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 importingbuffer
. -
buffer
is the Android hardware buffer which will be imported. -
pProperties
is a pointer to a VkAndroidHardwareBufferPropertiesANDROID structure in which the properties ofbuffer
are returned.
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
isNULL
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.
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
isNULL
or a pointer to a structure extending this structure. -
format
is the Vulkan format corresponding to the Android hardware buffer’s format, orVK_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 frombuffer
. -
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 |
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
|
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
isNULL
or a pointer to a structure extending this structure. -
format
is the Vulkan format corresponding to the Android hardware buffer’s format, orVK_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 frombuffer
. -
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
.
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.
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
isNULL
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.
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
isNULL
or a pointer to a structure extending this structure. -
handleType
is a VkExternalMemoryHandleTypeFlagBits value specifying the type ofhandle
. -
handle
is azx_handle_t
(Zircon) handle to the external memory.
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);
-
device
is the VkDevice. -
handleType
is a VkExternalMemoryHandleTypeFlagBits value specifying the type ofzirconHandle
-
zirconHandle
is azx_handle_t
(Zircon) handle to the external resource. -
pMemoryZirconHandleProperties
is a pointer to a VkMemoryZirconHandlePropertiesFUCHSIA structure in which the result will be stored.
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
isNULL
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.
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);
-
device
is the VkDevice. -
pGetZirconHandleInfo
is a pointer to a VkMemoryGetZirconHandleInfoFUCHSIA structure. -
pZirconHandle
is a pointer to azx_handle_t
which holds the resulting Zircon handle.
VkMemoryGetZirconHandleInfoFUCHSIA
is defined as:
// Provided by VK_FUCHSIA_external_memory
typedef struct VkMemoryGetZirconHandleInfoFUCHSIA {
VkStructureType sType;
const void* pNext;
VkDeviceMemory memory;
VkExternalMemoryHandleTypeFlagBits handleType;
} VkMemoryGetZirconHandleInfoFUCHSIA;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
memory
the VkDeviceMemory being exported. -
handleType
is a VkExternalMemoryHandleTypeFlagBits value specifying the type of the handle pointed to by vkGetMemoryZirconHandleFUCHSIA::pZirconHandle
.
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
isNULL
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.
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 MetalMTLDevice
may be exported. -
VK_EXPORT_METAL_OBJECT_TYPE_METAL_COMMAND_QUEUE_BIT_EXT
indicates a MetalMTLCommandQueue
may be exported. -
VK_EXPORT_METAL_OBJECT_TYPE_METAL_BUFFER_BIT_EXT
indicates a MetalMTLBuffer
may be exported. -
VK_EXPORT_METAL_OBJECT_TYPE_METAL_TEXTURE_BIT_EXT
indicates a MetalMTLTexture
may be exported. -
VK_EXPORT_METAL_OBJECT_TYPE_METAL_IOSURFACE_BIT_EXT
indicates a MetalIOSurface
may be exported. -
VK_EXPORT_METAL_OBJECT_TYPE_METAL_SHARED_EVENT_BIT_EXT
indicates a MetalMTLSharedEvent
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 whosepNext
chain contains structures, each identifying a Vulkan object and providing a pointer through which the Metal object will be returned.
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
isNULL
or a pointer to a structure extending this structure.
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
isNULL
or a pointer to a structure extending this structure. -
mtlDevice
is the Metalid<MTLDevice>
object underlying the VkPhysicalDevice associated with the VkDevice object identified in the call. The implementation will return theMTLDevice
in this member, or it will returnNULL
if noMTLDevice
could be found underlying the VkPhysicalDevice object.
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
isNULL
or a pointer to a structure extending this structure. -
queue
is a VkQueue. -
mtlCommandQueue
is the Metalid<MTLCommandQueue>
object underlying the VkQueue object inqueue
. The implementation will return theMTLCommandQueue
in this member, or it will returnNULL
if noMTLCommandQueue
could be found underlying the VkQueue object.
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
isNULL
or a pointer to a structure extending this structure. -
memory
is a VkDeviceMemory. -
mtlBuffer
is the Metalid<MTLBuffer>
object underlying the VkDeviceMemory object inmemory
. The implementation will return theMTLBuffer
in this member, or it will returnNULL
if noMTLBuffer
could be found underlying the VkDeviceMemory object.
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
isNULL
or a pointer to a structure extending this structure. -
mtlBuffer
is the Metalid<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.
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;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
image
is VK_NULL_HANDLE or a VkImage. -
imageView
is VK_NULL_HANDLE or a VkImageView. -
bufferView
is VK_NULL_HANDLE or a VkBufferView. -
plane
indicates the plane of a multi-planar VkImage or VkImageView. -
mtlTexture
is the Metalid<MTLTexture>
object underlying the VkImage, VkImageView, or VkBufferView object inimage
,imageView
, orbufferView
, respectively, at the plane indicated inaspectMask
. The implementation will return theMTLTexture
in this member, or it will returnNULL
if noMTLTexture
could be found underlying the VkImage, VkImageView, or VkBufferView object, at the plane indicated inaspectMask
.
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
isNULL
or a pointer to a structure extending this structure. -
plane
indicates the plane of the VkImage that theid<MTLTexture>
object should be attached to. -
mtlTexture
is a the Metalid<MTLTexture>
object that is to underlie the VkImage plane.
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
isNULL
or a pointer to a structure extending this structure. -
image
is a VkImage. -
ioSurface
is the Metal IOSurfaceRef object underlying the VkImage object inimage
. The implementation will return the IOSurfaceRef in this member, or it will returnNULL
if no IOSurfaceRef could be found underlying the VkImage object.
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;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
ioSurface
is VK_NULL_HANDLE or the Metal IOSurfaceRef object that is to underlie the VkImage.
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.
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:
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
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 Metalid<MTLSharedEvent>
object underlying the VkSemaphore or VkEvent object insemaphore
orevent
, respectively. The implementation will return theMTLSharedEvent
in this member, or it will returnNULL
if noMTLSharedEvent
could be found underlying the VkSemaphore or VkEvent object.
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:
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
mtlSharedEvent
is the Metalid<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.
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:
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
isNULL
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, ifVK_MEMORY_ALLOCATE_DEVICE_MASK_BIT
is set inflags
.
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. |
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 theVK_BUFFER_USAGE_SHADER_DEVICE_ADDRESS_BIT
bit set inusage
, 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
isNULL
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 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.
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. |
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, orVK_WHOLE_SIZE
to map fromoffset
to the end of the allocation. -
flags
is reserved for future use. -
ppData
is a pointer to avoid*
variable in which a host-accessible pointer to the beginning of the mapped range is returned. This pointer minusoffset
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 |
Note
|
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. |
// 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
|
Note
While memory objects imported from a handle type of
|
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 thepMemoryRanges
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). |
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 thepMemoryRanges
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. |
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
isNULL
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, orVK_WHOLE_SIZE
to affect the range fromoffset
to the end of the current mapping of the allocation.
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.
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.
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 |
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 |
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
andheight
members ofAHardwareBuffer_Desc
must be the same as thewidth
andheight
members of VkImageCreateInfo::extent
, respectively. -
The
layers
member ofAHardwareBuffer_Desc
must be the same as thearrayLayers
member of VkImageCreateInfo. -
The
format
member ofAHardwareBuffer_Desc
must be equivalent to VkImageCreateInfo::format
as defined by AHardwareBuffer Format Equivalence. -
The
usage
member ofAHardwareBuffer_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.
AHardwareBuffer Format | Vulkan Format |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
AHardwareBuffer Usage | Vulkan Usage or Creation Flag |
---|---|
None |
|
None |
|
|
|
|
|
|
|
|
|
|
|
|
None 2 |
|
|
None |
|
None |
|
|
|
- 1
-
Vulkan does not differentiate between
AHARDWAREBUFFER_FORMAT_R8G8B8A8_UNORM
andAHARDWAREBUFFER_FORMAT_R8G8B8X8_UNORM
: they both behave asVK_FORMAT_R8G8B8A8_UNORM
. After an external entity writes to aAHARDWAREBUFFER_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 useVK_COMPONENT_SWIZZLE_ONE
in image view component mappings andVK_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 aAHARDWAREBUFFER_USAGE_GPU_FRAMEBUFFER
usage and try to create an image withVK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT
. - 4
-
In combination with a hardware buffer format other than
BLOB
.
Note
When using |
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.
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 anyvkCmdCopy*
command. -
VK_PEER_MEMORY_FEATURE_COPY_DST_BIT
specifies that the memory can be accessed as the destination of anyvkCmdCopy*
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. |
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
isNULL
or a pointer to a structure extending this structure. -
memory
specifies the memory whose address is being queried.
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.
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
isNULL
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 thepQueueFamilyIndices
array. -
pQueueFamilyIndices
is a pointer to an array of queue families that will access this buffer. It is ignored ifsharingMode
is notVK_SHARING_MODE_CONCURRENT
.
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 ofVK_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 aVkBufferView
suitable for occupying aVkDescriptorSet
slot of typeVK_DESCRIPTOR_TYPE_UNIFORM_TEXEL_BUFFER
. -
VK_BUFFER_USAGE_STORAGE_TEXEL_BUFFER_BIT
specifies that the buffer can be used to create aVkBufferView
suitable for occupying aVkDescriptorSet
slot of typeVK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER
. -
VK_BUFFER_USAGE_UNIFORM_BUFFER_BIT
specifies that the buffer can be used in aVkDescriptorBufferInfo
suitable for occupying aVkDescriptorSet
slot either of typeVK_DESCRIPTOR_TYPE_UNIFORM_BUFFER
orVK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC
. -
VK_BUFFER_USAGE_STORAGE_BUFFER_BIT
specifies that the buffer can be used in aVkDescriptorBufferInfo
suitable for occupying aVkDescriptorSet
slot either of typeVK_DESCRIPTOR_TYPE_STORAGE_BUFFER
orVK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC
. -
VK_BUFFER_USAGE_INDEX_BUFFER_BIT
specifies that the buffer is suitable for passing as thebuffer
parameter to vkCmdBindIndexBuffer. -
VK_BUFFER_USAGE_VERTEX_BUFFER_BIT
specifies that the buffer is suitable for passing as an element of thepBuffers
array to vkCmdBindVertexBuffers. -
VK_BUFFER_USAGE_INDIRECT_BUFFER_BIT
specifies that the buffer is suitable for passing as thebuffer
parameter to vkCmdDrawIndirect, vkCmdDrawIndexedIndirect, vkCmdDrawMeshTasksIndirectNV, vkCmdDrawMeshTasksIndirectCountNV,vkCmdDrawMeshTasksIndirectEXT
,vkCmdDrawMeshTasksIndirectCountEXT
, vkCmdDrawClusterIndirectHUAWEI, or vkCmdDispatchIndirect. It is also suitable for passing as thebuffer
member ofVkIndirectCommandsStreamNV
, orsequencesCountBuffer
orsequencesIndexBuffer
orpreprocessedBuffer
member ofVkGeneratedCommandsInfoNV
-
VK_BUFFER_USAGE_CONDITIONAL_RENDERING_BIT_EXT
specifies that the buffer is suitable for passing as thebuffer
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 specifyVK_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 theVK_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 theVK_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
isNULL
or a pointer to a structure extending this structure. -
dedicatedAllocation
specifies whether the buffer will have a dedicated allocation bound to it.
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 |
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
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.
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
isNULL
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
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
|
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
isNULL
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.
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
isNULL
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
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.
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.
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
isNULL
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. Ifrange
is equal toVK_WHOLE_SIZE
, the range fromoffset
to the end of the buffer is used. IfVK_WHOLE_SIZE
is used and the remaining size of the buffer is not a multiple of the texel block size offormat
, 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
.
// 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.
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.
-
If Vulkan 1.3 is supported or the
VK_KHR_format_feature_flags2
extension is supported, then the buffer view’s set of format features is the value of VkFormatProperties3::bufferFeatures
found by calling vkGetPhysicalDeviceFormatProperties2 on the sameformat
as VkBufferViewCreateInfo::format
.
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.
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
isNULL
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 thepQueueFamilyIndices
array. -
pQueueFamilyIndices
is a pointer to an array of queue families that will access this image. It is ignored ifsharingMode
is notVK_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
isVK_IMAGE_TYPE_2D
-
format
is not a depth/stencil format -
mipLevels
is 1 -
arrayLayers
is 1 -
samples
isVK_SAMPLE_COUNT_1_BIT
-
usage
only includesVK_IMAGE_USAGE_TRANSFER_SRC_BIT
and/orVK_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:
-
imageType
isVK_IMAGE_TYPE_2D
-
mipLevels
is 1 -
arrayLayers
is 1, unless theycbcrImageArrays
feature is enabled, or otherwise indicated by VkImageFormatProperties::maxArrayLayers
, as returned by vkGetPhysicalDeviceImageFormatProperties -
samples
isVK_SAMPLE_COUNT_1_BIT
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 For images created with |
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
isNULL
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
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
isNULL
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
.
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
isNULL
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. |
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 |
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
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.
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
isNULL
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.
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
isNULL
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.
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
isNULL
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.
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
isNULL
or a pointer to a structure extending this structure. -
viewFormatCount
is the number of entries in thepViewFormats
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.
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
isNULL
or a pointer to a structure extending this structure. -
drmFormatModifierCount
is the length of thepDrmFormatModifiers
array. -
pDrmFormatModifiers
is a pointer to an array of Linux DRM format modifiers.
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
isNULL
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 thepPlaneLayouts
array. -
pPlaneLayouts
is a pointer to an array of VkSubresourceLayout structures describing the image’s memory planes.
The i
th member of pPlaneLayouts
describes the layout of the
image’s i
th 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
.
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
isNULL
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 thepFixedRateFlags
array. -
pFixedRateFlags
isNULL
or a pointer to an array of VkImageCompressionFixedRateFlagsEXT bitfields describing allowed fixed-rate compression rates of each image plane. It is ignored ifflags
does not includeVK_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.
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 i
th
member of the pFixedRateFlags
array specifies the allowed compression
rates for the image’s i
th plane.
Note
If |
// 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, |
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 |
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
isNULL
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 eitherVK_IMAGE_COMPRESSION_DEFAULT_EXT
to indicate no fixed-rate compression,VK_IMAGE_COMPRESSION_FIXED_RATE_EXPLICIT_EXT
to indicate fixed-rate compression, orVK_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.
Bits which can be set in
-
VkImageViewUsageCreateInfo::
usage
-
VkImageStencilUsageCreateInfo::
stencilUsage
-
VkImageCreateInfo::
usage
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 aVkImageView
suitable for occupying aVkDescriptorSet
slot either of typeVK_DESCRIPTOR_TYPE_SAMPLED_IMAGE
orVK_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 aVkImageView
suitable for occupying aVkDescriptorSet
slot of typeVK_DESCRIPTOR_TYPE_STORAGE_IMAGE
. -
VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT
specifies that the image can be used to create aVkImageView
suitable for use as a color or resolve attachment in aVkFramebuffer
. -
VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT
specifies that the image can be used to create aVkImageView
suitable for use as a depth/stencil or depth/stencil resolve attachment in aVkFramebuffer
. -
VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT
specifies that implementations may support using memory allocations with theVK_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 aVkImageView
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 aVkImageView
suitable for occupyingVkDescriptorSet
slot of typeVK_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 aVkImageView
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 aVkImageView
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 theVK_IMAGE_LAYOUT_ATTACHMENT_FEEDBACK_LOOP_OPTIMAL_EXT
layout to be used as a color or depth/stencil attachment in aVkFramebuffer
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 theVK_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 theVK_IMAGE_CREATE_SPARSE_BINDING_BIT
flag. -
VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT
specifies that the image can be used to create aVkImageView
with a different format from the image. For multi-planar formats,VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT
specifies that aVkImageView
can be created of a plane of the image. -
VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT
specifies that the image can be used to create aVkImageView
of typeVK_IMAGE_VIEW_TYPE_CUBE
orVK_IMAGE_VIEW_TYPE_CUBE_ARRAY
. -
VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT
specifies that the image can be used to create aVkImageView
of typeVK_IMAGE_VIEW_TYPE_2D
orVK_IMAGE_VIEW_TYPE_2D_ARRAY
. -
VK_IMAGE_CREATE_2D_VIEW_COMPATIBLE_BIT_EXT
specifies that the image can be used to create aVkImageView
of typeVK_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 thesplitInstanceBindRegionCount
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 aVkImageView
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 aVkImageView
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 thepNext
chain includes a VkExternalMemoryImageCreateInfo or VkExternalMemoryImageCreateInfoNV structure whosehandleTypes
member is not0
, it is as ifVK_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
containingVK_SAMPLER_CREATE_SUBSAMPLED_BIT_EXT
or was not sampled through the use of a combined image sampler with an immutable sampler inVkDescriptorSetLayoutBinding
. -
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
ifVkPhysicalDeviceFragmentDensityMap2PropertiesEXT
::subsampledCoarseReconstructionEarlyAccess
isVK_TRUE
and the sampler was created withflags
containingVK_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
isVK_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 withVK_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;
-
VK_IMAGE_TILING_OPTIMAL
specifies optimal tiling (texels are laid out in an implementation-dependent arrangement, for more efficient memory access). -
VK_IMAGE_TILING_LINEAR
specifies linear tiling (texels are laid out in memory in row-major order, possibly with some padding on each row). -
VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT
indicates that the image’s tiling is defined by a Linux DRM format modifier. The modifier is specified at image creation with VkImageDrmFormatModifierListCreateInfoEXT or VkImageDrmFormatModifierExplicitCreateInfoEXT, and can be queried with vkGetImageDrmFormatModifierPropertiesEXT.
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.
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.
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 onrowPitch
. -
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:: |
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
isNULL
or a pointer to a structure extending this structure. -
imageSubresource
is a 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
isNULL
or a pointer to a structure extending this structure. -
subresourceLayout
is a VkSubresourceLayout structure.
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.
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;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
drmFormatModifier
returns the image’s Linux DRM format modifier.
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
.
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.
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.
-
If the image was created with
VK_IMAGE_TILING_LINEAR
, then its set of format features is the value of VkFormatProperties::linearTilingFeatures
found by calling vkGetPhysicalDeviceFormatProperties on the sameformat
as VkImageCreateInfo::format
. -
If the image was created with
VK_IMAGE_TILING_OPTIMAL
, but without an Android hardware buffer external format, or an VkBufferCollectionImageCreateInfoFUCHSIA, then its set of format features is the value of VkFormatProperties::optimalTilingFeatures
found by calling vkGetPhysicalDeviceFormatProperties on the sameformat
as VkImageCreateInfo::format
. -
If the image was created with an Android hardware buffer external format, then its set of format features is the value of VkAndroidHardwareBufferFormatPropertiesANDROID::
formatFeatures
found by calling vkGetAndroidHardwareBufferPropertiesANDROID on the Android hardware buffer that was imported to the VkDeviceMemory to which the image is bound. -
If the image was created with
VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT
, then:-
The image’s DRM format modifier is the value of VkImageDrmFormatModifierPropertiesEXT::
drmFormatModifier
found by calling vkGetImageDrmFormatModifierPropertiesEXT. -
Let VkDrmFormatModifierPropertiesListEXT::
pDrmFormatModifierProperties
be the array found by calling vkGetPhysicalDeviceFormatProperties2 on the sameformat
as VkImageCreateInfo::format
. -
Let
VkDrmFormatModifierPropertiesEXT prop
be the array element whosedrmFormatModifier
member is the value of the image’s DRM format modifier. -
Then the image’s set of format features is the value of
prop
::drmFormatModifierTilingFeatures
.
-
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:
-
Texels are centered on integer coordinates. See Unnormalized Texel Coordinate Operations
-
Normalized coordinates are scaled using coord × (dim - 1) rather than coord × dim, where dim is the size of one dimension of the image. See normalized texel coordinate transform.
-
Partial derivatives are scaled using coord × (dim - 1) rather than coord × dim. See Scale Factor Operation.
-
Calculation of the next higher LOD size goes according to ⌈dim / 2⌉ rather than ⌊dim / 2⌋. See Image Mip Level Sizing.
-
The minimum level size is 2x2 for 2D images and 2x2x2 for 3D images. See Image Mip Level Sizing.
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:
-
width
n+1 = max(⌊width
n/2⌋, 1) -
height
n+1 = max(⌊height
n/2⌋, 1) -
depth
n+1 = max(⌊depth
n/2⌋, 1)
where width
n, height
n, and depth
n
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(
width
0,height
0,depth
0))⌋ + 1
where width
0, height
0, and depth
0
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:
-
width
n+1 = max(⌈width
n/2⌉, 2) -
height
n+1 = max(⌈height
n/2⌉, 2) -
depth
n+1 = max(⌈depth
n/2⌉, 2)
where width
n, height
n, and depth
n
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(
width
0,height
0,depth
0))⌉
where width
0, height
0, and depth
0
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
|
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 theinitialLayout
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 theinitialLayout
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 forVK_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 aVkFramebuffer
. This layout is valid only for image subresources of images created with theVK_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 toVK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL
andVK_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 toVK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL
andVK_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 toVK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL
andVK_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 toVK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL
andVK_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 theVK_IMAGE_USAGE_SAMPLED_BIT
orVK_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 ofVK_PIPELINE_STAGE_TRANSFER_BIT
). This layout is valid only for image subresources of images created with theVK_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 theVK_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 theVK_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 aVkRenderPass
. This layout is valid only for image subresources of images created with theVK_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 theVK_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 theVK_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 theVK_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 theVK_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 aVkFramebuffer
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 theVK_IMAGE_USAGE_ATTACHMENT_FEEDBACK_LOOP_BIT_EXT
usage bit enabled and either theVK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT
orVK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT
and either theVK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT
orVK_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
andVK_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
andVK_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 aVkImageViewCreateInfo
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.
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
isNULL
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
aspectMask
includes onlyVK_IMAGE_ASPECT_STENCIL_BIT
, the implicitusage
is equal to VkImageStencilUsageCreateInfo::stencilUsage
. -
If
aspectMask
includes onlyVK_IMAGE_ASPECT_DEPTH_BIT
, the implicitusage
is equal to VkImageCreateInfo::usage
. -
If both aspects are included in
aspectMask
, the implicitusage
is equal to the intersection of VkImageCreateInfo::usage
and VkImageStencilUsageCreateInfo::stencilUsage
.
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.
Image View Type | Compatible Image Types |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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 duringVK_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
isNULL
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.
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
isNULL
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
.
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 frombaseMipLevel
) accessible to the view. -
baseArrayLayer
is the first array layer accessible to the view. -
layerCount
is the number of array layers (starting frombaseArrayLayer
) 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
.
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.
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:
Component | Identity Mapping |
---|---|
|
|
|
|
|
|
|
|
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
isNULL
or a pointer to a structure extending this structure. -
decodeMode
is the intermediate format used to decode ASTC compressed formats.
If format
uses sRGB encoding then the decodeMode
has no effect.
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
isNULL
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.
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.
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.
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
isNULL
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.
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.
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
isNULL
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.
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.
-
If Vulkan 1.3 is supported or the
VK_KHR_format_feature_flags2
extension is supported, and VkImageViewCreateInfo::image
was created withVK_IMAGE_TILING_LINEAR
, then the image view’s set of format features is the value of VkFormatProperties3::linearTilingFeatures
found by calling vkGetPhysicalDeviceFormatProperties2 on the sameformat
as VkImageViewCreateInfo::format
. -
If Vulkan 1.3 is not supported and the
VK_KHR_format_feature_flags2
extension is not supported, and VkImageViewCreateInfo::image
was created withVK_IMAGE_TILING_LINEAR
, then the image view’s set of format features is the union of the value of VkFormatProperties::linearTilingFeatures
found by calling vkGetPhysicalDeviceFormatProperties on the sameformat
as VkImageViewCreateInfo::format
, with:-
VK_FORMAT_FEATURE_2_SAMPLED_IMAGE_DEPTH_COMPARISON_BIT
if the format is a depth/stencil format and the image view features also containVK_FORMAT_FEATURE_2_SAMPLED_IMAGE_BIT
. -
VK_FORMAT_FEATURE_2_STORAGE_READ_WITHOUT_FORMAT_BIT
if the format is one of the extended storage formats andshaderStorageImageReadWithoutFormat
is enabled on the device. -
VK_FORMAT_FEATURE_2_STORAGE_WRITE_WITHOUT_FORMAT_BIT
if the format is one of the extended storage formats andshaderStorageImageWriteWithoutFormat
is enabled on the device.
-
-
If Vulkan 1.3 is supported or the
VK_KHR_format_feature_flags2
extension is supported, and VkImageViewCreateInfo::image
was created withVK_IMAGE_TILING_OPTIMAL
, but without an Android hardware buffer external format, then the image view’s set of format features is the value of VkFormatProperties::optimalTilingFeatures
or VkFormatProperties3::optimalTilingFeatures
found by calling vkGetPhysicalDeviceFormatProperties or vkGetPhysicalDeviceImageFormatProperties2 on the sameformat
as VkImageViewCreateInfo::format
. -
If Vulkan 1.3 is not supported and the
VK_KHR_format_feature_flags2
extension is not supported, and VkImageViewCreateInfo::image
was created withVK_IMAGE_TILING_OPTIMAL
, but without an Android hardware buffer external format, then the image view’s set of format features is the union of the value of VkFormatProperties::optimalTilingFeatures
found by calling vkGetPhysicalDeviceFormatProperties on the sameformat
as VkImageViewCreateInfo::format
, with:-
VK_FORMAT_FEATURE_2_SAMPLED_IMAGE_DEPTH_COMPARISON_BIT
if the format is a depth/stencil format and the image view features also containVK_FORMAT_FEATURE_2_SAMPLED_IMAGE_BIT
. -
VK_FORMAT_FEATURE_2_STORAGE_READ_WITHOUT_FORMAT_BIT
if the format is one of the extended storage formats andshaderStorageImageReadWithoutFormat
is enabled on the device. -
VK_FORMAT_FEATURE_2_STORAGE_WRITE_WITHOUT_FORMAT_BIT
if the format is one of the extended storage formats andshaderStorageImageWriteWithoutFormat
is enabled on the device.
-
-
If VkImageViewCreateInfo::
image
was created with an Android hardware buffer external format, then the image views’s set of format features is the value of VkAndroidHardwareBufferFormatPropertiesANDROID::formatFeatures
found by calling vkGetAndroidHardwareBufferPropertiesANDROID on the Android hardware buffer that was imported to the VkDeviceMemory to which the VkImageViewCreateInfo::image
is bound. -
If VkImageViewCreateInfo::
image
was created with a chained VkBufferCollectionImageCreateInfoFUCHSIA, then the image view’s set of format features is the value of VkBufferCollectionPropertiesFUCHSIA::formatFeatures
found by calling vkGetBufferCollectionPropertiesFUCHSIA on the buffer collection passed as VkBufferCollectionImageCreateInfoFUCHSIA::collection
when the image was created. -
If VkImageViewCreateInfo::
image
was created withVK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT
, then:-
The image’s DRM format modifier is the value of VkImageDrmFormatModifierPropertiesEXT::
drmFormatModifier
found by calling vkGetImageDrmFormatModifierPropertiesEXT. -
Let VkDrmFormatModifierPropertiesListEXT::
pDrmFormatModifierProperties
be the array found by calling vkGetPhysicalDeviceFormatProperties2 on the sameformat
as VkImageViewCreateInfo::format
. -
Let
VkDrmFormatModifierPropertiesEXT prop
be the array element whosedrmFormatModifier
member is the value of the image’s DRM format modifier. -
Then the image view’s set of format features is
prop
::drmFormatModifierTilingFeatures
.
-
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
isNULL
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⌋
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.
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;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
compactedSize
is the size from the result of vkCmdWriteAccelerationStructuresPropertiesNV if this acceleration structure is going to be the target of a compacting copy. -
info
is the VkAccelerationStructureInfoNV structure specifying further parameters of the created acceleration 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
isNULL
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 ofgeometryCount
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.