Vulkan^® 1.4.326 - A Specification (with all registered extensions)

The Vulkan Specification uses a combination of normative terminology and normative descriptions to express the requirements that it imposes on applications and implementations. An application which complies with all normative requirements imposed on applications is said to make valid use of the API; failing to comply with such requirements results in undefined behavior, as discussed in the Valid Usage section below. In the context of this document, an implementation which complies with all normative requirements imposed on implementations is said to be conformant.

References to external documents are considered normative references if the Specification uses normative terminology or normative descriptions to refer to them or their requirements, either as a whole or in part.

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

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

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

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

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

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

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

Google. VP9 Bitstream & Decoding Process Specification (February 22, 2017). https://storage.googleapis.com/downloads.webmproject.org/docs/vp9/vp9-bitstream-specification-v0.7-20170222-draft.pdf .

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

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

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

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

Some language in the specification is purely informative, intended to provide background information or make suggestions to implementors or developers. Such language does not impose normative requirements on implementations or applications.

All NOTEs are implicitly informative.

If an entire chapter, section, or appendix contains only informative language, its title will be suffixed with “(Informative)”. Unless so noted in the title, all chapters, sections, and appendices in this document are normative.

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

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

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

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.

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:

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 content of certain object types is still free to change. When an object is passed to another command, it may be accessed by the implementation, which may include both read and write access unless explicitly stated otherwise. 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.

Applications are responsible for managing the lifetimes of Vulkan objects and memory passed into the Vulkan API. The access semantics of different functions in the API follow a typical pattern as laid out below, with any exceptions listed with the commands or objects that have them.

Application-owned memory and Vulkan objects may be accessed at any time during the execution of a command they are passed to. Vulkan objects that device addresses are retrieved from may be accessed by the implementation any time that memory backing the device address is accessed. Device addresses and Vulkan objects passed in during the creation or allocation of another object may be accessed by the implementation any time that the created/allocated object is accessed unless explicitly stated otherwise. Device addresses and Vulkan objects passed to a recording command (vkCmd*) may be accessed at any time during the execution of the command, when the command buffer is subsequently recorded into another command buffer, during any subsequent command that is recorded to either the command buffer or one it is recorded into, or while the command buffer is in the pending state, unless explicitly stated otherwise. If an application is using deferred host operations in a command, and that operation is successfully deferred, objects and memory passed to that command may be accessed at any time until the deferred operation is complete. Some additional operations hold references to other objects or application-owned memory beyond the duration of the command; in which case the access semantics and lifetime of those references are described by that command.

When destroying or freeing an object, implementations must not access any memory or other objects that may otherwise be accessed when the object is accessed. Applications can free or destroy objects in any order, except that parent objects must be freed only after all child objects are freed. An object is the parent of another child object if the parent was used as the first object parameter in the creation of the child. Once an object is freed or destroyed it must not be accessed again, either directly or via access through another object. Applications must not free or destroy any object while it is being accessed.

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.

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.

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

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

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

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

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

Some query commands of the form vkGet* retrieve opaque binary data in the form of a byte array and have a possible result code of VK_ERROR_NOT_ENOUGH_SPACE_KHR. Such commands always have two pointer arguments as follows:

If such commands are called with the binary pointer not set to NULL, the binary size pointer must point to a variable set by the application to the allocated size of the binary pointer. These arguments may also be placed in an extensible structure, in which case the binary data size argument is not a pointer.

If the input binary size is less than the total retrievable binary size, the query will not write any data to the location pointed to the binary pointer, and the command will return VK_ERROR_NOT_ENOUGH_SPACE_KHR instead of VK_SUCCESS.

If the return code is VK_SUCCESS or VK_ERROR_NOT_ENOUGH_SPACE_KHR, the total size of the binary data that can be retrieved is returned in the variable pointed to by the binary size pointer.

If multiple binaries are being retrieved, VK_ERROR_NOT_ENOUGH_SPACE_KHR will be returned if any input binary sizes are less than their respective total retrievable binary sizes. Unless otherwise specified, this command will determine writing data to each binary individually based on if their input binary sizes are sufficiently sized, following the behavior for single binary retrieval.

For all other error codes, the contents of the return structures are undefined.